[#2] 优化README

2025-09-24 08:31:05 +00:00
parent fbe6def185
commit 2d56fed321
2 changed files with 159 additions and 44 deletions
--- a/src/master/README.md
+++ b/src/master/README.md
@@ -1,48 +1,149 @@
-# Argus Master Module
+# Argus Master 模块

-A lightweight Flask + SQLite service that manages Argus agent nodes. It exposes node registration, status updates, configuration management, statistics, and generates `nodes.json` for the metric module.
+Argus Master 是基于 Flask + SQLite 的节点管理服务，负责：

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

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

-Local run via Docker compose (test stack):
+本仓库提供的端到端测试会使用 `src/master/tests/docker-compose.yml` 启动示例环境：

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

-Service listens on port `3000` (`31300` when using the provided test compose). Key environment variables:
+服务日志与数据默认写入 `tests/private/argus/master/`（或自定义的挂载目录）。

- `DB_PATH` (default `/private/argus/master/db.sqlite3`)
- `METRIC_NODES_JSON_PATH` (default `/private/argus/metric/prometheus/nodes.json`)
- `OFFLINE_THRESHOLD_SECONDS`, `ONLINE_THRESHOLD_SECONDS`, `SCHEDULER_INTERVAL_SECONDS`
+## 运行时环境变量

-## REST API Summary
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `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` | 预留的认证开关，当前固定为禁用。 |

-Base path: `/api/v1/master`
+## REST API 详解

- `GET /nodes` — list node summaries
- `GET /nodes/{id}` — node detail
- `POST /nodes` — register/re-register
- `PUT /nodes/{id}/status` — status report (timestamp + health map)
- `PUT /nodes/{id}/config` — update config/labels (partial)
- `GET /nodes/statistics` — totals + grouped counts
- `GET /healthz`, `GET /readyz` — health checks
+基础路径：`/api/v1/master`，全部返回 JSON。

-`nodes.json` only contains nodes whose status is `online`.
+### 1. `GET /nodes`
+- **用途**：获取所有节点的简要信息。
+- **响应示例**：
+  ```json
+  [
+    {"id": "A1", "name": "dev-user-inst-pod-0", "status": "online", "type": "agent", "version": "1.1.0"}
+  ]
+  ```

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

-End-to-end tests are Docker based:
+### 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`：请求体缺字段或类型不正确。

-```bash
-cd src/master/tests
-./scripts/00_e2e_test.sh
-```
+### 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`）。
+
+## 端到端测试场景
+
+执行 `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 配置自行部署；只需确保上述环境变量在容器内正确设置即可。

-Scripts create temporary `private/` and `tmp/` directories under `tests/`; they are cleaned automatically by `06_down.sh`.