API 文档

事实来源

RTKHUB 与 SCRHUB 端点以主项目 src/web_server/rtk_web.c、src/scrhub/scrhub_api.c 为准；STRHUB 端点以 util/strhub/strhub.c 为准；EPHUB 端点以 util/ephub/ephub.c 为准。完整速查见 API 索引。

适合谁需要把 RTKHUB 状态、控制能力或任务管理接入外部系统的开发者。

你会完成登录认证、读取状态、控制基线、管理用户和脚本任务。

调用建议状态接口适合轮询，控制接口应记录原因并做权限和幂等保护。

API 基础地址

以下示例均使用默认端口 5426。如果 RTKHUB 部署在其他端口或通过反向代理访问，请相应替换基础地址。

RTKHUB 提供 REST API，便于把实时状态、基线控制、任务管理接入外部系统。示例地址使用默认端口：

http://127.0.0.1:5426

模块边界

模块	基础地址	认证	用途
RTKHUB	`http://127.0.0.1:5426/`	`rtkhub_session` Cookie	登录、状态、基线控制、用户、审计、配置
SCRHUB	`http://127.0.0.1:5426/`	复用 RTKHUB 会话	脚本任务、脚本扫描、手动运行、任务日志
STRHUB	`http://127.0.0.1:5427/`	建议仅内网或反代保护	流任务状态、添加、启停、删除、保存
EPHUB	`http://127.0.0.1:5428/`	建议仅内网或反代保护	星历输入/输出、缓存、告警、质量控制、参考源

公网访问

RTKHUB 会话 Cookie、STRHUB/EPHUB stream path 和 NTRIP 凭据都需要可信传输环境。公网访问必须走 HTTPS 反向代理、Cloudflare Tunnel 或 VPN，不要直接暴露后端端口。

调用约定

会话 Cookie 安全

rtkhub_session Cookie 是认证凭证，必须通过 HTTPS 传输。在 HTTP 环境下 Cookie 可被中间人截获。生产环境务必启用 HTTPS 反向代理。

认证方式：登录后使用 rtkhub_session Cookie 会话，8 小时无操作滑动过期。
请求格式：控制类接口优先使用 application/x-www-form-urlencoded 或 JSON。
响应格式：application/json。
字符集：UTF-8。
权限体系：viewer（只读）、operator（可控制）、admin（完全管理）。

认证

POST /api/login

登录并设置会话 Cookie。60 秒内最多 5 次失败尝试，超限返回 429。

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/session

查询当前会话状态，无需认证。前端页面加载时用此接口判断是否已登录。

{
  "authenticated": true,
  "user": {
    "username": "admin",
    "role": "admin"
  }
}

GET /api/me

获取当前用户的详细权限信息（需已认证）。

{
  "username": "admin",
  "role": "admin",
  "permissions": {
    "read": true,
    "control": true,
    "admin": true
  }
}

状态查询

需要认证

以下所有接口均需要登录认证（rtkhub_session Cookie），未认证将返回 401。

GET /api/status

获取所有测网和基线的实时状态（需 viewer 以上权限）。

{
  "networks": [
    {
      "name": "XANet",
      "net_lat": 34.2324,
      "net_lon": 108.9524,
      "net_hgt": 399.01,
      "dir": "./result/2026/XANet/",
      "channels": [
        {
          "id": 0,
          "site_name": "DH04-DH06",
          "running": true,
          "state": 5,
          "navsys": 5,
          "navsys_list": "G,R,E,C",
          "ns": 12,
          "nf": 2,
          "ratio": 15.3,
          "age": 1.2,
          "lat": 34.2355,
          "lon": 108.9099,
          "hgt": 384.39,
          "rt_lat": 34.2355,
          "rt_lon": 108.9099,
          "rt_hgt": 384.39,
          "err_n": -0.008,
          "err_e": 0.012,
          "err_u": 0.034,
          "in_bps": 1280,
          "out_bps": 0,
          "uptime": 3600,
          "gdop": 1.8,
          "pdop": 1.2,
          "hdop": 0.9,
          "vdop": 1.1,
          "dir": 245.3,
          "conf_file": "conf/XANet/rtkhub1.conf"
        }
      ]
    }
  ]
}

主要字段说明：

字段	类型	说明
`running`	boolean	基线进程是否运行
`state`	number	RTK 状态码：0 无解、1 SINGLE、2 DGPS、4 FLOAT、5 FIX
`navsys`	number	卫星系统位掩码
`navsys_list`	string	当前启用的卫星系统列表
`ns`	number	当前使用卫星数
`nf`	number	使用频率数
`ratio`	number	整周模糊度固定质量指标
`age`	number	差分数据龄期，单位秒
`lat/lon/hgt`	number	近似坐标（度/度/米）
`rt_lat/rt_lon/rt_hgt`	number	实时解算坐标
`err_n/err_e/err_u`	number	与参考坐标的 N/E/U 偏差（米）
`in_bps`	number	输入数据速率（字节/秒）
`uptime`	number	运行时长（秒）
`gdop/pdop/hdop/vdop`	number	各类 DOP 值
`conf_file`	string	该通道使用的配置文件路径

GET /api/stat?net=<net>&ch=<id>

获取指定通道的卫星级统计信息（需 viewer 以上权限），适合绘制天空图和残差图。

{
  "net_name": "XANet",
  "ch": 0,
  "global_id": 0,
  "local_id": 0,
  "site_name": "DH04-DH06",
  "nf": 2,
  "freq_unit": "MHz",
  "satellites": [
    {
      "sat": "G01",
      "c1": 20000000.0,
      "az": 145.2,
      "el": 35.8,
      "freq_mhz": [1575.42, 1227.60],
      "vsat": [1, 1],
      "fix": [2, 2],
      "resp": [0.12, -0.08],
      "resc": [0.002, -0.001],
      "slip": [0, 0]
    }
  ]
}

字段	类型	说明
`sat`	string	卫星编号（如 G01、C38）
`az`	number	方位角（度）
`el`	number	高度角（度）
`freq_mhz`	array	各频率值（MHz）
`vsat`	array	各频率是否有效（1/0）
`fix`	array	各频率固定状态（0:无 1:浮点 2:固定）
`resp`	array	伪距残差（米）
`resc`	array	载波残差（周）
`slip`	array	周跳标记（0/1）

GET /api/term_read

读取当前会话的 Web 终端输出缓冲区（需 viewer 以上权限）。每个会话独立隔离，最多支持 64 个并发会话。

{
  "output": "[INFO] XANet channel 0: FIX (ns=12, ratio=15.3)\n"
}

控制操作

需要 operator 以上权限

控制接口会直接影响正在运行的基线，请确保调用方具备 operator 或 admin 角色，并做好操作日志记录。

POST /api/control

启动、停止或重启单条基线或整个测网（需 operator 以上权限）。

POST /api/control
Content-Type: application/x-www-form-urlencoded

action=restart&net=XANet&ch=DH04-DH06

字段	类型	必填	说明
`action`	string	是	`start`、`stop`、`restart`
`net`	string	是	测网名称
`ch`	string	否	通道名称或 ID，省略或 `all` 时作用于整个测网

幂等保护

建议控制接口增加二次确认或操作日志，避免外部系统误触发批量重启。重复调用 start 已运行的基线不应导致异常，调用方应在发送前检查当前状态。

POST /api/term_cmd

执行终端命令（需 operator 以上权限）。按角色白名单过滤可执行命令，operator 可执行 start/stop/restart/list/status 等，admin 可执行所有命令。

POST /api/term_cmd
Content-Type: application/x-www-form-urlencoded

cmd=list+run

POST /api/cmd

执行任意终端命令，无白名单过滤（仅 admin）。用于需要完整控制台能力的自动化场景。

POST /api/cmd
Content-Type: application/x-www-form-urlencoded

cmd=save+conf%5Crtkhub.list

POST /api/config

执行配置相关命令（仅 admin）。功能等同于 /api/cmd，语义上区分配置类操作。

POST /api/upload

上传配置文件到 conf/ 目录（仅 admin）。支持 multipart 文件上传。

POST /api/upload
Content-Type: multipart/form-data

file=@rtkhub.list

用户管理 API

仅 admin 可用

用户管理接口仅对 admin 角色开放，操作失误可能导致所有用户无法登录。

GET /api/users

获取用户列表。

{
  "users": [
    {
      "id": 1,
      "username": "admin",
      "role": "admin",
      "enabled": true,
      "last_login": "2026-06-11T09:30:00"
    }
  ]
}

POST /api/users

创建用户。

POST /api/users
Content-Type: application/x-www-form-urlencoded

username=operator01&password=change_me&role=operator

POST /api/users/update

更新用户角色和启用状态。

POST /api/users/update
Content-Type: application/x-www-form-urlencoded

id=2&role=viewer&enabled=1

POST /api/users/delete

删除用户。生产环境建议优先停用而非删除，保留审计记录。

POST /api/users/delete
Content-Type: application/x-www-form-urlencoded

id=2

POST /api/users/reset_password

重置用户密码。

POST /api/users/reset_password
Content-Type: application/x-www-form-urlencoded

id=2&new_password=new_secret

GET /api/audit?date=YYYYMMDD

查看审计日志（仅 admin）。按日期筛选，返回登录、控制、用户管理等操作记录。

{
  "records": [
    {
      "timestamp": "2026-06-11T09:30:00",
      "username": "admin",
      "action": "login",
      "detail": "Login successful from 127.0.0.1",
      "result": "success"
    }
  ]
}

SCRHUB 脚本管理 API

脚本管理接口仅对 admin 开放，查看日志需 viewer 以上权限。

GET /api/scripts

获取脚本任务列表。

{
  "scripts": [
    {
      "id": 12,
      "name": "daily-backup",
      "script_file": "logs_archiving.sh",
      "script_type": "sh",
      "schedule": "0 2 * * *",
      "enabled": true,
      "log_retention_days": 30,
      "last_status": "success",
      "last_run": "2026-06-11T02:00:00"
    }
  ]
}

POST /api/scripts

创建脚本任务。

POST /api/scripts
Content-Type: application/json

{
  "name": "daily-backup",
  "script_file": "logs_archiving.sh",
  "script_type": "sh",
  "schedule": "0 2 * * *",
  "enabled": true,
  "log_retention_days": 30
}

PUT /api/scripts/:id

更新脚本任务配置。

DELETE /api/scripts/:id

删除脚本任务及其执行日志。

POST /api/scripts/:id/toggle

启用或停用脚本任务。

POST /api/scripts/:id/run

手动执行脚本任务。返回执行结果，stdout 和 stderr 写入日志。

GET /api/scripts/:id/logs?limit=N

获取脚本执行日志，limit 控制返回条数。

{
  "logs": [
    {
      "id": 42,
      "run_at": "2026-06-11T02:00:00",
      "status": "success",
      "exit_code": 0,
      "stdout": "Archived 15 log files\n",
      "stderr": ""
    }
  ]
}

GET /api/scripts/files?refresh=1

读取 script/ 目录下的可执行脚本文件列表。首次访问或传 refresh=1 时重新扫描目录。

{
  "files": [
    { "name": "logs_archiving.sh", "type": "sh", "path": "logs_archiving.sh" },
    { "name": "pos_archiving.sh", "type": "sh", "path": "pos_archiving.sh" }
  ]
}

EPHUB API

EPHUB 运行在独立端口（默认 5428），提供广播星历管理接口。详见 EPHUB 文档。

状态查询

方法	端点	说明
GET	`/api/status`	总览状态（输入/输出数量、缓存统计）
GET	`/api/inputs`	输入流详情（状态、字节数、星历接收、重复/无效统计）
GET	`/api/outputs`	输出流详情（状态、速率、失败次数、重连次数）
GET	`/api/sources`	查询当前采用星历及候选源摘要，支持 `?sat=G29`
GET	`/api/sat?id=G29`	查询单颗卫星当前采用星历和全部候选源
GET	`/api/cache`	缓存星历列表（支持 `?all=1` 全量、`?sat=G29` 卫星过滤）

输入流管理（热更新）

方法	端点	说明
POST	`/api/inputs`	运行期新增输入流，无需重启。JSON body: `{ "path": "ntrip://user:password@host:port/MOUNT" }`
PATCH	`/api/inputs/<id>`	运行期启停输入流。JSON body: `{ "action": "start" }` 或 `{ "action": "stop" }`
DELETE	`/api/inputs/<id>`	运行期删除输入流，并清理该源候选星历

输出流管理（热更新）

方法	端点	说明
POST	`/api/outputs`	运行期新增输出流，无需重启。JSON body: `{ "path": "tcpsvr://:10011" }` 或 `{ "path": "ntripsvr://password@host:port/MOUNT" }`
PATCH	`/api/outputs/<id>`	运行期启停输出流。JSON body: `{ "action": "start" }` 或 `{ "action": "stop" }`
DELETE	`/api/outputs/<id>`	运行期删除输出流

告警与完整性

方法	端点	说明
GET	`/api/active-alerts`	查询当前仍未恢复的完好性/输入输出告警
GET	`/api/alerts`	查询最近完好性/输入输出历史事件，支持 `?limit=50`

质量度量与参考源

方法	端点	说明
GET	`/api/reference`	查询外部 SP3/CLK 文件存在性、加载状态、精密轨道/钟差卫星数、时间范围、最后错误，以及实时 SSR APC/CoM 参考流状态
GET	`/api/reference/sat?id=G01`	查询单颗卫星外部参考诊断，包含 SSR orbit/clock、IOD、龄期和可用性原因

配置管理

方法	端点	说明
POST	`/api/config/save`	将当前运行配置（包括所有热更新的流）保存回 `-k` 加载的配置文件

热更新能力说明：

v1.3.0+ 支持运行期动态添加、删除、启停输入/输出流，无需重启 EPHUB。热更新的配置默认仅在内存中生效，使用 /api/config/save 可持久化到配置文件，确保重启后保留更改。

示例：新增输入流并保存配置

# 1. 新增输入流
curl -X POST http://127.0.0.1:5428/api/inputs \
  -H "Content-Type: application/json" \
  -d '{"path": "ntrip://user:password@caster.example.com:2101/MOUNT_NEW"}'

# 2. 保存配置到文件
curl -X POST http://127.0.0.1:5428/api/config/save

NTRIP 挂载点查询

方法	端点	说明
GET	`/api/ntrip/mountpoints?host=<host>&port=2101&user=<user>&password=<password>`	从 NTRIP caster sourcetable 获取挂载点列表

EPHUB 和 STRHUB 会返回较大的 sourcetable 结果集，用于 Web 弹窗中选择挂载点。返回内容应只在可信网络内使用，避免把 caster 凭据放进浏览器历史或公开日志。

STRHUB API

STRHUB 运行在独立端口（默认 5427），提供流转发管理接口。

方法	端点	说明
GET	`/api/status`	查询所有任务状态
GET	`/api/add?cmd=<args>`	添加新任务
GET	`/api/start?id=<id>`	启动任务
GET	`/api/stop?id=<id>`	停止任务
GET	`/api/del?id=<id>`	删除任务
GET	`/api/save`	保存配置
GET	`/api/ntrip/mountpoints?host=<host>&port=2101&user=<user>&password=<password>`	从 NTRIP caster sourcetable 获取挂载点列表

示例

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", data={
    "action": "start",
    "net": "XANet",
    "ch": "DH04-DH06",
})

# 查询卫星统计
stat = session.get(f"{base_url}/api/stat", params={
    "net": "XANet", "ch": 0
})
print(stat.json())

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());

// 控制基线
await fetch(`${baseUrl}/api/control`, {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: new URLSearchParams({action: 'restart', net: 'XANet', ch: 'all'}),
  credentials: 'include',
});

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

# 查询卫星统计
curl -b cookies.txt "http://127.0.0.1:5426/api/stat?net=XANet&ch=0"

# 控制基线
curl -b cookies.txt -d "action=restart&net=XANet&ch=all" \
  http://127.0.0.1:5426/api/control

# 查看审计日志
curl -b cookies.txt http://127.0.0.1:5426/api/audit?date=20260611

错误响应

{
  "success": false,
  "error": "unauthorized",
  "message": "请先登录"
}

错误码	HTTP 状态	说明
`invalid_params`	400	参数错误
`unauthorized`	401	未登录或会话失效
`forbidden`	403	权限不足
`not_found`	404	资源不存在
`conflict`	409	当前状态不允许操作
`too_many_requests`	429	登录失败过于频繁（60 秒内 5 次）
`internal_error`	500	服务内部错误

最佳实践

/api/status 轮询间隔建议不小于 1 秒。
控制接口应做幂等处理：重复 start 已运行基线不应导致异常。
自动化系统调用 restart 前应先读取当前状态并记录原因。
外部系统不要依赖内部 SQLite 表结构，优先使用 API。
网络异常时使用指数退避重试，避免对 Web 服务形成压力。
viewer 只读、operator 可控制、admin 完全管理，按最小权限原则分配角色。
生产环境不要在 URL、截图、浏览器历史或反向代理日志中保留 NTRIP 明文凭证；STRHUB/EPHUB 会脱敏展示，但配置文件和请求参数仍需按敏感数据处理。
Web 终端中的写文件类命令存在按用户每日限额，避免误操作频繁覆盖配置。

模块边界​

调用约定​

认证​

POST /api/login​

POST /api/logout​

GET /api/session​

GET /api/me​

状态查询​

GET /api/status​

GET /api/stat?net=<net>&ch=<id>​

GET /api/term_read​

控制操作​

POST /api/control​

POST /api/term_cmd​

POST /api/cmd​

POST /api/config​

POST /api/upload​

用户管理 API​

GET /api/users​

POST /api/users​

POST /api/users/update​

POST /api/users/delete​

POST /api/users/reset_password​

GET /api/audit?date=YYYYMMDD​

SCRHUB 脚本管理 API​

GET /api/scripts​

POST /api/scripts​

PUT /api/scripts/:id​

DELETE /api/scripts/:id​

POST /api/scripts/:id/toggle​

POST /api/scripts/:id/run​

GET /api/scripts/:id/logs?limit=N​

GET /api/scripts/files?refresh=1​

EPHUB API​

状态查询​

输入流管理（热更新）​

输出流管理（热更新）​

告警与完整性​

质量度量与参考源​

配置管理​

NTRIP 挂载点查询​

STRHUB API​

示例​

Python​

JavaScript​

cURL​

错误响应​

最佳实践​

相关文档​

模块边界

调用约定

认证

POST /api/login

POST /api/logout

GET /api/session

GET /api/me

状态查询

GET /api/status

GET /api/stat?net=<net>&ch=<id>

GET /api/term_read

控制操作

POST /api/control

POST /api/term_cmd

POST /api/cmd

POST /api/config

POST /api/upload

用户管理 API

GET /api/users

POST /api/users

POST /api/users/update

POST /api/users/delete

POST /api/users/reset_password

GET /api/audit?date=YYYYMMDD

SCRHUB 脚本管理 API

GET /api/scripts

POST /api/scripts

PUT /api/scripts/:id

DELETE /api/scripts/:id

POST /api/scripts/:id/toggle

POST /api/scripts/:id/run

GET /api/scripts/:id/logs?limit=N

GET /api/scripts/files?refresh=1

EPHUB API

状态查询

输入流管理（热更新）

输出流管理（热更新）

告警与完整性

质量度量与参考源

配置管理

NTRIP 挂载点查询

STRHUB API

示例

Python

JavaScript

cURL

错误响应

最佳实践

相关文档