docs(agent): 统一中文注释并补充部署文档
将代码与测试注释改为中文以符合仓库规范；新增中文部署指南、 示例配置，并完善构建脚本对 VERSION 注入的说明。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
codex
336
docs/DEPLOYMENT.md
Normal file
336
docs/DEPLOYMENT.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# MFD Monitor Agent 部署指南
|
||||
|
||||
本文档说明如何在 Linux 与 Windows 上编译、配置、安装并验收 MFD Monitor Agent。
|
||||
|
||||
## 概述
|
||||
|
||||
MFD Monitor Agent 是单二进制主机状态采集程序，具备以下能力：
|
||||
|
||||
- 后台周期采集主机状态并写入内存缓存
|
||||
- 本地 HTTP API：`GET /health`、`GET /status`（默认仅监听 `127.0.0.1:8080`）
|
||||
- 可选周期性向中心端 POST 与 `/status` 相同结构的 `HostStatus` JSON
|
||||
- CLI 管理服务生命周期：`run`、`install`、`uninstall`、`start`、`stop`、`version`
|
||||
|
||||
HTTP 接口与上报均读取同一份缓存，**不会在每次请求时实时扫描系统**。
|
||||
|
||||
## 环境要求
|
||||
|
||||
| 项目 | 要求 |
|
||||
|------|------|
|
||||
| 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 配置文件
|
||||
|
||||
所有字段均有安全默认值；未提供配置文件时也可仅依赖环境变量启动。
|
||||
|
||||
```json
|
||||
{
|
||||
"host_id": "host-a",
|
||||
"http": {
|
||||
"listen_address": "127.0.0.1:8080"
|
||||
},
|
||||
"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 监听地址 | `127.0.0.1:8080` |
|
||||
| `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 描述 | 见默认配置 |
|
||||
|
||||
**校验规则：** `report.enabled=true` 时必须设置 `report.endpoint`，否则 `config.Load` 失败。
|
||||
|
||||
时长字段使用 Go duration 字符串，例如 `"30s"`、`"1m"`。
|
||||
|
||||
### 环境变量覆盖
|
||||
|
||||
在 JSON 加载后，以下环境变量可覆盖对应配置（`Load("")` 时同样生效）：
|
||||
|
||||
| 环境变量 | 配置字段 |
|
||||
|----------|----------|
|
||||
| `MFD_AGENT_HOST_ID` | `host_id` |
|
||||
| `MFD_AGENT_LISTEN` | `http.listen_address` |
|
||||
| `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
|
||||
```
|
||||
|
||||
### 健康检查
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8080/health | 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 | jq '.agent, .host, .processes.status, .tcp_listeners.status'
|
||||
```
|
||||
|
||||
### 主动上报验收
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
- **默认仅本机监听**（`127.0.0.1:8080`），避免将进程列表、监听端口等敏感信息默认暴露到网络。
|
||||
- 若需远程拉取，应通过反向代理、mTLS 或防火墙限制来源，而非直接绑定 `0.0.0.0`（除非明确接受风险）。
|
||||
- 服务账户权限越高，采集越完整；生产环境应在「采集完整性」与「最小权限」之间权衡。
|
||||
- `/status` 响应体可能较大（进程多、监听多时），注意中心端与本地内存占用。
|
||||
|
||||
## 故障排查
|
||||
|
||||
| 现象 | 可能原因 | 处理建议 |
|
||||
|------|----------|----------|
|
||||
| 启动报错 `report endpoint is required` | 开启上报但未配置 endpoint | 设置 `report.endpoint` 或关闭 `report.enabled` |
|
||||
| `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)
|
||||
- 架构与规范：[AGENTS.md](../AGENTS.md)
|
||||
- 示例配置：[configs/example.json](../configs/example.json)
|
||||
Reference in New Issue
Block a user