docs: 添加 10 份技术文档，README 改为中文

- 01-architecture.md: 架构概览 - 02-backend-services.md: 后端服务层 - 03-frontend-interaction.md: 前端交互设计 - 04-database-design.md: 数据库设计 - 05-api-reference.md: API 接口文档 - 06-sse-streaming.md: SSE 流式传输 - 07-llm-integration.md: LLM 集成 - 08-deployment.md: 部署运维 - 09-development-guide.md: 开发指南 - 10-troubleshooting.md: 故障排查
2026-06-23 22:38:43 +08:00
parent 6f0fabf934
commit 275e5cc886
11 changed files with 4877 additions and 87 deletions
@@ -0,0 +1,591 @@
+# 故障排查
+
+## 概述
+
+本文档提供 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. 文档记录
+
+- 记录配置变更
+- 记录故障处理
+- 更新运维手册