一、先说部署前的几个前提
Dify 是开源的大模型应用开发平台，常见的对话机器人、文档问答、知识库检索、智能体编排，都能直接在它上面搭起来。它的好处不在'炫'，而在于把一堆原本要自己拼的组件收拢到一套可视化平台里，省掉很多重复造轮子的活。
这次用的是 Docker Compose 一键部署，环境放在 CentOS 7/8 上。思路很直接：镜像交给 Compose 编排，数据落到本地卷，后面重启、升级、迁移都不会太折腾。适合测试环境，也能撑起轻量生产环境；前提是别把系统版本、Compose 版本和网络条件搞错。
1.1 环境要求
- 操作系统：CentOS 7.x / 8.x（x86_64 架构）
- 硬件配置：最低 2 核 4G，推荐 4 核 8G；磁盘可用空间 ≥ 20G（测试环境 10G+ 也能跑，33G 更宽松）
- 网络要求：服务器可访问外网，放行 80 端口，或改成自定义端口后同步放行
- 依赖软件：Docker Engine ≥ 20.10、Docker Compose V2（V1 不兼容高版本配置）
1.2 这套部署会起哪些服务
Dify 不是单容器应用，Compose 会把一整套核心组件一起拉起来：
- Dify Web 前端、API 服务、Worker 任务队列
- PostgreSQL：存配置、用户、对话数据
- Redis：缓存和任务加速
- Weaviate：向量数据库，支撑 RAG 检索
- SSRF Proxy、Sandbox：安全沙箱与代理
- Nginx：统一入口和反向代理
这些服务都走容器化部署，数据挂本地卷。好处是清晰，坏处是第一次起服务时要耐心等镜像拉取完。
二、先把 Docker 和 Compose 装对
Dify 这套配置对 Docker Compose V2 比较敏感。旧版 docker-compose（带短横线）经常不是'能不能用'的问题，而是'能不能顺利起起来'的问题。少走弯路的办法就是直接上 V2。
2.1 先清掉旧版本，免得互相打架
如果机器上已经有老 Docker，建议先卸掉再装：
yum remove -y docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine
rm -rf /var/lib/docker
rm -rf /etc/docker
2.2 安装 Docker Engine
- 安装依赖工具
yum install -y yum-utils device-mapper-persistent-data lvm2
- 添加 Docker 官方 YUM 源
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
- 安装 Docker
yum install -y docker-ce docker-ce-cli containerd.io
- 启动 Docker 并设置开机自启
systemctl start docker
systemctl enable docker
- 看版本确认是否装好
docker --version
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 助手，都是在这个基础上继续往下搭。