docker run --group-add 在 Docker Desktop 上常不生效，因其底层 Linux VM 启用 user namespaces，导致传入的 GID 被重映射（如映射为 65536+），且容器内 /etc/group 不含宿主机组名；该参数仅接受数字 GID，需配合 --user UID:GID 显式指定以匹配挂载卷权限。
docker run 启动的容器默认不继承宿主机的用户组权限，Docker Desktop（macOS/Windows）底层用的是 Linux VM（如 docker-desktop-data 卷），无法直接将宿主机用户组映射进容器。所谓“给容器添加补充用户组”，本质是控制容器内进程的 UID/GID 和 supplementary groups —— 这必须在容器启动时通过参数显式指定，而非 Docker Desktop GUI 能配置的选项。
为什么 docker run --group-add 在 Docker Desktop 上有时不生效
macOS 和 Windows 的 Docker Desktop 使用轻量级 Linux VM 运行容器，但该 VM 的内核默认启用 user_namespaces（尤其 macOS 14+ 和较新 Windows WSL2 内核），导致：
- 容器内 GID 映射被重写为非零起始的私有范围（如 65536+）
- 即使你传了 --group-add=1001，容器内 id -G 可能仍只显示 0 或映射后的 GID
- /etc/group 文件也不包含宿主机的组名（如 docker、staff）
docker run --group-add 的正确用法与限制
该参数只接受数字 GID，不接受组名（如 --group-add=docker 会报错 invalid group name）。实际使用需注意：
- 先查宿主机目标组的 GID：运行
getent group docker | cut -d: -f3（Linux/macOS）或dscl . -read /Groups/docker gid（macOS）获取真实 GID - 若目标组在宿主机不存在（如 macOS 没有
docker组），传任意 GID 都无意义 —— 容器内不会自动创建对应组名 - 对 Alpine 镜像要额外注意：
apk add shadow才有groupadd命令；否则id -Gn无法解析组名，只显示数字 - 若容器内进程需要访问挂载卷中的文件，且文件属组为某 GID，必须确保该 GID 出现在容器的 supplementary groups 列表中，否则权限拒绝
替代方案：用 --user + --group-add 组合控制身份
单纯加组不够，常需同时指定 UID/GID 以匹配挂载卷权限。例如宿主机某目录属 1001:1001，想让容器内进程读写它：
docker run -v /path/on/host:/mnt/data:rw \ --user 1001:1001 \ --group-add 1001 \ --group-add 1002 \ alpine sh -c 'id && ls -l /mnt/data'
关键点：
-
--user必须是数字格式（UID:GID），不能用用户名 -
--group-add可多次使用，追加多个 supplementary GID - 镜像基础用户（如
alpine的root）会被覆盖，因此容器内id输出的 groups 是最终生效列表
Docker Desktop for Mac 的特别坑点
macOS 宿主机的 staff 组（GID 20）在 Docker Desktop 的 Linux VM 中通常被映射为另一个 GID（如 501），导致：
- 即使你
--group-add 20，容器内也无法访问宿主机staff组可读的文件 - 更可靠的做法是：用
stat -f "%g" /some/path查宿主机路径的实际 GID，再把这个 GID 传给--group-add - 若涉及 NFS 或 APFS 加密卷，还需确认该 GID 在 VM 内核中未被 user namespace 隔离过滤（可通过
docker run --rm alpine cat /proc/self/status | grep CapEff看是否启用了CAP_SETGID）
真正起作用的永远是 GID 数字本身，而不是组名。Docker Desktop 不提供“附加组权限”的图形开关，所有权限控制都得靠命令行参数落地——漏掉 --user 或传错 GID，--group-add 就只是个摆设。
