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

python

# main.py
from fastapi import FastAPI

app = FastAPI()


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

txt

# 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：

txt

django
gunicorn

在 settings.py 中从变量读取生产环境的设置：

python

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 处理：

python

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}

python

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`，或者给服务更多内存。

Python ​

FastAPI ​

Django ​

静态文件 ​

数据库迁移 ​

连接数据库 ​

常见问题 ​

Python

FastAPI

Django

静态文件

数据库迁移

连接数据库

常见问题