适用场景
这套方案适合希望在自有服务器或内网环境中运行 Dify 的团队与个人。通过 Docker Compose 把 API、Worker、Web 前端以及 PostgreSQL、Redis、向量库等依赖服务一起拉起，数据留在自己手里，方便做权限控制、网络隔离和后续二次开发。只要机器能装 Docker，就可以按下面步骤走通。
环境与前置条件
- 操作系统：常见 Linux 发行版均可，如 Ubuntu、Debian、CentOS。具体支持列表以官方文档当前版本为准。
- 运行时：Docker Engine 与 Docker Compose v2 插件。
docker compose version能正常输出即可。 - 内存：建议 8GB 以上。如果同时跑本地向量库和模型服务，建议 16GB 以上。
- 磁盘：建议 40GB 以上可用空间，用于镜像、数据库和上传文件。
- 网络：服务器需要能访问外网拉取镜像；对外提供服务的端口如 80、443 或自定义端口需要放行。
- 可选：一个已解析到服务器的域名，用于配置 HTTPS。
分步骤部署
步骤 1：安装 Docker 与 Compose 插件
如果机器还没装 Docker，可以用官方脚本安装：
```bash
curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
```
执行完最后一条后，退出当前 SSH 会话重新登录，或者执行 newgrp docker 让用户组生效。验证：
```bash
docker version
docker compose version
```
两条命令都能输出版本信息，说明安装成功。具体版本要求以官方文档当前版本为准。
步骤 2：获取 Dify 代码
```bash
git clone https://github.com/langgenius/dify.git
cd dify/docker
```
如果提示 git: command not found，先用系统包管理器安装 git，例如 sudo apt install git。进入 docker 目录后，你会看到 docker-compose.yaml、.env.example 等文件。
步骤 3：配置 .env 文件
复制一份环境变量模板：
```bash
cp .env.example .env
```
然后编辑 .env，重点改这几项：
1. SECRET_KEY：用于加密会话等，必须换成随机值。可以用下面的命令生成：
```bash
openssl rand -base64 42
```
把输出内容填到 SECRET_KEY= 后面。
2. 数据库密码：确保 DB_PASSWORD 和 POSTGRES_PASSWORD 的值一致。不一致会导致 API 连不上数据库。
3. 端口：默认 EXPOSE_NGINX_PORT=80。如果宿主机 80 端口已被占用，改成 8080 或其他空闲端口，后面反向代理会用到。
4. 初始管理员：部分版本支持在 .env 中设置初始管理员邮箱和密码，具体变量名以 .env.example 里的注释为准。如果没有，首次访问页面时按提示创建即可。
步骤 4：启动 Dify 与依赖服务
```bash
docker compose up -d
```
这条命令会拉取镜像并启动 PostgreSQL、Redis、向量库、API、Worker、Web、Nginx 等容器。首次执行需要几分钟，取决于网络速度。看到大量 Started 或 Running 字样即表示命令执行完毕。成功标志是：
```bash
docker compose ps
```
输出的 State 列显示 running 或 healthy。如果某个容器反复重启，先看日志：
```bash
docker compose logs -f api
```
步骤 5：配置反向代理
Dify 自带 Nginx 容器，默认监听 EXPOSE_NGINX_PORT。如果想让外部通过域名访问，可以在宿主机再装一层 Nginx 做反向代理。安装：
```bash
sudo apt install nginx
```
新建配置文件，例如 /etc/nginx/conf.d/dify.conf：
```nginx
server {
listen 80;
server_name your.domain.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
client_max_body_size 100m;
}
}
```
注意 proxy_pass 的端口要和 .env 中 EXPOSE_NGINX_PORT 一致。如果 Dify 端口改成了 8080，这里就写 8080。检查并重载：
```bash
sudo nginx -t
sudo systemctl reload nginx
```
需要 HTTPS 时，可以用 certbot 申请证书并自动修改 Nginx 配置，具体步骤以官方文档当前版本为准。
验证部署是否成功
1. 容器状态：
```bash
docker compose ps
```
预期：所有服务均为 running 或 healthy，没有 restarting。
2. 本地接口：
```bash
curl -I http://127.0.0.1:8080
```
预期：返回 HTTP/1.1 200 或 HTTP/1.1 302。如果返回 Connection refused，说明容器没起来或端口不对。
3. 浏览器访问：
打开 http://你的域名 或 http://服务器IP:端口，能看到 Dify 初始化页面。按提示设置管理员账号后进入控制台，说明 Web 服务正常。
4. 查看 API 日志：
```bash
docker compose logs -f api
```
预期：日志中出现启动完成、监听端口等信息，没有持续报错。
常见报错与解决
1. 报错：Error response from daemon: Ports are not available: bind: address already in use
→ 原因：宿主机的 80 或 8080 端口已被其他程序占用，常见的是系统自带 Nginx 或 Apache。
→ 解决：修改 .env 中 EXPOSE_NGINX_PORT 为其他端口，例如 8081，然后重启：
```bash
docker compose down
docker compose up -d
```
2. 报错：sqlalchemy.exc.OperationalError: connection to server at "db" ... failed
→ 原因：数据库密码不一致，或者数据库容器还没初始化完成。
→ 解决：检查 .env 中 DB_PASSWORD 与 POSTGRES_PASSWORD 是否相同，然后重启相关服务：
```bash
docker compose restart db api worker
```
3. 报错：Error pulling image ... net/http: TLS handshake timeout
→ 原因：拉取镜像时网络超时，常出现在国内网络环境。
→ 解决：为 Docker 配置镜像加速器或代理，具体配置方式以官方文档当前版本为准。配置完成后重新拉取：
```bash
docker compose pull
docker compose up -d
```
4. 报错：initdb: error: directory "/var/lib/postgresql/data" exists but is not empty
→ 原因：数据卷里残留了旧版本或不同密码初始化的数据，与新配置冲突。
→ 解决：如果不需要旧数据，先备份再清理数据卷：
```bash
docker compose down -v
docker compose up -d
```
注意 -v 会删除数据卷，执行前确认已备份。
后续维护
- 备份：定期备份 PostgreSQL 数据、上传文件目录和
.env。可以用docker compose exec db pg_dump -U postgres dify > backup.sql导出数据库，具体用户名和库名以.env为准。文件存储通常在dify/docker/volumes下，直接打包该目录即可。 - 升级：先备份，再拉取新代码并重建容器：
```bash
cd dify
git pull
cd docker
docker compose pull
docker compose up -d --build
```
升级前建议查看官方 release notes，确认是否有数据库迁移或破坏性变更，以官方文档当前版本为准。
- 日志：用
docker compose logs -f --tail=100查看实时日志，定位问题时可以只看某个服务，例如docker compose logs api。 - 监控：用
docker stats观察容器 CPU、内存和磁盘占用。关注容器重启次数、数据库连接数和磁盘剩余空间，必要时接入 Prometheus 与 Grafana 做长期监控。