43 lines
2.2 KiB
Markdown
43 lines
2.2 KiB
Markdown
# VPS-Commander 开发与协议规范
|
||
|
||
## 1. 技术基线
|
||
Go + SQLite + net/http + WebSocket。
|
||
组件：cmd/hub、cmd/agent、cmd/mcp-stdio；internal/api、auth、cluster、executor、mcp、security、storage、web、notify、model。
|
||
|
||
## 2. Agent Protocol
|
||
Agent 主动连接 /agent/ws。
|
||
握手包含 protocol version、AgentVersion、capabilities、per-device credential。
|
||
Hub 依据 credential 建立 canonical device identity；device/name 只能作为路由参数。
|
||
|
||
## 3. 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*、/healthz、/openapi.json。
|
||
Panel 使用 /panel/*。
|
||
|
||
## 4. MCP
|
||
serverInfo version：1.2.0；protocolVersion：2024-11-05。
|
||
11 tools：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 当前为 legacy SSE：GET /mcp/sse + POST /mcp/message?sessionId=...；本地为 stdio。
|
||
|
||
## 5. MCP 授权
|
||
exec → High；read → Low；write/edit/create/move → Medium；call_agent_mcp → mcp；list_agent_mcp → read。
|
||
MCP adapter 与 direct Agent MCP 使用同一 Hub security model。
|
||
|
||
## 6. 认证
|
||
HTTP/MCP：Authorization: Bearer API_KEY。
|
||
禁止 ?token、?key、?api_key。
|
||
Agent：per-device credential；SQLite 只保存 hash；生产不依赖 Cluster Secret fallback。
|
||
Panel：浏览器只持有 Panel Session；Admin Token 在服务端 bridge。
|
||
|
||
## 7. 资源
|
||
ExecLimiter 32；SearchLimiter 8；Node.WriteMu；Node.OpMu。
|
||
Session：ring 2MB；total 8MB；hard TTL 30m；idle TTL 10m；cleanup。
|
||
|
||
## 8. 测试
|
||
go test ./...；go test -race ./...；git diff --check。
|
||
生产额外要求 clean tree、vcs.modified=false、revision 与 release commit 一致、单 Agent 灰度、Hub recovery、MCP smoke、security matrix。
|
||
|
||
## 9. v2.1
|
||
P0：EffectiveRisk fail-closed；Agent token 不进入 argv/cmdline。
|
||
P1：Principal/Operator、Session owner 强隔离、完整身份审计链。
|
||
v2.1 不改变 Low/Medium/High 语义，不恢复 Shared Secret。
|