9.4 KiB

Raw Blame History

常见问题 (FAQ)

本文档收集了 XCodeReviewer 使用过程中的常见问题和解决方案。

快速入门

Q: 如何快速开始使用？

最快的方式是使用 Docker Compose：

# 1. 克隆项目
git clone https://github.com/lintsinghua/XCodeReviewer.git
cd XCodeReviewer

# 2. 配置 LLM API Key
cp backend/env.example backend/.env
# 编辑 backend/.env，填入你的 API Key

# 3. 启动服务
docker-compose up -d

# 4. 访问 http://localhost:5173

Q: 演示账户是什么？

系统启动时会自动创建演示账户，包含示例项目和审计数据：

📧 邮箱：demo@example.com
🔑 密码：demo123

演示账户拥有管理员权限，可体验所有功能。生产环境请删除或修改密码。

Q: 不想用 Docker，如何本地运行？

参见部署指南 - 本地开发部署。

Q: 支持哪些编程语言？

XCodeReviewer 支持所有主流编程语言的代码分析，包括但不限于：

Web: JavaScript, TypeScript, HTML, CSS
后端: Python, Java, Go, Rust, C/C++, C#
移动端: Swift, Kotlin, Dart
脚本: Shell, PowerShell, Ruby, PHP
其他: SQL, YAML, JSON, Markdown

LLM 配置

Q: 如何快速切换 LLM 平台？

方式一：浏览器运行时配置（推荐）

访问 http://localhost:5173/admin 系统管理页面
在"系统配置"标签页选择不同的 LLM 提供商
填入对应的 API Key
保存即可，无需重启

方式二：修改后端环境变量

编辑 backend/.env：

# 切换到 OpenAI
LLM_PROVIDER=openai
LLM_API_KEY=sk-your-key

# 切换到通义千问
LLM_PROVIDER=qwen
LLM_API_KEY=sk-your-dashscope-key

# 切换到 DeepSeek
LLM_PROVIDER=deepseek
LLM_API_KEY=sk-your-key

修改后需要重启后端服务。

Q: 百度文心一言的 API Key 格式是什么？

百度需要同时提供 API Key 和 Secret Key，用冒号分隔：

LLM_PROVIDER=baidu
LLM_API_KEY=your_api_key:your_secret_key
LLM_MODEL=ernie-bot-4

获取地址：https://console.bce.baidu.com/qianfan/

Q: 如何使用 Ollama 本地大模型？

# 1. 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh  # macOS/Linux
# Windows: 访问 https://ollama.com/download

# 2. 拉取模型
ollama pull llama3  # 或 codellama、qwen2.5、deepseek-coder

# 3. 确保 Ollama 服务运行
ollama serve

# 4. 配置后端
# 在 backend/.env 中设置：
LLM_PROVIDER=ollama
LLM_MODEL=llama3
LLM_BASE_URL=http://localhost:11434/v1

推荐模型：

llama3 - 综合能力强
codellama - 代码专用
qwen2.5 - 中文支持好
deepseek-coder - 代码分析强

Q: 哪个 LLM 平台性价比最高？

场景	推荐	原因
免费使用	Gemini / 智谱 GLM-4-Flash	有免费配额
低成本	DeepSeek	价格仅为 GPT-4 的 1/10
最佳性能	GPT-4o / Claude Sonnet	代码理解能力最强
敏感代码	Ollama 本地模型	完全本地化

网络问题

Q: 遇到请求超时怎么办？

方案一：增加超时时间

LLM_TIMEOUT=300  # 增加到 300 秒

方案二：使用 API 中转站

LLM_PROVIDER=openai
LLM_API_KEY=中转站提供的Key
LLM_BASE_URL=https://your-proxy.com/v1

方案三：切换到国内平台

通义千问、DeepSeek、智谱 AI 等国内平台访问更稳定。

方案四：降低并发

LLM_CONCURRENCY=1  # 降低并发数
LLM_GAP_MS=3000    # 增加请求间隔

Q: 如何配置 API 中转站？

LLM_PROVIDER=openai
LLM_API_KEY=中转站提供的Key
LLM_BASE_URL=https://your-proxy.com/v1
LLM_MODEL=gpt-4o-mini

常见中转站：

Q: 提示 "API Key 无效" 怎么办？

检查 API Key 是否正确复制（注意前后空格）
确认 API Key 未过期或被禁用
检查 LLM_PROVIDER 是否与 API Key 匹配
如果使用中转站，确认 LLM_BASE_URL 配置正确

功能使用

Q: 如何分析 GitHub/GitLab 仓库？

在"项目管理"页面点击"添加项目"
选择"GitHub 仓库"或"GitLab 仓库"
输入仓库 URL（如 https://github.com/user/repo）
如果是私有仓库，需要配置 Token：
- GitHub: 在 backend/.env 中设置 GITHUB_TOKEN
- GitLab: 在 backend/.env 中设置 GITLAB_TOKEN

Q: 如何上传 ZIP 文件分析？

在"项目管理"页面点击"添加项目"
选择"上传 ZIP"
选择本地 ZIP 文件上传
系统会自动解压并分析

Q: 如何使用即时分析功能？

访问"即时分析"页面
直接粘贴代码片段
选择编程语言
点击"分析"按钮

Q: 如何导出审计报告？

完成代码分析后，进入"审计报告"页面
点击"导出"按钮
选择导出格式：
- JSON: 结构化数据，适合程序处理
- PDF: 专业报告，适合交付

Q: 分析结果不准确怎么办？

切换更强的模型：如 GPT-4o、Claude Sonnet
调整温度参数：降低 LLM_TEMPERATURE 到 0.1 以下
增加上下文：确保代码文件完整
人工复核：AI 分析结果仅供参考，建议结合人工审查

部署问题

Q: Docker 容器启动失败？

端口被占用：

# 检查端口占用
lsof -i :5173
lsof -i :8000
lsof -i :5432

# 停止占用进程或修改 docker-compose.yml 中的端口

数据库连接失败：

# 确保数据库先启动
docker-compose up -d db
docker-compose exec db pg_isready -U postgres
docker-compose up -d backend

Q: Windows 导出 PDF 报错怎么办？

PDF 导出功能使用 WeasyPrint 库，在 Windows 系统上需要安装 GTK 依赖。

方法一：使用 MSYS2 安装（推荐）

# 1. 下载并安装 MSYS2: https://www.msys2.org/
# 2. 打开 MSYS2 终端，执行：
pacman -S mingw-w64-x86_64-pango mingw-w64-x86_64-gtk3

# 3. 将 MSYS2 的 bin 目录添加到系统 PATH：
# C:\msys64\mingw64\bin

方法二：使用 GTK3 Runtime

下载 GTK3 Runtime: https://github.com/nickvidal/gtk3-runtime/releases
安装后将安装目录添加到系统 PATH

方法三：使用 Docker 部署（最简单）

docker-compose up -d backend

Docker 镜像已包含所有依赖，无需额外配置。

Q: macOS 上 PDF 导出报错？

# 安装依赖
brew install pango cairo gdk-pixbuf libffi

# 重启后端服务

Q: 前端无法连接后端 API？

检查 frontend/.env 中的 API 地址配置：

# 本地开发
VITE_API_BASE_URL=http://localhost:8000/api/v1

# Docker Compose 部署
VITE_API_BASE_URL=/api

Q: 数据库迁移失败？

cd backend
source .venv/bin/activate

# 查看当前迁移状态
alembic current

# 重新执行迁移
alembic upgrade head

# 如果有问题，可以回滚
alembic downgrade -1

性能优化

Q: 分析速度太慢怎么办？

1. 增加并发数

LLM_CONCURRENCY=5  # 增加并发（注意 API 限流）
LLM_GAP_MS=500     # 减少请求间隔

2. 限制分析文件数

MAX_ANALYZE_FILES=30  # 减少单次分析文件数

3. 使用更快的模型

gpt-4o-mini 比 gpt-4o 快
qwen-turbo 比 qwen-max 快
glm-4-flash 比 glm-4 快

4. 使用本地模型

Ollama 本地模型没有网络延迟，适合大量文件分析。

Q: 如何减少 API 调用费用？

使用便宜的模型：DeepSeek、通义千问 Turbo
减少分析文件数：设置 MAX_ANALYZE_FILES
过滤不必要的文件：排除测试文件、配置文件等
使用本地模型：Ollama 完全免费

Q: 内存占用过高？

减少并发数：LLM_CONCURRENCY=1
限制文件大小：MAX_FILE_SIZE_BYTES=102400（100KB）
使用更小的本地模型：如 deepseek-coder:1.3b

数据管理

Q: 如何备份数据？

在 /admin 页面的"数据库管理"标签页中，点击"导出数据"按钮，可以将所有数据导出为 JSON 文件。

也可以直接备份 PostgreSQL 数据库：

# 导出数据
docker-compose exec db pg_dump -U postgres xcodereviewer > backup.sql

# 恢复数据
docker-compose exec -T db psql -U postgres xcodereviewer < backup.sql

Q: 如何恢复数据？

在 /admin 页面的"数据库管理"标签页中，点击"导入数据"按钮，选择之前导出的 JSON 文件即可恢复。

Q: 如何清空所有数据？

在 /admin 页面的"数据库管理"标签页中，点击"清空数据"按钮。

⚠️ 警告：此操作不可恢复，请先备份重要数据！

其他问题

Q: 如何更新到最新版本？

# 拉取最新代码
git pull origin main

# 重新构建镜像
docker-compose build --no-cache

# 重启服务
docker-compose up -d

Q: 如何参与贡献？

参见贡献指南。

还有问题？

如果以上内容没有解决你的问题，欢迎：

提交 GitHub Issue
发送邮件至 lintsinghua@qq.com

提问时请提供：

操作系统和版本
部署方式（Docker/本地）
错误日志或截图
复现步骤

9.4 KiB Raw Blame History Unescape Escape