Dify 如何配置反向代理？Nginx 部署实战指南
在当前 AI 应用快速落地的背景下，越来越多团队选择使用Dify——这个开源的 LLM 应用开发平台，来构建智能客服、知识库问答、自动化内容生成等系统。它提供了可视化编排、Prompt 工程支持和 RAG 流程设计能力，极大降低了大模型应用的开发门槛。
但一个常见的问题是：如何将本地运行的 Dify 服务安全、稳定地暴露给外部用户？
答案很明确：通过Nginx 反向代理进行生产级部署。这不仅是最佳实践，更是企业级部署的标配方案。
为什么不能直接暴露 Dify 服务？
你可能已经用docker-compose up成功启动了 Dify，并通过http://your-server-ip:3000访问到了前端界面。但这只是“能用”，远未达到“可用”和“可靠”。
直接暴露容器服务存在几个致命问题：
- 端口暴露风险高：开放 3000 或 5001 端口等于把后端接口直接摆在攻击者面前；
- 缺乏 HTTPS 加密：数据明文传输，敏感信息（如 API Key）极易被截获；
- 无法实现统一域名访问：难以与公司已有域名体系整合；
- 不支持大文件上传：默认配置下 Nginx 会拒绝超过 1MB 的请求体；
- WebSocket 支持缺失：实时日志流、Agent 输出等功能依赖长连接，需特殊头设置才能穿透代理。
而这些问题，都可以通过 Nginx 反向代理一次性解决。
Dify 容器架构解析：你知道它的内部是怎么工作的吗？
要正确配置反向代理，首先得理解 Dify 的服务结构。
Dify 使用前后端分离架构，主要由以下几个核心组件构成：
| 服务 | 端口 | 功能 |
|---|---|---|
| Web UI | 3000 | 前端 React 应用，提供图形化操作界面 |
| API Server | 5001 | 后端服务，处理 Prompt 执行、RAG 检索、Agent 调度等逻辑 |
| Worker | - | 异步任务处理器（文档解析、向量化等） |
| PostgreSQL / Redis | 5432 / 6379 | 数据存储与缓存 |
当你使用官方 Docker Compose 文件启动时，这些服务会在同一个网络内协同工作。但对外暴露的，通常只有前端和 API 接口。
关键点在于：前端页面通过浏览器发起的/api请求，目标其实是后端 API 服务（5001）。如果反向代理没有正确路由这些路径，就会导致“页面能打开，但功能不可用”的尴尬情况。
更复杂的是，Dify 中某些功能（如 Agent 实时输出）依赖 WebSocket 连接，路径通常是/socket.io，这也需要特别处理。
Nginx 反向代理：不只是转发请求这么简单
很多人以为反向代理就是加个proxy_pass就完事了，其实不然。一个健壮的 Nginx 配置，应该具备以下能力：
- ✅ 路径级精准路由（区分静态资源、API、WebSocket）
- ✅ 安全的 HTTPS 终止
- ✅ 正确传递客户端真实 IP
- ✅ 支持大文件上传（如 PDF 导入）
- ✅ 长连接与超时控制
- ✅ Gzip 压缩优化性能
- ✅ 自动跳转 HTTPS
下面我们一步步拆解一份生产可用的 Nginx 配置。
完整 Nginx 配置示例
# HTTP 端口监听，强制重定向到 HTTPS server { listen 80; server_name dify.example.com; # 全局 301 跳转，确保所有流量走加密通道 return 301 https://$server_name$request_uri; } # HTTPS 主服务块 server { listen 443 ssl http2; server_name dify.example.com; # SSL 证书配置（Let's Encrypt 示例） 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 ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512; ssl_prefer_server_ciphers off; # HSTS 强制浏览器后续请求都使用 HTTPS add_header Strict-Transport-Security "max-age=31536000" always; # 启用 Gzip 压缩，减少传输体积 gzip on; gzip_vary on; gzip_min_length 1024; gzip_types text/plain text/css text/xml application/json application/javascript application/xml+rss; # 允许最大 50MB 文件上传（Dify 文档导入所需） client_max_body_size 50M; # 通用代理参数设置 proxy_http_version 1.1; 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; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 300s; # 长响应支持（如流式输出） # 前端主页面代理 location / { proxy_pass http://127.0.0.1:3000; proxy_redirect off; } # API 接口代理到后端服务 location /api { proxy_pass http://127.0.0.1:5001; proxy_redirect off; } # WebSocket 支持（用于实时日志、Agent 流式输出） location /socket.io { proxy_pass http://127.0.0.1:5001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } }关键配置项详解：每一行都有它的意义
1.return 301 https://...
HTTP 到 HTTPS 的永久重定向是基本安全要求。现代浏览器对非 HTTPS 站点标记为“不安全”，影响用户体验。
2. SSL 配置建议
- 使用 Let’s Encrypt 免费证书即可满足绝大多数场景；
- 推荐配合 Certbot 实现自动续期（
certbot renew --quiet加入 cron）； - 不要使用自签名证书，会导致浏览器警告。
3.X-Forwarded-*头的作用
Dify 的后端服务需要知道原始请求的协议（HTTP/HTTPS）、客户端 IP 和主机名，否则可能出现：
- 回调地址错误（如 OAuth 登录跳转回http://）；
- 日志中记录的全是127.0.0.1，无法追踪真实访问来源。
因此必须设置：
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;4.client_max_body_size 50M
Dify 支持上传文档构建知识库，默认 Nginx 限制为 1M，超出即返回 413 错误。根据业务需求可调整至 50M 或更高。
⚠️ 注意：同时需检查 Dify 后端是否允许大文件上传，部分版本需在
.env中设置MAX_CONTENT_LENGTH。
5. WebSocket 长连接支持
Upgrade和Connection头是启用 WebSocket 的关键。缺少它们会导致：
- 实时日志无输出；
- Agent 流式回答卡顿或中断；
- 页面提示 “Failed to connect to server”。
务必单独为/socket.io路径配置升级头。
部署流程：从配置到上线
完成配置后，执行以下命令启用站点：
# 创建软链接激活配置 sudo ln -s /etc/nginx/sites-available/dify.conf /etc/nginx/sites-enabled/ # 测试配置语法是否正确 sudo nginx -t # 重新加载 Nginx（无需重启服务） sudo systemctl reload nginx如果你使用的是 Ubuntu/Debian 系统，注意站点默认不在sites-enabled中生效，必须手动建立软链。
此外，别忘了防火墙放行 80 和 443 端口：
sudo ufw allow 'Nginx Full'常见问题与解决方案
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 页面可以访问，但登录失败或接口报错 404 | 路由未正确代理/api | 检查location /api是否指向5001端口 |
| 上传文件时报错 413 Request Entity Too Large | 请求体过大被拒绝 | 设置client_max_body_size 50M |
| 实时输出无反应，控制台报 WebSocket 错误 | 缺少 Upgrade 头 | 添加Upgrade和Connection头 |
| HTTPS 访问显示不安全 | 证书过期或域名不匹配 | 使用 Certbot 更新证书并验证域名绑定 |
| 日志中全是 127.0.0.1 | 未传递真实客户端 IP | 添加X-Real-IP和X-Forwarded-For头 |
生产环境进阶建议
1. 域名规划
建议为 Dify 分配独立子域名，例如：
-dify.company.com
-ai-tools.internal.company.com
避免与其他应用共用同一路径前缀（如/dify），以免造成路由冲突。
2. 日志监控
开启 Nginx 访问日志和错误日志：
access_log /var/log/nginx/dify.access.log; error_log /var/log/nginx/dify.error.log warn;结合 ELK 或 Grafana Loki 做集中分析，便于排查异常请求。
3. 高可用部署
单节点 Nginx 存在单点故障风险。生产环境中可考虑：
- 使用 Keepalived + VIP 实现主备切换；
- 前置云厂商负载均衡器（如 AWS ALB、阿里云 SLB），后端挂载多台 Nginx 实例；
- 使用 Kubernetes Ingress Controller 替代裸金属 Nginx。
4. CORS 协调
虽然 Nginx 处理了跨域请求转发，但如果前端部署在不同域名下（如 CDN 托管），仍需在 Dify 后端配置允许的 Origin。
修改.env文件中的CORS_ALLOW_ORIGINS：
CORS_ALLOW_ORIGINS=https://my-frontend.com,https://app.company.com否则浏览器会因预检请求失败而拦截 AJAX 调用。
总结：这才是真正的生产就绪
Dify 提供了一个强大的 AI 应用开发底座，但它本身只是一个“运行时”。真正决定其能否稳定服务于企业用户的，是外围的基础设施设计。
通过 Nginx 反向代理，我们实现了：
- 🔐 安全隔离：隐藏真实服务端口，仅暴露 443；
- 🌐 统一接入：支持 HTTPS、自定义域名、路径路由；
- ⚡ 性能优化：Gzip 压缩、连接复用、静态资源缓存；
- 📦 功能完整：支持大文件上传、WebSocket 实时通信；
- 🛠 易于维护：日志清晰、配置模块化、可扩展性强。
这套组合拳不仅适用于 Dify，也适用于任何基于微服务架构的 Web 应用部署。
掌握这一套方法，意味着你已经迈出了 AI 工程化落地的关键一步——从“跑得起来”到“稳得住、守得牢、扩得开”。
未来无论是对接内部 SSO、集成审计系统，还是部署多租户架构，这个基础都将为你提供坚实的支撑。
