49 lines
2.8 KiB
Markdown
49 lines
2.8 KiB
Markdown
# 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。
|
||
|
||
## 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、本地执行。
|
||
|
||
## 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。
|
||
|
||
## 7. Policy Snapshot
|
||
SQLite 保存策略版本，Hub 使用内存 Snapshot 处理读路径。
|
||
version 单调递增；发布失败不替换旧 Snapshot；unknown device 不继承 GlobalRisk High。
|
||
v2.1 将彻底消除 EffectiveRisk 的 GlobalRisk fail-open fallback。
|
||
|
||
## 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、保留权限。
|
||
|
||
## 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 并回滚。
|