yuyr
1e5e91b193
Reviewed-on: #17 Reviewed-by: sundapeng <sundp@mail.zgclab.edu.cn> Reviewed-by: xuxt <xuxt@zgclab.edu.cn>
67 lines
3.2 KiB
Markdown
67 lines
3.2 KiB
Markdown
# Argus Agent 模块
|
||
|
||
Argus Agent 是一个轻量级 Python 进程，负责向 Argus Master 注册节点、汇报健康数据，并维护本地持久化信息。模块现以 PyInstaller 打包为独立可执行文件，便于在普通容器或虚机中直接运行。
|
||
|
||
## 构建可执行文件
|
||
|
||
```bash
|
||
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 库，无需额外处理。
|
||
|
||
例如：
|
||
|
||
```bash
|
||
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)` | 覆盖容器内主机名，便于测试或特殊命名需求。 |
|
||
|
||
派生路径：
|
||
|
||
- 节点信息：`/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 容器）：
|
||
|
||
```bash
|
||
cd src/agent/tests
|
||
./scripts/00_e2e_test.sh
|
||
```
|
||
|
||
测试脚本会：
|
||
|
||
1. 构建 master 镜像与 agent 可执行文件。
|
||
2. 以 `ubuntu:24.04` 启动 agent 容器，并通过环境变量注入 `MASTER_ENDPOINT`、`REPORT_INTERVAL_SECONDS`。
|
||
3. 验证注册、健康上报、nodes.json 生成、统计接口，以及“容器重启 + IP 变化”重注册流程。
|
||
4. 清理 `tests/private/` 与临时容器网络。
|
||
|
||
如需在真实环境部署，只需将 `dist/argus-agent` 连同健康目录挂载到目标主机，并按上表设置环境变量即可。
|