跳到主要内容

故障排查

本指南帮助你快速定位和解决常见问题。

启动问题​

无法启动 - 端口被占用​

错误信息：

Cannot start web server on port 5426
警告

端口被占用说明有其他进程正在使用该端口。请先确认是否已有 RTKHUB 实例在运行，避免重复启动导致数据冲突。

解决方法：

# 查看端口占用
netstat -ano | findstr 5426

# 结束占用进程（替换 <PID> 为实际进程 ID）
taskkill /PID <PID> /F
提示

如果端口被其他进程占用，先用 netstat -ano | findstr 5426 找到占用进程的 PID，再用 taskkill /PID <PID> /F 结束该进程，然后重新启动 RTKHUB。

配置文件错误​

检查清单：

  • 文件路径是否正确
  • 文件是否存在
  • 文件格式是否正确（UTF-8）
  • 语法是否有误

连接问题​

Web 页面无法访问​

检查清单：

  • RTKHUB 是否运行
  • 地址：http://127.0.0.1:5426
  • 防火墙是否阻止
  • 是否使用 IE（不支持）

验证方法：

# 检查进程
Get-Process rtkhub

# 检查端口
netstat -ano | findstr 5426

# 测试连接
curl http://127.0.0.1:5426
警告

数据源连接失败通常由网络不通、地址/端口错误或远端服务未启动引起。请逐项排查。

数据源无法连接​

错误信息：

stream connect error: Connection refused
提示

使用 Test-NetConnection 或 telnet 测试端口连通性。如果从服务器无法访问数据源，检查防火墙规则和网络路由。

测试连接：

# TCP 测试
Test-NetConnection 192.168.1.100 -Port 2101

# Telnet 测试
telnet 192.168.1.100 2101

定位问题​

警告

无法获取固定解是最常见的定位问题，通常与基线长度、数据质量或环境遮挡有关。请按以下步骤逐一排查。

无法获取固定解（FIX）​

1. 基线过长​

  • RTK 模式：< 20km（理想 < 10km）
  • PPP 模式：无距离限制
提示

Age 指差分数据的龄期，反映基准站修正数据的时效性。Age 越小定位精度越高，建议保持在 5 秒以内。

2. Age 过大​

标准：

  • 优秀：< 1s
  • 正常：< 5s
  • 可用：< 30s
  • 异常：> 30s

解决：

  1. 检查数据源连接
  2. 检查网络延迟
  3. 尝试其他挂载点
提示

增加可用卫星数的有效方法：启用多系统（GPS+BDS+Galileo），降低截止高度角（pos1-elmask），改善天线遮挡环境。

3. 卫星数不足​

标准：

  • 最低：5 颗
  • 推荐：≥ 8 颗
  • 理想：≥ 12 颗

解决：

1. 检查天线安装
2. 调整配置
   pos1-navsys = 5    # GPS+BDS
   pos1-elmask = 15
3. 查看卫星天空图
提示

Ratio 反映整周模糊度固定的可靠性。Ratio > 3.0 表示固定解可信，1.0-3.0 之间为浮点解，< 1.0 说明数据质量较差。

4. Ratio 不达标​

标准：

  • 固定：> 3.0
  • 浮点：1.0-3.0
  • 质量差：< 1.0

解决：

  • 增加观测时长
  • 改善环境
  • 优化配置
  • 使用双频多系统

Age 持续很大​

原因分析：

Age 范围可能原因
10-30s网络延迟
30-60s数据源中断
> 60s数据源失败

排查：

  1. 检查数据源连接
  2. 检查网络
  3. 验证 NTRIP 参数
  4. 尝试其他数据源

Ratio 很低​

改善方法：

  1. 延长观测时间（等待 1-5 分钟）
  2. 检查配置（双频、多系统）
  3. 改善环境（移除障碍物）
  4. 检查数据质量
警告

降低 Ratio 阈值可能导致伪固定！

警告

频繁失锁会导致浮点解退化，严重影响定位精度。需要从天线环境和配置参数两方面排查。

频繁失锁​

原因：

  1. 信号遮挡
  2. 多路径效应
  3. 电离层扰动
  4. 配置不当

解决：

pos2-arlockcnt = 5          # 增加锁定计数
pos2-aroutcnt = 10          # 增加失锁计数
pos2-elmaskhold = 10        # 保持模式高度角

性能问题​

提示

内存占用与基线数量成正比。关闭调试日志（-t 0）和限制历史数据保留时间可以有效降低内存消耗。

内存占用过高​

正常值：

  • 单基线：启动 14MB，稳定 5.6MB
  • 100 基线：约 560MB

优化：

  1. 关闭调试日志（-t 0）
  2. 限制历史数据
  3. 定期重启
提示

CPU 占用主要取决于采样率和基线数量。降低采样率或减少并发解算基线数可有效降低 CPU 压力。

CPU 占用过高​

正常值：单基线 < 5% CPU（1Hz）

检查：

  1. 采样率是否过高
  2. 日志是否过多
  3. 基线数是否超限
提示

定期清理旧日志和结果文件可以防止磁盘写满。建议使用 SCRHUB 的自动归档脚本进行定期清理。

磁盘占用过大​

清理：

# 清理旧日志（30天前）
$date = (Get-Date).AddDays(-30)
Get-ChildItem logs\*.trace | Where-Object { $_.LastWriteTime -lt $date } | Remove-Item

日志分析​

查看日志​

# 实时查看
Get-Content logs\rtkhub_YYYYMMDD.trace -Wait -Tail 50

# 搜索错误
Select-String -Path logs\*.trace -Pattern "error|failed"

常见日志消息​

消息含义处理
stream connect error连接失败检查地址/端口
no observation data无观测数据检查天线
age of differentialAge 过大检查差分数据
large residuals残差过大检查环境

EPHUB 问题​

警告

EPHUB 输入流连接失败会导致星历缓存为空，进而影响 RTK 解算的星历数据供给。

EPHUB 无法连接输入流​

症状：输入流状态显示断开或重连中

检查步骤：

  1. 确认 NTRIP caster 地址、端口、挂载点正确
  2. 确认用户名和密码正确（注意大小写）
  3. 检查网络连通性
  4. 查看 trace 日志（-x 3 或更高等级）
提示

将 EPHUB 的 trace 级别提升到 -x 3 或更高，可以查看详细的星历接收和过滤信息，有助于定位连接问题。

EPHUB 缓存卫星数为 0​

症状：Web 页面显示缓存卫星数为 0

可能原因：

  1. 输入流未成功连接
  2. 输入流中没有广播星历数据（只有观测数据）
  3. 缓存已过期（-maxage 设置过短）
提示

如果输入流正常但缓存仍为空，检查 -maxage 参数是否设置过短（默认 7200 秒），以及输入流是否包含广播星历数据（而不仅仅是观测数据）。

警告

EPHUB 输出端口无法连接意味着下游 RTK 解算引擎无法获取星历数据。请确认 EPHUB 进程正常运行且输出流配置正确。

EPHUB 输出端口无法连接​

症状：RTKLIB/RTKNAVI 无法连接 EPHUB 的 TCP Server 输出

检查：

netstat -ano | findstr :10010

确认 EPHUB 进程正在监听该端口。检查防火墙规则。

提示

如果 EPHUB 使用了 -noweb 参数启动，则不会提供 Web 管理界面。检查启动命令中是否包含该参数。

EPHUB Web 页面打不开​

症状：无法访问 http://127.0.0.1:5428/ephub.html

检查：

  1. 确认 EPHUB 进程已启动
  2. 确认端口 5428 未被占用
  3. 检查是否使用了 -noweb 参数禁用了 Web
提示

EPHUB Web 管理界面默认端口为 5428，可通过 -web 参数修改。如果端口被占用，EPHUB 会输出错误日志。

常见错误信息​

错误信息含义解决方法
bind failed端口已被占用结束占用进程或更换端口
database is locked数据库被锁定关闭其他实例或删除数据库
invalid configuration配置文件格式错误检查配置文件语法
connection timeoutNTRIP 连接超时检查网络和服务器地址
authentication failed认证失败检查用户名和密码
no satellite无卫星信号检查天线连接和位置

收集诊断信息​

# 创建诊断包
$date = Get-Date -Format "yyyyMMdd_HHmmss"
$diagPath = "diag_$date"
mkdir $diagPath

# 复制配置和日志
Copy-Item conf\ $diagPath\ -Recurse
Copy-Item logs\*.trace $diagPath\ -Force

# 导出进程信息
Get-Process rtkhub | Out-File $diagPath\process.txt

# 打包
Compress-Archive $diagPath diag_$date.zip

提交问题​

访问 GitHub Issues，附上：

  1. 问题描述
  2. 环境信息
  3. 配置文件（删除敏感信息）
  4. 日志片段
  5. 诊断包

相关资源​