314 lines
8.5 KiB
Markdown
314 lines
8.5 KiB
Markdown
# 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` | 请求体超过限制。 |
|