macOS 部署 Nginx + FastCGI (flup) + Flask 應用完整教學

在 macOS 上使用 Homebrew 安裝 Nginx，搭配 flup FastCGI 伺服器部署 Flask 應用。本文涵蓋 Nginx 安裝配置、FastCGI 啟動、Socket 權限問題排解、使用者/群組設定完整流程。

安裝 Nginx

brew install nginx
# 配置檔：/usr/local/etc/nginx/nginx.conf
# 預設埠：8080
nginx  # 啟動

訪問 https://localhost:8080 確認 Nginx 運作。

Nginx 配置 FastCGI 代理

編輯 nginx.conf 的 server 區塊：

server {
    listen 80;
    server_name localhost;
    charset utf-8;

    location / {
        try_files $uri @flaskr;
    }
    location @flaskr {
        include fastcgi_params;
        fastcgi_param PATH_INFO $fastcgi_script_name;
        fastcgi_param SCRIPT_NAME "";
        fastcgi_pass unix:/tmp/flaskr-fcgi.sock;
    }
}

重新載入：

nginx -s quit
sudo nginx  # 埠 80 需 root

安裝 flup 並建立 FastCGI 入口

pip install flup

專案目錄建立 flaskr.fcgi：

#!/usr/bin/python
from flup.server.fcgi import WSGIServer
from flaskr import app

if __name__ == '__main__':
    WSGIServer(app, bindAddress='/tmp/flaskr-fcgi.sock').run()

chmod +x flaskr.fcgi

啟動 FastCGI 伺服器

# 方式一：screen 後台
screen
./flaskr.fcgi

# 方式二：nohup
nohup ./flaskr.fcgi &

Socket 權限問題排解

首次啟動 Nginx 回傳 502，錯誤日誌顯示：

connect() to unix:/tmp/flaskr-fcgi.sock failed (13: Permission denied)

解決方案：設定 Nginx 執行使用者

# nginx.conf 主區塊加入
user wzy wheel;  # 使用者:群組

• user 僅指定使用者時，Nginx 會嘗試同名群組（不存在則報錯）
• 明確指定 user 使用者 群組 避免錯誤
• wheel 為 macOS 管理員群組

驗證部署

重新啟動 Nginx 後訪問 https://localhost 即可看到 Flask 應用。

架構圖解

Client → Nginx (Port 80) → FastCGI Socket → flup WSGIServer → Flask App
                    靜態檔案直接服務

生產環境建議

• 使用 supervisor 或 launchd 管理 FastCGI 進程
• Nginx 啟用 Gzip、快取、SSL
• 分離靜態檔案由 Nginx 直接服務
• 監控日誌與效能指標