openclaw/vps-commander

Fork 0

Files

T

kory cc99022215

Release / Build & Release (push) Canceled after 0s

Details

docs: restore established documentation format

2026-10-02 14:01:14 +08:00

3.6 KiB

Raw Blame History

VPS-Commander 研发设计规范与协议说明

一、技术选型与工程原则

开发语言：Go。
存储：SQLite。
HTTP：标准库 net/http。
节点通信：WebSocket。
Web 前端：Go embed。

工程原则：

认证与授权分离。
Tool Risk 静态注册。
Device Policy 运行时解析。
默认 fail-closed。
Session 必须有 TTL 与资源上限。
生产二进制必须可追溯。
发布必须可回滚。

二、项目工程结构

vps-commander/
├── cmd/
│   ├── hub/
│   ├── agent/
│   └── mcp-stdio/
├── internal/
│   ├── api/
│   ├── auth/
│   ├── cluster/
│   ├── executor/
│   ├── mcp/
│   ├── model/
│   ├── notify/
│   ├── security/
│   ├── storage/
│   └── web/
├── docs/
├── deploy/
└── openapi.json

三、Agent WebSocket 协议

Agent 主动连接：/agent/ws。

握手包含：

Protocol Version。
AgentVersion。
Capabilities。
Per-device Credential。

Hub 根据 Credential 建立 Canonical Device Identity。客户端请求中的 device/name 只能用于路由，不能作为授权身份来源。

四、HTTP API 规范

路径	方法	功能
`/api/v1/devices`	GET	设备列表
`/api/v1/exec`	POST	Shell
`/api/v1/file/read`	POST	文件读取
`/api/v1/file/list`	POST	目录列表
`/api/v1/file/info`	POST	文件信息
`/api/v1/file/search`	POST	文件搜索
`/api/v1/process/session`	POST	Session
`/api/v1/file/write`	POST	文件写入
`/api/v1/devices/file/edit_block`	POST	原子编辑
`/api/v1/mcp/*`	GET/POST/DELETE	MCP
`/api/v1/security/*`	GET/POST	安全策略
`/api/v1/notifications/webhook*`	GET/POST/DELETE	Webhook
`/healthz`	GET	健康检查
`/openapi.json`	GET	OpenAPI

五、MCP 协议规范

Server version：1.2.0。 Protocol Version：2024-11-05。

当前工具共 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。

远程 transport：legacy HTTP + SSE。本地 transport：stdio。未来 transport：Streamable HTTP。

六、认证与安全规范

6.1 HTTP / MCP

Authorization: Bearer <API_KEY>

禁止：

?token=
?key=
?api_key=

6.2 Agent

每设备独立 Credential。
SQLite 只保存 Hash。
生产关闭 Shared Secret fallback。

6.3 Panel

Panel Session 在服务端认证。 Admin Token 只在 Panel → 内部 API bridge 中使用，不发送给浏览器。

七、并发与资源限制

项目	限制
Exec	32 并发
Search	8 并发
Session Ring	2MB
Session 总 Buffer	8MB
Session Hard TTL	30m
Session Idle TTL	10m
WS Write	Node.WriteMu
Medium/High	Node.OpMu

八、测试与发布规范

8.1 提交前

go test ./...
go test -race ./...
git diff --check

8.2 发布前

clean Git tree。
vcs.modified=false。
revision 与 release commit 一致。
单 Agent 灰度。
Hub restart recovery。
MCP smoke test。
security deny/allow matrix。

九、v2.1 研发计划

9.1 P0

EffectiveRisk 完全 fail-closed。
Credential 不进入 argv / cmdline。

9.2 P1

Principal / Operator Identity。
Session Owner 强隔离。
完整身份审计链。

v2.1 不改变 Low / Medium / High 语义，不恢复 Shared Secret。

3.6 KiB Raw Blame History Unescape Escape