EPHUB 文档
适用版本包含 2026-06-28 安全加固、外部参考 SISRE、SSR 参考流、源间偏差和 API 字段。
默认入口
http://127.0.0.1:5428/ephub.html，API 基础地址为 http://127.0.0.1:5428/推荐下一步先配置输入 NTRIP 源和本地 TCP Server 输出，再通过缓存和告警页面验证星历质量。
EPHUB 是 PNTHUB 工具链中的广播星历实时汇集、质量控制、缓存重播与故障转发工具。它从多个 NTRIP/RTCM3 输入流中抽取广播星历，经过缓存、去重和周期重播后，通过文件、TCP Server 或 NTRIP Server 等多种方式输出，为 RTK 解算提供稳定可靠的星历数据源。
快速开始
启动 EPHUB
.\ephub\x64\Debug\ephub.exe -k conf\ephub_conf\ephub.conf -x 3
信息
EPHUB 提供 Web 管理界面，默认监听 5428 端口。
- 独立管理页面：http://127.0.0.1:5428/ephub.html
- HTTP API：http://127.0.0.1:5428/api/status
注意
配置文件 ephub.conf 包含 NTRIP 凭证等敏感信息，不应提交到 Git 仓库。建议将 conf/ephub_conf/ 目录加入 .gitignore。
配置文件建议放在 conf\ephub_conf\ephub.conf，该目录默认不进入 Git，适合保存私有 NTRIP 凭证。
配置文件示例
凭证安全
以下配置示例中的 user:password 仅为占位符。实际使用时，请替换为真实的 NTRIP 账号密码，并确保配置文件不被泄露或提交到版本控制系统。
# ephub local runtime configuration
# This file may contain private NTRIP credentials and should not be committed.
-in ntrip://user:password@caster.example.com:2101/MOUNT_A
-in ntrip://user:password@caster.example.com:2101/MOUNT_B
-out file://result\ephub-out.rtcm3
-out tcpsvr://:10010
# Push to a remote NTRIP caster when production publishing is needed.
# -out ntripsvr://caster_password@caster.example.com:2101/EPHUB:EPHUB
-d 2000
-rb 5000
-reconnect 5000
-maxage 7200
-prefer MOUNT_A
-toe-diff 60
-clock-jump 0.0
-sisre-warn 2.0
-sisre-alarm 5.0
-radial-warn 1.0
-radial-alarm 3.0
-clock-warn 1.0
-clock-alarm 3.0
# Optional external precise reference files for strict SISRE checks.
# -ref-sp3 reference.sp3
# -ref-clk reference.clk
# Optional real-time SSR reference streams. SSRA is APC, SSRC is CoM.
# -ref-ssr-apc ntrip://user:password@caster.example.com:2101/SSRA00BKG0
# -ref-ssr-com ntrip://user:password@caster.example.com:2101/SSRC00BKG0
-web 5428
RTKLIB/RTKNAVI 可使用 TCP Client 连接 127.0.0.1:10010，格式选择 RTCM 3，用于观察 EPHUB 实际播发的广播星历流。
核心特性
- 🛰️ 支持从多个 NTRIP/RTCM3 输入流抽取广播星历
- 🔁 支持星历缓存、重复过滤、周期性重播和多路输出
- 📡 支持本地文件验证、TCP Server 实时转发和 NTRIP Server 推送到远程 caster
- 🧭 支持 GPS、GLONASS、Galileo、BDS、QZSS、SBAS 等广播星历 RTCM3 消息
- 🌐 Web 管理界面：实时状态监控、输入/输出流详情、星历缓存查询
- 📊 HTTP API：覆盖状态查询、输入/输出流 CRUD、告警、参考源状态、配置保存和 NTRIP 挂载点查询
- 🔥 热更新流：运行期无需重启即可新增或删除输入/输出流
- 💾 配置持久化：通过 CLI 或 API 将当前运行配置保存回配置文件
- 🔁 自动重连：输入/输出流断开后自动重连（可配置间隔）
- ⏰ 缓存过期：自动清理过期星历（默认 7200 秒）
- 🎯 源优先级：同卫星多源冲突时可配置优先采用的挂载点
- 🚨 完整性告警：实时星历完整性监控，主动告警系统追踪过期/缺失星历，Web 面板可视化指示
- 📈 质量度量：多源质量对比，候选源缓存，源质量诊断与排名
- 🛰️ SSR 参考流：支持 SSR 状态空间表示参考流，增强 RTCM 3 SSR 改正处理
- 🧪 参考源诊断：支持 SP3/CLK 文件参考和实时 SSR APC/CoM 参考流状态诊断
- 🧾 控制台采用命令式查询，周期状态写入 RTKLIB trace，避免后端刷屏
- 🔒 Web、API、trace 与控制台输出会脱敏 NTRIP 凭证
启动参数
| 参数 | 说明 |
|---|---|
-k <file> | 从配置文件读取启动参数。推荐使用 conf\ephub_conf\ephub.conf |
-in <path> | 输入流，可重复指定。常用格式：ntrip://user:password@host:port/MOUNT |
-out <path> | 输出流，可重复指定。常用格式：file://result\ephub-out.rtcm3、tcpsvr://:10010、ntripsvr://password@host:port/MOUNT |
-d <ms> | trace 状态统计间隔，单位毫秒 |
-rb <ms> | 当前缓存星历周期性重播间隔，单位毫秒；设置为 0 可关闭周期重播 |
-reconnect <ms> | 输入和输出流重连间隔，单位毫秒，默认 5000 |
-maxage <sec> | 当前缓存星历最大保留时间，超时不再重播，默认 7200；设置为 0 可关闭过期清理 |
-prefer <mount> | 同一卫星同一 TOE 出现多源冲突时优先采用的挂载点，可重复配置 |
-toe-diff <sec> | 多源候选星历 TOE 差异冲突阈值，默认 60 |
-clock-jump <m> | 兼容旧配置的钟差告警阈值，默认 0.0；新配置建议使用 -clock-warn/-clock-alarm |
-sisre-warn <m> | 源间 SISRE-like 或外部参考 SISRE 综合偏差告警阈值，默认 2.0 |
-sisre-alarm <m> | 源间 SISRE-like 或外部参考 SISRE 综合偏差严重阈值，默认 5.0 |
-radial-warn <m> | 源间径向偏差告警阈值，默认 1.0 |
-radial-alarm <m> | 源间径向偏差严重阈值，默认 3.0 |
-clock-warn <m> | 源间钟差等效距离告警阈值，默认 1.0 |
-clock-alarm <m> | 源间钟差等效距离严重阈值，默认 3.0 |
-ref-sp3 <file> | 外部 SP3 精密轨道参考文件；EPHUB 启动时复用 RTKLIB readsp3() 加载 |
-ref-clk <file> | 外部 RINEX CLK 精密钟差参考文件；EPHUB 启动时复用 RTKLIB readrnxc() 加载 |
-ref-ssr-apc <path> | 实时 SSR APC 参考流，例如 ntrip://user:password@host:2101/SSRA00BKG0 |
-ref-ssr-com <path> | 实时 SSR CoM 参考流，例如 ntrip://user:password@host:2101/SSRC00BKG0 |
-web <port> | HTTP 管理 API 端口，默认 5428 |
-noweb | 禁用 HTTP 管理 API |
-q | 安静模式，不输出接受消息日志 |
-x <level> | RTKLIB trace 级别。1 生命周期，2 状态统计，3 接收星历，4 缓存/重播细节，5 重复和无效帧细节 |
-selftest | 执行内部 RTCM3 星历抽取与编码自测 |
Stream Path 格式
EPHUB 的 stream path 使用 scheme://参数 写法，底层由 RTKLIB stream 模块打开：
serial://port[:bit_rate[:byte[:parity(n|o|e)[:stopb[:fctr(off|on)[#port]]]]]]]
file://path[::T[::+offset][::xspeed]]
tcpsvr://:port
tcpcli://addr:port
ntripsvr://[passwd@]addr:port/mntpnt[:str]
ntrip://user:passwd@addr:port/mntpnt
ntripcli://user:passwd@addr:port/mntpnt
ntripcas://user:passwd@:[port]/mpoint[:srctbl]
udpsvr://:port
udpcli://addr:port
提示
向外部 caster 播发广播星历应使用 ntripsvr:// 输出，例如：
-out ntripsvr://caster_password@caster.example.com:2101/EPHUB:EPHUB
注意：ntripsvr:// 的密码是 caster 端设置的推送密码，与 NTRIP 客户端的登录密码不同。
控制台命令
查询命令
help 显示命令帮助
help path 显示 stream path 格式说明
status 显示总览、缓存数量和播发统计
inputs 单独显示输入流状态、星历接收和重复/无效统计
outputs 单独显示输出流状态、速率、失败次数和重连次数
sources 显示当前星历缓存中每颗卫星采用的来源挂载点
sources <sat> 按卫星号过滤当前采用来源，例如 sources G29
cache 列出当前缓存星历，默认最多显示 40 条
cache all 列出全部缓存星历
sat <id> 查询指定卫星当前采用星历和全部候选源
active alerts 查询当前仍未恢复的完好性/输入输出告警
alerts [n] 查询最近完好性/输入输出历史事件，默认 20 条
流管理命令（热更新）
add input <path> 运行期新增并启动输入流，无需重启 EPHUB
add output <path> 运行期新增并打开输出流，无需重启 EPHUB
remove input <id> 删除输入流并清理其候选星历
remove output <id> 删除输出流
start in <id> 启动已停止的输入流
stop in <id> 停止输入流
start out <id> 启动已停止的输出流
stop out <id> 停止输出流
命令别名
流管理命令支持简写别名：add in/add input、add out/add output、remove in/del in、remove out/del out 均可使用。
配置管理命令
save [file] 保存当前运行配置到指定文件或 -k 加载的配置文件
系统命令
quit / exit 停止 EPHUB 并退出
控制台行为说明
EPHUB 的控制台只保留命令查询结果；输入/输出流后台重连失败不会刷 CLI，详细失败原因写入 trace 文件。通过 -x <level> 控制详细程度，其中 -x 1 可看到输入/输出打开失败、重连、Web 启停等生命周期日志。
热更新流能力
v1.3.0+ 支持运行期动态管理输入/输出流，无需重启 EPHUB：
- 新增流：
add input <path>或add output <path>立即添加并启动新流 - 删除流：
remove input <id>或remove output <id>删除流并清理相关缓存 - 启停流：
start/stop in/out <id>控制单个流的运行状态 - API 支持：所有热更新操作均可通过 HTTP API 执行（见下文 API 章节）
配置持久化
热更新的流配置默认只在内存中生效。使用 save 命令或 /api/config/save 端点可将当前配置持久化到 -k 指定的配置文件，确保重启后保留更改。
缓存机制
当前播发缓存按 RTCM 类型 + 卫星 保留最新有效星历，历史旧星历不会持续重播；当同一卫星出现同 TOE 的多源冲突时，可用 -prefer 控制源优先级。
- 缓存过期：每个星历条目附带接收时间戳，超过
-maxage指定的秒数（默认 7200 秒）后不再播发。设置-maxage 0可关闭过期清理。 - 源优先级：同一卫星同一 TOE 出现多源冲突时，使用
-prefer <mount>指定优先挂载点。未配置-prefer时按首次到达的来源保留。 - 周期重播：缓存星历按
-rb设定的间隔周期重播，确保下游连接方（如 RTKNAVI）即使在星历更新间隙也能获取最新数据。设置-rb 0可关闭周期重播。 - 自动重连：输入和输出流断开后，按
-reconnect设定的间隔（默认 5000 毫秒）自动重连。重连失败不会刷 CLI，详细原因写入 trace 文件。
质量控制参数
EPHUB 支持多层级的星历质量控制，分为源间互比和外部参考两大类：
源间互比（默认启用）：复用 RTKLIB eph2pos/geph2pos 对同星多源候选星历计算同一历元的位置差和钟差差异，按参考源轨道方向分解为 R/A/C：
| 参数 | 默认值 | 说明 |
|---|---|---|
-toe-diff <sec> | 60 | 多源候选星历 TOE 差异超过此阈值时视为冲突 |
-clock-jump <m> | 0.0 | 兼容旧配置的钟差告警阈值；新配置建议使用 -clock-warn/-clock-alarm |
-sisre-warn <m> | 2.0 | 源间 SISRE-like 综合偏差告警阈值 |
-sisre-alarm <m> | 5.0 | 源间 SISRE-like 综合偏差严重阈值 |
-radial-warn <m> | 1.0 | 源间径向偏差告警阈值 |
-radial-alarm <m> | 3.0 | 源间径向偏差严重阈值 |
-clock-warn <m> | 1.0 | 源间钟差等效距离告警阈值 |
-clock-alarm <m> | 3.0 | 源间钟差等效距离严重阈值 |
其中 sisre_like_m 是多源广播星历之间的 SISRE-like 监测指标。
外部参考 SISRE（可选）：配置 -ref-sp3/-ref-clk 后，EPHUB 复用 RTKLIB readsp3()/readrnxc()/peph2pos() 加载外部精密轨道/钟差并计算严格参考偏差。sisre_m 是相对外部 SP3/CLK 参考的严格 SISRE 监测指标，和 sisre_like_m 分开展示。
| 参数 | 说明 |
|---|---|
-ref-sp3 <file> | 外部 SP3 精密轨道参考文件；启动时复用 RTKLIB readsp3() 加载 |
-ref-clk <file> | 外部 RINEX CLK 精密钟差参考文件；启动时复用 RTKLIB readrnxc() 加载 |
-ref-ssr-apc <path> | 实时 SSR APC 参考流，例如 ntrip://user:password@host:2101/SSRA00BKG0 |
-ref-ssr-com <path> | 实时 SSR CoM 参考流，例如 ntrip://user:password@host:2101/SSRC00BKG0 |
SSR 流使用 RTKLIB input_rtcm3() 解析 RTCM3 SSR 改正数。单星诊断会检查 SSR orbit/clock 是否存在、IOD 是否一致、参考龄期是否超过阈值，以及 SSR IODE 是否能匹配当前广播星历。
告警类型包括 reference_missing、reference_expired、sisre_warning、sisre_alarm、clock_reference_gap 等，并保持状态去重。
常见 reference_reason 包括：
| 原因 | 含义 |
|---|---|
reference_ok | 外部参考可用 |
reference_unconfigured | 未配置 SP3/CLK 或 SSR 参考源 |
reference_epoch_missing | 当前候选星历缺少可用于对齐的参考历元 |
ssr_missing_orbit | SSR 参考流缺少轨道改正 |
ssr_missing_clock | SSR 参考流缺少钟差改正 |
ssr_iod_mismatch | SSR 轨道与钟差 IOD 不一致 |
ssr_age_exceeded | SSR 参考数据龄期超过可用范围 |
ssr_iode_mismatch | SSR IODE 与广播星历不匹配 |
Web 管理界面
EPHUB 提供独立的 Web 管理页面，访问地址：
http://127.0.0.1:5428/ephub.html
管理页面支持：
- 实时状态监控（输入/输出流状态、缓存统计）
- 输入流详情（状态、字节数、星历接收、重复/无效统计）
- 输出流详情（状态、速率、失败次数、重连次数）
- 星历缓存查询（按卫星过滤、全量查看）
HTTP API
基础地址：http://127.0.0.1:5428/
状态查询
| 方法 | 端点 | 说明 |
|---|---|---|
| GET | /api/status | 查询总览状态（输入/输出数量、缓存统计、配置） |
| GET | /api/inputs | 查询输入流详情（状态、字节数、星历接收、重复/无效统计） |
| GET | /api/outputs | 查询输出流详情（状态、速率、失败次数、重连次数） |
| GET | /api/sources | 查询当前采用星历及候选源摘要（含 decision_reason、pos_diff_m、radial_diff_m、sisre_like_m、sisre_m 等字段），支持 ?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> | 删除输入流，并清理该源候选星历 |
示例：新增输入流
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_C"}'
示例：启动/停止输入流
# 停止输入流
curl -X PATCH http://127.0.0.1:5428/api/inputs/2 \
-H "Content-Type: application/json" \
-d '{"action": "stop"}'
# 启动输入流
curl -X PATCH http://127.0.0.1:5428/api/inputs/2 \
-H "Content-Type: application/json" \
-d '{"action": "start"}'
示例：删除输入流
curl -X DELETE http://127.0.0.1:5428/api/inputs/2
输出流管理（热更新）
| 方法 | 端点 | 说明 |
|---|---|---|
| POST | /api/outputs | 运行期新增输出流，JSON body: { "path": "tcpsvr://:10011" } |
| PATCH | /api/outputs/<id> | 启停输出流，JSON body: { "action": "start" } 或 { "action": "stop" } |
| DELETE | /api/outputs/<id> | 删除输出流 |
示例：新增输出流
curl -X POST http://127.0.0.1:5428/api/outputs \
-H "Content-Type: application/json" \
-d '{"path": "tcpsvr://:10011"}'
示例：删除输出流
curl -X DELETE http://127.0.0.1:5428/api/outputs/1
告警与完整性
| 方法 | 端点 | 说明 |
|---|---|---|
| GET | /api/active-alerts | 查询当前仍未恢复的完整性/输入输出告警，包括过期/缺失星历、源间偏差、参考偏差等 |
| GET | /api/alerts | 查询最近完整性/输入输出历史事件，支持 ?limit=50 参数控制返回条数 |
质量度量与参考源
| 方法 | 端点 | 说明 |
|---|---|---|
| GET | /api/reference | 查询外部 SP3/CLK 文件存在性、加载状态、精密轨道/钟差卫星数、时间范围、最后错误，以及实时 SSR APC/CoM 参考流状态 |
| GET | /api/reference/sat?id=G01 | 查询单颗卫星外部参考诊断，包含 SSR APC/CoM 可用性、orbit/clock IOD、龄期、匹配原因和 reference_reason |
配置管理
| 方法 | 端点 | 说明 |
|---|---|---|
| POST | /api/config/save | 将当前运行配置（包括所有热更新的流）保存回 -k 加载的配置文件 |
示例：保存配置
curl -X POST http://127.0.0.1:5428/api/config/save
凭证脱敏
EPHUB 的输入/输出流、参考流、状态 API、trace 和控制台输出会脱敏 NTRIP 凭证。配置文件仍保存真实 stream path，保存和备份时仍按敏感文件处理。
与 RTKHUB 的关系
RTKHUB 负责 GNSS / RTK 解算与控制台监控；EPHUB 负责广播星历的汇集、质量控制和分发。两者可以独立运行，也可以配合使用：
- EPHUB 从多个 NTRIP 源汇集广播星历，经过去重和质量控制后输出
- RTKHUB 或其他 RTK 解算引擎通过 TCP Client 连接 EPHUB 获取稳定星历数据
- EPHUB 可以将星历推送到远程 NTRIP caster，供更大范围的用户使用