RAILWISE-CLI 常见问题与故障排查

RAILWISE-CLI 常见问题与故障排查

目标读者：CLI 日常使用者、项目现场技术人员、运维支持人员
预计阅读时间：15 分钟
前置要求：已安装并运行过 RAILWISE-CLI

---

1. 安装与启动问题

1.1 安装失败：权限不足

现象：

bun install -g @railwise/cli
# EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@railwise'

原因：全局安装目录需要管理员权限。

解决方案：

# 方案一：使用用户级安装（推荐）
bun install -g @railwise/cli --prefix ~/.local
export PATH="$HOME/.local/bin:$PATH"

# 方案二：使用 sudo（macOS/Linux）
sudo bun install -g @railwise/cli

# 方案三：Windows 以管理员身份运行 PowerShell
# 右键 PowerShell → 以管理员身份运行

1.2 安装失败：网络超时

现象：

error: package "@railwise/cli" not found
# 或连接 registry 超时

解决方案：

# 配置国内镜像源
bun config set registry https://registry.npmmirror.com

# 或使用公司私有 registry
bun config set registry https://npm.railwise.cn

# 验证配置
bun config get registry

1.3 启动报错：Bun 版本不兼容

现象：

railwise --version
# error: Unsupported Bun version. Required: >=1.1.0, Found: 1.0.35

解决方案：

# 升级 Bun
bun upgrade

# 或重新安装
curl -fsSL https://bun.sh/install | bash

---

2. 配置问题

2.1 初始化失败：目录已存在

现象：

railwise init --project "测试项目"
# Error: .railwise directory already exists

解决方案：

# 方案一：强制重新初始化（备份后）
mv .railwise .railwise.backup.$(date +%Y%m%d)
railwise init --project "测试项目"

# 方案二：使用非交互模式，跳过已存在文件
railwise init --project "测试项目" --force --skip-existing

2.2 配置文件解析错误

现象：

railwise run workflow.yaml
# Error: YAML parse error at .railwise/config.yaml: line 23, column 5

排查步骤：

1. 检查缩进：YAML 使用空格缩进，禁止使用 Tab
2. 检查特殊字符：中文字符后的冒号需加空格 key: value
3. 验证语法：

   railwise config validate
   # 或使用在线工具 https://www.yamllint.com/

4. 常见错误示例：

   # ❌ 错误：Tab 缩进
   project:
     name: "项目"    # ← 这里用了 Tab
   
   # ✅ 正确：两个空格缩进
   project:
     name: "项目"

2.3 坐标系统配置无效

现象：导入时提示 “Unknown coordinate system: XXX”

排查清单：

检查项	命令/操作
坐标系名称拼写	railwise config get coordinate_systems.available
EPSG 代码有效性	访问 https://epsg.io/ 验证
投影参数完整性	检查 central_meridian, false_easting 等必填项
配置文件路径	确认修改的是当前项目的 .railwise/config.yaml

---

3. 数据导入问题

3.1 导入文件无响应

现象：

railwise surveyor import data/large_file.gsi
# 长时间无输出，CPU 占用高

排查步骤：

1. 检查文件大小：超大文件（>100MB）建议分批导入
2. 启用详细日志：

   railwise surveyor import data/large_file.gsi --verbose

3. 检查文件编码：

   file -i data/large_file.gsi
   # 输出应为 text/plain; charset=utf-8

4. 尝试限制导入范围：

   railwise surveyor import data/large_file.gsi --max-records 1000

3.2 数据解析错误：格式不匹配

现象：

# Error: Failed to parse record at line 156: Unknown field code "99"

解决方案：

# 方案一：跳过未知字段
railwise surveyor import data.gsi --skip-unknown-fields

# 方案二：使用通用 CSV 格式中转
# 1. 先用仪器自带软件导出为 CSV
# 2. 编写列映射文件（参见 cli-data-formats.md）
railwise surveyor import data.csv --format csv --mapping map.yaml

# 方案三：联系技术支持获取专用解析器

3.3 中文字符乱码

现象：导入后点号、备注显示为 ???? 或乱码方块。

排查与解决：

# 步骤一：检测原始文件编码
file -i data.gsi
# 输出示例：text/plain; charset=iso-8859-1

# 步骤二：转换编码
iconv -f GBK -t UTF-8 data.gsi > data_utf8.gsi
# 或
iconv -f ISO-8859-1 -t UTF-8 data.gsi > data_utf8.gsi

# 步骤三：重新导入
railwise surveyor import data_utf8.gsi --encoding utf-8

提示

for f in data/*.gsi; do
  iconv -f GBK -t UTF-8 "$f" > "${f%.gsi}_utf8.gsi"
done

---

4. 工作流执行问题

4.1 工作流执行失败：步骤超时

现象：

# Error: Step "平差计算" timed out after 300s

解决方案：

# 在工作流中增加超时设置
steps:
  - name: "平差计算"
    agent: "adjuster"
    action: "adjust"
    timeout: 600                        # 增加到 10 分钟
    # 或设为 0 表示不限制
    # timeout: 0

4.2 工作流执行失败：内存不足

现象：

# Error: JavaScript heap out of memory
# 或系统提示内存不足

解决方案：

# 方案一：增加 Node/Bun 内存限制
export BUN_JSC_memoryLimit=4096       # 4GB
railwise run workflow.yaml

# 方案二：减少并发
# 在 .railwise/config.yaml 中
performance:
  max_concurrent_agents: 1

# 方案三：分批处理大数据
steps:
  - name: "分批导入"
    agent: "surveyor"
    action: "import"
    input: "data/"
    params:
      batch_size: 500                   # 每批处理 500 条记录

4.3 条件判断不生效

现象：设置了 condition 但步骤始终执行或始终跳过。

排查清单：

检查项	说明
变量名拼写	确认与 output_var 完全一致
数据类型	条件表达式中数字与字符串比较需一致
布尔值格式	使用 true/false 而非 "true"/"false"
表达式语法	使用 == 而非 =

正确示例：

steps:
  - name: "检查"
    agent: "inspector"
    action: "check"
    output_var: "check_result"         # 输出布尔值

  - name: "条件执行"
    agent: "adjuster"
    action: "adjust"
    condition: "{{check_result}} == true"   # 正确
    # ❌ 错误：condition: "check_result == true" （缺少变量语法）

---

5. 错误代码速查表

错误代码	含义	常见原因	解决方案
RWI-001	配置文件未找到	未执行 railwise init	运行初始化命令
RWI-002	配置文件解析失败	YAML 语法错误	检查缩进、特殊字符
RWI-003	未知智能体	智能体名称拼写错误	运行 railwise agent list 查看
RWI-004	未知动作	智能体不支持该动作	查阅智能体文档
RWI-005	数据格式不支持	格式标识错误或文件损坏	检查文件头或使用 --format 指定
RWI-006	坐标系统未定义	坐标系名称拼写错误	检查 config.yaml 坐标系配置
RWI-007	文件编码错误	编码声明与实际不符	使用 file -i 检测并转换
RWI-008	限差超限	观测数据精度不足	检查仪器设置、观测条件
RWI-009	粗差探测失败	数据质量差或冗余度不足	增加观测次数或检查仪器
RWI-010	网络请求失败	外部 API 不可达	检查网络、代理配置
RWI-011	工作流循环依赖	步骤间存在循环引用	检查 input_var 引用链
RWI-012	并行步骤冲突	并行步骤输出变量重名	确保 output_var 唯一
RWI-013	插件加载失败	插件路径错误或版本不兼容	检查插件配置与 CLI 版本
RWI-014	内存不足	数据量过大或并发过高	减少批次大小、降低并发
RWI-015	磁盘空间不足	输出目录空间不足	清理磁盘或更换输出路径

---

6. 性能优化建议

6.1 大数据处理优化

场景	优化策略	预期效果
单次导入 >10万 条记录	分批导入，batch_size: 5000	减少内存峰值 60%
多期数据合并分析	使用数据库后端（SQLite/PostgreSQL）	查询速度提升 10x
重复执行相同工作流	启用缓存 cache.enabled: true	二次执行提速 80%
网络存储（NAS/SMB）数据	先复制到本地 SSD 再处理	I/O 延迟降低 90%

6.2 工作流加速配置

.railwise/config.yaml

performance:
  max_concurrent_agents: 4            # 根据 CPU 核心数调整
  enable_parallel_processing: true

cache:
  enabled: true
  ttl: 86400

logging:
  level: "warn"                       # 生产环境减少日志输出
  async: true                         # 异步日志写入

---

7. 获取帮助

7.1 内置帮助命令

# 查看全局帮助
railwise --help

# 查看子命令帮助
railwise surveyor --help
railwise surveyor import --help

# 查看智能体列表
railwise agent list

# 查看工作流语法
railwise workflow --help

7.2 日志与诊断

# 启用调试日志
railwise run workflow.yaml --verbose --log-level debug

# 导出诊断包（供技术支持分析）
railwise diagnose --output diagnostic-bundle.zip

# 查看最近执行日志
railwise logs --last 10

7.3 联系技术支持

若以上方案无法解决问题，请准备以下信息后联系技术支持：

1. 环境信息：操作系统、Bun 版本、CLI 版本（railwise --version）
2. 错误日志：执行命令加 --verbose 后的完整输出
3. 诊断包：运行 railwise diagnose 生成的压缩包
4. 数据样本：可复现问题的最小数据文件（脱敏后）

联系方式：

• 技术支持邮箱：support@railwise.cn
• 企业微信：RailWise技术支持群
• 电话：0574-XXXX-XXXX（工作日 9:00-18:00）

---

8. 相关文档

• cli-quickstart.md — 快速入门指南
• cli-agents-configuration.md — 智能体配置详解
• cli-workflow-orchestration.md — 工作流编排
• cli-data-formats.md — 数据格式与导入

---

元数据标签