wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault backup: 2026-06-09 23:15:17

Browse Source
This commit is contained in:
wonder
2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude-code-best/docs/features/remote-control-self-hosting.md
+86 -104
View File
@@ -1,28 +1,30 @@
---
tags: [remote-control, rcs, docker, self-hosting, websocket, claude-code]
create time: 2026-06-09 22:30
---
# Remote Control Server 私有化部署指南
本指南说明如何将 Remote Control Server (RCS) 部署到私有环境，并通过 Claude Code CLI 连接使用。
## 概述
## 架构概览
本指南说明如何将 Remote Control Server (RCS) 部署到私有环境，并通过 Claude Code CLI 连接使用。RCS 是一个纯内存的中间服务，负责桥接 CLI、Web UI 和 ACP agent 之间的通信。
```
┌──────────────────┐ ┌──────────────────────┐
│ Claude Code CLI │ ◄── HTTP/SSE/WS ─►│ Remote Control │
│ (Bridge Worker) │ 长轮询 + 心跳 │ Server (RCS) │
└──────────────────┘ │ │
│ ┌──────────────┐ │
┌──────────────────┐ HTTP/SSE │ │ In-Memory │ │
│ Web UI 控制面板 │ ◄─────────────── │ │ Store │ │
│ (/code/*) │ │ └──────────────┘ │
│ (React + Vite) │ │ ┌──────────────┐ │
└──────────────────┘ │ │ JWT Auth │ │
│ └──────────────┘ │
┌──────────────────┐ │ ┌──────────────┐ │
│ acp-link │ ◄── ACP Relay ─── │ │ ACP Handler │ │
│ + ACP Agent │ WebSocket │ └──────────────┘ │
└──────────────────┘ └──────────────────────┘
## 正文
### 架构概览
```mermaid
graph TB
A["Claude Code CLI Bridge Worker"] <-->|"HTTP/SSE/WS 长轮询+心跳"| B["Remote Control Server RCS"]
C["Web UI 控制面板 /code/* React+Vite"] -->|"HTTP/SSE"| B
D["acp-link + ACP Agent"] <-->|"ACP Relay WebSocket"| B
B --> E["In-Memory Store"]
B --> F["JWT Auth"]
B --> G["ACP Handler"]
```
**RCS 是一个纯内存的中间服务**，它的职责是：
**RCS 的职责**：
- 接收 Claude Code CLI 的环境注册和工作轮询
- 接收 acp-link 的 ACP agent 注册，支持 WebSocket relay 桥接
- 提供 Web UI 供操作者远程监控和审批
@@ -30,15 +32,15 @@
- 管理会话、环境、权限请求
- 提供 ACP SSE event stream 供外部消费者订阅 channel group 事件
## 前置条件
### 前置条件
- 一台可被 Claude Code CLI 和 Web 浏览器同时访问的服务器（物理机、VM、容器均可）
- [Docker](https://www.docker.com/)
- 启用 `BRIDGE_MODE` feature flag 的 Claude Code 构建
## 部署
### 部署
### 构建 Docker 镜像
#### 构建 Docker 镜像
在项目根目录执行：
@@ -46,7 +48,7 @@
docker build -t rcs:latest -f packages/remote-control-server/Dockerfile .
```
### 启动容器
#### 启动容器
```bash
docker run -d \
@@ -59,7 +61,7 @@ docker run -d \
rcs:latest
```
### Docker Compose
#### Docker Compose
```yaml
version: "3.8"
@@ -89,9 +91,9 @@ volumes:
docker compose up -d
```
## 环境变量参考
### 环境变量参考
### 服务器端
#### 服务器端
| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
@@ -107,7 +109,7 @@ docker compose up -d
| `RCS_WS_IDLE_TIMEOUT` | 否 | `30` | WebSocket 空闲超时（秒），Bun 发送协议级 ping |
| `RCS_WS_KEEPALIVE_INTERVAL` | 否 | `20` | 服务端→客户端 keep_alive 帧间隔（秒），防止反向代理关闭空闲连接 |
### 客户端（Claude Code CLI）
#### 客户端（Claude Code CLI）
| 变量 | 必填 | 说明 |
|------|------|------|
@@ -116,9 +118,9 @@ docker compose up -d
| `CLAUDE_BRIDGE_SESSION_INGRESS_URL` | 否 | WebSocket 入口地址（默认与 `CLAUDE_BRIDGE_BASE_URL` 相同） |
| `CLAUDE_CODE_REMOTE` | 否 | 设为 `1` 时标记为远程执行模式 |
## Claude Code 客户端连接
### Claude Code 客户端连接
### 1. 设置环境变量
#### 1. 设置环境变量
在运行 Claude Code 的机器上设置：
@@ -127,7 +129,7 @@ export CLAUDE_BRIDGE_BASE_URL="https://rcs.example.com"
export CLAUDE_BRIDGE_OAUTH_TOKEN="sk-rcs-your-secret-key-here"
```
### 2. 启动 Claude Code
#### 2. 启动 Claude Code
```bash
# 使用 dev 模式（BRIDGE_MODE 默认启用）
@@ -137,7 +139,7 @@ bun run dev
bun run dist/cli.js
```
### 3. 执行 /remote-control 命令
#### 3. 执行 /remote-control 命令
在 Claude Code 的 REPL 中输入：
@@ -160,6 +162,7 @@ https://rcs.example.com/code/session_<id>
两种 URL 都可以直接在浏览器打开并远程操控当前会话；只有 environment 模式才会出现在 Web UI 的环境列表中。
若已连接，再次执行 `/remote-control` 会显示对话框，包含以下选项：
- **Disconnect this session** — 断开远程连接
- **Show QR code** — 显示/隐藏二维码
- **Continue** — 保持连接，继续使用
@@ -174,11 +177,11 @@ claude rc
claude bridge
```
## Web UI 控制面板
### Web UI 控制面板
通过 `/remote-control` 命令获取 URL 后，在浏览器打开即可使用。
### 技术栈（v2，2026-04-18 重构）
#### 技术栈（v2，2026-04-18 重构）
Web UI 已从原生 JS 重构为 **React + Vite + Radix UI**：
@@ -189,7 +192,7 @@ Web UI 已从原生 JS 重构为 **React + Vite + Radix UI**：
- **ACP 直连**: 支持 QR 码扫描自动跳转 ACP 直连视图（`ACPDirectView`）
- **主题系统**: 暗色/亮色主题切换，遵循 Impeccable 设计系统
### 功能
#### 功能
- 查看已注册的运行环境（environment 模式），区分 ACP Agent 和 Claude Code 类型
- 创建和管理会话
@@ -204,19 +207,11 @@ Web UI 已从原生 JS 重构为 **React + Vite + Radix UI**：
Web UI 使用 UUID 认证（无需用户账户），适合受信任网络环境。
## ACP 支持
### ACP 支持
RCS 支持 ACP (Agent Client Protocol) agent 通过 `acp-link` 包接入。
### 架构
```
acp-link ──REST注册──► RCS POST /v1/environments/bridge
acp-link ──WS identify──► RCS WebSocket (携带 agentId)
acp-link ◄──ACP relay──► RCS ◄──Web UI WS──► 浏览器
```
### 后端组件
#### 后端组件
| 文件 | 职责 |
|------|------|
@@ -225,14 +220,12 @@ acp-link ◄──ACP relay──► RCS ◄──Web UI WS──► 浏览器
| `src/transport/acp-relay-handler.ts` | 前端 WS → acp-link 透传 + EventBus inbound 转发 |
| `src/transport/acp-sse-writer.ts` | SSE event stream 供外部消费者订阅 |
ACP 的 agents、channel groups、relay 和 channel-group SSE 端点都要求有效
API key。浏览器 `EventSource` 不能发送 `Authorization` header，外部订阅
`/acp/channel-groups/:id/events` 时需要使用 `fetch` + `ReadableStream` 并带
`Authorization: Bearer <api-key>`。
> [!warning]
> ACP 的 agents、channel groups、relay 和 channel-group SSE 端点都要求有效 API key。浏览器 `EventSource` 不能发送 `Authorization` header，外部订阅 `/acp/channel-groups/:id/events` 时需要使用 `fetch` + `ReadableStream` 并带 `Authorization: Bearer <api-key>`。
### acp-link 连接
#### acp-link 连接
详见 [acp-link 文档](./acp-link.md)。
详见 [[acp-link]] 文档。
```bash
# 在 RCS 环境中启动 acp-link
@@ -244,96 +237,77 @@ acp-link ccb-bun -- --acp
ACP session 在 Web UI 中显示品牌色标签，与普通 Claude Code session 区分。
## 工作流程详解
### 工作流程详解
```
┌──────────────────────────────────────────────────────────┐
│ 完整工作流程 │
└──────────────────────────────────────────────────────────┘
1. Claude Code CLI 启动，设置环境变量指向自托管 RCS
2. 用户执行 /remote-control 命令
3. 注册环境
CLI ──POST /v1/environments/bridge──► RCS
CLI ◄── { environment_id, environment_secret } ── RCS
4. 终端显示连接 URL
https://rcs.example.com/code?bridge=<environmentId>
5. 开始工作轮询（循环）
CLI ──GET /v1/environments/:id/work/poll──► RCS
（长轮询，等待任务分配，超时 8 秒后重试）
6. 浏览器打开 URL → Web UI 创建任务
Browser ──POST /web/sessions──► RCS
RCS 分配 work 给正在轮询的 CLI
7. CLI 收到任务并确认
CLI ◄── { id, data: { type, sessionId } } ── RCS
CLI ──POST /v1/environments/:id/work/:workId/ack──► RCS
8. 建立会话连接
CLI ──WebSocket /v1/session_ingress──► RCS
（或使用 V2 的 SSE + HTTP POST）
9. 双向通信
CLI ──消息/工具调用结果──► RCS ──► Browser
CLI ◄──权限审批/指令───── RCS ◄──── Browser
CLI ──automation_state / task_state──► RCS ──► Browser
10. 心跳保活（每 20 秒）
CLI ──POST /v1/environments/:id/work/:workId/heartbeat──► RCS
11. 任务完成 → 归档会话 → 注销环境
```mermaid
sequenceDiagram
participant CLI as Claude Code CLI
participant RCS as RCS
participant Browser as 浏览器
CLI->>RCS: POST /v1/environments/bridge 注册环境
RCS-->>CLI: environment_id + environment_secret
Note over CLI: 终端显示连接 URL
loop 工作轮询
CLI->>RCS: GET /v1/environments/:id/work/poll (长轮询8秒)
RCS-->>CLI: WorkResponse { id, data: { type, sessionId } }
end
Browser->>RCS: POST /web/sessions 创建任务
RCS-->>CLI: 分配 work 给正在轮询的 CLI
CLI->>RCS: POST .../work/:workId/ack 确认
CLI->>RCS: WebSocket /v1/session_ingress 建立会话
Note over CLI,RCS: 双向通信: 消息/工具调用/权限审批/心跳
loop 每20秒
CLI->>RCS: POST .../work/:workId/heartbeat 心跳保活
end
```
## 故障排查
### 故障排查
### Web UI 看不到当前 Autopilot 状态
#### Web UI 看不到当前 Autopilot 状态
- `standby`：proactive 已开启，正在等待下一个 tick
- `sleeping`：模型正在 `SleepTool` 等待窗口中
这两个状态通过 worker `external_metadata.automation_state` 上报。如果页面只显示普通 working spinner，优先检查 CLI 和 RCS 之间的 worker metadata PUT 是否成功。
### CLI 无法连接
#### CLI 无法连接
```
Error: Remote Control is not available in this build.
```
**原因**：`BRIDGE_MODE` feature flag 未启用。
> [!warning]
> **原因**：`BRIDGE_MODE` feature flag 未启用。
> **解决**：使用 dev 模式（默认启用）或确保构建时包含 `BRIDGE_MODE` flag。
**解决**：使用 dev 模式（默认启用）或确保构建时包含 `BRIDGE_MODE` flag。
### 认证失败 (401)
#### 认证失败 (401)
```
Error: Unauthorized
```
**检查项**：
1. `CLAUDE_BRIDGE_OAUTH_TOKEN` 是否与 `RCS_API_KEYS` 中的值匹配
2. API Key 是否包含多余的空格或换行
3. 两个环境变量是否都已正确设置
### WebSocket 连接中断
#### WebSocket 连接中断
**检查项**：
1. 如果使用反向代理，确认已正确配置 WebSocket 升级（`Upgrade` / `Connection` 头）
2. 代理的 `proxy_read_timeout` 是否足够大（建议 86400 秒）
3. 网络防火墙是否允许 WebSocket 流量
### 健康检查
#### 健康检查
```bash
curl https://rcs.example.com/health
# 预期: {"status":"ok","version":"0.1.0"}
```
## 限制与注意事项
### 限制与注意事项
| 项目 | 说明 |
|------|------|
@@ -343,7 +317,7 @@ curl https://rcs.example.com/health
| 数据持久化 | `/app/data` 卷已预留但当前未使用，未来可能用于持久化 |
| Web UI 认证 | 基于 UUID，无用户账户系统，适合受信任网络环境 |
## 与云端模式对比
### 与云端模式对比
| 特性 | 云端 (Anthropic CCR) | 自托管 (RCS) |
|------|---------------------|--------------|
@@ -354,4 +328,12 @@ curl https://rcs.example.com/health
| 数据流经 | Anthropic 基础设施 | 用户私有网络 |
| 依赖 | claude.ai 订阅 + OAuth | 仅需 API Key |
自托管模式的核心优势是：设置 `CLAUDE_BRIDGE_BASE_URL` 后，代码自动调用 `isSelfHostedBridge()` 返回 `true`，跳过所有 GrowthBook 和订阅检查，无需 claude.ai 账户即可使用。
> [!tip]
> 自托管模式的核心优势是：设置 `CLAUDE_BRIDGE_BASE_URL` 后，代码自动调用 `isSelfHostedBridge()` 返回 `true`，跳过所有 GrowthBook 和订阅检查，无需 claude.ai 账户即可使用。
## 关联笔记
- [[bridge-mode]]
- [[acp-link]]
- [[acp-zed]]
- [[daemon]]