开发者故障排查指南

开发者故障排查指南

适用产品: RAILWISE-CLI | WorkWise | RAILWISE-TSM | RAILWISE-OS
目标读者: 开发者、DevOps工程师、技术支持工程师
阅读时间: 约40分钟

---

1. 概述

1.1 文档目的

本文档为RailWise全产品栈的开发者提供系统化的故障排查指南。涵盖安装配置、运行时错误、性能问题、数据异常等常见场景，帮助开发者快速定位并解决问题。

1.2 排查方法论

问题报告
    │
    ▼
┌─────────────┐
│ 1. 信息收集 │ ← 日志、配置、环境、复现步骤
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 2. 问题分类 │ ← 安装/运行/性能/数据/网络
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 3. 快速诊断 │ ← 对照常见问题表、使用诊断工具
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 4. 深度排查 │ ← 日志分析、调试、代码审查
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 5. 解决方案 │ ← 应用修复、验证、记录
└─────────────┘

1.3 产品范围

产品	技术栈	常见问题类别
RAILWISE-CLI	TypeScript/Bun	安装、命令执行、AI调用、配置
WorkWise	Tauri/Rust + React	安装、桌面集成、AI功能、更新
RAILWISE-TSM	Next.js/NestJS/Rust/WASM	部署、API、实时数据、WASM计算
RAILWISE-OS	Vue3/Java/Python/PostgreSQL	部署、数据库、业务逻辑、报表

---

2. RAILWISE-CLI 故障排查

2.1 安装问题

问题：安装脚本执行失败

症状：

curl -fsSL https://cli.railwise.cn/install.sh | bash
# 返回：curl: (6) Could not resolve host

排查步骤：

1. 检查网络连接

   ping cli.railwise.cn
   curl -I https://cli.railwise.cn/install.sh

2. 检查DNS解析

   nslookup cli.railwise.cn
   dig cli.railwise.cn

3. 使用代理（如需要）

   export HTTPS_PROXY=http://proxy.company.com:8080
   curl -fsSL https://cli.railwise.cn/install.sh | bash

4. 手动安装

   # 下载安装包
   wget https://cli.railwise.cn/releases/latest/railwise-cli-linux-x64.tar.gz
   
   # 解压到本地目录
   tar -xzf railwise-cli-linux-x64.tar.gz -C ~/.local/bin
   
   # 添加到PATH
   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

问题：Bun运行时错误

症状：

railwise --version
# 返回：error: Cannot find module 'bun' or corresponding type declarations

解决方案：

# 检查Bun安装
bun --version
# 应返回：1.1.x

# 如果未安装
curl -fsSL https://bun.sh/install | bash

# 如果版本过低
bun upgrade

# 重新安装CLI依赖
railwise doctor --fix

2.2 命令执行问题

问题：命令返回“未授权”

症状：

railwise project list
# 返回：Error: 401 Unauthorized - Invalid API key

排查步骤：

1. 检查API Key配置

   railwise config get api_key
   # 或查看环境变量
   echo $RAILWISE_API_KEY

2. 验证API Key有效性

   railwise auth verify

3. 重新配置

   railwise config set api_key YOUR_API_KEY
   # 或
   export RAILWISE_API_KEY="YOUR_API_KEY"

4. 检查API Key权限

   railwise auth status
   # 查看权限范围

问题：AI命令超时

症状：

railwise ai analyze --point MP-01
# 返回：Error: Request timeout after 30000ms

解决方案：

# 增加超时时间
railwise ai analyze --point MP-01 --timeout 60000

# 或全局配置
railwise config set ai_timeout 60000

# 检查网络延迟
railwise network ping

# 使用本地模型（离线场景）
railwise ai analyze --point MP-01 --model local-llama

2.3 配置问题

配置文件验证

# 验证配置文件语法
railwise config validate

# 查看完整配置
railwise config dump

# 重置为默认配置
railwise config reset --confirm

# 导出配置用于排查
railwise config export --output config-debug.json

环境变量冲突

# 检查环境变量优先级
railwise config env --verbose

# 常见冲突
# 1. RAILWISE_API_KEY vs 配置文件中的api_key
# 环境变量优先级高于配置文件

# 2. HTTPS_PROXY vs NO_PROXY
# 确保api.railwise.cn在NO_PROXY中（如使用内部API）
export NO_PROXY="localhost,127.0.0.1,api.railwise.cn"

2.4 日志与调试

启用详细日志

# 全局详细模式
export RAILWISE_LOG_LEVEL=debug

# 单命令详细模式
railwise --verbose project list

# 调试模式（包含内部状态）
railwise --debug ai analyze --point MP-01

# 日志输出到文件
railwise --log-file ./railwise-debug.log project list

日志分析

# 查看最近错误
railwise logs --level error --last 1h

# 追踪特定命令
railwise logs --command "ai analyze" --follow

# 导出日志用于支持
railwise logs --export --since "2026-07-01" --output support-logs.zip

---

3. WorkWise 故障排查

3.1 安装与启动问题

问题：应用无法启动

症状：双击应用图标无反应，或启动后立即崩溃。

macOS排查：

# 检查控制台日志
Console.app → 崩溃报告

# 查看应用日志
tail -f ~/Library/Logs/RailWise/WorkWise/main.log

# 重置应用状态
rm -rf ~/Library/Application\ Support/RailWise/WorkWise

# 检查权限
ls -la /Applications/WorkWise.app
# 确保有执行权限
chmod +x /Applications/WorkWise.app/Contents/MacOS/WorkWise

Windows排查：

# 查看事件查看器
eventvwr.msc → Windows日志 → 应用程序

# 查看应用日志
Get-Content "$env:APPDATA\RailWise\WorkWise\logs\main.log" -Tail 50

# 重置应用状态
Remove-Item -Recurse "$env:APPDATA\RailWise\WorkWise"

# 以管理员身份运行
# 右键 → 以管理员身份运行

问题：更新失败

症状：自动更新下载完成后无法安装，或版本号未变化。

解决方案：

# macOS
# 1. 手动下载最新版本
# 2. 替换Applications目录中的.app
# 3. xattr -cr /Applications/WorkWise.app

# Windows
# 1. 关闭WorkWise
# 2. 下载安装包
# 3. 运行安装程序（会自动替换）

# 通用：强制检查更新
WorkWise → 设置 → 关于 → 检查更新

# 跳过当前版本（如更新有问题）
# 设置 → 更新 → 跳过版本

3.2 AI功能问题

问题：AI助手无响应

排查步骤：

1. 检查AI配置

   WorkWise → 设置 → AI → 模型配置
   - 确认API Key已配置
   - 确认模型可用
   - 测试连接

2. 检查网络连接

   WorkWise → 设置 → 网络 → 测试连接
   - 测试与API服务的连接
   - 检查代理设置

3. 查看AI日志

   # macOS
   tail -f ~/Library/Logs/RailWise/WorkWise/ai.log
   
   # Windows
   Get-Content "$env:APPDATA\RailWise\WorkWise\logs\ai.log" -Tail 50

4. 重置AI会话

   AI面板 → 设置 → 清除会话历史

问题：MCP工具无法使用

症状：AI助手提示“无法找到工具”或工具调用失败。

排查步骤：

1. 检查MCP Server状态

   railwise mcp status

2. 检查WorkWise MCP配置

   WorkWise → 设置 → AI → MCP → 配置
   - 确认MCP Server路径正确
   - 确认环境变量已设置

3. 重新加载MCP工具

   AI面板 → 工具 → 重新加载

4. 查看MCP日志

   tail -f ~/.railwise/logs/mcp-server.log

3.3 性能问题

问题：应用卡顿

排查方法：

# macOS - 查看资源占用
Activity Monitor → 搜索"WorkWise"
# 关注CPU、内存、磁盘使用情况

# Windows - 查看资源占用
任务管理器 → 详细信息 → WorkWise.exe

# 查看渲染性能
WorkWise → 帮助 → 开发者工具 → Performance
# 记录性能分析，查看长任务

优化建议：

问题	原因	解决方案
启动慢	数据加载量大	启用懒加载，减少初始数据
界面卡顿	大量图表渲染	限制同时显示的图表数量
内存占用高	历史数据缓存	清理缓存，调整缓存策略
响应慢	后台任务阻塞	将耗时任务移至后台线程

---

4. RAILWISE-TSM 故障排查

4.1 部署问题

问题：Docker部署失败

症状：

docker-compose up -d
# 返回：Error: No such image: railwise-tsm:latest

排查步骤：

# 1. 检查镜像是否存在
docker images | grep railwise

# 2. 拉取镜像
docker pull registry.railwise.cn/railwise-tsm:latest

# 3. 检查docker-compose配置
docker-compose config

# 4. 查看构建日志
docker-compose build --no-cache 2>&1 | tee build.log

# 5. 检查端口冲突
netstat -tlnp | grep 3000
# 或
lsof -i :3000

问题：NestJS服务启动失败

症状：

[Nest] 12345  - 07/08/2026, 8:00:00 PM   ERROR [ExceptionHandler]
Unable to connect to the database.

排查步骤：

# 1. 检查数据库连接
pg_isready -h localhost -p 5432 -U railwise

# 2. 检查环境变量
cat .env | grep DATABASE
# 确认：DATABASE_URL、DATABASE_HOST、DATABASE_PORT等

# 3. 检查数据库迁移
npm run migration:status

# 4. 执行迁移
npm run migration:run

# 5. 查看详细日志
npm run start:dev 2>&1 | tee nestjs.log

4.2 实时数据问题

问题：WebSocket连接断开

症状：监测数据不再实时更新，控制台显示WebSocket错误。

排查步骤：

# 1. 检查WebSocket服务
ws://localhost:3001/ws/monitoring
# 使用在线工具测试连接

# 2. 检查Nginx配置（如使用）
cat /etc/nginx/conf.d/railwise.conf | grep websocket
# 确保proxy_pass和upgrade头正确

# 3. 查看WebSocket日志
tail -f /var/log/railwise/websocket.log

# 4. 检查Redis（如使用Pub/Sub）
redis-cli ping
redis-cli pubsub channels

Nginx配置示例：

location /ws/ {
    proxy_pass http://localhost:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 86400;
}

问题：WASM计算错误

症状：前端计算功能报错，控制台显示WASM相关错误。

排查步骤：

# 1. 检查WASM文件
ls -la public/wasm/
# 确认.railwise_calc.wasm存在

# 2. 检查MIME类型
curl -I http://localhost:3000/wasm/railwise_calc.wasm
# 确保Content-Type: application/wasm

# 3. 检查浏览器兼容性
# Chrome/Edge/Firefox/Safari均支持WASM
# 检查版本是否过旧

# 4. 查看WASM加载日志
# 浏览器开发者工具 → Console → 筛选"wasm"

# 5. 重新构建WASM
cd rust/calc-engine
wasm-pack build --target web

4.3 API问题

问题：API返回500错误

排查步骤：

# 1. 查看错误日志
tail -f /var/log/railwise/api-error.log

# 2. 检查请求格式
curl -X POST http://localhost:3000/api/v2/measurements \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"point_id":"MP-01"}' \
  -v

# 3. 检查数据库连接池
# 查看是否有连接池耗尽

# 4. 检查内存使用
free -h
# 或
docker stats railwise-tsm-api

---

5. RAILWISE-OS 故障排查

5.1 数据库问题

问题：PostgreSQL连接失败

症状：

org.postgresql.util.PSQLException: Connection to localhost:5432 refused

排查步骤：

# 1. 检查PostgreSQL服务
sudo systemctl status postgresql
# 或
docker ps | grep postgres

# 2. 检查连接配置
cat application.yml | grep -A 5 datasource

# 3. 测试连接
psql -h localhost -U railwise -d railwise_os -c "SELECT 1"

# 4. 检查连接池
# 查看HikariCP日志
# 确认max_pool_size、connection_timeout配置

# 5. 检查防火墙
sudo ufw status
# 或
sudo iptables -L | grep 5432

问题：数据库性能慢

排查步骤：

-- 查看慢查询
SELECT query, calls, mean_time, total_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

-- 查看锁等待
SELECT * FROM pg_locks WHERE NOT granted;

-- 查看连接数
SELECT count(*) FROM pg_stat_activity;

-- 查看表膨胀
SELECT schemaname, relname, n_live_tup, n_dead_tup
FROM pg_stat_user_tables
WHERE n_dead_tup > 1000;

优化建议：

问题	解决方案
缺少索引	CREATE INDEX CONCURRENTLY idx_name ON table(column);
查询未优化	使用EXPLAIN ANALYZE分析，优化SQL
连接池过小	增加HikariCP的maximum-pool-size
表数据量大	考虑分区表、归档历史数据
统计信息过期	ANALYZE table_name;

5.2 Vue3前端问题

问题：构建失败

症状：

npm run build
# 返回：Error: Cannot find module '@vue/...'

排查步骤：

# 1. 清理依赖
rm -rf node_modules package-lock.json
npm install

# 2. 检查Node版本
node --version
# 要求：≥ 18.0.0

# 3. 检查Vite配置
cat vite.config.ts
# 确认路径别名、代理配置正确

# 4. 查看详细错误
npm run build -- --debug

# 5. 检查类型错误
npm run type-check

问题：API请求失败

排查步骤：

# 1. 检查代理配置
cat vite.config.ts | grep proxy
# 确认开发服务器代理到后端API

# 2. 检查环境变量
cat .env.development
# 确认VITE_API_BASE_URL

# 3. 检查CORS配置
# 浏览器Console查看CORS错误
# 后端配置允许前端域名

# 4. 网络面板检查
# 浏览器开发者工具 → Network → 查看请求详情

5.3 Java后端问题

问题：Spring Boot启动失败

症状：

Error starting ApplicationContext. To display the conditions report re-run
with 'debug' enabled.

排查步骤：

# 1. 启用调试启动
java -jar -Ddebug railwise-os.jar

# 2. 检查配置文件
cat application.yml
# 确认所有必需配置项已设置

# 3. 检查端口占用
netstat -tlnp | grep 8080

# 4. 检查依赖冲突
mvn dependency:tree | grep conflict

# 5. 查看完整堆栈跟踪
# 日志中查找Caused by:

问题：内存溢出（OOM）

症状：

java.lang.OutOfMemoryError: Java heap space

解决方案：

# 1. 增加堆内存
java -Xms2g -Xmx4g -jar railwise-os.jar

# 2. 启用GC日志
java -Xms2g -Xmx4g \
  -Xlog:gc*:file=gc.log:time,uptime,level,tags \
  -jar railwise-os.jar

# 3. 生成堆转储
java -Xms2g -Xmx4g \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/var/log/railwise/heapdump.hprof \
  -jar railwise-os.jar

# 4. 分析堆转储
# 使用Eclipse MAT或VisualVM分析

---

6. 通用网络问题

6.1 连接问题诊断

# 完整诊断流程
# 1. DNS解析
dig api.railwise.cn

# 2. 网络连通性
ping api.railwise.cn

# 3. 端口连通性
telnet api.railwise.cn 443
# 或
nc -zv api.railwise.cn 443

# 4. TLS握手
curl -v https://api.railwise.cn/health

# 5. 完整请求
curl -w "\nHTTP_CODE: %{http_code}\nTIME_TOTAL: %{time_total}\n" \
  https://api.railwise.cn/health

# 6. 使用RailWise诊断工具
railwise network diagnose --target api.railwise.cn

6.2 代理配置

# HTTP代理
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY="localhost,127.0.0.1,*.railwise.cn"

# SOCKS5代理
export ALL_PROXY=socks5://127.0.0.1:1080

# 验证代理
curl -x $HTTP_PROXY https://api.railwise.cn/health

# RailWise CLI代理配置
railwise config set proxy.http http://proxy.company.com:8080
railwise config set proxy.https http://proxy.company.com:8080
railwise config set proxy.no_proxy "localhost,127.0.0.1,*.railwise.cn"

---

7. 诊断工具

7.1 RailWise CLI诊断工具

# 完整系统诊断
railwise doctor

# 检查特定组件
railwise doctor --component cli
railwise doctor --component network
railwise doctor --component ai

# 自动修复常见问题
railwise doctor --fix

# 生成诊断报告
railwise doctor --report --output diagnosis-report.html

7.2 日志收集工具

# 收集所有日志
railwise logs collect --all --output logs.zip

# 收集特定时间范围
railwise logs collect --since "2026-07-01" --until "2026-07-08" --output logs.zip

# 收集特定组件日志
railwise logs collect --component tsm --component os --output logs.zip

7.3 性能分析工具

# CLI性能分析
railwise benchmark --command "project list" --iterations 10

# API性能测试
railwise benchmark --endpoint /api/v2/projects --method GET --iterations 100

# AI响应时间测试
railwise benchmark --command "ai analyze --point MP-01" --iterations 5

---

8. 常见问题速查表

8.1 快速解决方案索引

问题	产品	快速解决
命令未找到	CLI	export PATH="$HOME/.local/bin:$PATH"
401未授权	全部	检查API Key，railwise auth verify
连接超时	全部	检查网络，railwise network ping
数据库连接失败	TSM/OS	检查服务状态，验证连接字符串
WASM加载失败	TSM	检查文件存在，MIME类型
构建失败	OS	rm -rf node_modules && npm install
内存溢出	OS	增加-Xmx参数
应用崩溃	WorkWise	查看日志，重置应用状态
AI无响应	WorkWise/CLI	检查配置，测试网络
端口冲突	TSM	lsof -i :PORT，更换端口

8.2 错误码速查

错误码	含义	解决方案
400	请求参数错误	检查请求体格式和必填字段
401	未授权	检查API Key和权限
403	禁止访问	检查资源权限和访问控制
404	资源不存在	检查URL路径和ID
409	资源冲突	检查唯一性约束
422	验证失败	检查数据格式和业务规则
429	请求过多	降低请求频率，检查限流策略
500	服务器错误	查看服务器日志
502	网关错误	检查上游服务状态
503	服务不可用	检查服务是否启动
504	网关超时	检查网络和后端响应时间

---

9. 获取帮助

9.1 自助资源

• 文档中心: https://docs.railwise.cn
• API参考: https://api.railwise.cn/docs
• 状态页面: https://status.railwise.cn
• 社区论坛: https://community.railwise.cn

9.2 联系支持

技术支持邮箱: support@railwise.cn

提交工单时请包含：

1. 问题描述和复现步骤
2. 产品名称和版本号
3. 操作系统和版本
4. 错误日志（关键部分）
5. 诊断报告（railwise doctor --report）
6. 截图（如适用）

9.3 紧急联系

紧急技术热线: 400-XXX-XXXX（工作日 9:00-18:00）

紧急问题定义：

• 生产环境完全不可用
• 数据丢失或损坏
• 安全漏洞

---

10. 相关文档

• RAILWISE-CLI开发指南 — CLI工具详细文档
• WorkWise用户手册 — 桌面端使用指南
• RAILWISE-TSM部署指南 — 平台部署文档
• RAILWISE-OS开发手册 — 业务OS开发文档
• API REST概述 — REST API参考
• MCP Server概述 — MCP集成指南

---

11. 更新日志

版本	日期	变更内容
1.0.0	2026-07-08	初始版本，涵盖CLI、WorkWise、TSM、OS四大产品故障排查

---

本文档由RailWise技术团队维护，如有疑问请联系技术支持：support@railwise.cn