This commit is contained in:
kory
+189
-39
@@ -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://<hub>/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 完整审计链。
|
||||
|
||||
Reference in New Issue
Block a user