简介这份资源是面向国内开发者与运维人员的 dify-main Docker 镜像包主要解决在国内网络环境下拉取官方镜像速度慢、不稳定甚至无法访问的问题适合需要快速搭建与测试 dify 相关技术栈的中高级开发者使用。压缩包共包含 2000 个文件以 1411 个 py 源码文件、370 个 json 配置、103 个 css 样式、41 个 md 文档为主另有 js、yaml、sh、html、sql 等辅助文件整体约 20.29MB目录结构完整便于按模块查阅与二次开发。目前已有 1481 人学习下载说明该镜像方案在社区中具备一定认可度。通过该资源读者可直接获得适配国内环境的镜像文件省去自行配置镜像源与反复调试的麻烦同时可结合其中的源码、配置与文档快速理解项目结构、部署流程与依赖关系为本地开发、测试及合规部署提供便利。1. 国内环境跑 dify-main从拉镜像到服务起来的完整路径dify-main 这个仓库名最近在不少技术群里被反复提起。很多人拿到的是同一个诉求想在内网或者国内网络环境下把 Dify 主分支的镜像版本跑起来做一套自己的 AI 应用编排平台。问题往往卡在第一步——镜像拉不动、依赖装不上、服务起不来。我前后在几台机器上折腾过这套东西从最开始的盲目docker compose up到后来摸清每个环节的替代方案中间踩的坑足够写满一页纸。这篇笔记不讲 Dify 是什么只讲在国内网络条件下怎么把 dify-main 的镜像版本从零跑通包括镜像获取、依赖替换、配置调整和排错。适合已经决定用 Dify 做应用编排、但被网络和镜像问题卡住的工程师也适合想在内网环境部署一套可维护 AI 平台的团队参考。2. 镜像获取dify-main 的镜像从哪来、怎么换2.1 先搞清楚 dify-main 的镜像构成Dify 的部署包不是单个镜像而是一组服务的组合。核心包括dify-api、dify-web、dify-worker再加上 PostgreSQL、Redis、Weaviate 或 Qdrant 这类向量库以及 Nginx 做入口。dify-main指的是主分支构建出来的镜像标签通常以langgenius/dify-api:main这种形式存在。国内直接拉这些镜像大概率会卡在 Docker Hub 的连通性上表现为pull access denied或者长时间停在Waiting状态。我一般会先确认当前部署包里的docker-compose.yaml引用了哪些镜像。命令很简单进到项目根目录执行grep -E image: docker-compose.yaml输出会列出所有依赖的镜像地址。把这些地址记下来后面逐个替换。注意dify-main的 compose 文件里有些镜像带latest或main标签有些带具体版本号替换时标签要对应不能随意改。2.2 用国内镜像源替换 Docker Hub 地址最直接的办法是给 Docker 配置镜像加速器。编辑/etc/docker/daemon.json加入国内可用的 registry-mirrors。不同云厂商的加速地址不一样选一个当前可用的就行。配置完重启 Dockersudo systemctl daemon-reload sudo systemctl restart docker然后重新拉取。如果加速器对某些镜像仍然无效就需要手动替换镜像前缀。比如把langgenius/dify-api:main换成某个国内 registry 上的同步版本。常见做法是使用阿里云或腾讯云的容器镜像服务把 Docker Hub 上的镜像同步到自己的命名空间下。这一步需要你有对应云账号在控制台里创建同步规则把langgenius/dify-api、langgenius/dify-web等仓库同步过去。同步完成后修改docker-compose.yaml里的image字段指向你的同步地址。例如services: api: image: registry.cn-hangzhou.aliyuncs.com/your-namespace/dify-api:main改完保存再执行docker compose pull。如果同步的镜像标签和原仓库一致这一步就能顺利拉下来。2.3 离线环境下的镜像导入方案有些内网机器完全不能出网那就需要在一台能出网的机器上先把镜像拉下来导出成 tar 包再拷贝进去。操作如下# 在能出网的机器上拉取并导出 docker pull langgenius/dify-api:main docker save -o dify-api-main.tar langgenius/dify-api:main # 拷贝到内网机器后导入 docker load -i dify-api-main.tar所有镜像都这样处理一遍包括 PostgreSQL、Redis、向量库和 Nginx。导入后给镜像打上 compose 文件里引用的标签或者直接改 compose 文件指向本地镜像名。这一步的坑在于镜像层数多、体积大docker save出来的 tar 包可能好几个 GB拷贝时注意磁盘空间。提示导出前先用docker images确认镜像标签和 compose 文件里完全一致避免导入后标签对不上导致 compose 找不到镜像。3. 依赖与配置让 dify-main 在国内环境跑起来3.1 Python 依赖的国内源替换Dify 的 api 服务基于 Python构建镜像时会从 PyPI 拉大量包。如果直接构建国内网络下大概率超时。解决办法是在 Dockerfile 里替换 pip 源。找到 api 目录下的 Dockerfile在pip install之前插入一行RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple如果不想改 Dockerfile也可以在构建时通过--build-arg传入。但 Dify 的 compose 文件默认不传构建参数所以改 Dockerfile 更直接。改完后重新构建docker compose build api构建过程中如果还有包拉不下来检查是不是某些依赖指定了 git 地址。Dify 的requirements.txt里偶尔会有从 GitHub 直接安装的包这类依赖在国内网络下容易失败。遇到这种情况可以手动把该依赖换成 PyPI 上的同名包或者提前下载 whl 文件放到本地目录用pip install --find-links指定本地路径。3.2 数据库和向量库的初始化配置Dify 依赖 PostgreSQL 存元数据Redis 做缓存向量库存嵌入向量。compose 文件里这些服务默认会拉取官方镜像。国内环境下PostgreSQL 和 Redis 的官方镜像通常可以通过加速器拉取问题不大。向量库如果是 Weaviate 或 Qdrant镜像体积较大建议提前同步。配置方面重点看.env文件。Dify 的 compose 会读取根目录下的.env里面定义了数据库密码、Redis 端口、向量库类型等。国内部署时我一般会改这几个# .env 关键项 POSTGRES_PASSWORDyour_strong_password REDIS_PASSWORDyour_redis_password VECTOR_STOREweaviate WEAVIATE_ENDPOINThttp://weaviate:8080如果向量库换成 QdrantVECTOR_STORE改成qdrant并确保QDRANT_URL指向正确地址。改完.env后先启动数据库和向量库docker compose up -d postgres redis weaviate等这些服务健康检查通过后再启动 api 和 worker。顺序反了会导致 api 启动时连不上数据库反复重启。3.3 前端资源的本地化处理dify-web镜像构建时会从 npm 拉包。国内网络下同样需要替换 npm 源。在 web 目录的 Dockerfile 里npm install之前加入RUN npm config set registry https://registry.npmmirror.com如果前端构建过程中还有下载字体或静态资源失败的情况检查next.config.js里有没有引用外部 CDN。有的话改成相对路径或者本地资源。构建完成后dify-web容器启动Nginx 做反向代理。Nginx 配置在docker/nginx目录下默认监听 80 端口代理到 api 和 web。国内部署时如果 80 端口被占用改nginx.conf里的listen端口同时调整 compose 里的端口映射。4. 避坑排查dify-main 国内部署的五个翻车点4.1 镜像拉取成功但容器启动即退出现象docker compose up -d后docker ps看不到 api 容器或者状态是Exited (1)。查看日志docker logs dify-api报错通常是数据库连接失败。原因api 启动时 PostgreSQL 还没完全就绪或者.env里的数据库密码和 postgres 容器实际密码不一致。Dify 的 compose 里 postgres 密码从.env读取如果.env改了但 postgres 数据卷是旧的密码不会同步更新。解决先确认.env里POSTGRES_PASSWORD和 compose 文件里 postgres 服务的POSTGRES_PASSWORD环境变量一致。如果之前启动过删掉数据卷重新来docker compose down -v再docker compose up -d postgres等健康检查通过后再启动 api。4.2 前端页面打开空白或静态资源 404现象浏览器访问 Nginx 端口页面加载但白屏控制台报 JS 或 CSS 文件 404。原因dify-web构建时静态资源路径配置不对或者 Nginx 的root指向了错误目录。国内替换 npm 源后如果构建过程中断过可能生成不完整的.next目录。解决进到 web 容器里检查/app/.next目录是否存在且完整。不完整就重新构建docker compose build web --no-cache。同时检查 Nginx 配置里location /的proxy_pass是否指向web:3000。4.3 向量库连接超时导致嵌入失败现象在 Dify 里创建知识库、上传文档后处理一直卡在pendingworker 日志报向量库连接超时。原因向量库容器虽然启动了但端口没对 api 和 worker 开放或者.env里的向量库地址写成了localhost。在 Docker 网络里服务之间要用服务名通信不能用localhost。解决确认.env里WEAVIATE_ENDPOINT或QDRANT_URL用的是 compose 里的服务名比如http://weaviate:8080。然后用docker exec进 api 容器curl一下向量库地址看能不能通。4.4 构建镜像时 pip 或 npm 卡住不动现象docker compose build执行到pip install或npm install时长时间无输出最后超时失败。原因国内源替换没生效或者某些包在国内源里没有同步。Dify 的依赖里有些包版本较新国内源可能滞后。解决先确认 Dockerfile 里的源替换命令在pip install之前执行。如果某个包确实拉不到单独在requirements.txt里把它注释掉手动从其他途径获取 whl 文件用COPY指令拷进镜像再安装。npm 同理可以配置--registry参数或者用.npmrc文件。4.5 服务全部启动但 API 返回 502现象Nginx 起来了前端能访问但调用 API 时返回 502 Bad Gateway。原因api 容器虽然运行但内部服务没监听在预期端口或者 Nginx 的proxy_pass指向了错误的 api 地址。Dify 的 api 默认监听 5001 端口Nginx 配置里如果写成了 8000 就会 502。解决docker exec进 api 容器netstat -tlnp看实际监听端口。然后核对 Nginx 配置里location /api的proxy_pass地址。改完 Nginx 配置后docker compose restart nginx。5. 进阶技巧用本地构建替代镜像拉取彻底摆脱网络依赖前面讲的都是拉取或同步现成镜像。如果你在内网环境反复部署或者需要对 Dify 做定制修改更彻底的办法是本地构建所有镜像。Dify 的仓库里每个服务都有 Dockerfile只要把依赖源替换好完全可以在本地构建出全套镜像然后导出成 tar 包以后部署直接导入不再依赖任何外部 registry。具体做法先在一台能出网的机器上克隆dify-main仓库修改 api 和 web 的 Dockerfile 替换 pip/npm 源。然后执行docker compose build构建完成后用docker save把所有镜像打包docker save -o dify-full.tar \ dify-api:latest \ dify-web:latest \ dify-worker:latest \ postgres:15 \ redis:6 \ semitechnologies/weaviate:1.19.0 \ nginx:latest把这个 tar 包拷到内网机器docker load -i dify-full.tar然后修改 compose 文件里的image字段指向本地镜像名直接docker compose up -d。这套流程我用了大半年内网部署从最初的两天缩短到半小时。注意本地构建的镜像标签要和 compose 文件里引用的完全一致否则 compose 会尝试从远程拉取。构建前先docker compose config看一下最终解析出的镜像名。还有一个细节Dify 的 api 和 worker 用的是同一个镜像只是启动命令不同。构建一次就行compose 里两个服务引用同一个 image 字段。这样能省不少构建时间。最后说一个我自己的习惯每次部署前先把.env和docker-compose.yaml备份一份改坏了直接回滚。国内环境跑 dify-main最怕的不是拉不到镜像而是改了一堆配置之后忘了改了什么出问题无从查起。备份加版本管理比任何排错技巧都管用。希望帮到你。本文还有配套的精品资源点击获取