升级 Dify 后碰见“权限拒绝”报错？别急，这不是什么玄学问题。文件存储权限错误几乎是每个从旧版迁移过来的用户都会踩的坑，而且原因很清晰，修复方案也相当成熟。下面就把整个问题的来龙去脉和修复步骤捋一遍。

一、错误原因核心分析

日志里那个 opendal.exceptions.PermissionDenied (os error 13) 已经说明一切：操作系统的权限拒绝错误。结合 Dify 1.10.1-fix.1 版本的变化，根本原因其实就一条——

有三个关键佐证可以锁定问题：

• 报错上下文 service: fs 表明用的是本地文件系统存储；
• 报错路径 upload_files/xxx.pdf 正是文件上传的核心目录；
• os error 13 就是 Linux 上经典的“权限不足”错误，没有其他可能。

二、分步骤修复建议

步骤 1：停掉 Dify 服务

修文件之前先把服务停了，避免文件被占用导致修复失败。

# 进入Dify的docker目录（根据你的实际路径调整）
cd /你的dify安装目录/docker

# 停止所有服务
docker compose down

步骤 2：修复宿主机存储目录权限（核心操作）

默认情况下，Dify 的文件存储会映射到宿主机 ./volumes/app/storage。需要让容器内的 1001 用户能读写这个目录。两种方式任选：

# 方式1：直接赋权，适配非root用户（推荐）
sudo chown -R 1001:1001 ./volumes/app/storage
sudo chmod -R 755 ./volumes/app/storage  # 保证读/写/执行权限

# 方式2：如果方式1无效（比如宿主机上没有1001用户），测试环境可以放宽权限
sudo chmod -R 777 ./volumes/app/storage

步骤 3：验证容器内权限（可选，但建议走一遍）

启动 API 容器进去看一眼，确认目录权限没问题再继续。

# 临时启动API容器并进入
docker compose run --rm api bash

# 容器内检查存储目录权限
ls -ld /app/storage/upload_files

# 预期输出（所有者为1001）：
# drwxr-xr-x 2 1001 1001 4096 Dec  8 14:00 /app/storage/upload_files

# 测试写入权限（创建空文件）
touch /app/storage/upload_files/test.txt

# 无报错则权限正常，执行exit退出容器
exit

步骤 4：重启 Dify 并验证

docker compose up -d

# 查看API日志，确认没有权限错误
docker compose logs -f api

步骤 5：兜底方案——临时改用 root 用户运行

如果上面几步都试了还是报错，可以临时把容器改成 root 用户运行。不推荐生产环境这么干，但应急完全够用：

1. 修改 docker-compose.yml 中 api 服务的配置，添加 user: root：

services:
  api:
    image: langgenius/dify-api:1.10.1-fix.1
    user: root  # 新增这一行
    volumes:
      - ./volumes/app/storage:/app/storage
      # 其他配置不变

1. 重启服务：

docker compose down && docker compose up -d

三、预防措施

经验总结三条，下次升级就不会再踩同样的坑：

1. 升级前提前给存储目录赋权：sudo chown -R 1001:1001 ./volumes/app/storage；
2. 生产环境别偷懒用 777，优先适配容器默认的 1001 用户；
3. 如果自定义了存储路径（比如在 .env 里配置了 STORAGE_PATH），记得同步给自定义路径赋权。

四、验证修复效果

最后，用 DeepSeek OCR 流程随便上传一个 PDF 文件试试。看，文件正常上传了——到这里问题就彻底搞定了。