docs: restore established documentation format

deploy/README.md

@@ -1,52 +1,196 @@
-# VPS-Commander 生产部署与运维
+# VPS-Commander 部署与运维指南
 
-> 基线：2026-10-02
+本文档介绍 VPS-Commander 当前生产环境部署架构、凭据规范、Agent 接入、升级与回滚流程。
 
-## 1. 拓扑
-Internet → TLS Reverse Proxy → vpstool.kory.kdns.fr → 127.0.0.1:9521 → Hub。
-Hub → Local Executor 或 Agent WSS。
-Hub 不直接公网监听；Agent 不需要公网入站管理端口。
+---
 
-## 2. Hub
-binary：/opt/vps-commander/vps-commander-hub
-env：/etc/vps-commander/hub.env
-db：/opt/vps-commander/data/commander.db
-systemd：vps-commander-hub.service
-listen：127.0.0.1:9521
+## 一、系统架构与端口规划
 
-## 3. Agent
-binary：/opt/vps-commander/vps-commander-agent
-env：/etc/vps-commander/agent.env
-必须包含 VPS_COMMANDER_HUB_WS_URL、VPS_COMMANDER_AGENT_NAME、VPS_COMMANDER_AGENT_TOKEN。
-env 文件必须 0600。
+- **Hub 服务端**：监听 `127.0.0.1:9521`，不直接暴露公网。
+- **反向代理**：公网 HTTPS/WSS 入口为 `https://vpstool.kory.kdns.fr`。
+- **Agent 客户端**：通过 `wss://vpstool.kory.kdns.fr/agent/ws` 主动回连 Hub。
 
-## 4. Credential
-每个 Agent 使用独立 token；Hub SQLite 只保存 token hash。
-生产不依赖 Cluster Secret fallback。
-v2.0 代码仍兼容旧 -token 参数；v2.1 要求 secret 不进入 argv/cmdline。
+反代必须支持：
+- WebSocket Upgrade；
+- `/agent/ws`；
+- `/mcp/*`；
+- `/api/v1/*`；
+- `/panel/*`；
+- `/.well-known/*`；
+- `/oauth/*`。
 
-## 5. Reverse Proxy
-必须支持 HTTPS、WebSocket Upgrade、/agent/ws、/mcp/*、/api/v1/*、/panel/*、/.well-known/*、/oauth/*。
+---
 
-## 6. Clean Release
-禁止 dirty tree build。
-git status --short；go test ./...；go test -race ./...；git diff --check；make clean；make linux-amd64；make linux-arm64。
-发布证据必须包含 vcs.modified=false 和 vcs.revision=<release commit>。
+## 二、凭据安全规范（强制要求）
 
-## 7. Rolling
-backup → Hub install/restart → Agent recovery → single-node gray → rolling Agent → MCP smoke → audit → acceptance。
-任何断联或授权异常都停止。
+### 2.1 Hub 凭据
+Hub 使用：
+- `VPS_COMMANDER_API_KEY`；
+- `VPS_COMMANDER_WEB_PASSWORD`。
 
-## 8. 日常检查
+生产环境不再依赖 `VPS_COMMANDER_CLUSTER_SECRET` 作为 Agent 身份 fallback。
+
+### 2.2 Agent 凭据
+每台 Agent 使用独立：
+`VPS_COMMANDER_AGENT_TOKEN`。
+
+Hub SQLite 仅保存 Credential Hash。
+
+### 2.3 文件权限
+```bash
+chmod 0600 /etc/vps-commander/hub.env
+chmod 0600 /etc/vps-commander/agent.env
+```
+
+### 2.4 v2.1 安全要求
+当前 v2.0 代码仍兼容旧的 `-token` 参数；下一版本要求 Secret 不出现在 argv / `/proc/*/cmdline`，优先使用 systemd EnvironmentFile / LoadCredential。
+
+---
+
+## 三、Hub 服务端部署步骤
+
+### 3.1 编译
+```bash
+cd /root/.openclaw/workspace/vps-commander
+go test ./...
+go test -race ./...
+git diff --check
+make clean
+make linux-amd64
+```
+
+发布前必须确认：
+```text
+vcs.modified=false
+vcs.revision=<release commit>
+```
+
+### 3.2 安装
+```bash
+install -d -m 0750 /opt/vps-commander/data /etc/vps-commander
+install -m 0755 bin/vps-commander-hub-linux-amd64 /opt/vps-commander/vps-commander-hub
+```
+
+### 3.3 配置
+```bash
+cat << 'ENV' > /etc/vps-commander/hub.env
+VPS_COMMANDER_API_KEY=your_secure_api_key
+VPS_COMMANDER_WEB_PASSWORD=your_web_password
+ENV
+chmod 0600 /etc/vps-commander/hub.env
+```
+
+### 3.4 Systemd
+```ini
+[Service]
+EnvironmentFile=-/etc/vps-commander/hub.env
+ExecStart=/opt/vps-commander/vps-commander-hub -addr 127.0.0.1:9521 -db /opt/vps-commander/data/commander.db
+Restart=always
+RestartSec=3s
+```
+
+### 3.5 启动
+```bash
+systemctl daemon-reload
+systemctl enable --now vps-commander-hub
+systemctl status vps-commander-hub
+```
+
+---
+
+## 四、远程 Agent 节点部署步骤
+
+### 4.1 安装二进制
+```bash
+install -d -m 0750 /etc/vps-commander /opt/vps-commander
+install -m 0755 vps-commander-agent-linux-amd64 /opt/vps-commander/vps-commander-agent
+```
+
+### 4.2 配置
+```bash
+cat << 'ENV' > /etc/vps-commander/agent.env
+VPS_COMMANDER_HUB_WS_URL=wss://vpstool.kory.kdns.fr/agent/ws
+VPS_COMMANDER_AGENT_NAME=vps-node-01
+VPS_COMMANDER_AGENT_TOKEN=<per-device-token>
+ENV
+chmod 0600 /etc/vps-commander/agent.env
+```
+
+### 4.3 Systemd
+```ini
+[Service]
+EnvironmentFile=-/etc/vps-commander/agent.env
+ExecStart=/opt/vps-commander/vps-commander-agent -hub ${VPS_COMMANDER_HUB_WS_URL} -name ${VPS_COMMANDER_AGENT_NAME}
+Restart=always
+RestartSec=3s
+```
+
+当前 v2.0 生产迁移阶段可兼容显式 token；v2.1 发布后必须改为不出现在 ExecStart 的方式。
+
+### 4.4 启动
+```bash
+systemctl daemon-reload
+systemctl enable --now vps-commander-agent
+systemctl status vps-commander-agent
+```
+
+Agent 启动后主动连接 Hub，并在设备列表中显示为 `online`。
+
+---
+
+## 五、控制面板与 MCP 使用
+
+### 5.1 管理面板
+`https://vpstool.kory.kdns.fr/panel/login`
+
+面板包含设备状态、安全策略、操作控制、审计和相关管理功能。
+
+### 5.2 MCP
+远程入口：
+`https://vpstool.kory.kdns.fr/mcp/sse`
+
+本地 stdio 使用 `vps-commander-mcp-stdio`。
+
+当前共 11 个 MCP tools，详见 `docs/MCP_INTEGRATION.md`。
+
+---
+
+## 六、生产升级流程
+
+```text
+Backup
+  ↓
+Clean Build
+  ↓
+Single-node Gray Release
+  ↓
+Hub Restart Recovery
+  ↓
+Rolling Agent
+  ↓
+MCP / Security / Audit Smoke Test
+  ↓
+Full Acceptance
+```
+
+任一节点断联、权限绕过、Credential 泄露或协议不兼容，立即停止发布并回滚。
+
+---
+
+## 七、日常运维检查
+
+```bash
 systemctl status vps-commander-hub
 journalctl -u vps-commander-hub -n 100
 curl -fsS http://127.0.0.1:9521/healthz
-/api/v1/devices、Web Panel、MCP list_devices。
+```
 
-## 9. 当前生产审计
-2026-10-02 Bug Hunt 发现生产 Hub/Agent 曾 vcs.modified=true。
-这说明现场二进制不能直接视为 HEAD 的可复现产物；下一次发布必须 clean rebuild 并重新部署。
+集群可通过 Web Panel、`/api/v1/devices` 或 MCP `list_devices` 检查。
 
-## 10. 回滚
-保留 Hub/Agent binary、systemd env、commander.db backup、release commit。
-协议不兼容时先恢复 Hub，再滚动恢复 Agent。
+---
+
+## 八、当前生产审计提示
+
+2026-10-02 审计发现生产 Hub / Agent 曾由 `vcs.modified=true` 的工作树构建。
+因此生产现场二进制不能直接视为当前 HEAD 的可复现产物。
+下一次正式发布必须 clean rebuild，并重新部署与验证。