部署指南

架构概览

DeepDiagram 生产环境由以下服务组成：

服务	技术栈	镜像
前端	React 19 + Nginx	twwch/deepdiagram-frontend:latest
后端	FastAPI + LangGraph	twwch/deepdiagram-backend:latest
数据库	PostgreSQL 16	postgres:16-alpine

Docker Compose 部署

1. 创建项目目录

mkdir deepdiagram && cd deepdiagram

2. 创建 docker-compose.yml

version: '3.8'

services:
  db:
    image: postgres:16-alpine
    container_name: deepdiagram-db
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: your_secure_password
      POSTGRES_DB: deepdiagram
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  backend:
    image: twwch/deepdiagram-backend:latest
    container_name: deepdiagram-backend
    restart: always
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:your_secure_password@db:5432/deepdiagram
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - OPENAI_BASE_URL=${OPENAI_BASE_URL}
      - MODEL_ID=${MODEL_ID}
      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
      - DEEPSEEK_BASE_URL=${DEEPSEEK_BASE_URL}
    ports:
      - "8000:8000"

  frontend:
    image: twwch/deepdiagram-frontend:latest
    container_name: deepdiagram-frontend
    restart: always
    depends_on:
      - backend
    ports:
      - "80:80"

volumes:
  pgdata:

3. 创建 .env 文件

OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.openai.com
MODEL_ID=gpt-4o

4. 启动

docker compose up -d

环境变量说明

模型配置

变量	默认值	说明
OPENAI_API_KEY	无	OpenAI API 密钥
OPENAI_BASE_URL	https://api.openai.com	OpenAI API 地址
MODEL_ID	无	模型 ID，如 gpt-4o、deepseek-chat
DEEPSEEK_API_KEY	无	DeepSeek API 密钥（设置后优先使用）
DEEPSEEK_BASE_URL	https://api.deepseek.com	DeepSeek API 地址
MAX_TOKENS	16384	最大上下文长度
THINKING_VERBOSITY	normal	思考详细程度：concise、normal、verbose

数据库配置

变量	默认值	说明
DATABASE_URL	见 docker-compose	PostgreSQL 异步连接字符串

可观测性

变量	默认值	说明
LANGCHAIN_TRACING_V2	false	启用 LangSmith 链路追踪
LANGCHAIN_API_KEY	无	LangSmith API 密钥

Nginx 反向代理

如果你需要通过域名访问并启用 HTTPS，可以在前端添加 Nginx 网关。

示例 nginx.conf

upstream frontend {
    server frontend:80;
}

upstream backend {
    server backend:8000;
}

server {
    listen 80;
    server_name your-domain.com;

    client_max_body_size 200m;

    location / {
        proxy_pass http://frontend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # API 代理
    location /api {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # SSE 支持（重要）
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding off;
    }
}

SSE（Server-Sent Events）需要关闭 proxy_buffering，否则流式响应会被缓冲。

数据持久化

PostgreSQL 数据通过 Docker Volume pgdata 持久化。

备份数据库

docker exec deepdiagram-db pg_dump -U postgres deepdiagram > backup.sql

恢复数据库

cat backup.sql | docker exec -i deepdiagram-db psql -U postgres deepdiagram

更新版本

# 拉取最新镜像
docker compose pull

# 重启服务
docker compose up -d

从源码构建

如果你需要自定义构建：

git clone https://github.com/twwch/DeepDiagram.git
cd DeepDiagram
docker compose up -d --build

常见问题

后端无法连接数据库

• 检查 DATABASE_URL 中的密码是否与 POSTGRES_PASSWORD 一致
• 确认 db 容器已启动：docker compose ps

LLM 调用失败

• 确认 API Key 有效且有余额
• 检查 OPENAI_BASE_URL 是否正确
• 查看后端日志：docker compose logs -f backend

SSE 连接中断

• 确认 Nginx 配置了 proxy_buffering off
• 检查 proxy_read_timeout 是否足够（建议 300s）

文件上传失败

• 检查 Nginx 的 client_max_body_size 配置（默认 200MB）