Dify 本地部署最容易卡住的地方，通常不是启动命令，而是版本、端口、密钥和数据目录。本篇完成一个明确任务：在独立测试环境安装 Dify，建立管理员账号，并用一份虚构活动简报验证首个 AI 应用。适合有基础终端操作经验的个人和小团队。

本文按官方 Docker Compose 文档整理，命令与输出属于操作说明和验收预期，不代表本站已替读者在其服务器亲测部署。Dify 是应用平台，部署它不会自动获得可免费使用的大模型；调用模型仍需对应服务或自行部署的推理端点。

一、先准备独立测试环境

官方最低硬件条件为 2 核 CPU、4 GiB 内存；这只是起步条件，不能据此承诺多人使用性能。macOS 的 Docker Desktop 虚拟机按文档至少分配 2 个虚拟 CPU、8 GiB 内存。Windows 使用 WSL 2 时，把源码和容器数据放在 Linux 文件系统，避免直接在 Windows 挂载盘反复读写。

准备 Docker、Docker Compose 2.35.0 或更高版本、Git 和 OpenSSL，并确认 Docker 服务正在运行。不同发行版安装 Docker 的步骤不同，应从 Docker 官方安装文档进入，不把网上的一键脚本直接复制到生产机器执行。

docker version
docker compose version
git --version
openssl version

逐项查看输出。Docker 如果只有客户端信息而无法连接服务端，应先解决权限或 Docker daemon 问题。磁盘还要容纳镜像、数据库、上传文件和备份，不能只看源码大小。若服务器正在运行博客、宝塔或其他业务，优先使用单独测试机器，不抢占现有 80/443 端口。

Dify 从固定版本、私有配置到容器及应用验收的部署流程示意

上图为原创部署示意，展示检查顺序，不是 Dify 界面截图。

二、固定发行版，再创建配置

  1. 打开文末的官方 Releases，选择正式发行版，阅读对应升级说明。不要把滚动更新的 main 分支当成固定版本。
  2. 将下面的 RELEASE_TAG 替换为 Releases 页面显示的真实 tag。不要把 RELEASE_TAG 占位符当成真实版本运行；不同版本的配置模板可能变化。
git clone --branch RELEASE_TAG --depth 1 https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
openssl rand -hex 32
  1. 用文本编辑器打开 .env，将上一步生成的随机值写入 DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN。当前官方文档明确要求 Agent 后端与本地沙箱使用这一共享令牌。
  2. 检查端口。默认 HTTP 端口是 80。已有服务占用时，在 .env 设置例如 EXPOSE_NGINX_PORT=8088，后续访问地址相应带上 :8088。这只是示例端口，仍须确认本机未占用。

`.env` 属于私有配置，不能上传公开仓库或展示在教程截图里。不要直接覆盖已有部署的 .env，本段只适用于第一次安装。生产机器还需要按后文检查项替换开发凭据，不能启动后就直接向所有人开放。

三、启动后，区分正常退出与服务异常

docker compose config --quiet
docker compose up -d
docker compose ps --all

第一条检查 Compose 配置能否解析，不等于检查密钥有效或模型可用。第二条拉取并启动服务，耗时受网络和镜像体积影响。第三条查看容器状态：长期运行的服务应显示 Up 或 healthy；init_permissions 是一次性权限初始化任务，完成后显示 Exited (0) 属于正常状态，不能把所有 Exited 一概认定为失败。

如某个服务持续重启，先从 docker compose ps --all 找到实际服务名，再查看它的日志。例如检查 Nginx：

docker compose logs --tail=100 nginx

日志可能包含内部路径或连接信息，对外求助前先脱敏。不要用删除 volumes 的方式碰运气修复，其中可能已有数据库和上传文件。

四、创建管理员并连接模型

  1. 本机部署访问 http://localhost/install。使用示例 8088 端口时访问 http://localhost:8088/install；远程测试则换成服务器地址和实际端口。
  2. 按初始化页面创建管理员账号。先限制测试环境访问来源，再进行账号初始化，避免把无人管理的安装页长期公开。
  3. 登录后，在工作区设置中找到模型供应商配置。选择你已有可用凭据的供应商，按其说明安装必要的供应商插件并填写凭据、端点和模型。具体界面文字随版本可能调整，以本次发行版实际界面为准。
  4. 发起一次短请求。网页能打开只是 Web 服务可用；只有模型请求成功，才能说明应用具备完成 AI 任务的基础条件。余额、区域、访问权限和端点类型必须与供应商账号一致。

自行部署的模型同样要提供 Dify 可访问的推理服务。容器里的 localhost 指向容器自身，不一定是宿主机；不能把宿主机地址照抄进去而不检查网络连通性。此处不额外部署模型，先用已开通的服务完成最小闭环。

五、实际任务：把活动简报整理成待办

在应用创建入口选择基础对话应用，起名“活动简报助手”，选择刚刚验证可用的模型。第一次不要叠加知识库、联网搜索和自动执行工具，先验证输入到输出的链路。

将下面文字作为应用指令，再将示例简报作为测试输入。它们都是非敏感虚构数据。

你是项目记录助手。只依据用户提供的活动简报整理待办。
输出表格：事项｜负责人｜截止时间｜依据原句。
未给出的负责人或时间填写“待确认”，不得自行推断。
最后单独列出需要人工确认的问题。
周四举行线上分享。小林负责海报，周二前提交。
小周整理报名表，截止时间尚未确定。
直播彩排需要安排，负责人还没确定。

预期检查点：海报负责人是小林，时间是周二；报名表负责人是小周，时间应为待确认；彩排负责人和时间都应待确认。若输出自行添加具体日期、主持人或预算，就不合格。这里展示的是验收标准，不是声称某模型一定给出的实际结果。

在预览区先测通，再按发布入口保存应用。将同一份输入重复测试，并补充一份故意缺失信息的简报。记录模型名称、提示词和修改原因，后续才有依据比较调整效果。

Dify 首次应用验收分为网页、容器、模型和任务四层的检查示意

上图是验收示意。四层检查都通过，才算完成本次练习。

六、从测试到落地，还要补哪些配置

  1. 访问入口：应检查的内容：HTTPS、反向代理、限定访问来源；容易忽略的问题：仅开放端口并不等于具备安全入口。
  2. 数据库与 Redis：应检查的内容：更换 DB_PASSWORD、REDIS_PASSWORD；容易忽略的问题：初始化后数据库密码需先在数据库端修改。
  3. 代码沙箱：应检查的内容：SANDBOX_API_KEY 与 CODE_EXECUTION_API_KEY 匹配；容易忽略的问题：只改一侧会导致调用失败。
  4. 插件与 Agent：应检查的内容：按官方文档分别生成所需密钥；容易忽略的问题：不同配置项不能随意共用同一个字符串。
  5. 数据与恢复：应检查的内容：配置文件、持久化目录、命名卷均有备份；容易忽略的问题：只备份 Git 源码无法恢复业务数据。

采用默认 Weaviate 时，还应按官方说明配置其 API key 并关闭匿名访问。SECRET_KEY 若由初次启动生成，应保留已有值；随意更换会影响旧令牌和文件链接。完整凭据清单以文末 Secure the Deployment 为准，表格只是落地核对入口。

配置变化后一般运行 docker compose up -d 重新创建受影响容器，单独 restart 不会让容器获得新的环境变量。切换数据库或向量库也不会自动迁移原数据，不能把修改变量当作迁移方案。

七、常见问题与停止方法

  1. 浏览器打不开：先检查容器、实际端口和地址，再检查防火墙、反向代理。若应用仅供自己测试，不应靠向全网放开所有端口解决。
  2. 页面正常，模型报错：核对供应商凭据、端点、模型可用范围、余额以及容器对外网络，避免反复重装 Dify。
  3. 配置改了没有生效：检查是否改错部署目录、变量优先级，以及是否执行了 up -d。官方新版本存在服务级 .env 文件，不能把所有变量都凭印象塞进同一文件。
  4. 暂时不用：在原部署目录运行 docker compose stop。后续用 docker compose up -d 启动；不要额外附带删除数据卷的参数。

本次交付应保留一份部署记录：发行 tag、主机资源、实际端口、配置备份位置、模型供应商、测试样例和验收结论。Dify 的许可证有额外条件，多租户服务、前端标识等场景须阅读对应版本 LICENSE，不能仅看到 Apache 字样就认定所有商业方式都无限制。

官方资料