✨ feat(agent): 添加 token 鉴权和流程文档

* 默认监听调整为 0.0.0.0:8080，并要求查询参数 token * 支持首次 run 自动生成含随机 token 的配置文件 * 补充 HTTP 鉴权、配置校验和相关测试 * 完善代码注释，覆盖缓存、上报、服务和平台采集路径 * 新增架构与开发流程文档，补充一键构建脚本
2026-05-22 06:46:21 +00:00
parent 877e4cf41d
commit de3fd88948
19 changed files with 875 additions and 125 deletions
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -0,0 +1,127 @@
+# MFD Monitor Agent 开发流程
+
+本文档记录当前仓库的构建、测试和跨平台验证流程。
+
+## 本地环境
+
+- Go 版本见 [go.mod](../go.mod)
+- Linux 服务化验证需要 systemd
+- Windows 服务化验证需要管理员 PowerShell
+- 构建产物默认写入 `dist/`，该目录不提交到 Git
+
+## 测试命令
+
+运行全部单元测试：
+
+```bash
+go test ./...
+```
+
+按包运行：
+
+```bash
+go test ./internal/collector
+go test ./internal/httpapi
+go test ./internal/reporter
+go test ./internal/service
+go test ./internal/snapshot
+```
+
+Windows 编译与测试验证：
+
+```bash
+GOOS=windows GOARCH=amd64 go test ./...
+```
+
+## Linux 构建
+
+```bash
+./scripts/build-linux.sh
+```
+
+默认产物：
+
+```text
+dist/agent-linux-amd64
+```
+
+常用变量：
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `OUT_DIR` | 输出目录 | `dist` |
+| `VERSION` | 注入到 `cmd/agent.version` 的版本号 | `0.1.0` |
+| `GOOS_TARGET` | 目标系统 | `linux` |
+| `GOARCH_TARGET` | 目标架构 | `amd64` |
+| `OUTPUT_NAME` | 输出文件名 | `agent-<goos>-<goarch>` |
+| `CGO_ENABLED` | CGO 开关 | `0` |
+
+版本号注入示例：
+
+```bash
+VERSION=1.0.0 ./scripts/build-linux.sh
+./dist/agent-linux-amd64 version
+```
+
+## Windows 构建
+
+在 Windows PowerShell：
+
+```powershell
+.\scripts\build-windows.ps1
+```
+
+默认产物：
+
+```text
+dist\agent-windows-amd64.exe
+```
+
+从 Linux 交叉编译 Windows：
+
+```bash
+GOOS_TARGET=windows GOARCH_TARGET=amd64 OUTPUT_NAME=agent-windows-amd64.exe ./scripts/build-linux.sh
+```
+
+## 全平台构建
+
+仓库包含 `scripts/build-all.sh`，用于一次构建 Linux amd64 与 Windows amd64 产物：
+
+```bash
+./scripts/build-all.sh
+```
+
+建议发布前执行：
+
+```bash
+go test ./...
+GOOS=windows GOARCH=amd64 go test ./...
+./scripts/build-all.sh
+```
+
+## 开发验证重点
+
+变更采集逻辑时，重点验证：
+
+- 单个子采集器失败后 `agent.snapshot_status=partial`
+- `errors[]` 包含失败采集器名称和错误摘要
+- `processes.status` 与 `tcp_listeners.status` 正确反映 `ok`、`partial`、`error`
+- HTTP 请求只读取缓存，不触发实时采集
+- 上报载荷与 `/status` 的 `HostStatus` 结构一致
+- 上报失败不会影响本地 HTTP 服务
+
+变更服务逻辑时，重点验证：
+
+- Linux `install` 非 root 返回错误
+- systemd unit 的 `ExecStart` 保留 `run -config <path>`
+- Windows `sc.exe create` 的 `binPath` 包含 `run -config <path>`
+- `uninstall` 对已停止或不存在的服务尽力清理
+
+## 文档关系
+
+- [README.md](../README.md)：项目入口与快速命令
+- [DEPLOYMENT.md](DEPLOYMENT.md)：部署、验收、安全与排障
+- [ARCHITECTURE.md](ARCHITECTURE.md)：运行时架构和工作流程
+- [AGENTS.md](../AGENTS.md)：仓库规则与功能边界
+- [plan.md](../plan.md)：历史设计草案，当前行为以代码和 docs 文档为准
+