Linux 上部署 Python Web 應用的完整指南

在現代 Web 開發中，Python 以其豐富的生態系（如 Django、Flask、FastAPI）成為首選語言之一。然而，將本地開發環境順利遷移至生產伺服器，往往是許多開發者面臨的挑戰。本指南將帶領你逐步在 Ubuntu 22.04 或 Debian 12 伺服器上，建立一個穩固、高效的 Python Web 應用部署環境。我們將採用 Nginx 作為反向代理，Gunicorn 作為應用伺服器，並利用 Systemd 確保服務的穩定性。

第一步：環境準備與依賴安裝

首先，我們需要更新系統套件索引，並安裝必要的依賴程式。這包括 Python 3 運行環境、pip 套件管理器，以及用於編譯某些 Python 擴充功能的系統庫。

sudo apt update
sudo apt upgrade -y

# 安裝 Python 3、pip、virtualenv 及編譯工具
sudo apt install python3-pip python3-venv python3-dev build-essential libssl-dev libffi-dev -y

第二步：建立專案虛擬環境

為了避免依賴衝突，強烈建議為每個專案建立獨立的虛擬環境（Virtual Environment）。這能確保專案所需的套件版本不會影響系統其他部分。

假設我們的主程式目錄為 /var/www/myapp：

# 建立專案目錄並進入
sudo mkdir -p /var/www/myapp
cd /var/www/myapp

# 建立虛擬環境
python3 -m venv venv

# 啟用虛擬環境
source venv/bin/activate

啟用後，你的終端提示字元前會顯示 (venv)。接下來，安裝你的 Web 框架和生產級應用伺服器。這裡以 Flask 和 Gunicorn 為例：

# 安裝 Flask 和 Gunicorn
pip install flask gunicorn

第三步：撰寫簡單的測試應用

為了驗證部署流程，我們建立一個簡單的 app.py：

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return "Hello from Gunicorn & Nginx!"

if __name__ == '__main__':
    app.run()

第四步：配置 Gunicorn 與 Systemd 服務

直接從終端啟動 Gunicorn 並不適合生產環境，因為一旦終端關閉，服務就會停止。我們需要使用 Systemd 來管理 Gunicorn 進程，使其在背景運行並隨系統啟動。

建立一個 Systemd 服務檔案 /etc/systemd/system/myapp.service：

[Unit]
Description=My Flask App
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/myapp
Environment="PATH=/var/www/myapp/venv/bin"
ExecStart=/var/www/myapp/venv/bin/gunicorn --workers 3 --bind unix:myapp.sock -m 007 wsgi:app

[Install]
WantedBy=multi-user.target

關鍵參數說明：

--bind unix:myapp.sock：Gunicorn 將透過 Unix Socket 與 Nginx 通訊，這比 TCP 連接更高效且安全。
wsgi:app：這裡假設你的應用檔案名稱為 wsgi.py 且匯入物件為 app。若你使用的是 app.py，請改為 app:app。
--workers 3：根據 CPU 核心數調整工作進程數，一般建議公式為 2 * CPU核心數 + 1。

啟用並啟動服務：

sudo systemctl daemon-reload
sudo systemctl start myapp
sudo systemctl enable myapp
sudo systemctl status myapp

確認狀態為 active (running) 後，我們需要確保 Nginx 有權限讀取該 socket 檔案。由於我們在服務檔中設定了 Group=www-data，通常預設權限已足夠，但若有問題可執行 sudo chmod 775 /var/www/myapp/myapp.sock。

第五步：配置 Nginx 反向代理

Nginx 將負責處理靜態檔案、SSL 終端以及將 HTTP 請求轉發給後端的 Gunicorn。

建立 Nginx 站點配置 /etc/nginx/sites-available/myapp：

server {
    listen 80;
    server_name your_domain_or_IP;

    location / {
        include proxy_params;
        proxy_pass http://unix:/var/www/myapp/myapp.sock;
    }
}

啟用該配置並重新載入 Nginx：

sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled
sudo nginx -t
sudo systemctl reload nginx

現在，訪問你的伺服器 IP 或網域，應該能看到 "Hello from Gunicorn & Nginx!" 的回應。

常見問題排查

502 Bad Gateway 錯誤：這通常意味著 Nginx 無法連接到後端 Gunicorn。請檢查 sudo systemctl status myapp 確認 Gunicorn 是否正常運行，並確認 proxy_pass 路徑中的 socket 檔案路徑與 ExecStart 中設定的一致。此外，檢查 SELinux（若啟用）或 AppArmor 是否阻擋了存取。
權限拒絕 (Permission Denied)：若 Gunicorn 無法寫入 socket 檔案，請確認 www-data 使用者對 /var/www/myapp 目錄擁有讀寫權限。可以使用 sudo chown -R www-data:www-data /var/www/myapp 來修正所有者權限。

小結

透過上述步驟，我們成功在 Linux 伺服器上部署了一個具備反向代理、進程管理和虛擬環境隔離的 Python Web 應用。這種架構不僅提升了應用的穩定性與效能，也為後續導入 HTTPS（使用 Let's Encrypt）和自動擴展奠定了堅實的基礎。對於中階使用者而言，理解各組件之間的協作關係，比單純複製貼上指令更為重要。希望這篇指南能幫助你順利跨越部署的門檻。