PR-Helper/docs/10-troubleshooting.md

故障排查

概述

本文档提供 PR-Helper 常见问题的诊断和解决方案。

快速诊断

健康检查

# 检查服务状态
curl http://localhost:8080/

# 检查数据库连接
curl http://localhost:8080/api/repos

查看日志

# systemd 日志
sudo journalctl -u pr-helper -f

# Docker 日志
docker compose logs -f app

# 直接运行时的输出
./pr-helper 2>&1 | tee app.log

常见问题

1. 服务无法启动

端口被占用

错误信息:

listen tcp :8080: bind: address already in use

解决方案:

# 查找占用端口的进程
lsof -i :8080

# 终止进程
kill -9 <PID>

# 或使用其他端口
PORT=8081 ./pr-helper

数据库连接失败

错误信息:

failed to initialize database: dial tcp 127.0.0.1:3306: connect: connection refused

解决方案:

# 检查 MySQL 服务状态
sudo systemctl status mysql

# 启动 MySQL
sudo systemctl start mysql

# 验证连接参数
mysql -u root -p -h 127.0.0.1 -P 3306 pr_helper

# 检查 .env 配置
cat .env | grep MYSQL

数据库不存在

错误信息:

Unknown database 'pr_helper'

解决方案:

CREATE DATABASE pr_helper CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

权限问题

错误信息:

permission denied

解决方案:

# 检查文件权限
ls -la pr-helper

# 添加执行权限
chmod +x pr-helper

# 检查数据目录权限
ls -la data/
chmod -R 755 data/

2. 克隆仓库失败

网络连接问题

错误信息:

dial tcp: lookup github.com: no such host

解决方案:

# 检查网络连接
ping github.com

# 检查 DNS
nslookup github.com

# 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

认证失败

错误信息:

authentication required

解决方案:

• 确认仓库 URL 正确
• 检查认证类型（none/https）
• 验证用户名和密码
• 对于私有仓库，使用个人访问令牌

磁盘空间不足

错误信息:

no space left on device

解决方案:

# 检查磁盘空间
df -h

# 清理旧仓库
curl -X DELETE http://localhost:8080/api/repos/1

# 或手动清理
rm -rf data/repos/*

3. PR 生成失败

LLM API 密钥未配置

错误信息:

LLM API key not configured — please set it in the settings page

解决方案:

1. 访问设置页面 /settings
2. 配置 LLM API 密钥
3. 保存设置

LLM API 调用失败

错误信息:

create stream: Post "https://api.deepseek.com/v1/chat/completions": dial tcp: lookup api.deepseek.com: no such host

解决方案:

# 检查网络连接
curl https://api.deepseek.com/v1/models

# 验证 API 密钥
curl https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer sk-..."

# 检查端点配置
# 访问 /settings 确认 llm.endpoint 正确

差异过大

错误信息:

diff truncated due to size

说明:

• 差异超过 60k 字符会被截断
• 这是正常行为，不影响功能

优化建议:

• 减少变更范围
• 分多次提交

4. 代码审查失败

文件数过多

现象:

• 审查时间过长
• 内存使用过高

解决方案:

• 调整 Top-N 设置（默认 20）
• 在请求中指定较小的 top_n 值

并发数过高

现象:

• LLM API 限流
• 响应时间过长

解决方案:

• 降低并发数设置（默认 5）
• 在请求中指定较小的 concurrency 值

JSON 解析失败

错误信息:

invalid character '<' looking for beginning of value

说明:

• LLM 返回了非 JSON 格式的内容
• 系统会自动降级处理

解决方案:

• 检查 LLM 模型是否支持 JSON 输出
• 尝试使用其他模型

5. 前端显示异常

样式丢失

现象:

• 页面布局混乱
• 样式不生效

解决方案:

# 重新编译 Tailwind CSS
npx tailwindcss -i ./static/css/input.css -o ./static/css/style.css --minify

# 清除浏览器缓存
# Chrome: Ctrl+Shift+Delete

JavaScript 错误

现象:

• 功能不工作
• 控制台报错

解决方案:

1. 打开浏览器开发者工具 (F12)
2. 查看 Console 面板的错误信息
3. 检查 Network 面板的请求状态

SSE 连接断开

现象:

• 流式输出中断
• 无响应

解决方案:

# 检查网络连接
ping localhost

# 检查防火墙
sudo ufw status

# 检查 Nginx 配置（如果有）
# 确保 proxy_buffering off;

6. 数据库问题

连接数过多

错误信息:

too many connections

解决方案:

-- 查看当前连接数
SHOW STATUS LIKE 'Threads_connected';

-- 增加最大连接数
SET GLOBAL max_connections = 200;

-- 或修改 my.cnf
-- max_connections = 200

查询缓慢

现象:

• API 响应慢
• 页面加载超时

解决方案:

-- 查看慢查询
SHOW VARIABLES LIKE 'slow_query_log';
SET GLOBAL slow_query_log = 'ON';

-- 分析查询
EXPLAIN SELECT * FROM analyses WHERE repo_id = 1;

-- 添加索引
CREATE INDEX idx_analyses_repo_id ON analyses(repo_id);

数据损坏

错误信息:

Table 'pr_helper.analyses' doesn't exist

解决方案:

# 从备份恢复
mysql -u root -p pr_helper < backup.sql

# 或重新初始化
# 删除数据库并重启服务

7. Docker 问题

容器无法启动

错误信息:

Error response from daemon: driver failed programming external connectivity

解决方案:

# 重启 Docker 服务
sudo systemctl restart docker

# 清理停止的容器
docker container prune

# 重新启动
docker compose up -d

数据持久化问题

现象:

• 重启后数据丢失

解决方案:

# 确保 docker-compose.yml 中配置了 volumes
services:
  app:
    volumes:
      - app-data:/app/data
  db:
    volumes:
      - mysql-data:/var/lib/mysql

volumes:
  app-data:
  mysql-data:

网络问题

现象:

• 容器间无法通信

解决方案:

# 检查网络
docker network ls
docker network inspect pr-helper_default

# 重启网络
docker compose down
docker compose up -d

性能问题

1. 内存使用过高

诊断:

# 查看内存使用
free -h
top -o %MEM

# 查看进程内存
ps aux | grep pr-helper

解决方案:

• 减少并发数
• 限制 Top-N
• 增加系统内存

2. CPU 使用过高

诊断:

# 查看 CPU 使用
top -o %CPU
htop

解决方案:

• 减少并发数
• 优化数据库查询
• 使用更快的 LLM API

3. 磁盘 I/O 过高

诊断:

# 查看磁盘 I/O
iostat -x 1
iotop

解决方案:

• 使用 SSD
• 优化数据库索引
• 定期清理旧数据

安全问题

1. 未授权访问

现象:

• 陌生人访问了服务

解决方案:

• 配置防火墙
• 使用反向代理认证
• 不要暴露到公网

2. SQL 注入

预防:

• 使用参数化查询
• 验证输入数据
• 限制数据库权限

3. XSS 攻击

预防:

• 转义输出内容
• 使用 CSP 头
• 验证输入数据

调试工具

1. 日志级别

# 设置调试模式
GIN_MODE=debug ./pr-helper

# 查看详细日志
./pr-helper 2>&1 | tee debug.log

2. 数据库调试

# 连接数据库
mysql -u root -p pr_helper

# 查看表结构
DESCRIBE analyses;

# 查看数据
SELECT * FROM analyses LIMIT 10;

# 查看慢查询
SHOW PROCESSLIST;

3. 网络调试

# 测试 API
curl -v http://localhost:8080/api/repos

# 测试 SSE
curl -N http://localhost:8080/api/repos/1/review \
  -H "Content-Type: application/json" \
  -d '{"base":"main","head":"feature"}'

# 抓包
sudo tcpdump -i lo port 8080

4. 前端调试

// 在浏览器控制台中
console.log('Debug info');

// 查看 SSE 连接
// Network 面板 → EventStream

// 查看 HTMX 请求
// Network 面板 → XHR

获取帮助

1. 收集信息

在报告问题时，请提供：

• 错误信息
• 复现步骤
• 环境信息（OS、Go 版本、MySQL 版本）
• 日志输出
• 配置文件（去除敏感信息）

2. 检查已知问题

# 查看 GitHub Issues
# https://github.com/your-org/pr-helper/issues

# 搜索类似问题
# 使用关键词搜索

3. 社区支持

• GitHub Issues: 报告 Bug
• GitHub Discussions: 提问和讨论
• Stack Overflow: 技术问题

预防措施

1. 定期备份

# 每日备份
0 2 * * * /opt/pr-helper/backup.sh

2. 监控告警

• 设置资源使用告警
• 监控错误率
• 监控响应时间

3. 更新维护

• 定期更新依赖
• 应用安全补丁
• 测试新版本

4. 文档记录

• 记录配置变更
• 记录故障处理
• 更新运维手册