PR-Helper/docs/10-troubleshooting.md

# 故障排查

## 概述

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

## 快速诊断

### 健康检查

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

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

### 查看日志

```bash
# 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
```

**解决方案**:
```bash
# 查找占用端口的进程
lsof -i :8080

# 终止进程
kill -9 <PID>

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

#### 数据库连接失败

**错误信息**:
```
failed to initialize database: dial tcp 127.0.0.1:3306: connect: connection refused
```

**解决方案**:
```bash
# 检查 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'
```

**解决方案**:
```sql
CREATE DATABASE pr_helper CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

#### 权限问题

**错误信息**:
```
permission denied
```

**解决方案**:
```bash
# 检查文件权限
ls -la pr-helper

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

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

### 2. 克隆仓库失败

#### 网络连接问题

**错误信息**:
```
dial tcp: lookup github.com: no such host
```

**解决方案**:
```bash
# 检查网络连接
ping github.com

# 检查 DNS
nslookup github.com

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

#### 认证失败

**错误信息**:
```
authentication required
```

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

#### 磁盘空间不足

**错误信息**:
```
no space left on device
```

**解决方案**:
```bash
# 检查磁盘空间
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
```

**解决方案**:
```bash
# 检查网络连接
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. 前端显示异常

#### 样式丢失

**现象**:
- 页面布局混乱
- 样式不生效

**解决方案**:
```bash
# 重新编译 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 连接断开

**现象**:
- 流式输出中断
- 无响应

**解决方案**:
```bash
# 检查网络连接
ping localhost

# 检查防火墙
sudo ufw status

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

### 6. 数据库问题

#### 连接数过多

**错误信息**:
```
too many connections
```

**解决方案**:
```sql
-- 查看当前连接数
SHOW STATUS LIKE 'Threads_connected';

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

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

#### 查询缓慢

**现象**:
- API 响应慢
- 页面加载超时

**解决方案**:
```sql
-- 查看慢查询
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
```

**解决方案**:
```bash
# 从备份恢复
mysql -u root -p pr_helper < backup.sql

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

### 7. Docker 问题

#### 容器无法启动

**错误信息**:
```
Error response from daemon: driver failed programming external connectivity
```

**解决方案**:
```bash
# 重启 Docker 服务
sudo systemctl restart docker

# 清理停止的容器
docker container prune

# 重新启动
docker compose up -d
```

#### 数据持久化问题

**现象**:
- 重启后数据丢失

**解决方案**:
```yaml
# 确保 docker-compose.yml 中配置了 volumes
services:
  app:
    volumes:
      - app-data:/app/data
  db:
    volumes:
      - mysql-data:/var/lib/mysql

volumes:
  app-data:
  mysql-data:
```

#### 网络问题

**现象**:
- 容器间无法通信

**解决方案**:
```bash
# 检查网络
docker network ls
docker network inspect pr-helper_default

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

## 性能问题

### 1. 内存使用过高

**诊断**:
```bash
# 查看内存使用
free -h
top -o %MEM

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

**解决方案**:
- 减少并发数
- 限制 Top-N
- 增加系统内存

### 2. CPU 使用过高

**诊断**:
```bash
# 查看 CPU 使用
top -o %CPU
htop
```

**解决方案**:
- 减少并发数
- 优化数据库查询
- 使用更快的 LLM API

### 3. 磁盘 I/O 过高

**诊断**:
```bash
# 查看磁盘 I/O
iostat -x 1
iotop
```

**解决方案**:
- 使用 SSD
- 优化数据库索引
- 定期清理旧数据

## 安全问题

### 1. 未授权访问

**现象**:
- 陌生人访问了服务

**解决方案**:
- 配置防火墙
- 使用反向代理认证
- 不要暴露到公网

### 2. SQL 注入

**预防**:
- 使用参数化查询
- 验证输入数据
- 限制数据库权限

### 3. XSS 攻击

**预防**:
- 转义输出内容
- 使用 CSP 头
- 验证输入数据

## 调试工具

### 1. 日志级别

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

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

### 2. 数据库调试

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

# 查看表结构
DESCRIBE analyses;

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

# 查看慢查询
SHOW PROCESSLIST;
```

### 3. 网络调试

```bash
# 测试 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. 前端调试

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

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

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

## 获取帮助

### 1. 收集信息

在报告问题时，请提供：

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

### 2. 检查已知问题

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

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

### 3. 社区支持

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

## 预防措施

### 1. 定期备份

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

### 2. 监控告警

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

### 3. 更新维护

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

### 4. 文档记录

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