WSL2环境下Docker Compose卷挂载权限报错问题

DevOps 小满

2026-8-26

问题根因

这个权限问题是WSL2和MacOS的Docker Desktop挂载路径权限映射逻辑不一致导致的：

MacOS的Docker Desktop挂载宿主目录时，会自动将文件所有者UID/GID映射为容器内运行用户的UID/GID，因此你写死UID为999的appuser可以正常读取挂载进来的.config目录
WSL2环境下，如果你~解析到的是Windows侧的用户目录（即/mnt/c/Users/[你的Windows用户名]路径，属于drvfs跨文件系统挂载），Docker不会自动做UID映射，挂载进容器的目录所有者默认是root，UID为999的appuser没有对应目录/文件的读权限，就会抛出Errno 13权限拒绝错误
你用./开头的相对路径挂载正常，是因为项目目录存放在WSL原生ext4文件系统中，POSIX权限模型兼容，挂载后权限继承逻辑正常

推荐解决方案（跨平台零配置兼容）

最稳妥的方案是绕开家目录整目录挂载的权限坑，单独挂载凭据文件并显式指定凭据路径，不需要修改用户UID，也不需要调整WSL全局配置，Mac和Windows WSL2环境可直接通用：

修改主应用Dockerfile，在切换到appuser用户前，创建一个全局可读的凭据存放目录：

# 放在 USER appuser 指令之前即可
RUN mkdir -p /opt/gcloud && chmod 755 /opt/gcloud

修改docker-compose.yaml配置，删除原有的整目录.config挂载规则，改为单独挂载凭据文件，同时通过环境变量显式指定Google Cloud凭据路径：

services:
  # 替换为你自己的服务名
  app:
    # 原有build、image等配置保留
    environment:
      # 新增这行，指定凭据路径
      - GOOGLE_APPLICATION_CREDENTIALS=/opt/gcloud/application_default_credentials.json
    volumes:
      # 删除原来的 - ~/.config:/home/appuser/.config 行，替换为下面的单文件挂载
      - ~/.config/gcloud/application_default_credentials.json:/opt/gcloud/application_default_credentials.json:ro
      # 原有其他卷挂载保留
      - ./app:/home/appuser/app
      - ./tests:/home/appuser/tests

注意：挂载参数末尾的:ro是只读标记，可避免容器误修改宿主本地的凭据文件，安全性更高。
改完重新构建镜像启动即可，这个方案不依赖宿主目录的权限映射逻辑，单文件挂载在Mac和WSL2环境下都可以正常识别权限。

备选方案（保留整目录挂载逻辑）

如果必须挂载整个~/.config目录，可以通过动态对齐容器内用户和宿主用户UID的方式解决权限问题：

修改Dockerfile，将appuser的UID改为可通过构建参数传入，不写死999：

FROM python:3.8.13-buster as base

ARG HOME=/home/appuser
ARG APP_UID=999
ENV PIP_NO_CACHE_DIR false

# 用传入的UID/GID创建用户
RUN groupadd -g ${APP_UID} appuser && useradd -r -u ${APP_UID} -g appuser appuser
RUN apt-get update -y && apt-get install ffmpeg -y && pip install --upgrade pip

WORKDIR ${HOME}
RUN chown -R appuser:appuser ${HOME}

USER appuser
ENV PYTHONDONTWRITEBYTECODE True

COPY requirements.txt ./

RUN pip install -r requirements.txt

启动容器时自动传入当前宿主用户的UID作为构建参数，在项目根目录执行以下命令启动即可：

CURRENT_UID=$(id -u) docker compose up --build

这个方案可以让容器内appuser的UID和宿主用户UID完全一致，挂载进来的目录自然拥有对应权限，但需要每个开发人员启动时注入环境变量，团队协作场景下维护成本更高。

避坑提示

不要为了快速解决权限直接将容器运行用户改为root，违反生产环境最小权限原则，存在安全风险
WSL2环境下尽量将项目文件、需要挂载的配置文件存放在WSL原生ext4分区（即/home/[你的WSL用户名]/路径下），不要存放在/mnt/c/开头的Windows挂载分区，drvfs文件系统除了权限问题还会存在IO性能差、文件变更监听失效等问题
单文件挂载凭据比整目录挂载.config更安全，可避免容器内进程误访问本地gcloud的其他敏感配置

内容的提问来源于stack exchange，提问作者Dom.MB