WuYanBo
/
CodeReview
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: expand contributing guidelines and improve documentation structure 

- Restructure CONTRIBUTING.md with comprehensive sections including code of conduct, development setup, and PR workflow
- Add detailed environment requirements table with version specifications and descriptions
- Include step-by-step backend and frontend setup instructions with database initialization
- Document code standards for both Python (Ruff, mypy) and TypeScript (Biome) with example commands
- Add conventional commits specification with type definitions and practical examples
- Provide complete PR process guide from forking through code review
- Include project structure diagram for better navigation
- Expand DISCLAIMER.md with improved formatting, tables, and clearer responsibility sections
- Add AI analysis limitations and technical constraints documentation
- Update SECURITY.md with enhanced security guidelines
- Refresh backend/env.example and frontend/.env.example with current configuration options
- Create new docs/ARCHITECTURE.md for system design documentation
- Update docs/CONFIGURATION.md, docs/DEPLOYMENT.md, docs/FAQ.md, and docs/LLM_PROVIDERS.md with improved clarity and structure
- Improve overall documentation consistency and user experience across all guides
This commit is contained in:
lintsinghua 2025-12-05 14:37:07 +08:00
parent c454db6159
commit 50d9d71f90
10 changed files with 2064 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

305
CONTRIBUTING.md
View File

@ -1,58 +1,325 @@
# 贡献指南
我们热烈欢迎所有形式的贡献！无论是提交 issue、创建 PR，还是改进文档，您的每一次贡献对我们都至关重要。
感谢你对 XCodeReviewer 的关注！我们热烈欢迎所有形式的贡献，无论是提交 Issue、创建 PR，还是改进文档。
## 开发流程
## 目录
1. **Fork** 本项目
2. 创建您的功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建一个 **Pull Request**
- [行为准则](#行为准则)
- [如何贡献](#如何贡献)
- [开发环境搭建](#开发环境搭建)
- [代码规范](#代码规范)
- [提交规范](#提交规范)
- [Pull Request 流程](#pull-request-流程)
## 环境要求
---
- Node.js 18+
- Python 3.13+
- PostgreSQL 15+
- pnpm 8+ (推荐) 或 npm/yarn
## 行为准则
## 本地开发
请在参与项目时保持友善和尊重。我们致力于为每个人提供一个开放、包容的环境。
---
## 如何贡献
### 报告 Bug
1. 先搜索 [Issues](https://github.com/lintsinghua/XCodeReviewer/issues) 确认问题未被报告
2. 创建新 Issue，使用 Bug 报告模板
3. 提供详细信息：
- 操作系统和版本
- 部署方式（Docker/本地）
- 复现步骤
- 错误日志或截图
- 期望行为 vs 实际行为
### 提出新功能
1. 先搜索 Issues 确认功能未被提出
2. 创建新 Issue，描述：
- 功能需求背景
- 期望的实现方式
- 可能的替代方案
### 改进文档
文档改进同样重要！你可以：
- 修复文档中的错误
- 补充缺失的说明
- 改进文档结构
- 添加使用示例
### 贡献代码
1. Fork 本项目
2. 创建功能分支
3. 编写代码和测试
4. 提交 Pull Request
---
## 开发环境搭建
### 环境要求
| 依赖 | 版本要求 | 说明 |
|------|---------|------|
| Node.js | 18+ | 前端运行环境 |
| Python | 3.13+ | 后端运行环境 |
| PostgreSQL | 15+ | 数据库 |
| pnpm | 8+ | 推荐的前端包管理器 |
| uv | 最新版 | 推荐的 Python 包管理器 |
### 数据库准备
```bash
# 使用 Docker 启动 PostgreSQL（推荐）
docker run -d \
--name xcodereviewer-db \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=xcodereviewer \
-p 5432:5432 \
postgres:15-alpine
```
### 后端启动
```bash
# 1. 进入后端目录
cd backend
# 2. 创建虚拟环境
uv venv
source .venv/bin/activate # Linux/macOS
# 或 .venv\Scripts\activate # Windows
# 3. 安装依赖
uv pip install -e .
# 4. 配置环境变量
cp env.example .env
# 编辑 .env 文件，配置数据库和 LLM 参数
# 5. 初始化数据库
alembic upgrade head
# 6. 启动后端服务
uvicorn app.main:app --reload --port 8000
```
### 前端启动
```bash
# 1. 进入前端目录
cd frontend
# 2. 安装依赖
pnpm install
# 3. 配置环境变量（可选）
cp .env.example .env
# 4. 启动开发服务器
pnpm dev
```
---
## 代码规范
- 后端使用 Python 类型注解
- 前端使用 TypeScript
- 提交前请确保代码通过 lint 检查
### 后端 (Python)
## 问题反馈
- 使用 Python 3.13+ 类型注解
- 遵循 PEP 8 代码风格
- 使用 Ruff 进行代码格式化和检查
- 使用 mypy 进行类型检查
如有问题，请通过 [Issues](https://github.com/lintsinghua/XCodeReviewer/issues) 反馈。
```bash
# 代码格式化
ruff format app
# 代码检查
ruff check app
# 类型检查
mypy app
```
### 前端 (TypeScript/React)
- 使用 TypeScript 严格模式
- 遵循 React 最佳实践
- 使用 Biome 进行代码格式化和检查
```bash
# 代码检查
pnpm lint
# 类型检查
pnpm type-check
# 代码格式化
pnpm format
```
### 通用规范
- 变量和函数使用有意义的命名
- 添加必要的注释，特别是复杂逻辑
- 保持函数简短，单一职责
- 避免硬编码，使用配置或常量
---
## 提交规范
我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范。
### 提交格式
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Type 类型
| Type | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `docs` | 文档更新 |
| `style` | 代码格式（不影响功能） |
| `refactor` | 代码重构 |
| `perf` | 性能优化 |
| `test` | 测试相关 |
| `chore` | 构建/工具相关 |
| `ci` | CI/CD 相关 |
### 示例
```bash
# 新功能
git commit -m "feat(llm): add support for DeepSeek API"
# Bug 修复
git commit -m "fix(scan): handle empty file content"
# 文档更新
git commit -m "docs: update deployment guide"
# 代码重构
git commit -m "refactor(api): simplify error handling"
```
---
## Pull Request 流程
### 1. Fork 和克隆
```bash
# Fork 项目到你的 GitHub 账号
# 然后克隆到本地
git clone https://github.com/YOUR_USERNAME/XCodeReviewer.git
cd XCodeReviewer
# 添加上游仓库
git remote add upstream https://github.com/lintsinghua/XCodeReviewer.git
```
### 2. 创建分支
```bash
# 同步上游代码
git fetch upstream
git checkout main
git merge upstream/main
# 创建功能分支
git checkout -b feature/your-feature-name
```
### 3. 开发和测试
```bash
# 编写代码...
# 确保代码通过检查
cd frontend && pnpm lint && pnpm type-check
cd backend && ruff check app && mypy app
# 提交代码
git add .
git commit -m "feat: your feature description"
```
### 4. 推送和创建 PR
```bash
# 推送到你的 Fork
git push origin feature/your-feature-name
```
然后在 GitHub 上创建 Pull Request：
1. 填写 PR 标题（遵循提交规范）
2. 描述改动内容和原因
3. 关联相关 Issue（如有）
4. 等待 Review
### 5. 代码审查
- 回应 Review 意见
- 根据反馈修改代码
- 保持 PR 更新（rebase 上游代码）
---
## 项目结构
```
XCodeReviewer/
├── backend/ # 后端 (FastAPI)
│ ├── app/
│ │ ├── api/ # API 路由
│ │ ├── core/ # 核心配置
│ │ ├── db/ # 数据库
│ │ ├── models/ # 数据模型
│ │ ├── schemas/ # Pydantic 模式
│ │ └── services/ # 业务逻辑
│ │ └── llm/ # LLM 适配器
│ ├── alembic/ # 数据库迁移
│ └── pyproject.toml
├── frontend/ # 前端 (React + TypeScript)
│ ├── src/
│ │ ├── app/ # 应用配置
│ │ ├── components/ # UI 组件
│ │ ├── features/ # 功能模块
│ │ ├── pages/ # 页面组件
│ │ └── shared/ # 共享工具
│ └── package.json
├── docs/ # 文档
├── docker-compose.yml # Docker 编排
└── README.md
```
---
## 贡献者
感谢以下优秀的贡献者们！
感谢所有贡献者的付出！
[![Contributors](https://contrib.rocks/image?repo=lintsinghua/XCodeReviewer)](https://github.com/lintsinghua/XCodeReviewer/graphs/contributors)
---
## 问题反馈
如有问题，请通过以下方式联系：
- [GitHub Issues](https://github.com/lintsinghua/XCodeReviewer/issues)
- 邮箱: lintsinghua@qq.com

265
DISCLAIMER.md
View File

@ -1,57 +1,220 @@
# 免责声明 (Disclaimer)
本免责声明旨在明确用户使用本开源项目的相关责任和风险，保护项目作者、贡献者和维护者的合法权益。本开源项目提供的代码、工具及相关内容仅供参考和学习使用。
本免责声明旨在明确用户使用本开源项目的相关责任和风险，保护项目作者、贡献者和维护者的合法权益。
## 1. 代码隐私与安全警告 (Code Privacy and Security Warning)
- ⚠️ **重要提示**：本工具通过调用第三方LLM服务商API进行代码分析，**您的代码将被发送到所选择的LLM服务商服务器**。
- **严禁上传以下类型的代码**：
- 包含商业机密、专有算法或核心业务逻辑的代码
- 涉及国家秘密、国防安全或其他保密信息的代码
- 包含敏感数据（如用户数据、密钥、密码、token等）的代码
- 受法律法规限制不得外传的代码
- 客户或第三方的专有代码（未经授权）
- 用户**必须自行评估代码的敏感性**，对上传代码及其可能导致的信息泄露承担全部责任。
- **建议**：对于敏感代码，请使用 Ollama 本地模型部署功能，或使用私有部署的LLM服务。
- 项目作者、贡献者和维护者**对因用户上传敏感代码导致的任何信息泄露、知识产权侵权、法律纠纷或其他损失不承担任何责任**。
## 2. 非专业建议 (Non-Professional Advice)
- 本工具提供的代码分析结果和建议**仅供参考**，不构成专业的安全审计、代码审查或法律意见。
- 用户必须结合人工审查、专业工具及其他可靠资源，对关键代码（尤其是涉及安全、金融、医疗等高风险领域）进行全面验证。
## 3. 无担保与免责 (No Warranty and Liability Disclaimer)
- 本项目以"原样"形式提供，**不附带任何明示或默示担保**，包括但不限于适销性、特定用途适用性及非侵权性。
- 作者、贡献者和维护者**不对任何直接、间接、附带、特殊、惩戒性或后果性损害承担责任**，包括但不限于数据丢失、系统中断、安全漏洞或商业损失，即使已知此类风险存在。
## 4. AI 分析局限性 (Limitations of AI Analysis)
- 本工具依赖多种 AI 模型，分析结果可能包含**错误、遗漏或不准确信息**，无法保证100% 可靠性。
- AI 输出**不能替代人类专家判断**，用户应对最终代码质量及应用后果全权负责。
## 5. 第三方服务与数据隐私 (Third-Party Services and Data Privacy)
- 本项目集成 Google Gemini、OpenAI、Claude、通义千问、DeepSeek 等多个第三方LLM服务，以及 Supabase、GitHub 等服务，使用时须遵守其各自服务条款和隐私政策。
- **代码传输说明**：用户提交的代码将通过API发送到所选LLM服务商进行分析，传输过程和数据处理遵循各服务商的隐私政策。
- 用户需自行获取、管理 API 密钥，本项目**不存储、传输或处理用户的API密钥和敏感信息**。
- 第三方服务的可用性、准确性、隐私保护、数据留存政策或中断风险，由服务提供商负责，本项目作者不承担任何连带责任。
## 6. 用户责任 (User Responsibilities)
- 用户在使用前须确保其代码不侵犯第三方知识产权，不包含保密信息，并严格遵守开源许可证及相关法规。
- 用户**对上传代码的内容、性质和合规性承担全部责任**，包括但不限于：
- 确保代码不包含敏感信息或商业机密
- 确保拥有代码的使用和分析权限
- 遵守所在国家/地区关于数据保护和隐私的法律法规
- 遵守公司或组织的保密协议和安全政策
- **严禁将本工具用于非法、恶意或损害他人权益的活动**，用户对所有使用后果承担全部法律与经济责任。
## 7. 开源贡献 (Open Source Contributions)
- 贡献者的代码、内容或建议**不代表项目官方观点**，其准确性、安全性及合规性由贡献者自行负责。
- 项目维护者保留审查、修改、拒绝或移除任何贡献的权利。
**本开源项目提供的代码、工具及相关内容仅供参考和学习使用。**
---
如有疑问，请通过 [GitHub Issues](https://github.com/lintsinghua/XCodeReviewer/issues) 联系维护者。本免责声明受项目所在地法律管辖。
## 1. 代码隐私与安全警告
### ⚠️ 重要提示
本工具通过调用第三方 LLM 服务商 API 进行代码分析，**您的代码将被发送到所选择的 LLM 服务商服务器**。
### 严禁上传以下类型的代码
| 类型 | 说明 |
|------|------|
| 🔒 商业机密 | 包含商业机密、专有算法或核心业务逻辑的代码 |
| 🛡️ 保密信息 | 涉及国家秘密、国防安全或其他保密信息的代码 |
| 🔑 敏感数据 | 包含用户数据、密钥、密码、token 等敏感信息的代码 |
| ⚖️ 受限代码 | 受法律法规限制不得外传的代码 |
| 📋 第三方代码 | 客户或第三方的专有代码（未经授权） |
### 用户责任
- 用户**必须自行评估代码的敏感性**
- 对上传代码及其可能导致的信息泄露承担**全部责任**
- 对于敏感代码，请使用 **Ollama 本地模型部署功能**，或使用私有部署的 LLM 服务
### 免责声明
项目作者、贡献者和维护者**对因用户上传敏感代码导致的任何信息泄露、知识产权侵权、法律纠纷或其他损失不承担任何责任**。
---
## 2. 非专业建议
### 分析结果仅供参考
- 本工具提供的代码分析结果和建议**仅供参考**
- **不构成**专业的安全审计、代码审查或法律意见
- **不能替代**人类专家的专业判断
### 建议做法
- 结合人工审查验证分析结果
- 使用专业安全工具进行补充检测
- 对关键代码（尤其是涉及安全、金融、医疗等高风险领域）进行全面验证
- 在生产环境部署前进行充分测试
---
## 3. 无担保与免责
### 无担保声明
本项目以 **"原样"（AS IS）** 形式提供，**不附带任何明示或默示担保**，包括但不限于：
- 适销性担保
- 特定用途适用性担保
- 非侵权性担保
- 准确性或完整性担保
### 责任限制
作者、贡献者和维护者**不对任何直接、间接、附带、特殊、惩戒性或后果性损害承担责任**，包括但不限于：
| 损害类型 | 说明 |
|---------|------|
| 数据丢失 | 因使用本工具导致的数据丢失或损坏 |
| 系统中断 | 服务中断或系统故障 |
| 安全漏洞 | 因依赖分析结果导致的安全问题 |
| 商业损失 | 利润损失、业务中断或其他商业损失 |
| 法律纠纷 | 因使用本工具引发的法律诉讼或纠纷 |
即使已知此类风险存在，上述免责条款仍然适用。
---
## 4. AI 分析局限性
### 技术局限
- 本工具依赖多种 AI 模型进行代码分析
- 分析结果可能包含**错误、遗漏或不准确信息**
- **无法保证** 100% 的准确性和可靠性
### AI 输出特性
| 特性 | 说明 |
|------|------|
| 概率性 | AI 输出基于概率模型，可能产生不同结果 |
| 上下文依赖 | 分析质量受代码上下文完整性影响 |
| 模型差异 | 不同 LLM 模型可能给出不同的分析结果 |
| 知识截止 | AI 模型的知识有截止日期，可能不了解最新漏洞 |
### 用户责任
- AI 输出**不能替代人类专家判断**
- 用户应对最终代码质量及应用后果**全权负责**
- 建议将 AI 分析作为辅助工具，而非唯一依据
---
## 5. 第三方服务与数据隐私
### 集成的第三方服务
本项目集成以下第三方服务：
| 服务类型 | 服务商 | 用途 |
|---------|--------|------|
| LLM API | OpenAI, Google Gemini, Anthropic Claude | 代码分析 |
| LLM API | 通义千问, DeepSeek, 智谱AI, Kimi | 代码分析 |
| LLM API | 百度文心, MiniMax, 字节豆包 | 代码分析 |
| 数据库 | Supabase | 数据存储（可选） |
| 代码托管 | GitHub, GitLab | 仓库集成 |
### 数据传输说明
- 用户提交的代码将通过 API 发送到所选 LLM 服务商进行分析
- 传输过程和数据处理遵循各服务商的隐私政策
- 用户需自行了解并接受各服务商的数据处理方式
### API 密钥管理
- 用户需自行获取、管理 API 密钥
- 本项目**不存储、传输或处理用户的 API 密钥**（除本地配置文件外）
- 运行时配置的密钥仅存储在用户浏览器本地
### 第三方服务风险
第三方服务的以下风险由服务提供商负责，本项目作者不承担任何连带责任：
- 服务可用性
- 数据准确性
- 隐私保护
- 数据留存政策
- 服务中断
---
## 6. 用户责任
### 使用前确认
用户在使用本工具前须确保：
- ✅ 代码不侵犯第三方知识产权
- ✅ 代码不包含保密信息
- ✅ 严格遵守开源许可证及相关法规
- ✅ 拥有代码的使用和分析权限
### 用户承诺
用户**对上传代码的内容、性质和合规性承担全部责任**，包括但不限于：
| 责任 | 说明 |
|------|------|
| 内容审查 | 确保代码不包含敏感信息或商业机密 |
| 权限确认 | 确保拥有代码的使用和分析权限 |
| 法规遵守 | 遵守所在国家/地区关于数据保护和隐私的法律法规 |
| 政策遵守 | 遵守公司或组织的保密协议和安全政策 |
### 禁止行为
**严禁将本工具用于以下活动**：
- ❌ 非法活动
- ❌ 恶意代码分析或开发
- ❌ 损害他人权益的行为
- ❌ 违反服务条款的行为
用户对所有使用后果承担**全部法律与经济责任**。
---
## 7. 开源贡献
### 贡献者声明
- 贡献者的代码、内容或建议**不代表项目官方观点**
- 其准确性、安全性及合规性由贡献者自行负责
### 维护者权利
项目维护者保留以下权利：
- 审查任何贡献
- 修改贡献内容
- 拒绝不符合要求的贡献
- 移除已合并的贡献
---
## 8. 许可证
本项目采用 [MIT 许可证](LICENSE) 开源。
MIT 许可证明确声明软件按"原样"提供，不提供任何形式的担保。
---
## 9. 管辖法律
本免责声明受项目所在地法律管辖。
---
## 联系方式
如有疑问，请通过以下方式联系维护者：
- **GitHub Issues**: [https://github.com/lintsinghua/XCodeReviewer/issues](https://github.com/lintsinghua/XCodeReviewer/issues)
- **邮箱**: lintsinghua@qq.com
---
**使用本工具即表示您已阅读、理解并同意本免责声明的所有条款。**

151
SECURITY.md
View File

@ -6,26 +6,147 @@
### 严禁上传以下类型的代码
- 包含商业机密、专有算法或核心业务逻辑的代码
- 涉及国家秘密、国防安全或其他保密信息的代码
- 包含敏感数据（如用户数据、密钥、密码、token 等）的代码
- 受法律法规限制不得外传的代码
- 客户或第三方的专有代码（未经授权）
- 🔒 包含商业机密、专有算法或核心业务逻辑的代码
- 🛡️ 涉及国家秘密、国防安全或其他保密信息的代码
- 🔑 包含敏感数据（如用户数据、密钥、密码、token 等）的代码
- ⚖️ 受法律法规限制不得外传的代码
- 📋 客户或第三方的专有代码（未经授权）
### 安全建议
- 用户**必须自行评估代码的敏感性**，对上传代码及其可能导致的信息泄露承担全部责任
- 对于敏感代码，请使用 **Ollama 本地模型部署功能**，或使用私有部署的 LLM 服务
- 确保代码不包含敏感信息或商业机密
- 确保拥有代码的使用和分析权限
- 遵守所在国家/地区关于数据保护和隐私的法律法规
- 遵守公司或组织的保密协议和安全政策
1. **评估代码敏感性**
- 用户必须自行评估代码的敏感性
- 对上传代码及其可能导致的信息泄露承担全部责任
2. **使用本地模型处理敏感代码**
- 对于敏感代码，请使用 **Ollama 本地模型部署功能**
- 或使用私有部署的 LLM 服务
- 本地模型不会将代码发送到任何外部服务器
3. **代码脱敏**
- 上传前移除敏感信息（API Key、密码、Token 等）
- 使用占位符替换真实数据
- 移除包含个人身份信息（PII）的代码
4. **遵守合规要求**
- 遵守所在国家/地区关于数据保护和隐私的法律法规
- 遵守公司或组织的保密协议和安全政策
- 确保拥有代码的使用和分析权限
---
## 支持的安全版本
| 版本 | 支持状态 |
|------|---------|
| 2.x.x | ✅ 支持 |
| 1.x.x | ❌ 不再支持 |
---
## 报告安全漏洞
如果您发现安全漏洞，请通过以下方式联系我们：
如果您发现安全漏洞，请通过以下方式负责任地披露：
- **邮箱**: lintsinghua@qq.com
- **Issues**: [GitHub Issues](https://github.com/lintsinghua/XCodeReviewer/issues)（请勿公开披露敏感漏洞详情）
### 报告方式
我们会尽快响应并处理安全问题。
1. **邮箱报告（推荐）**
- 发送邮件至: lintsinghua@qq.com
- 邮件标题请注明: `[Security] XCodeReviewer 安全漏洞报告`
2. **GitHub Issues**
- 地址: [GitHub Issues](https://github.com/lintsinghua/XCodeReviewer/issues)
- ⚠️ **请勿公开披露敏感漏洞详情**
- 仅描述漏洞类型，详细信息请通过邮件发送
### 报告内容
请在报告中包含以下信息：
- 漏洞类型和严重程度评估
- 受影响的版本和组件
- 复现步骤
- 潜在影响
- 建议的修复方案（如有）
### 响应时间
- 我们会在 **48 小时内** 确认收到报告
- 在 **7 天内** 提供初步评估
- 根据漏洞严重程度，在 **30-90 天内** 发布修复
### 致谢
我们感谢所有负责任地报告安全问题的研究人员。在漏洞修复后，我们会在发布说明中致谢（除非您希望保持匿名）。
---
## 安全最佳实践
### 部署安全
1. **修改默认密钥**
```env
# 生产环境必须修改！
SECRET_KEY=your-random-secret-key-at-least-32-characters
```
2. **配置 HTTPS**
- 生产环境务必启用 HTTPS
- 使用 Let's Encrypt 或其他 SSL 证书
3. **限制 CORS**
- 生产环境配置具体的前端域名
- 不要使用 `allow_origins=["*"]`
4. **数据库安全**
- 修改默认数据库密码
- 限制数据库访问 IP
- 定期备份数据
5. **API 限流**
- 配置 Nginx 或应用层限流
- 防止 API 滥用
### 运行时安全
1. **定期更新依赖**
```bash
# 后端
cd backend && pip install --upgrade -r requirements.txt
# 前端
cd frontend && pnpm update
```
2. **监控日志**
- 配置日志收集
- 设置异常告警
3. **最小权限原则**
- 使用最小必要的权限运行服务
- 不要以 root 用户运行容器
---
## 第三方服务安全
本项目集成以下第三方服务，使用时请遵守其各自的服务条款和隐私政策：
| 服务 | 用途 | 隐私政策 |
|------|------|---------|
| OpenAI | LLM API | [Privacy Policy](https://openai.com/privacy/) |
| Google Gemini | LLM API | [Privacy Policy](https://policies.google.com/privacy) |
| Anthropic Claude | LLM API | [Privacy Policy](https://www.anthropic.com/privacy) |
| 阿里云通义千问 | LLM API | [隐私政策](https://terms.alicdn.com/legal-agreement/terms/suit_bu1_ali_cloud/suit_bu1_ali_cloud202112071754_83380.html) |
| DeepSeek | LLM API | [Privacy Policy](https://www.deepseek.com/privacy) |
| Supabase | 数据库 | [Privacy Policy](https://supabase.com/privacy) |
| GitHub | 仓库集成 | [Privacy Policy](https://docs.github.com/en/site-policy/privacy-policies) |
---
## 免责声明
项目作者、贡献者和维护者对因用户上传敏感代码导致的任何信息泄露、知识产权侵权、法律纠纷或其他损失不承担任何责任。
详细免责声明请参阅 [DISCLAIMER.md](DISCLAIMER.md)。

130
backend/env.example
View File

@ -1,36 +1,148 @@
# =============================================
# XCodeReviewer Backend 配置文件
# 复制此文件为 .env 并填入实际配置
# =============================================
# 复制此文件为 .env 并填入实际配置
# 详细说明请参阅 docs/CONFIGURATION.md
# ------------ 数据库配置 ------------
# =============================================
# 数据库配置
# =============================================
# PostgreSQL 数据库连接配置
# Docker Compose 部署时使用 db 作为服务器地址
POSTGRES_SERVER=localhost
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=xcodereviewer
# ------------ 安全配置 ------------
# 完整数据库连接字符串（可选，会覆盖上述配置）
# DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost/xcodereviewer
# =============================================
# 安全配置
# =============================================
# JWT 签名密钥 - 生产环境必须修改为随机字符串！
# 建议使用: openssl rand -hex 32
SECRET_KEY=your-super-secret-key-change-this-in-production
# JWT 加密算法
ALGORITHM=HS256
# Token 过期时间（分钟），默认 8 天
ACCESS_TOKEN_EXPIRE_MINUTES=11520
# ------------ LLM配置 ------------
# 支持的provider: openai, gemini, claude, qwen, deepseek, zhipu, moonshot, baidu, minimax, doubao, ollama
#
# 使用 LiteLLM 统一适配器: openai, gemini, claude, qwen, deepseek, zhipu, moonshot, ollama
# 使用原生适配器 (API格式特殊): baidu, minimax, doubao
# =============================================
# LLM 通用配置
# =============================================
# 支持的 provider:
# - LiteLLM 适配器: openai, gemini, claude, qwen, deepseek, zhipu, moonshot, ollama
# - 原生适配器: baidu, minimax, doubao
LLM_PROVIDER=openai
# API 密钥
LLM_API_KEY=sk-your-api-key
# 模型名称（留空使用 provider 默认模型）
# OpenAI: gpt-4o-mini, gpt-4o, gpt-3.5-turbo
# Gemini: gemini-2.0-flash, gemini-1.5-pro
# Claude: claude-3-5-sonnet-20241022, claude-3-haiku-20240307
# Qwen: qwen-turbo, qwen-plus, qwen-max
# DeepSeek: deepseek-chat, deepseek-coder
# Zhipu: glm-4-flash, glm-4
# Moonshot: moonshot-v1-8k, moonshot-v1-32k
# Ollama: llama3, codellama, qwen2.5, deepseek-coder
LLM_MODEL=
# 自定义 API 端点（API 中转站）
# 示例: https://your-proxy.com/v1
LLM_BASE_URL=
# 请求超时时间（秒）
LLM_TIMEOUT=150
# 生成温度（0-1，越低越确定性）
LLM_TEMPERATURE=0.1
# 最大生成 Token 数
LLM_MAX_TOKENS=4096
# ------------ 仓库扫描配置 ------------
# =============================================
# 各平台独立配置（可选）
# =============================================
# 如果需要同时配置多个平台，可以单独设置
# 运行时可通过 /admin 页面切换
# OpenAI
# OPENAI_API_KEY=sk-xxx
# OPENAI_BASE_URL=https://api.openai.com/v1
# Google Gemini
# GEMINI_API_KEY=xxx
# Anthropic Claude
# CLAUDE_API_KEY=sk-ant-xxx
# 阿里云通义千问
# QWEN_API_KEY=sk-xxx
# DeepSeek
# DEEPSEEK_API_KEY=sk-xxx
# 智谱 AI
# ZHIPU_API_KEY=xxx
# 月之暗面 Kimi
# MOONSHOT_API_KEY=sk-xxx
# 百度文心一言（格式: api_key:secret_key）
# BAIDU_API_KEY=your_api_key:your_secret_key
# MiniMax
# MINIMAX_API_KEY=xxx
# 字节豆包
# DOUBAO_API_KEY=xxx
# Ollama 本地模型
# OLLAMA_BASE_URL=http://localhost:11434/v1
# =============================================
# Git 仓库配置
# =============================================
# GitHub Personal Access Token
# 获取地址: https://github.com/settings/tokens
# 权限要求: repo (私有仓库) 或 public_repo (公开仓库)
GITHUB_TOKEN=
# GitLab Personal Access Token
# 获取地址: https://gitlab.com/-/profile/personal_access_tokens
# 权限要求: read_repository
GITLAB_TOKEN=
# =============================================
# 扫描配置
# =============================================
# 单次扫描最大文件数
MAX_ANALYZE_FILES=50
# 单文件最大大小（字节），默认 200KB
MAX_FILE_SIZE_BYTES=204800
# LLM 并发请求数（注意 API 限流）
LLM_CONCURRENCY=3
# LLM 请求间隔（毫秒），避免触发限流
LLM_GAP_MS=2000
# =============================================
# 存储配置
# =============================================
# ZIP 文件存储目录
ZIP_STORAGE_PATH=./uploads/zip_files
# =============================================
# 输出配置
# =============================================
# 分析结果输出语言
# zh-CN: 中文
# en-US: 英文
OUTPUT_LANGUAGE=zh-CN

0
docs/ARCHITECTURE.md Normal file
View File

308
docs/CONFIGURATION.md
View File

@ -1,74 +1,261 @@
# 配置说明
## 后端核心配置
本文档详细介绍 XCodeReviewer 的所有配置选项，包括后端环境变量、前端配置和运行时配置。
编辑 `backend/.env` 文件：
## 目录
- [配置方式概览](#配置方式概览)
- [后端配置](#后端配置)
- [前端配置](#前端配置)
- [运行时配置](#运行时配置)
- [API 中转站配置](#api-中转站配置)
---
## 配置方式概览
XCodeReviewer 采用前后端分离架构，数据存储在后端 PostgreSQL 数据库中。
配置优先级（从高到低）：
| 配置方式 | 适用场景 | 优先级 |
|---------|---------|--------|
| 运行时配置（浏览器 /admin） | 快速切换 LLM、调试 | 最高 |
| 后端环境变量 | 生产部署、团队共享 | 中 |
| 默认值 | 开箱即用 | 最低 |
---
## 后端配置
后端配置文件位于 `backend/.env`，首次使用请复制示例文件：
```bash
cp backend/env.example backend/.env
```
### 完整配置参考
```env
# =============================================
# XCodeReviewer Backend 配置文件
# =============================================
# ========== 数据库配置 ==========
POSTGRES_SERVER=localhost
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=xcodereviewer
POSTGRES_SERVER=localhost # 数据库服务器地址
POSTGRES_USER=postgres # 数据库用户名
POSTGRES_PASSWORD=postgres # 数据库密码
POSTGRES_DB=xcodereviewer # 数据库名称
# DATABASE_URL= # 完整数据库连接字符串（可选，会覆盖上述配置）
# ========== 安全配置 ==========
SECRET_KEY=your-super-secret-key-change-this-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=11520
SECRET_KEY=your-super-secret-key # JWT 签名密钥（生产环境必须修改！）
ALGORITHM=HS256 # JWT 加密算法
ACCESS_TOKEN_EXPIRE_MINUTES=11520 # Token 过期时间（分钟），默认 8 天
# ========== LLM配置 ==========
# 支持的provider: openai, gemini, claude, qwen, deepseek, zhipu, moonshot, baidu, minimax, doubao, ollama
# ========== LLM 通用配置 ==========
LLM_PROVIDER=openai # LLM 提供商（见下方支持列表）
LLM_API_KEY=sk-your-api-key # API 密钥
LLM_MODEL= # 模型名称（留空使用默认模型）
LLM_BASE_URL= # 自定义 API 端点（API 中转站）
LLM_TIMEOUT=150 # 请求超时时间（秒）
LLM_TEMPERATURE=0.1 # 生成温度（0-1，越低越确定）
LLM_MAX_TOKENS=4096 # 最大生成 Token 数
# ========== 各平台独立配置（可选） ==========
# 如果需要同时配置多个平台，可以单独设置
# OPENAI_API_KEY=sk-xxx
# OPENAI_BASE_URL=https://api.openai.com/v1
# GEMINI_API_KEY=xxx
# CLAUDE_API_KEY=xxx
# QWEN_API_KEY=xxx
# DEEPSEEK_API_KEY=xxx
# ZHIPU_API_KEY=xxx
# MOONSHOT_API_KEY=xxx
# BAIDU_API_KEY=api_key:secret_key # 百度格式特殊
# MINIMAX_API_KEY=xxx
# DOUBAO_API_KEY=xxx
# OLLAMA_BASE_URL=http://localhost:11434/v1
# ========== Git 仓库配置 ==========
GITHUB_TOKEN= # GitHub Personal Access Token
GITLAB_TOKEN= # GitLab Personal Access Token
# ========== 扫描配置 ==========
MAX_ANALYZE_FILES=50 # 单次扫描最大文件数
MAX_FILE_SIZE_BYTES=204800 # 单文件最大大小（字节），默认 200KB
LLM_CONCURRENCY=3 # LLM 并发请求数
LLM_GAP_MS=2000 # 请求间隔（毫秒），避免限流
# ========== 存储配置 ==========
ZIP_STORAGE_PATH=./uploads/zip_files # ZIP 文件存储目录
# ========== 输出配置 ==========
OUTPUT_LANGUAGE=zh-CN # 输出语言：zh-CN（中文）| en-US（英文）
```
### 支持的 LLM 提供商
| Provider | 说明 | 适配器类型 |
|----------|------|-----------|
| `openai` | OpenAI GPT 系列 | LiteLLM |
| `gemini` | Google Gemini | LiteLLM |
| `claude` | Anthropic Claude | LiteLLM |
| `qwen` | 阿里云通义千问 | LiteLLM |
| `deepseek` | DeepSeek | LiteLLM |
| `zhipu` | 智谱 AI (GLM) | LiteLLM |
| `moonshot` | 月之暗面 Kimi | LiteLLM |
| `ollama` | Ollama 本地模型 | LiteLLM |
| `baidu` | 百度文心一言 | 原生适配器 |
| `minimax` | MiniMax | 原生适配器 |
| `doubao` | 字节豆包 | 原生适配器 |
### 配置示例
#### OpenAI
```env
LLM_PROVIDER=openai
LLM_API_KEY=sk-your-api-key
LLM_MODEL=gpt-4o-mini
LLM_BASE_URL= # API中转站地址（可选）
LLM_TIMEOUT=150
LLM_TEMPERATURE=0.1
LLM_MAX_TOKENS=4096
# ========== 仓库扫描配置 ==========
GITHUB_TOKEN=your_github_token
GITLAB_TOKEN=your_gitlab_token
MAX_ANALYZE_FILES=50
LLM_CONCURRENCY=3
LLM_GAP_MS=2000
```
## 运行时配置（浏览器）
访问 `/admin` 系统管理页面，可在浏览器中直接配置：
- **LLM 配置**：API Keys、模型、超时等参数
- **平台密钥**：管理 10+ LLM 平台的 API Keys
- **分析参数**：并发数、间隔时间、最大文件数等
- **API 中转站**：配置第三方 API 代理服务
## 数据库模式
### 本地模式（推荐）
数据存储在浏览器 IndexedDB，开箱即用，隐私安全：
#### 通义千问
```env
VITE_USE_LOCAL_DB=true
LLM_PROVIDER=qwen
LLM_API_KEY=sk-your-dashscope-key
LLM_MODEL=qwen-turbo
```
### 云端模式
数据存储在 Supabase，支持多设备同步：
#### Ollama 本地模型
```env
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_key
LLM_PROVIDER=ollama
LLM_MODEL=llama3
LLM_BASE_URL=http://localhost:11434/v1
```
### 后端数据库模式
#### 百度文心一言
使用 PostgreSQL 存储，适合团队协作。
```env
LLM_PROVIDER=baidu
LLM_API_KEY=your_api_key:your_secret_key
LLM_MODEL=ernie-bot-4
```
---
## 前端配置
前端配置文件位于 `frontend/.env`，首次使用请复制示例文件：
```bash
cp frontend/.env.example frontend/.env
```
### 完整配置参考
```env
# ========== 后端 API 配置 ==========
VITE_API_BASE_URL=/api # 后端 API 地址
# ========== 应用配置 ==========
VITE_APP_ID=xcodereviewer
# ========== 代码分析配置 ==========
VITE_MAX_ANALYZE_FILES=40 # 最大分析文件数
VITE_LLM_CONCURRENCY=2 # LLM 并发数
VITE_LLM_GAP_MS=500 # 请求间隔（毫秒）
VITE_OUTPUT_LANGUAGE=zh-CN # 输出语言
```
### 配置说明
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `VITE_API_BASE_URL` | 后端 API 地址，Docker 部署时使用 `/api` | `/api` |
| `VITE_MAX_ANALYZE_FILES` | 单次扫描最大文件数 | `40` |
| `VITE_LLM_CONCURRENCY` | 前端 LLM 并发请求数 | `2` |
| `VITE_LLM_GAP_MS` | 前端请求间隔 | `500` |
| `VITE_OUTPUT_LANGUAGE` | 分析结果输出语言 | `zh-CN` |
---
## 运行时配置
XCodeReviewer 支持在浏览器中进行运行时配置，无需重启服务。
### 访问方式
1. 登录系统后，访问 `/admin` 系统管理页面
2. 或点击侧边栏的"系统管理"菜单
### 可配置项
#### LLM 配置
- LLM 提供商选择
- API Key 配置
- 模型选择
- 自定义 API 端点（中转站）
- 超时时间
- 温度参数
- 最大 Token 数
#### 分析参数
- 最大分析文件数
- 并发请求数
- 请求间隔时间
- 输出语言
#### Git 集成
- GitHub Token
- GitLab Token
### 配置优先级
运行时配置 > 后端环境变量 > 默认值
---
## 数据存储
XCodeReviewer 采用前后端分离架构，所有数据存储在后端 PostgreSQL 数据库中。
### 架构说明
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 前端 │────▶│ 后端 API │────▶│ PostgreSQL │
│ (React) │ │ (FastAPI) │ │ 数据库 │
└─────────────┘ └─────────────┘ └─────────────┘
```
### 特点
- ✅ 数据持久化存储
- ✅ 支持多用户
- ✅ 支持用户认证
- ✅ 数据导入/导出功能
- ✅ 团队协作
### 数据管理
在 `/admin` 页面的"数据库管理"标签页中，可以：
- **导出数据**: 将所有数据导出为 JSON 文件备份
- **导入数据**: 从 JSON 文件恢复数据
- **清空数据**: 删除所有数据（谨慎操作）
- **健康检查**: 检查数据库连接状态
---
## API 中转站配置
许多用户使用 API 中转服务来访问 LLM（更稳定、更便宜）。
许多用户使用 API 中转服务来访问 LLM（更稳定、更便宜、解决网络问题）。
### 后端配置（推荐）
@ -79,8 +266,33 @@ LLM_BASE_URL=https://your-proxy.com/v1
LLM_MODEL=gpt-4o-mini
```
### 前端运行时配置
### 运行时配置
1. 访问系统管理页面（`/admin`）
2. 在"系统配置"标签页中配置 API 基础 URL 和 Key
3. 保存并刷新页面
2. 在"系统配置"标签页中：
- 选择 LLM 提供商
- 填入中转站提供的 API Key
- 设置自定义 API 基础 URL
3. 保存配置
### 常见中转站
| 中转站 | 说明 |
|--------|------|
| [OpenRouter](https://openrouter.ai/) | 支持多种模型 |
| [API2D](https://api2d.com/) | 国内访问友好 |
| [CloseAI](https://www.closeai-asia.com/) | 价格实惠 |
### 注意事项
1. 确保中转站支持你选择的模型
2. 中转站的 API 格式需要与 OpenAI 兼容
3. 部分中转站可能有请求限制
---
## 更多资源
- [部署指南](DEPLOYMENT.md) - 详细的部署说明
- [LLM 平台支持](LLM_PROVIDERS.md) - 各 LLM 平台的配置方法
- [常见问题](FAQ.md) - 配置相关问题解答

383
docs/DEPLOYMENT.md
View File

@ -1,8 +1,20 @@
# 部署指南
## Docker Compose 部署（推荐）
本文档详细介绍 XCodeReviewer 的各种部署方式，包括 Docker Compose 一键部署、生产环境部署和本地开发环境搭建。
完整的前后端分离部署方案，包含前端、后端和 PostgreSQL 数据库，一键启动所有服务。
## 目录
- [快速开始](#快速开始)
- [Docker Compose 部署（推荐）](#docker-compose-部署推荐)
- [生产环境部署](#生产环境部署)
- [本地开发部署](#本地开发部署)
- [常见部署问题](#常见部署问题)
---
## 快速开始
最快的方式是使用 Docker Compose 一键部署：
```bash
# 1. 克隆项目
@ -11,50 +23,252 @@ cd XCodeReviewer
# 2. 配置后端环境变量
cp backend/env.example backend/.env
# 编辑 backend/.env 文件，配置 LLM API Key 等参数
# 编辑 backend/.env，配置 LLM API Key
# 3. 使用 Docker Compose 启动所有服务
# 3. 启动所有服务
docker-compose up -d
# 4. 访问应用
# 前端: http://localhost:5173
# 后端 API: http://localhost:8000
# API 文档: http://localhost:8000/docs
# 后端 API: http://localhost:8000/docs
```
---
## Docker Compose 部署（推荐）
完整的前后端分离部署方案，包含前端、后端和 PostgreSQL 数据库。
### 系统要求
- Docker 20.10+
- Docker Compose 2.0+
- 至少 2GB 可用内存
- 至少 5GB 可用磁盘空间
### 部署步骤
```bash
# 1. 克隆项目
git clone https://github.com/lintsinghua/XCodeReviewer.git
cd XCodeReviewer
# 2. 配置后端环境变量
cp backend/env.example backend/.env
```
编辑 `backend/.env` 文件，配置必要参数：
```env
# 数据库配置（Docker Compose 会自动处理）
POSTGRES_SERVER=db
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=xcodereviewer
# 安全配置（生产环境请修改）
SECRET_KEY=your-super-secret-key-change-this-in-production
# LLM 配置（必填）
LLM_PROVIDER=openai
LLM_API_KEY=sk-your-api-key
LLM_MODEL=gpt-4o-mini
# 可选：API 中转站
# LLM_BASE_URL=https://your-proxy.com/v1
```
```bash
# 3. 启动所有服务
docker-compose up -d
# 4. 查看服务状态
docker-compose ps
# 5. 查看日志
docker-compose logs -f
```
### 服务说明
| 服务 | 端口 | 说明 |
|------|------|------|
| `frontend` | 5173 | React 前端应用（开发模式） |
| `frontend` | 5173 | React 前端应用（开发模式，支持热重载） |
| `backend` | 8000 | FastAPI 后端 API |
| `db` | 5432 | PostgreSQL 数据库 |
| `db` | 5432 | PostgreSQL 15 数据库 |
### 生产环境部署
### 访问地址
如需生产环境部署，可使用根目录的 `Dockerfile` 构建前端静态文件并通过 Nginx 提供服务：
- 前端应用: http://localhost:5173
- 后端 API: http://localhost:8000
- API 文档 (Swagger): http://localhost:8000/docs
- API 文档 (ReDoc): http://localhost:8000/redoc
### 常用命令
```bash
# 构建前端生产镜像
# 停止所有服务
docker-compose down
# 停止并删除数据卷（清除数据库）
docker-compose down -v
# 重新构建镜像
docker-compose build --no-cache
# 查看特定服务日志
docker-compose logs -f backend
# 进入容器调试
docker-compose exec backend bash
docker-compose exec db psql -U postgres -d xcodereviewer
```
---
## 生产环境部署
生产环境建议使用 Nginx 提供前端静态文件服务，并配置 HTTPS。
### 方式一：使用预构建 Docker 镜像
```bash
# 拉取最新镜像
docker pull ghcr.io/lintsinghua/xcodereviewer-frontend:latest
docker pull ghcr.io/lintsinghua/xcodereviewer-backend:latest
# 启动后端和数据库
docker-compose up -d db backend
# 启动前端（Nginx 生产镜像）
docker run -d \
--name xcodereviewer-frontend \
-p 80:80 \
--network xcodereviewer-network \
ghcr.io/lintsinghua/xcodereviewer-frontend:latest
```
### 方式二：本地构建生产镜像
```bash
# 构建前端生产镜像（使用 Nginx）
docker build -t xcodereviewer-frontend .
# 运行前端容器（端口 8888）
docker run -d -p 8888:80 --name xcodereviewer-frontend xcodereviewer-frontend
# 运行前端容器
docker run -d \
-p 80:80 \
--name xcodereviewer-frontend \
xcodereviewer-frontend
# 后端和数据库仍使用 docker-compose
docker-compose up -d db backend
```
### 方式三：手动部署
#### 前端部署
```bash
cd frontend
# 安装依赖
pnpm install
# 构建生产版本
pnpm build
# 将 dist 目录部署到 Nginx/Apache 等 Web 服务器
```
Nginx 配置示例：
```nginx
server {
listen 80;
server_name your-domain.com;
root /var/www/xcodereviewer/dist;
index index.html;
# 前端路由支持
location / {
try_files $uri $uri/ /index.html;
}
# API 代理
location /api {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
#### 后端部署
```bash
cd backend
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt
# 配置环境变量
cp env.example .env
# 编辑 .env 文件
# 初始化数据库
alembic upgrade head
# 使用 Gunicorn 启动（生产环境）
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
```
### 生产环境安全建议
1. **修改默认密钥**：务必修改 `SECRET_KEY` 为随机字符串
2. **配置 HTTPS**：使用 Let's Encrypt 或其他 SSL 证书
3. **限制 CORS**：在生产环境配置具体的前端域名
4. **数据库安全**：修改默认数据库密码，限制访问 IP
5. **API 限流**：配置 Nginx 或应用层限流
6. **日志监控**：配置日志收集和监控告警
---
## 本地开发部署
适合需要开发或自定义修改的场景。
### 环境要求
- Node.js 18+
- Python 3.13+
- PostgreSQL 15+
- pnpm 8+ (推荐) 或 npm/yarn
| 依赖 | 版本要求 | 说明 |
|------|---------|------|
| Node.js | 18+ | 前端运行环境 |
| Python | 3.13+ | 后端运行环境 |
| PostgreSQL | 15+ | 数据库 |
| pnpm | 8+ | 推荐的包管理器 |
| uv | 最新版 | 推荐的 Python 包管理器 |
### 数据库准备
```bash
# 方式一：使用 Docker 启动 PostgreSQL
docker run -d \
--name xcodereviewer-db \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=xcodereviewer \
-p 5432:5432 \
postgres:15-alpine
# 方式二：使用本地 PostgreSQL
# 创建数据库
createdb xcodereviewer
```
### 后端启动
@ -69,6 +283,8 @@ source .venv/bin/activate # Linux/macOS
# 3. 安装依赖
uv pip install -e .
# 或使用 pip
pip install -r requirements.txt
# 4. 配置环境变量
cp env.example .env
@ -77,7 +293,7 @@ cp env.example .env
# 5. 初始化数据库
alembic upgrade head
# 6. 启动后端服务
# 6. 启动后端服务（开发模式，支持热重载）
uvicorn app.main:app --reload --port 8000
```
@ -88,7 +304,8 @@ uvicorn app.main:app --reload --port 8000
cd frontend
# 2. 安装依赖
pnpm install # 或 npm install / yarn install
pnpm install
# 或 npm install / yarn install
# 3. 配置环境变量（可选，也可使用运行时配置）
cp .env.example .env
@ -99,3 +316,131 @@ pnpm dev
# 5. 访问应用
# 浏览器打开 http://localhost:5173
```
### 开发工具
```bash
# 前端代码检查
cd frontend
pnpm lint
pnpm type-check
# 前端代码格式化
pnpm format
# 后端类型检查
cd backend
mypy app
# 后端代码格式化
ruff format app
```
---
## 数据存储
XCodeReviewer 采用前后端分离架构，所有数据存储在后端 PostgreSQL 数据库中。
### 数据管理
在 `/admin` 页面的"数据库管理"标签页中，可以：
- **导出数据**: 将所有数据导出为 JSON 文件备份
- **导入数据**: 从 JSON 文件恢复数据
- **清空数据**: 删除所有数据（谨慎操作）
- **健康检查**: 检查数据库连接状态和数据完整性
### 数据库备份
```bash
# 导出 PostgreSQL 数据
docker-compose exec db pg_dump -U postgres xcodereviewer > backup.sql
# 恢复数据
docker-compose exec -T db psql -U postgres xcodereviewer < backup.sql
```
---
## 常见部署问题
### Docker 相关
**Q: 容器启动失败，提示端口被占用**
```bash
# 检查端口占用
lsof -i :5173
lsof -i :8000
lsof -i :5432
# 停止占用端口的进程，或修改 docker-compose.yml 中的端口映射
```
**Q: 数据库连接失败**
```bash
# 检查数据库容器状态
docker-compose ps db
# 查看数据库日志
docker-compose logs db
# 确保数据库健康检查通过后再启动后端
docker-compose up -d db
docker-compose exec db pg_isready -U postgres
docker-compose up -d backend
```
### 后端相关
**Q: PDF 导出功能报错（WeasyPrint 依赖问题）**
WeasyPrint 需要系统级依赖，Docker 镜像已包含。本地开发时：
```bash
# macOS
brew install pango cairo gdk-pixbuf libffi
# Ubuntu/Debian
sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0 libcairo2 libgdk-pixbuf2.0-0
# Windows - 参见 FAQ.md 中的详细说明
```
**Q: LLM API 请求超时**
```env
# 增加超时时间
LLM_TIMEOUT=300
# 降低并发数
LLM_CONCURRENCY=1
# 增加请求间隔
LLM_GAP_MS=3000
```
### 前端相关
**Q: 前端无法连接后端 API**
检查 `frontend/.env` 中的 API 地址配置：
```env
# 本地开发
VITE_API_BASE_URL=http://localhost:8000/api/v1
# Docker Compose 部署
VITE_API_BASE_URL=/api
```
---
## 更多资源
- [配置说明](CONFIGURATION.md) - 详细的配置参数说明
- [LLM 平台支持](LLM_PROVIDERS.md) - 各 LLM 平台的配置方法
- [常见问题](FAQ.md) - 更多问题解答
- [贡献指南](../CONTRIBUTING.md) - 参与项目开发

389
docs/FAQ.md
View File

@ -1,36 +1,99 @@
# 常见问题
# 常见问题 (FAQ)
## 如何快速切换 LLM 平台？
本文档收集了 XCodeReviewer 使用过程中的常见问题和解决方案。
### 方式一：浏览器配置（推荐）
## 目录
- [快速入门](#快速入门)
- [LLM 配置](#llm-配置)
- [网络问题](#网络问题)
- [功能使用](#功能使用)
- [部署问题](#部署问题)
- [性能优化](#性能优化)
---
## 快速入门
### Q: 如何快速开始使用？
最快的方式是使用 Docker Compose：
```bash
# 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: 不想用 Docker，如何本地运行？
参见 [部署指南 - 本地开发部署](DEPLOYMENT.md#本地开发部署)。
### 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 平台？
**方式一：浏览器运行时配置（推荐）**
1. 访问 `http://localhost:5173/admin` 系统管理页面
2. 在"系统配置"标签页选择不同的 LLM 提供商
3. 填入对应的 API Key
4. 保存并刷新页面
4. 保存即可，无需重启
### 方式二：后端环境变量配置
**方式二：修改后端环境变量**
修改 `backend/.env` 中的配置：
编辑 `backend/.env`：
```env
# 切换到 OpenAI
LLM_PROVIDER=openai
LLM_API_KEY=your_key
LLM_API_KEY=sk-your-key
# 切换到通义千问
LLM_PROVIDER=qwen
LLM_API_KEY=your_key
LLM_API_KEY=sk-your-dashscope-key
# 切换到 DeepSeek
LLM_PROVIDER=deepseek
LLM_API_KEY=sk-your-key
```
## 遇到请求超时怎么办？
修改后需要重启后端服务。
1. 增加超时时间：`LLM_TIMEOUT=300`
2. 使用代理：配置 `LLM_BASE_URL`
3. 切换到国内平台：通义千问、DeepSeek、智谱AI 等
4. 降低并发：`LLM_CONCURRENCY=1`
### Q: 百度文心一言的 API Key 格式是什么？
## 如何使用 Ollama 本地大模型？
百度需要同时提供 API Key 和 Secret Key，用冒号分隔：
```env
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 本地大模型？
```bash
# 1. 安装 Ollama
@ -40,52 +103,318 @@ curl -fsSL https://ollama.com/install.sh | sh # macOS/Linux
# 2. 拉取模型
ollama pull llama3 # 或 codellama、qwen2.5、deepseek-coder
# 3. 配置后端
# 3. 确保 Ollama 服务运行
ollama serve
# 4. 配置后端
# 在 backend/.env 中设置：
LLM_PROVIDER=ollama
LLM_MODEL=llama3
LLM_BASE_URL=http://localhost:11434/v1
```
推荐模型：`llama3`（综合）、`codellama`（代码专用）、`qwen2.5`（中文）
**推荐模型**：
- `llama3` - 综合能力强
- `codellama` - 代码专用
- `qwen2.5` - 中文支持好
- `deepseek-coder` - 代码分析强
## 百度文心一言的 API Key 格式？
### Q: 哪个 LLM 平台性价比最高？
百度需要同时提供 API Key 和 Secret Key，用冒号分隔：
| 场景 | 推荐 | 原因 |
|------|------|------|
| 免费使用 | Gemini / 智谱 GLM-4-Flash | 有免费配额 |
| 低成本 | DeepSeek | 价格仅为 GPT-4 的 1/10 |
| 最佳性能 | GPT-4o / Claude Sonnet | 代码理解能力最强 |
| 敏感代码 | Ollama 本地模型 | 完全本地化 |
---
## 网络问题
### Q: 遇到请求超时怎么办？
**方案一：增加超时时间**
```env
LLM_PROVIDER=baidu
LLM_API_KEY=your_api_key:your_secret_key
LLM_TIMEOUT=300 # 增加到 300 秒
```
获取地址：https://console.bce.baidu.com/qianfan/
**方案二：使用 API 中转站**
## Windows 导出 PDF 报错怎么办？
```env
LLM_PROVIDER=openai
LLM_API_KEY=中转站提供的Key
LLM_BASE_URL=https://your-proxy.com/v1
```
PDF 导出功能使用 WeasyPrint 库，在 Windows 系统上需要安装 GTK 依赖：
**方案三：切换到国内平台**
### 方法一：使用 MSYS2 安装（推荐）
通义千问、DeepSeek、智谱 AI 等国内平台访问更稳定。
**方案四：降低并发**
```env
LLM_CONCURRENCY=1 # 降低并发数
LLM_GAP_MS=3000 # 增加请求间隔
```
### Q: 如何配置 API 中转站？
```env
LLM_PROVIDER=openai
LLM_API_KEY=中转站提供的Key
LLM_BASE_URL=https://your-proxy.com/v1
LLM_MODEL=gpt-4o-mini
```
常见中转站：
- [OpenRouter](https://openrouter.ai/)
- [API2D](https://api2d.com/)
- [CloseAI](https://www.closeai-asia.com/)
### Q: 提示 "API Key 无效" 怎么办？
1. 检查 API Key 是否正确复制（注意前后空格）
2. 确认 API Key 未过期或被禁用
3. 检查 LLM_PROVIDER 是否与 API Key 匹配
4. 如果使用中转站，确认 LLM_BASE_URL 配置正确
---
## 功能使用
### Q: 如何分析 GitHub/GitLab 仓库？
1. 在"项目管理"页面点击"添加项目"
2. 选择"GitHub 仓库"或"GitLab 仓库"
3. 输入仓库 URL（如 `https://github.com/user/repo`）
4. 如果是私有仓库，需要配置 Token：
- GitHub: 在 `backend/.env` 中设置 `GITHUB_TOKEN`
- GitLab: 在 `backend/.env` 中设置 `GITLAB_TOKEN`
### Q: 如何上传 ZIP 文件分析？
1. 在"项目管理"页面点击"添加项目"
2. 选择"上传 ZIP"
3. 选择本地 ZIP 文件上传
4. 系统会自动解压并分析
### Q: 如何使用即时分析功能？
1. 访问"即时分析"页面
2. 直接粘贴代码片段
3. 选择编程语言
4. 点击"分析"按钮
### Q: 如何导出审计报告？
1. 完成代码分析后，进入"审计报告"页面
2. 点击"导出"按钮
3. 选择导出格式：
- **JSON**: 结构化数据，适合程序处理
- **PDF**: 专业报告，适合交付
### Q: 分析结果不准确怎么办？
1. **切换更强的模型**：如 GPT-4o、Claude Sonnet
2. **调整温度参数**：降低 `LLM_TEMPERATURE` 到 0.1 以下
3. **增加上下文**：确保代码文件完整
4. **人工复核**：AI 分析结果仅供参考，建议结合人工审查
---
## 部署问题
### Q: Docker 容器启动失败？
**端口被占用**：
```bash
# 检查端口占用
lsof -i :5173
lsof -i :8000
lsof -i :5432
# 停止占用进程或修改 docker-compose.yml 中的端口
```
**数据库连接失败**：
```bash
# 确保数据库先启动
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 安装（推荐）**
```bash
# 1. 下载并安装 MSYS2: https://www.msys2.org/
# 2. 打开 MSYS2 终端，执行：
pacman -S mingw-w64-x86_64-pango mingw-w64-x86_64-gtk3
# 3. 将 MSYS2 的 bin 目录添加到系统 PATH 环境变量：
# 3. 将 MSYS2 的 bin 目录添加到系统 PATH：
# C:\msys64\mingw64\bin
```
### 方法二：使用 GTK3 Runtime 安装包
**方法二：使用 GTK3 Runtime**
1. 下载 GTK3 Runtime: https://github.com/nickvidal/gtk3-runtime/releases
2. 安装后将安装目录添加到系统 PATH
### 方法三：使用 Docker 部署（最简单）
使用 Docker 部署后端可以避免 Windows 上的依赖问题：
**方法三：使用 Docker 部署（最简单）**
```bash
docker-compose up -d backend
```
安装完成后重启后端服务即可正常导出 PDF。
Docker 镜像已包含所有依赖，无需额外配置。
### Q: macOS 上 PDF 导出报错？
```bash
# 安装依赖
brew install pango cairo gdk-pixbuf libffi
# 重启后端服务
```
### Q: 前端无法连接后端 API？
检查 `frontend/.env` 中的 API 地址配置：
```env
# 本地开发
VITE_API_BASE_URL=http://localhost:8000/api/v1
# Docker Compose 部署
VITE_API_BASE_URL=/api
```
### Q: 数据库迁移失败？
```bash
cd backend
source .venv/bin/activate
# 查看当前迁移状态
alembic current
# 重新执行迁移
alembic upgrade head
# 如果有问题，可以回滚
alembic downgrade -1
```
---
## 性能优化
### Q: 分析速度太慢怎么办？
**1. 增加并发数**
```env
LLM_CONCURRENCY=5 # 增加并发（注意 API 限流）
LLM_GAP_MS=500 # 减少请求间隔
```
**2. 限制分析文件数**
```env
MAX_ANALYZE_FILES=30 # 减少单次分析文件数
```
**3. 使用更快的模型**
- `gpt-4o-mini` 比 `gpt-4o` 快
- `qwen-turbo` 比 `qwen-max` 快
- `glm-4-flash` 比 `glm-4` 快
**4. 使用本地模型**
Ollama 本地模型没有网络延迟，适合大量文件分析。
### Q: 如何减少 API 调用费用？
1. **使用便宜的模型**：DeepSeek、通义千问 Turbo
2. **减少分析文件数**：设置 `MAX_ANALYZE_FILES`
3. **过滤不必要的文件**：排除测试文件、配置文件等
4. **使用本地模型**：Ollama 完全免费
### Q: 内存占用过高？
1. **减少并发数**：`LLM_CONCURRENCY=1`
2. **限制文件大小**：`MAX_FILE_SIZE_BYTES=102400`（100KB）
3. **使用更小的本地模型**：如 `deepseek-coder:1.3b`
---
## 数据管理
### Q: 如何备份数据？
在 `/admin` 页面的"数据库管理"标签页中，点击"导出数据"按钮，可以将所有数据导出为 JSON 文件。
也可以直接备份 PostgreSQL 数据库：
```bash
# 导出数据
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: 如何更新到最新版本？
```bash
# 拉取最新代码
git pull origin main
# 重新构建镜像
docker-compose build --no-cache
# 重启服务
docker-compose up -d
```
### Q: 如何参与贡献？
参见 [贡献指南](../CONTRIBUTING.md)。
---
## 还有问题？
如果以上内容没有解决你的问题，欢迎：
- 提交 [GitHub Issue](https://github.com/lintsinghua/XCodeReviewer/issues)
- 发送邮件至 lintsinghua@qq.com
提问时请提供：
1. 操作系统和版本
2. 部署方式（Docker/本地）
3. 错误日志或截图
4. 复现步骤

307
docs/LLM_PROVIDERS.md
View File

@ -1,26 +1,45 @@
# LLM 平台支持
XCodeReviewer 支持 10+ 主流 LLM 平台，可根据需求自由选择。
XCodeReviewer 支持 10+ 主流 LLM 平台，可根据需求自由选择。本文档介绍各平台的配置方法。
## 支持的平台
## 目录
| 平台类型 | 平台名称 | 特点 | 获取地址 |
|---------|---------|------|---------|
| **国际平台** | Google Gemini | 免费配额充足，推荐 | [获取](https://makersuite.google.com/app/apikey) |
| | OpenAI GPT | 稳定可靠，性能最佳 | [获取](https://platform.openai.com/api-keys) |
| | Anthropic Claude | 代码理解能力强 | [获取](https://console.anthropic.com/) |
| | DeepSeek | 性价比高 | [获取](https://platform.deepseek.com/) |
| **国内平台** | 阿里云通义千问 | 国内访问快 | [获取](https://dashscope.console.aliyun.com/) |
| | 智谱AI (GLM) | 中文支持好 | [获取](https://open.bigmodel.cn/) |
| | 月之暗面 Kimi | 长文本处理 | [获取](https://platform.moonshot.cn/) |
| | 百度文心一言 | 企业级服务 | [获取](https://console.bce.baidu.com/qianfan/) |
| | MiniMax | 多模态能力 | [获取](https://www.minimaxi.com/) |
| | 字节豆包 | 高性价比 | [获取](https://console.volcengine.com/ark) |
| **本地部署** | Ollama | 完全本地化，隐私安全 | [安装](https://ollama.com/) |
- [平台概览](#平台概览)
- [国际平台](#国际平台)
- [国内平台](#国内平台)
- [本地部署](#本地部署)
- [API 中转站](#api-中转站)
- [选择建议](#选择建议)
## 配置示例
---
### OpenAI
## 平台概览
| 平台类型 | 平台名称 | Provider | 特点 | 获取 API Key |
|---------|---------|----------|------|-------------|
| **国际平台** | OpenAI GPT | `openai` | 稳定可靠，生态完善 | [获取](https://platform.openai.com/api-keys) |
| | Google Gemini | `gemini` | 免费配额充足 | [获取](https://makersuite.google.com/app/apikey) |
| | Anthropic Claude | `claude` | 代码理解能力强 | [获取](https://console.anthropic.com/) |
| | DeepSeek | `deepseek` | 性价比极高，代码能力强 | [获取](https://platform.deepseek.com/) |
| **国内平台** | 阿里云通义千问 | `qwen` | 国内访问快，中文好 | [获取](https://dashscope.console.aliyun.com/) |
| | 智谱 AI (GLM) | `zhipu` | 中文支持好 | [获取](https://open.bigmodel.cn/) |
| | 月之暗面 Kimi | `moonshot` | 长文本处理强 | [获取](https://platform.moonshot.cn/) |
| | 百度文心一言 | `baidu` | 企业级服务 | [获取](https://console.bce.baidu.com/qianfan/) |
| | MiniMax | `minimax` | 多模态能力 | [获取](https://www.minimaxi.com/) |
| | 字节豆包 | `doubao` | 高性价比 | [获取](https://console.volcengine.com/ark) |
| **本地部署** | Ollama | `ollama` | 完全本地化，隐私安全 | [安装](https://ollama.com/) |
---
## 国际平台
### OpenAI GPT
OpenAI 是最成熟的 LLM 平台，模型性能稳定，代码理解能力强。
**获取 API Key**: https://platform.openai.com/api-keys
**配置示例**:
```env
LLM_PROVIDER=openai
@ -28,33 +47,135 @@ LLM_API_KEY=sk-your-api-key
LLM_MODEL=gpt-4o-mini
```
**常用模型**: `gpt-4o`、`gpt-4o-mini`、`gpt-4-turbo`、`o1`、`o1-mini` 等
> 💡 模型列表会持续更新，请访问 [OpenAI 官网](https://platform.openai.com/docs/models) 查看最新模型。
---
### Google Gemini
Google 的 Gemini 系列模型，免费配额充足，适合个人使用。
**获取 API Key**: https://makersuite.google.com/app/apikey
**配置示例**:
```env
LLM_PROVIDER=gemini
LLM_API_KEY=your-api-key
LLM_MODEL=gemini-pro
LLM_MODEL=gemini-2.0-flash
```
### 通义千问
**常用模型**: `gemini-2.0-flash`、`gemini-1.5-pro`、`gemini-1.5-flash` 等
> 💡 Gemini 有免费配额限制，超出后需付费。请访问 [Google AI Studio](https://ai.google.dev/) 查看最新模型。
---
### Anthropic Claude
Claude 在代码理解和生成方面表现优秀，特别适合代码审计场景。
**获取 API Key**: https://console.anthropic.com/
**配置示例**:
```env
LLM_PROVIDER=qwen
LLM_API_KEY=your-api-key
LLM_MODEL=qwen-turbo
LLM_PROVIDER=claude
LLM_API_KEY=sk-ant-your-api-key
LLM_MODEL=claude-sonnet-4-20250514
```
**常用模型**: `claude-sonnet-4-*`、`claude-opus-4-*`、`claude-3.5-sonnet-*` 等
> 💡 Claude 模型名称包含日期后缀，请访问 [Anthropic 官网](https://docs.anthropic.com/en/docs/about-claude/models) 查看最新模型。
---
### DeepSeek
DeepSeek 是国产模型中代码能力最强的之一，性价比极高。
**获取 API Key**: https://platform.deepseek.com/
**配置示例**:
```env
LLM_PROVIDER=deepseek
LLM_API_KEY=your-api-key
LLM_API_KEY=sk-your-api-key
LLM_MODEL=deepseek-chat
```
**常用模型**: `deepseek-chat`、`deepseek-coder`、`deepseek-reasoner` 等
> 💡 DeepSeek 价格仅为 GPT-4 的 1/10，代码能力接近 GPT-4，性价比极高。
---
## 国内平台
### 阿里云通义千问
通义千问是阿里云的大模型服务，国内访问速度快，中文理解能力强。
**获取 API Key**: https://dashscope.console.aliyun.com/
**配置示例**:
```env
LLM_PROVIDER=qwen
LLM_API_KEY=sk-your-dashscope-key
LLM_MODEL=qwen-turbo
```
**常用模型**: `qwen-max`、`qwen-plus`、`qwen-turbo`、`qwen-coder-*` 等
---
### 智谱 AI (GLM)
智谱 AI 的 GLM 系列模型，中文支持好，有免费配额。
**获取 API Key**: https://open.bigmodel.cn/
**配置示例**:
```env
LLM_PROVIDER=zhipu
LLM_API_KEY=your-api-key
LLM_MODEL=glm-4-flash
```
**常用模型**: `glm-4`、`glm-4-flash`、`glm-4-air`、`codegeex-4` 等
---
### 月之暗面 Kimi
Kimi 以长文本处理能力著称，适合分析大型代码文件。
**获取 API Key**: https://platform.moonshot.cn/
**配置示例**:
```env
LLM_PROVIDER=moonshot
LLM_API_KEY=sk-your-api-key
LLM_MODEL=moonshot-v1-8k
```
**常用模型**: `moonshot-v1-8k`、`moonshot-v1-32k`、`moonshot-v1-128k`、`kimi-*` 等
---
### 百度文心一言
百度需要同时提供 API Key 和 Secret Key，用冒号分隔：
百度的企业级大模型服务，适合企业用户。
**获取 API Key**: https://console.bce.baidu.com/qianfan/
**⚠️ 特殊配置**: 百度需要同时提供 API Key 和 Secret Key，用冒号分隔：
```env
LLM_PROVIDER=baidu
@ -62,7 +183,72 @@ LLM_API_KEY=your_api_key:your_secret_key
LLM_MODEL=ernie-bot-4
```
### Ollama 本地模型
**常用模型**: `ernie-bot-4`、`ernie-bot-turbo`、`ernie-bot` 等
---
### MiniMax
MiniMax 提供多模态能力，支持文本、语音等多种输入。
**获取 API Key**: https://www.minimaxi.com/
**配置示例**:
```env
LLM_PROVIDER=minimax
LLM_API_KEY=your-api-key
LLM_MODEL=abab6.5-chat
```
---
### 字节豆包
字节跳动的大模型服务，性价比高。
**获取 API Key**: https://console.volcengine.com/ark
**配置示例**:
```env
LLM_PROVIDER=doubao
LLM_API_KEY=your-api-key
LLM_MODEL=doubao-pro-4k
```
---
## 本地部署
### Ollama
Ollama 支持在本地运行开源大模型，完全本地化，隐私安全，适合处理敏感代码。
**安装 Ollama**:
```bash
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh
# Windows
# 访问 https://ollama.com/download 下载安装包
```
**拉取模型**:
```bash
# 通用模型
ollama pull llama3
ollama pull qwen2.5
# 代码专用模型
ollama pull codellama
ollama pull deepseek-coder
ollama pull qwen2.5-coder
```
**配置示例**:
```env
LLM_PROVIDER=ollama
@ -70,13 +256,33 @@ LLM_MODEL=llama3
LLM_BASE_URL=http://localhost:11434/v1
```
推荐模型：
- `llama3` - 综合能力强
- `codellama` - 代码专用
- `qwen2.5` - 中文支持好
- `deepseek-coder` - 代码分析
**推荐模型**:
## 使用 API 中转站
| 模型 | 特点 |
|------|------|
| `llama3` / `llama3.1` / `llama3.2` | Meta 开源，综合能力强 |
| `qwen2.5` / `qwen2.5-coder` | 阿里开源，中文支持好 |
| `codellama` | Meta 代码专用模型 |
| `deepseek-coder` / `deepseek-coder-v2` | DeepSeek 代码模型 |
| `mistral` / `mixtral` | Mistral AI 开源模型 |
**硬件要求**:
| 模型参数 | 最低内存 | 推荐内存 |
|---------|---------|---------|
| 7B | 8GB | 16GB |
| 13B | 16GB | 32GB |
| 70B | 64GB | 128GB |
> 💡 访问 [Ollama 模型库](https://ollama.com/library) 查看所有可用模型。
---
## API 中转站
如果直接访问国际平台有困难，可以使用 API 中转站。
**配置方式**:
```env
LLM_PROVIDER=openai
@ -84,3 +290,42 @@ LLM_API_KEY=中转站提供的Key
LLM_BASE_URL=https://your-proxy.com/v1
LLM_MODEL=gpt-4o-mini
```
**常见中转站**:
| 中转站 | 特点 |
|--------|------|
| [OpenRouter](https://openrouter.ai/) | 支持多种模型，统一接口 |
| [API2D](https://api2d.com/) | 国内访问友好 |
| [CloseAI](https://www.closeai-asia.com/) | 价格实惠 |
---
## 选择建议
### 按场景选择
| 场景 | 推荐 | 原因 |
|------|------|------|
| 日常使用 | OpenAI / 通义千问 / DeepSeek | 性价比高，稳定 |
| 深度分析 | Claude / GPT-4o | 代码理解能力最强 |
| 敏感代码 | Ollama 本地模型 | 完全本地化，隐私安全 |
| 预算有限 | DeepSeek / 智谱 GLM-4-Flash | 价格极低或有免费配额 |
| 长文件分析 | Kimi / Gemini | 支持长上下文 |
### 按预算选择
| 预算 | 推荐方案 |
|------|---------|
| 免费 | Gemini (免费配额) / 智谱 GLM-4-Flash / Ollama |
| 低预算 | DeepSeek / 通义千问 Turbo |
| 中等预算 | GPT-4o-mini / Claude Haiku |
| 高预算 | GPT-4o / Claude Sonnet |
---
## 更多资源
- [配置说明](CONFIGURATION.md) - 详细的配置参数说明
- [部署指南](DEPLOYMENT.md) - 部署相关说明
- [常见问题](FAQ.md) - LLM 相关问题解答

75
frontend/.env.example
View File

@ -1,42 +1,63 @@
# ========================================
# XCodeReviewer 前端环境变量配置示例
# ========================================
# =============================================
# XCodeReviewer 前端环境变量配置
# =============================================
# 复制此文件为 .env 并填写你的配置
# 注意：前后端分离架构下，LLM 配置主要在后端 backend/.env 中设置
# 详细说明请参阅 docs/CONFIGURATION.md
#
# 注意：
# - 前后端分离架构，数据存储在后端 PostgreSQL 数据库
# - LLM 配置主要在后端 backend/.env 中设置
# - 前端可通过 /admin 页面进行运行时配置
# ==================== 后端 API 配置 ====================
# 后端 API 地址（Docker Compose 部署时使用）
# =============================================
# 后端 API 配置
# =============================================
# 后端 API 地址
# - 本地开发: http://localhost:8000/api/v1
# - Docker Compose 部署: /api
VITE_API_BASE_URL=/api
# ==================== 数据库配置 ====================
# 方式1：本地数据库（推荐，开箱即用）
VITE_USE_LOCAL_DB=true
# =============================================
# Git 仓库集成配置（可选）
# =============================================
# 用于前端直接访问公开仓库
# 私有仓库建议在后端 backend/.env 中配置
# 方式2：Supabase 云端数据库（支持多设备同步）
# VITE_SUPABASE_URL=https://your-project.supabase.co
# VITE_SUPABASE_ANON_KEY=your-anon-key-here
# ==================== Git 仓库集成配置 (可选) ====================
# 用于前端直接访问公开仓库（私有仓库建议在后端配置）
# GitHub Token
# GitHub Personal Access Token
# 获取地址: https://github.com/settings/tokens
# VITE_GITHUB_TOKEN=ghp_your_github_token_here
# GitLab Token
# GitLab Personal Access Token
# 获取地址: https://gitlab.com/-/profile/personal_access_tokens
# VITE_GITLAB_TOKEN=glpat-your_gitlab_token_here
# ==================== 应用配置 ====================
# =============================================
# 应用配置
# =============================================
# 应用 ID（用于本地存储隔离）
VITE_APP_ID=xcodereviewer
# ==================== 代码分析配置 ====================
# =============================================
# 代码分析配置
# =============================================
# 单次扫描最大文件数
VITE_MAX_ANALYZE_FILES=40
VITE_LLM_CONCURRENCY=2
VITE_LLM_GAP_MS=500
VITE_OUTPUT_LANGUAGE=zh-CN # zh-CN: 中文 | en-US: 英文
# ========================================
# LLM 并发请求数
VITE_LLM_CONCURRENCY=2
# LLM 请求间隔（毫秒）
VITE_LLM_GAP_MS=500
# 分析结果输出语言
# zh-CN: 中文
# en-US: 英文
VITE_OUTPUT_LANGUAGE=zh-CN
# =============================================
# 重要提示
# ========================================
# =============================================
# 1. LLM 配置（API Key、模型等）请在后端 backend/.env 中设置
# 2. 前端可通过 /admin 页面进行运行时配置
# 3. 本地数据库模式下，数据存储在浏览器 IndexedDB 中
# 2. 前端可通过 /admin 页面进行运行时配置，无需重启服务
# 3. 数据存储在后端 PostgreSQL 数据库中
# 4. 可在 /admin 页面的"数据库管理"中导出/导入数据备份