VPS-Commander 文档基线与现状索引

基线日期：2026-10-02 本文件是仓库文档的导航入口。历史审核记录保留原貌，不作为当前实现契约。

当前定位

VPS-Commander 是自托管的多节点 Linux 运维控制中枢。链路：AI/客户端 → Hub → Local Executor 或 Agent WebSocket → 目标主机。

当前目标：

多节点统一身份、路由与状态管理；
文件、进程、Shell、MCP 运维能力；
认证、三级风险授权与审计；
可回滚、可持续升级的生产部署；
面向 AI Agent 的 MCP 与 HTTP 接口。

当前架构

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。

当前安全模型

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 已关闭。

当前 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。

当前 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/*

文档分层

当前规范：

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

历史报告解释演进原因，不覆盖当前规范。

生产状态

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 已完成能力。

3.1 KiB Raw Blame History Unescape Escape