# 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 + 白名单）