Dify v1.18.0 这两天正式发布了。
上一篇我们聊过，这一版的主角是 Agent——Agent Routing、Portable Apps、Agent 专属知识库，全是围绕 Agent 转的。
但你可能没想到，装这一版遇到的第一个坑，也是 Agent 埋的。
官方最新的 Docker Compose 文档里，多了一个以前没有的强制步骤：你必须手动生成一个 Agent Sandbox 的鉴权 Token，填进 .env，否则 agent_backend 和它的沙箱容器压根不会启动。不少人按老教程一路 up -d，回头一看 Agent 节点全灰，查半天日志才发现就少这一行。
这篇就把 v1.18.0 的安装从头到尾走一遍，新装的、老版本升级的、还有装好之后该检查什么，一次说清楚。照着做，基本不会踩坑。
本文命令基于官方文档（2026-10-23 更新，对应 v1.18.0）和 v1.18.0 Release 说明整理。
一、先看你的机器够不够格
别上来就 clone，先花十秒钟对一下配置。v1.18.0 因为多了 agent_backend 和本地沙箱，吃的资源比早期版本多一点。
硬件最低要求：
-
CPU：2 核起步 -
内存：4 GiB 起步（这是能跑起来的下限，真要带知识库和 Agent 建议 8G 往上）
软件要求：
这里有个高频翻车点：Compose 必须是 2.24.0 或更高。很多老服务器上还是 v1 的 docker-compose（带横杠那个），启动新版编排会直接报语法错。
先自查一下：
注意是 docker compose（空格），不是 docker-compose（横杠）。版本不够就先升级，别硬上。
二、全新安装：四步跑起来
第 1 步：拉取 1.18.0 的代码
官方文档给了一条"自动拉最新版"的命令，但国内网络调 GitHub API 经常抽风，拉下来一个 null 分支。装指定版本，我更推荐老老实实写明 tag：
这样拉下来的就是确定的 v1.18.0，不会被"最新版"坑。
第 2 步：生成环境配置文件
.env 是你唯一需要手动改的配置文件，所有定制都放这里。
记住一个原则：docker-compose.yaml 不要手改。这个文件是从 docker-compose-template.yaml 自动生成的，你一改，下次升级就被覆盖。所有自定义都通过 .env 搞定。
第 3 步：【1.18 重点】生成 Agent Sandbox Token
这就是开头说的那个新坑。
执行下面这条命令，生成一串随机 Token：
把输出的字符串复制下来，打开 .env，找到这一行填进去：
为什么必须配？ 因为这一版 Agent 是独立的后端服务（agent_backend），它执行代码要走本地沙箱（local_sandbox），两边通信用这个 Token 做鉴权。这个值是空的，agent_backend 和沙箱容器会直接拒绝启动——这是官方文档白纸黑字写明的。
顺手再说几个建议第一次启动前就改好的变量：
第 4 步：启动
第一次会拉一堆镜像，耐心等。国内拉得慢的，可以给 Docker 配个镜像加速器。
三、启动之后，怎么确认装成功了
看懂这一堆容器
v1.18.0 起来之后，会跑 16 个容器，第一次看到 docker compose ps 那一屏别慌，它们分三类：
7 个核心应用服务：
-
api：后端 API 主服务 -
api_websocket：WebSocket 长连接 -
worker/worker_beat：异步任务处理和定时调度 -
web：前端页面 -
plugin_daemon：插件守护进程 -
agent_backend：Agent 专用后端（这一版的重点）
8 个依赖组件：
-
db_postgres（数据库）、redis、nginx（入口） -
weaviate（默认向量库，可换） -
ssrf_proxy/agent_ssrf_proxy（网络安全代理） -
sandbox/local_sandbox（代码执行沙箱）
1 个一次性任务：
-
init_permissions：只负责初始化存储目录权限，干完就退出。
验证命令：
正常情况：所有常驻服务都是 Up 或 healthy。
特别注意：init_permissions 显示 Exited 是完全正常的，它本来就是干完活就退出，别当成报错去重启它。
打开页面，创建管理员
浏览器访问：
设置管理员邮箱、用户名、密码，然后就能登录工作台了。
想确认管理员是否已初始化，可以 curl 一下：
进来之后第一件事，去「设置 → 模型供应商」配上模型的 API Key（OpenAI、DeepSeek、通义千问都行），就可以开始建应用了。
四、老用户升级到 1.18.0：顺序千万别乱
如果你已经在跑旧版本，升级比重装讲究，核心就一句话：先停、拉代码、拉镜像、起、再迁移数据库。
标准升级流程
起完之后，数据库迁移要按顺序跑
backfill-plugin-auto-upgrade 是回填插件自动升级策略的，它依赖上一步迁移新加的字段，所以顺序不能反。如果你的版本早于 1.15.0、一直没跑过这条，升级后补跑一次即可。
还有两个升级后必做的检查
第一，比对 .env。 新版经常引入新变量（比如这次的 Agent Token），但你的 .env 是当初复制的、升级不会动它。一定要把新版的 .env.example 和你的 .env 对比一下，把新增的必填项补上：
官方仓库里有个 dify-env-sync.sh 脚本可以做单向同步（自动备份你的 .env 再加新变量），不熟命令的可以用。
第二，确认插件守护进程版本对齐。 plugin_daemon 的镜像 tag 必须和 Dify 版本锁步，版本不匹配会出现插件各种莫名报错。升级后在 UI 里确认插件都正常，再去清理 ./volumes/plugin_daemon/plugin/ 下那些日志报 record not found 的残留目录。
如果你从更早的版本跳级
几个历史改名顺手提醒，跳级升级容易撞上：
-
从 1.16 之前升： EDITION改名为DEPLOYMENT_EDITION；DIFY_AGENT_SHELLCTL_AUTH_TOKEN改名成了现在用的DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN（就是前面让你填的那个）。 -
从 1.14.x 升：模型类型枚举改过名（ text-generation→llm、embeddings→text-embedding、reranking→rerank），症状是 UI 提示"Credentials unavailable"。 -
用 Weaviate 内置向量库且跨 1.17.1 升级的：Weaviate 从 1.27 升到了 1.39，要分阶段迁移，不能跨小版本硬跳。
五、装好之后，这几个安全坑建议顺手填了
这部分官方文档不会拦着你启动，但对公网部署的实例非常重要。最近社区刚有人专门写文章提醒过，很多人升级后 .env 里还留着"全网公开的默认密钥"。
1. 换掉公开的 SECRET_KEY。
1.14.x 及更早的 .env.example 里，SECRET_KEY 是一串写死的、以 sk-9f73s3lj 开头的公开值，GitHub 历史里谁都能看到。它用来签 Cookie、JWT、文件 URL，等于你家门锁型号全网公开。
检查一下：
换新的：
注意：换密钥会让所有用户重新登录、旧文件链接失效、OAuth 插件要重新授权，挑个没人用的时间操作。1.15.0 之后这个值留空会自动生成持久化密钥，新装的同学不用管。
2. 别把端口裸奔在所有网卡上。
Linux 上 Docker 发布的端口会绕过 ufw 防火墙。建议在 .env 里把入口绑到回环地址，前面再套你自己的 HTTPS 反代或 VPN：
3. CORS 不要留 *。 把 CONSOLE_CORS_ALLOW_ORIGINS 设成你自己的控制台域名。
4. 共享主机上改掉内置数据库的默认密码（difyai123456 这些都是公开的）。改 Postgres 密码记得先进库里面改，否则 API 会连不上。
六、几个高频报错，对号入座
-
docker compose报语法错 / 不认识新指令：Compose 版本低于 2.24.0，升级 Compose。 -
Agent 节点用不了， agent_backend没起来：九成是没配DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN，回到第二步补上再up -d。 -
克隆报 Remote branch null not found：那条自动拉最新版的命令没取到 tag，直接用git clone --branch 1.18.0写明版本。 -
页面打不开 / 一直转圈：可能还在初始化，等一分钟刷新；用 docker compose logs -f api看后端日志。 -
插件报凭证失效（Credentials unavailable）：从 1.14.x 跳级上来的模型类型枚举问题，跑迁移后重新填一下模型凭证。 -
某个容器反复重启：先 docker compose logs 服务名看具体报错，内存不够（低于 4G）是常见原因。
最后
回头看，Dify 的安装这几年其实在变简单，但 v1.18.0 这一版有个微妙的变化：它开始要求你"理解 Agent 在系统里是个什么角色"了。
以前 Dify 就是一个 Web + API + 数据库的传统 Web 应用栈，复制个 .env 就能起。现在多了独立的 agent_backend、多了本地沙箱、多了鉴权 Token、多了 SSRF 代理——这套东西本质上是在为"Agent 能真正动手干活"搭一套带安全边界的运行时。安装时多敲的那一行 openssl rand，背后是 Agent 从"对话框里的大脑"变成"能执行代码的执行者"之后，必须补上的安全门禁。
所以装这一版，我的建议是：别只盯着"能不能打开页面"，重点确认 agent_backend 和沙箱是不是健康、Token 是不是配了。这两样正常，你才算真正装好了一个"Agent 版"的 Dify，而不只是又起了一套 Web 服务。
祝一次启动成功。
Dify社区群：嗨聊吧
欢迎扫码加入嗨聊吧！
