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 接口与上报均读取同一份缓存，不会在每次请求时实时扫描系统。

更多内部流程见 架构与工作流程，构建测试流程见 开发流程。

运行流程

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）

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 示例：

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

指定发布版本：

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

Windows（PowerShell）

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

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

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

推荐目录布局

Linux

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

Windows

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

仓库提供示例配置：configs/example.json。

配置说明

JSON 配置文件

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

install / start 等命令不会自动创建配置文件，需事先准备好 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 命令

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. 安装文件

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. 注册并启用服务

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 形如：

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

3. 启动与查看状态

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. 停止与卸载

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）

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

3. 启动与查询

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

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

4. 卸载

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

内部会先 sc stop 再 sc delete。

前台运行与验收

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

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

健康检查

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

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

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

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

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

完整状态

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

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

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
• 架构与流程：docs/ARCHITECTURE.md
• 开发与构建：docs/DEVELOPMENT.md
• 架构与规范：AGENTS.md
• 示例配置：configs/example.json