国内环境快速部署Dify：镜像拉取与docker-compose改造指南-北京尧图网络

简介这份资源是面向国内开发者的 dify-main Docker 镜像包主要解决在国内网络环境下拉取官方镜像速度慢、不稳定甚至无法访问的问题。适合需要快速搭建 dify 相关技术栈、进行本地部署与测试的开发者尤其对希望合规、高效使用容器化方案的企业团队有实际帮助。压缩包共包含 2000 个文件以 1411 个 py 源码文件、370 个 json 配置、103 个 css 样式、41 个 md 文档为主另有 js、yaml、sh、html 等辅助文件整体约 20.29MB目录结构完整便于按模块查阅与二次开发。目前已有 1481 人学习下载说明该镜像方案在社区中具备一定认可度。拿到资源后读者可直接加载镜像并配合国内 Docker 镜像源完成部署省去繁琐的网络配置与排错环节快速进入开发调试阶段同时也能借助源码与配置文件理解项目结构为后续定制与维护提供参考。1. 国内能拉到的 dify-main 镜像从「拉不动」到「十分钟跑起来」如果你最近在折腾 Dify大概率经历过这个场景docker compose up -d敲下去终端卡在Pulling api ...一动不动等十分钟弹出一个context deadline exceeded或者TLS handshake timeout。这不是你网络的问题是默认的 compose 文件里引用的镜像地址在国内直连环境下基本拉不动。dify-main这个分支名本身就说明了一件事——你拿到的是主仓库的 main 分支代码而官方 compose 里写的镜像 tag 往往指向 Docker Hub 上的langgenius/dify-api、langgenius/dify-web这类仓库国内拉取体验非常不稳定。这篇要解决的问题很具体在国内网络环境下怎么把dify-main这套代码跑起来。核心思路不是去改代码而是把镜像来源换掉——用国内可访问的镜像加速地址或者直接用国内镜像仓库里已经同步好的 dify 镜像版本。适合两类人一是想本地部署 Dify 做 LLM 应用编排的开发者二是需要在公司内网环境搭一套可用的 Dify 做 PoC 的工程师。接下来从镜像选型、compose 改造、参数配置到排错一步步拆开讲。2. 镜像版本怎么选dify-main 的镜像构成与国内可拉取方案2.1 dify-main 到底包含哪几个镜像先把dify-main的镜像构成搞清楚不然换源的时候容易漏。Dify 的 docker 部署本质上是多容器编排核心镜像有这么几个服务默认镜像作用apilanggenius/dify-api后端 API Workerweblanggenius/dify-web前端 Next.jsdbpostgres:15-alpine元数据库redisredis:6-alpine缓存队列nginxnginx:latest反向代理sandboxlanggenius/dify-sandbox代码执行沙箱ssrf_proxyubuntu/squidSSRF 防护代理weaviatesemitechnologies/weaviate向量库默认真正难拉的是langgenius/dify-api、langgenius/dify-web、langgenius/dify-sandbox这三个因为它们只在 Docker Hub 上有。postgres、redis、nginx 这些基础镜像国内各大加速器都有缓存问题不大。2.2 三种国内可用的镜像获取路径我实际用过并且能跑通的方案有三种按推荐程度排方案一配置 Docker 镜像加速器指定版本 tag。这是改动最小的方式。国内主流云厂商都提供容器镜像加速服务配置到/etc/docker/daemon.json之后Docker Hub 的镜像会走加速节点拉取。但要注意加速器对langgenius这类非官方仓库的缓存命中率不稳定热门 tag 一般有缓存冷门 tag 可能还是要回源。方案二使用国内镜像仓库的同步版本。一些国内镜像仓库会定期同步 Docker Hub 上的热门镜像。你需要手动把 compose 文件里的image:字段替换成国内仓库地址。这个方案的关键是找到同步了 dify 的仓库并且确认 tag 和你的dify-main代码版本匹配。方案三本地构建。如果前两种都不行dify-main源码里本身带了 Dockerfile你可以docker build自己构建 api 和 web 镜像。缺点是构建时间长web 镜像的 Next.js 构建在国内也需要配 npm 镜像源。提示不管用哪种方案先把dify-main的docker/.env.example复制成.env里面有几个版本相关的变量需要确认。2.3 确认代码版本和镜像 tag 的对应关系这一步很多人会忽略。dify-main是主分支代码它的docker-compose.yaml里写的镜像 tag 可能是latest也可能是某个具体版本号。如果你拉到的镜像 tag 和代码不匹配会出现数据库 migration 失败或者 API 启动报错。# 进入 dify-main 的 docker 目录 cd dify-main/docker # 查看 compose 文件里引用的镜像 tag grep -E image: docker-compose.yaml # 查看当前代码的版本号如果有 VERSION 文件 cat ../VERSION 2/dev/null || echo no VERSION file # 查看最近一次 commit判断代码新旧 git -C .. log -1 --format%h %ci %s逻辑说明grep image:把所有镜像引用列出来你重点关注langgenius/开头的那些。VERSION文件不一定存在没有的话就看 git log 的日期。参数方面如果 compose 里写的是langgenius/dify-api:latest那你要确保拉到的也是最新版如果写的是langgenius/dify-api:0.6.9这种具体版本就必须拉对应版本不能混用。3. 改造 docker-compose把镜像地址换成国内可拉取的写法3.1 用 override 文件做镜像替换不动原始 compose直接改docker-compose.yaml有个问题下次git pull更新代码时会产生冲突。我一般用docker-compose.override.yaml来做镜像替换这样原始文件保持干净。# docker-compose.override.yaml # 放在 dify-main/docker/ 目录下和 docker-compose.yaml 同级 services: api: image: 国内仓库地址/dify-api:latest web: image: 国内仓库地址/dify-web:latest sandbox: image: 国内仓库地址/dify-sandbox:latest逻辑说明Docker Compose 会自动读取同目录下的docker-compose.override.yaml并与主文件合并image字段会被覆盖。参数方面国内仓库地址替换成你实际可用的镜像仓库前缀。如果你用的是镜像加速器方案而不是替换仓库地址那这一步可以跳过直接配 daemon.json 就行。3.2 配置 Docker 镜像加速器如果选择加速器方案编辑 Docker 的配置文件# 编辑或创建 daemon.json sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json -EOF { registry-mirrors: [ https://你的加速器地址1, https://你的加速器地址2 ], max-concurrent-downloads: 5, max-download-attempts: 5 } EOF # 重载配置并重启 Docker sudo systemctl daemon-reload sudo systemctl restart docker # 验证加速器是否生效 docker info | grep -A 5 Registry Mirrors逻辑说明registry-mirrors是加速器地址列表Docker 会按顺序尝试。max-concurrent-downloads控制并发拉取层数国内网络下建议不要设太高5 左右比较稳。max-download-attempts是单层重试次数默认 5 次网络差的时候可以加到 10。重启后必须用docker info确认加速器已经加载如果Registry Mirrors下面是空的说明配置没生效检查 JSON 格式。3.3 拉取镜像并验证配置好之后先单独拉镜像不要直接up这样出问题好定位# 逐个拉取核心镜像观察哪个卡住 docker pull langgenius/dify-api:latest docker pull langgenius/dify-web:latest docker pull langgenius/dify-sandbox:latest # 拉完之后确认本地镜像列表 docker images | grep -E dify|langgenius # 如果某个镜像拉不动试试指定平台部分镜像只有 amd64 docker pull --platform linux/amd64 langgenius/dify-api:latest逻辑说明单独 pull 的好处是能看到具体卡在哪一层。如果dify-api拉下来了但dify-web卡住说明加速器对 web 镜像的缓存没命中。--platform linux/amd64在 ARM 机器比如 M 系列 Mac上有时能绕过 manifest 不匹配的问题。参数上如果你的机器是 ARM 架构而镜像只有 amd64 版本Docker 会通过 QEMU 模拟运行性能会下降生产环境不建议这么干。4. 启动与参数配置让 dify-main 在国内环境真正跑起来4.1 最小启动命令与关键环境变量镜像拉到位之后启动本身不复杂但.env里有几个参数必须改不然起来了也用不了。cd dify-main/docker # 复制环境变量模板 cp .env.example .env # 编辑 .env重点改这几项 # EXPOSE_NGINX_PORT80 # 如果 80 被占用改成别的 # CONSOLE_API_URL # 留空则用相对路径 # APP_WEB_URL # 同上 # SECRET_KEY # 必须改用 openssl rand -base64 42 生成 # INIT_PASSWORD # 首次登录的管理员密码生成 SECRET_KEYopenssl rand -base64 42逻辑说明SECRET_KEY是 Dify 用来签名会话和加密敏感数据的默认值绝对不能用于任何非本地测试环境。INIT_PASSWORD是初始化管理员账号的密码第一次启动时会用到。EXPOSE_NGINX_PORT默认 80如果本机 80 被占比如装了其他 web 服务改成 8080 之类的。启动命令# 后台启动所有服务 docker compose up -d # 查看启动状态重点看 api 和 web 是否 healthy docker compose ps # 跟踪 api 日志看有没有 migration 报错 docker compose logs -f api4.2 数据库 migration 与首次初始化Dify 的 api 容器启动时会自动执行数据库 migration。如果镜像版本和代码版本不匹配这一步会报错。# 查看 api 容器日志中的 migration 输出 docker compose logs api | grep -i migrat # 如果 migration 失败手动进容器执行 docker compose exec api flask db upgrade # 检查数据库当前版本 docker compose exec api flask db current逻辑说明flask db upgrade是手动触发 migration正常情况下容器启动时自动执行。如果自动执行失败手动跑一次能看到具体报错。flask db current显示当前数据库的 migration 版本号和你代码里的 migration 文件对比能判断是否落后。参数方面如果报Cant locate revision说明数据库里的版本号在代码里找不到对应文件通常是镜像 tag 和代码版本差太远需要换镜像。4.3 验证部署是否成功启动完成后按这个顺序验证# 1. 检查所有容器状态 docker compose ps --format table {{.Name}}\t{{.Status}} # 2. 检查 nginx 是否正常响应 curl -I http://localhost:80 # 3. 检查 api 健康端点 curl http://localhost:80/console/api/health # 4. 检查 web 页面是否返回 HTML curl -s http://localhost:80 | head -20逻辑说明docker compose ps里所有服务应该是running或healthy。curl -I返回 200 或 307 都算正常。/console/api/health是 api 的健康检查端点返回 JSON 说明后端通了。如果 nginx 返回 502说明 api 或 web 没起来去看对应容器的日志。5. 避坑与排查国内部署 dify-main 最常见的 5 个翻车点5.1 镜像拉取到一半卡死重试也拉不动现象docker compose up -d卡在Pulling阶段CtrlC 之后重新拉还是卡在同一层。原因Docker 的层缓存机制导致失败的层被标记为「下载中」重试时不会重新开始。另外加速器对某些层没有缓存回源又超时。解决先清理未完成的拉取状态再换一个加速器地址重试。# 清理 dangling 镜像和未完成的拉取 docker image prune -f # 如果还是不行重启 Docker 服务清掉拉取状态 sudo systemctl restart docker # 换加速器地址后重试 docker pull langgenius/dify-api:latest5.2 api 容器反复重启日志报数据库连接失败现象docker compose ps里 api 状态是Restarting日志里刷could not connect to server: Connection refused。原因db 容器还没完全初始化好api 就启动去连了。或者.env里的DB_HOST、DB_PORT被改错了。解决确认.env里数据库配置和 compose 文件一致给 api 加启动延迟。# 先单独启动 db 和 redis等它们 healthy 再启动 api docker compose up -d db redis docker compose ps # 等 db 显示 healthy docker compose up -d api web nginx5.3 web 容器起来了但页面白屏现象nginx 返回 200但浏览器打开是空白页控制台报 JS 加载失败。原因dify-web镜像里的静态资源路径和 nginx 配置不匹配常见于镜像版本和代码版本不一致。解决确认 web 镜像 tag 和代码版本对应检查 nginx 配置里的proxy_pass指向。# 查看 web 容器日志 docker compose logs web # 进 web 容器看静态文件是否存在 docker compose exec web ls /app/.next/static # 检查 nginx 配置 docker compose exec nginx cat /etc/nginx/conf.d/default.conf5.4 sandbox 容器启动报权限错误现象sandbox 容器启动后立刻退出日志报permission denied或operation not permitted。原因sandbox 需要特定的内核权限来做代码隔离执行部分国内云主机或容器环境限制了这些权限。解决如果只是本地测试可以临时禁用 sandbox在.env里设置CODE_EXECUTION_ENDPOINT为空或改用其他执行方式。生产环境需要给容器加--privileged或调整 seccomp 配置。# 查看 sandbox 日志确认具体错误 docker compose logs sandbox # 临时方案在 .env 中关闭代码执行 # CODE_EXECUTION_ENDPOINT # CODE_EXECUTION_API_KEY5.5 更新代码后 migration 冲突现象git pull更新了dify-main代码重新up -d后 api 报Target database is not up to date或Multiple head revisions。原因新代码带了新的 migration 文件但数据库里已经有部分 migration 记录或者多个分支的 migration 产生了冲突。解决先备份数据库再手动处理 migration。# 备份数据库 docker compose exec db pg_dump -U postgres dify backup_$(date %Y%m%d).sql # 查看当前 migration 状态 docker compose exec api flask db heads docker compose exec api flask db current # 如果有多个 head需要 merge docker compose exec api flask db merge heads docker compose exec api flask db upgrade6. 进阶技巧用国内镜像源加速构建和长期维护如果你走的是本地构建路线或者需要在 CI 里自动构建 dify 镜像npm 和 pip 的源配置是绕不开的。dify-web的 Dockerfile 里跑npm install默认走 registry.npmjs.org国内构建能等到天荒地老。# 在 dify-web/Dockerfile 的 npm install 之前插入 RUN npm config set registry https://registry.npmmirror.com # 在 dify-api/Dockerfile 的 pip install 之前插入 RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple逻辑说明这两行分别把 npm 和 pip 的源指向国内镜像。参数上npm 用 npmmirror原淘宝源pip 用清华源这两个是我实测比较稳的。注意不要用--registry临时参数写在 Dockerfile 里才能让所有层都生效。另一个长期维护的技巧是给镜像打本地 tag。国内镜像仓库的地址往往很长每次 compose 里写一长串容易出错。拉下来之后统一打个短 tag# 拉取后重命名方便 compose 引用 docker tag 国内仓库地址/dify-api:latest dify-api:local docker tag 国内仓库地址/dify-web:latest dify-web:local docker tag 国内仓库地址/dify-sandbox:latest dify-sandbox:local # compose override 里就可以写短 tag # image: dify-api:local这样做的另一个好处是当你需要切换镜像版本时只需要重新 tag不用改 compose 文件。我一般会在docker-compose.override.yaml里统一用:local后缀配合一个pull-and-tag.sh脚本每次更新镜像跑一次脚本就行。最后说一个我踩过的坑国内镜像仓库的同步有延迟有时候latesttag 指向的版本比 Docker Hub 落后好几天。如果你在追新功能拉完之后用docker inspect看一下镜像的创建时间确认不是几个月前的老版本。这个习惯帮我省过好几次「为什么新功能没有」的排查时间。希望帮到你。本文还有配套的精品资源点击获取

国内环境快速部署Dify：镜像拉取与docker-compose改造指南

相关推荐

WSL下STM32烧录难题：ST-Link USB直通与OpenOCD实战

低功耗气体传感模组物联网设计：从选型到功耗优化的实战解析

CH379M双通道读卡器方案：SD/TF卡并行读写与国产化迁移实践

更多资讯

Apache Calcite 1.4.0-incubating 发布解析：RelBuilder 关系代数构建器 API 的诞生

Peekaboo 实时多目标认证协调器：双后台控制器与前台语义重叠的行为契约全解析

LunaTranslator OCR 设置一步到位：从零配置到云端加速的完整避坑指南

Nuitka打包Python：MinGW64工具链配置与常见错误排查

AI编程代理工具链：记忆层、代码地图与Token记账实战

fonttools mtiLib 全解析：读取 Monotype FontDame 文本格式的 OpenType 布局表

今日更新

声子晶体仿真：三角晶格与六角晶格的能带计算实战

度假村安保定岗定编：岗位梳理、编制测算与排班设计

COMSOL等离子体模块实战：氩气双层DBD仿真建模全解析

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？