docs: synchronize architecture deployment and MCP documentation

2026-10-02 13:53:00 +08:00
parent b9f7197ec7
commit 71a596a556
16 changed files with 701 additions and 877 deletions
@@ -0,0 +1,123 @@
+# VPS-Commander 文档基线与现状索引
+
+> 基线日期：2026-10-02
+> 本文件是仓库文档的导航入口。历史审核记录保留原貌，不作为当前实现契约。
+
+## 当前定位
+
+VPS-Commander 是自托管的多节点 Linux 运维控制中枢。
+链路：AI/客户端 → Hub → Local Executor 或 Agent WebSocket → 目标主机。
+
+当前目标：
+- 多节点统一身份、路由与状态管理；
+- 文件、进程、Shell、MCP 运维能力；
+- 认证、三级风险授权与审计；
+- 可回滚、可持续升级的生产部署；
+- 面向 AI Agent 的 MCP 与 HTTP 接口。
+
+## 当前架构
+
+```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。
+
+## 当前安全模型
+
+- 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 已完成能力。
+