argus/src/master/README.md

Argus Master 模块

Argus Master 是基于 Flask + SQLite 的节点管理服务，负责：

• 接收 agent 的注册与重注册请求，分配/校验节点 ID。
• 存储节点元数据、配置、健康状态，并根据上报时间计算在线状态。
• 输出仅包含在线节点的 nodes.json，供其他模块（如 metric）消费。
• 提供查询、配置更新、统计等 REST API。

构建与运行

cd src/master
./scripts/build_images.sh            # 生成 argus-master:dev 镜像

如需离线构建，先在有网环境运行准备脚本：

cd src/master
./scripts/prepare_offline_wheels.sh --pip-version 25.2  # 可选 --clean

脚本会把 requirements.txt 及 pip 指定版本全部下载到 offline_wheels/。随后将源码目录（含该子目录）与基础镜像一并拷贝到内网，执行：

cd src/master
./scripts/build_images.sh --offline --tag argus-master:dev

若内网缺少 python:3.11-slim，请提前在外网 docker save 后通过离线介质 docker load。

本仓库提供的端到端测试会使用 src/master/tests/docker-compose.yml 启动示例环境：

cd src/master/tests
./scripts/01_up_master.sh            # 构建镜像并启动容器，监听 http://localhost:31300

服务日志与数据默认写入 tests/private/argus/master/（或自定义的挂载目录）。

运行时环境变量

变量	默认值	说明
DB_PATH	/private/argus/master/db.sqlite3	SQLite 数据库存放路径。目录会在启动时自动创建。
METRIC_NODES_JSON_PATH	/private/argus/metric/prometheus/nodes.json	nodes.json 输出位置，仅包含在线节点。采用原子写入避免部分文件。
OFFLINE_THRESHOLD_SECONDS	180	若距离最近一次上报时间超过该值，调度器会将节点标记为 offline。
ONLINE_THRESHOLD_SECONDS	120	若最新上报时间距当前不超过该值，则标记为 online。范围处于两个阈值之间时保持原状态。
SCHEDULER_INTERVAL_SECONDS	30	调度器检查节点状态与刷新 nodes.json 的周期。
NODE_ID_PREFIX	A	新节点 ID 的前缀，实际 ID 形如 A1、A2。
AUTH_MODE	disabled	预留的认证开关，当前固定为禁用。

进程与监控

镜像内通过 supervisord 管理进程：

• master：执行 /usr/local/bin/start-master.sh，默认以 4 个 Gunicorn worker 监听 0.0.0.0:3000；可通过环境变量 GUNICORN_WORKERS、GUNICORN_BIND、GUNICORN_EXTRA_ARGS 调整。
• dns-monitor：轮询 /private/argus/etc/dns.conf，若发现变更则调用 /private/argus/etc/update-dns.sh，日志输出在 /var/log/supervisor/dns-monitor.log。

镜像构建阶段会安装 supervisor/net-tools/inetutils-ping/vim 等基础工具，并在运行前把 apt 源切换到内网镜像，方便容器内进一步运维。

REST API 详解

基础路径：/api/v1/master，全部返回 JSON。

1. GET /nodes

• 用途：获取所有节点的简要信息。
• 响应示例：

  [
    {"id": "A1", "name": "dev-user-inst-pod-0", "status": "online", "type": "agent", "version": "1.1.0"}
  ]
  

2. GET /nodes/{id}

• 用途：获取节点详情（包含配置、健康、持久化时间戳等）。
• 错误：404 表示节点不存在。

3. POST /nodes

• 用途：注册或重注册节点。
• 请求体：

  {
    "id": "A1",            // 可选，重注册时携带
    "name": "dev-user-inst-pod-0",
    "type": "agent",
    "version": "1.1.0",
    "meta_data": {
      "hostname": "dev-user-inst-pod-0",
      "ip": "10.0.0.10",
      "env": "dev",
      "user": "testuser",
      "instance": "testinst",
      "cpu_number": 4,
      "memory_in_bytes": 2147483648,
      "gpu_number": 0
    }
  }
  

• 成功返回：
  • 新节点：201 Created，返回完整节点对象。
  • 重注册：200 OK，返回更新后的节点对象。
• 错误情况：
  • 404 Not Found：携带的 ID 在 Master 中不存在。
  • 500 Internal Server Error：携带的 ID 与已有名称不匹配。
  • 400 Bad Request：请求体缺字段或类型不正确。

4. PUT /nodes/{id}/status

• 用途：Agent 上报状态。Master 记录 last_report（服务器时间）与 agent_last_report（上报内时间），并更新 health 字段。
• 请求体示例：

  {
    "timestamp": "2025-09-24T03:24:59Z",
    "health": {
      "log-fluentbit": {"status": "healthy"},
      "metric-node-exporter": {"status": "healthy"}
    }
  }
  

• 响应：200 OK，返回最新节点对象。404 表示节点不存在。

5. PUT /nodes/{id}/config

• 用途：局部更新节点配置与标签。
• 请求体示例：

  {
    "config": {"log_level": "debug"},
    "label": ["gpu", "exp001"]
  }
  

• 说明：字段可任选其一；未提供的配置保持原值。更新标签会触发 nodes.json 重新生成。
• 错误：404 表示节点不存在；400 表示请求体不合法。

6. GET /nodes/statistics

• 用途：统计节点总数及按状态分布。
• 响应示例：

  {
    "total": 2,
    "status_statistics": [
      {"status": "online", "count": 1},
      {"status": "offline", "count": 1}
    ]
  }
  

7. 健康探针

• GET /healthz：进程存活检查。
• GET /readyz：数据库可用性检查（会尝试访问 DB_PATH）。

如需验证离线镜像，可使用自动化脚本：

cd src/master/tests
./scripts/00_e2e_test_offline.sh    # 构建离线镜像并执行完整 E2E

端到端测试场景

执行 src/master/tests/scripts/00_e2e_test.sh 会串联以下用例（脚本 01–10）：

1. 01_up_master：构建镜像、启动容器、初始化目录与卷。
2. 02_verify_ready_and_nodes_json：轮询 /readyz，校验初始 nodes.json 为 []。
3. 03_register_via_curl：模拟 agent 注册，保存返回的节点 ID，并确认节点出现在列表接口中。
4. 04_reregister_and_error_cases：覆盖重注册成功、携带未知 ID 的 404、ID/名称不匹配触发 500 等场景。
5. 05_status_report_via_curl：上报健康信息并验证状态自动从 initialized→online→offline→online 的转换。
6. 06_config_update_and_nodes_json：更新配置/标签，检查 nodes.json 中的标签同步，并确保离线节点不会出现在文件里。
7. 07_stats_single_node：等待节点掉线，验证统计接口与 nodes.json 为空列表。
8. 08_multi_node_stats：注册第二节点，使一在线一离线，校验统计聚合和 nodes.json 仅包含在线节点。
9. 09_restart_persistence：重启 master 容器，确认节点数据、统计结果与 nodes.json 在持久化目录中保持不变。
10. 10_down：停止并清理容器、网络与临时目录。

相关持久化文件

• SQLite：默认位于 DB_PATH，包含 nodes 与 kv 两张表。
• nodes.json：由调度器周期生成，仅保留状态为 online 的节点信息。
• 测试用例中的 tests/private/、tests/tmp/ 会随脚本自动清理，避免污染后续运行。

如需在生产环境运行，可将镜像推送到私有仓库，或参考测试 Compose 配置自行部署；只需确保上述环境变量在容器内正确设置即可。