# VPS-Commander 双通道架构与安全整改——送审交接文档

**文档版本：** 2026-10-02 / Review Handoff v1  
**项目：** VPS-Commander v2.0  
**用途：** 提交外部审核，审核通过后作为生产上线前置依据

---

## 1. 本次交接目标

本次开发针对双通道架构重构及此前审核专家 A/B 提出的安全、并发、权限、会话和文件操作问题进行集中整改。

本文件只描述**当前代码实际完成状态**，不把尚未部署到生产的代码描述为“已上线”。

当前原则：

- 生产 Hub / Agent 在本轮整改过程中**没有重启**。
- 所有新增能力先在代码与测试环境完成验证。
- 生产切换采用分阶段、可回滚方式。
- 审核通过后，才进入生产上线阶段。

---

## 2. 当前生产保护状态

本轮整改期间确认生产进程仍保持运行，未执行 Hub/Agent 重启：

- Hub：`/opt/vps-commander/vps-commander-hub`
- Agent：`/opt/vps-commander/vps-commander-agent`

因此，本次代码整改本身没有主动造成生产节点失联。

**注意：** 当前生产进程运行的是现有部署版本，不等同于本工作树代码已经上线。

---

## 3. 审核问题整改总表

| 审核问题 | 当前状态 | 说明 |
|---|---|---|
| Security Snapshot 统一门禁 | PASS | API/MCP 等执行路径使用统一安全模式判断 |
| MCP 绕过安全门禁 | PASS | `exec/read/write/edit/mcp` 路径已接入门禁；Agent-MCP 直通已补齐 |
| 未知设备继承 GlobalRisk | PASS | 未注册/未知设备 fail-closed 为 `unknown` |
| Security Policy Version 回退 | PASS | Snapshot Publish 拒绝版本回退 |
| Admin 安全策略权限 | PASS | 安全策略修改要求独立 Admin Token |
| edit_block 原子写入 | PASS | 临时文件、fsync、原子 rename、权限保留 |
| edit_block 并发/生成冲突 | PASS* | 已增加提交前重新读取校验及进程内串行保护；可选 expected hash |
| Session Owner | PARTIAL / HARDENING | 当前 owner 绑定认证主体指纹；若所有调用者共享同一全局 token，无法天然区分操作者 |
| Session TTL | PASS | 30 分钟硬 TTL + 10 分钟 idle TTL，访问会刷新 LastAccess |
| Session 资源上限 | PASS | 单 Manager 会话/缓冲总量有限制 |
| WebSocket 并发写 | PASS | Node 写操作通过 WriteMu 串行化 |
| Agent 业务错误导致断链 | PASS | 业务错误返回错误消息，不主动关闭 WebSocket |
| Agent 能力声明 | PASS | Modern Agent 按 capability 校验；旧 Agent 保持兼容 |
| 设备级凭证 | IMPLEMENTED / NOT DEPLOYED | SQLite 已支持 per-device credential hash；未切换生产认证 |
| URL Query Token | PASS | Auth 不再接受 `?token/?key/?api_key` |
| 审计记录 | PASS | 关键安全拒绝、MCP 调用等路径具备审计 |
| 审计敏感信息治理 | HARDENING | 仍建议上线前进一步检查 command/error 的敏感字段脱敏 |
| 全局 exec/search 资源配额 | HARDENING | 已有 session/ring buffer 限制，但仍可进一步增加全局并发/搜索资源配额 |
| 生产部署验证 | PENDING | 必须在审核通过后分阶段执行 |

> `PASS*` 表示代码层已完成并通过测试；最终生产审核仍应覆盖真实文件系统与并发场景。

---

## 4. 已完成的核心安全机制

### 4.1 Security Snapshot

Hub 启动时加载安全策略 Snapshot。策略版本保存在 SQLite 中。

安全模式包括：

- `low`
- `medium`
- `high`
- `inherit`

工具动作通过固定 Registry 映射到风险等级，避免调用方自行声明风险等级。

### 4.2 Fail-Closed

对于未知、未注册或不在线的远程设备，不再默认继承 GlobalRisk。

此类设备的有效安全模式为 `unknown`，高风险执行因此被拒绝。

### 4.3 MCP 安全门禁

MCP 不再被视为绕过 Hub Security Snapshot 的旁路。

目前已经覆盖：

- `exec_command`
- `read_file`
- `write_file`
- `edit_block`
- `call_agent_mcp`
- `list_agent_mcp`

并增加了对应单元测试。

### 4.4 Admin Token

安全策略修改接口要求独立 Admin Token：

`X-Admin-Token`

启动时优先读取：

`VPS_COMMANDER_ADMIN_TOKEN`

同时保留旧 Web Password 作为兼容 fallback，方便后续迁移。

### 4.5 URL Token 禁用

API Auth 不再从 URL Query 中接受：

- `token`
- `key`
- `api_key`

统一使用 Authorization Bearer 认证路径。

---

## 5. 文件修改安全

`edit_block` 当前实现包含：

1. 唯一匹配检查
2. 初始内容 SHA-256 generation
3. 提交前重新读取
4. generation/hash 冲突检测
5. 进程内编辑串行化
6. 同目录临时文件
7. 写入后 fsync
8. atomic rename
9. 保留原文件权限
10. 目录同步

目标是避免“读取后文件被其他操作修改，随后旧内容覆盖新内容”的典型 lost-update 问题。

---

## 6. Session 安全

当前 Session 具备：

- Owner
- 30 分钟 hard TTL
- 10 分钟 idle TTL
- 访问刷新 `LastAccess`
- 最大输入 64 KiB
- 环形输出缓冲
- Manager 总缓冲/会话上限
- terminate / kill 按 Session 控制

Owner 校验失败或 Session 过期时，不允许继续操作。

### 已知边界

当前 Owner 来源仍然是 API 认证主体的 token fingerprint。在所有调用者共用同一个 API Token 的部署中，这个 fingerprint 无法区分不同人工操作者。

因此上线前如果要求强操作者隔离，应继续引入明确的 principal/operator identity。

---

## 7. WebSocket 稳定性

Agent 与 Hub 通信增加了写锁，避免多个 goroutine 同时向同一 WebSocket 写入。

Agent 业务请求错误不再直接导致 WebSocket 连接被关闭。

设备断线后：

- Node 保留在 Manager
- 状态变为 offline
- SQLite 保留设备记录
- pending request 收到 disconnect error
- 自动重连可以恢复 online 状态

---

## 8. 设备级凭证迁移

这是本轮新增的重要安全能力。

SQLite 新增：

`device_credentials`

数据库只保存 token 的 SHA-256 hash，不保存明文 token。

当前 WebSocket 握手逻辑：

```text
设备存在独立 credential
        |
        +--> 使用该设备 credential 校验

设备尚未配置 credential
        |
        +--> 暂时兼容 Cluster Secret
```

这样可以支持逐节点迁移，而不是一次性切换所有 Agent。

### 当前状态

**代码已经实现，但尚未在生产逐节点启用。**

这是有意保留的上线门禁，避免在没有审核和迁移计划的情况下直接造成 Agent 全部掉线。

---

## 9. 测试与验证结果

当前工作树已经完成：

```text
go test ./...                 PASS
go test -race ./...           PASS
go build ./cmd/hub            PASS
go build ./cmd/agent          PASS
go build ./cmd/mcp-stdio      PASS
git diff --check              PASS
```

并增加/验证了：

- MCP Security Snapshot 测试
- 未知设备 fail-closed 测试
- MCP Agent-MCP gate 测试
- MCP list-agent gate 测试
- Session idle authorization 测试
- Device credential hash/rotation 测试
- Cluster lifecycle acceptance 测试
- Race detector

---

## 10. 审核者重点检查项

建议审核者重点确认以下问题，而不是重复审查已经验证的普通功能：

### A. 设备身份

确认：

- device name 不能单独成为可信身份
- 已配置 credential 的设备必须使用对应 credential
- credential 不能跨设备复用
- revoked device 不能重新建立连接
- 迁移期间 legacy Cluster Secret 的边界是否可接受

### B. Session 操作者身份

确认：

- Owner 是否满足当前部署需要
- 是否需要进一步引入 operator/principal ID
- kill/terminate/input/output 是否全部经过 Owner 检查

### C. 审计

确认：

- command/error 是否可能写入密码、Token、Cookie、Authorization 等敏感内容
- MCP 参数是否需要脱敏
- 安全拒绝事件是否足够追踪

### D. 资源控制

确认：

- exec 并发数
- search 并发数
- 单文件读取大小
- 单 Agent MCP 请求并发
- WebSocket pending request 数量

是否满足生产部署规模。

### E. 上线安全

审核通过后必须采用：

**备份 → 单节点 → 健康检查 → 保持旧进程可回滚 → 再逐节点扩散**

而不是直接全量替换。

---

## 11. 上线前置条件

只有审核者确认以下事项后，才进入生产部署：

- [ ] 代码审核通过
- [ ] 明确 Session principal 要求
- [ ] 明确设备 credential 迁移方案
- [ ] 确认现有 Cluster Secret fallback 的过渡期限
- [ ] 确认审计脱敏要求
- [ ] 确认生产资源配额
- [ ] 确认 DB 备份/回滚方案

---

## 12. 推荐上线顺序

### Stage 0 — Preflight

- 备份 `commander.db`
- 记录当前 Hub/Agent PID、版本、配置
- 记录当前在线节点
- 保留当前生产 binary

### Stage 1 — Hub

先部署 Hub 新版本。

验证：

- `/panel`
- API Auth
- Security Snapshot
- MCP
- Device state
- WebSocket handshake

### Stage 2 — 单 Agent

选择非关键节点进行验证：

- 独立 credential
- online/offline
- exec
- read
- write
- edit_block
- MCP
- reconnect

### Stage 3 — 逐节点迁移

每次只迁移一个 Agent，并确认：

```text
connected
→ authenticated
→ heartbeat
→ command
→ MCP
→ disconnect
→ reconnect
```

全部正常后再处理下一节点。

### Stage 4 — Legacy Secret 收口

所有 Agent 完成 credential migration 后，再考虑关闭 shared Cluster Secret fallback。

**不能提前关闭。**

---

## 13. 审核结论请求

请审核者对本文件给出以下三类结论之一：

### A — APPROVED FOR DEPLOYMENT

允许进入生产上线阶段。

### B — APPROVED WITH CONDITIONS

允许进入上线准备，但指定条件必须在上线前完成。

### C — BLOCKED

存在必须修复的阻断性安全/架构问题。

如果选择 B 或 C，请明确指出：

1. 问题
2. 风险
3. 必须修改的代码/配置
4. 验证方法
5. 是否要求生产变更

---

## 14. 当前开发团队声明

截至本文件生成时：

- 本轮整改代码未直接替换生产二进制。
- 生产 Hub/Agent 未因本轮整改重启。
- 自动化测试与 race detector 已通过。
- 设备级 credential 已实现兼容迁移机制，但尚未执行生产迁移。
- 当前目标是先接受独立审核，再执行生产上线。

**因此，本文件是“送审版”，不是“生产上线完成报告”。**

## 11. 最终上线收口（2026-10-02）

本轮批准后的生产实施已完成：

- Hub 已部署最终版本并验证启动；共享 Cluster Secret fallback 已关闭。
- 5 个远程 Agent 均已配置独立设备凭证，数据库仅保存 SHA-256 hash。
- 5 个远程 Agent 均已滚动升级到最终 Agent 构建，且重新上线。
- `wjyhk / N3450 / hwhk / hwsg / m4-live-agent / qnvn` 六个节点全部 online。
- 六个节点均已通过实际执行请求验证控制链路可用。
- Hub 全局安全级别保持 `medium`；节点级策略保持 `high`，未通过降低全局策略绕过门禁。
- 审计写入增加敏感字段脱敏、换行清理和长度上限。
- Hub 增加 exec 32 并发槽、search 8 并发槽，防止高频资源请求拖垮主控。
- DC 工具池补齐：多文件读取、进程列表、目录创建、文件移动，并接入 Agent/Hub/MCP。
- Agent 仍保留协议兼容能力；设备级凭证优先，未配置设备不会再因为共享 Secret fallback 而自动获得认证。

最终验证：

```text
go test ./...       PASS
go test -race ./... PASS
git diff --check    PASS
```

最终生产 Agent SHA-256：
`1969456fb09004e4be5b05ba1bf30a0a19a6ed2d41236c2bccd391b2ad6bc362`

最终生产 Hub SHA-256：
`1cb2136cb5f108480f8cc4f59d432838812332d319ae84ff28f0a53fba68d3c5`

Shared Secret 已从 Hub 生产环境移除；现阶段生产认证权威为 per-device credential。