nexus/wiki/concepts/PUID-PGID.md

PUID/PGID

Type

• Concept

Definition

PUID（Process User ID）和 PGID（Process Group ID）是 LinuxServer.io Docker 镜像专用的环境变量，用于将容器内进程以宿主机指定用户/组的身份运行，从根本上解决 Docker 容器创建文件的权限归属问题。

Mechanism

核心原理

宿主机：用户 shenwei (UID=1000, GID=1000)
    ↓ 设置 PUID=1000, PGID=1000
容器内：Transmission 进程以 UID=1000, GID=1000 运行
    ↓ 结果
容器创建的文件 → 归属 shenwei:shenwei → 宿主机可直接读写

获取宿主机 UID/GID

id shenwei
# 输出：uid=1000(shenwei) gid=1000(shenwei) groups=1000(shenwei),...

Docker Compose 配置示例

environment:
  - PUID=1000    # 对应宿主机用户 ID
  - PGID=1000    # 对应宿主机组 ID

Key Claims

• PUID/PGID 是 LinuxServer.io 镜像的标准化用户配置，与非 root 用户运行（USER 环境变量）不同
• 不设置 PUID/PGID 时，容器进程以 root（UID=0）运行，创建的文件归属 root:root，导致宿主机用户无法直接管理
• PUID/PGID 解决了"容器内 root vs 宿主机普通用户"的跨环境文件权限冲突
• 与 user: "1000:1000" Docker Compose 顶级键效果类似，但 PUID/PGID 由 LinuxServer.io 镜像内部脚本处理

Relationship to LinuxServer.io

PUID/PGID 是 LinuxServer.io 所有镜像的标准化配置环境变量，属于其官方推荐的最佳实践。

Sources

• 用docker安装transmission