简介面向国内开发者与企业的 Dify 镜像版本基于 dify-main 工程打包有效规避 Docker Hub 访问慢、超时等网络问题同时适配国内合规要求适合需要在内网或国内容器环境快速部署 LLM 应用平台的场景。资源共 2000 个文件压缩包约 20.29MB主体为 1411 个 Python 源码文件配合 370 个 JSON 配置、103 个 CSS 样式、41 个 Markdown 文档及少量 YAML、Shell、JS、HTML 等覆盖后端逻辑、接口配置、前端界面与部署脚本目录结构完整。已有 1470 人学习下载。解压后可通过 Docker 命令直接加载镜像运行并建议搭配国内镜像源可显著提升拉取速度与成功率随包附带的项目文件和默认配置便于做二次开发、私有化部署或作为学习 Dify 架构的参考。 最近在折腾 Dify 部署的时候好几个朋友都来问我“国内可以的镜像版本 dify-main 到底怎么搞”。说实话“dify-main”这个名字本身就带着不少信息量——它是 Dify 开源项目的 main 分支对应构建版也就是持续更新的开发版镜像。对于国内团队来说难点根本不在 Dify 本身怎么用而是怎么把镜拉下来、怎么让整个 Compose 服务稳稳跑起来。今天我就把从零开始在国内环境部署 dify-main 的完整过程、遇到的各种坑和解决办法一次性写清楚希望能帮你少走弯路。这篇文章适合谁适合想在自建服务器上部署 Dify 的开发者、运维同学或者想体验最新功能但又不知道怎么选版本的人。我会从版本理解、环境准备、镜像加速配置、完整部署流程、常见问题排查几个方面展开保证每一步都有可操作性的说明。1. 先搞清楚几件事dify-main 是什么、部署到哪种环境1.1 dify-main 对应的是什么版本Dify 是当前非常火的开源 LLM 应用开发平台帮你把模型 API、RAG 流程、Agent、工作流这些复杂组件串起来以可视化的方式构建 AI 应用。它的官方代码仓库托管在 GitHub 的 langgenius/dify默认分支就是 main。“dify-main”在镜像语境下一般指的就是这个 main 分支构建出来的 Docker 镜像。这里要特别注意一个区别Dify 官方发布版本时会打上类似 v0.15.x、v1.0.x 这样的 release 标签而dify-api:main、dify-web:main这类带 main 标签的镜像则是跟随主线代码持续构建的“最新开发版”。它能让你体验到还没正式发版的新功能但也意味着可能有未充分验证的改动。如果你的目标是生产环境长期稳定跑业务我更建议选 release 版本但如果你是想尝鲜、测试新特性或者想跟进社区最新进展dify-main 就非常适合你。1.2 部署环境选型与硬件要求Dify 是一个典型的多服务容器架构包含 API 服务、Web 前端、Worker 异步任务、Sandbox 沙箱执行、SSRF Proxy以及 PostgreSQL、Redis 和向量数据库默认为 Weaviate。所以部署时基本都是直接用 Docker Compose 跑整套Kubernetes 部署虽然官方也支持但对于多数团队和个人开发者来说Docker Compose 是最快、最容易维护的方式。硬件上我实际测试下来的底线是2 核 CPU、4G 内存、20G 以上磁盘。运行起来后容器数量大约 9 个占用的资源不算小如果机器负载较高建议直接上 4 核 8G。系统方面 CentOS 7.9、Ubuntu 22.04 这类主流 Linux 发行版都没问题Docker 和 Docker Compose 插件先装好就行。2. 部署前必做的国内环境优化2.1 Docker 镜像加速配置这一步真的救了我国内服务器用 Docker 拉取官方 Hub 镜像最常见的问题就是慢到怀疑人生或者直接timeout超时失败。dify-main 涉及的镜像少说有十个不解决拉取问题根本起不来。解决办法就是配置 Docker 镜像加速器。编辑/etc/docker/daemon.json如果没有就新建写入如下内容{ registry-mirrors: [ https://docker.m.daocloud.io, https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com ] }这里我列的都是国内比较常见的 Docker 加速地址你可以多配置几个Docker 在拉取时会按顺序尝试。配置完成后重启 Dockersudo systemctl daemon-reload sudo systemctl restart docker重启后可以用docker info查看 Registry Mirrors 是否生效。如果输出里能看到你填写的加速地址说明生效了。这一步是后续所有操作的基础我建议你在部署 Dify 之前就先把它配好否则后面拉镜像大概率会卡住。2.2 部署代码的正确获取方式Dify 的部署文件都放在仓库的docker/目录下里面有docker-compose.yaml和.env.example。由于官方仓库在 GitHub 上国内直接git clone有时会非常慢甚至失败。这里我比较推荐通过国内代码托管平台来获取。你可以在 Gitee 上直接搜索 “dify”通常能找到官方同步仓库或社区维护的同步镜像仓库。使用方式很简单git clone -b main https://gitee.com/你的用户名/dify.git如果找不到合适的同步仓库也可以先下载 GitHub 仓库的 zip 包再传到服务器上解压。总之只要拿到docker/目录下的文件就行不需要从零编写部署配置。2.3 顺手把系统软件源和 pip 源也换了部署过程中还会涉及一些辅助操作比如在宿主机安装 Python 包、给容器构建自定义镜像等所以我建议顺手把系统软件源和 pip 源也换成国内镜像。Ubuntu 系统可以用清华源CentOS 7 可以用阿里云的 centos7 镜像源Python 包则用阿里云 pip 源。这些操作不是 Dify 部署的必要步骤但能避免很多“软件装一半超时”的尴尬。尤其是你在调试 dify-main 时如果需要自定义镜像构建过程会大量拉取基础镜像和运行依赖国内源能明显提升成功率。3. 完整实操国内环境部署 dify-main3.1 获取代码并准备配置文件假设你已经拿到了 Dify 的部署文件进入docker/目录cd dify/docker cp .env.example .env.env文件里包含所有关键配置比如对外访问端口、数据库密码、Secret Key、向量库类型等。第一次部署时可以直接用默认值Dify 会自动生成必要的随机密钥。不过有两点建议你提前改掉一是EXPOSE_NGINX_PORT默认是 80如果服务器 80 端口已被其他服务占用就改成你想要的端口比如 8080二是POSTGRES_PASSWORD虽然默认能用但生产环境还是要改成强密码。3.2 先手动拉取核心镜像很多新手直接docker compose up -d然后发现一堆镜像在拉取时卡住半天又不知道哪个环节出了问题。我的习惯是先手动拉取核心镜像确认网络没问题再启动服务。进入 docker 目录后先用docker compose config查看实际要拉取的镜像列表然后挨个手动拉一遍核心的几个镜像包括docker pull langgenius/dify-api:main docker pull langgenius/dify-web:main docker pull langgenius/dify-worker:main docker pull langgenius/dify-sandbox:main docker pull langgenius/ssrf_proxy:latest如果你配置了加速器这些拉取命令会自动走加速通道。手动拉取的好处是你能第一时间看到镜像是否拉取成功避免在docker compose up时出现一堆半途而废的下载。3.3 启动整套服务核心镜像拉下来后回到dify/docker目录直接启动docker compose up -d这个命令会先检查本地镜像是否存在不存在则自动拉取然后按依赖顺序启动容器。启动过程大概需要一两分钟主要耗时在初始化数据库和 Migration 上。启动完成后用docker compose ps查看状态正常情况下所有容器都应该处于Up状态。如果看到某些容器反复重启不要慌先看日志docker compose logs -f api docker compose logs -f web docker compose logs -f db大概率问题出在数据库初始化、端口冲突或者资源不足上具体细节我会在下一部分展开。3.4 浏览器访问与初始化管理员服务起来后在浏览器里访问http://服务器IP:端口端口就是你配置的EXPOSE_NGINX_PORT。第一次访问会进入管理员账号初始化页面设置好管理员邮箱和密码后就可以登录 Dify 主界面了。到这里dify-main 就算部署完成可以开始创建应用、接入模型 API 了。4. 常见问题与避坑记录4.1 镜像拉取失败timeout / no such host这是国内部署 Dify 时遇到最多的问题往往出现在没有配置加速器或加速器失效的情况下。排查步骤很简单先确认daemon.json配置无误且 Docker 已重启再用docker info验证 Registry Mirrors 生效如果加速器地址本身访问不了就换一个多配置几个地址作为备选是更稳妥的做法。还有一个小技巧Docker 拉镜像时是分层的如果中途失败重新执行docker pull会基于已有层继续拉取不会从头再传一遍。所以遇到偶尔抖动多试几次往往就成功了。如果真的所有加速器都不行那可能就是你服务器所在网络环境对 Docker Hub 管控比较严格可以考虑换一台镜像源更畅通的机器或者使用一些国内外都可用的容器镜像仓库服务。4.2 启动后服务一直重启、容器反复退出docker compose ps里看到Restarting状态大概率是资源不够或者配置冲突。先说资源Dify 全套服务至少需要 4G 内存如果你的机器只有 2G不爆内存才怪。我的建议是至少保证 4G 内存并提前设置好 Swap交换分区避免内存压力导致容器被 OOM Kill。查看是否因为内存被杀可以这样docker inspect 容器名 | grep -i oom dmesg | tail -30如果日志中出现Out of memory或不带退出码的 kill 记录基本就是内存问题。另外80 端口被占用也是常见原因你可以先停止占用端口的服务或者直接改EXPOSE_NGINX_PORT换一个端口之后重新docker compose up -d。4.3 数据库初始化失败、Migration 卡住数据库容器状态正常但 API 服务一直报连不上数据库或者日志里有FATAL: password authentication failed大概率是.env里的数据库密码和 POSTGRES 容器初始化密码不一致。Dify 的 Compose 文件中数据库容器会读取.env里的POSTGRES_PASSWORD进行初始化API 服务也会用这个密码连接数据库。如果你修改了密码一定要同时修改两处实际上 Compose 文件会自动引用.env但要注意不要改错变量名。Migration 卡住则多见于磁盘 IO 较低或网络拉取迁移依赖较慢的情况。这种时候除了等待还可以观察数据库容器日志确认是否在正常执行 SQL。4.4 关于 dify-main 版本本身的坑main 分支作为开发版最大的问题不是功能缺失而是“前一天还能跑、第二天更新完就起不来”。我在测试时遇到过前端构建产物与 API 版本不兼容的情况后来发现是镜像构建时间不一致导致的。解决办法很简单每次升级都保持 api、web、worker 三个镜像使用同一个 main 标签并且尽量在同一时间点执行docker compose pull和docker compose up -d避免混用不同时间构建的版本。另外main 分支升级频率很高如果生产环境依赖 Dify 的稳定性我强烈建议不要直接上 main。社区里比较稳妥的做法是等待官方 release 发布后再升级release 版本经过更多验证坑会少很多。5. 写在最后我的几点实操体会整套 dify-main 在国内环境部署下来我个人最大的感受是网络问题才是真正的拦路虎Dify 本身的部署设计其实已经相当成熟了。只要把 Docker 加速器配好、部署代码通过国内托管平台获取再按照“先手动拉镜像、再启动服务、最后查日志”的流程走基本不会遇到什么大问题。最后再分享一个小技巧如果你打算长期维护 Dify 实例一定要养成定期备份.env文件和 Docker Volume 数据的习惯。.env里包含了数据库密码、密钥等关键信息一旦数据卷损坏或误删至少还能靠备份恢复配置。升级前也可以先停止服务、备份数据再执行docker compose pull和docker compose up -d这样即使新版本有坑也有后悔药可吃。就聊到这儿吧希望这篇笔记能帮你在国内网络环境下顺利把 dify-main 跑起来。如果你在部署中遇到其他奇怪的问题欢迎留言交流我尽量把自己踩过的坑都翻出来给你参考。本文还有配套的精品资源点击获取