Docker Compose 完整部署指南──从必备准备到服务启动、验证和故障排除

体验 Dify Enterprise 的最快方法是使用 Docker Compose 进行部署。在本文中，我们将在命令级别详细解释在一台服务器上启动所有 Dify Enterprise 服务并从浏览器访问它们的步骤。

定位：Docker Compose 非常适合 PoC、验证和培训目的。有关生产环境中的高可用性配置，请参阅 Helm Chart デプロイガイド。

1.先决条件

1.1 硬件要求

如果您要向矢量数据库输入大量数据，请提供更多磁盘和内存空间。

1.2 软件要求

Docker Compose V1（docker-compose 命令）已弃用。请使用V2（docker compose子命令格式）。

1.3 网络要求

• 拉取对 Docker Hub 或私有注册表的访问权限
• 打开端口80/443（nginx监听）
• 对于内部代理环境，设置 HTTP_PROXY / HTTPS_PROXY

# Docker のバージョン確認
docker version --format '{{.Server.Version}}'

# Docker Compose V2 の確認
docker compose version

2. 存储库克隆和目录结构

2.1 获取源码

# Dify リポジトリをクローン
git clone https://github.com/langgenius/dify.git
cd dify/docker

如果提供了企业版的私有存储库，请替换该 URL。

2.2 主目录结构

dify/docker/
├── docker-compose.yaml          # メインの Compose 定義
├── docker-compose.middleware.yaml # ミドルウェアのみの構成（開発用）
├── .env.example                 # 環境変数テンプレート
├── nginx/
│   ├── nginx.conf.template      # nginx 設定テンプレート
│   └── proxy.conf.template      # プロキシ設定テンプレート
├── volumes/                     # 永続化データの格納先
│   ├── db/                      # PostgreSQL データ
│   ├── redis/                   # Redis データ
│   └── weaviate/                # ベクトルデータベース
└── ssrf_proxy/
    └── squid.conf.template      # SSRF プロキシ設定

3.设置环境变量(.env)

3.1 复制模板

cp .env.example .env

3.2 主要设置项

.env 文件是决定 Dify 行为的最重要的配置文件。我将分以下几类进行解释。

####服务基本设置

# ── モード設定 ──
MODE=api      # api | worker（単独起動時に使用）

# ── シークレットキー ──
# 必ず変更してください。openssl rand -base64 42 などで生成
SECRET_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# ── ログレベル ──
LOG_LEVEL=INFO    # DEBUG | INFO | WARNING | ERROR

数据库连接

# ── PostgreSQL ──
DB_USERNAME=postgres
DB_PASSWORD=difyai123456    # 必ず変更してください
DB_HOST=db
DB_PORT=5432
DB_DATABASE=dify

# 接続プール
SQLALCHEMY_POOL_SIZE=30
SQLALCHEMY_MAX_OVERFLOW=10

Redis 连接

# ── Redis ──
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=difyai123456    # 必ず変更してください
REDIS_DB=0

# Celery ブローカー（Worker が使用）
CELERY_BROKER_URL=redis://:difyai123456@redis:6379/1

####向量数据库

# ── ベクトルストア ──
VECTOR_STORE=weaviate    # weaviate | qdrant | milvus | pgvector など

# Weaviate の場合
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_API_KEY=WVF5YThaHlkYwhGUSmCRgsX3tD5ngdN8pkih   # ⚠ これは .env.example のデフォルト値です。本番では必ず変更してください

存储设置

# ── ファイルストレージ ──
STORAGE_TYPE=local             # local | s3 | azure-blob | google-storage
STORAGE_LOCAL_PATH=storage     # local の場合のパス

# S3 互換ストレージの場合
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET_NAME=dify-storage
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=ap-northeast-1

nginx / 公共 URL

# ── nginx ──
NGINX_HTTPS_ENABLED=false
NGINX_PORT=80
NGINX_SSL_PORT=443

# ── サービスの公開 URL ──
# 外部からアクセスする際の URL（nginx 経由）
CONSOLE_WEB_URL=http://your-server-ip
CONSOLE_API_URL=http://your-server-ip
SERVICE_API_URL=http://your-server-ip
APP_WEB_URL=http://your-server-ip

3.3 安全注意事项

请务必更改以下默认值。

# シークレットキーの生成例
openssl rand -base64 42

4. docker-compose.yaml 中的服务配置

4.1 整体架构

graph TB
    Client[ブラウザ / API クライアント]
    Client --> nginx

    subgraph "Docker Compose ネットワーク"
        nginx[nginx<br/>リバースプロキシ<br/>:80 / :443]
        nginx --> web[web<br/>Next.js フロントエンド<br/>:3000]
        nginx --> api[api<br/>Flask API サーバー<br/>:5001]

        api --> db[(db_postgres<br/>PostgreSQL<br/>:5432)]
        api --> redis[(redis<br/>Redis<br/>:6379)]
        api --> weaviate[(weaviate<br/>ベクトル DB<br/>:8080)]
        api --> sandbox[sandbox<br/>コード実行<br/>:8194]
        api --> ssrf_proxy[ssrf_proxy<br/>Squid<br/>:3128]
        api --> plugin_daemon[plugin_daemon<br/>プラグイン実行]

        worker[worker<br/>Celery Worker]
        worker --> db
        worker --> redis
        worker --> weaviate

        worker_beat[worker_beat<br/>Celery Beat<br/>定期タスク]
        worker_beat --> redis
    end

4.2 各个服务的作用

核心服务

基础设施服务

4.3 服务之间的依赖关系

docker-compose.yaml的depends_on定义的启动顺序如下。

db, redis ← api ← nginx
db, redis ← worker
redis     ← worker_beat
           ← web ← nginx
           ← sandbox ← api
           ← ssrf_proxy ← api
weaviate  ← api, worker

重要：depends_on 只保证容器的启动顺序，不保证服务的 Ready 状态。建议使用 healthcheck 和 condition: service_healthy 的组合，因为 api 可能会在 PostgreSQL 或 Redis 完全启动之前尝试连接。

5.执行部署

5.1 启动服务

# docker ディレクトリにいることを確認
cd dify/docker

# 全サービスをバックグラウンドで起動
docker compose up -d

第一次启动时，需要几分钟时间来拉取 Docker 镜像。请根据您的线路速度稍等。

5.2 检查启动状态

# 全コンテナの状態を確認
docker compose ps

# 期待される出力例
# NAME          STATUS       PORTS
# api           Up (healthy) 5001/tcp
# worker        Up           
# worker_beat   Up           
# web           Up           3000/tcp
# db            Up (healthy) 5432/tcp
# redis         Up (healthy) 6379/tcp
# weaviate      Up           8080/tcp
# nginx         Up           0.0.0.0:80->80/tcp
# sandbox       Up           8194/tcp
# ssrf_proxy    Up           3128/tcp
# plugin_daemon Up           

确保所有容器的状态为 Up。服务显示(healthy)表示健康检查已完成。

5.3 查看日志

# 全サービスのログをリアルタイムで表示
docker compose logs -f

# 特定サービスのログのみ
docker compose logs -f api
docker compose logs -f worker

# 直近 100 行を表示
docker compose logs --tail 100 api

6.运行验证

6.1 从浏览器访问

1.在浏览器中访问http://<サーバーIP> 2. 将首次显示设置屏幕。 3. 注册管理员账户（邮箱地址、密码） 4. 登录后如果显示仪表板，则说明登录成功。

6.2 API健康检查

# API サーバーの稼働確認（Dify 1.x の標準ヘルスエンドポイント）
curl -s http://localhost/console/api/health | python3 -m json.tool

# 期待される応答
# {
#     "pong": "ok",
#     "version": "..."
# }

メモ：旧版本では /v1/health も使われていましたが、Dify 1.x では /console/api/health が標準です。デプロイ後 200 を返さない場合は、docker compose ps で api コンテナが healthy になっているか確認してください。

6.3 检查各部件的连接

# PostgreSQL への接続確認
docker compose exec db psql -U postgres -d dify -c "SELECT version();"

# Redis への接続確認
docker compose exec redis redis-cli -a difyai123456 ping
# 期待される応答: PONG

# Weaviate の稼働確認
curl -s http://localhost:8080/v1/.well-known/ready

6.4 简单测试场景

要全面检查部署是否成功，请运行以下场景：

7. 常用操作命令

7.1 停止和重新启动服务

# 全サービスを停止（データは保持）
docker compose stop

# 全サービスを停止し、コンテナとネットワークを削除（ボリュームは保持）
docker compose down

# 全サービスを停止し、ボリュームも削除（データ完全削除）
docker compose down -v

# 特定サービスの再起動
docker compose restart api
docker compose restart worker

7.2 更新

# 最新のソースを取得
git pull origin main

# 最新イメージの Pull と再起動
docker compose pull
docker compose up -d

# 特定サービスのみ更新
docker compose pull api web
docker compose up -d api web

7.3 资源监控

# コンテナごとの CPU / メモリ使用率をリアルタイム表示
docker stats

# 特定コンテナのリソース確認
docker stats api worker db redis

8. 故障排除

8.1 容器未启动

# コンテナの終了理由を確認
docker compose ps -a
docker compose logs <サービス名>

# よくある原因と対処
# 1. ポート競合 → 80 番ポートが別プロセスで使用中
sudo lsof -i :80

# 2. メモリ不足 → Docker Desktop のメモリ割り当てを確認
docker info | grep "Total Memory"

8.2 数据库连接错误

# PostgreSQL のログを確認
docker compose logs db

# 接続テスト
docker compose exec api python -c "
import psycopg2
conn = psycopg2.connect(
    host='db', port=5432,
    user='postgres', password='difyai123456',
    dbname='dify'
)
print('Connection OK')
conn.close()
"

常见原因：

• .env 的 DB_PASSWORD 与实际 PostgreSQL 密码不匹配
• API 在 PostgreSQL 初始化完成之前启动（→ docker compose restart api）

8.3 Redis连接错误

# Redis のログを確認
docker compose logs redis

# Redis への直接接続テスト
docker compose exec redis redis-cli -a difyai123456 info server

8.4 nginx 返回 502 Bad Gateway

# nginx のログを確認
docker compose logs nginx

# api / web コンテナが起動しているか確認
docker compose ps api web

# nginx の設定をテスト
docker compose exec nginx nginx -t

常见原因：

• API 或 Web 仍在启动（等待启动完成）
• .env的CONSOLE_API_URL设置不正确

8.5 Worker不处理任务

# Worker のログを確認
docker compose logs worker worker_beat

# Redis のキュー状態を確認
docker compose exec redis redis-cli -a difyai123456 llen celery

常见原因：

• 无法连接到Redis
• CELERY_BROKER_URL配置错误

8.6 磁盘空间问题

# Docker が使用しているディスク容量を確認
docker system df

# 未使用のイメージ・コンテナ・ボリュームを削除
docker system prune -f

# 未使用ボリュームの削除（注意: データが失われる可能性あり）
docker volume prune -f

9. 启用 HTTPS

我们建议在接近生产的测试环境中启用 HTTPS。

9.1 创建自签名证书（用于验证）

mkdir -p nginx/ssl

openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout nginx/ssl/server.key \
  -out nginx/ssl/server.crt \
  -subj "/CN=dify.local"

9.2 .env 更改

NGINX_HTTPS_ENABLED=true
NGINX_PORT=80
NGINX_SSL_PORT=443

# URL も https に変更
CONSOLE_WEB_URL=https://dify.local
CONSOLE_API_URL=https://dify.local
SERVICE_API_URL=https://dify.local
APP_WEB_URL=https://dify.local

9.3 重启

docker compose down
docker compose up -d

10. 服务故障的影响范围

对于运营来说，了解如果服务停止哪些功能将受到影响非常重要。

11. 迁移到生产环境

Docker Compose 非常适合验证和 PoC，但它对于生产操作有以下限制。

生产环境迁移请参考Helm Chart デプロイガイド。

总结

在本文中，我们使用以下流程解释了 Dify Enterprise 的 Docker Compose 部署。

1. 检查先决条件 – 检查硬件和软件要求
2. 克隆存储库 – 了解目录结构
3. 环境变量设置 – .env文件中各项的含义及推荐值
4. 理解服务配置 – 11个服务的角色和依赖关系
5. 启动与验证 – 从docker compose up -d到运行确认
6. 操作命令 – 停止、更新、监控等基本操作
7. 故障排除 – 常见问题及其解决步骤

在使用 Docker Compose 了解系统的整体结构后，我们建议下一步使用 Helm Charts 部署 Kubernetes。

参考资料

-Docker Compose で Dify をデプロイする - Dify 公式ドキュメント -Deploy Dify with Docker Compose - Dify Docs (EN) -Dify GitHub リポジトリ