API 文档
适合谁需要把 RTKHUB 状态、控制能力或任务管理接入外部系统的开发者。
你会完成登录认证、读取状态、控制基线，并理解用户、任务和 Webhook 接口边界。
调用建议状态接口适合轮询，控制接口应记录原因并做权限和幂等保护。
RTKHUB 提供 REST API，便于把实时状态、基线控制、任务管理和告警能力接入外部系统。示例地址使用默认端口：
http://127.0.0.1:5426
调用约定
- 认证方式：登录后使用 Cookie 会话。
- 请求格式：控制类接口优先使用 JSON。
- 响应格式：
application/json。 - 字符集：UTF-8。
- 权限：只读接口可授予
viewer，控制接口建议授予operator或admin。
认证
POST /api/login
POST /api/login
Content-Type: application/x-www-form-urlencoded
username=admin&password=your_password
响应示例：
{
"success": true,
"message": "Login successful",
"user": {
"username": "admin",
"role": "admin"
}
}
POST /api/logout
退出当前会话。
POST /api/logout
状态查询
GET /api/status
获取所有测网和基线的实时状态。
{
"networks": [
{
"name": "XANet",
"channels": [
{
"id": 0,
"name": "DH04-DH06",
"running": true,
"state": 5,
"stateText": "FIX",
"ns": 12,
"ratio": 15.3,
"age": 1.2,
"e": 0.012,
"n": -0.008,
"u": 0.034
}
]
}
]
}
字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
running | boolean | 基线进程是否运行 |
state | number | RTK 状态码，常见值：0 无解、1 SINGLE、4 FLOAT、5 FIX |
ns | number | 当前使用卫星数 |
ratio | number | 整周模糊度固定质量指标 |
age | number | 差分数据龄期，单位秒 |
e/n/u | number | ENU 位移，单位米 |
GET /api/stat
获取卫星级统计信息，适合绘制天空图、残差图和卫星系统分布。
{
"channel": 0,
"satellites": [
{
"sat": "G01",
"sys": "GPS",
"az": 145.2,
"el": 35.8,
"fix": 2,
"resp": [0.12, -0.08],
"resc": [0.002, -0.001]
}
]
}
控制操作
POST /api/control
启动、停止或重启单条基线或整个测网。
{
"action": "restart",
"network": "XANet",
"channel": "DH04-DH06"
}
参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
action | string | 是 | start、stop、restart |
network | string | 是 | 测网名称 |
channel | string | 否 | 通道名称，省略时作用于整个测网 |
建议控制接口增加二次确认或操作日志，避免外部系统误触发批量重启。
用户管理 API
用户管理接口应仅对 admin 开放。
GET /api/users
获取用户列表。
{
"users": [
{
"id": 1,
"username": "admin",
"role": "admin",
"enabled": true,
"lastLogin": "2026-06-11T09:30:00+08:00"
}
]
}
POST /api/users
创建用户。
{
"username": "operator01",
"password": "change_me_first",
"role": "operator",
"enabled": true
}
PUT /api/users/:id
更新用户角色、状态或密码。
{
"role": "viewer",
"enabled": true
}
DELETE /api/users/:id
删除用户或停用用户。生产环境建议优先停用，保留审计记录。
SCRHUB API
GET /api/scrhub/tasks
获取脚本任务列表。
{
"tasks": [
{
"id": 12,
"name": "daily-backup",
"schedule": "0 2 * * *",
"enabled": true,
"lastStatus": "success"
}
]
}
POST /api/scrhub/execute
手动执行任务。
{
"taskId": 12,
"args": ["--days", "7"]
}
接口应返回执行 ID，调用方再查询任务日志或状态。
Webhook 通知
如果启用 Webhook，建议事件载荷保持稳定：
{
"event": "channel.state_changed",
"time": "2026-06-11T10:00:00+08:00",
"network": "XANet",
"channel": "DH04-DH06",
"level": "warning",
"message": "State changed from FIX to FLOAT"
}
建议事件类型：
| 事件 | 说明 |
|---|---|
channel.started | 基线启动 |
channel.stopped | 基线停止 |
channel.state_changed | 解算状态变化 |
channel.age_high | 差分龄期过高 |
channel.ratio_low | Ratio 低于阈值 |
task.finished | SCRHUB 任务完成 |
task.failed | SCRHUB 任务失败 |
示例
Python
import requests
base_url = "http://127.0.0.1:5426"
session = requests.Session()
session.post(f"{base_url}/api/login", data={
"username": "admin",
"password": "password",
})
status = session.get(f"{base_url}/api/status")
print(status.json())
session.post(f"{base_url}/api/control", json={
"action": "start",
"network": "XANet",
"channel": "DH04-DH06",
})
JavaScript
const baseUrl = 'http://127.0.0.1:5426';
await fetch(`${baseUrl}/api/login`, {
method: 'POST',
headers: {'Content-Type': 'application/x-www-form-urlencoded'},
body: new URLSearchParams({
username: 'admin',
password: 'password',
}),
credentials: 'include',
});
const response = await fetch(`${baseUrl}/api/status`, {
credentials: 'include',
});
console.log(await response.json());
cURL
curl -c cookies.txt -d "username=admin&password=password" \
http://127.0.0.1:5426/api/login
curl -b cookies.txt http://127.0.0.1:5426/api/status
错误响应
{
"success": false,
"error": "unauthorized",
"message": "请先登录"
}
| 错误码 | HTTP 状态 | 说明 |
|---|---|---|
invalid_params | 400 | 参数错误 |
unauthorized | 401 | 未登录或会话失效 |
forbidden | 403 | 权限不足 |
not_found | 404 | 资源不存在 |
conflict | 409 | 当前状态不允许操作 |
too_many_requests | 429 | 调用过于频繁 |
internal_error | 500 | 服务内部错误 |
最佳实践
/api/status轮询间隔建议不小于 1 秒。- 控制接口应做幂等处理：重复
start已运行基线不应导致异常。 - 自动化系统调用
restart前应先读取当前状态并记录原因。 - 外部系统不要依赖内部 SQLite 表结构，优先使用 API。
- 网络异常时使用指数退避重试，避免对 Web 服务形成压力。