SSD Nodes Learn Hosting plans →
Посібники Matt ConnorВід Matt Connor

PUID і PGID у Docker Compose: як виправити UID 911

PUID і PGID не є налаштуваннями Docker. Пояснюємо convention linuxserver.io, чому bind mount отримує власника 911:911 і як це виправити.

Що насправді означають PUID і PGID

PUID і PGID — це дві змінні середовища, які під час запуску зчитують певні container images. Сам Docker їх не перевіряє. Це усталена конвенція, яку використовують images від linuxserver.io та деякі інші. Тому image, який не запрограмований на їх зчитування, мовчки їх ігнорує.

У linuxserver.io image є користувач abc. Його створено під час build із UID (user ID) 911 і GID (group ID) 911. Контейнер запускається від імені root, виконує init scripts, а один із цих scripts перед запуском застосунку змінює ідентифікатори цього користувача:

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

Прапорець -o дає змогу призначити ID, який уже використовується в іншому місці. Після цього init знижує привілеї та запускає застосунок від імені abc. Отже, Docker передає PUID=1000 у контейнер як будь-яку іншу змінну середовища і не виконує з нею жодних дій. Ця змінна змінює ідентифікатор користувача всередині контейнера до запуску застосунку. Тому у стандартному rootful daemon без remapping user namespace нові файли зазвичай створюються на диску з власником 1000. Запис до наявного доступного для запису файлу не змінює його власника. Rootless Docker змінює це число, як пояснено далі. Якщо не задати 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 першому звичайному користувачу призначають 1000:1000, але не покладайтеся на це припущення. Розподіл залежить від наявних облікових записів і конфігурації: на перебудованому сервері знову може бути призначено 1000, а наступний користувач отримає інший доступний ідентифікатор. Якщо ваші сервіси працюють від імені окремого облікового запису сервісу, а не вашого користувача для входу, виконайте id thatuser і візьміть значення звідти.

Чому ваші файли відображаються як 911:911

ls -l виводить числовий ідентифікатор замість імені, якщо на хості немає облікового запису, що відповідає цьому ідентифікатору. Якщо на хості немає облікового запису з 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 у цьому списку також є файлом, що містить параметри автентифікації. Це важливо, коли ви вперше відкриваєте веб-інтерфейс і бачите, що Sonarr і Radarr постачаються без імені користувача або пароля за замовчуванням. Перевірте це всередині контейнера, а не вгадуйте:

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

linuxserver init виводить результат у startup log двома рядками:

User UID:    911
User GID:    911

Якщо після встановлення PUID=1000 у файлі Compose у цих рядках зазначено 911, запущений контейнер не використовує встановлене вами значення. Зазвичай причина полягає в тому, що ви відредагували docker-compose.yml, а потім виконали docker compose restart. Ця команда повторно використовує наявний контейнер із початковим environment. Зміни environment потребують docker compose up -d, яка створює контейнер заново. Інша причина може бути навмисною: коли image працює в режимі read-only або non-root, init повністю пропускає перенумерацію, навіть якщо змінна присутня в контейнері. У режимі read-only banner показує незмінений ID abc; у режимі non-root він показує власника /run.

Чому не можна видалити файл, створений контейнером

Ядро порівнює числові ідентифікатори, а не імена. Ваша оболонка працює з UID 1000. Файл належить UID 911. Каталог, у якому він міститься, має права drwxr-xr-x і також належить UID 911, тому група та інші користувачі мають права на читання й виконання, але не на запис. Для видалення файлу потрібні права на запис до його каталогу, а не до самого файлу. Тому ви отримуєте таку помилку, навіть якщо сам файл виглядає нешкідливим:

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

Контейнер, який записує дані, стикається з тією самою проблемою з іншого боку. Якщо каталог на хості належить вашому користувачу й має режим 755, а застосунок працює від UID 911, його перша спроба запису завершується помилкою Permission denied, і застосунок повідомляє про неї у власному форматі. У .NET-застосунку, такому як Sonarr або Radarr, це відображається як UnauthorizedAccessException: Access to the path '/data/downloads' is denied. Рядок прав перед іменем файлу показує, до якого з трьох наборів прав застосовується перевірка. Уміння правильно читати drwxr-xr-x перетворює цю помилку з незрозумілої на очевидну.

Це саме проблема bind mount. Коли Docker створює порожній іменований том і монтує його поверх шляху, який уже існує в image, він копіює в том вміст цього шляху, зокрема власника та біти прав доступу. Тому застосунок отримує каталог, яким уже володіє. Bind mount не має такої поведінки: Docker монтує каталог із хоста саме в тому стані, у якому він є. Ця відмінність є однією з практичних причин знати, коли bind mount кращий за іменований том, а коли ні.

Виправлення каталогу, у якому вже є помилки

Налаштування PUID і PGID визначає поведінку застосунку надалі. Воно не виправляє заднім числом усі файли, які вже є на диску, хоча init-процес виправляє власника для певних шляхів, описаних нижче. Зупиніть stack, самостійно виправте власника, а потім запустіть 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. Виконуйте цю операцію, коли container зупинений. Якщо застосунок продовжує запис під час рекурсивного chown, дерево каталогів може бути виправлене лише частково, що спричинить нову серію незрозумілих помилок.

Що PUID і PGID не виправляють

Ось частина, на якій помиляються навіть ті, хто все налаштував правильно. Скрипт налаштування користувача в базовому образі linuxserver під час запуску виконує chown для трьох шляхів: /app, /config і /defaults. Ваші монтування медіаданих до цього списку не входять. /data, /downloads і /tv передаються застосунку без змін. Тому, якщо на стороні хоста для цих монтувань власником є користувач, якому заборонено запис, контейнер запускається без помилок, виводить правильний UID у своєму банері, а потім завершується помилкою під час першого імпорту.

Це правильна поведінка. Рекурсивний chown для бібліотеки медіаданих обсягом дванадцять терабайт під час кожного запуску контейнера був би катастрофою. Це означає, що за каталоги з медіаданими відповідаєте ви. Саме в цих монтуваннях найчастіше виникають проблеми з правами доступу. Такий збій непомітно з’являється в журналі застосунку через кілька годин після того, як контейнер почав працювати. Тому періодична перевірка запису, підключена до ntfy на власному VPS із надсиланням сповіщень на телефон, — простий спосіб дізнатися про проблему до того, як про неї повідомить тиждень відсутніх епізодів.

Три способи керування користувачем і коли застосовувати кожен

Змінні середовища PUID і PGID

Це працює лише в образах, чий entrypoint їх зчитує. Такий підхід популярний, оскільки контейнер спочатку запускається від root, виконує власне налаштування, виправляє /config, а потім знижує привілеї. Docker Mods і власні init-скрипти продовжують працювати. Недолік полягає в тому, що ви покладаєтеся на певну домовленість, а не на функцію платформи, і назви змінних у різних проєктах не стандартизовані.

Ключ user: у Compose

Це справжня функція Docker, яка працює з будь-яким образом, оскільки середовище виконання контейнерів застосовує її до запуску власного коду образу:

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

Процес не запускається від root навіть на мить, що дає реальний виграш у безпеці. Водночас це ламає все в entrypoint, для чого потрібні права root. В образах linuxserver проєкт підтримує цей режим на основі розумних зусиль і лише для протестованих образів. Обмеження конкретні: PUID і PGID більше не впливають на роботу, Docker Mods не запускаються, власні сервіси не запускаються, а за права доступу до кожного змонтованого тому відповідаєте ви. У задокументованому проєктом шаблоні цей прапорець поєднується із доступним для запису /run:

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

Один косметичний побічний ефект застає користувачів зненацька. Числовий user:, для якого немає відповідного запису в /etc/passwd контейнера, змушує інструменти всередині повідомляти whoami: cannot find name for user ID 1000. Ідентифікатор є коректним, і доступ до файлів працює як звичайно. Не працює лише пошук імені.

Rootless Docker

Rootless Docker запускає сам daemon від імені непривілейованого користувача. Тому daemon і контейнери працюють без привілеїв root на хості. Це повністю змінює розрахунок власників. UID контейнера 0 відображається на UID користувача хоста, від імені якого працює rootless Docker. UID контейнера n для будь-якого n, що дорівнює 1 або більше, відображається на subuid + (n - 1), де subuid — початок діапазону, виділеного для вас у /etc/subuid. Ідентифікатори груп підпорядковуються тому самому правилу через /etc/subgid. Docker очікує, що в цьому файлі буде щонайменше 65,536 додаткових ідентифікаторів.

Прочитайте цей опис відображення ще раз, оскільки він змінює стандартну рекомендацію на протилежну. У rootless Docker контейнер, який створює файл від root, зазвичай створює файл, власником якого єте ви. Контейнер, який створює файл із UID 1000, зазвичай створює файл, власником якого є додатковий ідентифікатор, наприклад 100999, якщо діапазон починається з 100000. Доступ із вашої оболонки залежить від прав і ACL. Видалення зазвичай залежить від каталогу, що містить файл, тому файл можна видалити з каталогу, яким ви керуєте. Отже, значення PUID, правильне для daemon із правами root, тут буде неправильним. Ці два механізми змінюють власника на різних рівнях. Якщо застосувати їх одночасно без перевірки, можна втратити можливість запису до змонтованих даних. Якщо ви переходите на rootless, перевірте власника одного створеного файла на власному сервері, перш ніж переносити в нього бібліотеку.

Для більшості self-hosted стеків на одному VPS практичним вибором є PUID і PGID у daemon із правами root, оскільки саме для цього створено та задокументовано відповідні образи. Обирайте user:, коли README образу повідомляє, що цей режим протестовано, або коли ви використовуєте офіційний upstream-образ, який взагалі не підтримує PUID. Робочий простір для документів, наприклад self-hosted інстанс AFFiNE на одному VPS, належить до останнього випадку, оскільки жоден із його контейнерів не зчитує PUID, а власник каталогу бази даних і завантажених файлів визначається середовищем виконання, а не будь-чим у блоці environment. Те саме стосується self-hosted служби підтримки Chatwoot, де Rails-контейнер і його worker Sidekiq записують дані в один каталог завантажень, але жоден із них не зчитує PUID. Тому цей каталог має відповідати користувачу, від імені якого образ уже запускається. Для новішого стека нічого не змінюється. Тому надання кожному учаснику команди власного ізольованого агента OneCLI залишає каталоги робочих просторів окремих користувачів і каталог даних Postgres у власності користувача, від імені якого вже запускається кожен образ. Це питання user: і chown, а не PUID. Якщо розмістити один self-hosted API перед Codex, Claude Code і Hermes, його entrypoint керує кількома ідентичностями: контейнер має запускатися від root, консоль і gateway працюють від непривілейованого користувача, а кожен сеанс агента працює від власного користувача. Не додавайте user: до цього розгортання: його entrypoint сам керує власником тому з даними.

Випадок media stack: одна спільна група для контейнерів

arr media stack із Sonarr, Radarr і клієнтом завантажень — це практичний приклад. Клієнт завантажень записує готовий файл у /data/downloads. Потім Sonarr створює для цього файлу hardlink або переміщує його в /data/media. Для роботи hardlink обидва контейнери мають мати доступ на запис до одного дерева каталогів. Якщо клієнт завантажень працює від імені 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 {} +

Початковий 2 у 2775 — це біт setgid. Для каталогу він означає, що кожен новий файл і підкаталог, створений усередині, успадковує групу media, а не основну групу користувача, який його створив. Тому ця схема працює і для нових завантажень без повторного виконання chown. Вийдіть із системи та увійдіть знову або виконайте newgrp media, перш ніж перевіряти власний доступ. Група, додана за допомогою usermod -aG, не з’являється у вже відкритій shell-сесії.

У контейнері groupmod -o -g 13000 abc змінює GID групи abc на 13000, тому abc записує файли з тим самим GID, що й ваша група media на хості. Кожен контейнер linuxserver, який має доступ до цього дерева, зберігає власний PUID і використовує цей спільний PGID. Це стосується і контейнерів далі в ланцюжку, які лише читають готову бібліотеку, зокрема самого Jellyfin. Front end на кшталт Halcyon, який подає цю бібліотеку як доступний для перегляду відеомагазин у стилі 90-х, підключається до Jellyfin через HTTP за допомогою HALCYON_JELLYFIN_URL. Для його стандартного розгортання не потрібні ні спільний PGID media, ні монтування каталогу media.

Потім задайте UMASK=002 у кожному контейнері linuxserver у стеку. Саме цей крок часто пропускають. Якщо значення не задано, застосунок використовує успадкований umask, якщо інше налаштування його не змінює. У прикладі зі сторінок README образів наведено значення UMASK=022. За ефективного umask 022 застосунок, який запитує 0666 для нового файлу, отримує 0644, якщо немає ACL за замовчуванням. Інші учасники групи все ще можуть читати файл, але не можуть його змінювати, що фактично скасовує більшість щойно налаштованого спільного доступу. За 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

Ці два значення потрібно зберігати у файлі .env поруч із Compose-файлом, щоб увесь стек використовував одне визначення:

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 — s у drwxrwsr-x, — або сам каталог усе ще належить групі 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 не має еквівалента й передає керування користувачем контейнера ключу user: у Docker. Тому вибір між PhotoPrism та Immich також визначає, який із цих механізмів вам доведеться підтримувати для найбільшої бібліотеки на сервері. Багато офіційних upstream-образів, зокрема поширені образи баз даних і вебсерверів, містять фіксованого вбудованого користувача й очікують, що ви використаєте user: або залишите все без змін. У невеликих інсталяціях одного застосунку виникає те саме питання. Тому перед підключенням bind mount до self-hosted трекера тренувань openGym перевірте, від імені якого користувача фактично працює його контейнер. Каталог із його базою даних успадкує цей режим незалежно від того, чи встановили ви PUID. Віддалений relay також належить до цієї категорії. Коли ви запускаєте власний relay-сервер RustDesk, пара ключів Ed25519, яку hbbs записує під час першого запуску, з’являється у вашому bind mount із власником, що відповідає користувачу, від імені якого працює цей образ. Пізніше це можна виправити за допомогою chown на хості або заздалегідь вибрати потрібну ідентичність через ключ user:. Цей образ самостійно не задає користувача, але змонтований каталог має бути доступним для запису вибраному ID. Те саме стосується інфраструктури, яку ви додаєте пізніше. Розміщення Authentik перед застосунками для єдиного входу означає запуск офіційних образів authentik і Postgres, які взагалі не читають PUID. Власник їхніх томів визначається користувачами, від імені яких працюють процеси, і діями, які виконують їхні entrypoint-скрипти. Authentik видалив залежність від Redis у релізі 2025.10.

Тому перед копіюванням блоку змінних середовища між проєктами перевірте README кожного образу. Docker передає в контейнер будь-яку встановлену вами змінну середовища незалежно від того, чи читає її щось усередині контейнера. Якщо PUID нічого не використовує, це не спричиняє помилки, попередження або будь-якого ефекту. Контейнер запускається від імені користувача, вибраного параметром user: у Docker або Dockerfile. Після цього його entrypoint може знизити привілеї перед запуском застосунку. Перевірте це до додавання будь-яких нових компонентів на сервер, зокрема self-hosted стека сканування безпеки open-kritt. Його Compose-файл покаже, чи підтримують образи PUID, чи власник змонтованих каталогів фіксований самими образами.

FAQ

Чому мої файли Docker належать 911:911?

911 — це UID і GID користувача abc, вбудованого в образи linuxserver.io. Така відповідність означає, що використовуються вбудовані значення за замовчуванням, але файли можуть зберегти ці права власності після зміни PUID і PGID контейнера. ls -l показує необроблені числові значення, якщо жоден обліковий запис на вашому хості не відповідає цим ID, тому ім’я відобразити неможливо. Установіть PUID і PGID відповідно до виводу id, повторно створіть контейнер за допомогою docker compose up -d, а потім виправте права власності на наявні файли за допомогою sudo chown -R 1000:1000 у відповідному каталозі.

Чи працюють PUID і PGID у кожному образі Docker?

Ні. Це не функція Docker, і Docker їх не зчитує. Вони працюють лише в образах, чия власна entrypoint-логіка зчитує ці змінні та викликає usermod і groupmod перед запуском застосунку. Це стосується сімейства linuxserver.io та кількох проєктів, які скопіювали цей підхід. Інші проєкти використовують інші назви, наприклад USERMAP_UID і USERMAP_GID у paperless-ngx. В образі, який не зчитує жодну з цих змінних, вони приймаються та ігноруються без попередження.

Чи слід використовувати PUID і PGID або ключ user: у Docker Compose?

Використовуйте PUID і PGID, якщо образ їх підтримує, оскільки entrypoint продовжує виконуватися від імені root достатньо довго, щоб виправити /config і належним чином запустити власні служби. Використовуйте user:, якщо в документації образу зазначено підтримку вибраного користувача. Відсутність підтримки PUID сама по собі не означає, що entrypoint працює без root. В образі linuxserver встановлення user: робить PUID і PGID неактивними, припиняє роботу Docker Mods і користувацьких служб, а права доступу до кожного змонтованого тому стають вашою відповідальністю.

Sonarr має правильний PUID, але все одно не може переміщувати файли. У чому проблема?

Перевірте послідовно три речі. По-перше, саме монтування медіафайлів: скрипт налаштування користувача базового образу змінює власника для /app, /config і /defaults, тому /data або /downloads зберігає права власності, установлені на хості. По-друге, спільну групу: призначте контейнерам, які мають доступ до дерева медіафайлів, однакове значення PGID і права запису для групи. По-третє, umask: ефективна маска 022 створює файли 0644, коли застосунок запитує 0666 і не застосовується ACL за замовчуванням. У такому разі інші контейнери групи можуть читати ці файли, але не змінювати їх. Якщо залишити UMASK невстановленим, це не гарантує певну маску або режим доступу до файлів. Установіть UMASK=002 і встановіть біт setgid для каталогів за допомогою chmod 2775, щоб нові файли успадковували групу. Застосунок, який запитує 0600, усе одно створює приватні файли, а ACL за замовчуванням змінює спосіб призначення прав під час створення.

Чи була ця стаття корисною?