SSD Nodes Learn Hosting plans →
คู่มือ Matt Connorโดย Matt Connor

PUID และ PGID ใน Docker Compose คืออะไรและตั้งค่าอย่างไร

PUID และ PGID ไม่ใช่การตั้งค่าของ Docker แต่เป็นข้อตกลงของ linuxserver.io เพื่อจัดการสิทธิ์ไฟล์บน Host เรียนรู้วิธีแก้ไขปัญหาไฟล์ติดสิทธิ์ 911:911 ให้เป็นผู้ใช้ปัจจุบัน

PUID และ PGID คืออะไร

PUID และ PGID คือตัวแปรสภาพแวดล้อม (environment variables) สองตัวที่ container image บางตัวจะอ่านค่าเมื่อเริ่มทำงาน ตัว Docker เองไม่ได้ตรวจสอบค่าเหล่านี้ แต่เป็นธรรมเนียมที่ใช้ใน image ของ linuxserver.io และ image อื่นๆ อีกจำนวนหนึ่ง ดังนั้นหาก image ไม่ได้ถูกเขียนมาให้รองรับตัวแปรเหล่านี้ มันก็จะเพิกเฉยต่อค่าดังกล่าวโดยไม่มีการแจ้งเตือน

ภายใน image ของ linuxserver.io จะมีผู้ใช้ชื่อ abc ซึ่งถูกสร้างขึ้นในขั้นตอน build โดยมี UID (user ID) เป็น 911 และ GID (group ID) เป็น 911 ตัว container จะเริ่มทำงานด้วยสิทธิ์ root จากนั้นจะรันสคริปต์เริ่มต้น (init scripts) และหนึ่งในสคริปต์เหล่านั้นจะทำการเปลี่ยนหมายเลข UID/GID ของผู้ใช้ดังกล่าวก่อนที่แอปพลิเคชันจะเริ่มทำงาน:

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

แฟล็ก -o อนุญาตให้ใช้ ID ที่มีการใช้งานอยู่แล้วในที่อื่นได้ หลังจากนั้นกระบวนการ init จะลดสิทธิ์ลงและรันแอปพลิเคชันในฐานะผู้ใช้ abc ดังนั้น Docker จึงเพียงแค่ส่งผ่าน PUID=1000 เข้าไปใน container เหมือนกับตัวแปรสภาพแวดล้อมอื่นๆ และไม่ได้ดำเนินการใดๆ กับมัน ตัวแปรนี้จะทำหน้าที่เปลี่ยนหมายเลขผู้ใช้ภายใน container ก่อนที่แอปพลิเคชันจะเริ่มทำงาน ซึ่งหมายความว่าบน daemon แบบ rootful มาตรฐานที่ไม่มีการทำ user namespace remapping ไฟล์ที่ถูกสร้างขึ้นใหม่มักจะมีเจ้าของเป็น 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 ที่สูงขึ้น หากบริการของคุณรันภายใต้ บัญชีผู้ใช้สำหรับบริการโดยเฉพาะแทนที่จะเป็นบัญชีล็อกอินของคุณเอง ให้รัน 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 ในรายการนั้นยังเป็นไฟล์ที่เก็บการตั้งค่าการยืนยันตัวตน ซึ่งมีความสำคัญในครั้งแรกที่คุณเปิดเว็บ UI และพบว่า Sonarr และ Radarr ไม่ได้กำหนดชื่อผู้ใช้หรือรหัสผ่านเริ่มต้นมาให้ ให้ยืนยันจากภายในคอนเทนเนอร์แทนการคาดเดา:

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

กระบวนการเริ่มต้นของ linuxserver จะพิมพ์ผลลัพธ์ใน log การเริ่มระบบเป็นสองบรรทัด:

User UID:    911
User GID:    911

หากบรรทัดเหล่านั้นแสดงค่า 911 หลังจากที่คุณตั้งค่า PUID=1000 ในไฟล์ Compose ของคุณ แสดงว่าคอนเทนเนอร์ที่กำลังทำงานอยู่ไม่ได้ใช้ค่าที่คุณตั้งไว้ สาเหตุทั่วไปคือคุณแก้ไขไฟล์ docker-compose.yml แล้วรันคำสั่ง docker compose restart ซึ่งเป็นการนำคอนเทนเนอร์เดิมที่มี environment เดิมกลับมาใช้ใหม่ การเปลี่ยนแปลง environment จำเป็นต้องใช้คำสั่ง docker compose up -d ซึ่งจะสร้างคอนเทนเนอร์ขึ้นมาใหม่ อีกสาเหตุหนึ่งคือความตั้งใจของระบบ: เมื่ออิมเมจทำงานในโหมดอ่านอย่างเดียว (read-only) หรือโหมดไม่ใช้สิทธิ์ root (non-root) กระบวนการเริ่มต้นจะข้ามการเปลี่ยนหมายเลขไปโดยสิ้นเชิง แม้ว่าตัวแปรจะปรากฏอยู่ในคอนเทนเนอร์ก็ตาม ในโหมดอ่านอย่างเดียว แบนเนอร์จะรายงาน ID เดิมของ abc และในโหมดไม่ใช้สิทธิ์ root จะรายงานเจ้าของไฟล์ /run

เหตุผลที่คุณไม่สามารถลบไฟล์ที่คอนเทนเนอร์สร้างขึ้นได้

Kernel จะเปรียบเทียบตัวเลข ไม่ใช่ชื่อ Shell ของคุณทำงานในฐานะ UID 1000 แต่ไฟล์นั้นเป็นของ UID 911 ไดเรกทอรีที่เก็บไฟล์ดังกล่าวคือ drwxr-xr-x และเป็นของ 911 เช่นกัน ดังนั้นกลุ่ม (group) และผู้อื่น (other) จึงมีสิทธิ์อ่านและเรียกใช้งาน (read and execute) แต่ไม่มีสิทธิ์เขียน (write) การลบไฟล์ต้องใช้สิทธิ์เขียนบน ไดเรกทอรี ที่เก็บไฟล์นั้น ไม่ใช่ที่ตัวไฟล์เอง คุณจึงพบข้อผิดพลาดนี้แม้ว่าตัวไฟล์จะดูไม่มีอันตรายก็ตาม:

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

คอนเทนเนอร์ที่พยายามเขียนไฟล์จะเจอปัญหาเดียวกันจากอีกฝั่ง หากไดเรกทอรีบนโฮสต์เป็นของผู้ใช้ของคุณด้วยโหมด 755 และแอปพลิเคชันทำงานในฐานะ 911 การเขียนครั้งแรกจะล้มเหลวด้วย Permission denied และแอปจะรายงานข้อผิดพลาดในรูปแบบของตนเอง ในแอปพลิเคชัน .NET เช่น Sonarr หรือ Radarr ข้อผิดพลาดนี้จะแสดงเป็น UnauthorizedAccessException: Access to the path '/data/downloads' is denied สตริงสิทธิ์ที่อยู่หน้าชื่อไฟล์จะบอกคุณว่าคุณกำลังถูกตัดสินด้วยชุดสิทธิ์ใดในสามชุด และการ อ่าน drwxr-xr-x อย่างถูกต้อง คือสิ่งที่เปลี่ยนข้อผิดพลาดที่ดูซับซ้อนให้กลายเป็นเรื่องที่เข้าใจได้ทันที

นี่เป็นปัญหาที่เกิดจาก bind mount โดยเฉพาะ เมื่อ Docker สร้าง named volume ว่าง และ mount ทับ path ที่มีอยู่แล้วใน image มันจะคัดลอกเนื้อหาของ path นั้นลงใน volume รวมถึงความเป็นเจ้าของและบิตสิทธิ์ต่างๆ ทำให้แอปพลิเคชันพบไดเรกทอรีที่ตนเองเป็นเจ้าของอยู่แล้ว แต่ bind mount จะไม่ได้รับการจัดการในลักษณะนั้น Docker จะ mount ไดเรกทอรีบนโฮสต์ของคุณตามสภาพที่เป็นอยู่จริง ความแตกต่างนี้เป็นหนึ่งในเหตุผลเชิงปฏิบัติที่คุณควรทราบว่า เมื่อใดที่ bind mount ดีกว่า named volume และเมื่อใดที่ไม่ใช่

การแก้ไขไดเรกทอรีที่ตั้งค่าไว้ไม่ถูกต้อง

การตั้งค่า PUID และ PGID จะส่งผลต่อการทำงานของแอปพลิเคชันนับจากนี้เป็นต้นไป การตั้งค่านี้จะไม่แก้ไขสิทธิ์ของไฟล์ที่มีอยู่เดิมบนดิสก์ย้อนหลัง แม้ว่า init จะแก้ไขความเป็นเจ้าของในบาง path ตามที่ระบุไว้ด้านล่างก็ตาม ให้หยุดการทำงานของ 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 แบบ recursive อาจทำให้โครงสร้างไดเรกทอรีถูกแก้ไขเพียงบางส่วน และนำไปสู่ข้อผิดพลาดรอบสองที่สร้างความสับสนได้

สิ่งที่ PUID และ PGID แก้ไขไม่ได้

นี่คือส่วนที่ทำให้ผู้ที่ทำตามขั้นตอนทุกอย่างถูกต้องต้องประสบปัญหา สคริปต์ตั้งค่าผู้ใช้ของ base image จาก linuxserver จะทำการ chown เส้นทาง 3 แห่งเมื่อเริ่มทำงาน ได้แก่ /app, /config และ /defaults โดยที่ mount point ของสื่อบันทึกข้อมูลของคุณไม่ได้อยู่ในรายการดังกล่าว เส้นทาง /data, /downloads และ /tv จะถูกส่งต่อไปยังแอปพลิเคชันโดยไม่มีการเปลี่ยนแปลง ดังนั้นหากฝั่งโฮสต์ของ mount เหล่านั้นมีสิทธิ์ความเป็นเจ้าของที่ผู้ใช้ในคอนเทนเนอร์ไม่สามารถเขียนข้อมูลลงไปได้ คอนเทนเนอร์จะเริ่มทำงานได้อย่างปกติ แสดง UID ที่ถูกต้องใน banner แต่จะล้มเหลวเมื่อเริ่มการนำเข้าข้อมูลครั้งแรก

นั่นคือพฤติกรรมที่ถูกต้องแล้ว การทำ chown แบบ recursive กับคลังสื่อขนาด 12 เทราไบต์ทุกครั้งที่คอนเทนเนอร์เริ่มทำงานจะเป็นหายนะอย่างยิ่ง ซึ่งหมายความว่าไดเรกทอรีสื่อบันทึกข้อมูลเป็นหน้าที่ของคุณในการดูแล และเป็นจุดที่มักเกิดปัญหาเรื่องสิทธิ์การเข้าถึง เนื่องจากความล้มเหลวประเภทนี้มักปรากฏเงียบๆ ใน log ของแอปพลิเคชันหลังจากที่คอนเทนเนอร์ดูเหมือนทำงานปกติไปแล้วหลายชั่วโมง การทดสอบการเขียนข้อมูลเป็นระยะโดยเชื่อมต่อเข้ากับ ntfy บน VPS ของคุณเอง เพื่อส่งการแจ้งเตือนไปยังโทรศัพท์ จึงเป็นวิธีที่ประหยัดในการรับทราบปัญหาก่อนที่จะเกิดกรณีรายการตอนต่างๆ หายไปนานถึงหนึ่งสัปดาห์โดยไม่รู้ตัว

สามวิธีในการควบคุมผู้ใช้และสถานการณ์ที่ควรใช้แต่ละวิธี

ตัวแปรสภาพแวดล้อม PUID และ PGID

วิธีนี้ใช้ได้เฉพาะกับอิมเมจที่ entrypoint อ่านค่าตัวแปรเหล่านี้เท่านั้น วิธีนี้เป็นที่นิยมเพราะคอนเทนเนอร์ยังคงเริ่มทำงานด้วยสิทธิ์ root เพื่อดำเนินการตั้งค่าต่างๆ แก้ไข /config และลดสิทธิ์ลงในภายหลัง Docker Mods และสคริปต์ init แบบกำหนดเองยังคงทำงานได้ตามปกติ ข้อเสียคือคุณต้องเชื่อถือในธรรมเนียมปฏิบัติมากกว่าฟีเจอร์ของแพลตฟอร์ม และชื่อตัวแปรเหล่านี้ไม่ได้เป็นมาตรฐานเดียวกันในทุกโปรเจกต์

คีย์ user: ใน Compose

นี่คือฟีเจอร์จริงของ Docker และใช้งานได้กับทุกอิมเมจ เนื่องจาก container runtime จะนำไปใช้ก่อนที่โค้ดของอิมเมจจะเริ่มทำงาน:

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

กระบวนการทำงานจะไม่รันในฐานะ root เลยแม้แต่วินาทีเดียว ซึ่งถือเป็นการเพิ่มความปลอดภัยอย่างแท้จริง นอกจากนี้ยังทำให้สิ่งที่อยู่ใน entrypoint ซึ่งจำเป็นต้องใช้สิทธิ์ root ทำงานไม่ได้ สำหรับอิมเมจของ linuxserver ทางโปรเจกต์รองรับวิธีนี้ตามความเหมาะสมและเฉพาะอิมเมจที่ผ่านการทดสอบแล้วเท่านั้น โดยมีข้อควรระวังเฉพาะคือ: PUID และ PGID จะไม่มีผลใดๆ, Docker Mods จะไม่ทำงาน, บริการแบบกำหนดเองจะไม่ทำงาน และคุณต้องรับผิดชอบสิทธิ์การเข้าถึงในทุก volume ที่ mount ไว้ รูปแบบที่แนะนำตามเอกสารคือการใช้ flag นี้คู่กับ /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 ทั้งที่ ID นั้นถูกต้องและสามารถเข้าถึงไฟล์ได้ตามปกติ เพียงแต่การค้นหาชื่อผู้ใช้ไม่สำเร็จเท่านั้น

Rootless Docker

Rootless Docker จะรัน daemon ในฐานะผู้ใช้ที่ไม่มีสิทธิ์ (unprivileged user) ของคุณเอง ดังนั้นทั้ง daemon และคอนเทนเนอร์จึงทำงานโดยไม่มีสิทธิ์ root ของโฮสต์ มันเปลี่ยนวิธีการคำนวณความเป็นเจ้าของไปโดยสิ้นเชิง โดย UID 0 ในคอนเทนเนอร์จะ map ไปยัง UID ของผู้ใช้ที่รัน rootless Docker บนโฮสต์ และ UID n ในคอนเทนเนอร์สำหรับ n ใดๆ ที่มีค่าตั้งแต่ 1 ขึ้นไป จะ map ไปยัง subuid + (n - 1) โดยที่ subuid คือค่าเริ่มต้นของช่วงที่ถูกจัดสรรให้คุณใน /etc/subuid ส่วน group ID จะใช้กฎเดียวกันโดยใช้ /etc/subgid ซึ่ง Docker คาดหวังว่าจะมี subordinate ID อย่างน้อย 65,536 รายการในส่วนนั้น

โปรดอ่านการ mapping นี้อีกครั้ง เพราะมันกลับตรรกะจากคำแนะนำทั่วไป ภายใต้ rootless Docker การที่คอนเทนเนอร์สร้างไฟล์ในฐานะ root จะได้ไฟล์ที่เป็นของคุณโดยปกติ แต่การที่คอนเทนเนอร์สร้างไฟล์ในฐานะ UID 1000 จะได้ไฟล์ที่เป็นของ subordinate ID เช่น 100999 เมื่อช่วงเริ่มต้นที่ 100000 การเข้าถึงผ่าน shell ของคุณขึ้นอยู่กับสิทธิ์และ ACL ส่วนการลบไฟล์มักขึ้นอยู่กับไดเรกทอรีที่บรรจุไฟล์นั้น ดังนั้นคุณจึงสามารถลบไฟล์ดังกล่าวได้จากไดเรกทอรีที่คุณควบคุมอยู่ ดังนั้นค่า PUID ที่ถูกต้องบน rootful daemon จึงเป็นค่าที่ผิดในกรณีนี้ กลไกทั้งสองเปลี่ยนความเป็นเจ้าของในระดับที่ต่างกัน และการใช้ทั้งสองอย่างร่วมกันโดยไม่ตรวจสอบอาจทำให้คุณไม่สามารถเขียนข้อมูลลงใน volume ที่ mount ไว้ได้ หากคุณเลือกใช้ rootless ให้ทดสอบความเป็นเจ้าของของไฟล์ที่เขียนขึ้นบนเซิร์ฟเวอร์ของคุณเองก่อนที่จะย้าย library เข้าไป

สำหรับ stack ส่วนใหญ่ที่ self-host บน VPS เดียวกัน การใช้ PUID และ PGID บน rootful daemon เป็นทางเลือกที่ใช้งานได้จริง เพราะเป็นสิ่งที่อิมเมจส่วนใหญ่ถูกสร้างและจัดทำเอกสารไว้ ให้เลือกใช้ user: เมื่อ README ของอิมเมจระบุว่าผ่านการทดสอบสำหรับวิธีนี้แล้ว หรือเมื่อคุณรันอิมเมจต้นทางที่เป็นทางการซึ่งไม่มีการรองรับ PUID เลย พื้นที่ทำงานเอกสารอย่าง อินสแตนซ์ AFFiNE ที่ self-host บน VPS เดียว จัดอยู่ในกรณีหลัง เนื่องจากไม่มีคอนเทนเนอร์ใดอ่านค่า PUID และความเป็นเจ้าของไดเรกทอรีฐานข้อมูลและไฟล์ที่อัปโหลดจะถูกกำหนดโดย runtime แทนที่จะเป็นสิ่งที่อยู่ใน environment block เช่นเดียวกับ ระบบสนับสนุน Chatwoot ที่ self-host ซึ่งคอนเทนเนอร์ Rails และ worker ของ Sidekiq ต่างเขียนข้อมูลลงในไดเรกทอรี uploads เดียวกันและไม่มีตัวใดอ่านค่า PUID ดังนั้นไดเรกทอรีนั้นจึงต้องตรงกับผู้ใช้ที่อิมเมจนั้นรันอยู่แล้ว สิ่งเหล่านี้ไม่เปลี่ยนแปลงสำหรับ stack ใหม่ ดังนั้น การให้ทุกคนในทีมมี OneCLI agent แบบ sandboxed ของตนเอง จึงทำให้ไดเรกทอรีพื้นที่ทำงานของแต่ละคนและไดเรกทอรีข้อมูล Postgres เป็นของผู้ใช้ที่แต่ละอิมเมจรันอยู่แล้ว ซึ่งกลายเป็นปัญหาเรื่อง user: และ chown มากกว่าเรื่อง PUID หากคุณ วาง API ที่ self-host ไว้หน้า Codex, Claude Code และ Hermes ตัว entrypoint ของมันจะจัดการหลายตัวตน: คอนเทนเนอร์ต้องเริ่มด้วย root, คอนโซลและเกตเวย์รันด้วยผู้ใช้ที่ไม่มีสิทธิ์ และแต่ละเซสชันของ agent รันด้วยผู้ใช้ของตนเอง อย่าเพิ่ม user: เข้าไปในการปรับใช้ดังกล่าว เพราะ entrypoint ของมันจัดการความเป็นเจ้าของของ data volume อยู่แล้ว

กรณีศึกษา media stack: การใช้กลุ่มผู้ใช้ร่วมกันระหว่างคอนเทนเนอร์

arr media stack ที่ประกอบด้วย Sonarr, Radarr และโปรแกรมดาวน์โหลด คือจุดที่ทฤษฎีนี้ถูกนำมาใช้งานจริง โปรแกรมดาวน์โหลดจะเขียนไฟล์ที่เสร็จสมบูรณ์ลงใน /data/downloads จากนั้น Sonarr จะทำการ hardlink หรือย้ายไฟล์นั้นไปยัง /data/media เพื่อให้การทำ hardlink สำเร็จ คอนเทนเนอร์ทั้งสองต้องมีสิทธิ์เขียนในโครงสร้างไดเรกทอรีเดียวกัน หากโปรแกรมดาวน์โหลดรันด้วย UID 1000 ในขณะที่ Sonarr รันด้วย 1001 โดยไม่มีสิทธิ์เขียนของกลุ่ม (group write permissions) ร่วมกัน ไฟล์ที่สร้างขึ้นจะถูกครอบครองโดยผู้ใช้คนใดคนหนึ่ง และอีกฝั่งจะทำได้เพียงแค่อ่านเท่านั้น

วิธีแก้ไขคือการสร้างกลุ่มร่วมที่ทุกคอนเทนเนอร์ใน stack ใช้เป็น 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 bit สำหรับไดเรกทอรีแล้ว มันหมายความว่าไฟล์และไดเรกทอรีย่อยใหม่ทุกรายการที่ถูกสร้างขึ้นภายใน จะสืบทอดกลุ่ม media แทนที่จะเป็นกลุ่มหลักของผู้สร้าง ดังนั้นการตั้งค่านี้จึงคงอยู่แม้มีการดาวน์โหลดไฟล์ใหม่โดยที่คุณไม่ต้องรัน chown ซ้ำ ให้ทำการออกจากระบบแล้วล็อกอินใหม่ หรือรันคำสั่ง newgrp media ก่อนตรวจสอบสิทธิ์ของคุณเอง เนื่องจากกลุ่มที่เพิ่มด้วย usermod -aG จะไม่ปรากฏใน shell session ที่เปิดค้างไว้

ภายในคอนเทนเนอร์ groupmod -o -g 13000 abc จะเปลี่ยนหมายเลขกลุ่ม abc เป็น 13000 เพื่อให้ abc เขียนไฟล์ด้วย GID เดียวกับกลุ่ม media บนโฮสต์ของคุณ คอนเทนเนอร์ linuxserver ทุกตัวที่เข้าถึงโครงสร้างนี้จะยังคงใช้ PUID ของตนเอง แต่ใช้ PGID เดียวกันนี้ร่วมกัน ซึ่งรวมถึงคอนเทนเนอร์ที่อยู่ถัดไปในสายงานที่ทำหน้าที่เพียงแค่อ่านคลังสื่อ เช่น Jellyfin เอง ส่วน front end อย่าง Halcyon ซึ่งให้บริการคลังสื่อนั้นในรูปแบบร้านวิดีโอสไตล์ยุค 90 จะเชื่อมต่อกับ Jellyfin ผ่าน HTTP โดยใช้ HALCYON_JELLYFIN_URL ซึ่งการติดตั้งใช้งานมาตรฐานไม่จำเป็นต้องใช้ PGID ของ media หรือการ mount ไดเรกทอรีสื่อแต่อย่างใด

จากนั้นตั้งค่า UMASK=002 ในคอนเทนเนอร์ linuxserver ทุกตัวใน stack นี่คือขั้นตอนที่คนมักมองข้าม หากไม่ตั้งค่าไว้ แอปพลิเคชันจะใช้ umask ที่สืบทอดมาจนกว่าจะมีสิ่งอื่นมาเปลี่ยนมัน และค่าตัวอย่างที่แสดงใน README ของอิมเมจคือ UMASK=022 ด้วย umask ที่มีผลเป็น 022 แอปพลิเคชันที่ร้องขอ 0666 สำหรับไฟล์ใหม่จะได้ 0644 เมื่อไม่มี default ACL: สมาชิกกลุ่มที่เหลือจะอ่านได้แต่แก้ไขไม่ได้ ซึ่งจะทำลายการตั้งค่าการแชร์ที่คุณเพิ่งกำหนดไว้ แต่ด้วย 002 และไม่มี default ACL แอปพลิเคชันที่ร้องขอ 0666 สำหรับไฟล์และ 0777 สำหรับไดเรกทอรี จะได้ไฟล์เป็น 0664 และสำหรับไดเรกทอรีที่อยู่ในโครงสร้าง setgid จะได้เป็น 2775 ซึ่งทำให้กลุ่มสามารถเขียนได้ umask จะทำหน้าที่ลบสิทธิ์ออกเท่านั้น ดังนั้นแอปพลิเคชันที่ขอ 0600 จะยังคงได้ 0600 และไดเรกทอรีที่มี default 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 เพื่อให้ทั้ง stack อ่านคำจำกัดความเดียวกัน:

PUID=1000
PGID=13000

Compose จะอ่านไฟล์นั้นโดยอัตโนมัติสำหรับการแทนที่ค่าแบบ ${PUID} ซึ่งเป็นกลไกเดียวกับที่คุณใช้สำหรับข้อมูลรับรอง (credentials) นิสัยในการ เก็บค่าต่างๆ ไว้ในไฟล์ .env แทนที่จะใส่ใน docker-compose.yml สามารถนำมาใช้ที่นี่ได้เช่นกัน โดยมีความแตกต่างตรงที่ตัวเลขสองค่านี้ไม่ใช่ความลับ

ตรวจสอบการทำงานตั้งแต่ต้นจนจบแทนที่จะเชื่อใจการตั้งค่าเพียงอย่างเดียว ให้เขียนไฟล์ใหม่ในฐานะผู้ใช้ของแอปพลิเคชันโดยใช้ 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 bit (คือ s ใน drwxrwsr-x) หายไปจากไดเรกทอรีนั้น หรือไดเรกทอรียังคงเป็นของกลุ่ม 1000 แทนที่จะเป็น media ซึ่งคำสั่ง chown และ chmod 2775 ด้านบนจะแก้ไขปัญหาทั้งสองอย่าง หากโหมดแสดงเป็น -rw-r--r-- ให้ตรวจสอบค่า UMASK ของคอนเทนเนอร์และ default ACL ของไดเรกทอรี หากสภาพแวดล้อมของคอนเทนเนอร์เก่าเกินไปให้สร้างใหม่ การทดสอบนี้ตรวจสอบการสร้างไฟล์ในฐานะ abc ด้วย mask ที่กำหนดไว้ โหมดการสร้างไฟล์และ 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 จึงเป็นการตัดสินใจด้วยว่าคุณจะต้องดูแลกลไกใดในบรรดากลไกเหล่านี้สำหรับคลังข้อมูลขนาดใหญ่ที่สุดบนเซิร์ฟเวอร์ อิมเมจต้นทางที่เป็นทางการหลายตัว รวมถึงอิมเมจฐานข้อมูลและเว็บเซิร์ฟเวอร์ทั่วไป มักกำหนดผู้ใช้แบบตายตัวมาให้และคาดหวังให้คุณใช้ user: หรือปล่อยให้เป็นค่าเริ่มต้น การติดตั้งแอปขนาดเล็กเพียงแอปเดียวก็ทำให้เกิดคำถามเดียวกัน ดังนั้นเมื่อคุณเริ่มใช้งาน ระบบติดตามการออกกำลังกาย openGym แบบ self-hosted ควรตรวจสอบก่อนว่าคอนเทนเนอร์นั้นรันด้วยผู้ใช้ใดก่อนที่จะกำหนด bind mount เข้าไป เพราะไดเรกทอรีที่เก็บฐานข้อมูลจะสืบทอดสิทธิ์นั้นมาไม่ว่าคุณจะตั้งค่า PUID ไว้หรือไม่ก็ตาม ระบบรีเลย์สำหรับการเข้าถึงระยะไกลก็อยู่ในหมวดหมู่เดียวกัน ดังนั้นเมื่อ คุณรันเซิร์ฟเวอร์รีเลย์ RustDesk ของตนเอง คู่กุญแจ Ed25519 ที่ hbbs สร้างขึ้นในการเริ่มทำงานครั้งแรกจะถูกเขียนลงใน bind mount ของคุณด้วยสิทธิ์ของผู้ใช้ที่อิมเมจนั้นกำหนดไว้ คุณสามารถแก้ไขสิทธิ์ภายหลังได้ด้วยคำสั่ง chown บนโฮสต์ หรือเลือกตัวตนตั้งแต่ต้นด้วยคีย์ user: เนื่องจากอิมเมจดังกล่าวไม่ได้กำหนดผู้ใช้ไว้ล่วงหน้า ตราบใดที่ไดเรกทอรีที่ mount สามารถเขียนได้โดย ID ที่คุณเลือก กรณีนี้ยังใช้กับโครงสร้างพื้นฐานที่คุณเพิ่มเข้ามาภายหลังด้วย เช่น การติดตั้ง Authentik ไว้หน้าแอปของคุณเพื่อทำ single login หมายถึงการรันอิมเมจ Authentik และ Postgres อย่างเป็นทางการซึ่งไม่อ่านค่า PUID เลย และความเป็นเจ้าของของ volume จะมาจากผู้ใช้ที่กระบวนการเหล่านั้นรันอยู่และการตั้งค่าที่ entrypoint ดำเนินการ โดย Authentik ได้นำการพึ่งพา Redis ออกไปในรุ่น 2025.10

ดังนั้น โปรดตรวจสอบ README ของแต่ละอิมเมจก่อนที่คุณจะคัดลอกบล็อก environment ไปใช้ระหว่างโปรเจกต์ Docker จะส่งผ่านตัวแปร environment ใดก็ตามที่คุณตั้งค่าเข้าไปในคอนเทนเนอร์ ไม่ว่าจะมีสิ่งใดภายในอ่านค่าเหล่านั้นหรือไม่ก็ตาม และการตั้งค่า PUID ที่ไม่มีกระบวนการใดใช้งานจะไม่ทำให้เกิดข้อผิดพลาด คำเตือน หรือผลลัพธ์ใดๆ คอนเทนเนอร์จะเริ่มทำงานในฐานะผู้ใช้ที่เลือกโดยการตั้งค่า user: ของ Docker หรือที่ระบุใน Dockerfile จากนั้น entrypoint อาจลดระดับสิทธิ์ก่อนเริ่มแอปพลิเคชัน โปรดอ่านข้อมูลเหล่านั้นก่อนที่คุณจะเพิ่มสิ่งใหม่ลงในเซิร์ฟเวอร์ รวมถึง ชุดเครื่องมือสแกนความปลอดภัย open-kritt แบบ self-hosted ซึ่งไฟล์ Compose จะบอกคุณว่าอิมเมจเหล่านั้นรองรับ PUID หรือไม่ หรือความเป็นเจ้าของไดเรกทอรีที่คุณ mount ถูกกำหนดไว้ตายตัวโดยตัวอิมเมจเอง

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 image หรือไม่?

ไม่สามารถใช้ได้กับทุกอิมเมจ เนื่องจากไม่ใช่ฟีเจอร์ของ 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 และบริการที่กำหนดเอง และทำให้สิทธิ์ของทุก volume ที่ mount ไว้กลายเป็นความรับผิดชอบของคุณโดยตรง

Sonarr มี PUID ที่ถูกต้องแล้วแต่ยังย้ายไฟล์ไม่ได้ เกิดอะไรขึ้น?

ให้ตรวจสอบสามสิ่งตามลำดับ ดังนี้: ประการแรก คือตัว media mount เอง: สคริปต์ตั้งค่าผู้ใช้ของอิมเมจหลักจะทำการ chown เฉพาะ /app, /config และ /defaults เท่านั้น ดังนั้น /data หรือ /downloads จะยังคงความเป็นเจ้าของเดิมที่มีอยู่บนโฮสต์ ประการที่สอง คือกลุ่มที่ใช้ร่วมกัน: ให้คอนเทนเนอร์ที่เข้าถึงโครงสร้างสื่อข้อมูลมี PGID เดียวกันและมีสิทธิ์เขียนสำหรับกลุ่ม ประการที่สาม คือ umask: ค่า mask ที่มีผลเป็น 022 จะสร้างไฟล์ที่มีสิทธิ์ 0644 เมื่อแอปพลิเคชันร้องขอ 0666 และไม่มี default ACL ใดๆ นำมาใช้ ส่งผลให้คอนเทนเนอร์อื่นในกลุ่มสามารถอ่านไฟล์ได้แต่ไม่สามารถแก้ไขได้ การปล่อยให้ UMASK ไม่ถูกตั้งค่าไว้ไม่ได้รับประกันว่าจะมี mask หรือ file mode ที่เฉพาะเจาะจง ให้ตั้งค่า UMASK=002 และตั้งค่า setgid bit บนไดเรกทอรีด้วย chmod 2775 เพื่อให้ไฟล์ใหม่สืบทอดกลุ่มมาด้วย แอปพลิเคชันที่ร้องขอ 0600 จะยังคงสร้างไฟล์ส่วนตัว และ default ACL จะเปลี่ยนวิธีการกำหนดสิทธิ์ในการสร้างไฟล์

บทความนี้มีประโยชน์หรือไม่