yuyr
31ccb0b1b8
Reviewed-on: #26 Reviewed-by: xuxt <xuxt@zgclab.edu.cn> Reviewed-by: huhy <husteryezi@163.com> Reviewed-by: sundapeng <sundp@mail.zgclab.edu.cn>
4.3 KiB
Argus Agent 模块
Argus Agent 是一个轻量级 Python 进程，负责向 Argus Master 注册节点、汇报健康数据，并维护本地持久化信息。模块现以 PyInstaller 打包为独立可执行文件，便于在普通容器或虚机中直接运行。
构建可执行文件
cd src/agent
./scripts/build_binary.sh # 生成 dist/argus-agent
脚本默认会在 Docker 容器 (python:3.11-slim-bullseye) 内执行 PyInstaller，确保产物运行时兼容 glibc 2.31+（覆盖 2.35 环境）。构建流程注意事项：
- 每次构建前会清理
build/、dist/并在容器内重新创建虚拟环境。 - 需要使用内网 Python 镜像时，可通过
PIP_INDEX_URL、PIP_EXTRA_INDEX_URL、PIP_TRUSTED_HOST等环境变量传入，脚本会自动透传给容器。 - 如果宿主机无法运行 Docker，可设置
AGENT_BUILD_USE_DOCKER=0回退到本地构建；此时代码必须在 glibc ≤ 2.35 的机器上执行。
构建结束后脚本会在 build/compat_check/ 下解包关键动态库并输出最高 GLIBC_x.y 版本，便于快速核对兼容性。如果结果中缺少 libssl.so.3 / libcrypto.so.3，表示系统会在目标宿主机上使用本地 OpenSSL 库，无需额外处理。
例如：
strings build/compat_check/libpython*.so.1.0 | grep -Eo 'GLIBC_[0-9]+\.[0-9]+' | sort -Vu | tail -n1
如遇构建失败，常见原因是 Docker 不可用（请改用 AGENT_BUILD_USE_DOCKER=0）或无法访问 Python 包镜像（先设置上述镜像环境变量后重试）。
运行时配置
Agent 不再依赖配置文件；所有参数均由环境变量与主机名推导：
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
MASTER_ENDPOINT |
是 | N/A | Master 基础地址，可写 http://host:3000 或 host:3000（自动补全 http://）。 |
REPORT_INTERVAL_SECONDS |
否 | 60 |
状态上报间隔（秒）。必须为正整数。 |
AGENT_HOSTNAME |
否 | $(hostname) |
覆盖容器内主机名，便于测试或特殊命名需求。 |
AGENT_ENV |
否 | 来源于主机名 | 运行环境标识（如 dev、prod）。与 AGENT_USER、AGENT_INSTANCE 必须同时设置。 |
AGENT_USER |
否 | 来源于主机名 | 归属用户或团队标识。与 AGENT_ENV、AGENT_INSTANCE 必须同时设置。 |
AGENT_INSTANCE |
否 | 来源于主机名 | 实例编号或别名。与 AGENT_ENV、AGENT_USER 必须同时设置。 |
主机名与元数据的解析优先级：
- 若设置
AGENT_ENV/AGENT_USER/AGENT_INSTANCE且全部存在，则直接使用这些值。 - 否则检查历史
node.json（注册成功后由 Master 返回的信息），若包含env/user/instance则沿用。 - 若以上均不可用，则按历史约定从主机名解析
env-user-instance前缀。 - 如果仍无法得到完整结果，Agent 启动会失败并提示需要提供上述环境变量。
提示：在首次部署时需确保环境变量或主机名能够提供完整信息。完成注册后，Agent 会把 Master 返回的元数据写入
node.json，后续重启无需再次提供环境变量就能保持一致性。
派生路径：
- 节点信息：
/private/argus/agent/<hostname>/node.json - 子模块健康目录：
/private/argus/agent/<hostname>/health/
健康目录中的文件需遵循 <模块前缀>-*.json 命名（例如 log-fluentbit.json、metric-node-exporter.json），文件内容会原样并入上报的 health 字段。
日志与持久化
- Agent 会在成功注册、状态上报、异常重试等关键节点输出结构化日志，便于聚合分析。
node.json保存 Master 返回的最新节点对象，用于重启后继续使用既有节点 ID。
端到端测试
仓库内提供 Docker Compose 测试栈（master + ubuntu 容器）：
cd src/agent/tests
./scripts/00_e2e_test.sh
测试脚本会：
- 构建 master 镜像与 agent 可执行文件。
- 以
ubuntu:24.04启动 agent 容器，并通过环境变量注入MASTER_ENDPOINT、REPORT_INTERVAL_SECONDS。 - 验证注册、健康上报、nodes.json 生成、统计接口，以及“容器重启 + IP 变化”重注册流程。
- 清理
tests/private/与临时容器网络。
如需在真实环境部署，只需将 dist/argus-agent 连同健康目录挂载到目标主机，并按上表设置环境变量即可。