119 lines
4.4 KiB
Markdown
119 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 + 白名单）
|