用 Docker Compose 部署 Dify 的实操记录

2.3 安装 Docker Compose V2

Compose 直接装插件版，别再混用旧的二进制包：

yum install -y docker-compose-plugin

查看版本：

docker compose version

这里最好是 v2.20.0 及以上。版本太低，后面很容易撞上 Additional property required is not allowed 这类配置报错。

2.4 配个镜像加速，不然拉镜像会磨人

Docker Hub 在国内拉取速度不稳定，先把镜像加速配好，能省不少时间：

cat > /etc/docker/daemon.json <<EOF
{
 "registry-mirrors": [
  "https://docker.mirrors.ustc.edu.cn",
  "https://hub-mirror.c.163.com",
  "https://mirror.baidubce.com"
 ]
}
EOF

重启 Docker：

systemctl daemon-reload
systemctl restart docker

三、下载项目并准备配置

3.1 拉取 Dify 官方源码

我习惯放在 /opt 下面，后续查找和运维都省事：

cd /opt
git clone https://github.com/langgenius/dify.git
cd dify/docker

3.2 生成环境配置文件

先复制官方示例配置：

cp .env.example .env

测试环境通常不需要改太多，先跑起来再说。要是 80 端口已经被占了，就把 .env 里的 EXPOSE_NGINX_PORT 改成别的端口，比如 8080，然后把防火墙规则同步放开。

3.3 先清理一次异常网络

这一步看起来有点多余，但实际很常见。Compose 起服务时碰到残留网络，最容易报 Container cannot be connected to network endpoints 之类的错。先清掉脏东西，后面省时间：

# 停止残留容器
docker compose down
# 清理无用网络
docker network prune -f
# 清理无用镜像、缓存
docker system prune -f

四、启动 Dify 并确认状态

4.1 启动服务

进入 dify/docker 后，直接执行：

# 正确命令：docker + compose + up -d，中间要有空格
docker compose up -d

这里最容易出错的是命令写法。docker-compose 和 docker compose 不是一回事，-d 也不能乱挪位置。报 unknown shorthand flag: 'd' in -d 时，通常不是服务本身有问题，而是命令格式写歪了。

第一次启动会拉取镜像，时间通常在 3 到 10 分钟之间，取决于机器网络和镜像源速度。中途卡住不用硬扛，直接 Ctrl+C，再执行一次同样的命令就行。Compose 这件事比较'老实'，重复执行不会把数据弄乱。

4.2 看容器是不是都起来了

docker compose ps

如果状态都是 Up，说明主链路基本没问题。重点看 web、api、worker、postgres、redis、weaviate 这些服务，别只盯着前端。

4.3 看日志，别只猜

真要排障，日志比猜测管用得多：

# 查看全部服务日志
docker compose logs -f
# 单独看某个服务日志，比如 web
docker compose logs -f web

如果日志里没有明显报错，且能看到服务启动完成的提示，基本就可以进入访问阶段了。

五、访问和初始配置

5.1 打开后台

浏览器直接访问服务器 IP。如果你改了端口，就带上端口号。

5.2 注册管理员

首次启动会进入管理员注册页，按提示创建邮箱和密码即可。这里没什么花活，先把账号建起来。

5.3 后续常用动作

• 修改管理员密码和个人信息
• 创建知识库
• 配置对话应用

这一步之后，Dify 才算真正进入可用状态。前面做的那些安装和配置，本质上都是为了少踩坑。

六、几个最常见的坑

6.1 用了旧版 Docker Compose V1

原因：旧版 docker-compose 不支持高版本配置语法。docker compose 的 V2 插件版才是这套部署真正需要的。

6.2 Container cannot be connected to network endpoints

处理：

docker compose down && docker network prune -f

然后重新启动服务。

常见背景：多半是残留网络、异常容器或者上一次启动没清干净。先清理，再重来，通常比硬排查快。

6.3 启动卡住或镜像拉不下来

处理：先配 Docker 镜像加速，必要时中断后重新执行启动命令。

常见背景：网络慢、80 端口冲突、防火墙没放行，都可能让表面上的'卡住'变成实际的启动失败。

七、收个尾

这套部署里最关键的不是 Dify 本身，而是三个细节：Compose 必须用 V2、异常网络要先清、命令格式不能写错。只要这三点不踩雷，docker compose up -d 一般都能把整套服务拉起来。后面要做知识库、对话应用或者私有化 AI 助手，都是在这个基础上继续往下搭。