# Argus Master 模块

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

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

## 构建与运行

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

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

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

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

```bash
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` 启动示例环境：

```bash
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`
- **用途**：获取所有节点的简要信息。
- **响应示例**：
  ```json
  [
    {"id": "A1", "name": "dev-user-inst-pod-0", "status": "online", "type": "agent", "version": "1.1.0"}
  ]
  ```

### 2. `GET /nodes/{id}`
- **用途**：获取节点详情（包含配置、健康、持久化时间戳等）。
- **错误**：`404` 表示节点不存在。

### 3. `POST /nodes`
- **用途**：注册或重注册节点。
- **请求体**：
  ```json
  {
    "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` 字段。
- **请求体示例**：
  ```json
  {
    "timestamp": "2025-09-24T03:24:59Z",
    "health": {
      "log-fluentbit": {"status": "healthy"},
      "metric-node-exporter": {"status": "healthy"}
    }
  }
  ```
- **响应**：`200 OK`，返回最新节点对象。`404` 表示节点不存在。

### 5. `PUT /nodes/{id}/config`
- **用途**：局部更新节点配置与标签。
- **请求体示例**：
  ```json
  {
    "config": {"log_level": "debug"},
    "label": ["gpu", "exp001"]
  }
  ```
- **说明**：字段可任选其一；未提供的配置保持原值。更新标签会触发 `nodes.json` 重新生成。
- **错误**：`404` 表示节点不存在；`400` 表示请求体不合法。

### 6. `GET /nodes/statistics`
- **用途**：统计节点总数及按状态分布。
- **响应示例**：
  ```json
  {
    "total": 2,
    "status_statistics": [
      {"status": "online", "count": 1},
      {"status": "offline", "count": 1}
    ]
  }
  ```

### 7. 健康探针
- `GET /healthz`：进程存活检查。
- `GET /readyz`：数据库可用性检查（会尝试访问 `DB_PATH`）。


如需验证离线镜像，可使用自动化脚本：
```bash
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 配置自行部署；只需确保上述环境变量在容器内正确设置即可。