Dify Docker 调试实录：macOS 外置硬盘的血泪一课

> 步子哥 @ 2026-06-17　|　共耗时约 2 小时　|　12 个服务从全崩到全绿

---

一、缘起

Dify 是步子哥的日常底座。某日登录，曰密码不对。清缓存，曰数据库坏了。再清，曰彻底起不来。三个来回，docker compose up 之后——PostgreSQL 无限重启，API 刚起就挂，Redis 拒绝写操作，Weaviate 翻白眼，Sandbox 找不到配置文件。

若以医理喻之：初为头疼（密码不对），误服泻药（清缓存），进而五脏俱损（全删 volumes），终至气若游丝（全线崩溃）。

---

二、诊断纪实

第一刀：清创（清理旧数据）

rm -rf ./docker/volumes/

685MB 历史数据一刀切。却遇一怪事——certbot/conf/live 目录删不动。细查之下，竟是 ACL 作祟：

$ ls -lae certbot/conf/live
 0: user:linmiao deny delete

一条 ACL 规则 user:linmiao deny delete，连属主自己都不许删，只得以 chmod -a 破之。

第二刀：PostgreSQL 的无声抗拒

清理完毕，重生成配置，docker compose up。PostgreSQL 日志循环输出：

mkdir: can't create directory '/var/lib/postgresql/data/pgdata': No such file or directory

怪哉。目录我刚建好，宿主机 ls 看得清清楚楚，Docker 却说「No such file」。

> 类比：好比你在房间 A 放了一个箱子（宿主机建目录），镜子里（Docker 容器内）却照不出来。不是箱子不存在，是镜子有问题。

这就是Docker Desktop macOS + 外部存储的经典 bind mount 缺陷。Docker Desktop 在 macOS 上跑在一个 Linux 虚拟机里，宿主机目录通过文件共享协议（gRPC FUSE / VirtioFS）映射进去。外置 SSD 的 /Volumes/SSD 路径，在 VM 内部变成了 /host_mnt/Volumes/SSD——这一层翻译，时不时掉链子。

解法：放弃 bind mount，改用 Docker 命名卷。

# 之前
- ./volumes/db/data:/var/lib/postgresql/data

# 之后
- dify_postgres_data:/var/lib/postgresql/data

Docker 命名卷由 Docker 自己管理，不经过 macOS→Linux 的文件系统翻译层，自然不会出现「宿主看得见、容器看不见」的灵异事件。

第三刀：Secret Key 加载 Bug

PostgreSQL 通了，API 又挂。日志：

opendal.exceptions.NotFound: NotFound (persistent) at read
  path: .dify_secret_key

Dify 使用 OpenDAL 作为存储抽象层，启动时找不到 .dify_secret_key 就会生成一个。但——代码里写的异常捕获是：

try:
    persisted_key = storage.load_once(filename)
except FileNotFoundError:  # ← 只捕获 Python 标准异常
    pass                    #    但 OpenDAL 抛的是自己的 NotFound！

opendal.exceptions.NotFound 不是 FileNotFoundError 的子类，异常径直穿透 catch 块，导致整个 Flask 应用初始化失败。

解法：手动在 volumes/app/storage/ 下创建 .dify_secret_key。

> 这本质是 Dify 代码的 bug，异常类型不匹配。不过我们此时只为让系统跑起来，先治标。

第四刀：管理员注册报错

Web 界面能看了，Install 页面能打开了，填完邮箱密码一点保存——又报错：

opendal.exceptions.NotFound: NotFound (persistent) at write
  path: privkeys/d3d7c732-.../private.pem

同样的 OpenDAL 错误，不过是写操作。API 容器以 UID 1001 运行，而 volumes/app/storage/ 宿主机权限是 linmiao:staff (755)。「others」只有 r-x，写不了。

解法：chmod 777 volumes/app/storage/ 加重启 API 容器（因为 bind mount 在容器创建时冻结了初始状态，不重启不会生效）。

第五刀：Redis 的沉默罢工

管理员注册终于过了，登进去一看——API 和 Worker 又双叒重启了。Redis 日志：

Failed opening the RDB file dump.rdb (in server root dir /data) for saving: No such file or directory
MISCONF Redis is configured to save RDB snapshots, but it is currently not able to persist on disk.

Redis 尝试后台写 dump.rdb，又是 bind mount 写不进去。更致命的是——stop-writes-on-bgsave-error 默认开启，一旦 RDB 写失败，Redis 拒绝所有写命令。

这一波连锁反应触目惊心：

• Plugin Daemon 集群选举依赖 Redis 写入 → 选举失败，无限重试
• API / Worker 依赖 Redis 缓存 → 写操作被拒 → 进程崩溃重启

redis:         ./volumes/redis/data     → dify_redis_data
plugin_daemon: ./volumes/plugin_daemon  → dify_plugin_daemon_storage

---

三、最终架构

经过三轮调试，docker-compose.yaml 中有写入需求的卷全部从 bind mount 改为命名卷：

---

四、经验谈

铁律一：Docker Desktop macOS 不要在外置硬盘上用 bind mount 做写入

这不是 bug，是架构决定的。Docker Desktop 通过 Linux VM 访问 macOS 文件系统，多了一层翻译。读通常还凑合，写——特别是 initdb、BGSAVE、bolt_db 这类需要原子操作的写——随时扑街。

如果服务需要写入持久化数据，一律用命名卷（named volume）。 配置文件、只读资源用 bind mount 无妨。

铁律二：容器重启 ≠ 重建

Docker bind mount 在容器创建时冻结文件系统视图。你在宿主机上改了权限、加了文件，运行中的容器不一定看得见。docker compose restart 可以刷新，docker compose down && up 更彻底。

铁律三：日志是沉默的证人

每次故障，docker logs 都有明确线索。PostgreSQL 的 mkdir 失败、Redis 的 Failed opening the RDB file、API 的 opendal.exceptions.NotFound——每条日志都在喊「bind mount 写不进去」，只是换着姿势喊。

铁律四：一条链断，全线崩溃

Redis 写不进 → 禁写命令 → Plugin Daemon 选举失败 → API/Worker 依赖 Redis 崩。现代微服务架构中，一条共享依赖的故障会像多米诺骨牌一样传导。修的时候要从最底层（存储层）往上修，不要盯着最顶上的症状打地鼠。

铁律五：别怕脏，怕不彻底

步子哥第一次清理时，留了部分历史数据；第二次又留了一些；越留越脏。最终 rm -rf volumes/ 一了百了，反而最快。重置就要彻底——半吊子的清理，比不清理还折腾人。

---

五、余语

此次调试，本质是 Docker Desktop macOS 的文件系统隔离问题在一个外部 SSD 上被集中引爆。从 PostgreSQL 到 Weaviate 到 Redis 到 Plugin Daemon，六个服务逐一中招，症状各异，病根归一。

中医曰「异病同治」，西医曰「root cause analysis」，步子哥曰「先看日志再动手」。与诸君共勉。