解决 OpenList v4.1.0+ Docker 部署中的目录权限报错

问题描述

在部署或升级 OpenList (v4.1.0+) 时，通过 docker-compose 启动容器失败，后台日志抛出以下错误：

Error: Current user does not have write and/or execute permissions for the ./data directory: /opt/openlist/data
错误：当前用户没有 ./data 目录的写和/或执行权限。
Exiting...

即使在 docker-compose.yml 中配置了 user: '0:0' (Root)，该错误依然存在。

---

排查过程

1. 确认环境干扰

首先排查了系统安全策略。在部分 Linux 发行版中，SELinux 可能会拦截容器对宿主机目录的访问。

• 检查命令：getenforce
• 结果：返回 Disabled，排除 SELinux 导致权限拦截的可能性。

2. 检查宿主机物理权限

通过 ls -la 观察映射到容器内的宿主机目录 ./data，发现其权限位异常：

Bash

# 实际观察到的权限
drw------- 4 root root 4096 Mar  1 16:54 data

诊断分析：

• 目录权限为 drw-------。
• 在 Linux 中，目录必须具备执行权限 (x) 才能被“进入”或访问。
• 当前目录缺少 x 位，且仅 root 可读写，导致容器内部进程（即使以 root 运行）在进行权限自检时失败。

---

解决方案

方案一：修正物理目录权限（推荐）

赋予目录及其子目录必要的读、写、执行权限：

Bash

# 赋予 755 权限（所有者可写，其他可读可执行）
sudo chmod -R 755 ./data

# 或者在开发环境下使用更宽松的权限
sudo chmod -R 777 ./data

方案二：优化 Docker Compose 配置

避免硬编码 user: '0:0'，改用环境变量 PUID/PGID 来对齐宿主机用户身份，这有助于解决文件生成后的所有权归属问题。

YAML

services:
  openlist:
    image: 'openlistteam/openlist:latest'
    container_name: openlist
    environment:
      - PUID=1000  # 对应宿主机用户的 UID
      - PGID=1000  # 对应宿主机用户的 GID
      - UMASK=022
    volumes:
      - './data:/opt/openlist/data'
    ports:
      - '5244:5244'
    restart: unless-stopped

---

总结

对于 Docker 挂载卷的权限问题，不能仅依赖容器内的 root 身份。Linux 目录的执行权限 (x) 是访问目录的门槛，如果宿主机上的挂载点权限位缺失，容器进程将无法正常初始化。

提示：如果你的数据目录位于 NTFS 或 exFAT 格式的外部驱动器上，chmod 命令可能失效，需在 mount 时指定挂载参数。