openclaw/vps-commander

Fork 0

Files

T

kory cc99022215

Release / Build & Release (push) Canceled after 0s

Details

docs: restore established documentation format

2026-10-02 14:01:14 +08:00

6.0 KiB

Raw Permalink Blame History

VPS-Commander（自托管私有化多节点运维管家）架构与开发设计规范

一、项目立项背景与目标

1.1 背景与痛点

早期方案过度依赖第三方 Relay，控制面与节点执行面边界不清。
单机开发网关通常存在项目目录沙箱，无法覆盖完整 Host-centric 运维。
AI Agent 需要的不只是 Shell，而是节点发现、文件、进程、Session、MCP 和审计的一体化控制面。

1.2 核心目标

100% 私有化控制面：Hub、Agent、SQLite 与反向代理均由用户控制。
Host-centric 运维：Shell、文件、进程、Session、远程 MCP。
多节点统一调度：一个 Hub 管理多个 VPS，节点状态持久化。
AI 原生接入：HTTP、MCP、stdio、Web 管理面板。
安全闭环：认证、风险授权、资源限制、审计、可回滚发布。

二、总体架构设计

[ 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

2.1 控制通道

AI / MCP / HTTP 请求进入 Hub，由 Hub 完成认证、设备解析、风险判断和路由。

2.2 节点通道

Agent 主动通过 WSS 回连 Hub，负责设备注册、状态、能力协商及 RPC 请求/响应。

两条通道共享同一设备身份、策略和审计上下文，不允许出现 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 个工具：

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

call_agent_mcp 必须经过 MCP risk gate，不允许成为远程 Agent 的权限旁路。

当前远程 transport 为 legacy HTTP + SSE，本地客户端为 stdio；Streamable HTTP 属于后续演进。

七、项目工程结构与技术选型

语言：Go。
存储：SQLite。
HTTP：标准库。
Web：Go embed。
节点通信：WebSocket。

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。

升级必须执行：

backup；
clean build；
单节点灰度；
Hub restart recovery；
rolling Agent；
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 完整审计链。

6.0 KiB Raw Permalink Blame History Unescape Escape