diff --git a/README.md b/README.md index c8ee0ee..00752b9 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,195 @@ +
+ # VPS-Commander -> 当前文档基线：2026-10-02 +**面向 AI Agent、MCP 与个人运维的高性能、轻量、多节点私有基础设施调度中枢** -自托管、多节点、AI Agent 友好的 Linux 运维控制中枢。 +[![Go Version](https://img.shields.io/badge/Go-1.22+-00ADD8?style=flat&logo=go)](https://golang.org) +[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Architecture](https://img.shields.io/badge/Arch-Linux%20AMD64%20%7C%20ARM64-orange)](#) -## 研发最初目标 -- 不依赖第三方运维 Relay，建立用户自己的私有控制面； -- 从单机运维扩展到多 VPS 统一调度； -- 在主机级能力之上建立认证、授权、审计、资源限制和可回滚发布体系。 +
-当前系统已经从早期的 OpenAPI + Cluster Secret + 4 个 MCP 工具，演进为： -Hub/Agent 双通道 + per-device credential + Policy Snapshot + Tool Registry + MCP/HTTP 统一安全门禁 + SQLite audit + Web Panel。 +--- -## 当前架构 -AI / MCP / Web Panel → HTTPS/WSS → Reverse Proxy → Hub 127.0.0.1:9521 -Hub → Local Executor，或 Hub → Agent WSS → Remote VPS。 -Hub 不直接公网监听；Agent 只主动回连 Hub。 +## 🌟 核心特性 -## 当前 MCP：11 个工具 -list_devices、exec_command、read_file、read_multiple_files、create_directory、move_file、list_processes、edit_block、write_file、list_agent_mcp、call_agent_mcp。 +- ⚡ **轻量单体部署**：纯 Go 原生编译，Hub、Agent、MCP stdio 均可独立部署。 +- 🤖 **原生 AI / MCP 接入**：提供 HTTP API、MCP SSE、stdio 以及 Agent WebSocket，多种客户端可以共用同一套安全模型。 +- 🌐 **Hub & Agent 双通道架构**：Hub 负责控制与授权，Agent 通过 WSS 主动回连，不要求远端开放入站管理端口。 +- 🛡️ **认证与授权分离**：HTTP/MCP 使用 Bearer API Key；Agent 使用每设备独立 Credential；Tool Registry + Security Snapshot 实现 Low / Medium / High 风险门禁。 +- 📋 **完整审计链**：SQLite 持久化设备、凭据哈希、策略版本、操作审计与 Webhook 配置。 +- 🧩 **多节点能力聚合**：文件、Shell、进程、Session、Agent MCP 等能力由 Hub 统一调度。 +- 🖥️ **内嵌 Web 管理面板**：Go embed 打包，无需 Node.js 运行时。 -风险：Low=读取/观察；Medium=文件修改/目录移动/Agent MCP；High=Shell/进程控制。 -远程 HTTP MCP 当前为 legacy HTTP+SSE；本地客户端为 stdio。Streamable HTTP 属于后续演进方向。 +--- -## 当前 HTTP -/api/v1/devices、/api/v1/exec、/api/v1/file/read、/api/v1/file/list、/api/v1/file/info、/api/v1/file/search、/api/v1/process/session、/api/v1/file/write、/api/v1/devices/file/edit_block、/api/v1/mcp/*、/api/v1/security/*、/api/v1/notifications/webhook*、/agent/ws、/healthz、/openapi.json、/panel/*。 +## 🏁 研发最初目标 -## 安全 -HTTP/MCP 使用 Bearer API Key；Agent 使用每设备独立 credential，Hub 只保存 hash。 -生产 Shared Secret fallback 已关闭；URL token 不作为认证方式。 -MCP、HTTP、direct Agent MCP 共用 Hub security model；未知设备必须 fail-closed。 -Panel Admin Token 由服务端内部 bridge，不下发浏览器。 +VPS-Commander 最初并不是一个简单的远程 Shell 工具，而是为 AI Agent 建立一个**用户自己控制的私有化 Linux 运维控制面**。 -## 部署 -Hub：/opt/vps-commander/vps-commander-hub，监听 127.0.0.1:9521，数据库 /opt/vps-commander/data/commander.db。 -Agent：/opt/vps-commander/vps-commander-agent，配置 /etc/vps-commander/agent.env，通过 WSS 回连 Hub。 +### 1.1 私有化 +- 运维请求通过用户自己的 Hub 和 VPS 节点完成。 +- 不依赖第三方运维 Relay。 +- 凭据、策略和审计数据由用户自己的基础设施控制。 -发布必须：clean tree → go test ./... → go test -race ./... → clean build → vcs.modified=false → 单节点灰度 → Hub recovery → rolling Agent → MCP/security/audit 验收。 +### 1.2 Host-centric 运维 +- 全局 Shell。 +- 全局文件读写。 +- 进程与长任务 Session。 +- 远程 Agent MCP。 -## 文档 -docs/DOCUMENTATION_BASELINE_20261002.md、docs/ARCHITECTURE.md、docs/DEV_SPEC.md、docs/MCP_INTEGRATION.md、deploy/README.md、docs/ACCEPTANCE_CRITERIA.md、docs/PROGRESS_TRACKING.md、docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md。 +### 1.3 多节点统一调度 +- 一个 Hub 管理多个 VPS。 +- 使用节点名称选择目标。 +- 节点离线后保留设备身份与持久化状态。 -## 当前生产注意 -2026-10-02 Bug Hunt 发现生产二进制曾以 vcs.modified=true 构建，因此生产现场不能直接视为 HEAD 的可复现产物。 -下一次发布必须 clean rebuild，并把 revision/modified 作为发布证据。 +### 1.4 AI 原生接口 +- HTTP API。 +- MCP。 +- OpenAPI 契约。 +- Web 管理面板。 -## v2.1 -P0：EffectiveRisk 完全 fail-closed；Agent credential 不进入 argv/cmdline。 -P1：Principal/Operator 身份、Session owner 强隔离、principal→credential→session→device→operation 审计链。 +--- + +## 🏗️ 当前总体架构 + +```text + +--------------------------------------+ + | AI / MCP Client / Web Panel | + +------------------+-------------------+ + | HTTPS / MCP / WSS + v + +--------------------------------------+ + | Reverse Proxy / TLS | + +------------------+-------------------+ + | 127.0.0.1:9521 + v + +-----------------------------------------------------------+ + | VPS-Commander Hub | + |-----------------------------------------------------------| + | Auth / API / MCP / Web Panel | + | Security Snapshot / Tool Registry / Audit | + | Cluster Router / Session / Rate Limiter | + +----------------------+-------------------+---------------+ + | | + Local Executor Agent WSS + | | + v v + Hub 本机 Remote VPS + | + Host Executor + File / Shell / Process +``` + +--- + +## 🔐 当前安全模型 + +### 1. Client Authentication +`Authorization: Bearer ` 是 HTTP / MCP 的主要客户端认证方式。 + +### 2. Agent Authentication +每个 Agent 使用独立的 `VPS_COMMANDER_AGENT_TOKEN`。 +Hub SQLite 只保存 Credential Hash，不保存明文 Token。 + +### 3. Authorization +Tool Registry 首先确定操作风险： + +| 风险 | 典型能力 | +| :--- | :--- | +| Low | 读取、搜索、设备/进程观察 | +| Medium | 文件修改、目录创建/移动、Agent MCP | +| High | Shell、进程启动、交互、终止 | + +未知设备、未知身份或策略无法解析时不得获得 High 权限。 + +### 4. Shared Secret +生产环境已经关闭 Cluster Secret / Shared Secret fallback。 + +--- + +## 🤖 当前 MCP 能力 + +目前共 **11 个 MCP Tools**： + +| Tool | Risk | 功能 | +| :--- | :--- | :--- | +| `list_devices` | Low | 节点列表与状态 | +| `exec_command` | High | Shell 执行 | +| `read_file` | Low | 分页读取文件 | +| `read_multiple_files` | Low | 批量读取文件 | +| `create_directory` | Medium | 创建目录 | +| `move_file` | Medium | 移动/重命名 | +| `list_processes` | Low | 进程观察 | +| `edit_block` | Medium | 原子文本修改 | +| `write_file` | Medium | 创建/覆写文件 | +| `list_agent_mcp` | Low | 查看 Agent MCP | +| `call_agent_mcp` | Medium | 调用 Agent MCP | + +远程 MCP 当前使用 **legacy HTTP + SSE**；本地客户端使用 stdio。 +Streamable HTTP 作为下一阶段 transport 演进方向。 + +--- + +## 📊 HTTP / Web 能力 + +| 接口 | 方法 | 功能 | +| :--- | :--- | :--- | +| `/api/v1/devices` | GET | 设备状态与资源画像 | +| `/api/v1/exec` | POST | 远程 Shell | +| `/api/v1/file/read` | POST | 文件读取 | +| `/api/v1/file/list` | POST | 目录列表 | +| `/api/v1/file/info` | POST | 文件信息 | +| `/api/v1/file/search` | POST | 文件搜索 | +| `/api/v1/file/write` | POST | 文件写入 | +| `/api/v1/devices/file/edit_block` | POST | 安全块编辑 | +| `/api/v1/process/session` | POST | Session 操作 | +| `/api/v1/mcp/*` | GET/POST/DELETE | MCP 服务管理与调用 | +| `/api/v1/security/*` | GET/POST | 安全策略 | +| `/api/v1/notifications/webhook*` | GET/POST/DELETE | Webhook | +| `/agent/ws` | WebSocket | Agent 长连接 | +| `/panel/*` | GET/POST | Web 管理面板 | + +--- + +## 🚀 生产部署 + +Hub： +```text +/opt/vps-commander/vps-commander-hub +/etc/vps-commander/hub.env +/opt/vps-commander/data/commander.db +127.0.0.1:9521 +``` + +Agent： +```text +/opt/vps-commander/vps-commander-agent +/etc/vps-commander/agent.env +wss://vpstool.kory.kdns.fr/agent/ws +``` + +Agent 只主动连接 Hub，不需要公网入站端口。 + +生产发布顺序： +`backup → clean build → 单节点灰度 → Hub restart recovery → rolling Agent → MCP/security/audit 验收`。 + +--- + +## 📄 文档索引 + +- [文档基线与全局索引](docs/DOCUMENTATION_BASELINE_20261002.md) +- [系统架构与开发设计规范](docs/ARCHITECTURE.md) +- [研发与协议规范](docs/DEV_SPEC.md) +- [MCP 接入指南](docs/MCP_INTEGRATION.md) +- [生产部署与运维指南](deploy/README.md) +- [发布验收标准](docs/ACCEPTANCE_CRITERIA.md) +- [项目进度与路线图](docs/PROGRESS_TRACKING.md) +- [v2.1 安全加固规范](docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md) + +--- + +## 📜 开源协议 + +本项目基于 [MIT](LICENSE) 协议开源。 diff --git a/deploy/README.md b/deploy/README.md index c94be5f..0303957 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -1,52 +1,196 @@ -# VPS-Commander 生产部署与运维 +# VPS-Commander 部署与运维指南 -> 基线：2026-10-02 +本文档介绍 VPS-Commander 当前生产环境部署架构、凭据规范、Agent 接入、升级与回滚流程。 -## 1. 拓扑 -Internet → TLS Reverse Proxy → vpstool.kory.kdns.fr → 127.0.0.1:9521 → Hub。 -Hub → Local Executor 或 Agent WSS。 -Hub 不直接公网监听；Agent 不需要公网入站管理端口。 +--- -## 2. Hub -binary：/opt/vps-commander/vps-commander-hub -env：/etc/vps-commander/hub.env -db：/opt/vps-commander/data/commander.db -systemd：vps-commander-hub.service -listen：127.0.0.1:9521 +## 一、系统架构与端口规划 -## 3. Agent -binary：/opt/vps-commander/vps-commander-agent -env：/etc/vps-commander/agent.env -必须包含 VPS_COMMANDER_HUB_WS_URL、VPS_COMMANDER_AGENT_NAME、VPS_COMMANDER_AGENT_TOKEN。 -env 文件必须 0600。 +- **Hub 服务端**：监听 `127.0.0.1:9521`，不直接暴露公网。 +- **反向代理**：公网 HTTPS/WSS 入口为 `https://vpstool.kory.kdns.fr`。 +- **Agent 客户端**：通过 `wss://vpstool.kory.kdns.fr/agent/ws` 主动回连 Hub。 -## 4. Credential -每个 Agent 使用独立 token；Hub SQLite 只保存 token hash。 -生产不依赖 Cluster Secret fallback。 -v2.0 代码仍兼容旧 -token 参数；v2.1 要求 secret 不进入 argv/cmdline。 +反代必须支持： +- WebSocket Upgrade； +- `/agent/ws`； +- `/mcp/*`； +- `/api/v1/*`； +- `/panel/*`； +- `/.well-known/*`； +- `/oauth/*`。 -## 5. Reverse Proxy -必须支持 HTTPS、WebSocket Upgrade、/agent/ws、/mcp/*、/api/v1/*、/panel/*、/.well-known/*、/oauth/*。 +--- -## 6. Clean Release -禁止 dirty tree build。 -git status --short；go test ./...；go test -race ./...；git diff --check；make clean；make linux-amd64；make linux-arm64。 -发布证据必须包含 vcs.modified=false 和 vcs.revision=。 +## 二、凭据安全规范（强制要求） -## 7. Rolling -backup → Hub install/restart → Agent recovery → single-node gray → rolling Agent → MCP smoke → audit → acceptance。 -任何断联或授权异常都停止。 +### 2.1 Hub 凭据 +Hub 使用： +- `VPS_COMMANDER_API_KEY`； +- `VPS_COMMANDER_WEB_PASSWORD`。 -## 8. 日常检查 +生产环境不再依赖 `VPS_COMMANDER_CLUSTER_SECRET` 作为 Agent 身份 fallback。 + +### 2.2 Agent 凭据 +每台 Agent 使用独立： +`VPS_COMMANDER_AGENT_TOKEN`。 + +Hub SQLite 仅保存 Credential Hash。 + +### 2.3 文件权限 +```bash +chmod 0600 /etc/vps-commander/hub.env +chmod 0600 /etc/vps-commander/agent.env +``` + +### 2.4 v2.1 安全要求 +当前 v2.0 代码仍兼容旧的 `-token` 参数；下一版本要求 Secret 不出现在 argv / `/proc/*/cmdline`，优先使用 systemd EnvironmentFile / LoadCredential。 + +--- + +## 三、Hub 服务端部署步骤 + +### 3.1 编译 +```bash +cd /root/.openclaw/workspace/vps-commander +go test ./... +go test -race ./... +git diff --check +make clean +make linux-amd64 +``` + +发布前必须确认： +```text +vcs.modified=false +vcs.revision= +``` + +### 3.2 安装 +```bash +install -d -m 0750 /opt/vps-commander/data /etc/vps-commander +install -m 0755 bin/vps-commander-hub-linux-amd64 /opt/vps-commander/vps-commander-hub +``` + +### 3.3 配置 +```bash +cat << 'ENV' > /etc/vps-commander/hub.env +VPS_COMMANDER_API_KEY=your_secure_api_key +VPS_COMMANDER_WEB_PASSWORD=your_web_password +ENV +chmod 0600 /etc/vps-commander/hub.env +``` + +### 3.4 Systemd +```ini +[Service] +EnvironmentFile=-/etc/vps-commander/hub.env +ExecStart=/opt/vps-commander/vps-commander-hub -addr 127.0.0.1:9521 -db /opt/vps-commander/data/commander.db +Restart=always +RestartSec=3s +``` + +### 3.5 启动 +```bash +systemctl daemon-reload +systemctl enable --now vps-commander-hub +systemctl status vps-commander-hub +``` + +--- + +## 四、远程 Agent 节点部署步骤 + +### 4.1 安装二进制 +```bash +install -d -m 0750 /etc/vps-commander /opt/vps-commander +install -m 0755 vps-commander-agent-linux-amd64 /opt/vps-commander/vps-commander-agent +``` + +### 4.2 配置 +```bash +cat << 'ENV' > /etc/vps-commander/agent.env +VPS_COMMANDER_HUB_WS_URL=wss://vpstool.kory.kdns.fr/agent/ws +VPS_COMMANDER_AGENT_NAME=vps-node-01 +VPS_COMMANDER_AGENT_TOKEN= +ENV +chmod 0600 /etc/vps-commander/agent.env +``` + +### 4.3 Systemd +```ini +[Service] +EnvironmentFile=-/etc/vps-commander/agent.env +ExecStart=/opt/vps-commander/vps-commander-agent -hub ${VPS_COMMANDER_HUB_WS_URL} -name ${VPS_COMMANDER_AGENT_NAME} +Restart=always +RestartSec=3s +``` + +当前 v2.0 生产迁移阶段可兼容显式 token；v2.1 发布后必须改为不出现在 ExecStart 的方式。 + +### 4.4 启动 +```bash +systemctl daemon-reload +systemctl enable --now vps-commander-agent +systemctl status vps-commander-agent +``` + +Agent 启动后主动连接 Hub，并在设备列表中显示为 `online`。 + +--- + +## 五、控制面板与 MCP 使用 + +### 5.1 管理面板 +`https://vpstool.kory.kdns.fr/panel/login` + +面板包含设备状态、安全策略、操作控制、审计和相关管理功能。 + +### 5.2 MCP +远程入口： +`https://vpstool.kory.kdns.fr/mcp/sse` + +本地 stdio 使用 `vps-commander-mcp-stdio`。 + +当前共 11 个 MCP tools，详见 `docs/MCP_INTEGRATION.md`。 + +--- + +## 六、生产升级流程 + +```text +Backup + ↓ +Clean Build + ↓ +Single-node Gray Release + ↓ +Hub Restart Recovery + ↓ +Rolling Agent + ↓ +MCP / Security / Audit Smoke Test + ↓ +Full Acceptance +``` + +任一节点断联、权限绕过、Credential 泄露或协议不兼容，立即停止发布并回滚。 + +--- + +## 七、日常运维检查 + +```bash systemctl status vps-commander-hub journalctl -u vps-commander-hub -n 100 curl -fsS http://127.0.0.1:9521/healthz -/api/v1/devices、Web Panel、MCP list_devices。 +``` -## 9. 当前生产审计 -2026-10-02 Bug Hunt 发现生产 Hub/Agent 曾 vcs.modified=true。 -这说明现场二进制不能直接视为 HEAD 的可复现产物；下一次发布必须 clean rebuild 并重新部署。 +集群可通过 Web Panel、`/api/v1/devices` 或 MCP `list_devices` 检查。 -## 10. 回滚 -保留 Hub/Agent binary、systemd env、commander.db backup、release commit。 -协议不兼容时先恢复 Hub，再滚动恢复 Agent。 +--- + +## 八、当前生产审计提示 + +2026-10-02 审计发现生产 Hub / Agent 曾由 `vcs.modified=true` 的工作树构建。 +因此生产现场二进制不能直接视为当前 HEAD 的可复现产物。 +下一次正式发布必须 clean rebuild，并重新部署与验证。 diff --git a/docs/ACCEPTANCE_CRITERIA.md b/docs/ACCEPTANCE_CRITERIA.md index 51aa3cc..1bf61b6 100644 --- a/docs/ACCEPTANCE_CRITERIA.md +++ b/docs/ACCEPTANCE_CRITERIA.md @@ -1,58 +1,131 @@ -# VPS-Commander 当前发布门禁 +# VPS-Commander 阶段验收标准与发布门禁用例矩阵 -## 1. Build -- clean Git tree -- vcs.modified=false -- vcs.revision == release commit -- AMD64/ARM64 build 成功 +本文档定义当前 v2.0 生产架构的发布门禁，并为 v2.1 安全加固预留验收项。 -## 2. Cluster -- Hub 127.0.0.1:9521 -- 5 个远程 Agent online -- Hub restart 后自动恢复 -- unknown device fail-closed +--- -## 3. Auth -- Bearer auth -- URL token rejected -- per-device credential -- Shared Secret fallback disabled -- Panel Admin Token 不进浏览器 +## 一、构建与版本一致性 -## 4. Authorization -- Tool Registry 固定 -- Low/Medium/High 一致 -- MCP 与 HTTP 共用 gate -- call_agent_mcp 无旁路 -- policy version 不回退 +### 1.1 基础测试 +```bash +go test ./... +go test -race ./... +git diff --check +``` -## 5. File -- edit_block 唯一匹配 -- atomic write -- generation check -- failure 不损坏原文件 +### 1.2 生产构建 +- Git 工作树必须 clean。 +- `vcs.modified=false`。 +- `vcs.revision` 必须等于 release commit。 +- AMD64 / ARM64 编译成功。 -## 6. Session -- hard TTL -- idle TTL -- ring buffer cap -- manager concurrency safe -- kill 只操作 Session 内部 process handle +--- -## 7. MCP -11 tools 与源码一致：list_devices、exec_command、read_file、read_multiple_files、create_directory、move_file、list_processes、edit_block、write_file、list_agent_mcp、call_agent_mcp。 -必须验证：Medium 可拦截写工具；Medium 可拦截 High 工具；Agent MCP 有 gate；stdio 正常；SSE 正常。 +## 二、Hub / Agent 集群验收 -## 8. API regression -devices、exec、file read/list/info/search/write、edit_block、process/session、MCP、security、webhook、panel、agent WS。 +| 项目 | 验收标准 | +| :--- | :--- | +| Hub | 监听 `127.0.0.1:9521` | +| Agent | 5 个远程节点可正常回连 | +| Restart | Hub 重启后 Agent 自动恢复 | +| Identity | Credential 与设备身份一致 | +| Unknown | 未知设备必须 fail-closed | -## 9. Test -go test ./...；go test -race ./...；git diff --check。 -并在 clean build 后重新执行核心 smoke。 +--- -## 10. Stop conditions -Agent 断联、认证绕过、unknown device 获得 High、MCP 旁路、token 进入 argv、审计丢失、dirty binary、policy version 回退、Session 无限制增长，任一发生即停止发布。 +## 三、认证与授权验收 -## 11. v2.1 -P0：EffectiveRisk fail-closed；Agent credential 不进 argv。 -P1：Principal、Session owner 强隔离、身份链审计。 +- Bearer API Key 正常。 +- URL token (`?token` / `?key` / `?api_key`) 必须拒绝。 +- 每设备 Credential 独立。 +- Shared Secret fallback 关闭。 +- Panel Admin Token 不进入浏览器。 +- Tool Registry 风险等级一致。 +- Policy version 不允许回退。 + +--- + +## 四、MCP 验收矩阵 + +| Tool | Risk | 基础用例 | +| :--- | :--- | :--- | +| `list_devices` | Low | 返回设备列表 | +| `exec_command` | High | `echo/true` | +| `read_file` | Low | 读取 `/etc/hostname` | +| `read_multiple_files` | Low | 批量读取临时文件 | +| `create_directory` | Medium | 创建临时目录 | +| `move_file` | Medium | 移动临时文件 | +| `list_processes` | Low | 返回进程 | +| `edit_block` | Medium | 唯一匹配修改 | +| `write_file` | Medium | 写入临时文件 | +| `list_agent_mcp` | Low | 查询 Agent MCP | +| `call_agent_mcp` | Medium | 调用无害 Agent MCP | + +必须同时验证： +- Medium 策略可以阻断 Medium 工具。 +- Medium 策略可以阻断 High 工具。 +- MCP 与 HTTP 使用同一授权逻辑。 +- `call_agent_mcp` 无旁路。 + +--- + +## 五、文件与 Session 验收 + +### 5.1 edit_block +- old_text 唯一匹配。 +- generation check。 +- atomic write。 +- fsync。 +- 失败不破坏原文件。 + +### 5.2 Session +- Hard TTL。 +- Idle TTL。 +- Ring Buffer 上限。 +- 总 buffer 上限。 +- 并发访问安全。 +- kill 只能作用于 Session 内部 process handle。 + +--- + +## 六、API Regression + +必须覆盖： +- `/api/v1/devices` +- `/api/v1/exec` +- file read/list/info/search/write +- edit_block +- process/session +- MCP services/list/call/test +- security settings +- webhook +- Panel +- Agent WebSocket + +--- + +## 七、发布停止条件 + +出现以下任一情况立即停止发布： +- Agent 断联。 +- 未授权请求成功。 +- unknown device 获得 High。 +- MCP 存在旁路。 +- Token 出现在 argv。 +- 审计丢失。 +- dirty binary。 +- Policy version 回退。 +- Session 资源无限增长。 + +--- + +## 八、v2.1 验收预留 + +### P0 +- EffectiveRisk 完全 fail-closed。 +- Agent Credential 不进入 argv / cmdline。 + +### P1 +- Principal / Operator。 +- Session Owner 强隔离。 +- principal → credential → session → device → operation 审计链。 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 66cc75f..83f10ba 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,48 +1,198 @@ -# VPS-Commander 当前系统架构规范 +# VPS-Commander（自托管私有化多节点运维管家）架构与开发设计规范 -## 1. 研发起点 -项目最初不是远程终端 UI，而是私有化 AI 运维控制面：用户自己的 Hub 作为控制中枢，多 VPS 通过 Agent 汇聚，AI 通过标准 API/MCP 发起操作，高权限能力可认证、可授权、可审计、可回滚。 +## 一、项目立项背景与目标 -## 2. 双通道 -控制通道：AI/MCP/HTTP → Hub → Local Executor 或 Agent RPC。 -节点通道：Agent → WSS → Hub。 -Hub 同时承担身份、策略、路由、审计和资源门禁；任何 MCP 或 Agent MCP 调用都不能绕过 Hub。 +### 1.1 背景与痛点 +- 早期方案过度依赖第三方 Relay，控制面与节点执行面边界不清。 +- 单机开发网关通常存在项目目录沙箱，无法覆盖完整 Host-centric 运维。 +- AI Agent 需要的不只是 Shell，而是节点发现、文件、进程、Session、MCP 和审计的一体化控制面。 -## 3. Hub -生产 binary：/opt/vps-commander/vps-commander-hub。 -监听：127.0.0.1:9521。 -数据库：/opt/vps-commander/data/commander.db。 -systemd：vps-commander-hub.service。 -职责：HTTP API、MCP、Panel、设备状态、Agent RPC、Policy Snapshot、credential、audit、Webhook、本地执行。 +### 1.2 核心目标 +- **100% 私有化控制面**：Hub、Agent、SQLite 与反向代理均由用户控制。 +- **Host-centric 运维**：Shell、文件、进程、Session、远程 MCP。 +- **多节点统一调度**：一个 Hub 管理多个 VPS，节点状态持久化。 +- **AI 原生接入**：HTTP、MCP、stdio、Web 管理面板。 +- **安全闭环**：认证、风险授权、资源限制、审计、可回滚发布。 -## 4. Agent -Agent 是目标主机上的最小执行面，主动连接 /agent/ws，不要求远端开放管理端口。 -握手包含 protocol version、AgentVersion、capabilities、per-device credential。 -设备身份必须来自已认证 credential，不能信任客户端自报 device/name。 +--- -## 5. 安全模型 -Client：Bearer API Key；Panel：Panel Session；Agent：per-device credential。 -Tool Registry 定义静态风险；Policy Snapshot 定义设备运行时权限。 -Low / Medium / High 是权限上限；unknown device → deny。 -生产 Shared Secret fallback 已关闭。 +## 二、总体架构设计 -## 6. Tool Registry -Low：read_file、read_multiple_files、list_directory、get_file_info、start_search、get_more_search_results、list_processes、list_sessions、read_process_output。 -Medium：edit_block、write_file、create_directory、move_file、mcp_call。 -High：exec_command、start_process、interact_with_process、kill_process、force_terminate。 +```text +[ AI / MCP Client / Web Panel ] + │ + ▼ HTTPS / MCP + [ Reverse Proxy / TLS ] + │ + ▼ 127.0.0.1:9521 + ┌──────────────────────────────────────────────┐ + │ VPS-Commander Hub │ + │----------------------------------------------│ + │ Auth / API / MCP / Web Panel │ + │ Policy Snapshot / Tool Registry │ + │ Cluster Router / Session / Rate Limit │ + │ SQLite / Audit / Webhook │ + └──────────────┬───────────────────┬───────────┘ + │ │ + Local Executor Agent WSS + │ │ + ▼ ▼ + Hub 本机 Remote VPS + │ + Host Executor + Shell / File / Process +``` -## 7. Policy Snapshot -SQLite 保存策略版本，Hub 使用内存 Snapshot 处理读路径。 -version 单调递增；发布失败不替换旧 Snapshot；unknown device 不继承 GlobalRisk High。 -v2.1 将彻底消除 EffectiveRisk 的 GlobalRisk fail-open fallback。 +### 2.1 控制通道 +AI / MCP / HTTP 请求进入 Hub，由 Hub 完成认证、设备解析、风险判断和路由。 -## 8. Session 与文件安全 -Session：默认 RingBuffer 2MB，总 buffer 8MB，hard TTL 30m，idle TTL 10m，LastAccess + cleanup。 -kill/terminate 使用 Session 内部 process handle，不接受客户端 PID；Principal 强隔离属于 v2.1。 -edit_block：唯一匹配、generation fingerprint、临时文件、fsync、atomic rename、保留权限。 +### 2.2 节点通道 +Agent 主动通过 WSS 回连 Hub，负责设备注册、状态、能力协商及 RPC 请求/响应。 -## 9. 部署与回滚 -Internet → TLS Reverse Proxy → 127.0.0.1:9521；Agent 仅出站 WSS。 -生产节点：wjyhk、N3450、hwhk、hwsg、m4-live-agent、qnvn。 -backup → clean build → single-node gray → Hub recovery → rolling Agent → audit → acceptance。 -发现断联、授权绕过、credential 泄露或协议不兼容，立即停止 rollout 并回滚。 +两条通道共享同一设备身份、策略和审计上下文，不允许出现 MCP 或 Agent MCP 绕过 Hub 授权的旁路。 + +--- + +## 三、Hub 与 Agent 通信规范 + +### 3.1 Agent 注册与鉴权 +- Agent 连接：`wss:///agent/ws`。 +- 使用每设备独立 Credential。 +- Hub 从已认证 Credential 建立 Canonical Device Identity。 +- 客户端自报 `device/name` 不能成为授权身份来源。 +- 生产不再使用 Cluster Secret fallback。 + +### 3.2 协议握手 +握手包含： +- Protocol Version； +- AgentVersion； +- Capabilities； +- Per-device Credential。 + +### 3.3 RPC +Hub 将经过授权的操作转换为 Agent RPC。 +Agent 返回结果后，Hub 完成审计并将结果返回 HTTP/MCP 调用方。 + +--- + +## 四、安全与权限模型 + +### 4.1 认证 +- HTTP / MCP：Bearer API Key。 +- Web Panel：Panel Session，服务端内部 bridge Admin Token。 +- Agent：per-device credential。 + +### 4.2 Tool Risk Registry + +| 风险 | 典型操作 | +| :--- | :--- | +| Low | read_file、read_multiple_files、list_directory、file_info、search、list_processes | +| Medium | edit_block、write_file、create_directory、move_file、mcp_call | +| High | exec_command、start_process、interact_with_process、kill_process、force_terminate | + +### 4.3 Policy Snapshot +- 安全策略持久化到 SQLite。 +- 每次更新生成单调递增 version。 +- Hub 请求路径读取内存 Snapshot。 +- 未知、未注册、凭据错误或身份无法解析的设备必须 deny。 +- GlobalRisk 不得让未知设备获得 High。 + +v2.1 将彻底清理 `EffectiveRisk` 中仍存在的 GlobalRisk fallback。 + +--- + +## 五、Session 与执行安全 + +### 5.1 Session 资源限制 +- Ring Buffer 默认 2MB。 +- 总 Session buffer 上限 8MB。 +- Hard TTL 30 分钟。 +- Idle TTL 10 分钟。 +- LastAccess 自动刷新。 +- 过期与空闲 Session 自动清理。 + +### 5.2 进程生命周期 +kill / terminate 使用 Session 内部进程句柄，不接受客户端任意 PID 作为授权对象。 + +### 5.3 文件修改 +`edit_block` 使用唯一匹配、generation check、临时文件、fsync、atomic rename 和权限保留，失败时不破坏原文件。 + +--- + +## 六、MCP 架构 + +当前 MCP 共 11 个工具： +1. `list_devices` +2. `exec_command` +3. `read_file` +4. `read_multiple_files` +5. `create_directory` +6. `move_file` +7. `list_processes` +8. `edit_block` +9. `write_file` +10. `list_agent_mcp` +11. `call_agent_mcp` + +`call_agent_mcp` 必须经过 MCP risk gate，不允许成为远程 Agent 的权限旁路。 + +当前远程 transport 为 legacy HTTP + SSE，本地客户端为 stdio；Streamable HTTP 属于后续演进。 + +--- + +## 七、项目工程结构与技术选型 + +- **语言**：Go。 +- **存储**：SQLite。 +- **HTTP**：标准库。 +- **Web**：Go embed。 +- **节点通信**：WebSocket。 + +```text +cmd/ +├── hub/ +├── agent/ +└── mcp-stdio/ +internal/ +├── api/ +├── auth/ +├── cluster/ +├── executor/ +├── mcp/ +├── model/ +├── notify/ +├── security/ +├── storage/ +└── web/ +``` + +--- + +## 八、生产部署边界 + +- Hub：`127.0.0.1:9521`。 +- 公网由 Reverse Proxy 终止 TLS。 +- Agent 仅出站连接 Hub。 +- 数据库：`/opt/vps-commander/data/commander.db`。 +- systemd：`vps-commander-hub.service` / `vps-commander-agent.service`。 + +升级必须执行： +1. backup； +2. clean build； +3. 单节点灰度； +4. Hub restart recovery； +5. rolling Agent； +6. MCP/security/audit 验收。 + +--- + +## 九、v2.1 演进方向 + +### 9.1 P0 +- EffectiveRisk 完全 fail-closed。 +- Agent Credential 不进入 argv / cmdline。 + +### 9.2 P1 +- Principal / Operator Identity。 +- Session Owner 强隔离。 +- principal → credential → session → device → operation 完整审计链。 diff --git a/docs/DEV_SPEC.md b/docs/DEV_SPEC.md index a0f4ab9..cdffbfc 100644 --- a/docs/DEV_SPEC.md +++ b/docs/DEV_SPEC.md @@ -1,42 +1,167 @@ -# VPS-Commander 开发与协议规范 +# VPS-Commander 研发设计规范与协议说明 -## 1. 技术基线 -Go + SQLite + net/http + WebSocket。 -组件：cmd/hub、cmd/agent、cmd/mcp-stdio；internal/api、auth、cluster、executor、mcp、security、storage、web、notify、model。 +## 一、技术选型与工程原则 -## 2. Agent Protocol -Agent 主动连接 /agent/ws。 -握手包含 protocol version、AgentVersion、capabilities、per-device credential。 -Hub 依据 credential 建立 canonical device identity；device/name 只能作为路由参数。 +- **开发语言**：Go。 +- **存储**：SQLite。 +- **HTTP**：标准库 `net/http`。 +- **节点通信**：WebSocket。 +- **Web 前端**：Go `embed`。 -## 3. HTTP -/api/v1/devices、/api/v1/exec、/api/v1/file/read、/api/v1/file/list、/api/v1/file/info、/api/v1/file/search、/api/v1/process/session、/api/v1/file/write、/api/v1/devices/file/edit_block、/api/v1/mcp/*、/api/v1/security/*、/api/v1/notifications/webhook*、/healthz、/openapi.json。 -Panel 使用 /panel/*。 +工程原则： +1. 认证与授权分离。 +2. Tool Risk 静态注册。 +3. Device Policy 运行时解析。 +4. 默认 fail-closed。 +5. Session 必须有 TTL 与资源上限。 +6. 生产二进制必须可追溯。 +7. 发布必须可回滚。 -## 4. MCP -serverInfo version：1.2.0；protocolVersion：2024-11-05。 -11 tools：list_devices、exec_command、read_file、read_multiple_files、create_directory、move_file、list_processes、edit_block、write_file、list_agent_mcp、call_agent_mcp。 -远程 HTTP 当前为 legacy SSE：GET /mcp/sse + POST /mcp/message?sessionId=...；本地为 stdio。 +--- -## 5. MCP 授权 -exec → High；read → Low；write/edit/create/move → Medium；call_agent_mcp → mcp；list_agent_mcp → read。 -MCP adapter 与 direct Agent MCP 使用同一 Hub security model。 +## 二、项目工程结构 -## 6. 认证 -HTTP/MCP：Authorization: Bearer API_KEY。 -禁止 ?token、?key、?api_key。 -Agent：per-device credential；SQLite 只保存 hash；生产不依赖 Cluster Secret fallback。 -Panel：浏览器只持有 Panel Session；Admin Token 在服务端 bridge。 +```text +vps-commander/ +├── cmd/ +│ ├── hub/ +│ ├── agent/ +│ └── mcp-stdio/ +├── internal/ +│ ├── api/ +│ ├── auth/ +│ ├── cluster/ +│ ├── executor/ +│ ├── mcp/ +│ ├── model/ +│ ├── notify/ +│ ├── security/ +│ ├── storage/ +│ └── web/ +├── docs/ +├── deploy/ +└── openapi.json +``` -## 7. 资源 -ExecLimiter 32；SearchLimiter 8；Node.WriteMu；Node.OpMu。 -Session：ring 2MB；total 8MB；hard TTL 30m；idle TTL 10m；cleanup。 +--- -## 8. 测试 -go test ./...；go test -race ./...；git diff --check。 -生产额外要求 clean tree、vcs.modified=false、revision 与 release commit 一致、单 Agent 灰度、Hub recovery、MCP smoke、security matrix。 +## 三、Agent WebSocket 协议 -## 9. v2.1 -P0：EffectiveRisk fail-closed；Agent token 不进入 argv/cmdline。 -P1：Principal/Operator、Session owner 强隔离、完整身份审计链。 -v2.1 不改变 Low/Medium/High 语义，不恢复 Shared Secret。 +Agent 主动连接：`/agent/ws`。 + +握手包含： +- Protocol Version。 +- AgentVersion。 +- Capabilities。 +- Per-device Credential。 + +Hub 根据 Credential 建立 Canonical Device Identity。 +客户端请求中的 `device/name` 只能用于路由，不能作为授权身份来源。 + +--- + +## 四、HTTP API 规范 + +| 路径 | 方法 | 功能 | +| :--- | :--- | :--- | +| `/api/v1/devices` | GET | 设备列表 | +| `/api/v1/exec` | POST | Shell | +| `/api/v1/file/read` | POST | 文件读取 | +| `/api/v1/file/list` | POST | 目录列表 | +| `/api/v1/file/info` | POST | 文件信息 | +| `/api/v1/file/search` | POST | 文件搜索 | +| `/api/v1/process/session` | POST | Session | +| `/api/v1/file/write` | POST | 文件写入 | +| `/api/v1/devices/file/edit_block` | POST | 原子编辑 | +| `/api/v1/mcp/*` | GET/POST/DELETE | MCP | +| `/api/v1/security/*` | GET/POST | 安全策略 | +| `/api/v1/notifications/webhook*` | GET/POST/DELETE | Webhook | +| `/healthz` | GET | 健康检查 | +| `/openapi.json` | GET | OpenAPI | + +--- + +## 五、MCP 协议规范 + +Server version：`1.2.0`。 +Protocol Version：`2024-11-05`。 + +当前工具共 11 个： +`list_devices`、`exec_command`、`read_file`、`read_multiple_files`、`create_directory`、`move_file`、`list_processes`、`edit_block`、`write_file`、`list_agent_mcp`、`call_agent_mcp`。 + +远程 transport：legacy HTTP + SSE。 +本地 transport：stdio。 +未来 transport：Streamable HTTP。 + +--- + +## 六、认证与安全规范 + +### 6.1 HTTP / MCP +```http +Authorization: Bearer +``` + +禁止： +- `?token=` +- `?key=` +- `?api_key=` + +### 6.2 Agent +- 每设备独立 Credential。 +- SQLite 只保存 Hash。 +- 生产关闭 Shared Secret fallback。 + +### 6.3 Panel +Panel Session 在服务端认证。 +Admin Token 只在 Panel → 内部 API bridge 中使用，不发送给浏览器。 + +--- + +## 七、并发与资源限制 + +| 项目 | 限制 | +| :--- | :--- | +| Exec | 32 并发 | +| Search | 8 并发 | +| Session Ring | 2MB | +| Session 总 Buffer | 8MB | +| Session Hard TTL | 30m | +| Session Idle TTL | 10m | +| WS Write | Node.WriteMu | +| Medium/High | Node.OpMu | + +--- + +## 八、测试与发布规范 + +### 8.1 提交前 +```bash +go test ./... +go test -race ./... +git diff --check +``` + +### 8.2 发布前 +- clean Git tree。 +- `vcs.modified=false`。 +- revision 与 release commit 一致。 +- 单 Agent 灰度。 +- Hub restart recovery。 +- MCP smoke test。 +- security deny/allow matrix。 + +--- + +## 九、v2.1 研发计划 + +### 9.1 P0 +- EffectiveRisk 完全 fail-closed。 +- Credential 不进入 argv / cmdline。 + +### 9.2 P1 +- Principal / Operator Identity。 +- Session Owner 强隔离。 +- 完整身份审计链。 + +v2.1 不改变 Low / Medium / High 语义，不恢复 Shared Secret。 diff --git a/docs/DOCUMENTATION_BASELINE_20261002.md b/docs/DOCUMENTATION_BASELINE_20261002.md index eec7f07..3f6aceb 100644 --- a/docs/DOCUMENTATION_BASELINE_20261002.md +++ b/docs/DOCUMENTATION_BASELINE_20261002.md @@ -1,123 +1,128 @@ -# VPS-Commander 文档基线与现状索引 +# VPS-Commander 全仓库文档基线与索引 -> 基线日期：2026-10-02 -> 本文件是仓库文档的导航入口。历史审核记录保留原貌，不作为当前实现契约。 +本文档作为 2026-10-02 之后的文档总入口，用于区分当前设计、历史记录与下一版本研发计划。 -## 当前定位 +--- -VPS-Commander 是自托管的多节点 Linux 运维控制中枢。 -链路：AI/客户端 → Hub → Local Executor 或 Agent WebSocket → 目标主机。 +## 一、当前项目定位 -当前目标： -- 多节点统一身份、路由与状态管理； -- 文件、进程、Shell、MCP 运维能力； -- 认证、三级风险授权与审计； -- 可回滚、可持续升级的生产部署； -- 面向 AI Agent 的 MCP 与 HTTP 接口。 +VPS-Commander 是自托管、多节点、AI Agent 友好的 Linux 运维控制中枢。 -## 当前架构 +核心链路： +`AI / MCP / Web Panel → Hub → Local Executor 或 Agent WSS → Target Host`。 -```text -AI / MCP / Web - | - HTTPS/WSS - | -Reverse Proxy - | -Hub 127.0.0.1:9521 - | | -Local Agent WSS -Executor | - +-- N3450 - +-- hwhk - +-- hwsg - +-- m4-live-agent - +-- qnvn - | -SQLite: state / policy / audit -``` +--- -Hub 不直接公网监听；Agent 只主动回连 Hub。 +## 二、当前架构基线 -## 当前安全模型 +### 2.1 Hub +- HTTP API。 +- MCP。 +- Web Panel。 +- Agent Router。 +- Security Snapshot。 +- Tool Registry。 +- Session。 +- SQLite。 +- Audit / Webhook。 -- HTTP/MCP：Bearer API Key； -- Agent：per-device credential； -- Policy Snapshot：设备级有效策略； -- Tool Registry：Low / Medium / High； -- MCP、HTTP、direct Agent MCP 统一授权； -- SQLite 审计； -- 生产 Shared Secret fallback 已关闭。 +### 2.2 Agent +- 主动 WSS 回连。 +- per-device Credential。 +- Protocol / AgentVersion / Capabilities。 +- Host-level File / Shell / Process 执行。 -## 当前 MCP +### 2.3 双通道 +- 控制通道：HTTP / MCP → Hub → Executor。 +- 节点通道：Agent → WSS → Hub。 + +--- + +## 三、当前 MCP 基线 11 个工具： -list_devices、exec_command、read_file、read_multiple_files、 -create_directory、move_file、list_processes、edit_block、 -write_file、list_agent_mcp、call_agent_mcp。 +`list_devices`、`exec_command`、`read_file`、`read_multiple_files`、`create_directory`、`move_file`、`list_processes`、`edit_block`、`write_file`、`list_agent_mcp`、`call_agent_mcp`。 -当前 HTTP MCP 是 legacy HTTP+SSE；本地是 stdio。 -Streamable HTTP 是后续演进方向。 +远程：legacy SSE。 +本地：stdio。 +下一阶段：Streamable HTTP。 -## 当前 HTTP +--- -主要接口： -/api/v1/devices -/api/v1/exec -/api/v1/file/read -/api/v1/file/list -/api/v1/file/info -/api/v1/file/search -/api/v1/process/session -/api/v1/file/write -/api/v1/devices/file/edit_block -/api/v1/mcp/* -/api/v1/security/* -/api/v1/notifications/webhook* -/agent/ws -/healthz -/openapi.json -/panel/* +## 四、当前安全基线 -## 文档分层 +- HTTP/MCP：Bearer API Key。 +- Agent：per-device Credential。 +- SQLite：Credential Hash。 +- Low / Medium / High Tool Risk。 +- Policy Snapshot。 +- Shared Secret fallback：生产关闭。 +- MCP 与 HTTP：统一授权门禁。 +- Panel Admin Token：服务端 bridge。 -当前规范： -- README.md -- docs/ARCHITECTURE.md -- docs/DEV_SPEC.md -- docs/MCP_INTEGRATION.md -- deploy/README.md -- docs/ACCEPTANCE_CRITERIA.md -- docs/PROGRESS_TRACKING.md -- docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md +--- -审计/整改输入： -- docs/BUGHUNT_20261002.md -- docs/DC_REFACTORING_AND_SECURITY_SPEC.md -- docs/DC_REFACTORING_SECURITY_REVIEW_HANDOFF_20261002.md -- docs/REVIEW_B_TO_A_HANDOFF_20261002.md +## 五、文档分层 -历史记录： -- REVIEW_A_CODE_AUDIT_20261002.md -- REVIEW_B_CODE_AUDIT_20261002.md -- INCIDENT_TIMEOUT-20260930.md -- M4_FINAL_ACCEPTANCE_REPORT.md -- DC_PHASE1_IMPLEMENTATION.md +### 5.1 当前规范 +- `README.md`：项目入口与能力总览。 +- `docs/ARCHITECTURE.md`：架构与设计。 +- `docs/DEV_SPEC.md`：研发与协议。 +- `docs/MCP_INTEGRATION.md`：MCP 接入。 +- `deploy/README.md`：生产部署。 +- `docs/ACCEPTANCE_CRITERIA.md`：验收门禁。 +- `docs/PROGRESS_TRACKING.md`：当前进度。 +- `docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md`：v2.1 安全加固。 -历史报告解释演进原因，不覆盖当前规范。 +### 5.2 审计 / 整改材料 +- `docs/BUGHUNT_20261002.md`。 +- `docs/DC_REFACTORING_AND_SECURITY_SPEC.md`。 +- `docs/DC_REFACTORING_SECURITY_REVIEW_HANDOFF_20261002.md`。 +- `docs/REVIEW_B_TO_A_HANDOFF_20261002.md`。 -## 生产状态 +### 5.3 历史记录 +- `REVIEW_A_CODE_AUDIT_20261002.md`。 +- `REVIEW_B_CODE_AUDIT_20261002.md`。 +- `INCIDENT_TIMEOUT-20260930.md`。 +- `M4_FINAL_ACCEPTANCE_REPORT.md`。 +- `DC_PHASE1_IMPLEMENTATION.md`。 -2026-10-02 审计确认 6 个设备在线： -wjyhk、N3450、hwhk、hwsg、m4-live-agent、qnvn。 +历史文件用于记录演进过程，不覆盖当前规范。 -同时发现生产二进制存在 vcs.modified=true 的构建漂移。 -因此必须区分“源码当前状态”和“生产现场状态”。 -下一次发布必须 clean build、校验 revision/modified，再滚动部署。 +--- -## v2.1 +## 六、当前生产基线 -P0：EffectiveRisk fail-closed；Agent Token 脱离 argv/cmdline。 -P1：Principal/Operator 身份、Session 强隔离、完整身份审计链。 -这些属于下一版本，不伪装成 v2.0 已完成能劘，不伪装成 v2.0 已完成能力。 +当前生产集群包括： +- `wjyhk` +- `N3450` +- `hwhk` +- `hwsg` +- `m4-live-agent` +- `qnvn` +Hub：`/opt/vps-commander/vps-commander-hub`。 +Database：`/opt/vps-commander/data/commander.db`。 +Listen：`127.0.0.1:9521`。 + +2026-10-02 审计发现生产二进制曾 `vcs.modified=true`，因此下一次发布必须 clean rebuild 后重新对齐生产现场。 + +--- + +## 七、v2.1 基线 + +### P0 +- EffectiveRisk 完全 fail-closed。 +- Agent Credential 脱离 argv / cmdline。 + +### P1 +- Principal / Operator Identity。 +- Session Owner 强隔离。 +- principal → credential → session → device → operation 审计链。 + +--- + +## 八、文档维护规则 + +新增能力必须同时检查 README、架构、开发规范、MCP、部署、验收、进度以及 OpenAPI Contract。 +历史报告只追加新的后续报告，不覆盖原始证据。 diff --git a/docs/MCP_INTEGRATION.md b/docs/MCP_INTEGRATION.md index ec017b0..4ae086a 100644 --- a/docs/MCP_INTEGRATION.md +++ b/docs/MCP_INTEGRATION.md @@ -1,52 +1,191 @@ -# VPS-Commander MCP 接入与能力 +# VPS-Commander MCP（Model Context Protocol）接入指南 -## 1. 当前状态 -MCP JSON-RPC 2.0；serverInfo 1.2.0；initialize protocolVersion 2024-11-05。 -远程 HTTP 当前是 legacy HTTP+SSE；本地是 stdio。Streamable HTTP 是后续演进方向。 +本文介绍 VPS-Commander 当前 MCP 能力、客户端接入方式、工具权限以及后续 transport 演进方向。 -## 2. 11 个工具 -| Tool | Risk | 作用 | -|---|---|---| -| list_devices | Low | 设备列表 | -| exec_command | High | Shell | -| read_file | Low | 文件读取 | -| read_multiple_files | Low | 批量读取 | -| create_directory | Medium | 创建目录 | -| move_file | Medium | 移动/重命名 | -| list_processes | Low | 进程观察 | -| edit_block | Medium | 原子文本修改 | -| write_file | Medium | 文件写入 | -| list_agent_mcp | Low | Agent MCP 列表 | -| call_agent_mcp | Medium | 调度 Agent MCP | +--- -## 3. 远程接入 -GET /mcp/sse → sessionId → POST /mcp/message?sessionId=。 -请求头：Authorization: Bearer 。 -HTTP+SSE 仅作为兼容层，不作为未来新能力的主要 transport。 +## 一、MCP 总体能力 -## 4. stdio -启动 vps-commander-mcp-stdio，参数 -hub -key 。 -API Key 不提交到仓库。 +VPS-Commander 当前提供两种 MCP 接入模式： -## 5. 参数 -exec_command：device、command、workdir、timeout。 -read_file：device、path、offset、limit；默认 256 KiB，最大 1 MiB。 -read_multiple_files：device、paths、limit；paths 最多 32 个。 -create_directory：device、path。 -move_file：device、source、destination。 -list_processes：device。 -edit_block：device、path、old_text、new_text；old_text 必须唯一匹配。 -write_file：device、path、content。 -list_agent_mcp：device。 -call_agent_mcp：device、server、tool、arguments。 +- **远程 HTTP SSE 模式**：适用于远程 MCP Client。 +- **本地 stdio 模式**：适用于 Claude Desktop、Cursor、VS Code 等本地客户端。 -## 6. 安全链路 -MCP Client → Bearer auth → JSON-RPC → tool mapping → authenticated device → Policy Snapshot → Tool Registry → allow/deny → Local/Agent → audit。 -未知设备不得因为 GlobalRisk 而获得 High。 +当前 MCP Server： +- JSON-RPC 2.0。 +- server version：`1.2.0`。 +- initialize protocolVersion：`2024-11-05`。 -## 7. Agent MCP -Hub 发现远程 Agent MCP service；客户端不直连 Agent。 -Hub 负责 device authentication、risk gate、routing、audit。 +当前远程 SSE 属于兼容 transport；后续新能力优先考虑 Streamable HTTP。 -## 8. 下一步 -Streamable HTTP、SSE fallback、capability-based advertisement、Principal audit context、显式 operation/session handle。 +--- + +## 二、当前支持的 11 大 MCP Tools + +| Tool 名称 | 风险等级 | 参数/功能说明 | +| :--- | :--- | :--- | +| `list_devices` | Low | 列出设备、状态及资源画像 | +| `exec_command` | High | 指定节点执行 Shell | +| `read_file` | Low | 分页读取文件 | +| `read_multiple_files` | Low | 批量读取多个文件 | +| `create_directory` | Medium | 创建目录 | +| `move_file` | Medium | 移动/重命名文件 | +| `list_processes` | Low | 查看进程 | +| `edit_block` | Medium | 唯一匹配 + 原子写回 | +| `write_file` | Medium | 创建或覆写文件 | +| `list_agent_mcp` | Low | 查询 Agent MCP 服务 | +| `call_agent_mcp` | Medium | 调用 Agent MCP 工具 | + +风险等级不是客户端提示，而是 Hub 强制执行的授权门禁。 + +--- + +## 三、统一安全链路 + +```text +MCP Client + │ + ▼ +Bearer Authentication + │ + ▼ +MCP JSON-RPC + │ + ▼ +Tool / Action Mapping + │ + ▼ +Authenticated Device Identity + │ + ▼ +Security Snapshot + Tool Risk + │ + ├── DENY + │ + ▼ +Local Executor / Agent WSS + │ + ▼ +Audit +``` + +`call_agent_mcp` 同样必须进入 MCP risk gate，不能因为目标是 Agent MCP 就绕过 Hub 授权。 + +--- + +## 四、远程 SSE 模式 + +### 4.1 SSE 建立 + +```text +GET https://your-domain.example/mcp/sse +Authorization: Bearer +``` + +服务器建立 MCP Session 后提供消息端点： + +```text +POST /mcp/message?sessionId= +Authorization: Bearer +``` + +### 4.2 注意事项 +- URL 中禁止放 Token。 +- `?token=`、`?key=`、`?api_key=` 不作为认证方式。 +- SSE 当前作为 legacy compatibility transport。 + +--- + +## 五、本地 stdio 模式 + +适用于 Claude Desktop、Cursor、VS Code 等本地客户端。 + +```json +{ + "mcpServers": { + "vps-commander": { + "command": "/opt/vps-commander/vps-commander-mcp-stdio", + "args": [ + "-hub", "https://your-domain.example", + "-key", "YOUR_API_KEY" + ] + } + } +} +``` + +API Key 不应提交到 Git 仓库。 + +--- + +## 六、主要工具参数 + +### 6.1 exec_command +- `device`：目标节点，可选。 +- `command`：必填。 +- `workdir`：可选。 +- `timeout`：默认 30 秒，最大 300 秒。 + +### 6.2 read_file +- `device`、`path` 必填。 +- `offset` 可选。 +- `limit` 默认 256 KiB，最大 1 MiB。 + +### 6.3 read_multiple_files +- `device` 可选。 +- `paths` 必填数组。 +- 当前 Hub 最多接受 32 个路径。 + +### 6.4 create_directory +- `device`、`path`。 + +### 6.5 move_file +- `device`、`source`、`destination`。 + +### 6.6 list_processes +- `device` 可选。 + +### 6.7 edit_block +- `device`、`path`、`old_text`、`new_text`。 +- `old_text` 必须唯一匹配。 +- 使用 generation check + atomic write。 + +### 6.8 write_file +- `device`、`path`、`content`。 + +### 6.9 list_agent_mcp +- `device` 必填。 + +### 6.10 call_agent_mcp +- `device`、`server`、`tool` 必填。 +- `arguments` 可选 JSON 对象。 + +--- + +## 七、Agent MCP + +Hub 可以发现远程 Agent 暴露的 MCP Service。 + +```text +MCP Client + ↓ +Hub Authentication + ↓ +Security Gate + ↓ +Authenticated Agent + ↓ +Agent MCP Service +``` + +客户端不直接连接 Agent MCP。 + +--- + +## 八、后续演进 + +1. Streamable HTTP。 +2. 保留 SSE fallback。 +3. Capability-based Tool Advertisement。 +4. Principal Identity 纳入 MCP Audit Context。 +5. 长任务引入显式 Operation / Session Handle。 diff --git a/docs/PROGRESS_TRACKING.md b/docs/PROGRESS_TRACKING.md index 95c257f..1be184c 100644 --- a/docs/PROGRESS_TRACKING.md +++ b/docs/PROGRESS_TRACKING.md @@ -1,47 +1,133 @@ -# VPS-Commander 当前进度与路线图 +# VPS-Commander 项目进度与路线图 -> 更新时间：2026-10-02 +本文档记录当前版本真实进度。历史审计文件继续保留原始证据，不直接作为当前状态判断依据。 -## 1. 已完成 -- Hub/Agent 双通道 -- 多节点状态持久化 -- per-device credential -- Security Snapshot -- Low/Medium/High gate -- MCP 安全门禁 -- edit_block 原子安全 -- Session 资源限制 -- Web Panel -- Webhook -- MCP 11 tools +--- -## 2. 当前 MCP -11 个：list_devices、exec_command、read_file、read_multiple_files、create_directory、move_file、list_processes、edit_block、write_file、list_agent_mcp、call_agent_mcp。 -早期文档中的“4 个 MCP 工具”已废止。 +## 一、当前总体状态 -## 3. v2.0 当前定位 -Hub、Agent WSS、per-device credential、Policy Snapshot、Tool Registry、MCP/HTTP unified gate、SQLite audit、Panel、Session limits 已形成完整架构。 +| 模块 | 状态 | +| :--- | :--- | +| Hub / Agent 双通道 | ✅ 已完成 | +| 多节点持久化 | ✅ 已完成 | +| Per-device Credential | ✅ 已完成 | +| Security Snapshot | ✅ 已完成 | +| Low / Medium / High Gate | ✅ 已完成 | +| MCP 安全门禁 | ✅ 已完成 | +| edit_block 原子安全 | ✅ 已完成 | +| Session 资源限制 | ✅ 已完成 | +| Web Panel | ✅ 已完成 | +| Webhook | ✅ 已完成 | +| MCP 11 Tools | ✅ 已完成源码实现 | +| Clean Production Rebuild | 🟡 下一次发布收口 | +| EffectiveRisk 完全 Fail-closed | 🔵 v2.1 | +| Agent Token 脱离 argv | 🔵 v2.1 | +| Principal 强隔离 | 🔵 v2.1 | -## 4. 当前发布问题 -2026-10-02 Bug Hunt： -1. 生产 binary 曾由 dirty tree 构建； -2. 造成生产 Agent 与 HEAD 能力漂移； -3. process/session snake_case 请求字段存在兼容问题； -4. Hub 本地 process/session 缺少 local fallback。 -在源码、测试、生产现场同时确认前，不把这些项目标记为已修复。 +--- -## 5. v2.1 P0 -EffectiveRisk：canonical device identity；unknown/offline/bad credential → risk 0；GlobalRisk 仅用于已认证设备；unknown 不得继承 High。 -Agent credential：EnvironmentFile/LoadCredential；ExecStart 不出现 secret；ps/cmdline 不可读 token；支持 rotation + rollback。 +## 二、MCP 当前能力 -## 6. v2.1 P1 -Principal：principal_id、principal_type、credential_id、device_id。 -Session owner 绑定 Principal；takeover 必须显式授权并审计。 -形成 principal → credential → session → device → operation 链。 +当前共 11 个 Tools： +1. `list_devices` +2. `exec_command` +3. `read_file` +4. `read_multiple_files` +5. `create_directory` +6. `move_file` +7. `list_processes` +8. `edit_block` +9. `write_file` +10. `list_agent_mcp` +11. `call_agent_mcp` -## 7. 发布顺序 -backup → clean build → single-node gray → Hub recovery → rolling Agent → MCP smoke → security matrix → audit → acceptance。 +早期“4 个 MCP Tools”的文档已经废止。 -## 8. 文档同步规则 -功能变化同时检查 README、ARCHITECTURE、DEV_SPEC、MCP_INTEGRATION、deploy/README、ACCEPTANCE_CRITERIA、PROGRESS_TRACKING、openapi.json。 -历史审核报告保留原貌，不回写当前结论。 +--- + +## 三、v2.0 当前收口 + +当前架构已经形成： +- Hub 中央控制。 +- Agent WSS 回连。 +- Per-device Credential。 +- Policy Snapshot。 +- Tool Registry。 +- MCP / HTTP Unified Gate。 +- SQLite Audit。 +- Session Resource Limits。 +- Web Management Panel。 + +--- + +## 四、2026-10-02 审计发现 + +### 4.1 生产构建漂移 +生产 Hub / Agent 曾以 `vcs.modified=true` 构建。 +这会破坏源码 → revision → binary 的可追溯链。 + +### 4.2 代码兼容问题 +- process/session API 存在 snake_case 请求字段兼容问题。 +- Hub 本地 process/session 路径缺少 local fallback。 + +在源码、测试和生产现场全部验证之前，上述项目不标记为“已修复”。 + +--- + +## 五、v2.1 路线 + +### 5.1 P0-1：EffectiveRisk +- Canonical Device Identity。 +- unknown / offline / bad credential → risk 0。 +- GlobalRisk 只作为已认证设备的业务默认。 +- Unknown 不得继承 High。 + +### 5.2 P0-2：Agent Credential +- EnvironmentFile / LoadCredential。 +- ExecStart 不出现 secret。 +- `/proc/*/cmdline` 不可读取 token。 +- 支持 rotation + rollback。 + +### 5.3 P1：Principal +- `principal_id`。 +- `principal_type`。 +- `credential_id`。 +- `device_id`。 +- Session Owner 绑定 Principal。 +- takeover 必须显式授权并审计。 + +--- + +## 六、标准发布顺序 + +```text +Backup + ↓ +Clean Build + ↓ +Single-node Gray Release + ↓ +Hub Restart Recovery + ↓ +Rolling Agent + ↓ +MCP / Security / Audit + ↓ +Full Acceptance +``` + +--- + +## 七、文档同步规则 + +任何新功能或安全变更必须同步检查： +- README +- ARCHITECTURE +- DEV_SPEC +- MCP_INTEGRATION +- deploy/README +- ACCEPTANCE_CRITERIA +- PROGRESS_TRACKING +- openapi.json（如影响 HTTP Contract） + +历史审核报告保持原貌，不回写成当前状态。