v1.0.0 remote-host-agent: 机器B监控/控制轻量方案（HTTP上报+命令长轮询）

- collector.py: 机器A端 FastAPI 服务(16018)，token认证 + strict/open 命令白名单 + SQLite存储 - agent.sh: 机器B端轻量agent（仅bash+curl+base64，零安装），采集CPU/内存/磁盘/负载/开机时间 + 长轮询执行命令回传结果 - hostctl.py: 机器A端 CLI（status/hosts/run/history/commands） - host-agent.service: 机器B端 systemd 服务 - start.sh: collector 启停脚本
2026-08-19 19:08:23 +08:00
commit c877b25ff6
8 changed files with 928 additions and 0 deletions
@@ -0,0 +1,119 @@
+# 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 部署（本机）
+
+```bash
+cd works/remote-host-agent
+./start.sh          # 启动（端口 16018，首次自动生成 data/token.txt）
+./start.sh stop     # 停止
+```
+
+启动后查看 token：
+
+```bash
+cat data/token.txt
+```
+
+### 常用 CLI（hostctl.py）
+
+```bash
+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`：
+
+```bash
+SERVER="http://121.40.164.32:16018"
+TOKEN="<机器A data/token.txt 里的值>"
+HOST_NAME="web-server-01"    # 自定义主机标识
+INTERVAL=10
+```
+
+3. 方式一（前台测试）：
+
+```bash
+chmod +x agent.sh
+./agent.sh
+```
+
+4. 方式二（systemd 常驻，推荐）：
+
+```bash
+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 + 白名单）