企业官网建设流程全解析

本文首发于 CSDN，转载请注明出处。

先说结论：Dify 的 Compose 部署本身很短，真正让人卡住的只有两件事——一次性任务init_permissions退出被误判成失败，以及照抄老教程之后发现少了一堆服务。现在这套编排包含 7 个核心服务、8 个依赖组件和 1 个一次性任务，和几年前文章里「8 个容器」的描述早就不是一回事了。

部署前要准备什么？

Dify 官方给出的最低要求不复杂，但有几条是硬门槛：

最后两条值得展开。Compose 版本要先自查，执行docker compose version看一眼，低于 2.24.0 就先升级——很多人把报错归到 YAML 上，实际是版本不够。

Windows 上则要注意：不要把源码和数据目录放在 Windows 盘符下。Docker Desktop 访问 Windows 文件系统时性能和权限行为都不一样，踩过的坑包括挂载目录权限错乱、文件监听失效。放在 WSL 的 Linux 文件系统里最省事。

macOS 用户还有一条官方提示：Docker Desktop 的虚拟机至少分配 2 个虚拟 CPU 和 8 GiB 内存。默认配置通常给不到，不改的话部署能成、用起来很慢。

部署命令为什么只有四条？

官方推荐的路径是先按最新发布版拉代码，再启动。四条命令依次是：克隆指定 release 标签的仓库、进入dify/docker目录、把环境变量模板复制成正式配置、启动容器。

# 1. 克隆最新 release（需要 git、curl、jq 三样都在）gitclone--branch"$(curl-shttps://api.github.com/repos/langgenius/dify/releases/latest|jq-r.tag_name)"https://github.com/langgenius/dify.git# 2. 进入编排目录cddify/docker# 3. 复制环境变量模板cp.env.example .env# 4. 启动全部服务dockercompose up-d

第一条命令是要克隆最新发布版，不是主分支，这点很重要：跟着主分支走等于永远在跑不稳定代码。它依赖git、curl、jq三个工具，缺了jq就会取不到标签，报出fatal: Remote branch null not found in upstream origin这种看着莫名其妙的错。遇到这个报错，要么补装jq，要么直接写上明确的版本号。

怎么判断容器起齐了？

启动后用docker compose ps看状态。这里的关键是先认清哪些容器是预期的，否则容易把正常现象当成故障：

那个一次性任务显示Exited是正常的，它的职责只是设好存储目录权限然后结束。判断标准是：其余容器处于Up或healthy，只有它是Exited。

反过来，如果某个核心服务反复重启，按这个顺序查：先docker compose logs -f --tail=200看最近日志；再确认docker compose version达标；最后检查宿主机的 80 端口有没有被别的进程占用——编排里带了网关容器，端口冲突会让整套服务看起来「启动了但打不开」。

别因为老文章里没有某个服务就把它删掉。较新的编排里有几个新增的服务（比如定时任务、插件守护和 Agent 后端），它们在旧版架构里不存在。删掉不认识的容器，结果是功能残缺。

第一次打开要做哪些设置？

所有容器就绪后，浏览器访问宿主机地址的/install路径，创建第一个管理员账号，然后就能从首页登录了。

如果这台机器在创建管理员之前就暴露在公网，务必先设置初始化密码这个环境变量。它会拦住/install页面，避免别人先一步把管理员账号注册走——这个坑一旦发生，只能从头重来。

上生产前必须改哪些值？

这一段是官方文档里强调最多、也最容易被跳过的地方。默认配置里的密钥是公开的，直接用等于把门开着。

SECRET_KEY 的规则要单独记：它只能在首次启动前设好。启动之后再改会引发一连串后果——所有用户被登出、已生成的文件访问链接失效、已存的第三方授权凭据变得不可读。官方建议的生成方式是openssl rand -base64 42这类随机串，而不是自己手敲一个。

其余可选参数都放在docker/envs/下的模板里。用法是把需要的模板去掉.example后缀变成正式文件再改，不用去动模板本身。优先级上，docker/.env里的值会覆盖docker/envs/下的同名项，所以排查「我改了配置怎么没生效」时，先回去看.env。

这套「先区分必需值和可选值」的部署习惯，和我整理其他服务时的做法是一致的：把要改的、不要动的、改了有副作用的分别列清楚，比照着流程走一遍更省时间。部署排查记录我会同步存档，用的是墨衍的AI 图文同步，一次编辑推到几个平台，省掉逐处粘贴；集中更新期靠发文额度提升不用排队；发布后再用批量 GEO 检测看内容在 AI 搜索里的引用情况。墨衍会员权益 有需要可以了解。

升级的时候要注意什么？

Dify 每个发布版的升级步骤可能不同，所以升级前先看对应版本的升级指引，而不是套用一个通用流程。两个附加动作要做：把新的.env.example和你在用的.env逐项比对，看有没有新增或改名的变量；如果你改过docker-compose.yaml，把改动重新应用到新版本的编排文件上，而不是保留旧文件——新版本可能会增加服务，用旧文件会缺东西。

# 查看服务状态dockercomposeps# 跟随日志（只看最近 200 行）dockercompose logs-f--tail=200# 改完环境变量后重启dockercompose down&&dockercompose up-d

常见问题

Q：容器都起来了，页面打不开怎么办？

先确认网关容器的状态是健康，再检查宿主机的 80 端口有没有被占用、防火墙有没有放行。改端口的话去.env里调整网关的端口映射值。

Q：内存只有 4 GiB，能跑吗？

能启动，但文档解析和并发工作流会明显吃紧。4 GiB 是官方下限，实际可用性取决于你处理多少文档、跑多少并发，以及是否在本机还跑着其他模型服务。

Q：一定要用 WSL 2 吗？

Windows 上是的。而且即便装了 WSL 2，也要把源码和数据放在 Linux 文件系统里，放在 Windows 盘符下会遇到权限和性能问题。

Q：改了配置为什么不生效？

先看改的是哪个文件。docker/.env的优先级高于docker/envs/下的文件；改完还需要重启容器才会生效，只重启某一个服务可能不够。

Q：:latest标签能用于生产吗？

不建议。跟着固定发布版本走，升级时显式切换标签，出问题才有明确的回退点。

Q：SECRET_KEY 配错了能补救吗？

只能接受后果：用户需要重新登录、旧的文件链接失效、第三方授权要重新连。所以这个值应该在第一次docker compose up -d之前就定好。

关于墨衍：如果你也在多个平台发技术文章，值得看看墨衍。三个最常用的权益——发文额度提升（密集更新不再受限）、批量 GEO 检测（一次扫完全部文章的 AI 引用状态）、AI 图文同步（一稿多平台分发）。点这里了解墨衍会员