hz4th_coder
c877b25ff6
- 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 启停脚本
120 lines
4.4 KiB
Markdown
120 lines
4.4 KiB
Markdown
# 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 + 白名单）
|