企业官网建设流程全解析

部署Dify 1.1.3的时候，我遇到了PostgreSQL初始化失败。准确说不是PostgreSQL本身起不来，而是api容器启动时数据库还没就绪，一连串连接报错、迁移失败直接把我整懵了。这个问题在Dify部署群里几乎每天都能见到：第一次docker compose up -d，容器一个接一个起来，结果打开网页进不去安装页，docker compose logs -f api一看，满屏都是connect: connection refused。这一篇我就把完整的排查思路和修复过程写清楚，核心就一句话：用wait-for-it.sh让api和worker等数据库真正就绪后再启动。

Dify是什么不用我多介绍，搞AI应用开发的基本都知道——开源LLM应用开发平台，可视化编排工作流、知识库流水线、智能体，一个界面全搞定。很多人第一次接触Dify，就是冲着本地部署一个私有环境来的，想着数据不出去、模型可以自由接。但恰恰是这一步，卡住了大量新手。我碰到的问题也很有代表性：PostgreSQL容器状态显示运行中，日志却一直刷初始化信息，api容器疯狂重启，登录页面永远出不来。这篇避坑指南不只针对1.1.3，Dify后续很多版本也用同样的docker-compose方式部署，思路完全通用。

1. 部署Dify时，那个让人头疼的PostgreSQL初始化失败

1.1 先交代一下背景：Dify到底是个什么

Dify是一款开源的LLM应用开发平台，核心价值在于把AI应用的开发流程可视化、模块化。它集成了模型管理、Prompt编排、知识库（RAG）、工作流、智能体（Agent）等能力，开发者不需要从零写代码去串联各家大模型API，直接在Web界面里拖拖拽拽就能搭出一个带知识库的问答机器人或者自动化工作流。

这也是为什么Dify在本地部署圈子里热度一直很高。很多人装Dify不只是尝鲜，而是真想把它当生产工具用——比如把内部文档丢进知识库做成企业问答助手，或者接上Ollama本地部署的DeepSeek这类模型做私有化推理。本地部署的最大好处是数据自主可控，加上Dify本身是社区版免费开源，于是大量个人开发者和中小企业选择自己用Docker部署一套。

但问题也出在这：Dify整套系统组件非常多，不只是Dify本体，还包括PostgreSQL、Redis、Weaviate（或Qdrant）等中间件。docker compose一拉起来就是十几个容器，任何一个环节没就绪，整个系统就起不来。其中PostgreSQL的初始化问题，是我见过最多、也最容易被误判的一个。

1.2 初始化失败的典型报错长什么样

我那次部署，配置文件改完、镜像拉完后执行docker compose up -d，满怀期待等了几分钟，结果一访问服务器IP，浏览器直接转圈，最后提示无法访问。这时候的第一反应就是看容器状态，docker compose ps一拉，一排容器里好几个显示restarting，尤其是api和worker。

再看日志，问题就很明显了。api容器的日志里反复出现这类异常：

psycopg2.OperationalError: could not connect to server: Connection refused Is the server running on host "db" (172.20.0.3) and accepting TCP/IP connections on port 5432?

紧接着就是数据库迁移失败：

INFO [alembic.runtime.migration] Context impl PostgresqlImpl. ERROR: relation "app_models" does not exist

worker容器的情况也差不多，连不上数据库，任务队列根本起不来。这套报错组合拳下来，基本可以断定：PostgreSQL还没准备好，Dify的api服务却已经开始尝试连接并执行迁移了。

但有意思的是，你去docker compose ps看db容器，状态竟然是Up，有时甚至显示healthy。这就让很多人困惑：数据库明明在运行，为什么连接被拒绝？其实容器“在运行”和数据库“能接受连接”是两码事，这个坑坑了我一整个下午，必须说清楚。

1.3 问题根源不只是“顺序”

Dify的api镜像在容器启动时会执行数据库迁移命令，把数据表结构初始化到PostgreSQL里。问题在于，PostgreSQL容器首次启动时并不是立刻就能对外服务的——它要先初始化数据目录、创建用户、创建数据库、执行初始化脚本，然后才能真正监听5432端口。

docker-compose里虽然有depends_on配置，但depends_on默认只控制容器“启动”的先后顺序，不控制“服务就绪”与否。也就是说，api容器看到db容器启动了，就立刻开始跑自己的逻辑，而db容器此时可能还在初始化数据目录阶段。api一连接，自然就是connection refused。

这不是Dify独有的问题，而是Docker Compose编排里最常见的通用陷阱之一。任何有依赖关系的服务，比如api依赖数据库、worker依赖Redis，都会遇到。很多人第一反应是给db容器加restart，但这种重启只解决了db自身崩溃的问题，解决不了“api启动得太早”的问题。真正要做的，是让api等一等，等数据库能够接受连接了再干活。

2. 为什么depends_on搞不定这件事

2.1 depends_on只保证“启动顺序”不保证“就绪”

docker-compose的depends_on，很多人理解成“等前面的服务完全可用后我再启动”，其实不是。它只是一个启动顺序控制器，保证被依赖的容器先启动，但不会检测被依赖容器里的服务是否真正可用。

打个比方，depends_on只是叫你“起床”，不会确认你是不是已经洗漱好可以出门了。你起来了，但还在刷牙，后面的服务已经冲到门口等着走了。PostgreSQL容器刚创建数据目录的时候，进程还在忙着initdb和配置权限，虽然容器状态是运行中，但5432端口对外完全不可用。

Compose也提供了一种进阶写法，配合healthcheck使用：

depends_on: db: condition: service_healthy

这种写法确实能解决问题，前提是你给db服务定义了准确的healthcheck，并且docker-compose版本支持这个语法。Dify 1.1.3自带的docker-compose.yaml里，db服务并没有配置合适的healthcheck条件，所以直接用depends_on等于白配。

2.2 PostgreSQL初始化到底做了什么

理解这个问题，得先知道PostgreSQL官方Docker镜像启动时做了什么。这里我简单梳理一下流程：

• 容器启动后，entrypoint脚本检查数据目录是否为空。
• 如果为空，执行initdb初始化数据目录，生成系统表。
• 根据环境变量（POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB）创建用户和数据库。
• 执行/docker-entrypoint-initdb.d目录下的所有初始化脚本。
• 配置好访问权限后，关闭临时实例，再以正式模式启动PostgreSQL监听5432端口。

也就是说，从容器启动到真正能接受外部连接，中间可能隔了几十秒，取决于服务器磁盘性能和初始化脚本的复杂度。尤其第一次启动时，涉及到initdb和数据目录权限设置，耗时更长。而api容器启动只需要几秒钟，它当然会撞在数据库还没有就绪的时间窗口上。

还有一点很多人忽略：PostgreSQL初始化过程中，5432端口可能已经在监听，但这时候接受的连接会返回“the database system is starting up”这样的错误，而不是直接的connection refused。这种错误更容易误判成数据库配置有问题，实际只是时机问题。

2.3 除了等待，还有什么干净的补救方法

遇到这种问题，通常有几种解法：

• 手动反复restart api容器：如果PostgreSQL已经初始化完成，重启api就能成功。这招作为临时救急没问题，但自动化部署时不可靠。
• 给db添加healthcheck，配合depends_on的condition: service_healthy：这是相对规范的做法，但需要改db服务的定义。
• 用wait-for-it.sh脚本显式等待：在执行api启动命令之前，先等待db:5432可连接。这是我这篇博文要重点讲的方案，因为它不需要改动db服务本身的配置，侵入性最小。
• 粗暴地加sleep：比如command: sleep 30 && python ...，虽然简单，但等待时间是拍脑袋定的，数据库初始化慢一点就不够用，快一点又浪费时间。

我做个表格对比一下这几种方式，方便你根据场景选择：

个人建议是：本地或者测试环境快速部署，用wait-for-it.sh最省心；要长期跑生产，优先把healthcheck和condition配好。两者不冲突，甚至可以在同一套配置里同时用。

3. wait-for-it.sh：一个可靠的“等位”脚本

3.1 脚本原理解读

wait-for-it.sh是GitHub上一个非常经典的开源小脚本，作者是vishnubob。它的作用很简单：轮询指定的主机和端口，直到连接成功或者超时，然后可以选择性地继续执行后续命令。在容器编排中，它常被用来解决服务启动依赖问题。

基本用法是这样的：

./wait-for-it.sh db:5432 -t 60 -- python app.py

意思是：等待db的5432端口可以被TCP连接，最多等60秒，等到了之后执行后面的python app.py。

脚本的核心逻辑并不复杂。它通过bash内置的/dev/tcp特性或者nc工具去尝试连接目标地址，连接失败就sleep几秒再试，循环往复，直到成功或超时。它支持几个常用参数：

用它来等PostgreSQL，本质就是在api进程启动前增加一道“门禁”：数据库端口可连接了，才放行。相比sleep那种盲等，这种方式准得多，数据库30秒初始化完就30秒后启动api，60秒完成就60秒后启动，不会多等也不会少等。

3.2 什么时候用它，什么时候用healthcheck

wait-for-it.sh不是唯一解法，但我在Dify部署场景下特别偏爱它，原因有两点。

第一，它不需要改动PostgreSQL服务的任何配置。你只需要把脚本挂载到api或worker容器里，改一下command命令，其他服务完全不用动。如果是在别人写好的docker-compose.yaml上做最小改动，这很关键。

第二，它的等待逻辑是显式的。你可以直接在命令里看到“我要等db:5432”，排错的时候一目了然。healthcheck方案虽然更Docker原生，但它把等待逻辑隐藏在了compose文件深处，新手排查问题时往往反应不过来。

当然，healthcheck在正式环境里依然是更推荐的做法，因为它是Docker编排层面的标准能力，对容器生命周期管理更友好。比如编排工具可以根据容器健康状态决定是否重启、是否纳入服务发现。wait-for-it.sh这种在进程内部等待的方式，只在容器启动的那一刻起作用，进程起来之后如果数据库挂了，它帮不上忙。

我实际部署时的选择是：生产环境两个都配——db服务加healthcheck，api和worker的command里依然用wait-for-it.sh做双保险。这样即使Compose版本或语法有兼容问题，脚本也能兜底。

3.3 使用前的两个小坑：换行符和权限

wait-for-it.sh本身是个bash脚本，在Linux/Mac上直接下载就能用，但在Windows上操作经常会遇到两个奇怪的问题。

第一个坑是换行符。如果在Windows下用记事本或者某些编辑器改过这个脚本，文件的行尾符会变成CRLF。Linux容器里执行时会报“/bin/sh^M: bad interpreter: No such file or directory”或者类似错误。解决办法很简单，把脚本放到Linux环境后执行一次：

sed -i 's/\r$//' wait-for-it.sh

或者用dos2unix命令转换。这步我几乎每次部署都会做，因为Windows编辑器的习惯很难改。

第二个坑是执行权限。脚本挂载进容器后，如果没有执行权限，直接调用会报Permission denied。在宿主机上先执行chmod +x wait-for-it.sh，或者在容器内调用时用sh前置，比如改成sh /wait-for-it.sh，也能绕过。

还有一个容易被忽略的点：wait-for-it.sh的原版依赖bash特性，所以在容器里需要bash环境。Dify的镜像基于python:slim，一般自带bash，直接在command里用/bin/bash -c调用脚本应该没问题。如果遇到精简镜像没有bash的情况，可以用sh版本或者简化版脚本，后面实操部分我再给替代写法。

4. 实操：给Dify 1.1.3打上wait-for-it补丁

4.1 准备工作：拉取代码、生成密钥

先说明一下我的环境：Ubuntu 22.04服务器，已经装好Docker和Docker Compose插件。Dify的部署包可以直接从GitHub Releases下载，我拿到的是1.1.3的压缩包，解压后进入docker目录：

unzip dify-1.1.3.zip cd dify-docker-1.1.3/docker

这个目录下最重要的是docker-compose.yaml和.env.example。先把环境变量文件复制出来：

cp .env.example .env

打开.env，把SECRET_KEY那一行取消注释，填一个随机生成的值。可以用openssl生成：

openssl rand -base64 42

把生成的字符串填到.env里，还有POSTGRES_PASSWORD、POSTGRES_USER等数据库账号信息，如果没有特殊需求可以保持默认，但生产环境建议改掉。这一步是常规操作，但漏掉SECRET_KEY会导致后面api容器反复报错。

4.2 先复现一次初始化失败

为了让问题看得更明白，我建议你先不要急着修复，按照原始配置启动一次，亲自看一下报错现场。执行：

docker compose up -d

第一次启动会拉取大量镜像，Dify的组件很多，包含api、worker、web、db、redis、sandbox、ssrf_proxy、weaviate等，耐心等几分钟。拉完镜像后，容器会自动启动。等个一两分钟再看状态：

docker compose ps

我那次看到的状态是db和weaviate显示Up或者Restarting，api和worker直接是Restarting。用日志确认：

docker compose logs api

日志里就是前面说的psycopg2.OperationalError。到这里，问题复现完毕，可以开始修复。这时候再回头看db日志，会发现数据库其实还在做初始化：

docker compose logs db

日志中间会出现“database system is ready to accept connections”字样，但这条日志出现的时间点，往往已经晚于api第一次尝试连接的时间。两相对照，“启动时序”的问题就实锤了。

4.3 加入wait-for-it.sh并修改compose

下载wait-for-it.sh脚本到docker部署目录，也就是和docker-compose.yaml同一个目录：

wget https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh chmod +x wait-for-it.sh sed -i 's/\r$//' wait-for-it.sh

三条命令一步到位：下载、加执行权限、转换换行符。如果服务器访问GitHub的raw地址比较慢，也可以直接在本地下载然后上传，或者从其他开发者镜像站获取。总之确保文件内容完整、是Unix换行即可。

接下来修改docker-compose.yaml。用vim打开文件，找到api服务段落，大概长这样：

api: image: langgenius/dify-api:1.1.3 restart: always environment: MODE: api ... volumes: - ./volumes/app/storage:/app/api/storage depends_on: - db - redis command: /bin/bash -c 'python /app/api/commands.py start-api'

核心改动有两处：第一，在volumes里挂载wait-for-it.sh脚本；第二，把command改成先等待数据库再启动api。

改完的api服务关键部分长这样：

api: image: langgenius/dify-api:1.1.3 restart: always environment: MODE: api ... volumes: - ./volumes/app/storage:/app/api/storage - ./wait-for-it.sh:/wait-for-it.sh:ro depends_on: - db - redis command: /bin/bash -c '/wait-for-it.sh db:5432 -t 60 -- python /app/api/commands.py start-api'

注意，这里我把等待目标写成db:5432，是因为docker-compose内部网络里，PostgreSQL服务的主机名就是db。如果你在.env里改了数据库服务名或者端口映射，这里要跟着改。等数据库就绪后，再执行原有的start-api命令。

worker服务的改动一模一样。Dify的worker主要负责异步任务，启动命令是：

worker: image: langgenius/dify-api:1.1.3 restart: always environment: MODE: worker ... command: /bin/bash -c 'python /app/api/commands.py start-worker'

同样加上脚本挂载，改成：

command: /bin/bash -c '/wait-for-it.sh db:5432 -t 60 -- python /app/api/commands.py start-worker'

worker也连接Redis，如果Redis启动也慢，可以再加一个等待：

command: /bin/bash -c '/wait-for-it.sh db:5432 -t 60 -- /wait-for-it.sh redis:6379 -t 60 -- python /app/api/commands.py start-worker'

这样等两个服务都就绪后再启动worker。不过Redis启动速度比PostgreSQL快得多，通常只等数据库就够了。

4.4 重新部署并验证

配置文件改完之后，执行docker compose down，把当前的容器停掉。这里不用加-v，因为我们没有用数据库持久化卷做实验，直接关掉再重新起：

docker compose down docker compose up -d

这次启动后，api容器的日志会先显示等待信息。我实测时日志里会出现：

wait-for-it.sh: waiting for db:5432 with a timeout of 60 seconds wait-for-it.sh: db:5432 is available after 15 seconds wait-for-it.sh: executing python /app/api/commands.py start-api

看到“is available”和“executing”这两行，就说明等待生效了。等待时间就是我那次数据库初始化的实际耗时，15秒左右，完全可以在60秒超时内完成。

过一会再验证：

docker compose ps

api和worker应该都变成了Up状态，不再反复重启。浏览器访问服务器IP，就能看到Dify的安装页面了。首次访问会要求设置管理员邮箱和密码，填完提交就正式进入系统。到这一步，PostgreSQL初始化失败的问题已经彻底解决。

5. 后续维护：其他需要留心的坑

5.1 常见问题速查表

解决了数据库初始化问题之后，Dify部署还有其他几个高频坑，我顺手整理成一张速查表，都是我自己实测或者帮别人排查时遇到的典型场景：

这张表解决不了所有问题，但基本覆盖了我碰到的80%的部署场景。如果你遇到的报错不在表里，记住一个通用排查思路：先docker compose ps看哪个容器异常，再docker compose logs <服务名>看具体报错，最后根据报错关键字去搜索，比盲目重启高效得多。

5.2 部署后的初始化配置

数据库问题解决、成功进入Dify安装页之后，还有几步初始化配置要做，否则Dify只是个空壳。

首先是创建管理员账号。首次访问安装页会要求设置管理员邮箱、名称和密码，这一步完成后才会真正进入Dify主界面。

接着是配置模型供应商。Dify本身不带模型，需要接入外部模型服务。最省事的方案是在“设置-模型供应商”里添加OpenAI兼容的API地址。如果你像我一样希望完全本地化，可以配合Ollama本地部署，把DeepSeek这类开源模型跑在本机，然后在Dify里填写Ollama的接口地址，比如http://host.docker.internal:11434，模型选deepseek-r1之类的名字就行。

再往后就是创建应用、知识库，走Dify的工作流和知识库流水线功能了。知识库需要配置Embedding模型，本地环境推荐用Ollama里的bge-m3或者nomic-embed-text，效果不错而且不依赖外网。

5.3 我的一些部署经验

这篇博文写到这里，主要的技术内容已经讲完了，我再说几条实战中沉淀下来的经验，都是踩坑踩出来的。

固定版本号而不是用latest。Dify更新很快，我现在部署都会在.env或者镜像地址里把版本固定下来，比如langgenius/dify-api:1.1.3。用latest虽然能拿到最新功能，但升级可能带来数据库结构变化，一个不留神就起不来了。

升级前先备份volumes目录。Dify的数据都在./volumes下面，特别是PostgreSQL的数据目录和app/storage里上传的文件。升级时先把整个volumes目录复制一份，万一新版本迁移出问题，还能回滚。这个习惯帮我避免过太多次悲剧。

wait-for-it.sh这个脚本留着别删。哪怕你觉得这次部署完了用不上了，下次重新部署、迁移服务器、恢复备份，大概率还会遇到同样的时序问题。我现在每台部署Dify的服务器上，docker目录里都会常驻这个脚本，以备不时之需。

最后再分享一个小技巧：docker compose up -d之后别急着看网页，先执行docker compose logs -f api，盯着api日志看几秒钟。如果看到“is available”然后又正常进入start-api流程，说明整个链路是通的，这时候再刷新页面，基本已经能登录了。这个习惯比反复刷新浏览器强一百倍，能帮你第一时间发现是哪个环节卡住了。