Docker 目录挂载与用户权限：PUID/PGID 讲解

容器版最常见的翻车点：下载完成了，但宿主机上文件属主是奇怪的 UID，NAS 共享目录里删不掉、改不了。这一页解释为什么以及怎么治。

为什么会这样

容器内进程默认以特定用户身份运行，写入挂载目录时按容器内 UID 创建文件。宿主机（尤其 NAS）上对应的 UID 没有匹配用户时，文件就显示为「数字属主」，权限管理一片混乱。

PUID/PGID 环境变量

镜像支持用这两个变量指定容器内进程运行身份：

docker run --name gopeed -d -p 9999:9999 \
    -e PUID=1000 \
    -e PGID=100 \
    -v /path/to/download:/app/Downloads \
    liwei2633/gopeed

• PUID：容器内进程使用的用户 ID，设成宿主机上你自己的用户 UID（Linux 上 id -u 查看）。
• PGID：对应的组 ID（id -g 查看）。

两个值与挂载目录的属主对齐后，下载文件在宿主机上就是「正常」文件。

NAS 场景的配合要点

• 先在 NAS 上确认共享目录的属主 UID/PGID，再填给容器，顺序别反。
• 挂载路径与下载目录白名单保持一致，白名单机制见下载目录设置。
• 改完环境变量要重建容器才生效，改配置不重启等于没改。

相关阅读

• 部署命令全集：Docker 一行命令部署。
• 多用户访问的边界：公网部署必开认证。