8.7 KiB

Raw Blame History

部署指南

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

快速开始

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

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

# 2. 配置后端环境变量
cp backend/env.example backend/.env
# 编辑 backend/.env，配置 LLM API Key

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

# 4. 访问应用
# 前端: http://localhost:3000
# 后端 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/DeepAudit.git
cd DeepAudit

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

编辑 backend/.env 文件，配置必要参数：

# 数据库配置（Docker Compose 会自动处理）
POSTGRES_SERVER=db
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=deepaudit

# 安全配置（生产环境请修改）
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`	3000	React 前端应用（生产构建，使用 serve 提供静态文件）
`backend`	8000	FastAPI 后端 API（使用 uv 管理依赖）
`db`	5432	PostgreSQL 15 数据库

访问地址

前端应用: http://localhost:3000
后端 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 sh
docker compose exec db psql -U postgres -d deepaudit

生产环境部署

Docker Compose 默认配置已适用于生产环境：

前端：构建生产版本，使用 serve 提供静态文件服务
后端：使用 uv 管理依赖，镜像内包含所有依赖
数据库：使用 Docker Volume 持久化数据

生产环境安全建议

修改默认密钥：务必修改 SECRET_KEY 为随机字符串
配置 HTTPS：使用 Nginx 反向代理并配置 SSL 证书
限制 CORS：在生产环境配置具体的前端域名
数据库安全：修改默认数据库密码，限制访问 IP
API 限流：配置 Nginx 或应用层限流
日志监控：配置日志收集和监控告警
删除演示账户：生产环境请删除或禁用 demo 账户

Nginx 反向代理配置（可选）

如需使用 Nginx 提供 HTTPS 和统一入口：

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # 前端
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # API 代理
    location /api/ {
        proxy_pass http://localhost:8000/api/;
        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;
    }
}

本地开发部署

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

环境要求

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

数据库准备

# 方式一：使用 Docker 启动 PostgreSQL（推荐）
docker run -d \
  --name deepaudit-db \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=deepaudit \
  -p 5432:5432 \
  postgres:15-alpine

# 方式二：使用本地 PostgreSQL
createdb deepaudit

后端启动

# 1. 进入后端目录
cd backend

# 2. 安装 uv（如未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 同步依赖
uv sync

# 4. 配置环境变量
cp env.example .env
# 编辑 .env 文件，配置数据库和 LLM 参数

# 5. 初始化数据库
uv run alembic upgrade head

# 6. 启动后端服务（开发模式，支持热重载）
uv run uvicorn app.main:app --reload --port 8000

前端启动

# 1. 进入前端目录
cd frontend

# 2. 安装依赖
pnpm install

# 3. 配置环境变量（可选）
cp .env.example .env

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

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

开发工具

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

# 前端代码格式化
pnpm format

# 后端类型检查
cd backend
uv run mypy app

# 后端代码格式化
uv run ruff format app

数据存储

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

数据管理

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

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

数据库备份

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

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

常见部署问题

Docker 相关

Q: 容器启动失败，提示端口被占用

# 检查端口占用
lsof -i :3000
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: 构建时网络问题（代理相关）

如果构建时遇到网络问题，检查 Docker Desktop 的代理设置：

打开 Docker Desktop → Settings → Resources → Proxies
关闭代理或配置正确的代理地址
重启 Docker Desktop
重新构建：docker compose build --no-cache

后端相关

Q: PDF 导出功能报错（WeasyPrint 依赖问题）

Docker 镜像已包含 WeasyPrint 所需的系统依赖。本地开发时需要安装：

# macOS
brew install pango cairo gdk-pixbuf libffi

# Ubuntu/Debian
sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 libglib2.0-0

# Windows - 参见 FAQ.md 中的详细说明

Q: LLM API 请求超时

# 增加超时时间
LLM_TIMEOUT=300

# 降低并发数
LLM_CONCURRENCY=1

# 增加请求间隔
LLM_GAP_MS=3000

前端相关

Q: 前端无法连接后端 API

Docker Compose 部署时，前端通过 http://localhost:8000/api/v1 访问后端。确保：

后端容器正常运行：docker compose ps backend
后端端口 8000 可访问：curl http://localhost:8000/docs

本地开发时，检查 frontend/.env 中的 API 地址配置：

VITE_API_BASE_URL=http://localhost:8000/api/v1

8.7 KiB Raw Blame History Unescape Escape