Dify Agent上云部署：中间件编排、域名解析与HTTPS全流程

容器显示Running，浏览器却打不开；管理页能登录，Agent一调用模型就超时。这两类问题发生在不同层，靠“把所有端口打开”通常解决不了。本文以社区教程为参考，梳理Dify类Agent应用从GitHub源码到Linux服务器上线的部署链路，覆盖中间件编排、端口分层、云安全组、Nginx反向代理、HTTPS证书签发与续期，并给出分层排错清单与生产加固建议。

来源说明：本文主要依据社区教程整理，属于工程实践参考，不是官方部署规范。文中涉及Dify 1.17.1的组件构成、环境键、Agent backend、local sandbox等版本相关细节，请以官方仓库和官方文档为准。密钥清单、容器分工、端口链路等均为社区教程给出的部署路径，建议独立核验后再用于生产环境。

一、部署边界与组件分工

从社区教程的部署路径看，Dify的部署入口通常不在仓库根目录，而在docker/目录中，包含Compose文件、环境模板、Nginx模板和持久化目录。只复制单个YAML可能不够，因为其中挂载了本地配置文件，缺少nginx/、ssrf_proxy/等目录可能导致挂载失败。较稳妥的做法是完整克隆仓库，再进入docker/。

按该教程的描述，中间件分工大致如下：

组件 在部署中的角色 是否建议开放公网端口
Web与API 管理界面、应用配置和请求入口 只经统一网关访问
Worker与定时调度 后台处理、定时任务 不需要
PostgreSQL 应用、用户、知识库等结构化数据 不需要
Redis 缓存、消息与后台任务通信 不需要
Weaviate 知识检索向量存储（该教程选定） 不需要
文件存储 用户上传内容及生成产物 通过授权文件接口访问
插件服务与沙箱 模型/工具插件及受限代码环境 普通使用不开放调试口
Nginx 统一转发界面和API请求 公开入口使用80/443

该教程提到，其部署路径中向量库选用Weaviate，不需要再安装Milvus、Qdrant、Elasticsearch全家桶，默认文件存储也不依赖MinIO。如果选择其他后端，需要根据对应环境模板补充服务和配置。

关于1.17.1版本，该教程提到存在独立Agent backend、local sandbox和相关代理网络，并提醒不要依据早期版本的容器数量判断新版是否多启动了无用服务。这类版本相关细节建议以官方仓库和官方文档为准。

API启动不代表知识库能处理。按该教程说明，源码启动入口依据运行模式分别启动API、Celery Worker或调度进程，它们可以使用同一应用镜像，却承担不同职责。文档上传后的后台处理不应仅凭API首页能打开就判定正常。验收时可分别检查：入口是否通、数据库是否连接、Worker是否执行、插件是否初始化、模型是否可达。Running只是进程状态，不等于业务成功。

二、服务器准备与出站网络

该教程建议先用已有测试服务器验证，不要仅凭教程购买配置。其给出的保守起始建议是4 vCPU、8 GiB内存、60 GiB可用SSD，并明确这不是官方最低要求或性能保证。文档规模、插件数量、并发和本地模型都会改变资源需求。

先检查环境：

cat /etc/os-release
uname -m
free -h
df -h
sudo ss -lntp

最后一条比较重要：如果宿主Nginx、宝塔或其他应用已占用80/443，就不宜让Dify容器再占同一端口。该教程采用“宿主Nginx → 回环端口 → Dify内部Nginx”的路径，以避免冲突。

服务器需能访问GitHub、镜像仓库、模型供应商以及所选插件源。GitHub下载成功不代表模型域名也可访问；模型服务器返回401至少说明TLS和HTTP已通，但不说明账号具备调用资格。不建议通过关闭TLS校验处理证书报错，可先查系统时间、CA证书、DNS和企业代理。

安装Docker Engine和Compose v2时，该教程建议按Docker官方Ubuntu安装指引配置官方apt仓库。Ubuntu 24.04使用noble，其他版本不要照抄发行版代号。ARM64机器把Architectures改成arm64，并确认应用镜像支持该架构。该教程一直使用sudo docker，避免为方便把所有用户加入接近root权限的docker组。其端口覆盖使用!override，需要Compose v2.24.4或更新。

三、克隆固定版本并生成密钥

该教程建议克隆固定发布标签，而不是直接部署main分支：

mkdir -p "$HOME/agent-services"
cd "$HOME/agent-services"
git clone --branch 1.17.1 --depth 1 https://github.com/langgenius/dify.git dify-1.17.1
cd dify-1.17.1/docker
cp .env.example .env
chmod 600 .env
git rev-parse HEAD

记录最后输出的提交标识。固定仓库标签不一定固定所有镜像：某些依赖镜像仍可能使用latest。正式交付还应记录实际镜像digest，做安全审查并测试升级。

该教程提醒不要把新版.env.example当成旧版“大杂烩”。当前发布版本的入口模板与可选envs/*.env.example分工：默认启动参数在根模板，高级配置按服务分组。不要从网上复制另一版本的千行.env，它可能漏掉新增的安全键，还可能包含已弃用配置。需要检查的键包括：

DB_TYPE=postgresql
VECTOR_STORE=weaviate
WEAVIATE_AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=false
NGINX_HTTPS_ENABLED=false
SERVER_CONSOLE_API_URL=http://api:5001

最后一个是Web在容器内访问API的地址，不要改成http://localhost:5001。此处NGINX_HTTPS_ENABLED=false只表示内部这一跳走HTTP，公网TLS在宿主Nginx终止。

首次部署应生成独立密钥。该教程给出一个configure_first_install.py思路：在首次启动前运行，只替换模板中已存在的键，遇到版本不匹配就停止，不打印秘密。其处理的键包括SECRET_KEY、DB_PASSWORD、REDIS_PASSWORD、PLUGIN_DAEMON_KEY、PLUGIN_DIFY_INNER_API_KEY、DIFY_AGENT_API_TOKEN、DIFY_AGENT_SERVER_SECRET_KEY、DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN，以及成对配置的SANDBOX_API_KEY与CODE_EXECUTION_API_KEY、WEAVIATE_API_KEY与WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS。hex字符串可避免密码中的@、:、$干扰Redis URI和Compose展开。

已有数据库不能靠改DB_PASSWORD更新密码。数据库镜像的初始化密码通常只在空数据目录首次创建时生效。已有实例需要协调数据库密码变更和应用配置，不能重新跑上述脚本。SECRET_KEY改变也可能影响现有会话和签名。

四、端口分层与访问链路

该教程固定的访问路径为：浏览器https://agent.example.com:443 → 云安全组允许443 → 宿主Nginx :443 → 宿主127.0.0.1:8088 → Dify内部Nginx。公网、宿主和容器三个地址空间需要分开。

覆盖端口时不能“加一条更安全的映射”就算完成，需要用!override确保旧映射被替换。中间件随官方Compose部署，先逐个验收：PostgreSQL能连接、Redis能PING、Weaviate能响应、Worker日志无异常，再继续下一步。

云安全组只放行22、80、443，其余端口不对公网开放。没有域名时，先用SSH隧道访问安装页面，不裸露管理端口。

五、域名、Nginx与HTTPS

配好DNS后，将域名解析到服务器公网IP，并设置Dify外部URL。先配置HTTP入口用于证书校验，拿到证书后替换为完整反向代理配置。宿主Nginx监听443，将请求转发到127.0.0.1:8088，由Dify内部Nginx再分发。

证书签发可使用Let's Encrypt。自动续期需配置定时任务，续期后重载Nginx。注意：NGINX_HTTPS_ENABLED=false只影响容器内部这一跳，公网TLS在宿主Nginx终止，两者不矛盾。

六、配置可执行工具的Agent

模型Key不等于Dify应用API Key，两者用途不同。做一个可验收的任务，不只问“你好”：例如让Agent调用一个工具并返回结构化结果，确认模型可达、工具可执行、日志可追踪。接本机模型或内部工具时，localhost最容易误配——容器内的localhost指向容器自身，不是宿主机。

七、分层排错清单

先在服务器本机查，再从你的电脑查。按层定位：

  1. 容器层：docker compose ps看状态，docker compose logs看日志。
  2. 宿主端口层：ss -lntp确认监听地址和端口。
  3. 安全组层：确认443、80、22放行，其余关闭。
  4. Nginx层：nginx -t校验配置，看access/error日志。
  5. 应用层：检查数据库连接、Worker执行、插件初始化、模型可达。

部署验收通过的标准不是“页面能打开”，而是：入口经HTTPS可达、数据库连接正常、Worker执行任务、插件初始化完成、模型调用返回预期结果。

八、持久化、备份与升级

不要把容器当数据库备份。必须备份的不只PostgreSQL，还包括Redis持久化数据、Weaviate向量数据、文件存储和.env中的密钥配置。升级应先恢复演练，再切换镜像。固定版本标签不等于固定所有依赖镜像，正式交付应记录实际镜像digest。

单机部署适合学习和小规模验证，不承诺高可用或任何并发指标。生产环境加固建议：最小化安全组放行、使用独立密钥、定期备份并验证恢复、记录镜像digest、升级前做恢复演练。

参考来源与说明

  • 社区教程：Agent上云部署实战（上）：从GitHub到Linux，用Dify跑通中间件、域名和HTTPS（CSDN）
  • Dify官方仓库：https://github.com/langgenius/dify
  • Docker官方Ubuntu安装指引：https://docs.docker.com/engine/install/ubuntu/

本文为社区教程整理与工程实践参考，不构成官方部署规范。版本相关细节、密钥清单、容器分工和端口链路请以官方仓库和官方文档为准，并在生产环境独立核验。