mfd-monitor-agent/docs/DEPLOYMENT.md

# MFD Monitor Agent 部署指南

本文档说明如何在 Linux 与 Windows 上编译、配置、安装并验收 MFD Monitor Agent。

## 概述

MFD Monitor Agent 是单二进制主机状态采集程序，具备以下能力：

- 后台周期采集主机状态并写入内存缓存
- 本地 HTTP API：`GET /health?token=...`、`GET /status?token=...`（默认监听 `0.0.0.0:8080`，需配置 `http.token`）
- 可选周期性向中心端 POST 与 `/status` 相同结构的 `HostStatus` JSON
- CLI 管理服务生命周期：`run`、`install`、`uninstall`、`start`、`stop`、`version`

HTTP 接口与上报均读取同一份缓存，**不会在每次请求时实时扫描系统**。

更多内部流程见 [架构与工作流程](ARCHITECTURE.md)，构建测试流程见 [开发流程](DEVELOPMENT.md)。

## 运行流程

`agent run` 的运行链路如下：

1. 解析 `-config`；未指定时使用当前目录 `config.json`。
2. 配置不存在时自动生成默认配置与随机 `http.token`，文件权限为 `0600`。
3. 加载 JSON，并应用 `MFD_AGENT_*` 环境变量覆盖。
4. 启动 `snapshot.Cache.Run`，立即采集一次并按 `collect.interval` 周期刷新缓存。
5. 如果 `report.enabled=true`，启动主动上报循环。
6. 启动 HTTP API，默认监听 `0.0.0.0:8080`。
7. 收到退出信号后优雅关闭 HTTP server。

单轮采集使用 `collect.timeout` 作为整体超时。子采集器失败不会导致整份 `/status` 失败，而是记录到 `errors[]` 并将 `agent.snapshot_status` 标记为 `partial`。

## 环境要求

| 项目 | 要求 |
|------|------|
| Go | 1.22 及以上（见 `go.mod`） |
| Linux 服务化 | systemd |
| 安装权限 | Linux `install` 需 **root**；Windows `install` 需**管理员** |
| 运行账户 | 首版建议以高权限服务账户运行，以便采集完整进程列表与 TCP 监听→进程映射 |

> 非 Linux/Windows 平台可前台 `run`，但不支持 `install`/`start`/`stop` 服务命令。

## 编译与产物

### Linux / 交叉编译（bash）

```bash
cd /path/to/mfd-monitor-agent
./scripts/build-linux.sh
```

默认输出：`dist/agent-linux-amd64`。

常用环境变量：

| 变量 | 含义 | 默认值 |
|------|------|--------|
| `OUT_DIR` | 输出目录 | `dist/` |
| `VERSION` | 写入二进制的版本号 | `0.1.0` |
| `GOOS_TARGET` | 目标操作系统 | `linux` |
| `GOARCH_TARGET` | 目标架构 | `amd64` |
| `OUTPUT_NAME` | 输出文件名 | `agent-<GOOS>-<GOARCH>` |
| `CGO_ENABLED` | 是否启用 CGO | `0` |

交叉编译 Windows 示例：

```bash
GOOS_TARGET=windows GOARCH_TARGET=amd64 OUTPUT_NAME=agent-windows-amd64.exe ./scripts/build-linux.sh
```

指定发布版本：

```bash
VERSION=1.0.0 ./scripts/build-linux.sh
./dist/agent-linux-amd64 version
```

### Windows（PowerShell）

```powershell
cd C:\path\to\mfd-monitor-agent
.\scripts\build-windows.ps1
```

默认输出：`dist\agent-windows-amd64.exe`。

构建产物目录 `dist/` 已在 `.gitignore` 中忽略，不会提交到仓库。

## 推荐目录布局

### Linux

```text
/opt/mfd-monitor-agent/agent          # 可执行文件
/etc/mfd-monitor-agent/config.json    # 配置文件
```

### Windows

```text
C:\Program Files\MFD\agent\agent.exe
C:\ProgramData\MFD\config.json
```

仓库提供示例配置：[configs/example.json](../configs/example.json)。

## 配置说明

### JSON 配置文件

`agent run` 在未指定 `-config` 时使用当前工作目录下的 `config.json`；若文件不存在，会自动生成含随机 `http.token` 的默认配置（权限 `0600`）。

`install` / `start` 等命令不会自动创建配置文件，需事先准备好 JSON。

```json
{
  "host_id": "host-a",
  "http": {
    "listen_address": "0.0.0.0:8080",
    "token": "请替换为强随机值"
  },
  "collect": {
    "interval": "30s",
    "timeout": "10s"
  },
  "report": {
    "enabled": true,
    "endpoint": "http://center.example.internal/agent/status",
    "interval": "60s",
    "timeout": "5s"
  },
  "service": {
    "name": "mfd-monitor-agent",
    "display_name": "MFD Monitor Agent",
    "description": "采集主机状态并通过 HTTP 提供查询"
  }
}
```

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `host_id` | 机器标识；为空时采集器可回退为主机名 | `""` |
| `http.listen_address` | HTTP 监听地址 | `0.0.0.0:8080` |
| `http.token` | API 查询参数 `?token=` 鉴权密钥（必填） | 无（`run` 自动生成） |
| `collect.interval` | 采集周期 | `30s` |
| `collect.timeout` | 单次采集总超时 | `10s` |
| `report.enabled` | 是否启用主动上报 | `false` |
| `report.endpoint` | 中心端 POST URL | `""` |
| `report.interval` | 上报周期 | `60s` |
| `report.timeout` | 单次上报 HTTP 超时 | `5s` |
| `service.name` | 服务名（systemd unit / Windows 服务名） | `mfd-monitor-agent` |
| `service.display_name` | Windows 显示名称 | `MFD Monitor Agent` |
| `service.description` | systemd unit 描述 | 见默认配置 |

**校验规则：**

- `http.token` 不能为空，否则 `config.Load` 失败。
- `report.enabled=true` 时必须设置 `report.endpoint`，否则 `config.Load` 失败。

时长字段使用 Go duration 字符串，例如 `"30s"`、`"1m"`。

### 环境变量覆盖

在 JSON 加载后，以下环境变量可覆盖对应配置：

| 环境变量 | 配置字段 |
|----------|----------|
| `MFD_AGENT_HOST_ID` | `host_id` |
| `MFD_AGENT_LISTEN` | `http.listen_address` |
| `MFD_AGENT_TOKEN` | `http.token` |
| `MFD_AGENT_COLLECT_INTERVAL` | `collect.interval` |
| `MFD_AGENT_COLLECT_TIMEOUT` | `collect.timeout` |
| `MFD_AGENT_REPORT_ENABLED` | `report.enabled` |
| `MFD_AGENT_REPORT_ENDPOINT` | `report.endpoint` |
| `MFD_AGENT_REPORT_INTERVAL` | `report.interval` |
| `MFD_AGENT_REPORT_TIMEOUT` | `report.timeout` |

## CLI 命令

```bash
agent run [-config /path/to/config.json]
agent install [-config /path/to/config.json] [-exe /path/to/agent]
agent uninstall [-config /path/to/config.json]
agent start [-config /path/to/config.json]
agent stop [-config /path/to/config.json]
agent version
```

无参数时默认执行 `run`。

## Linux systemd 部署

### 1. 安装文件

```bash
sudo install -m 0755 dist/agent-linux-amd64 /opt/mfd-monitor-agent/agent
sudo install -m 0644 configs/example.json /etc/mfd-monitor-agent/config.json
# 按需编辑 host_id、report 等字段
sudo ${EDITOR:-vi} /etc/mfd-monitor-agent/config.json
```

### 2. 注册并启用服务

```bash
sudo /opt/mfd-monitor-agent/agent install \
  -config /etc/mfd-monitor-agent/config.json \
  -exe /opt/mfd-monitor-agent/agent
```

`install` 会：

1. 写入 `/etc/systemd/system/<service.name>.service`
2. 执行 `systemctl daemon-reload`
3. 执行 `systemctl enable <service.name>`

生成的 unit 中 `ExecStart` 形如：

```ini
ExecStart=/opt/mfd-monitor-agent/agent run -config /etc/mfd-monitor-agent/config.json
```

### 3. 启动与查看状态

```bash
sudo /opt/mfd-monitor-agent/agent start -config /etc/mfd-monitor-agent/config.json
# 或
sudo systemctl start mfd-monitor-agent

sudo systemctl status mfd-monitor-agent
sudo journalctl -u mfd-monitor-agent -f
```

### 4. 停止与卸载

```bash
sudo /opt/mfd-monitor-agent/agent stop -config /etc/mfd-monitor-agent/config.json
sudo /opt/mfd-monitor-agent/agent uninstall -config /etc/mfd-monitor-agent/config.json
```

`uninstall` 会 `disable --now` 服务、删除 unit 文件并 `daemon-reload`。

## Windows 服务部署

> 当前通过 `sc.exe` 注册 Windows 服务；`run` 为前台模式，**非** Go SCM 内嵌服务包装。服务启动后由 SCM 按 `binPath` 拉起 `agent run`。

### 1. 复制文件

将 `agent-windows-amd64.exe` 与 `config.json` 放到固定路径，例如：

- `C:\Program Files\MFD\agent\agent.exe`
- `C:\ProgramData\MFD\config.json`

### 2. 注册服务（管理员 PowerShell）

```powershell
cd "C:\Program Files\MFD\agent"
.\agent.exe install -config "C:\ProgramData\MFD\config.json" -exe "C:\Program Files\MFD\agent\agent.exe"
```

### 3. 启动与查询

```powershell
.\agent.exe start -config "C:\ProgramData\MFD\config.json"
sc.exe query mfd-monitor-agent
```

也可在「服务」管理器中启停。

### 4. 卸载

```powershell
.\agent.exe uninstall -config "C:\ProgramData\MFD\config.json"
```

内部会先 `sc stop` 再 `sc delete`。

## 前台运行与验收

开发或临时排查时可前台运行：

```bash
./agent run -config /etc/mfd-monitor-agent/config.json
```

### 健康检查

将 `YOUR_TOKEN` 替换为配置文件中的 `http.token`：

```bash
curl -s 'http://127.0.0.1:8080/health?token=YOUR_TOKEN' | jq .
```

首次采集完成前可能返回 `503` 且 `{"status":"starting"}`。就绪后示例：

```json
{
  "status": "ok",
  "version": "0.1.0",
  "snapshot_at": "2026-05-19T12:00:00Z",
  "snapshot_status": "ok"
}
```

`snapshot_status` 为 `partial` 表示部分子采集器失败，但接口仍返回 200。

### 完整状态

```bash
curl -s 'http://127.0.0.1:8080/status?token=YOUR_TOKEN' | jq '.agent, .host, .processes.status, .tcp_listeners.status'
```

浏览器调试示例：`http://<host>:8080/status?token=YOUR_TOKEN`

### 主动上报验收

1. 在配置中设置 `report.enabled=true` 与可达的 `report.endpoint`
2. 在中心端确认收到 POST，Body 为完整 `HostStatus` JSON
3. 上报失败仅记录日志并重试一次，**不会**导致 agent 进程退出或影响本地 HTTP

## 升级与回滚

### Linux

```bash
sudo systemctl stop mfd-monitor-agent
sudo install -m 0755 dist/agent-linux-amd64 /opt/mfd-monitor-agent/agent
sudo systemctl start mfd-monitor-agent
```

若 unit 中可执行路径未变，无需重新 `install`。

### Windows

```powershell
sc.exe stop mfd-monitor-agent
# 替换 agent.exe
sc.exe start mfd-monitor-agent
```

## 安全注意事项

- **默认监听所有网卡**（`0.0.0.0:8080`），`/health` 与 `/status` 均须通过查询参数 `?token=` 鉴权。
- Token 会出现在 URL 中，代理与访问日志可能记录完整 URL；生产环境建议使用 HTTPS 反向代理、防火墙限制来源，并定期轮换 token。
- 自动生成的 `config.json` 权限为 `0600`，请妥善保管其中的 `http.token`。
- 服务账户权限越高，采集越完整；生产环境应在「采集完整性」与「最小权限」之间权衡。
- `/status` 响应体可能较大（进程多、监听多时），注意中心端与本地内存占用。

## 故障排查

| 现象 | 可能原因 | 处理建议 |
|------|----------|----------|
| 启动报错 `http.token is required` | 配置中 token 为空 | 在 JSON 中设置 `http.token`，或使用 `agent run` 自动生成 |
| 启动报错 `report endpoint is required` | 开启上报但未配置 endpoint | 设置 `report.endpoint` 或关闭 `report.enabled` |
| HTTP `401 unauthorized` | 缺少或错误的 `?token=` | 使用配置文件中的 `http.token` |
| `install requires root` | Linux 非 root 执行 install | 使用 `sudo` |
| `service install is not implemented` | 非 Linux/Windows | 仅使用 `run` 前台模式 |
| `/health` 长期 `starting` | 首次采集未完成或采集卡住 | 检查 `collect.timeout`、系统负载与权限 |
| `snapshot_status: partial` | 部分采集器失败 | 查看 `/status` 中 `errors` 数组 |
| `processes.status: partial/error` | 权限不足或 /proc 部分不可读 | 以更高权限运行服务 |
| `tcp_listeners.status: partial` | 端口→进程映射不完整 | Linux 检查 `/proc/<pid>/fd` 可读性；Windows 检查权限 |
| 上报失败日志 | 网络、中心端 5xx、超时 | 检查 `report.endpoint` 与 `report.timeout`；失败会自动重试一次 |

## 相关文档

- 项目简介：[README.md](../README.md)
- 架构与流程：[docs/ARCHITECTURE.md](ARCHITECTURE.md)
- 开发与构建：[docs/DEVELOPMENT.md](DEVELOPMENT.md)
- 架构与规范：[AGENTS.md](../AGENTS.md)
- 示例配置：[configs/example.json](../configs/example.json)