Auto-sync: 2026-04-22 19:20

wiki/concepts/PUID-PGID.md

@@ -0,0 +1,43 @@
+# 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
+```bash
+id shenwei
+# 输出：uid=1000(shenwei) gid=1000(shenwei) groups=1000(shenwei),...
+```
+
+### Docker Compose 配置示例
+```yaml
+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]]