เลือกใช้ Python venv, pipx หรือ uv บนเซิร์ฟเวอร์อย่างไรดี
แก้ไขปัญหา pip install ล้มเหลวด้วยข้อผิดพลาด externally-managed-environment บน Ubuntu 24.04 เรียนรู้วิธีเลือกเครื่องมือจัดการแพ็กเกจที่เหมาะสมและตั้งค่าผ่าน systemd
เหตุใด pip install จึงล้มเหลวบนเซิร์ฟเวอร์ Ubuntu ที่ติดตั้งใหม่
การเลือกระหว่าง Python venv, pipx และ uv บนเซิร์ฟเวอร์ขึ้นอยู่กับคำถามเดียวคือ คุณกำลังติดตั้งอะไร? dependency ของแอปพลิเคชันควรอยู่ใน virtual environment ภายในไดเรกทอรีของแอปพลิเคชันนั้นๆ ส่วนเครื่องมือบรรทัดคำสั่งที่คุณต้องการเรียกใช้งานด้วยชื่อควรติดตั้งผ่าน pipx สำหรับ uv นั้นสามารถทำงานได้ทั้งสองอย่างและเพิ่ม lockfile เข้ามา ซึ่งจะเริ่มมีความสำคัญทันทีเมื่อต้องสร้าง environment เดียวกันบนเครื่องที่สอง สิ่งที่เครื่องมือเหล่านี้ไม่ทำคือการติดตั้งลงใน Python ของระบบ เพราะเซิร์ฟเวอร์ Ubuntu รุ่นปัจจุบันปฏิเสธการกระทำดังกล่าวโดยสิ้นเชิง
หากรัน sudo pip install requests บน Ubuntu 24.04 ตัว pip จะหยุดทำงานก่อนที่จะดาวน์โหลดไฟล์แม้แต่ไฟล์เดียว
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.
If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip.
If you wish to install a non-Debian packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you.
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this behaviour by passing --break-system-packages.นี่คือการทำงานตาม PEP 668 (Python enhancement proposal 668, "externally managed environments") โดย Debian และ Ubuntu จะวางไฟล์เครื่องหมายไว้ข้างตัวแปลภาษาที่ /usr/lib/python3.12/EXTERNALLY-MANAGED และ pip จะปฏิเสธการเขียนข้อมูลลงในตัวแปลภาษาใดก็ตามที่มีไฟล์นี้อยู่
กฎนี้มีไว้เพื่อรักษาลำดับของ sys.path โดย apt จะติดตั้งไลบรารีไว้ที่ /usr/lib/python3/dist-packages ส่วน pip ที่รันด้วยสิทธิ์ root กับตัวแปลภาษาของระบบจะเขียนข้อมูลลงใน /usr/local/lib/python3.12/dist-packages และการจัดการแพ็กเกจของ Debian จะวางไดเรกทอรีนั้นไว้ก่อนในลำดับการค้นหา คุณสามารถตรวจสอบลำดับได้ด้วยการรัน python3 -c 'import sys; print(sys.path)' เพื่อดูผลลัพธ์ ดังนั้นสำเนาที่ pip เขียนลงไปจะทับซ้อนกับสำเนาที่ apt ติดตั้งไว้ สำหรับทุกโปรแกรมบนเครื่องที่รันภายใต้ /usr/bin/python3 รวมถึงเครื่องมือของตัว distribution เอง ตัวอย่างเช่น cloud-init จะ import requests, jinja2 และ PyYAML จากตัวแปลภาษานั้น หากคุณอัปเกรดแพ็กเกจเหล่านี้ด้วย pip แล้วได้เวอร์ชันที่ไม่เข้ากัน สิ่งที่คุณไม่เคยแตะต้องอาจล้มเหลวในการบูตครั้งถัดไปพร้อมกับ traceback ที่ระบุชื่อแพ็กเกจที่คุณไม่ทราบมาก่อนว่าอยู่ในห่วงโซ่การทำงาน ในขณะที่ apt ยังคงบันทึกว่าเวอร์ชันของตนเองถูกติดตั้งอยู่ จึงไม่มีการแจ้งเตือนใดๆ วิธีแก้ไขคือการลบสำเนาของ pip ออกด้วย sudo pip uninstall --break-system-packages requests เพราะการใช้ sudo apt reinstall python3-requests เพียงอย่างเดียวจะเป็นการเขียนทับเฉพาะสำเนาของ apt ที่ถูกทับซ้อนอยู่แล้วเท่านั้น
กฎที่ตามมานั้นสั้นและชัดเจน Python ของระบบเป็นของตัว distribution ห้ามติดตั้งลงในนั้น ห้ามอัปเกรดไลบรารีด้วย pip และห้ามลบไฟล์ EXTERNALLY-MANAGED เพื่อให้ข้อความแจ้งเตือนหายไป หน้าที่เดียวที่ควรให้ /usr/bin/python3 ทำคือการสร้าง virtual environments เท่านั้น
เกณฑ์การตัดสินใจเลือกใช้ venv, pipx และ uv
ให้เลือกเครื่องมือตามประเภทของสิ่งที่คุณกำลังติดตั้ง ไม่ใช่เลือกตามเครื่องมือที่คุณเพิ่งอ่านเจอมาล่าสุด
- แอปพลิเคชันที่คุณนำไปใช้งานและรันเป็น service เช่น โปรเจกต์ Django หรือ Flask: ให้ใช้ virtual environment (venv) หนึ่งชุดภายในไดเรกทอรีของแอปพลิเคชันนั้น
- เครื่องมือบรรทัดคำสั่ง (command-line tool) ที่คุณต้องการเรียกใช้บน
PATHของคุณ เช่นansibleหรือhttpie: ให้ใช้ pipx ซึ่งจะสร้างสภาพแวดล้อมส่วนตัวให้แต่ละเครื่องมือและสร้างลิงก์ไว้บนPATH - โปรเจกต์ที่ต้องการ lockfile, การติดตั้งที่รวดเร็วขึ้น หรือเวอร์ชัน Python ที่ไม่มีใน distribution: ให้ใช้ uv ซึ่งจะสร้าง venv ปกติควบคู่ไปกับไฟล์
uv.lock - ไลบรารีที่เครื่องมือของระบบจำเป็นต้องใช้ (ไม่ใช่ไลบรารีสำหรับโค้ดของคุณ): ให้ใช้
sudo apt install python3-<name>ซึ่งเป็นวิธีเดียวที่รองรับในการเพิ่มสิ่งใดๆ ลงใน system interpreter
pipx และ uv tool install ทำหน้าที่เดียวกัน ดังนั้นเครื่องที่มี uv อยู่แล้วจึงไม่จำเป็นต้องติดตั้ง pipx เพิ่มเติม การเลือกใช้ web framework ไม่ส่งผลต่อเรื่องนี้ Django และ Flask บน VPS มีความแตกต่างกันที่สิ่งที่อยู่ใน requirements.txt ไม่ใช่ที่วิธีการสร้างสภาพแวดล้อมโดยรอบ ทุกขั้นตอนด้านล่างนี้ใช้ Ubuntu 24.04 และ Python 3.12 ดังนั้นหากเวอร์ชันของคุณแตกต่างออกไป ให้ปรับแก้เวอร์ชันภายใน path ให้ถูกต้อง
สร้าง venv สำหรับแต่ละแอปพลิเคชัน
Ubuntu แยกโมดูล venv ออกจากแพ็กเกจ Python หลัก ดังนั้นบนอิมเมจแบบ minimal การพยายามรันครั้งแรกจะล้มเหลวพร้อมข้อความที่ระบุสิ่งที่ขาดหายไปอย่างชัดเจน
The virtual environment was not created successfully because ensurepip is not
available. On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.
apt install python3.12-venvให้ติดตั้งโมดูลดังกล่าว จากนั้นสร้างสภาพแวดล้อมโดยใช้ผู้ใช้ที่จะเป็นเจ้าของโค้ด
sudo apt update
sudo apt install -y python3-venv
sudo install -d -o deploy -g deploy -m 755 /srv/myapp
sudo -u deploy python3 -m venv /srv/myapp/.venv
sudo -u deploy /srv/myapp/.venv/bin/pip install -r /srv/myapp/requirements.txtสังเกตสิ่งที่ไม่มีอยู่: ไม่มี source และไม่มี activate คำสั่ง /srv/myapp/.venv/bin/pip จะติดตั้งลงในสภาพแวดล้อมนั้นโดยพิจารณาจากตำแหน่งของ binary ไม่ใช่เพราะสิ่งที่คุณ export เข้าสู่ shell ให้ตรวจสอบยืนยันก่อนดำเนินการต่อ
/srv/myapp/.venv/bin/python -c 'import sys; print(sys.prefix)'คำสั่งนั้นจะแสดงผลเป็น /srv/myapp/.venv หากแสดงผลเป็น /usr แสดงว่าคุณกำลังรันตัวแปลภาษา (interpreter) ของระบบ และแพ็กเกจของคุณถูกติดตั้งไปยังตำแหน่งที่ไม่ต้องการ
คุณสมบัติสองประการของ venv เป็นตัวกำหนดสิ่งที่คุณสามารถทำได้หลังจากนั้น venv ไม่สามารถย้ายตำแหน่งได้ (not relocatable) เนื่องจากสคริปต์ entry-point ทุกตัวใน bin/ มีบรรทัด shebang แบบสัมบูรณ์: head -1 /srv/myapp/.venv/bin/pip จะอ่าน #!/srv/myapp/.venv/bin/python หากคุณเปลี่ยนชื่อไดเรกทอรีหลัก สคริปต์เหล่านั้นจะล้มเหลวพร้อมข้อความ bad interpreter: No such file or directory นอกจากนี้ venv ยังผูกติดกับตัวแปลภาษาที่สร้างมันขึ้นมา ซึ่งบันทึกไว้เป็นบรรทัด home ใน /srv/myapp/.venv/pyvenv.cfg และ bin/python3 เป็น symlink ไปยัง /usr/bin/python3 หากคุณอัปเกรด release จนทำให้ path ดังกล่าวชี้ไปยัง Python เวอร์ชันใหม่ ตัวแปลภาษาตัวใหม่จะมองหาแพ็กเกจในไดเรกทอรี lib/python3.13 ที่ venv ไม่มี ส่งผลให้ service หยุดทำงานเมื่อเริ่มระบบพร้อมข้อความ ModuleNotFoundError ทั้งสองกรณีมีวิธีแก้ไขแบบเดียวกันคือ: ลบ venv ทิ้งแล้วสร้างใหม่จาก requirements.txt การสร้างใหม่ใช้เวลาเพียงไม่กี่วินาที ห้ามคัดลอก venv ระหว่างเครื่องโดยเด็ดขาด
ตำแหน่งของ venv และผู้ถือสิทธิ์
ให้วาง venv ไว้ข้างกับซอร์สโค้ดที่ /srv/myapp/.venv และใช้ venv แยกกันสำหรับแต่ละแอปพลิเคชัน วิธีนี้จะทำให้การ deployment เป็นไปในรูปแบบไดเรกทอรีเดียว systemd unit จะได้ใช้ path ที่ไม่เปลี่ยนแปลง และแอปพลิเคชันสองตัวจะไม่ส่งผลกระทบต่อกันหากมีการอัปเกรด dependency ร่วมกัน ห้ามวาง venv ไว้ในตำแหน่งที่เว็บเซิร์ฟเวอร์เผยแพร่ไฟล์โดยตรง เนื่องจาก venv เก็บ dependency และมักจะมีไฟล์ตั้งค่าของคุณอยู่ด้วย
เรื่องความเป็นเจ้าของควรให้ความสำคัญสักครู่ ให้ผู้ใช้ deploy เป็นเจ้าของโค้ดและสภาพแวดล้อม และกำหนดสิทธิ์ให้บัญชีผู้ใช้ของ service มีสิทธิ์อ่านและเรียกใช้งาน (read and execute) เท่านั้น
sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myappขณะนี้ service สามารถเรียกใช้ dependency ได้แต่ไม่สามารถแก้ไขไฟล์เหล่านั้นได้ ซึ่งหมายความว่าหากเกิดข้อผิดพลาดประเภท code execution ในเว็บแอปพลิเคชัน ผู้โจมตีจะไม่สามารถแอบเปลี่ยนไลบรารีในดิสก์เพื่อให้คงอยู่ถาวรหลังการรีสตาร์ทได้ หลักการเดียวกันนี้ที่นำไปใช้กับส่วนอื่นๆ ของเครื่องถูกอธิบายไว้ใน การรัน service ด้วยสิทธิ์ผู้ใช้ที่จำกัดที่สุด
การใช้ pipx สำหรับเครื่องมือบรรทัดคำสั่ง
pipx ใช้สำหรับติดตั้งแอปพลิเคชัน ไม่ใช่ไลบรารี เครื่องมือแต่ละตัวจะมีสภาพแวดล้อมแยกเป็นของตนเองภายใต้ ~/.local/share/pipx/venvs/<name> และไฟล์สั่งการ (executable) ของเครื่องมือนั้นจะถูกเชื่อมโยง (link) เข้าไปยัง ~/.local/bin ดังนั้นเครื่องมือสองตัวที่ต้องการไลบรารีเวอร์ชันต่างกันจึงไม่เกิดปัญหาขัดแย้งกัน
sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpiepipx ensurepath จะเพิ่ม ~/.local/bin เข้าไปใน PATH โดยการแก้ไขไฟล์เริ่มต้นของเชลล์ (shell startup file) มันไม่สามารถเปลี่ยนแปลงเชลล์ที่คุณกำลังใช้งานอยู่ได้ ดังนั้นการที่ http: command not found แจ้งว่าไม่พบคำสั่งหลังจากติดตั้งเสร็จสิ้น มักหมายความว่าคุณยังไม่ได้ออกจากระบบและล็อกอินเข้ามาใหม่ ค่าเริ่มต้นของ ~/.profile ใน Ubuntu จะเพิ่ม ~/.local/bin ก็ต่อเมื่อไดเรกทอรีนั้นมีอยู่จริงในขณะล็อกอิน ซึ่งเป็นสาเหตุว่าทำไมปัญหานี้จึงเกิดขึ้นเพียงครั้งเดียวบนบัญชีผู้ใช้ใหม่และจะไม่เกิดขึ้นอีก
หากคุณระบุไลบรารีให้ pipx มันจะปฏิเสธการทำงานพร้อมข้อความที่ขึ้นต้นว่า:
No apps associated with package requests.นั่นคือเครื่องมือที่กำลังบอกคุณว่าคุณกำลังใช้เครื่องมือผิดประเภท ไลบรารีควรอยู่ใน venv ของแอปพลิเคชันเท่านั้น
รายละเอียดที่สำคัญบนเซิร์ฟเวอร์คือตำแหน่งที่ตั้ง การใช้ pipx install แบบปกติจะเก็บทุกอย่างไว้ภายใต้ไดเรกทอรี home ของผู้ใช้คนเดียว ซึ่ง systemd unit ที่รันในฐานะ myapp จะมองไม่เห็น, cron job ของ root จะมองไม่เห็น และ sudo ก็จะหาไม่พบเช่นกัน เนื่องจาก secure_path ใน /etc/sudoers จะแทนที่ PATH ด้วยรายการที่กำหนดไว้ตายตัว สำหรับเครื่องมือที่ควรใช้งานได้ทั้งเครื่อง ให้ติดตั้งแบบ global
sudo pipx install --global ansible
sudo pipx ensurepath --globalแฟล็ก --global จะวางสภาพแวดล้อมไว้ใน /opt/pipx และเชื่อมโยงไฟล์สั่งการเข้าไปใน /usr/local/bin ซึ่งอยู่ใน PATH มาตรฐานและอยู่ภายใน secure_path ให้ตรวจสอบเวอร์ชันของคุณก่อนด้วย pipx --version เนื่องจาก Ubuntu 24.04 มาพร้อมกับ pipx เวอร์ชัน 1.4.3 ซึ่งเก่ากว่า --global และ pipx เวอร์ชันเก่าจะตอบสนองด้วย unrecognized arguments: --global ในเวอร์ชันดังกล่าว ให้คุณกำหนดไดเรกทอรีทั้งสองตามที่ระบุไว้ในเอกสารด้วยตนเอง:
sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansiblecommand -v ansible ควรแสดงผลลัพธ์เป็น /usr/local/bin/ansible หากแสดงผลเป็นพาธภายใต้ /home แสดงว่าเครื่องมือนั้นถูกติดตั้งลงในบัญชีผู้ใช้รายบุคคล และจะไม่มีเซอร์วิสใดหาพบ
uv เมื่อคุณต้องการ lockfile
uv เป็น binary ไฟล์เดียวจาก Astral ซึ่งครอบคลุมการทำงานของ pip, venv และ pip-tools อีกทั้งยังสามารถดาวน์โหลด Python interpreter มาให้ได้ด้วย ความเร็วของมันสูงจนเห็นความแตกต่างได้ชัดเจนบน VPS ขนาดเล็ก และมันสามารถสร้าง lockfile ที่ใช้งานได้จริง
ตัวติดตั้งอย่างเป็นทางการจะวาง uv และ uvx ไว้ที่ ~/.local/bin:
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --versionการส่ง script ผ่าน pipe เข้า shell บนเซิร์ฟเวอร์ควรใช้ความระมัดระวังเป็นพิเศษ ให้ระบุเวอร์ชันใน URL และอ่านไฟล์ก่อนที่จะรัน:
curl -LsSf https://astral.sh/uv/0.12.3/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.shpipx install uv ก็สามารถใช้งานได้เช่นกันหากมี pipx ติดตั้งอยู่แล้ว uv เป็น binary ที่รวมทุกอย่างไว้ในตัวเดียวโดยไม่มี dependency ของ Python ดังนั้นการคัดลอกไปยัง /usr/local/bin จึงเป็นวิธีที่ถูกต้องในการแชร์ให้ผู้ใช้ทุกคนบนเครื่องใช้งานได้
สำหรับโปรเจกต์ที่มี pyproject.toml เวิร์กโฟลว์จะมี 4 คำสั่ง และมีเพียงคำสั่งสุดท้ายเท่านั้นที่ต้องรันบนเซิร์ฟเวอร์:
uv init myapp
uv add flask gunicorn
uv lock
uv sync --frozen --no-devuv lock จะเขียน uv.lock ซึ่งเป็น lockfile แบบข้ามแพลตฟอร์มที่เก็บเวอร์ชันที่แก้ไขแล้วไว้อย่างแม่นยำ คุณควร commit ไฟล์นี้ไว้คู่กับโค้ดของคุณ uv sync จะสร้าง .venv ไว้ที่ root ของโปรเจกต์ให้ตรงกับ lockfile บนเซิร์ฟเวอร์ flag ที่สำคัญคือ --frozen ซึ่งเอกสารระบุว่าเป็นการใช้เวอร์ชันใน lockfile เป็นแหล่งข้อมูลหลัก แทนที่จะตรวจสอบว่า lockfile เป็นเวอร์ชันล่าสุดหรือไม่ ซึ่งเป็นพฤติกรรมที่เหมาะสมสำหรับการ deployment ส่วน --no-dev จะละเว้นกลุ่ม dependency สำหรับการพัฒนาออกไป
โปรเจกต์ requirements.txt ที่มีอยู่แล้วไม่จำเป็นต้องแปลงรูปแบบ เพราะ uv รองรับภาษาเดียวกับ pip:
uv venv /srv/myapp/.venv
uv pip install --python /srv/myapp/.venv/bin/python -r /srv/myapp/requirements.txtสิ่งที่ได้คือ virtual environment ปกติที่มีข้อแตกต่างเพียงอย่างเดียวคือ uv จะไม่ติดตั้ง pip ลงไป ดังนั้น .venv/bin/pip และ .venv/bin/python -m pip จะไม่ทำงานเว้นแต่คุณจะสร้าง environment ด้วย uv venv --seed ให้ติดตั้งด้วย uv pip แทน ไม่มีขั้นตอนใดในคู่มือนี้ที่ต้องรัน pip ภายใน environment ดังนั้นจึงไม่มีผลกระทบใดๆ ตามมา
มีค่าเริ่มต้นของ uv หนึ่งอย่างที่ควรทราบก่อนนำไปใช้บนเซิร์ฟเวอร์ การตั้งค่า python-preference มีค่าเริ่มต้นเป็น managed ซึ่งเอกสารระบุว่าเป็นการเลือก "ตัวที่ดาวน์โหลดและติดตั้งโดย uv" แทนที่จะใช้ interpreter ที่มีอยู่แล้วในระบบ ดังนั้น uv venv --python 3.13 บนเครื่องที่มีเฉพาะ 3.12 จะทำการดาวน์โหลด 3.13 มาไว้ที่ ~/.local/share/uv/python โดยอัตโนมัติแทนที่จะแจ้งเตือนว่าล้มเหลว สิ่งนี้สะดวกสำหรับแล็ปท็อปแต่สร้างความประหลาดใจบนเซิร์ฟเวอร์ เพราะบริการของคุณจะขึ้นอยู่กับ interpreter ที่อยู่ใน home directory ซึ่ง apt upgrade จะไม่ทำการ patch ให้ ให้ตั้งค่า python-preference เป็น only-system ใน uv.toml หากคุณต้องการใช้ interpreter ของ distribution นั้นๆ หากคุณต้องการให้ environment อยู่ที่อื่นที่ไม่ใช่ root ของโปรเจกต์ UV_PROJECT_ENVIRONMENT จะเป็นตัวกำหนดไดเรกทอรีที่จะใช้สำหรับ virtual environment ของโปรเจกต์นั้นๆ
ชี้ systemd ไปที่ตัวแปลภาษาใน venv โดยตรง ไม่ใช่ที่ activate
นี่คือจุดที่การติดตั้ง Python ส่วนใหญ่ล้มเหลว และสาเหตุมาจากความเข้าใจผิดว่า activate ทำหน้าที่อะไร
bin/activate เป็นเพียงเชลล์สคริปต์ มันทำหน้าที่เพิ่มไดเรกทอรี bin ของ venv เข้าไปที่หน้าสุดของ PATH, ตั้งค่า VIRTUAL_ENV, บันทึกค่าเดิมไว้เพื่อให้ deactivate เรียกคืนได้ และเปลี่ยนรูปแบบ prompt ของคุณ มันไม่มีสิ่งใดที่ตัวแปลภาษาอ่านเองได้ การ activate เป็นเพียงความสะดวกสำหรับมนุษย์ที่พิมพ์ python ที่ prompt เท่านั้น
สิ่งที่กำหนดสภาพแวดล้อมที่แท้จริงคือไฟล์ตัวแปลภาษาที่คุณเรียกใช้งาน เมื่อ /srv/myapp/.venv/bin/python เริ่มทำงาน โมดูล site ของ Python จะมองหาไฟล์ pyvenv.cfg ในไดเรกทอรีที่เก็บไฟล์สั่งการและไดเรกทอรีที่อยู่เหนือขึ้นไปหนึ่งระดับ การพบไฟล์ /srv/myapp/.venv/pyvenv.cfg จะตั้งค่า sys.prefix ให้เป็น venv ซึ่งจะนำ site-packages ของ venv นั้นไปไว้บน sys.path นี่คือกลไกทั้งหมด มันไม่ต้องการตัวแปรสภาพแวดล้อมและไม่ต้องการเชลล์
ดังนั้น unit นี้จึงไม่เคยเริ่มทำงาน:
[Service]
ExecStart=source /srv/myapp/.venv/bin/activate && gunicorn app:appmyapp.service: Failed to locate executable source: No such file or directory
myapp.service: Failed at step EXEC spawning source: No such file or directory
myapp.service: Main process exited, code=exited, status=203/EXECExecStart ไม่ใช่บรรทัดคำสั่งของเชลล์ systemd เรียกโปรแกรมโดยตรง ดังนั้นจึงไม่มี source ในตัว, && จะถูกส่งผ่านเป็นอาร์กิวเมนต์ตามตัวอักษร และไม่มีการขยายคำสั่งของเชลล์ใดๆ เกิดขึ้นนอกเหนือจากที่ systemd ระบุไว้เอง
และ unit นี้เริ่มทำงานแล้วก็ดับไป:
[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.pyModuleNotFoundError: No module named 'flask'/usr/bin/python3 คือตัวแปลภาษาของระบบ และ sys.path ของมันไม่เคยมี venv ของคุณอยู่ คำสั่งเดียวกันนี้ทำงานได้ใน SSH session ของคุณเพียงเพราะคุณได้ activate venv ไว้ที่นั่น เชลล์จึงแปลง python3 ผ่าน PATH ไปเป็น .venv/bin/python3 แทน
การครอบคำสั่งด้วย /bin/bash -c 'source ... && gunicorn ...' นั้นใช้งานได้จริง แต่มันเป็นการเพิ่มเชลล์เข้ามาคั่นกลางระหว่าง systemd กับกระบวนการของคุณโดยไม่จำเป็น ในเมื่อการใช้พาธแบบสัมบูรณ์ (absolute path) เพียงอย่างเดียวก็จัดการได้แล้ว:
[Unit]
Description=myapp web service
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp
Environment=PYTHONUNBUFFERED=1
Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/srv/myapp/.venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 app:app
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now myapp
systemctl status myapp
journalctl -u myapp -n 50 --no-pagersystemctl status myapp ควรรายงาน active (running) พร้อมกับ Main PID ที่เป็นกระบวนการ gunicorn ของคุณ หากเป็นอย่างอื่น ให้ตรวจสอบ journal
บรรทัด Environment=PATH= ไม่ได้มีไว้สำหรับ ExecStart ซึ่งมีพาธเต็มอยู่แล้ว แต่มีไว้สำหรับกระบวนการที่แอปพลิเคชันของคุณเรียกใช้งาน บริการหนึ่งๆ จะได้รับค่า PATH เริ่มต้นที่สั้นจาก systemd ดังนั้นโค้ด Python ที่เรียก subprocess.run(["ffmpeg", ...]) หรือคำสั่งจัดการที่เรียกใช้สคริปต์คอนโซลจาก venv จะไม่พบสิ่งที่ต้องการ การนำไดเรกทอรี bin ของ venv มาไว้หน้าสุดคือส่วนเดียวของ activate ที่บริการใช้งานจริง ตรวจสอบสิ่งที่ unit ได้รับจริงๆ ด้วย systemctl show -p Environment myapp
กฎเดียวกันนี้ครอบคลุมถึงงานที่ตั้งเวลาไว้ บน Ubuntu นั้น cron ไม่ได้ส่งผ่าน PATH จากเชลล์หรือจาก daemon ให้กับงาน: เว้นแต่ crontab จะตั้งค่า PATH เอง ทุกงานจะได้รับค่า /usr/bin:/bin เริ่มต้นที่คอมไพล์มา และ /etc/environment ก็ไม่ได้ไปแทนที่ค่าดังกล่าว ซึ่งค่าเริ่มต้นนั้นไม่มี venv ของคุณอยู่ ดังนั้นบรรทัดใน crontab ที่อ่านว่า python3 /srv/myapp/cleanup.py จึงรันตัวแปลภาษาของระบบและล้มเหลวด้วย ModuleNotFoundError ในตอนตีสาม cron จะส่งอีเมลแจ้งข้อผิดพลาดไปยังเจ้าของ crontab หรือไปยังที่อยู่ MAILTO หากคุณตั้งค่าไว้ ซึ่งบนเซิร์ฟเวอร์ส่วนใหญ่หมายถึงกล่องจดหมายภายในที่ไม่มีใครอ่าน หากไม่มีโปรแกรมรับอีเมลติดตั้งอยู่ cron จะทิ้งผลลัพธ์นั้นและเขียนเพียง No MTA installed, discarding output ลงใน log ของระบบเท่านั้น ให้เขียนพาธ venv แบบสัมบูรณ์ลงไปในนั้นด้วย และเพื่อให้ได้ผลลัพธ์นั้นใน journal รวมถึงบันทึกการรันครั้งล่าสุด ให้ใช้ คู่ของ systemd service และ timer ซึ่งใช้บรรทัด ExecStart เดียวกันนี้
Docker เข้ามาแทนที่การตัดสินใจนี้หรือไม่?
Container มีระบบไฟล์เป็นของตัวเอง ดังนั้นคำถามนี้จึงเปลี่ยนรูปแบบไปแทนที่จะหายไป ในอิมเมจทางการอย่าง python:3.12-slim ตัว Python ถูกรวมไว้ใน /usr/local และไม่มีเครื่องหมาย EXTERNALLY-MANAGED ดังนั้นการใช้ pip install ในฐานะ root จึงเป็นวิธีที่ตั้งใจไว้สำหรับการเพิ่มแพ็กเกจ และการใช้ venv แทบไม่ได้ประโยชน์อะไรเพิ่มขึ้นมา หากคุณสร้าง FROM ubuntu:24.04 ขึ้นมาเอง คุณจะพบกับ externally-managed-environment อีกครั้งภายในอิมเมจ ด้วยเหตุผลเดียวกับที่พบในโฮสต์ นั่นคือมันเป็นอินเทอร์พรีเตอร์ของดิสทริบิวชันที่มาพร้อมกับไฟล์เครื่องหมายของดิสทริบิวชันนั้น
อิมเมจจำนวนมากยังคงใช้ venv เพราะช่วยให้การทำ multi-stage build เป็นเรื่องง่าย โดยขั้นตอน builder จะติดตั้งลงใน /opt/venv และขั้นตอน runtime จะคัดลอกเฉพาะไดเรกทอรีนั้นมาโดยทิ้งคอมไพเลอร์ไว้เบื้องหลัง ปัญหาเรื่องการ activate จึงติดมาด้วย บรรทัด RUN source /opt/venv/bin/activate ส่งผลต่อ shell ของเลเยอร์การ build นั้นเท่านั้น ดังนั้นในขณะ runtime คอนเทนเนอร์จะเริ่มทำงานบนอินเทอร์พรีเตอร์ของระบบและแจ้งเตือน ModuleNotFoundError คุณต้องตั้งค่า ENV PATH="/opt/venv/bin:$PATH" หรือระบุพาธแบบสัมบูรณ์ /opt/venv/bin/gunicorn ให้กับ CMD มันคือบั๊กเดียวกับที่พบใน systemd เพียงแต่อยู่ในไฟล์ที่ต่างออกไป
ดังนั้น คอนเทนเนอร์เข้ามาแทนที่คำถามเรื่องอินเทอร์พรีเตอร์ เพราะอิมเมจจะล็อกเวอร์ชันของอินเทอร์พรีเตอร์และทุกสิ่งที่อยู่ภายใต้มันไว้ แต่มันไม่ได้เข้ามาแทนที่คำถามเรื่องการล็อกเวอร์ชัน (pinning) อิมเมจที่สร้างจาก requirements.txt ที่ไม่ได้ล็อกเวอร์ชันไว้จะทำให้ได้เวอร์ชันที่ต่างออกไปในเดือนถัดมา ซึ่งหมายความว่าแท็กของอิมเมจนั้นทำซ้ำได้ (reproducible) แต่กระบวนการ build ที่สร้างอิมเมจนั้นกลับทำซ้ำไม่ได้ ไฟล์ล็อกอย่าง uv.lock หรือไฟล์ requirements ที่ล็อกเวอร์ชันไว้อย่างครบถ้วน คือสิ่งที่ช่วยปิดช่องว่างนี้ ไม่ว่าจะใช้คอนเทนเนอร์หรือไม่ก็ตาม และเมื่อแอปพลิเคชันหนึ่งรันบน VPS หนึ่งเครื่องภายใต้ systemd คอนเทนเนอร์ส่วนใหญ่จะย้ายการตัดสินใจนี้ไปไว้ใน Dockerfile เนื่องจาก systemd สามารถรีสตาร์ทกระบวนการที่ล้มเหลวและบันทึกเอาต์พุตลงใน journal ได้อยู่แล้ว การรัน Docker บน VPS จะคุ้มค่าเมื่อคุณต้องการให้อิมเมจที่ build เสร็จแล้วเป็นสิ่งที่คุณนำไป deploy จริงๆ
FAQ
ฉันสามารถใช้ pip install พร้อมแฟล็ก --break-system-packages ได้หรือไม่
ไม่ควรทำบนเซิร์ฟเวอร์ที่คุณต้องดูแลให้ทำงานได้อย่างต่อเนื่อง แฟล็กนี้ทำงานตามชื่อของมัน คือการเอาตัวป้องกันออก แล้ว pip จะเขียนไฟล์ลงใน /usr/local/lib/python3.12/dist-packages ซึ่งมีลำดับความสำคัญสูงกว่าไดเรกทอรีของ apt ใน sys.path ส่งผลให้เวอร์ชันของคุณไปทับซ้อนกับเวอร์ชันของระบบสำหรับสคริปต์ทุกตัวที่รันภายใต้ /usr/bin/python3 ในขณะที่ apt ยังคงเข้าใจว่าเวอร์ชันเดิมของมันถูกติดตั้งอยู่ จึงไม่มีระบบใดตรวจพบความขัดแย้งจนกว่าจะมีบางอย่างทำงานผิดพลาด หากเป็นภายใน container image ที่คุณสร้างใหม่จากศูนย์ทุกครั้ง ความเสียหายจะจำกัดอยู่แค่ใน image นั้น ซึ่งถือว่ายอมรับได้ แต่บนเครื่องที่คุณต้องดูแลรักษา ให้สร้าง venv แทน ซึ่งใช้เพียงคำสั่งเดียวเท่านั้น
virtual environment ควรวางไว้ที่ใดบนเซิร์ฟเวอร์
ควรวางไว้ภายในไดเรกทอรีของแอปพลิเคชันเองในชื่อ /srv/myapp/.venv โดยให้ deploy user เป็นเจ้าของ และให้ service account มีสิทธิ์เพียงอ่านและเรียกใช้งานเท่านั้น ควรแยก venv ต่อหนึ่งแอปพลิเคชัน เพราะการใช้ venv ร่วมกันจะทำให้การอัปเกรดแอปพลิเคชันแรกอาจส่งผลให้แอปพลิเคชันที่สองทำงานไม่ได้ ห้ามย้ายหรือคัดลอก venv หลังจากสร้างเสร็จแล้ว เพราะสคริปต์ entry-point ทุกตัวในไดเรกทอรี bin/ ของมันมีการระบุ absolute path ไว้ในบรรทัด shebang ดังนั้นหากย้าย venv ไปที่อื่นจะทำให้เกิดข้อผิดพลาด bad interpreter: No such file or directory ให้ลบทิ้งแล้วสร้างใหม่จาก requirements.txt แทน
ทำไม systemd service ของฉันถึงล้มเหลวด้วยข้อผิดพลาด ModuleNotFoundError
เพราะ unit กำลังเรียกใช้งาน interpreter ที่ไม่ใช่ของ venv ให้รัน systemctl cat myapp และอ่าน ExecStart โดยจะต้องระบุ /srv/myapp/.venv/bin/python หรือ console script จากไดเรกทอรี bin/ เดียวกันนั้นด้วย absolute path การใช้คำสั่ง source activate โดยตรงใน ExecStart ไม่สามารถทำได้ เพราะ ExecStart ไม่ใช่ shell และ systemd จะรายงานข้อผิดพลาด Failed to locate executable source พร้อมกับ status=203/EXEC ให้เพิ่ม Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin เพื่อให้ subprocess ใดๆ ที่โค้ดของคุณเรียกใช้งานสามารถค้นพบเครื่องมือของ venv ได้เช่นกัน
ฉันควรใช้ uv แทน venv และ pip หรือไม่
ให้ใช้ uv เมื่อคุณต้องการ lockfile, เมื่อเวลาที่ใช้ในการติดตั้งนานจนเป็นปัญหา หรือเมื่อคุณต้องการ Python เวอร์ชันที่ไม่มีใน distribution ของคุณ uv จะสร้าง venv แบบปกติขึ้นมา ดังนั้น unit ของ systemd และโครงสร้างไฟล์จะไม่เปลี่ยนแปลง และ uv sync --frozen จะติดตั้งสิ่งที่ระบุไว้ใน lockfile อย่างแม่นยำ หากแอปพลิเคชันเดียวถูก deploy จาก git โดยใช้ requirements.txt ที่ระบุเวอร์ชันไว้ชัดเจนและใช้เวลาติดตั้งเพียงไม่กี่วินาที python3 -m venv ก็เพียงพอแล้ว และยังช่วยลดจำนวน binary ที่ต้องคอยอัปเดตบนเซิร์ฟเวอร์ลงได้หนึ่งตัว