简介这份资源是面向国内开发者与运维人员的 dify-main Docker 镜像包针对国内网络环境做了适配优化可绕开直连 Docker Hub 时常见的下载缓慢、连接不稳定等问题适合需要快速搭建与测试 dify 相关技术栈、又希望部署流程合规高效的初中级技术人员。压缩包为 zip 格式共约 2000 个文件整体大小 20.29MB其中以 1411 个 py 源码文件为主体辅以 370 个 json 配置、103 个 css 样式、41 个 md 文档、25 个 js 脚本及 23 个 yaml 编排文件另有少量 sh、html、sql 等基本覆盖项目运行所需的代码、配置与前端资源。目前已有 1480 人学习下载说明该镜像在国内社区具备一定认可度。拿到后可直接加载运行省去逐层拉取依赖的繁琐便于快速验证环境、排查配置问题并投入实际开发。1. 国内环境跑 Dify为什么镜像版本比源码编译更值得选如果你在国内做过 AI 应用编排大概率遇到过这种情况官方文档给的docker compose up -d跑了一半卡在拉镜像或者pip install到某个包直接超时。Dify 本身是个功能相当完整的 LLM 应用开发平台支持工作流编排、RAG 检索、Agent 调用、多模型接入但它的依赖链条很长——前端 Next.js、后端 Flask、异步任务 Celery、向量库、Postgres、Redis、Nginx 一层套一层。源码编译部署对网络环境的要求相当高而国内可用的镜像版本 dify-main 解决的正是这个问题把构建好的镜像和编排文件打包让你跳过编译和拉取海外镜像的环节直接docker compose起服务。适合两类人一是想快速搭一套内部 AI 应用平台的后端或全栈工程师二是需要离线或半离线环境部署、不想在依赖上反复折腾的运维同学。下面按「拿到资源怎么落地 → 配置怎么改 → 坑在哪」的顺序拆开讲。2. 镜像包结构拆解先搞清楚你拿到的是什么2.1 目录层级与关键文件国内镜像版本的 dify-main 通常是一个压缩包解压后目录结构和官方仓库基本一致但多了预构建的镜像归档或已配置好的镜像加速地址。核心目录大致如下路径作用是否必须改docker/docker-compose.yaml服务编排主文件按需改端口和镜像地址docker/.env.example环境变量模板必须复制为.env并修改docker/volumes/数据持久化目录一般不动api/后端源码镜像版可能只留配置不改web/前端源码不改images/或*.tar预导出的镜像归档用docker load导入如果你拿到的是带.tar的镜像包说明作者已经把langgenius/dify-api、langgenius/dify-web等镜像导出好了。这种情况下你不需要联网拉镜像直接导入即可。如果拿到的是纯 compose 文件加镜像地址替换那就要确认.env里的镜像前缀是否指向了国内可访问的 registry。2.2 镜像导入与校验假设你拿到的是镜像归档操作步骤如下# 进入镜像存放目录批量导入所有 tar 包 for img in *.tar; do echo 正在导入: $img docker load -i $img done # 导入完成后确认镜像列表 docker images | grep -E dify|langgenius逻辑说明docker load会把 tar 中的镜像层写入本地 Docker 存储导入后docker images应该能看到dify-api、dify-web、dify-sandbox等条目。参数上注意-i指定输入文件不要写成-f。如果导入报invalid tar header多半是文件下载不完整重新校验压缩包的哈希值。校验环节容易被跳过但这一步能帮你排除掉大部分「起不来」的问题。常见做法是对比docker images输出的 IMAGE ID 和资源包里附带的清单文件确认版本一致。如果清单里写的是某个具体 tag而本地显示none说明导入时标签丢了需要手动docker tag补上。2.3 环境变量文件的最小改动集.env是整套服务的黑匣子改错一个变量可能让后端连不上数据库。最小改动集如下# 复制模板 cp docker/.env.example docker/.env # 必须修改的项用编辑器打开 .env # 1. 数据库密码不要用默认值 POSTGRES_PASSWORDyour_strong_password # 2. 对外访问地址影响前端回调 CONSOLE_API_URLhttp://你的服务器IP:5001 CONSOLE_WEB_URLhttp://你的服务器IP:3000 # 3. 密钥用于加密存储 SECRET_KEY随机生成一串 # 4. 镜像地址如果 compose 里引用了变量 DIFY_IMAGE_PREFIX你的国内镜像地址前缀参数说明SECRET_KEY必须改默认值在公开仓库里不改等于把加密钥匙挂在门上。CONSOLE_API_URL和CONSOLE_WEB_URL如果填 localhost远程访问时前端会请求不到后端表现为页面能打开但登录转圈。POSTGRES_PASSWORD改了之后compose 文件里引用这个变量的地方会自动同步不需要手动改数据库配置。3. 启动与验证从 compose 到可访问的控制台3.1 启动顺序与依赖等待Dify 的服务之间有依赖关系直接docker compose up -d有时会因为数据库没就绪导致后端反复重启。稳妥的做法是分步启动cd docker # 第一步只起数据库和缓存 docker compose up -d postgres redis # 等待约 10 秒确认健康状态 docker compose ps # 第二步起后端 API 和 worker docker compose up -d api worker # 第三步起前端和网关 docker compose up -d web nginx逻辑说明postgres和redis是基础依赖先让它们跑稳。api服务启动时会执行数据库迁移如果 postgres 还没 ready迁移会失败并退出。分步启动的好处是每一步都能看到日志出问题容易定位。worker是 Celery 异步任务进程负责处理文档索引、模型调用等耗时操作不能省。启动后查看日志# 跟踪 api 日志看迁移是否完成 docker compose logs -f api | head -50 # 确认所有服务状态 docker compose ps --format table {{.Name}}\t{{.Status}}如果api日志里出现relation xxx does not exist说明迁移没跑完就退出了重启一次api容器通常能解决。如果反复出现检查POSTGRES_PASSWORD是否和数据库初始化时一致——数据卷已经初始化过的话改密码不会同步到数据库里。3.2 首次登录与模型接入服务全部起来后浏览器访问http://你的IP:3000会进入初始化页面设置管理员账号。登录后在「设置 → 模型供应商」里接入模型。国内环境常用的是 OpenAI 兼容接口填写Base URL和API Key即可。这里有个容易翻车的点如果你的模型服务是本地部署的比如用 vLLM 起的推理服务Base URL要填容器能访问到的地址。Dify 的api容器在 Docker 网络里localhost指向的是容器自身不是宿主机。常见做法是填宿主机的内网 IP或者在 compose 里给api服务加extra_hosts映射。# docker-compose.yaml 中 api 服务的片段 services: api: extra_hosts: - host.docker.internal:host-gateway加上这段后模型地址可以填http://host.docker.internal:8000/v1容器就能访问宿主机的推理服务了。这个配置在 Linux 上需要 Docker 20.10 以上版本支持老版本可能不生效那就老老实实填内网 IP。3.3 验证工作流是否跑通接入模型后建一个最简单的对话应用测试。在「工作室」里创建应用选「聊天助手」编排里加一个 LLM 节点选好模型保存后点预览。如果回复正常说明整条链路通了。如果报错按这个顺序排查模型供应商页面点「测试」按钮确认连通性看api容器日志有没有Connection refused或Timeout确认模型服务的Base URL路径是否要加/v1检查 API Key 是否有余额或权限这一步跑通之后再去做 RAG 索引和 Agent 编排基础环境就算稳了。4. 避坑与排查镜像版部署最常见的五个问题4.1 容器起来了但页面 502现象docker compose ps显示所有容器都是Up但访问 3000 端口返回 502 Bad Gateway。原因Nginx 容器配置里 upstream 指向的服务名和实际 compose 服务名不一致或者web容器还没完全启动 Nginx 就转发了。解决先看nginx日志docker compose logs nginx确认报错是connect() failed还是no live upstreams。如果是前者等 30 秒再刷新如果是后者检查 compose 文件里web服务的容器名和 nginx 配置里的proxy_pass是否匹配。镜像版有时会改服务名需要手动对齐。4.2 数据库迁移卡住或反复重启现象api容器不断重启日志停在Running upgrade或Waiting for database。原因Postgres 数据卷里已有旧版本的数据新镜像的迁移脚本和旧表结构冲突或者.env里数据库密码和已初始化卷的密码不一致。解决如果是测试环境直接删掉数据卷重来docker compose down -v然后重新启动。生产环境不能删卷的话进 Postgres 容器手动检查alembic_version表确认当前版本号再决定是回滚还是手动补迁移。密码不一致的情况要么改.env回原密码要么进数据库改密码。4.3 文件上传后索引一直转圈现象在知识库里上传文档状态一直显示「索引中」不报错也不完成。原因worker容器没起来或者worker连不上 redis。文档索引是异步任务由 worker 消费队列执行。解决docker compose ps确认worker状态如果没起来看日志。常见的是 redis 连接失败检查.env里REDIS_HOST和REDIS_PORT是否指向 compose 里的服务名。另外确认worker和api用的是同一个.env有时只改了 api 的环境变量worker 还在用默认值。4.4 镜像导入后标签丢失现象docker images里能看到镜像但 tag 是nonecompose 启动时报image not found。原因导出镜像时用了docker save没带 tag或者导入时被覆盖。解决手动补 tag。先找到 IMAGE ID然后docker tag IMAGE_ID langgenius/dify-api:latestweb 同理。补完后重新docker compose up -d。预防办法是导入前先看清单文件里记录的完整镜像名导入后逐一核对。4.5 端口冲突导致部分服务起不来现象docker compose up报port is already allocated。原因宿主机上已有服务占用了 3000、5001、5432、6379 等端口。国内环境里 6379 和 5432 被本地 Redis/Postgres 占用的概率很高。解决改 compose 文件里的端口映射比如把5432:5432改成15432:5432只改宿主机侧端口容器内不变。改完记得同步改.env里如果有引用外部端口的配置。改端口是最省事的做法不要去停宿主机上已有的服务。5. 进阶把镜像版改造成可迁移的离线部署包镜像版最大的价值在于可迁移。你在一台机器上跑通之后可以把它打包成离线部署包复制到内网其他机器上。具体做法是先docker save导出所有相关镜像再把docker/目录整个拷出来包括改好的.env和 compose 文件。目标机器上先docker load导入镜像再docker compose up -d。# 在源机器上导出所有 dify 相关镜像 docker save -o dify-images.tar \ langgenius/dify-api:latest \ langgenius/dify-web:latest \ langgenius/dify-sandbox:latest \ postgres:15-alpine \ redis:6-alpine \ nginx:latest # 打包 compose 和配置 tar czf dify-deploy.tar.gz docker/ # 目标机器上导入 docker load -i dify-images.tar tar xzf dify-deploy.tar.gz cd docker docker compose up -d参数说明docker save的-o指定输出文件后面跟多个镜像名。注意镜像名要和docker images里显示的完全一致包括 tag。如果镜像有none标签先补 tag 再导出。tar czf打包docker/目录时.env文件会被一起打进去如果里面有敏感信息迁移前先清理或替换。验证迁移是否成功重点看三处docker compose ps全部Up、控制台能登录、模型测试能通。三处都过这套离线包就算可用了。我自己的习惯是每次迁移完先跑一个最小对话应用确认 LLM 节点能返回内容再去做其他配置。这个习惯帮我省过好几次「以为好了结果 RAG 索引全挂」的后悔药。希望帮到你。本文还有配套的精品资源点击获取