124 lines
3.1 KiB
Markdown
124 lines
3.1 KiB
Markdown
# 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 已完成能力。
|
||
|