云端托管的 Dify 够用，但数据出境、API 限流、每月 token 配额这几件事总会在不合时宜的时候让你难受。自部署一套就没这些烦恼——代价是要自己管机器、管证书、管升级。这章把整条路走一遍，顺带把坑标出来。
前置条件
机器规格：最低 2 vCPU / 4 GB RAM（跑完整栈 + 向量数据库），推荐 4 vCPU / 8 GB。磁盘留 40 GB 以上，向量数据会持续增长。
软件依赖：
- Docker Engine 24.0+
- Docker Compose v2（命令是
docker compose，不是旧版docker-compose） - 一个指向该服务器 IP 的域名 A 记录（申请 SSL 证书用）
端口：服务器防火墙放开 80、443、22。不要直接暴露 Dify 内部端口（5001、3000 等）到公网。
架构速览
Dify 的 docker-compose.yaml 默认起八个服务：
| 服务 | 作用 |
|---|---|
api |
Dify 后端 Python Flask，端口 5001 |
web |
Next.js 前端，端口 3000 |
worker |
Celery 异步任务（RAG 索引、回调） |
db |
PostgreSQL，应用元数据 |
redis |
会话缓存 + 任务队列 |
weaviate |
默认向量数据库 |
sandbox |
代码执行沙箱（隔离环境运行用户代码） |
nginx |
内置反向代理，把 /api/ 路由到 api，其余路由到 web |
外层再加一个宿主机 Nginx 做 HTTPS 终端，证书放在宿主机上，内部流量走 HTTP。
Step 1：拉代码，配 .env
git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
.env.example 里有一百多个变量，大多数默认值可以直接用。必须改的几个：
# .env — 必改项
# 换成强随机字符串（openssl rand -hex 32 生成）
SECRET_KEY=your-random-secret-key-here
# 换成你的域名（后面配完 HTTPS 再改成 https://）
CONSOLE_URL=https://dify.example.com
APP_URL=https://dify.example.com
# 如果宿主机 80/443 已被占用，把内置 nginx 挪到别的端口
EXPOSE_NGINX_PORT=8080
EXPOSE_NGINX_SSL_PORT=8443
SECRET_KEY 不改的话用的是示例值，等于把签名密钥公开，任何人都能伪造 session。
选择向量数据库
默认是 Weaviate。如果你已经有 Qdrant 或 Milvus，在 .env 里改：
VECTOR_STORE=qdrant
QDRANT_URL=http://your-qdrant-host:6333
QDRANT_API_KEY=your-key
不改的话直接用内置 Weaviate 就行，零额外配置。
Step 2：启动 Dify 容器栈
cd dify/docker
docker compose up -d
第一次启动会拉镜像，根据网速大概要 3-8 分钟。确认所有服务跑起来：
docker compose ps
期望输出每个服务都是 Up（healthy 更好）。如果 api 或 worker 反复重启，先看日志：
docker compose logs api --tail 50
docker compose logs worker --tail 50
最常见原因：.env 的 SECRET_KEY 没改，或者 PostgreSQL 还没完成初始化就被 api 连接了——后者等十秒再 docker compose restart api 一般能解决。
Step 3：宿主机 Nginx 反向代理
内置 Nginx 监听 8080（或者你在 .env 里设的端口），宿主机 Nginx 在 80/443 做 TLS 终端，然后把流量转发进去。
先装 Nginx：
# Ubuntu/Debian
sudo apt install nginx -y
创建站点配置（先只配 HTTP，等会儿 Certbot 会自动改成 HTTPS）：
# /etc/nginx/sites-available/dify
server {
listen 80;
server_name dify.example.com;
# 大文件上传（知识库文档）
client_max_body_size 100M;
location / {
proxy_pass http://127.0.0.1:8080;
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;
# WebSocket 支持（Dify 控制台用到）
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;
proxy_connect_timeout 10s;
}
}
启用并测试：
sudo ln -s /etc/nginx/sites-available/dify /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
此时用 curl http://dify.example.com 应该能拿到 Dify 前端的 HTML。
Step 4：Certbot 申请 SSL 证书
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d dify.example.com
Certbot 会自动修改你的 Nginx 配置，加上 ssl_certificate、ssl_certificate_key，并把 80 端口重定向到 443。完成后验证：
sudo nginx -t && sudo systemctl reload nginx
curl -I https://dify.example.com
# 期望看到 HTTP/2 200
证书 90 天到期，Certbot 的 systemd timer 会自动续期，不需要手动操作。
最终 Nginx 配置长这样
Certbot 改完之后，配置大概是：
server {
listen 80;
server_name dify.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name dify.example.com;
ssl_certificate /etc/letsencrypt/live/dify.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/dify.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
client_max_body_size 100M;
location / {
proxy_pass http://127.0.0.1:8080;
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 https;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;
}
}
注意 X-Forwarded-Proto https 硬编码成 https，不用 $scheme——因为宿主机到容器那段是 HTTP，如果用 $scheme 传进去的是 http，Dify 生成的链接会变成 http:// 开头，表单提交 CSRF 校验会报错。
Step 5：Dify 首次初始化
打开浏览器访问 https://dify.example.com，进入管理员账号创建页面。填完邮箱和密码，登进控制台，去「设置 → 模型供应商」填你的 OpenAI / Anthropic / 本地 Ollama 的 API Key。
如果你用 Ollama 或 LiteLLM 这类本地模型，BASE_URL 要填宿主机内网 IP 而不是 localhost，容器里的 localhost 解析不到宿主机。Docker Compose 默认网络下，用 host.docker.internal（Mac/Windows）或宿主机内网 IP（Linux）。
升级 Dify
cd dify/docker
git pull
docker compose pull
docker compose down
docker compose up -d
数据卷（PostgreSQL、Weaviate、上传文件）挂在命名 volume 上，down 不会删数据。但升级前建议先备份 PostgreSQL：
docker compose exec db pg_dump -U postgres dify > dify-backup-$(date +%Y%m%d).sql
常见问题排查
问：首页白屏，控制台报 502
先看 docker compose ps，确认 api 和 web 都在跑。再检查宿主机 Nginx 的 proxy_pass 端口有没有对上 .env 里的 EXPOSE_NGINX_PORT。
问：上传知识库文档报 413 Request Entity Too Large
Nginx 默认限制 1MB。在宿主机 Nginx 配置里加 client_max_body_size 100M;（已在上面的示例里包含）。
问：certbot 报 "Could not bind to IPv4 or IPv6"
certbot --nginx 的 standalone 模式需要占用 80 端口，但你的 Nginx 已经在用。用 --nginx 插件就好（不是 --standalone），它会和 Nginx 协作，不需要停服。
问：Dify 生成的链接是 http:// 不是 https://
.env 里的 CONSOLE_URL 和 APP_URL 还没改成 https://。改完 docker compose restart api 生效。
问：磁盘快满了
向量数据、Docker 镜像层和日志是三大占用。清理未使用镜像：docker image prune -f。Weaviate 数据在 volumes/weaviate，没有简单缩容方法，规划时提前留够空间。
自部署的核心优势是数据完全在自己手里，模型调用也走自己的 API Key，适合有数据合规要求或者用量大的场景。跑起来之后日常维护很少，主要就是偶尔升级版本和看一眼磁盘使用率。
