9.2 KiB

Raw Blame History

部署指南

本文档详细介绍 XCodeReviewer 的各种部署方式，包括 Docker Compose 一键部署、生产环境部署和本地开发环境搭建。

快速开始

最快的方式是使用 Docker Compose 一键部署：

# 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

演示账户

系统启动时会自动创建演示账户，包含示例项目和审计数据，可直接体验完整功能：

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

⚠️ 安全提示: 生产环境部署后，请删除演示账户或修改密码。

Docker Compose 部署（推荐）

完整的前后端分离部署方案，包含前端、后端和 PostgreSQL 数据库。

系统要求

Docker 20.10+
Docker Compose 2.0+
至少 2GB 可用内存
至少 5GB 可用磁盘空间

部署步骤

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

# 2. 配置后端环境变量
cp backend/env.example backend/.env

编辑 backend/.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

# 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

常用命令

# 停止所有服务
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 镜像

# 拉取最新镜像
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

方式二：本地构建生产镜像

# 构建前端生产镜像（使用 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

方式三：手动部署

前端部署

cd frontend

# 安装依赖
pnpm install

# 构建生产版本
pnpm build

# 将 dist 目录部署到 Nginx/Apache 等 Web 服务器

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;
    }
}

后端部署

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

生产环境安全建议

修改默认密钥：务必修改 SECRET_KEY 为随机字符串
配置 HTTPS：使用 Let's Encrypt 或其他 SSL 证书
限制 CORS：在生产环境配置具体的前端域名
数据库安全：修改默认数据库密码，限制访问 IP
API 限流：配置 Nginx 或应用层限流
日志监控：配置日志收集和监控告警

本地开发部署

适合需要开发或自定义修改的场景。

环境要求

依赖	版本要求	说明
Node.js	18+	前端运行环境
Python	3.13+	后端运行环境
PostgreSQL	15+	数据库
pnpm	8+	推荐的包管理器
uv	最新版	推荐的 Python 包管理器

数据库准备

# 方式一：使用 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

后端启动

# 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

前端启动

# 1. 进入前端目录
cd frontend

# 2. 安装依赖
pnpm install
# 或 npm install / yarn install

# 3. 配置环境变量（可选，也可使用运行时配置）
cp .env.example .env

# 4. 启动开发服务器
pnpm dev

# 5. 访问应用
# 浏览器打开 http://localhost:5173

开发工具

# 前端代码检查
cd frontend
pnpm lint
pnpm type-check

# 前端代码格式化
pnpm format

# 后端类型检查
cd backend
mypy app

# 后端代码格式化
ruff format app

数据存储

XCodeReviewer 采用前后端分离架构，所有数据存储在后端 PostgreSQL 数据库中。

数据管理

在 /admin 页面的"数据库管理"标签页中，可以：

导出数据: 将所有数据导出为 JSON 文件备份
导入数据: 从 JSON 文件恢复数据
清空数据: 删除所有数据（谨慎操作）
健康检查: 检查数据库连接状态和数据完整性

数据库备份

# 导出 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: 容器启动失败，提示端口被占用

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

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

Q: 数据库连接失败

# 检查数据库容器状态
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 镜像已包含。本地开发时：

# 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 请求超时

# 增加超时时间
LLM_TIMEOUT=300

# 降低并发数
LLM_CONCURRENCY=1

# 增加请求间隔
LLM_GAP_MS=3000

前端相关

Q: 前端无法连接后端 API

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

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

# Docker Compose 部署
VITE_API_BASE_URL=/api

9.2 KiB Raw Blame History Unescape Escape