Dify 安装与部署

二、安装与部署

Dify 有两条落地路径：Docker Compose 自托管，适合需要数据私有、要接内网系统的团队；官方云服务版，适合想先验证效果、暂时不想承担运维的团队。两者功能主体一致，主要差别在运维责任与配额计费。

方式一：Docker Compose 自托管

前置条件：一台能出网的 Linux 主机，装好 Docker Engine 与 Docker Compose v2；规格上建议至少 2 核 4G 起步，知识库文档量大或并发高时应按实测扩容。部署步骤：

# 1. 拉取代码
git clone https://github.com/langgenius/dify.git
cd dify/docker

# 2. 生成本地环境变量文件
cp .env.example .env

# 3. 启动全部服务，首次会拉取镜像，耗时较长
docker compose up -d

# 4. 查看容器状态，等到 api 与 web 均为运行状态
docker compose ps

# 5. 跟踪初始化日志，确认数据库迁移执行完毕
docker compose logs -f api

启动完成后，浏览器访问 http://<服务器IP>/install 设置初始管理员的邮箱与密码，这一步只能做一次，做完后该页面会自动关闭。默认由 Nginx 暴露 80 端口；如果 80 被占用，改 .env 里的 EXPOSE_NGINX_PORT（以及按需调整 EXPOSE_NGINX_SSL_PORT）后执行 docker compose up -d 重建。API 服务与插件守护进程另有各自端口，除非要直连调试，否则对外只暴露 Nginx 即可。

常用环境变量都写在 docker/.env 里，重点几个：

常见报错与排查：

• 端口被占用：报 bind: address already in use。用 ss -lntp | grep :80 找到占用进程，要么停掉它，要么改 EXPOSE_NGINX_PORT 换端口后重建。
• 镜像拉取失败：报 pull access denied，或长时间卡在 Pulling。国内网络环境需要给 Docker 配置镜像加速，或在能出网的机器上先执行 docker compose pull 再把镜像分发过去。
• 数据库未就绪导致 api 反复重启：docker compose logs -f api 里看到连接数据库被拒。先看 docker compose logs -f db 确认 Postgres 是否真的起来了，首次启动初始化数据目录较慢，等它就绪后执行 docker compose restart api。
• 迁移失败：日志里出现数据库迁移相关报错，通常是历史版本跨度过大。按官方升级说明逐版本升级，不要从很老的版本直接跳到最新版。
• 页面能打开但接口 502：多数是 api 容器没起来，或反向代理指向的服务名与端口被改错。先用 docker compose ps 确认容器状态，再核对代理配置。
• 上传文件后无法解析：检查存储相关配置与数据卷是否可写，容器重启后文件丢失往往是卷没挂上。

方式二：云服务版

1. 打开官方云服务站点注册账号，支持邮箱或第三方账号登录，完成邮箱验证。
2. 首次登录会引导创建工作区（Workspace）：填写工作区名称，创建者自动成为该工作区管理员。
3. 在「设置」的成员管理里邀请同事，按角色分配权限。成员数、应用数、消息条数、知识库存储等均受套餐配额限制。
4. 在「设置」的模型供应商里填入模型厂商的 API Key。云服务版不会替你支付模型费用，模型调用费仍由你自己的 Key 结算。
5. 需要对外提供接口时，在应用的访问 API 页面生成 API Key，把请求打到云服务提供的接口域名（形如 https://api.dify.ai/v1）。

套餐档位与配额以官网定价页为准。如果所在行业对数据合规有硬要求（金融、医疗、政企），云服务版通常不是首选，应走自托管并自行完成安全加固。

升级与备份

# 升级前先备份数据库（在 dify/docker 目录执行）
docker compose exec db pg_dump -U postgres -d dify > dify_backup.sql

# 备份关键数据卷，至少覆盖向量库、上传文件与插件数据
docker run --rm -v dify_weaviate_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/weaviate_data.tar.gz -C /data .

# 拉取新版本并重建
docker compose down
git pull origin main
docker compose pull
docker compose up -d

# 观察迁移是否成功
docker compose logs -f api

要点：升级前必须备份数据库与数据卷；docker compose down 只停容器不删数据卷，不要随手加 -v 参数。升级后数据库迁移由 api 容器在启动时自动执行，务必看日志确认没有报错再放流量。生产环境建议锁定官方 release 标签而不是跟随主干分支，回滚的前提是事前有备份，没有备份的回滚等于重装。数据卷的具体名称以 docker volume ls 的实际输出为准。