SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Docker Compose 的 PUID 和 PGID 是什麼?

PUID 和 PGID 不是 Docker 設定,而是 linuxserver.io image 的 entrypoint 慣例。了解 bind mount 為何產生 911:911,以及如何修正檔案擁有者。

PUID 與 PGID 的實際作用

PUID 和 PGID 是部分 container image 在啟動時讀取的兩個環境變數。Docker 本身不會讀取這些變數。這是一種慣例,linuxserver.io image 及少數其他 image 會採用。因此,未設計成讀取這些變數的 image 會靜默忽略它們。

在 linuxserver.io image 中,有一個名為 abc 的使用者。此使用者在 build 時建立,UID(user ID)為 911,GID(group ID)為 911。container 會以 root 身分啟動並執行初始化指令碼。其中一個指令碼會在應用程式啟動前重新設定該使用者的 ID:

groupmod -o -g "${PGID}" abc
usermod -o -u "${PUID}" abc

-o 旗標允許使用其他地方已經使用中的 ID。完成後,初始化程序會降低權限,並以 abc 身分執行應用程式。因此,Docker 只會像處理其他環境變數一樣,將 PUID=1000 傳入 container,不會對它採取任何動作。此變數會在應用程式啟動前重新設定 container 內使用者的 ID。也就是說,在未啟用 user namespace remapping 的標準 rootful daemon 上,新建立的檔案通常會以 1000 的擁有者身分寫入磁碟。寫入既有且可寫入的檔案不會變更其擁有者。Rootless Docker 會調整這個 ID,詳情如下文所述。若未設定 PUID,abc 會維持 911,因此未設定的 bind mount 會產生由 911:911 擁有的檔案。

使用 id 取得兩個數字

在主機上,以擁有資料目錄的使用者身分執行:

id
uid=1000(deploy) gid=1000(deploy) groups=1000(deploy),27(sudo),988(docker)

uid 是您的 PUID,gid 是您的 PGID。若要在腳本中使用,id -u 和 id -g 會輸出純數字。在多數全新的 VPS 映像中,第一個一般使用者的 ID 是 1000:1000,但不要直接假設如此。ID 的配置取決於現有的帳戶與設定:重建後的伺服器可能再次配置 1000,而較晚建立的帳戶則會取得更高的可用 ID。若服務是以 專用服務帳戶,而非您自己的登入使用者 執行,請執行 id thatuser,並從中取得這些數字。

為什麼檔案會顯示為 911:911

ls -l在找不到符合該 ID 的主機帳號時,會列印數字 ID,而不是名稱。如果沒有符合 UID 911 的主機帳號,就沒有名稱可供列印。使用 ls -ln 可一律顯示數字,避免產生歧義:

ls -ln /srv/appdata/sonarr
drwxr-xr-x 2 911 911 4096 Aug  7 09:12 Backups
-rw-r--r-- 1 911 911  512 Aug  7 09:12 config.xml

該輸出符合容器內建的預設值,但僅憑現有檔案,無法證明應用程式目前以哪個使用者身分執行。該清單中的 config.xml 也是存放驗證設定的檔案。第一次開啟 Web UI 時,這點很重要,因為 Sonarr 和 Radarr 不提供預設使用者名稱或密碼。請從容器內部確認,不要自行猜測:

docker exec sonarr id abc
docker compose logs sonarr | head -n 25

linuxserver init 會在啟動日誌中以 2 行列印結果:

User UID:    911
User GID:    911

如果你在 Compose 檔案中設定 PUID=1000 後,這 2 行仍顯示 911,表示執行中的容器沒有使用你設定的值。常見原因是你編輯了 docker-compose.yml,接著執行 docker compose restart;此命令會沿用現有容器及其原始環境。環境變更需要使用 docker compose up -d,此命令會重新建立容器。另一個原因是刻意的行為:映像檔以唯讀模式或非 root 模式執行時,init 會完全略過重新編號,即使容器中存在該變數。唯讀模式的啟動訊息會顯示 abc 未變更的 ID;非 root 模式則會顯示 /run 的擁有者。

為什麼無法刪除容器建立的檔案

核心只比對數字,不會比對名稱。您的 shell 以 UID 1000 執行。檔案屬於 UID 911。存放該檔案的目錄是 drwxr-xr-x,同樣屬於 911,因此群組與其他使用者只有讀取和執行權限,沒有寫入權限。刪除檔案需要對其所在目錄具備寫入權限,而不是對檔案本身具備寫入權限。因此,即使檔案本身看似沒有問題,仍會出現以下結果:

rm: cannot remove '/srv/appdata/sonarr/config.xml': Permission denied

寫入檔案的容器也會從另一端遇到相同限制。如果主機目錄屬於您的使用者,權限模式為 755,而應用程式以 911 執行,第一次寫入就會因 Permission denied 而失敗,應用程式則會以自身的訊息回報錯誤。在 Sonarr 或 Radarr 等 .NET 應用程式中,這會顯示為 UnauthorizedAccessException: Access to the path '/data/downloads' is denied。檔案前方的權限字串會告訴您實際套用的是三組權限中的哪一組,而正確讀懂 drwxr-xr-x能讓這個錯誤從難以理解變得一目了然。

這是 bind mount 特有的問題。當 Docker 建立空的 named volume,並將其掛載到 image 中已存在的路徑時,Docker 會將該路徑的內容複製到 volume,包括擁有者與權限位元,因此應用程式會取得一個原本就由它擁有的目錄。bind mount 不會獲得這項處理:Docker 會完全按照原樣掛載您的主機目錄。這項差異也是了解何時 bind mount 優於 named volume,以及何時不是的實際原因之一。

修正已經錯誤的目錄

設定 PUID 和 PGID 只會影響應用程式後續的行為。它不會追溯修正磁碟上已存在的所有檔案,不過 init 會修正下方所述特定路徑的擁有權。請停止 stack,自行修正擁有權後再重新啟動:

docker compose down
sudo chown -R 1000:1000 /srv/appdata/sonarr
docker compose up -d

如果不想輸入數字,請使用 sudo chown -R "$(id -u):$(id -g)" /srv/appdata/sonarr。請在容器停止時執行此操作,因為應用程式若在遞迴執行 chown 的期間仍寫入檔案,可能會導致目錄樹只修正一部分,並引發難以判斷的第二輪錯誤。

PUID 和 PGID 無法修正的問題

以下是即使所有設定都正確,仍可能遇到問題的部分。linuxserver 基礎映像的使用者設定指令碼會在啟動時對三個路徑執行 chown:/app、/config 和 /defaults。您的媒體掛載不在這份清單中。/data、/downloads 和 /tv 會原封不動交給應用程式處理。因此,如果這些掛載在主機端的擁有權不允許容器使用者寫入,容器仍會正常啟動,在啟動訊息中顯示正確的 UID,接著在第一次匯入時失敗。

這是正確的行為。每次容器啟動時,都對 12 TB 的媒體庫執行遞迴 chown 會造成嚴重問題。但這也表示媒體目錄由您負責管理,而這些掛載正是權限最容易出錯的地方。這類失敗通常不會立即顯現,而是在容器看似健康數小時後,才安靜地出現在應用程式日誌中。將定期寫入測試連接到 您自己的 VPS 上的 ntfy,並將警示推送到手機,就能以低成本及早得知問題,而不必等到一週沒有新集數後才發現。

控制使用者的 3 種方式,以及各自適用的時機

PUID 與 PGID 環境變數

這只適用於 entrypoint 會讀取這些變數的映像檔。這種方式很常見,因為容器仍會先以 root 啟動,完成自己的初始化、修正 /config,然後才降低權限。Docker Mods 與自訂 init scripts 也能繼續運作。代價是你依賴的是慣例,而不是平台功能,而且不同專案的變數名稱不一定一致。

Compose 中的 user: 金鑰

這是 Docker 的原生功能,適用於所有映像檔,因為容器 runtime 會在映像檔自己的程式碼執行前套用設定:

services:
  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    user: "1000:1000"

程序從未以 root 身分執行,連片刻也沒有,因此確實能提升安全性。但 entrypoint 中任何需要 root 的項目也會因此失效。對於 linuxserver 映像檔,專案僅在合理的努力範圍內支援此功能,而且只支援經過測試的映像檔。具體限制包括:PUID 和 PGID 不再生效、Docker Mods 不會執行、自訂服務不會執行,而且每個掛載 volume 的權限都由你負責。其文件記載的模式會將此旗標搭配可寫入的 /run:

user: 1000:1000
tmpfs:
  - /run:uid=1000,gid=1000,exec
security_opt:
  - no-new-privileges=true

有一個外觀上的副作用常讓人意外。容器的 /etc/passwd 中若沒有與數值 user: 相符的項目,容器內的工具會回報 whoami: cannot find name for user ID 1000。該 ID 有效,檔案存取也能正常運作。只有名稱查詢會失敗。

Rootless Docker

Rootless Docker 會讓 daemon 本身以你的非特權使用者身分執行,因此 daemon 與容器都不具備 host 的 root 權限。這會完全改變所有權的計算方式。容器 UID 0 會對應到執行 rootless Docker 的 host 使用者 UID;對於值為 1 或以上的任何 n,容器 UID n 會對應到 subuid + (n - 1),其中 subuid 是在 /etc/subuid 中分配給你的範圍起始值;群組 ID 也會依照相同規則使用 /etc/subgid。Docker 要求其中至少有 65,536 個 subordinate ID。

請重新閱讀這項對應關係,因為它與通常的建議相反。在 Rootless Docker 下,容器以 root 建立檔案時,通常會建立由你擁有的檔案。容器以 UID 1000 建立檔案時,通常會建立由 subordinate ID 擁有的檔案,例如範圍從 100000 開始時,會是 100999。你的 shell 能否存取取決於權限與 ACL;刪除檔案通常取決於所在目錄,因此你可以從自己控制的目錄刪除該檔案。因此,在 rootful daemon 上正確的 PUID 值,在這裡反而是錯的。這兩種機制會在不同層級變更所有權,未經檢查就疊加使用,可能導致你無法寫入掛載的資料。如果要使用 rootless,請先在自己的伺服器上測試一個已寫入檔案的所有權,再將媒體庫遷移到其中。

對於在單一 VPS 上執行的大多數自架服務堆疊,rootful daemon 搭配 PUID 和 PGID 是實務上較合理的選擇,因為映像檔就是依此建置並撰寫文件。當映像檔 README 明確表示已針對 user: 進行測試,或你執行的是完全不支援 PUID 的官方上游映像檔時,才應採用 user:。例如 在單一 VPS 上自架 AFFiNE instance 就屬於後一種情況,因為其中沒有任何容器會讀取 PUID,而其資料庫目錄與上傳檔案的所有權,是由 runtime 決定,而不是由環境區塊中的設定決定。自架 Chatwoot support desk 也是如此:Rails 容器及其 Sidekiq worker 都會寫入同一個 uploads 目錄,而且兩者都不會讀取 PUID,因此該目錄必須符合映像檔原本執行時所使用的使用者。即使是較新的堆疊,情況也不會改變。因此,讓團隊中的每個人各自使用隔離的 OneCLI agent 時,每個人的 workspace 目錄與 Postgres data 目錄仍會由各映像檔原本執行時所使用的使用者擁有,這會成為 user: 與 chown 問題,而不是 PUID 問題。若在 Codex、Claude Code 與 Hermes 前方放置 單一自架 API,其 entrypoint 會管理多個身分:容器必須以 root 啟動,console 與 gateway 以非特權使用者執行,而每個 agent session 則以自己的使用者身分執行。請勿在該部署中加入 user:;其 entrypoint 會處理 data volume 的所有權。

媒體堆疊案例:容器共用同一個群組

包含 Sonarr、Radarr 和下載用戶端的 arr 媒體堆疊會讓這不再只是理論。下載用戶端會將完成的檔案寫入 /data/downloads。Sonarr 接著會將該檔案建立硬連結,或移動至 /data/media。硬連結要能運作,兩個容器都必須能寫入同一個目錄樹。如果下載用戶端以 1000 執行,而 Sonarr 以 1001 執行,且沒有共用群組寫入權限,其中一個容器建立的檔案就會由另一個容器只能讀取。

解法是建立堆疊中所有容器都使用其 PGID 的共用群組:

sudo groupadd -g 13000 media
sudo usermod -aG media deploy
sudo chown -R deploy:media /srv/media
sudo find /srv/media -type d -exec chmod 2775 {} +
sudo find /srv/media -type f -exec chmod 0664 {} +

2775 開頭的 2 是 setgid 位元。套用在目錄上時,表示其中建立的每個新檔案和子目錄都會繼承群組 media,而不是建立者自己的主要群組。因此,新的下載完成後不必重新執行 chown,這個配置仍會持續有效。在檢查自己的存取權限前,請先登出再登入,或執行 newgrp media:使用 usermod -aG 新增的群組不會出現在已開啟的 shell 工作階段中。

在容器內,groupmod -o -g 13000 abc 會將 abc 群組重新編號為 13000,讓 abc 以與主機上的 media 群組相同的 GID 寫入。所有會存取此目錄樹的 linuxserver 容器都保留各自的 PUID,並共用同一個 PGID。這也包含鏈結中後續只讀取完成媒體庫的容器,例如 Jellyfin 本身。像 Halcyon 這類將該媒體庫提供為可瀏覽 90s 影音商店的前端,會使用 HALCYON_JELLYFIN_URL 透過 HTTP 連線至 Jellyfin;其標準部署不需要共用的媒體 PGID,也不需要掛載媒體目錄。

接著,在堆疊中的每個 linuxserver 容器設定 UMASK=002。這是最容易遺漏的步驟。若未設定,應用程式會繼承原本的 umask,除非其他設定將其變更;映像檔 README 顯示的範例值是 UMASK=022。有效 umask 為 022 時,應用程式要求建立新檔案並使用 0666 時,在沒有預設 ACL 的情況下會得到 0644:群組中的其他成員仍可讀取,但無法修改,這會抵銷剛完成的大部分共用設定。使用 002 且沒有預設 ACL 時,應用程式對檔案要求一般的 0666、對目錄要求 0777,會分別得到 0664 檔案,以及在 setgid 目錄樹內的 2775 目錄,群組也能寫入。umask 只會移除權限位元,因此應用程式要求 0600 時仍會得到 0600;而帶有預設 ACL 的目錄則會完全忽略 umask。將此變數加在 PUID 和 PGID 旁:

services:
  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    container_name: sonarr
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - UMASK=002
      - TZ=Etc/UTC
    volumes:
      - /srv/appdata/sonarr:/config
      - /srv/media:/data
    restart: unless-stopped

這兩個值應放在 Compose 檔案旁的 .env 檔案中,讓整個堆疊讀取同一份定義:

PUID=1000
PGID=13000

Compose 會自動讀取該檔案,用於 ${PUID} 式替換;這與設定憑證時使用的機制相同。將值從 docker-compose.yml 移至 .env 檔案,避免直接放入其中的做法同樣適用,差別在於這兩個數字不是秘密。

請端對端驗證,不要只相信設定。以應用程式使用者身分建立新檔案,套用已設定的 umask,然後從主機讀取該檔案。請使用尚不存在的測試檔名:

docker exec --user abc sonarr sh -c 'umask "$UMASK" && touch /data/downloads/permtest'
ls -ln /srv/media/downloads/permtest

正常結果會顯示你的 PUID 為擁有者、13000 為群組,以及 -rw-rw-r-- 為權限模式。如果群組顯示 1000,請執行 ls -ldn /srv/media/downloads:該目錄可能缺少 setgid 位元(drwxrwsr-x 中的 s),或目錄本身仍屬於群組 1000,而不是 media;上方的 chown 和 chmod 2775 命令可修正這兩個問題。如果權限模式顯示 -rw-r--r--,請檢查容器的 UMASK 值與目錄的預設 ACL;若環境變數仍是舊值,請重新建立容器。此測試會使用已設定的遮罩,以 abc 身分檢查檔案建立;應用程式自身的建立模式與有效 umask 仍會決定其檔案權限。完成後,使用 rm /srv/media/downloads/permtest 移除測試檔案。

哪些映像使用哪些變數

linuxserver.io 映像使用 PUID、PGID 和 UMASK。Paperless-ngx 對相同概念使用不同名稱:USERMAP_UID 和 USERMAP_GID,兩者預設值都是 1000;其文件要求你從 id -u 和 id -g 讀取這些值。相片伺服器也有相同差異:PhotoPrism 有自己的 PHOTOPRISM_UID 和 PHOTOPRISM_GID 組合,Immich 則沒有對應設定,而是讓容器使用 Docker 的 user: 鍵。因此,選擇 PhotoPrism 或 Immich 也會決定你要為主機上最大的媒體庫維護哪一套機制。許多官方上游映像,包括常見的資料庫與 Web 伺服器映像,都使用內建的固定使用者,並要求你設定 user:,或維持預設值不變。

小型單一應用程式部署也會遇到相同問題。因此,當你建立 自架的 openGym 運動追蹤器 時,應先確認其容器實際以哪個使用者執行,再將 bind mount 指向該容器。因為無論是否設定 PUID,存放其資料庫的目錄都會受到該使用者設定影響。遠端存取 relay 也屬於同類情況。當 你執行自己的 RustDesk relay server 時,hbbs 首次啟動時寫入的 Ed25519 金鑰組,會以該映像最後使用的使用者身分出現在 bind mount 中。你可以事後在主機端使用 chown 修正擁有權,也可以透過 user: 鍵預先指定身分。這是因為該映像沒有自行設定使用者;但掛載的目錄必須允許你選定的 ID 寫入。之後加入的基礎架構也適用相同原則。因此,將 Authentik 放在應用程式前方以提供單一登入,代表你會執行不讀取 PUID 的官方 authentik 和 Postgres 映像。這些映像的 volume 擁有權,取決於其程序執行時使用的使用者,以及 entrypoint 執行的設定流程。Authentik 已在 release 2025.10 移除 Redis 相依性。

因此,在不同專案之間複製環境變數區塊前,請先查看每個映像的 README。Docker 會將你設定的任何環境變數傳入任何容器,不論容器內是否有元件讀取該變數;未被使用的 PUID 不會產生錯誤、警告或任何效果。容器會先以 Docker 的 user: 設定或 Dockerfile 選定的使用者身分啟動,之後 entrypoint 可能在啟動應用程式前降低權限。新增任何服務到主機前,都應先完成這項確認,包括 自架的 open-kritt 安全掃描堆疊。其 Compose 檔案會說明這些映像是否支援 PUID,或掛載目錄的擁有權是否由映像本身固定決定。

FAQ

為什麼我的 Docker 檔案擁有者是 911:911?

911 是 linuxserver.io 映像檔內建的 abc 使用者之 UID 和 GID。這表示檔案使用的是內建預設值,但即使變更容器的 PUID 和 PGID,檔案仍可能保留原本的擁有權。若主機上沒有帳號符合這些 ID,ls -l 會顯示原始數字,因此沒有名稱可顯示。將 PUID 和 PGID 設為 id 的輸出,使用 docker compose up -d 重新建立容器,然後在受影響的目錄上使用 sudo chown -R 1000:1000 修正現有檔案。

PUID 和 PGID 適用於每個 Docker 映像檔嗎?

不適用。它們不是 Docker 功能,Docker 也不會讀取這些變數。只有映像檔自己的 entrypoint 會讀取這些變數,並在啟動應用程式前呼叫 usermod 和 groupmod 時,這些變數才會生效。linuxserver.io 系列,以及少數採用相同模式的專案支援這種方式。其他專案可能使用不同名稱,例如 paperless-ngx 的 USERMAP_UID 和 USERMAP_GID。若映像檔完全不讀取這些變數,Docker 會接受並忽略它們,且不會顯示警告。

在 Docker Compose 中,我應該使用 PUID 和 PGID,還是使用 user: 金鑰?

映像檔支援時,請使用 PUID 和 PGID,因為 entrypoint 仍會以 root 身分執行足夠長的時間,以正確修正 /config 並啟動自身的服務。若映像檔文件說明支援指定的使用者,請使用 user:;不支援 PUID 並不代表 entrypoint 不需要 root。在 linuxserver 映像檔中,設定 user: 會使 PUID 和 PGID 不再生效、停止 Docker Mods 和自訂服務執行,並讓所有掛載磁碟區的權限都由你負責。

Sonarr 的 PUID 正確,但仍無法移動檔案。問題在哪裡?

請依序檢查 3 件事。第一是媒體掛載本身:基礎映像檔的使用者設定指令碼會對 /app、/config 和 /defaults 執行 chown,因此 /data 或 /downloads 會保留主機上的既有擁有權。第二是共用群組:讓存取媒體樹狀目錄的容器使用相同的 PGID,並授予群組寫入權限。第三是 umask:當應用程式要求 0666 且未套用預設 ACL 時,有效遮罩 022 會產生 0644 檔案,因此群組中的其他容器可以讀取,但無法修改這些檔案。未設定 UMASK 不代表一定會使用特定的遮罩或檔案模式。設定 UMASK=002,並使用 chmod 2775 在目錄上設定 setgid 位元,讓新檔案繼承該群組。即使應用程式要求 0600,仍會建立私有檔案;而預設 ACL 會改變建立檔案時套用權限的方式。

這篇文章對您有幫助嗎?