# 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)` | 覆盖容器内主机名，便于测试或特殊命名需求。 |
| `AGENT_ENV` | 否 | 来源于主机名 | 运行环境标识（如 `dev`、`prod`）。与 `AGENT_USER`、`AGENT_INSTANCE` 必须同时设置。 |
| `AGENT_USER` | 否 | 来源于主机名 | 归属用户或团队标识。与 `AGENT_ENV`、`AGENT_INSTANCE` 必须同时设置。 |
| `AGENT_INSTANCE` | 否 | 来源于主机名 | 实例编号或别名。与 `AGENT_ENV`、`AGENT_USER` 必须同时设置。 |

主机名与元数据的解析优先级：

1. 若设置 `AGENT_ENV` / `AGENT_USER` / `AGENT_INSTANCE` 且全部存在，则直接使用这些值。
2. 否则检查历史 `node.json`（注册成功后由 Master 返回的信息），若包含 `env` / `user` / `instance` 则沿用。
3. 若以上均不可用，则按历史约定从主机名解析 `env-user-instance` 前缀。
4. 如果仍无法得到完整结果，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 容器）：

```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` 连同健康目录挂载到目标主机，并按上表设置环境变量即可。
