Python

zbpack 可以建置帶有 requirements.txt、pyproject.toml（Poetry、uv、PDM）或 Pipfile 的 Python 應用。它能識別 FastAPI、Django 和 Flask，併為每種框架選擇一個生產環境伺服器。

框架	zbpack 使用的啟動指令
FastAPI	uvicorn main:app --host 0.0.0.0 --port 8080
Django	gunicorn --bind :8080 <project>.wsgi
Flask	gunicorn --bind :8080 main:app

Python 版本預設是 3.13；可以在 .python-version、pyproject.toml 中設定，或者用 ZBPACK_PYTHON_VERSION。要用其他方式啟動應用，在 設定 → 建置 → zbpack 選項 中設定 ZBPACK_START_COMMAND。

FastAPI

# main.py
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def root():
    return {"message": "Hello from FastAPI"}

# requirements.txt
fastapi
uvicorn[standard]

zbpack 依次查詢 main.py、app.py、server.py 和 app/__init__.py，取第一個存在的檔案，以及其中被賦值為 FastAPI(...) 的變數（上面的 app）。如果是其他目錄結構，例如 app/main.py，請設定啟動指令：

ZBPACK_START_COMMAND=uvicorn app.main:app --host 0.0.0.0 --port 8080

Django

專案需要有 manage.py，並在 requirements.txt 中包含 gunicorn：

django
gunicorn

在 settings.py 中從變數讀取生產環境的設定：

import os

SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "")
DEBUG = os.environ.get("DJANGO_DEBUG") == "1"
ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "").split(",")
CSRF_TRUSTED_ORIGINS = os.environ.get("DJANGO_CSRF_TRUSTED_ORIGINS", "").split(",")

然後在 變數 分頁中設定它們：

DJANGO_SECRET_KEY=${PASSWORD}
DJANGO_ALLOWED_HOSTS=${ZENAVO_WEB_DOMAIN}
DJANGO_CSRF_TRUSTED_ORIGINS=${ZENAVO_WEB_URL}

（WEB 是服務連接埠的名稱；請使用服務 網路 分頁中顯示的名稱。）

靜態檔案

當 settings.py 同時設定了 STATIC_URL 和 STATIC_ROOT 時，zbpack 會在建置時執行 python manage.py collectstatic --noinput，並在 gunicorn 前面用 nginx 提供這些檔案；如果 settings.py 中啟用了 WhiteNoise 的中介軟體，則交給 WhiteNoise 處理：

STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

建置時沒有服務的任何變數，所以 settings.py 必須在沒有變數的情況下也能載入：像上面那樣用 os.environ.get(...) 讀取 DJANGO_SECRET_KEY，不要用 os.environ[...]。

資料庫遷移

遷移需要資料庫，而建置時存取不到資料庫，所以請在啟動時執行：

ZBPACK_START_COMMAND=python manage.py migrate --noinput && gunicorn --bind :8080 mysite.wsgi

連線資料庫

在專案中新增 PostgreSQL，並使用它的連線字串，例如透過 dj-database-url 或 SQLAlchemy：

DATABASE_URL=${POSTGRESQL_CONNECTION_STRING}

import dj_database_url

DATABASES = {"default": dj_database_url.config(conn_max_age=600)}

還需要安裝驅動：PostgreSQL 用 psycopg[binary]，MySQL 和 MariaDB 用 mysqlclient 或 PyMySQL。

常見問題

現象	原因
啟動時報 ModuleNotFoundError	requirements.txt（或 pyproject.toml）中缺少這個包。
Django 返回 400 Bad Request	網域不在 ALLOWED_HOSTS 中。
Django 表單報 CSRF verification failed	https:// 位址不在 CSRF_TRUSTED_ORIGINS 中。
FastAPI 部署一直不健康	應用物件不在 main:app。請設定 ZBPACK_START_COMMAND。
高負載時 worker 被殺掉	服務的記憶體不夠 gunicorn 的 worker 數量使用。減少 --workers，或者給服務更多記憶體。