clawpanel/docs/docker-multi-instance-plan.md

# ClawPanel Docker 多实例管理 — 技术规划

> 版本: v1.0 | 日期: 2026-03-08

## 1. 问题分析

### 1.1 现状

ClawPanel 当前架构是 **单实例管理**：

```
浏览器 → ClawPanel 前端
              │
              ├── /__api/* → dev-api.js → 读写本机 ~/.openclaw/ 文件
              ├── /ws     → 代理到本机 Gateway:18789 (WebSocket)
              └── 静态文件  → dist/
```

**所有页面**（模型配置、Agent 管理、Gateway 设置、日志、聊天等）操作的都是：
- 本机文件系统上的 `~/.openclaw/openclaw.json`
- 本机运行的 Gateway 进程（端口 18789）

### 1.2 Phase 1 已完成

Docker 集群页面实现了 **容器生命周期管理**（通过 Docker Socket API）：
- 启动/停止/重启/删除容器
- 部署新容器（端口映射、数据卷、环境变量）
- 查看容器日志
- 多节点管理（本机 + 远程 Docker 主机）

### 1.3 缺口

Docker 页面能管容器的"壳"，但 **无法管理容器里的 OpenClaw**：
- 无法配置某个容器内的模型
- 无法查看某个容器内的 Gateway 日志
- 无法管理某个容器内的 Agent
- 聊天功能只连本机 Gateway

---

## 2. 目标架构

### 2.1 核心思路：API 代理 + 实例切换

```
┌──────────────────────────────────────────────────┐
│                  ClawPanel 前端                   │
│  ┌────────────────────────────────────────────┐  │
│  │  实例切换器: [ ● 本机 ▼ ]                    │  │
│  │              [ ○ prod-server (Docker) ]     │  │
│  │              [ ○ dev-box (远程) ]           │  │
│  │              [ + 添加实例 ]                  │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
│  现有页面（模型/Agent/Gateway/日志/聊天...）        │
│       │                                          │
│       │ api.readOpenclawConfig()                  │
│       │ api.listAgents()                         │
│       ▼                                          │
│  tauri-api.js → webInvoke('read_openclaw_config') │
│                    │                              │
│              自动附带 instanceId                   │
└──────────────────┼───────────────────────────────┘
                   ▼
         dev-api.js (本机后端)
                   │
          ┌────────┼────────┐
          ▼        ▼        ▼
       本机文件  代理转发   代理转发
     ~/.openclaw  ↓         ↓
              实例 A     实例 B
          http://host   http://192.168.1.100
            :18790        :1420
           /__api/*     /__api/*
```

**关键点：每个 Docker 容器运行 full 镜像，内含完整的 ClawPanel (serve.js) + Gateway。**
因此每个容器已经有自己的 `/__api/*` 端点，我们只需要代理请求过去。

### 2.2 WebSocket 连接

```
切换实例时：
  wsClient.disconnect()  ← 断开旧连接
  wsClient.connect(newHost, newToken)  ← 连接新实例的 Gateway
```

WebSocket 连接信息从目标实例的配置中读取（通过代理 API 获取 `read_openclaw_config`）。

### 2.3 自动组网流程

部署新容器时自动完成：

```
用户点击「部署容器」
    │
    ├─ 1. Docker API 创建容器（端口映射 hostPort→1420, hostPort→18789）
    ├─ 2. 启动容器，等待健康检查通过
    ├─ 3. 探测容器 Panel 端点：GET http://hostIP:hostPort/__api/check_installation
    ├─ 4. 自动写入实例注册表 ~/.openclaw/instances.json
    └─ 5. 前端自动刷新实例列表
```

---

## 3. 数据结构

### 3.1 实例注册表

文件位置：`~/.openclaw/instances.json`

```json
{
  "activeId": "local",
  "instances": [
    {
      "id": "local",
      "name": "本机",
      "type": "local",
      "endpoint": null,
      "gatewayPort": 18789,
      "addedAt": 1741420800,
      "note": ""
    },
    {
      "id": "docker-abc123",
      "name": "openclaw-prod",
      "type": "docker",
      "endpoint": "http://127.0.0.1:18790",
      "gatewayPort": 18789,
      "containerId": "abc123def456",
      "nodeId": "local",
      "addedAt": 1741420900,
      "note": "生产环境"
    },
    {
      "id": "remote-1",
      "name": "办公室服务器",
      "type": "remote",
      "endpoint": "http://192.168.1.100:1420",
      "gatewayPort": 18789,
      "addedAt": 1741421000,
      "note": ""
    }
  ]
}
```

**三种实例类型：**

| type | 说明 | 来源 |
|------|------|------|
| `local` | 本机 OpenClaw | 始终存在，不可删除 |
| `docker` | Docker 容器内的 OpenClaw | 部署容器时自动注册 |
| `remote` | 远程服务器上的 OpenClaw | 用户手动添加 |

### 3.2 实例状态（运行时，不持久化）

```js
{
  id: 'docker-abc123',
  online: true,           // 健康检查结果
  version: '2026.3.5',    // OpenClaw 版本
  gatewayRunning: true,   // Gateway 状态
  lastCheck: 1741420999,  // 上次检查时间
}
```

---

## 4. 改动清单

### 4.1 后端 dev-api.js

#### 4.1.1 实例注册表管理（新增）

```
新增 handlers:
  instance_list          → 读取 instances.json
  instance_add           → 添加实例（手动或自动）
  instance_remove        → 删除实例
  instance_set_active    → 切换活跃实例
  instance_health_check  → 健康检查单个实例
  instance_health_all    → 批量健康检查
```

#### 4.1.2 API 代理转发（核心改动）

改造 `_apiMiddleware`：

```js
// 伪代码
async function _apiMiddleware(req, res, next) {
  if (!req.url?.startsWith('/__api/')) return next()

  const cmd = extractCmd(req.url)
  const body = await readBody(req)

  // 实例管理命令 → 始终本机处理
  if (cmd.startsWith('instance_') || cmd.startsWith('docker_') || ALWAYS_LOCAL.has(cmd)) {
    return handleLocally(cmd, body, res)
  }

  // 获取当前活跃实例
  const active = getActiveInstance()

  if (active.type === 'local') {
    // 本机 → 直接处理（现有逻辑不变）
    return handleLocally(cmd, body, res)
  }

  // 远程/Docker 实例 → 代理转发
  return proxyToInstance(active, cmd, body, res)
}
```

**始终在本机处理的命令（ALWAYS_LOCAL）：**
- `instance_*` — 实例管理本身
- `docker_*` — Docker 容器管理
- `auth_*` — 认证
- `read_panel_config` / `write_panel_config` — 本地面板配置
- `assistant_*` — AI 助手（操作本机文件系统）

**通过代理转发的命令：**
- `read_openclaw_config` / `write_openclaw_config` — 目标实例的配置
- `get_services_status` / `start_service` / `stop_service` — 目标实例的服务
- `list_agents` / `add_agent` / `delete_agent` — 目标实例的 Agent
- `read_log_tail` / `search_log` — 目标实例的日志
- `get_version_info` / `upgrade_openclaw` — 目标实例的版本
- `list_memory_files` / `read_memory_file` — 目标实例的记忆文件
- `read_mcp_config` / `write_mcp_config` — 目标实例的 MCP 配置
- 等其他 OpenClaw 相关命令

#### 4.1.3 代理转发实现

```js
async function proxyToInstance(instance, cmd, body, res) {
  const url = `${instance.endpoint}/__api/${cmd}`
  try {
    const resp = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    })
    const data = await resp.text()
    res.writeHead(resp.status, { 'Content-Type': 'application/json' })
    res.end(data)
  } catch (e) {
    res.writeHead(502, { 'Content-Type': 'application/json' })
    res.end(JSON.stringify({ error: `实例 ${instance.name} 不可达: ${e.message}` }))
  }
}
```

#### 4.1.4 Docker 部署自动注册

修改 `docker_create_container` handler：
- 容器创建并启动后，自动等待健康检查
- 通过 `GET http://hostIP:panelPort/__api/check_installation` 验证
- 健康检查通过后自动写入 `instances.json`
- 返回结果包含 `instanceId`

### 4.2 前端 tauri-api.js

#### 4.2.1 新增实例管理 API

```js
// 实例管理
instanceList:        () => cachedInvoke('instance_list', {}, 10000),
instanceAdd:         (instance) => { invalidate('instance_list'); return invoke('instance_add', instance) },
instanceRemove:      (id) => { invalidate('instance_list'); return invoke('instance_remove', { id }) },
instanceSetActive:   (id) => { invalidate('instance_list'); _cache.clear(); return invoke('instance_set_active', { id }) },
instanceHealthCheck: (id) => invoke('instance_health_check', { id }),
instanceHealthAll:   () => invoke('instance_health_all'),
```

**注意 `instanceSetActive` 清空全部缓存**，因为切换实例后所有缓存数据都过期了。

#### 4.2.2 无需改动的部分

现有的 `api.readOpenclawConfig()`、`api.listAgents()` 等方法 **完全不变**。
代理逻辑在后端 `_apiMiddleware` 层透明处理。

### 4.3 前端 app-state.js

新增：

```js
let _activeInstance = { id: 'local', name: '本机', type: 'local' }
let _instanceListeners = []

export function getActiveInstance() { return _activeInstance }
export function onInstanceChange(fn) { ... }

export async function switchInstance(id) {
  // 1. 调后端切换
  await api.instanceSetActive(id)
  // 2. 更新本地状态
  _activeInstance = instances.find(i => i.id === id)
  // 3. 清缓存
  invalidate()        // 清 API 缓存
  // 4. 断开旧 WebSocket
  wsClient.disconnect()
  // 5. 重新检测状态
  await detectOpenclawStatus()
  // 6. 连接新实例的 Gateway WebSocket
  connectToActiveGateway()
  // 7. 通知所有监听者（侧边栏、页面刷新）
  _instanceListeners.forEach(fn => fn(_activeInstance))
}
```

### 4.4 前端 sidebar.js

在侧边栏顶部 logo 下方添加实例切换器：

```html
<div class="instance-switcher">
  <button class="instance-current" onclick="toggleDropdown()">
    <span class="instance-dot online"></span>
    <span class="instance-name">本机</span>
    <svg class="chevron">▼</svg>
  </button>
  <div class="instance-dropdown">
    <div class="instance-option active" data-id="local">
      <span class="instance-dot online"></span> 本机
    </div>
    <div class="instance-option" data-id="docker-abc123">
      <span class="instance-dot online"></span> openclaw-prod
      <span class="instance-badge">Docker</span>
    </div>
    <hr/>
    <div class="instance-option" onclick="addInstance()">
      <span>+ 添加实例</span>
    </div>
  </div>
</div>
```

### 4.5 前端 main.js

`autoConnectWebSocket()` 改为读取当前活跃实例的 Gateway 端点：

```js
async function autoConnectWebSocket() {
  const instance = getActiveInstance()
  if (instance.type === 'local') {
    // 本机：读本地配置
    const config = await api.readOpenclawConfig()
    const port = config?.gateway?.port || 18789
    wsClient.connect(`127.0.0.1:${port}`, token)
  } else {
    // 远程/Docker：从实例 endpoint 推导 Gateway 地址
    const config = await api.readOpenclawConfig() // 已通过代理转发
    const gwPort = config?.gateway?.port || 18789
    const url = new URL(instance.endpoint)
    wsClient.connect(`${url.hostname}:${instance.gatewayPort || gwPort}`, token)
  }
}
```

### 4.6 serve.js WebSocket 代理

WebSocket 代理改为动态目标：

```js
server.on('upgrade', (req, socket, head) => {
  // 从 query 或 header 中获取目标实例
  const target = resolveWsTarget(req)
  const conn = net.createConnection(target.port, target.host, () => { ... })
})
```

### 4.7 docker.js 集群页面

部署对话框增加"自动注册"逻辑：
- 容器创建成功后显示"正在等待实例就绪..."
- 健康检查通过后自动出现在实例切换器中
- 用户可直接切换到新实例进行管理

### 4.8 现有页面适配

| 页面 | 改动 | 说明 |
|------|------|------|
| dashboard.js | 极小 | 页头显示当前实例名称 |
| models.js | 无 | API 透明代理 |
| agents.js | 无 | API 透明代理 |
| gateway.js | 极小 | 远程实例时隐藏部分本机功能 |
| logs.js | 无 | API 透明代理 |
| chat.js | 无 | WebSocket 已切换到目标实例 |
| chat-debug.js | 无 | API 透明代理 |
| memory.js | 无 | API 透明代理 |
| services.js | 小 | 已有 Docker 适配，远程实例时隐藏 npm/CLI 相关 |
| extensions.js | 小 | 远程实例时 cftunnel/clawapp 不可用 |
| skills.js | 无 | API 透明代理 |
| security.js | 小 | 远程实例的密码管理走代理 |
| setup.js | 小 | 远程实例不需要 setup 流程 |
| assistant.js | 特殊 | AI 助手始终操作本机（ALWAYS_LOCAL） |

---

## 5. 实施步骤

### Step 1: 实例注册表后端（dev-api.js）
- `readInstances()` / `saveInstances()` 工具函数
- 6 个 handler：`instance_list` / `add` / `remove` / `set_active` / `health_check` / `health_all`
- 预计：~150 行

### Step 2: API 代理转发（dev-api.js）
- 改造 `_apiMiddleware` 添加代理逻辑
- `proxyToInstance()` 函数
- `ALWAYS_LOCAL` 命令集合
- 预计：~80 行

### Step 3: 前端实例管理 API（tauri-api.js）
- 新增 `api.instance*` 方法 + mock 数据
- 预计：~40 行

### Step 4: 前端状态管理（app-state.js）
- `_activeInstance` 状态 + `switchInstance()` 函数
- 预计：~50 行

### Step 5: 实例切换器 UI（sidebar.js）
- 下拉选择器组件 + CSS
- 预计：~100 行 JS + ~80 行 CSS

### Step 6: WebSocket 动态连接（main.js + serve.js）
- 切换实例时重新连接 WebSocket
- serve.js WebSocket 代理动态化
- 预计：~40 行

### Step 7: Docker 部署自动注册（docker.js + dev-api.js）
- `docker_create_container` 完成后自动注册
- 健康检查 + 就绪等待
- 预计：~60 行

### Step 8: 页面微调
- dashboard 显示实例名
- 远程实例时隐藏本机独占功能
- 预计：~30 行

**总计新增代码：约 600 行**

---

## 6. 安全考虑

### 6.1 认证
- 远程实例可能有不同的访问密码
- 代理转发时需要携带目标实例的认证凭据
- 首次连接时提示输入密码，存入 `instances.json`（加密存储待定）

### 6.2 网络安全
- Docker 容器默认只暴露在宿主机网络
- 远程实例建议通过 SSH 隧道或 VPN 连接
- 不建议在公网暴露 `/__api/` 端点而不加密码

### 6.3 权限隔离
- AI 助手（assistant_*）始终操作本机文件系统，不代理到远程
- Docker 管理（docker_*）始终操作本机 Docker，不代理

---

## 7. 边界与约束

### 7.1 不做的事情
- **不做** 统一聚合视图（如"查看所有实例的模型列表"）
- **不做** 跨实例数据同步（如"把本机模型配置复制到远程"）— 后续可做
- **不做** 实例间负载均衡
- **不做** 复杂的权限角色系统

### 7.2 前提条件
- 远程实例必须运行 ClawPanel（serve.js），版本 >= 0.7.0
- Docker 实例使用 full 镜像（含 Panel + Gateway）
- 网络可达（ClawPanel 后端能访问远程实例的端口）

### 7.3 兼容性
- 现有单实例用户 **零影响**：默认 activeId 为 "local"，行为完全不变
- 实例切换器在只有本机时可以隐藏或最小化显示
- 所有新功能向后兼容

---

## 8. 测试计划

| 场景 | 验证内容 |
|------|---------|
| 纯本机使用 | 现有功能不受影响，无回归 |
| 部署 Docker 容器 | 自动注册为可管理实例 |
| 切换到 Docker 实例 | 模型/Agent/日志等页面显示容器内数据 |
| 切换实例后聊天 | WebSocket 连接到正确的 Gateway |
| 远程实例离线 | 优雅报错，可切回本机 |
| 删除 Docker 容器 | 实例列表自动移除 |
| 多实例批量健康检查 | 侧边栏状态点实时更新 |