Dify 自建部署完全指南：从上手到放弃到真香

故事的开始：就想要个听话的 AI 应用平台

几个月前，老板突然找到小禾：“那个谁啊，咱们也得搞个 AI 应用平台，要能接入各种模型，数据必须在自己手里，最好下周就能用上。”

小禾心想，这不是 Coze 吗？打开浏览器准备注册账号，突然想起上次数据合规会议上法务部那张严肃的脸…“所有客户数据不得上传至第三方平台”。

好吧，Coze pass。

接下来的一周，小禾像个 AI 应用平台评测博主，把市面上能找到的都试了个遍：

Coze（字节跳动） —— “哇，这 UI 真香！插件真多！” → “等等，数据要上传？告辞。”

FastGPT —— “知识库功能不错” → “工作流怎么这么简陋？”

LangFlow —— “节点拖拽很酷” → “为啥总是莫名其妙报错？”

最后，小禾想到了 Dify。

特性	状态
开源？	是
私有化？	是
支持各种模型？	是
工作流强大？	是
Star 数 45k+？	是

"就是你了！"小禾信心满满地对老板说：“给我两天时间，保证搞定！”

然后，小禾用了整整两周…

这篇文章，就是这两周血泪史的完整记录。如果你也准备自建 Dify，建议先泡杯茶，因为这趟旅程，有点长。

---

第一天：看着文档信心满满

拿到任务后的第一件事，当然是看官方文档。Dify 的文档写得还挺详细，甚至贴心地提供了 docker-compose.yaml。

小禾脑海里已经规划好了整个架构：

"Docker Compose 一把梭，两小时搞定！"小禾甚至已经开始想象老板赞许的眼神了。

然后小禾 clone 了代码：

git clone https://github.com/langgenius/dify.git
cd dify
docker-compose up -d

5分钟后，小禾的屏幕上满是红色的报错信息…

---

第二天到第五天：PostgreSQL，你到底要我怎样？

Day 2：数据库启动失败的早晨

早上8点，小禾泡好了一杯大补茶，准备解决昨天的报错。看了下日志：

FATAL: role "postgres" does not exist
db init failed, retrying...
db init failed, retrying...
db init failed, retrying...

"postgres 角色不存在？"小禾挠了挠头，这不是 PostgreSQL 的默认超级用户吗？

接下来的4个小时，小禾尝试了：

• 改环境变量 ✗
• 改密码 ✗
• 改用户名 ✗
• 改端口 ✗
• 改人生 ✗（开玩笑的）

中午吃饭的时候，小禾突然灵光一闪：“不会是之前的容器残留数据吧？”

果然！docker volume ls 一看，一堆 dify 相关的 volumes 躺在那里。原来 Docker 的 Volume 是持久化的，即使容器删了，数据还在。而 PostgreSQL 有个特性：如果数据目录非空，就不会重新初始化。

# 终极大招
docker-compose down -v  # 连 volume 一起删
docker volume prune -f  # 再补一刀
rm -rf ./volumes/db/*   # 物理删除，以防万一

再次启动，终于看到了期待已久的：

PostgreSQL Database directory appears to contain a database
db_1 | PostgreSQL init process complete; ready for start up.

那一刻，小禾差点热泪盈眶。

Day 3：77 张表的灵异事件

数据库起来了，心情大好。打开 pgAdmin 连上去看看，准备欣赏一下空荡荡的数据库。

结果…77 张表整整齐齐地摆在那里。

“我还没初始化呢，哪来的表？” 小禾开始怀疑是不是撞鬼了。

仔细一看表名：migrations、users、apps…这不是 Dify 的表吗？可是明明刚删除了所有数据啊？

花了一下午排查，终于发现真相。原来，在调试过程中，多次使用 git restore docker-compose.yaml 还原配置文件，每次都会生成不同的 volume 名称。而 PostgreSQL 每次都会找到某个旧的 volume 并加载。

这就像是，你以为自己住进了新房子，结果发现上一任租客的家具都还在。

教训：不只是要删 volume，还要确保 volume 名称一致，或者干脆用绝对路径挂载。

Day 4：前端白屏的下午茶时光

数据库搞定了，服务也都起来了。下午3点，小禾按照惯例泡了杯茶，准备欣赏自己的劳动成果。

打开浏览器，输入 http://localhost:3000

白屏。

F12 打开控制台：

GET http://localhost:3000/static/js/main.chunk.js 404
GET http://localhost:3000/static/css/main.css 404
Uncaught ReferenceError: React is not defined

“静态资源 404？” 进到容器里一看，文件明明都在 /app/web/dist 目录下。

又是两个小时的排查，发现是 Nginx 配置的问题。Dify 的前端容器已经自带了一个 Node 服务器，不需要 Nginx 直接代理静态文件，而是要代理到这个 Node 服务器。

正确的配置应该是：

location / {
    proxy_pass http://web:3000;  # 注意是 3000 端口，不是 80
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

改完配置，nginx -s reload，页面终于出来了！

那个熟悉的 Dify Logo 出现在屏幕上时，感觉就像见到了老朋友。

Day 5：DeepSeek，你不按套路出牌啊

基础环境搞定，开始接入模型。OpenAI 的接入很顺利，毕竟是行业标准。但到了 DeepSeek…

在 Dify 后台填入：

• API Base: https://api.deepseek.com/v1
• API Key: sk-xxxx

测试连接，转了半天，超时。

“不应该啊，我在本地用 curl 测试是正常的。”

# 本地测试 OK
curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "Hi"}]}'

进到 Dify API 容器里再测试，也 OK。但从 Dify 界面就是不行。

抓包，看日志，翻源码…晚上11点，终于发现问题：DeepSeek 的 API 在处理 HTTP/2 请求时有些特殊，而 Dify 使用的 Python requests 库在某些情况下会强制使用 HTTP/2。

解决方案很魔幻：用 Nginx 做个中转，强制降级到 HTTP/1.1。

# deepseek 专用转发
location /deepseek-proxy/ {
    proxy_pass https://api.deepseek.com/;
    proxy_http_version 1.1;  # 关键是这行
    proxy_ssl_server_name on;
    proxy_set_header Host api.deepseek.com;
    proxy_set_header Authorization $http_authorization;
}

然后在 Dify 里填 http://nginx/deepseek-proxy 作为 API Base。

虽然解决了，但总感觉像是用创可贴修补软件 bug…

---

第六天：SGLang，一个空格引发的血案

自建模型也要接进来。我们用的是 SGLang，一个高性能的推理框架。部署很顺利，API 也通了，但开启流式输出后，Dify 又开始报错：

Invalid chunk format: expecting 'data:' prefix

“data: 前缀？明明有啊！” 小禾盯着返回的数据看了半天。

用 Postman 测试 SGLang 的流式输出：

data:{"choices":[{"delta":{"content":"Hello"}}]}

用 Postman 测试 OpenAI 的流式输出：

data: {"choices": [{"delta": {"content": "Hello"}}]}

你发现区别了吗？小禾盯了 10 分钟才发现：SGLang 在 data: 后面少了一个空格！

就这么一个空格，调试了整整一个晚上。

最后写了个中间件专门加空格：

async def fix_sse_format(original_stream):
    async for chunk in original_stream:
        if chunk.startswith(b'data:') and not chunk.startswith(b'data: '):
            chunk = b'data: ' + chunk[5:]  # 加个空格
        yield chunk + b'\n\n'

当这个 fix 生效的时候，小禾的心情很复杂。一方面终于解决了问题，另一方面觉得"程序员的人生就是在处理各种空格、分号、括号"…

---

第七天到第十天：从"能跑"到"能用"

基础环境搭好了，模型也接通了，但这只是"能跑"，离"能用"还有距离。

性能优化：为什么这么慢？

第一个用户反馈来了：“为什么第一次对话要等 5 秒钟？”

测了一下，确实慢：

• 冷启动：3-5 秒
• 知识库检索：10+ 秒
• 并发 20 人就开始卡

开始优化之旅：

1. 模型连接预热

原来每次用户第一次对话，Dify 才会去建立模型连接。改成启动时预加载：

# 启动时就把常用模型连接建好
PRELOAD_MODELS = ['gpt-4', 'deepseek-chat', 'local-llama']
for model in PRELOAD_MODELS:
    try:
        test_connection(model)
        logger.info(f"Model {model} preloaded")
    except:
        logger.error(f"Failed to preload {model}")

2. 数据库连接池

默认连接池太小了，高并发直接爆：

environment:
  - SQLALCHEMY_POOL_SIZE=20  # 原来是 5
  - SQLALCHEMY_MAX_OVERFLOW=40  # 原来是 10

3. 向量检索优化

知识库用的是向量数据库，默认是暴力搜索。改成 HNSW 索引后，检索速度提升 10 倍：

CREATE INDEX idx_embeddings ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

优化后的效果：

指标	优化前	优化后
冷启动	3.2s	0.8s
知识库检索	12s	1.5s
并发支持	20	200
内存占用	8GB	3GB

日志，我的日志去哪了？

多容器环境最头疼的就是查日志。出问题了，要进好几个容器挨个看：

docker logs dify-api
docker logs dify-web
docker logs dify-worker
docker logs nginx

搞了个 ELK Stack，但太重了。最后选了 Grafana Loki，轻量级正合适：

services:
  loki:
    image: grafana/loki:latest
    volumes:
      - ./loki-config.yaml:/etc/loki/config.yaml
    command: -config.file=/etc/loki/config.yaml

  promtail:
    image: grafana/promtail:latest
    volumes:
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - ./promtail-config.yaml:/etc/promtail/config.yaml
    command: -config.file=/etc/promtail/config.yaml

现在所有日志都能在 Grafana 里统一查询了，爽！

---

第十一天：上线前的最后准备

HTTPS，一定要有 HTTPS

测试环境用 HTTP 没问题，但生产环境必须上 HTTPS。不然：

• WebSocket 连不上
• 浏览器警告不安全
• SSE 流式输出各种问题

用 Let’s Encrypt 免费证书：

certbot certonly --webroot -w /var/www/html -d your-domain.com

Nginx 配置：

server {
    listen 443 ssl http2;
    ssl_certificate /etc/letsencrypt/live/your-domain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain/privkey.pem;

    # SSL 优化
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
}

备份，永远不要忘记备份

写了个定时备份脚本：

#!/bin/bash
# backup.sh

BACKUP_DIR="/backup/dify/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# 备份数据库
docker exec postgres pg_dump -U postgres dify > $BACKUP_DIR/db.sql

# 备份配置文件
cp -r ./docker ./volumes $BACKUP_DIR/

# 备份上传的文件
docker cp dify-api:/app/storage $BACKUP_DIR/storage

# 保留最近 7 天的备份
find /backup/dify -type d -mtime +7 -exec rm -rf {} +

加到 crontab，每天凌晨 3 点自动备份：

0 3 * * * /path/to/backup.sh

---

第十四天：终于，真香了

两周过去了，Dify 终于稳定运行起来。看着监控面板上平稳的曲线，小禾长舒一口气。

现在的架构图变成了这样：

回头看小禾这两周的经历：

踩过的坑：

• PostgreSQL 初始化问题
• Docker Volume 的坑
• 静态资源 404
• DeepSeek HTTP/2 不兼容
• SGLang 流式输出格式
• 性能优化
• 日志收集
• HTTPS 配置

收获的经验：

1. 永远先看日志 - 90% 的问题都能从日志里找到答案
2. Volume 要谨慎 - Docker Volume 是持久化的，删容器不会删数据
3. HTTP 协议细节很重要 - 一个空格、一个版本号都可能导致问题
4. 监控要先行 - 没有监控就像闭着眼睛开车
5. 备份是救命稻草 - 永远不要相信"不会出问题"

---

写在最后：到底值不值？

如果你问花两周时间部署 Dify 值不值？

答案是：值，不过也得看情况。

如果：

• 完全掌控数据
• 灵活接入各种模型
• 深度定制功能
• 无限制的 API 调用
• 可长期演进的平台

那 Dify 自建绝对是正确选择。

但如果：

• 只是想快速体验 AI 应用
• 团队没有运维能力
• 对数据安全没有强要求
• 不需要定制化功能

那还是用 SaaS 版本吧，真的能省很多事。

最后，如果你真的要自建 Dify，这份避坑指南希望能帮到你：

🎯 快速避坑清单

# 1. 彻底清理环境
docker-compose down -v
docker volume prune -f
rm -rf ./volumes/*

# 2. 检查端口占用
netstat -tulpn | grep -E '5432|6379|3000|5001'

# 3. 正确的启动顺序
docker-compose up -d db redis
sleep 30  # 等待数据库初始化
docker-compose up -d

# 4. 验证服务状态
curl http://localhost:5001/health
curl http://localhost:3000

# 5. 查看日志
docker-compose logs -f

# 6. 进容器调试
docker exec -it dify-api bash
docker exec -it dify-db psql -U postgres -d dify

📦 完整部署模板

最终稳定运行的配置整理成了模板，需要的朋友可以直接用：

# docker-compose.yaml
version: '3.8'

services:
  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - web
      - api
    restart: always

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: difyai123456
      POSTGRES_DB: dify
    volumes:
      - ./volumes/db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: always

  redis:
    image: redis:7-alpine
    volumes:
      - ./volumes/redis:/data
    command: redis-server --appendonly yes
    restart: always

  web:
    image: langgenius/dify-web:1.10.0
    environment:
      API_URL: https://your-domain.com/api
    depends_on:
      - api
    restart: always

  api:
    image: langgenius/dify-api:1.10.0
    environment:
      # 数据库配置
      DB_HOST: db
      DB_PORT: 5432
      DB_USERNAME: postgres
      DB_PASSWORD: difyai123456
      DB_DATABASE: dify

      # Redis 配置
      REDIS_HOST: redis
      REDIS_PORT: 6379

      # 性能优化
      SQLALCHEMY_POOL_SIZE: 20
      SQLALCHEMY_MAX_OVERFLOW: 40

      # 其他配置
      SECRET_KEY: your-secret-key-change-this
      STORAGE_TYPE: local
    depends_on:
      - db
      - redis
    volumes:
      - ./volumes/storage:/app/storage
    restart: always

---

部署 Dify 的这两周，从上手到放弃，再到真香，经历了一个完整的心路历程。

现在回想起来，那些深夜调试的时光、那些因为一个空格抓狂的瞬间、那些终于跑通后的喜悦，都成了宝贵的经验。

技术的路上，踩坑是常态，但每个坑都是成长的机会。

希望这篇文章能让你少踩一些坑，早点体验到 Dify 的"真香"。

如果你在部署过程中遇到问题，欢迎交流。毕竟，踩坑的人多了，坑就变成了路。