增加rtr一些必要的api接口

2026-06-23 17:04:00 +08:00
parent 303bdffd97
commit b105b3b7d0
41 changed files with 3078 additions and 1735 deletions
--- a/docs/rtr-admin-api.md
+++ b/docs/rtr-admin-api.md
@@ -0,0 +1,313 @@
+# RTR Admin API
+
+本文档描述 RTR server 当前提供的 HTTP 管理接口。
+
+## 启用方式
+
+Admin API 默认关闭。设置 `RPKI_RTR_ADMIN_ADDR` 后启用：
+
+```env
+RPKI_RTR_ADMIN_ADDR=127.0.0.1:8323
+RPKI_RTR_ADMIN_TOKEN=change-me
+```
+
+如果在 Docker 中需要从宿主机访问，容器内建议监听：
+
+```env
+RPKI_RTR_ADMIN_ADDR=0.0.0.0:8323
+RPKI_RTR_ADMIN_TOKEN=change-me
+```
+
+并在 compose 中映射端口：
+
+```yaml
+ports:
+  - "8323:8323"
+```
+
+安全规则：
+
+- `RPKI_RTR_ADMIN_ADDR` 为空时，不启动 Admin API。
+- 非 loopback 地址，例如 `0.0.0.0:8323`，必须配置 `RPKI_RTR_ADMIN_TOKEN`，否则 admin server 会拒绝启动。
+- 设置 token 后，请求必须带 `Authorization: Bearer <token>`。
+
+## 通用 Headers
+
+```http
+Authorization: Bearer change-me
+Content-Type: application/json
+```
+
+GET 请求不需要 `Content-Type`。
+
+## GET /admin/rtr/health
+
+用于检查 Admin API 是否可达，以及当前启用了哪些管理能力。
+
+```bash
+curl http://127.0.0.1:8323/admin/rtr/health \
+  -H "Authorization: Bearer change-me"
+```
+
+响应示例：
+
+```json
+{
+  "status": "ok",
+  "config_api": true,
+  "source_reload_api": true,
+  "slurm_api": true,
+  "logs_api": true
+}
+```
+
+## GET /admin/rtr/logs/tail
+
+实时读取 RTR 服务日志，效果类似 `tail -f`。默认读取 stdout 日志，先返回最近 200 行，然后持续输出新增内容。
+
+```bash
+curl -N "http://127.0.0.1:8323/admin/rtr/logs/tail?stream=stdout&lines=200&follow=true" \
+  -H "Authorization: Bearer change-me"
+```
+
+Query 参数：
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `stream` | `stdout` | 可选 `stdout` 或 `stderr`。 |
+| `lines` | `200` | 首次返回的历史行数，范围会限制在 `1..=5000`。 |
+| `follow` | `true` | `true` 时保持连接并持续输出新增日志；`false` 时只返回当前 tail 内容。 |
+
+日志文件路径按容器 entrypoint 的规则解析：
+
+- 目录：`RPKI_RTR_LOG_DIR`，默认 `/app/logs`。
+- 文件名前缀：`RPKI_RTR_LOG_NAME`，未设置时使用 `HOSTNAME`，再未设置时为 `rpki-rtr`。
+- stdout 文件：`<name>.stdout.log`。
+- stderr 文件：`<name>.stderr.log`。
+
+## GET /admin/rtr/config
+
+查询当前运行中的 runtime 配置。
+
+```bash
+curl http://127.0.0.1:8323/admin/rtr/config \
+  -H "Authorization: Bearer change-me"
+```
+
+响应示例：
+
+```json
+{
+  "status": "ok",
+  "config": {
+    "max_delta": 10,
+    "prune_delta_by_snapshot_size": true,
+    "source_refresh_interval_seconds": 300,
+    "runtime_report_interval_seconds": 300,
+    "report_history_limit": 10,
+    "strict_ccr_validation": false,
+    "timezone": "Asia/Shanghai",
+    "timing": {
+      "refresh": 3600,
+      "retry": 600,
+      "expire": 7200
+    }
+  }
+}
+```
+
+## POST /admin/rtr/config
+
+运行中动态修改 RTR server 的部分 runtime 配置。请求体是 JSON object，支持部分更新，只需要传要修改的字段。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `max_delta` | integer | 每个 RTR 版本最多保留的 delta 条数，必须 `>= 1`。 |
+| `prune_delta_by_snapshot_size` | boolean | 是否按 snapshot wire size 裁剪 delta window。 |
+| `source_refresh_interval_seconds` | integer | CCR/SLURM source refresh 间隔，单位秒，必须 `>= 1`。 |
+| `runtime_report_interval_seconds` | integer | `rtr-runtime-*.json` 周期写入间隔，单位秒，必须 `>= 1`。 |
+| `report_history_limit` | integer | 每类 report 文件滚动保留数量，必须 `>= 1`。 |
+| `strict_ccr_validation` | boolean | 是否严格校验 CCR 中的非法 VRP/VAP，影响下一次 source refresh。 |
+| `timezone` | string | IANA 时区名，例如 `Asia/Shanghai`、`UTC`、`Europe/London`。 |
+| `timing.refresh` | integer | RTR EndOfData `refresh`，单位秒。 |
+| `timing.retry` | integer | RTR EndOfData `retry`，单位秒。 |
+| `timing.expire` | integer | RTR EndOfData `expire`，必须大于 `refresh` 和 `retry`。 |
+
+示例：
+
+```bash
+curl -X POST http://127.0.0.1:8323/admin/rtr/config \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer change-me" \
+  -d '{"max_delta": 6}'
+```
+
+成功响应：
+
+```json
+{
+  "status": "ok",
+  "config": {
+    "max_delta": 6,
+    "prune_delta_by_snapshot_size": true,
+    "source_refresh_interval_seconds": 300,
+    "runtime_report_interval_seconds": 300,
+    "report_history_limit": 10,
+    "strict_ccr_validation": false,
+    "timezone": "Asia/Shanghai",
+    "timing": {
+      "refresh": 3600,
+      "retry": 600,
+      "expire": 7200
+    }
+  }
+}
+```
+
+## GET /admin/rtr/slurm/files
+
+列出 `RPKI_RTR_SLURM_DIR` 下的 SLURM 文件。只返回合法的 `*.slurm` 和 `*.slurm.disabled` 文件，不返回 `.backup/`。
+
+```bash
+curl http://127.0.0.1:8323/admin/rtr/slurm/files \
+  -H "Authorization: Bearer change-me"
+```
+
+响应示例：
+
+```json
+{
+  "status": "ok",
+  "files": [
+    {
+      "name": "local-policy.slurm",
+      "path": "/app/slurm/local-policy.slurm",
+      "enabled": true,
+      "size_bytes": 168,
+      "modified_unix_seconds": 1782100000
+    },
+    {
+      "name": "old-policy.slurm.disabled",
+      "path": "/app/slurm/old-policy.slurm.disabled",
+      "enabled": false,
+      "size_bytes": 168,
+      "modified_unix_seconds": 1782100100
+    }
+  ]
+}
+```
+
+## GET /admin/rtr/slurm/files/{name}
+
+读取单个 SLURM 文件，前端编辑页面可以直接使用这个接口加载内容。
+
+```bash
+curl http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm \
+  -H "Authorization: Bearer change-me"
+```
+
+响应示例：
+
+```json
+{
+  "status": "ok",
+  "file": {
+    "name": "local-policy.slurm",
+    "path": "/app/slurm/local-policy.slurm",
+    "enabled": true,
+    "size_bytes": 168,
+    "modified_unix_seconds": 1782100000,
+    "content": "{ \"slurmVersion\": 1, \"validationOutputFilters\": { \"prefixFilters\": [], \"bgpsecFilters\": [] }, \"locallyAddedAssertions\": { \"prefixAssertions\": [], \"bgpsecAssertions\": [] } }"
+  }
+}
+```
+
+## POST /admin/rtr/slurm/files
+
+新增或覆盖一个 SLURM 文件。文件名放在请求体中。
+
+```json
+{
+  "name": "local-policy.slurm",
+  "content": "{ \"slurmVersion\": 1, \"validationOutputFilters\": { \"prefixFilters\": [], \"bgpsecFilters\": [] }, \"locallyAddedAssertions\": { \"prefixAssertions\": [], \"bgpsecAssertions\": [] } }",
+  "reload": true
+}
+```
+
+## PUT /admin/rtr/slurm/files/{name}
+
+新增或覆盖指定 SLURM 文件。
+
+```bash
+curl -X PUT http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer change-me" \
+  -d '{
+    "content": "{ \"slurmVersion\": 1, \"validationOutputFilters\": { \"prefixFilters\": [], \"bgpsecFilters\": [] }, \"locallyAddedAssertions\": { \"prefixAssertions\": [], \"bgpsecAssertions\": [] } }",
+    "reload": true
+  }'
+```
+
+## DELETE /admin/rtr/slurm/files/{name}
+
+删除指定 SLURM 文件。删除前会先备份。
+
+```bash
+curl -X DELETE "http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm?reload=true" \
+  -H "Authorization: Bearer change-me"
+```
+
+## POST /admin/rtr/slurm/files/{name}/disable
+
+将启用文件改名为失效文件：
+
+```text
+local-policy.slurm -> local-policy.slurm.disabled
+```
+
+```bash
+curl -X POST "http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm/disable?reload=true" \
+  -H "Authorization: Bearer change-me"
+```
+
+## POST /admin/rtr/slurm/files/{name}/enable
+
+将失效文件改名为启用文件：
+
+```text
+local-policy.slurm.disabled -> local-policy.slurm
+```
+
+```bash
+curl -X POST "http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm.disabled/enable?reload=true" \
+  -H "Authorization: Bearer change-me"
+```
+
+## POST /admin/rtr/slurm/reload
+
+不修改文件，只立即触发一次 CCR/SLURM source reload。
+
+```bash
+curl -X POST http://127.0.0.1:8323/admin/rtr/slurm/reload \
+  -H "Authorization: Bearer change-me"
+```
+
+## SLURM 文件规则
+
+- `*.slurm`：启用，会被 source refresh 加载。
+- `*.slurm.disabled`：失效，不会被加载。
+- `.backup/`：接口自动生成的备份目录。
+- 文件名只能是 basename，不能包含 `/`、`\` 或 `..`。
+- 文件名只能包含 ASCII 字母、数字、`.`、`_`、`-`。
+- 写入内容必须是合法 JSON，并且能被解析为合法 SLURM 文件。
+- 单个请求体默认限制为 5 MiB。
+- 覆盖、删除前会写入 `.backup/` 备份。
+
+## 错误响应
+
+| HTTP 状态码 | 含义 |
+| --- | --- |
+| `400 Bad Request` | JSON 非法、配置值非法、SLURM 文件名非法、目标文件不存在、reload 失败等。 |
+| `401 Unauthorized` | 配置了 token，但请求缺少或使用了错误的 `Authorization`。 |
+| `404 Not Found` | 路径或方法不支持。 |
+| `413 Payload Too Large` | 请求体超过限制。 |