447 lines
8.9 KiB
Markdown
447 lines
8.9 KiB
Markdown
# 部署指南
|
||
|
||
本文档详细介绍 XCodeReviewer 的各种部署方式，包括 Docker Compose 一键部署、生产环境部署和本地开发环境搭建。
|
||
|
||
## 目录
|
||
|
||
- [快速开始](#快速开始)
|
||
- [Docker Compose 部署（推荐）](#docker-compose-部署推荐)
|
||
- [生产环境部署](#生产环境部署)
|
||
- [本地开发部署](#本地开发部署)
|
||
- [常见部署问题](#常见部署问题)
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
最快的方式是使用 Docker Compose 一键部署：
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone https://github.com/lintsinghua/XCodeReviewer.git
|
||
cd XCodeReviewer
|
||
|
||
# 2. 配置后端环境变量
|
||
cp backend/env.example backend/.env
|
||
# 编辑 backend/.env，配置 LLM API Key
|
||
|
||
# 3. 启动所有服务
|
||
docker-compose up -d
|
||
|
||
# 4. 访问应用
|
||
# 前端: http://localhost:5173
|
||
# 后端 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 前端应用（开发模式，支持热重载） |
|
||
| `backend` | 8000 | FastAPI 后端 API |
|
||
| `db` | 5432 | PostgreSQL 15 数据库 |
|
||
|
||
### 访问地址
|
||
|
||
- 前端应用: 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 .
|
||
|
||
# 运行前端容器
|
||
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+ | 推荐的包管理器 |
|
||
| 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
|
||
```
|
||
|
||
### 后端启动
|
||
|
||
```bash
|
||
# 1. 进入后端目录
|
||
cd backend
|
||
|
||
# 2. 创建虚拟环境（推荐使用 uv）
|
||
uv venv
|
||
source .venv/bin/activate # Linux/macOS
|
||
# 或 .venv\Scripts\activate # Windows
|
||
|
||
# 3. 安装依赖
|
||
uv pip install -e .
|
||
# 或使用 pip
|
||
pip install -r requirements.txt
|
||
|
||
# 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
|
||
# 或 npm install / yarn install
|
||
|
||
# 3. 配置环境变量（可选，也可使用运行时配置）
|
||
cp .env.example .env
|
||
|
||
# 4. 启动开发服务器
|
||
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) - 参与项目开发
|