Dify 的可视化编排界面把模型调用、条件分支、知识检索和工具节点放在同一张画布上。对自托管部署而言难点不在启动某个 Web 容器而在于同时管理 API、异步任务、数据库、缓存、向量存储、插件服务、代码沙箱和反向代理。工作流画布用于连接模型、检索、条件判断和输出节点。本文采用仓库维护的docker/docker-compose.yaml部署路径不在宿主机直接构建前端或安装 Python 依赖。这样可以让应用及其基础组件使用仓库定义的镜像和容器网络减少宿主机运行时版本差异带来的问题。一、部署结构与组件关系Dify 不是单容器应用。不同版本的 Compose 文件可能调整服务名称或增加可选组件因此应以当前检出版本中的docker-compose.yaml为准。典型服务职责如下组件主要职责持久化要求web管理界面与应用页面通常不保存核心业务数据apiHTTP API、鉴权、应用和知识库管理文件目录需要持久化worker文档处理、索引、异步任务依赖数据库、缓存和文件存储worker_beat调度周期性任务依赖数据库和缓存db保存账号、应用、工作流和运行记录必须备份redis缓存与任务队列建议持久化weaviate等保存知识库向量索引必须与数据库一起考虑备份sandbox隔离执行工作流中的代码不应直接暴露到公网plugin_daemon管理和运行插件插件数据需要持久化ssrf_proxy约束容器对外访问路径仅供内部服务调用nginx对外提供统一 HTTP/HTTPS 入口证书启用时需要持久化Compose 内部服务通过容器名称通信例如 API 连接db和redis不需要把 PostgreSQL、Redis、向量数据库或沙箱端口映射到公网。对话流在多轮会话基础上组织模型、知识检索和分支逻辑。二、准备 Linux 服务器仓库给出的最低要求是CPU 不少于 2 核内存不少于 4 GiB已安装 Git已安装 Docker EngineDocker Compose 不低于 v2.24.0服务器能够拉取部署所需镜像4 GiB 是启动要求不代表适合所有知识库规模。文档解析、向量化和多个工作流并发会继续占用内存与磁盘。生产环境还要预留数据库增长、镜像更新和备份空间。检查系统资源以及 Docker 版本uname-anprocfree-hdf-hdockerversiondockercompose version如果docker compose version低于 v2.24.0应先按照 Docker 官方文档更新 Compose 插件。不要使用旧的独立docker-compose命令替代仓库要求的 Compose v2。对外访问通常只需要 TCP 80启用 HTTPS 后再开放 TCP 443。SSH 端口应限制为管理来源地址。以下以 UFW 为例ADMIN_CIDR是需要替换的管理网络变量sudoufw allow from ADMIN_CIDR to any port22proto tcpsudoufw allow80/tcp# 只有完成 HTTPS 配置后才需要开放sudoufw allow443/tcpsudoufw status数据库、缓存、沙箱和向量数据库端口不应创建公网放行规则。三、获取固定版本的仓库直接长期跟随main分支会增加不可预测的升级变化。部署前可在项目 Releases 页面选择一个发布标签并将其写入DIFY_REF。下面的release-tag是变量不是固定版本号exportDIFY_REFrelease-taggitclone--branch$DIFY_REF--depth1\https://github.com/langgenius/dify.gitcddifygitlog-1--onelinegitstatus--short--branch--branch用来固定发布标签--depth 1可以减少首次下载量。若后续需要在同一目录切换版本再执行完整的标签获取操作。提交摘要可以定位当前代码快照但提交哈希不能替代发布标签。仓库状态应保持干净。部署相关文件集中在docker/目录其中需要重点关注dify/ ├── api/ # 后端 API 源码 ├── web/ # 前端源码 ├── docker/ │ ├── docker-compose.yaml # 容器编排入口 │ ├── .env.example # 基础环境变量模板 │ ├── envs/ # 按主题拆分的高级配置 │ └── volumes/ # 默认本地持久化目录 └── README.md不同发布版本的目录可能变化实际文件列表可用下面的命令核对gitls-filesdocker|sort四、创建并检查环境配置进入 Compose 目录从当前版本自带的模板创建配置文件cddockercp.env.example .envchmod600.env不要从旧教程复制整份.env。环境变量会随版本增加或改名当前标签中的.env.example才与当前 Compose 文件匹配。至少检查以下配置项# 应替换为随机值 SECRET_KEYYOUR_RANDOM_SECRET # 初始化管理员时使用完成初始化后仍应妥善保存配置 INIT_PASSWORDYOUR_INITIAL_PASSWORD # 数据库与缓存凭据 DB_PASSWORDYOUR_DATABASE_PASSWORD REDIS_PASSWORDYOUR_REDIS_PASSWORD # 内部服务鉴权 SANDBOX_API_KEYYOUR_SANDBOX_KEY PLUGIN_DIFY_INNER_API_KEYYOUR_PLUGIN_KEY # 默认反向代理端口 EXPOSE_NGINX_PORT80 EXPOSE_NGINX_SSL_PORT443 # 默认向量存储类型以当前模板支持的值为准 VECTOR_STOREweaviate可以生成多组互不相同的随机值不要把命令输出直接留在终端历史之外的公开位置openssl rand-base6442openssl rand-hex32几个 URL 类变量需要按访问方式处理CONSOLE_API_URL管理界面调用 API 的外部地址。CONSOLE_WEB_URL管理界面的外部地址。SERVICE_API_URL应用服务 API 的外部地址。APP_API_URL已发布应用调用 API 的外部地址。APP_WEB_URL已发布 Web 应用的外部地址。FILES_URL外部服务访问上传文件时使用的地址。INTERNAL_FILES_URL容器内部访问文件服务的地址。单域名、同源部署通常可以沿用模板默认值。只有在前端、API、文件服务使用不同域名或外部反向代理时才需要分别填写完整 URL。协议或域名写错时常见表现是页面可以打开但浏览器请求被跨域策略拦截或者模型服务无法获取上传文件。修改完成后先让 Compose 解析配置dockercompose config--quietdockercompose config--services第一条命令用于发现变量替换或 YAML 结构错误第二条命令显示当前版本实际会启动的服务。不要把docker compose config的完整输出直接发布因为解析结果可能包含密码和密钥。五、拉取镜像并启动服务在dify/docker目录执行dockercompose pulldockercompose up-dpull单独执行可以把镜像下载问题与容器启动问题分开。up -d会创建内部网络、启动依赖服务并在后台运行应用容器。随后查看状态dockercomposepsdockercompose logs--tail100apidockercompose logs--tail100workerdockercompose logs--tail100nginx验收时不要只看docker compose up -d的退出码。需要关注以下现象docker compose ps中核心服务处于Up或running状态。数据库、缓存和向量存储没有持续重启。API 日志中没有数据库认证、迁移或存储目录权限错误。Worker 能连接任务队列没有反复出现连接拒绝。Nginx 没有持续报告上游服务不可用。若某个容器处于Restarting应先查看该容器日志而不是反复执行up -ddockercompose logs--tail200service-namedockerinspectcontainer-name--format{{.State.Status}} {{.State.ExitCode}} {{.State.Error}}其中service-name和container-name都是需要根据docker compose ps替换的变量。六、初始化并验证 Dify在服务器本机检查 HTTP 入口curl-Ihttp://127.0.0.1/installcurl-Ihttp://127.0.0.1/初始化页面地址为http://服务器地址/install服务器地址是变量。首次访问/install时应出现管理员初始化界面完成初始化后根路径应能进入登录页面。HTTP 状态可能因当前版本的重定向策略有所不同但不应持续返回502或连接失败。对话应用页面用于检查消息输入、模型响应和会话记录是否连通。完成初始化后可按以下路径做应用级验收使用管理员账号进入控制台。在模型设置中配置一个可访问的模型接口。创建最小对话应用只保留开始节点、模型节点和输出节点。在调试界面发送一条测试消息。查看运行日志确认调用进入预期模型。发布测试应用再验证外部应用页面和 API 入口。应用调试页可以核对输入、模型输出和运行状态。如果页面正常但模型调用失败说明 Web、API 和数据库链路大体可用后续应检查模型凭据、接口地址、容器出站网络及 DNS而不是重新安装整个服务。七、避免在宿主机直接构建前端Dify Web 工程对 Node.js 运行时有明确约束。终端记录显示使用 Node.jsv24.18.0执行安装时项目要求的运行时为^22.22.1因此 npm 返回EBADDEVENGINES。宿主机 Node.js 不满足项目约束时npm 会在依赖安装阶段终止。这也是自托管部署优先使用仓库 Compose 镜像的原因普通部署不需要在宿主机运行npm install或npm run build。只有进行源码开发时才需要按照当前web/package.json、锁文件和开发文档准备对应 Node.js 版本及包管理器。八、反向代理与 HTTPS默认 Compose 使用 Nginx 作为统一入口。部署时应保持以下边界只公开 Web 入口端口。db、redis、sandbox、ssrf_proxy和向量存储仅加入 Compose 内部网络。HTTPS 终止位置只能有明确的一层避免代理之间循环跳转。外部代理使用 HTTPS 时要正确传递Host、X-Forwarded-Proto和客户端地址。修改域名或协议后同步检查.env中控制台、应用 API 和文件 URL。出现登录后跳回登录页、浏览器混合内容警告或上传文件无法访问时应重点核对外部协议、Cookie 安全属性和 URL 配置。HTTPS 配置完成前不要提前把所有外部 URL 写成无法访问的https://地址。九、备份持久化数据升级前至少备份docker/.envPostgreSQL 数据docker/volumes/下的应用文件向量存储数据插件数据自定义证书和反向代理配置先创建数据库逻辑备份。命令从数据库容器自身读取用户名和数据库名可兼容已经修改过的默认值cd/path/to/dify/dockerBACKUP_DIR/path/to/backups/dify-$(date%Y%m%d-%H%M%S)mkdir-p$BACKUP_DIRcp.env$BACKUP_DIR/envdockercomposeexec-Tdbsh-c\pg_dump -U $POSTGRES_USER $POSTGRES_DB\$BACKUP_DIR/postgres.sql为了获得一致的文件级副本可在安排维护窗口后停止服务再归档持久化目录dockercompose stoptar-C/path/to/dify/docker\-czf$BACKUP_DIR/volumes.tar.gz\volumesdockercompose start sha256sum$BACKUP_DIR/postgres.sql$BACKUP_DIR/volumes.tar.gz只备份 PostgreSQL 并不完整因为上传文件、插件和向量索引可能位于其他卷中。恢复演练还应验证备份文件能够解压、SQL 文件非空并记录对应的 Dify 发布标签。十、升级到新的发布版本不要在没有备份的情况下直接切换代码和镜像。升级流程可以按以下顺序执行cd/path/to/difygitfetch--tagsexportDIFY_REFnew-release-taggitcheckout$DIFY_REFcddockercp.env.env.before-${DIFY_REF}diff-u.env.example .env||truedockercompose config--quietdockercompose pulldockercompose up-ddiff的目的不是让.env与模板完全一致而是发现新版本新增、删除或改名的变量。升级后重新检查dockercomposepsdockercompose logs--tail200apidockercompose logs--tail200workercurl-Ihttp://127.0.0.1/installcurl-Ihttp://127.0.0.1/数据库迁移通常由应用启动流程处理迁移期间不要同时运行新旧两个版本的 API 或 Worker。确认新版本可用后再清理无引用镜像且不要执行会删除卷的docker compose down -v。十一、常见故障排查1. 浏览器访问返回 502通常是 Nginx 已启动但 API 或 Web 上游尚未就绪。dockercomposepsdockercompose logs--tail200nginxdockercompose logs--tail200apidockercompose logs--tail200web检查上游容器是否持续重启以及数据库迁移是否仍在进行。2. API 提示数据库认证失败检查.env中数据库密码是否修改完整尤其要避免只修改应用侧连接密码却没有同步数据库容器初始化变量。如果数据库目录已经使用旧密码初始化单纯修改.env不会自动修改数据库内部账号密码。应恢复原凭据或在明确了解数据库操作的前提下修改账号密码。3. Worker 无法连接 Redis确认redis服务状态、密码配置和内部主机名。容器内连接地址应使用 Compose 服务名不要写成127.0.0.1因为容器里的回环地址只指向容器自身。dockercompose logs--tail200redisdockercompose logs--tail200worker4. 知识库文档一直停留在排队状态重点检查Worker 是否运行。Redis 队列是否可连接。文档解析是否触发内存不足。向量存储是否正常。Embedding 模型接口是否可访问。上传目录是否具有写权限。可同时观察资源占用dockerstatsdf-hdockercompose logs--tail200worker5. 上传文件后模型无法读取检查FILES_URL是否能被模型服务访问。浏览器能打开文件不等于外部模型接口能够访问该地址内网域名、回环地址或错误的 HTTPS 配置都可能导致读取失败。6. 容器反复因内存不足退出使用下面的命令确认是否发生 OOMdockerinspectcontainer-name\--formatOOMKilled{{.State.OOMKilled}} ExitCode{{.State.ExitCode}}dmesg-T|grep-i-Eout of memory|killed process如果文档索引阶段触发 OOM应降低并发、减少单批文档规模或增加可用内存而不是只设置无限重启。7. 修改.env后配置没有生效仅执行docker compose restart不一定会重新创建容器并加载新环境变量。应执行dockercompose config--quietdockercompose up-dup -d会根据配置差异重建需要更新的容器。十二、日常运维检查日常检查可以保留为一组固定命令cd/path/to/dify/dockerdockercomposepsdockercompose logs--since30m api worker nginxdockerstats --no-streamdf-hdu-shvolumes需要持续关注的不是单一 CPU 数值而是以下趋势API 或 Worker 是否频繁重启。数据库和向量索引目录是否持续增长。文档处理期间内存是否逼近上限。磁盘剩余空间能否容纳下一次镜像拉取和备份。日志中是否重复出现认证失败、超时、队列阻塞或上游不可达。备份文件是否具有校验值并能在隔离环境完成恢复。十三、部署验收与结果判定完成安装或升级后应同时检查容器、HTTP 入口和应用调用链不能只以登录页面能够打开作为部署完成的依据。可使用下面的命令收集一次验收状态cd/path/to/dify/dockerdockercompose config--quietdockercomposepsdockercompose logs--since10m api worker nginxcurl-Ihttp://127.0.0.1/installcurl-Ihttp://127.0.0.1/部署结果可按以下条件判定Compose 配置能够通过解析没有缺失变量或 YAML 结构错误。api、web、worker、db、redis、nginx以及当前版本启用的向量存储和插件服务没有持续重启。本机 HTTP 请求能够得到响应不持续出现连接失败或502。管理员可以登录控制台并保存模型配置。最小对话应用能够完成一次调试调用运行日志中可以找到对应记录。发布后的应用页面或 API 入口可以访问。上传文件时API、Worker、文件存储和模型访问链路没有出现权限或地址错误。数据库与持久化目录已经纳入备份备份文件具有校验值并记录了对应发布标签。只有容器启动但模型调用失败时应将结果记录为基础服务可访问、应用调用链未通过知识库文档持续排队时应将结果记录为异步处理或向量化链路未通过。这样的判定可以把部署问题限制到具体组件避免因局部配置错误重复安装整个服务栈。十四、项目与官方参考Dify 源码仓库https://github.com/langgenius/dify自托管安装文档https://docs.dify.ai/getting-started/install-self-hosted环境变量说明https://docs.dify.ai/getting-started/install-self-hosted/environments自托管常见问题https://docs.dify.ai/getting-started/install-self-hosted/faqs源码部署文档https://docs.dify.ai/getting-started/install-self-hosted/local-source-codeDocker Engine 安装文档https://docs.docker.com/engine/install/Docker Compose 文档https://docs.docker.com/compose/Dify 发布记录https://github.com/langgenius/dify/releases仓库的许可证文件以 Apache 2.0 为基础并包含附加条件。部署、再分发或修改项目前应以当前版本仓库中的LICENSE原文为准。