部署 Dify：保存配置并验证完整问答链路

1. 先检查容量与 Compose 版本#

Dify 包含 Web、API、后台任务、数据库、缓存、向量检索和沙箱等组件，比单个聊天页面复杂。官方当前最低要求为 2 核 CPU、4 GiB 内存，Docker Compose 至少 2.24；实际知识库规模和并发增加时还需要更多资源。

free -h
df -h
docker version
docker compose version

先准备独立域名、HTTPS、备份位置和模型 API 账户。部署 Dify 不等于在 VPS 本地运行模型，接外部模型时请求与相关资料会发送到所选服务。

2. 获取明确版本的官方代码#

从 Dify 官方 Releases 选择稳定版本，阅读该版本部署和升级说明。不要依赖“自动查询最新版本”的命令返回值未检查就继续安装。

git clone --branch 实际版本标签 https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env

版本标签是占位符，必须换成 Releases 中的实际 tag。已有实例升级时不要覆盖原 .env；比较新模板中增加的变量，再合并自己的值。

3. 配置访问地址、秘密和持久数据#

检查 .env 中公开 URL、端口、数据库和密钥相关配置，按当前版本说明替换默认秘密。已有反向代理占用 80/443 时，调整 Dify 的入口端口或接入方式，不停止无关网站。

确认 volumes 与数据目录会持久保存数据库、上传、向量数据及插件相关状态。数据库和 Redis 不需直接公开到互联网；沙箱按官方网络与权限设计保留，不能为了启动方便随意移除隔离。

4. 启动并分清常驻服务与一次性任务#

docker compose config --quiet
docker compose up -d
docker compose ps -a
docker compose logs --tail 100

当前官方栈有多个核心与依赖服务，名称和数量会随版本变化。init_permissions 这类一次性权限初始化任务成功退出是正常现象，不能看到 Exited 就反复重启；常驻服务应处于正常运行或健康状态。

容器启动不代表应用初始化完成。通过受控的 HTTPS 域名访问 /install，创建管理员，再登录控制台。正式公开前确认初始化入口已经完成账户设置。

5. 接入模型并完成第一条问答#

在设置中打开模型供应商，选择官方支持的集成或经过核对的插件，填写自己的 API Key 与当前模型名。先测试一个对话模型，再配置知识库需要的 embedding 模型；对话模型和向量模型用途不同。

创建一个简单聊天应用，写清楚回答范围，发送一条无敏感信息的问题。查看模型调用、响应与费用，确认 Base URL、模型名和权限正确。不要把旧教程中的模型名称当成永久可用值。

6. 知识库从小文档开始验证#

先上传一份自己编写的短文档，检查分段、索引状态与检索结果，再提出答案确实存在于文档中的问题。查看是否检索到正确片段，以及答案是否给出可核对出处。

调整分段大小、重叠和召回参数时，每次只改一项并复测。向量模型更换后可能需要重新索引，不能假设旧向量与新模型兼容。上传私人文档前确认数据处理与模型服务范围。

7. 发布、备份与升级一起规划#

应用发布前配置访问权限和用量限制，验证外部访问、上传、后台索引与插件调用。备份数据库、文件存储、向量数据、配置和必要秘密，并在测试环境恢复一次。

升级按目标版本官方指引进行，新版本可能增加服务，不能永远沿用旧 compose 文件。失败时先看 API、worker、数据库和插件日志，再针对修复。相关步骤见Compose 管理与模型 API。