remote-host-agent

大模型智能体（机器A，有固定 IP）查看/控制机器B（无固定 IP）状态的轻量方案。

方案A：HTTP 上报 + 命令队列长轮询。B 端只需 bash + curl（系统自带，零安装）。

机器B (无固定IP)                     机器A (121.40.164.32:16018)
┌───────────────────┐  HTTPS      ┌──────────────────────────┐
│ agent.sh (轻量)    │ ──────────→ │ collector.py (FastAPI)   │ ←── hostctl.py / 智能体
│ · 采集CPU/内存/磁盘 │ ←─────────   │ · /api/report 收指标      │
│ · 长轮询命令执行    │   命令+结果  │ · /api/poll 下发命令      │
└───────────────────┘             │ · /api/status 查状态      │
                                  └──────────────────────────┘

目录结构

remote-host-agent/
├── collector.py        机器A 端服务（FastAPI, 端口 16018）
├── start.sh            机器A 服务启停（PID 管理）
├── hostctl.py          机器A 端 CLI（智能体/人调用）
├── agent.sh            机器B 端轻量 agent（核心）
├── config.sh.example   机器B 配置模板（复制为 config.sh）
├── host-agent.service  机器B 端 systemd 服务
└── data/               token.txt + host_agent.db（自动生成，勿提交）

一、机器A 部署（本机）

cd works/remote-host-agent
./start.sh          # 启动（端口 16018，首次自动生成 data/token.txt）
./start.sh stop     # 停止

启动后查看 token：

cat data/token.txt

常用 CLI（hostctl.py）

python3 hostctl.py hosts                       # 列出所有主机+在线状态
python3 hostctl.py status <host>               # 查看单台主机实时状态
python3 hostctl.py run <host> "df -h" --wait   # 下发命令并等待结果
python3 hostctl.py run <host> "cat /proc/cpuinfo | head -20" --wait
python3 hostctl.py history <host> --limit 50   # 历史指标
python3 hostctl.py commands --host <host>      # 命令执行记录

API 一览

方法	路径	说明
POST	/api/report	B 端上报指标（host/cpu/mem/disk/load/uptime）
GET	/api/poll	B 端长轮询取命令（阻塞 ≤65s）
POST	/api/result	B 端回传执行结果（base64）
GET	/api/status?host=X	实时状态
GET	/api/hosts	主机列表
GET	/api/history?host=X	历史指标
POST	/api/command	下发命令 {host, cmd, timeout, note}
GET	/api/commands	命令记录
GET	/api/health / /api/config	健康/配置

所有 API 需 Authorization: Bearer <token>。

二、机器B 部署（零安装，就 2 个文件）

1. 将 agent.sh 和 config.sh（由 config.sh.example 复制）放到 B 端任意目录（如 /opt/host-agent/）

2. 配置 config.sh：

SERVER="http://121.40.164.32:16018"
TOKEN="<机器A data/token.txt 里的值>"
HOST_NAME="web-server-01"    # 自定义主机标识
INTERVAL=10

3. 方式一（前台测试）：

chmod +x agent.sh
./agent.sh

4. 方式二（systemd 常驻，推荐）：

cp host-agent.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now host-agent
journalctl -u host-agent -f   # 看日志

三、大模型智能体集成

机器A 上智能体（OpenClaw）直接调用 CLI 即可，无需改 agent 代码：

"查机器B的CPU和内存" → exec: python3 hostctl.py status web-server-01
"在机器B上跑一下 df -h" → exec: python3 hostctl.py run web-server-01 "df -h" --wait

四、安全设计

• Token 认证：所有 API 必须带 Authorization: Bearer <token>，token 在 A 端首次启动自动生成（32字节随机）
• 命令白名单：默认 HOST_AGENT_CMD_MODE=strict，只允许只读命令（df/free/top/ps/uptime/cat/ls/netstat 等），可用 HOST_AGENT_CMD_MODE=open 放开全部
• 超时保护：B 端 timeout 强制命令超时（默认 30s），防挂死
• 离线检测：A 端 3 分钟无心跳标记离线
• 审计：所有命令记录落库（hostctl.py commands 可查）

五、版本

• v1.0.0：方案A 落地（监控上报 + 命令控制 + CLI + systemd + 白名单）