From 583b27fb5c463e5a78470b94d2676d5e4273a907 Mon Sep 17 00:00:00 2001 From: kory Date: Fri, 2 Oct 2026 14:07:11 +0800 Subject: [PATCH] fix: expose write_file and document one-click operations --- README.md | 22 ++++++++++++ deploy/README.md | 78 +++++++++++++++++++++++++++++++--------- deploy/install.sh | 23 +++++------- docs/MCP_INTEGRATION.md | 26 +++++++++++++- internal/mcp/mcp.go | 1 + internal/mcp/mcp_test.go | 17 +++++++++ 6 files changed, 135 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 00752b9..91b2f1e 100644 --- a/README.md +++ b/README.md @@ -177,6 +177,28 @@ Agent 只主动连接 Hub，不需要公网入站端口。 --- +## 🚀 一键安装与升级 + +### 一键安装 + +```bash +curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/install.sh | sudo bash +``` + +安装脚本自动识别 `amd64/arm64` 并进入 Hub / Agent 安装流程。 + +### 一键升级 Agent + +```bash +curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/upgrade-agent.sh | sudo bash +``` + +升级脚本下载目标 Release、校验文件大小、备份旧版本并在启动失败时自动回滚。 + +生产环境的 Agent 凭据以独立设备凭据为准；不要将 Cluster Secret 作为长期生产凭据重新启用。 + +--- + ## 📄 文档索引 - [文档基线与全局索引](docs/DOCUMENTATION_BASELINE_20261002.md) diff --git a/deploy/README.md b/deploy/README.md index 0303957..1ec7b44 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -47,9 +47,53 @@ chmod 0600 /etc/vps-commander/agent.env --- -## 三、Hub 服务端部署步骤 +## 三、一键安装与升级 -### 3.1 编译 +### 3.1 一键安装 + +```bash +curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/install.sh | sudo bash +``` + +脚本自动识别 `amd64/arm64`，并进入 Hub / Agent 安装流程。 + +- Hub：自动生成 API Key 与 Web 面板密码。 +- Agent：输入 Hub WSS 地址、节点名称和独立 Agent Token。 +- 生产环境不再要求 Cluster Secret 作为长期凭据。 + +### 3.2 一键升级 Agent + +```bash +curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/upgrade-agent.sh | sudo bash +``` + +升级流程： + +```text +下载 Release + ↓ +临时文件完整性检查 + ↓ +备份当前 Agent + ↓ +原子替换 + ↓ +systemd restart + ↓ +健康检查 + ├─ 成功 → 删除备份 + └─ 失败 → 自动恢复旧版本 +``` + +### 3.3 手工安装 + +如果需要固定版本、离线部署或灰度验证，再使用下面的手工安装流程。 + +--- + +## 四、Hub 服务端部署步骤 + +### 4.1 编译 ```bash cd /root/.openclaw/workspace/vps-commander go test ./... @@ -65,13 +109,13 @@ vcs.modified=false vcs.revision= ``` -### 3.2 安装 +### 4.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 配置 +### 4.3 配置 ```bash cat << 'ENV' > /etc/vps-commander/hub.env VPS_COMMANDER_API_KEY=your_secure_api_key @@ -80,7 +124,7 @@ ENV chmod 0600 /etc/vps-commander/hub.env ``` -### 3.4 Systemd +### 4.4 Systemd ```ini [Service] EnvironmentFile=-/etc/vps-commander/hub.env @@ -89,7 +133,7 @@ Restart=always RestartSec=3s ``` -### 3.5 启动 +### 4.5 启动 ```bash systemctl daemon-reload systemctl enable --now vps-commander-hub @@ -98,15 +142,15 @@ systemctl status vps-commander-hub --- -## 四、远程 Agent 节点部署步骤 +## 五、远程 Agent 节点部署步骤 -### 4.1 安装二进制 +### 5.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 配置 +### 5.2 配置 ```bash cat << 'ENV' > /etc/vps-commander/agent.env VPS_COMMANDER_HUB_WS_URL=wss://vpstool.kory.kdns.fr/agent/ws @@ -116,7 +160,7 @@ ENV chmod 0600 /etc/vps-commander/agent.env ``` -### 4.3 Systemd +### 5.3 Systemd ```ini [Service] EnvironmentFile=-/etc/vps-commander/agent.env @@ -127,7 +171,7 @@ RestartSec=3s 当前 v2.0 生产迁移阶段可兼容显式 token；v2.1 发布后必须改为不出现在 ExecStart 的方式。 -### 4.4 启动 +### 5.4 启动 ```bash systemctl daemon-reload systemctl enable --now vps-commander-agent @@ -138,14 +182,14 @@ Agent 启动后主动连接 Hub，并在设备列表中显示为 `online`。 --- -## 五、控制面板与 MCP 使用 +## 六、控制面板与 MCP 使用 -### 5.1 管理面板 +### 6.1 管理面板 `https://vpstool.kory.kdns.fr/panel/login` 面板包含设备状态、安全策略、操作控制、审计和相关管理功能。 -### 5.2 MCP +### 6.2 MCP 远程入口： `https://vpstool.kory.kdns.fr/mcp/sse` @@ -155,7 +199,7 @@ Agent 启动后主动连接 Hub，并在设备列表中显示为 `online`。 --- -## 六、生产升级流程 +## 七、生产升级流程 ```text Backup @@ -177,7 +221,7 @@ Full Acceptance --- -## 七、日常运维检查 +## 八、日常运维检查 ```bash systemctl status vps-commander-hub @@ -189,7 +233,7 @@ curl -fsS http://127.0.0.1:9521/healthz --- -## 八、当前生产审计提示 +## 九、当前生产审计提示 2026-10-02 审计发现生产 Hub / Agent 曾由 `vcs.modified=true` 的工作树构建。 因此生产现场二进制不能直接视为当前 HEAD 的可复现产物。 diff --git a/deploy/install.sh b/deploy/install.sh index 75726d9..7633fc1 100755 --- a/deploy/install.sh +++ b/deploy/install.sh @@ -72,15 +72,15 @@ install_agent() { read -rp "请输入本节点名称 (默认: ${DEFAULT_NAME}): " AGENT_NAME AGENT_NAME=${AGENT_NAME:-${DEFAULT_NAME}} - read -rp "请输入 Cluster Secret (集群通信密钥): " CLUSTER_SECRET - while [ -z "$CLUSTER_SECRET" ]; do - read -rp "Cluster Secret 不能为空，请重新输入: " CLUSTER_SECRET + read -rp "请输入 Agent 独立凭据 Token: " AGENT_TOKEN + while [ -z "$AGENT_TOKEN" ]; do + read -rp "Agent Token 不能为空，请重新输入: " AGENT_TOKEN done cat << ENV > "${CONF_DIR}/agent.env" VPS_COMMANDER_HUB_WS_URL=${HUB_WS} VPS_COMMANDER_AGENT_NAME=${AGENT_NAME} -VPS_COMMANDER_CLUSTER_SECRET=*** +VPS_COMMANDER_AGENT_TOKEN=${AGENT_TOKEN} ENV chmod 0600 "${CONF_DIR}/agent.env" @@ -133,23 +133,19 @@ install_hub() { read -rp "请输入监听端口 (默认 9521): " HUB_PORT HUB_PORT=${HUB_PORT:-9521} - GEN_API_KEY=*** -c 24 /dev/urandom | xxd -p) - GEN_SECRET=*** -c 24 /dev/urandom | xxd -p) + GEN_API_KEY=$(head -c 24 /dev/urandom | xxd -p) GEN_PASS=$(head -c 16 /dev/urandom | xxd -p) read -rp "请输入 API Key (默认随机生成): " API_KEY - API_KEY=*** - - read -rp "请输入 Cluster Secret (默认随机生成): " CLUSTER_SECRET - CLUSTER_SECRET=${CLUS…RET} + API_KEY=${API_KEY:-$GEN_API_KEY} read -rp "请输入 Web 管理面板密码 (默认随机生成): " WEB_PASS WEB_PASS=${WEB_PASS:-$GEN_PASS} cat << ENV > "${CONF_DIR}/hub.env" -VPS_COMMANDER_API_KEY=*** -VPS_COMMANDER_CLUSTER_SECRET=*** -VPS_COMMANDER_WEB_PASSWORD=*** +VPS_COMMANDER_API_KEY=${API_KEY} +VPS_COMMANDER_WEB_PASSWORD=${WEB_PASS} +ENV ENV chmod 0600 "${CONF_DIR}/hub.env" @@ -185,7 +181,6 @@ SVC echo -e "\n================== Hub 配置凭据 ==================" echo -e "监听地址: 127.0.0.1:${HUB_PORT}" echo -e "API Key: ${API_KEY}" - echo -e "Cluster Secret: ${CLUSTER_SECRET}" echo -e "Web 面板密码: ${WEB_PASS}" echo -e "==================================================\n" warn "请妥善保管上述凭据，反代请将域名反代至 127.0.0.1:${HUB_PORT}" diff --git a/docs/MCP_INTEGRATION.md b/docs/MCP_INTEGRATION.md index 4ae086a..e32335d 100644 --- a/docs/MCP_INTEGRATION.md +++ b/docs/MCP_INTEGRATION.md @@ -162,7 +162,31 @@ API Key 不应提交到 Git 仓库。 --- -## 七、Agent MCP +## 七、一键安装与升级 + +### 7.1 一键安装 + +仓库已经提供统一安装脚本，支持 Linux `amd64` 与 `arm64`，安装时自动识别架构并从 GitHub Release 获取对应二进制。 + +```bash +curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/install.sh | sudo bash +``` + +脚本会进入交互式安装流程，可选择 Hub 或 Agent。生产环境使用时，Agent 应使用独立设备凭据，不应重新启用全局 Shared Secret。 + +### 7.2 一键升级 Agent + +```bash +curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/upgrade-agent.sh | sudo bash +``` + +升级采用临时文件下载 → 基础完整性检查 → 旧二进制备份 → 原子替换 → systemd 重启 → 健康检查；启动失败时自动回滚旧版本。 + +> Hub 的生产升级建议继续采用滚动发布：先完成 Release 与构建校验，再替换 Hub，确认节点重新上线后再继续后续节点。避免把 Hub 升级做成无保护的“一键重启”。 + +--- + +## 八、Agent MCP Hub 可以发现远程 Agent 暴露的 MCP Service。 diff --git a/internal/mcp/mcp.go b/internal/mcp/mcp.go index 642f90c..fc1682a 100644 --- a/internal/mcp/mcp.go +++ b/internal/mcp/mcp.go @@ -286,6 +286,7 @@ func (s *Server) handleRequest(ctx context.Context, r *http.Request, req JSONRPC InputSchema: InputSchema{Type: "object", Properties: map[string]PropertyDef{"device": {Type: "string", Description: "目标节点名称"}, "path": {Type: "string", Description: "目标文件路径"}, "old_text": {Type: "string", Description: "必须唯一匹配的原文本块"}, "new_text": {Type: "string", Description: "替换后的文本块"}}, Required: []string{"path", "old_text", "new_text"}}, }, { + Name: "write_file", Description: "向指定受控节点创建或覆写文件", InputSchema: InputSchema{ Type: "object", diff --git a/internal/mcp/mcp_test.go b/internal/mcp/mcp_test.go index 84e187d..1a95473 100644 --- a/internal/mcp/mcp_test.go +++ b/internal/mcp/mcp_test.go @@ -82,6 +82,23 @@ func TestMCPInitializeAndListTools(t *testing.T) { if !ok || len(tools) != 11 { t.Fatalf("expected 11 tools, got %d", len(tools)) } + foundWriteFile := false + for _, raw := range tools { + tool, ok := raw.(map[string]any) + if !ok { + t.Fatalf("tool entry is not an object: %#v", raw) + } + name, _ := tool["name"].(string) + if name == "" { + t.Fatalf("tool entry has empty name: %#v", tool) + } + if name == "write_file" { + foundWriteFile = true + } + } + if !foundWriteFile { + t.Fatalf("write_file missing from tools/list") + } } func TestMCPCallTool(t *testing.T) {