在 App Engine 标准环境中运行 Django


App Engine 标准环境中运行的 Django 应用会根据流量动态扩缩。

本教程假定您熟悉 Django 网络开发。如果您刚开始接触 Django 开发,最好先查看编写您的第一个 Django 应用,然后再继续操作。

本教程专门演示 Django,但您可以将此部署过程与其他基于 Django 的框架(例如 WagtailDjango CMS)搭配使用。

本教程使用 Django 4,它至少需要 Python 3.8。 App Engine 标准环境支持 Python 3.7 及更高版本,包括 Python 3.8。

目标

在此教程中,您将学习以下操作:

  • 创建并连接 Cloud SQL 数据库。
  • 创建和使用 Secret Manager Secret 值。
  • 将 Django 应用部署到 App Engine 标准环境。

费用

在本文档中,您将使用 Google Cloud 的以下收费组件:

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用

准备工作

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Cloud SQL Admin API, Secret Manager, and Cloud Build APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.
  6. To initialize the gcloud CLI, run the following command:

    gcloud init
  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Enable the Cloud SQL Admin API, Secret Manager, and Cloud Build APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.
  11. To initialize the gcloud CLI, run the following command:

    gcloud init
  12. 初始化 App Engine 并选择您的首选区域(如果您尚未执行此操作):

    gcloud app create
    

准备环境

克隆示例应用

Django 示例应用的代码位于 GitHub 上的 GoogleCloudPlatform/python-docs-samples 代码库中。

  1. 您可以下载该示例的 ZIP 文件并将其解压缩,或将代码库克隆到本地机器:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
    
  2. 转到包含示例代码的目录:

    Linux/macOS

    cd python-docs-samples/appengine/standard_python3/django
    

    Windows

    cd python-docs-samples\appengine\standard_python3\django
    

确认 Python 设置

本教程依赖 Python 在您的机器上运行示例应用。示例代码还需要安装依赖项。

如需了解详情,请参阅 Python 开发环境指南

  1. 确认您的 Python 版本至少为 3.8。

     python -V
    

    您应该会看到 Python 3.8.0 或更高版本。

  2. 创建 Python 虚拟环境并安装依赖项:

    Linux/macOS

    python -m venv venv
    source venv/bin/activate
    pip install --upgrade pip
    pip install -r requirements.txt
    

    Windows

    python -m venv venv
    venv\scripts\activate
    pip install --upgrade pip
    pip install -r requirements.txt
    

下载 Cloud SQL Auth 代理以从本地机器连接到 Cloud SQL

部署后,您的应用会使用 App Engine 标准环境中内置的 Cloud SQL Auth 代理与 Cloud SQL 实例进行通信。但要在本地测试应用,您必须在开发环境中安装和使用该代理的本地副本。 如需了解详情,请参阅 Cloud SQL Auth 代理指南

Cloud SQL Auth 代理使用 Cloud SQL API 与 SQL 实例进行交互。为此,它需要通过 gcloud CLI 进行应用身份验证。

  1. 对 API 进行身份验证并获取凭据:

    gcloud auth application-default login
    
  2. 将 Cloud SQL Auth 代理下载并安装到本地机器上。

    Linux 64 位

    1. 下载 Cloud SQL Auth 代理:
      curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.linux.amd64
      
    2. 使 Cloud SQL Auth 代理可执行:
      chmod +x cloud-sql-proxy
      

    Linux 32 位

    1. 下载 Cloud SQL Auth 代理:
      curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.linux.386
      
    2. 如果找不到 curl 命令,请运行 sudo apt install curl 并重复执行下载命令。
    3. 使 Cloud SQL Auth 代理可执行:
      chmod +x cloud-sql-proxy
      

    macOS 64 位

    1. 下载 Cloud SQL Auth 代理:
      curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.darwin.amd64
      
    2. 使 Cloud SQL Auth 代理可执行:
      chmod +x cloud-sql-proxy
      

    Mac M1

    1. 下载 Cloud SQL Auth 代理:
        curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.darwin.arm64
        
    2. 使 Cloud SQL Auth 代理可执行:
        chmod +x cloud-sql-proxy
        

    Windows 64 位

    右键点击 https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.x64.exe,然后选择链接另存为以下载 Cloud SQL Auth 代理。将文件重命名为 cloud-sql-proxy.exe

    Windows 32 位

    右键点击 https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.x86.exe,然后选择链接另存为以下载 Cloud SQL Auth 代理。将文件重命名为 cloud-sql-proxy.exe

    Cloud SQL Auth 代理 Docker 映像

    Cloud SQL Auth 代理有不同的容器映像,例如 distrolessalpinebuster。默认的 Cloud SQL Auth 代理容器映像使用不包含 shell 的 distroless。如果您需要 shell 或相关工具,请下载基于 alpinebuster 的映像。如需了解详情,请参阅 Cloud SQL Auth 代理容器映像

    您可以通过 Docker 使用以下命令将最新映像拉取到本地机器:

    docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.1
    

    其他操作系统

    对于此处未列出的其他操作系统,您可以通过源代码编译 Cloud SQL Auth 代理

    您可以选择将下载的文件移到其他位置,例如 PATH 上的某个位置或主目录。如果您选择这样做,则在本教程的后面部分启动 Cloud SQL Auth 代理时,请务必在使用 cloud-sql-proxy 命令时引用您选择的位置。

创建支持性服务

本教程使用多种 Google Cloud 服务来提供支持已部署 Django 项目的数据库、媒体存储和 Secret 存储。这些服务部署在特定区域。为了提高服务之间的效率,所有服务都应部署在同一区域中。如需详细了解离您最近的区域,请参阅各区域可使用的产品

本教程使用 App Engine 标准环境中的集成式静态资源托管机制。

设置 Cloud SQL for PostgreSQL 实例

Django 官方支持多个关系型数据库,但为 PostgreSQL 提供了最全面的支持。Cloud SQL 支持 PostgreSQL,因此本教程选择使用此类型的数据库。

以下部分介绍了如何为应用创建 PostgreSQL 实例、数据库和数据库用户。

  1. 创建 PostgreSQL 实例:

    控制台

    1. 在 Google Cloud 控制台中,前往 Cloud SQL 实例页面。

      转到“Cloud SQL 实例”页面

    2. 点击创建实例

    3. 点击选择 PostgreSQL

    4. 对于 SQL 版本,请选择“企业版”。

    5. 对于版本预设值,请选择“沙盒”。

    6. 实例 ID 字段中,输入 INSTANCE_NAME

    7. 为 postgres 用户输入密码。

    8. 对于其他字段,请保留默认值。

    9. 点击创建实例

    实例需要几分钟才能准备就绪。

    gcloud

    • 创建 PostgreSQL 实例:

      gcloud sql instances create INSTANCE_NAME \
          --project PROJECT_ID \
          --database-version POSTGRES_16 \
          --tier db-n1-standard-2 \
          --region REGION
      

    请替换以下内容:

    • INSTANCE_NAME:Cloud SQL 实例名称
    • PROJECT_ID:Google Cloud 项目 ID
    • REGIONGoogle Cloud 区域

    创建实例并准备好使用需要几分钟时间。

  2. 在所创建的实例中,创建一个数据库:

    控制台

    1. 在实例页面中,转到数据库标签页。
    2. 点击创建数据库
    3. 数据库名称对话框中,输入 DATABASE_NAME
    4. 点击创建

    gcloud

    • 在最近创建的实例中创建数据库:

      gcloud sql databases create DATABASE_NAME \
          --instance INSTANCE_NAME
      

      DATABASE_NAME 替换为实例中数据库的名称。

  3. 创建数据库用户:

    控制台

    1. 在实例页面中,转到用户标签页。
    2. 点击添加用户账号
    3. 选择身份验证方式对话框中的“内置身份验证”下:
    4. 输入用户名 DATABASE_USERNAME
    5. 输入密码 DATABASE_PASSWORD
    6. 点击添加

    gcloud

    • 在最近创建的实例中创建用户:

      gcloud sql users create DATABASE_USERNAME \
          --instance INSTANCE_NAME \
          --password DATABASE_PASSWORD
      

      PASSWORD 替换为安全密码。

在 Secret Manager 中存储 Secret 值

现在,支持性服务已配置完毕,Django 需要关于这些服务的信息。本教程使用 Secret Manager 安全地存储这些值,而不是直接将这些信息放入 Django 源代码中。

将 Django 环境文件创建为 Secret Manager 的 Secret

将 Django 启动所需的设置存储在安全的 env 文件中。示例应用使用 Secret Manager API 来检索 Secret 值,并使用 django-environ 软件包将这些值加载到 Django 环境中。Secret 配置为可供 App Engine 标准环境访问。

  1. 创建一个名为 .env 的文件,定义数据库连接字符串、媒体存储分区名称和新的 SECRET_KEY 值:

    echo DATABASE_URL=postgres://DATABASE_USERNAME:DATABASE_PASSWORD@//cloudsql/PROJECT_ID:REGION:INSTANCE_NAME/DATABASE_NAME > .env
    echo GS_BUCKET_NAME=PROJECT_ID_MEDIA_BUCKET >> .env
    echo SECRET_KEY=$(cat /dev/urandom | LC_ALL=C tr -dc '[:alpha:]'| fold -w 50 | head -n1) >> .env
    
  2. 将 Secret 存储在 Secret Manager 中:

    控制台

    1. 在 Google Cloud 控制台中,前往 Secret Manager 页面

      转到 Secret Manager 页面

    2. 点击创建 Secret

    3. 名称字段中,输入 django_settings

    4. Secret 值对话框中,粘贴 .env 文件的内容。

    5. 点击创建密钥

    6. 删除本地文件以防止本地设置覆盖

    gcloud

    1. 使用 .env 文件的值创建新的 Secret django_settings

      gcloud secrets create django_settings --data-file .env
      
    2. 删除本地文件以防止本地设置覆盖

      rm .env
      
  3. 配置对 Secret 的访问权限:

    控制台

  4. 点击权限标签页。

  5. 点击授予访问权限

  6. 新成员字段中,输入 PROJECT_ID@appspot.gserviceaccount.com,然后按 Enter

  7. 角色下拉菜单中,选择 Secret Manager Secret Accessor

  8. 点击保存

gcloud

  1. 向 App Engine 标准环境服务账号授予对 Secret 的访问权限

    gcloud secrets add-iam-policy-binding django_settings \
        --member serviceAccount:PROJECT_ID@appspot.gserviceaccount.com \
        --role roles/secretmanager.secretAccessor
    

在输出中,确认 bindings 列出了新服务账号。

在本地计算机上运行应用

配置支持性服务后,您现在可以在计算机上运行应用。此设置允许本地开发、创建超级用户以及应用数据库迁移。

  1. 在单独的终端中启动 Cloud SQL Auth 代理:

    Linux/macOS

    ./cloud-sql-proxy PROJECT_ID:REGION:INSTANCE_NAME
    

    Windows

    cloud-sql-proxy.exe PROJECT_ID:REGION:INSTANCE_NAME
    

    此步骤会建立从本地计算机到您的 Cloud SQL 实例的连接,以进行本地测试。在您对应用进行本地测试的整个过程中,请确保 Cloud SQL Auth 代理一直运行。通过在单独的终端中运行此进程,您可以在此进程运行时继续工作。

  2. 在原始终端中,在本地设置项目 ID(供 Secret Manager API 使用):

    Linux/macOS

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
    

    Windows

    set GOOGLE_CLOUD_PROJECT=PROJECT_ID
    
  3. 设置环境变量以表明您正在使用 Cloud SQL Auth 代理(可在代码中识别此值):

    Linux/macOS

    export USE_CLOUD_SQL_AUTH_PROXY=true
    

    Windows

    set USE_CLOUD_SQL_AUTH_PROXY=true
    
  4. 运行 Django 迁移以设置模型和资源:

    python manage.py makemigrations
    python manage.py makemigrations polls
    python manage.py migrate
    python manage.py collectstatic
    
  5. 启动 Django 网络服务器:

    python manage.py runserver 8080
    
  6. 在浏览器中,前往 http://localhost:8080

    如果您使用的是 Cloud Shell,请点击网页预览按钮,然后选择在端口 8080 上预览

    该页面将显示以下文本:“Hello, world. You're at the polls index."。您的计算机上运行的 Django 网络服务器会提供示例应用页面。

  7. Ctrl/Cmd+C 停止本地网络服务器。

使用 Django 管理控制台

若要登录 Django 的管理控制台,您需要创建超级用户。由于您具有可在本地访问的数据库连接,因此可以运行管理命令:

  1. 创建超级用户。系统将提示您输入用户名、电子邮件和密码。

    python manage.py createsuperuser
    
  2. 启动本地网络服务器:

    python manage.py runserver
    
  3. 在浏览器中,转到 http://localhost:8000/admin

  4. 使用您在运行 createsuperuser 时使用的用户名和密码登录管理站点。

将应用部署到 App Engine 标准环境

设置所有支持性服务并在本地测试应用后,您现在可以将应用部署到 App Engine 标准环境了:

  1. 运行以下命令来上传应用,该命令会部署应用(如 app.yaml 中所述),并将新部署的版本设置为默认版本,从而使其能够处理所有新流量:
    gcloud app deploy
  2. 出现提示时,输入“yes”以确认设置。
  3. 等待更新已完成的通知消息。
  4. 打开 app.yaml 并使用已部署的网址更新 APPENGINE_URL 的值:
    ...
    env_variables:
        APPENGINE_URL: https://PROJECT_ID.uc.r.appspot.com
    
  5. 上传您的配置更改:
    gcloud app deploy

运行已部署的应用

应用已部署,现在可以访问:

  • 打开已部署的网站:

    gcloud app browse
    
  • 或者,您也可以显示网址并将其手动打开:

    gcloud app describe --format "value(defaultHostname)"
    

您的请求由在 App Engine 标准环境中运行的网络服务器来进行处理。

更新应用

如需更新应用,请对代码进行更改,然后再次运行 gcloud app deploy 命令。

部署会创建应用的新版本并将其提升为默认版本。应用的早期版本仍会保留。所有这些应用版本都是可计费资源。要减少费用,请删除应用的非默认版本。

针对生产环境进行配置

现在,您已有一个有效的 Django 部署,但您可以采取进一步措施来确保应用可用于生产环境。

停用调试功能

确认 mysite/settings.py 中的 DEBUG 变量设置为 False。这样可防止向用户显示详细的错误页面,否则可能会泄露配置的相关信息

限制数据库用户特权

使用 Cloud SQL 创建的任何用户都具有与 cloudsqlsuperuser 角色相关联的权限: CREATEROLECREATEDBLOGIN

为了防止 Django 数据库用户拥有这些权限,请在 PostgreSQL 中手动创建用户。您需要安装 psql 交互式终端,或使用预安装此工具的 Cloud Shell。

控制台

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

  2. 在 Cloud Shell 中,使用内置的终端连接到您的 INSTANCE_NAME 实例:

    gcloud sql connect INSTANCE_NAME --user postgres
    
  3. 输入 postgres 用户密码。

    您目前使用的是 psql。您应该会看到 postgres=> 提示符。

  4. 创建用户:

    CREATE USER DATABASE_USERNAME WITH PASSWORD 'DATABASE_PASSWORD';
    

    PASSWORD 替换为随机的唯一密码。

  5. 向新用户授予对新数据库的完整权限:

    GRANT ALL PRIVILEGES ON DATABASE DATABASE_NAME TO DATABASE_USERNAME;
    
  6. 退出 psql

    \q
    

gcloud

  1. 启动与 SQL 实例的连接:

    gcloud sql connect INSTANCE_NAME --user postgres
    

    INSTANCE_NAME 替换为创建的 Cloud SQL 实例。

  2. 输入 postgres 用户密码。

    您目前使用的是 psql。您应该会看到 postgres=> 提示符。

  3. 创建用户:

    CREATE USER DATABASE_USERNAME WITH PASSWORD 'DATABASE_PASSWORD';
    
  4. 向新用户授予对新数据库的完整权限:

    GRANT ALL PRIVILEGES ON DATABASE DATABASE_NAME TO DATABASE_USERNAME;
    
  5. 退出 psql

    \q
    

了解代码

示例应用

Django 示例应用使用标准 Django 工具创建。以下命令将创建项目及意见调查应用:

django-admin startproject mysite
python manage.py startapp polls

基础视图、模型和路由配置是从编写您的第一个 Django 应用第 1 部分第 2 部分)复制的。

Secret Manager 中的 Secret

settings.py 文件包含的代码使用 Secret Manager Python API 来检索指定 Secret 的最新版本并将其拉取到环境中(使用 django-environ):

env = environ.Env(DEBUG=(bool, False))
env_file = os.path.join(BASE_DIR, ".env")

if os.path.isfile(env_file):
    # Use a local secret file, if provided

    env.read_env(env_file)
# ...
elif os.environ.get("GOOGLE_CLOUD_PROJECT", None):
    # Pull secrets from Secret Manager
    project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")

    client = secretmanager.SecretManagerServiceClient()
    settings_name = os.environ.get("SETTINGS_NAME", "django_settings")
    name = f"projects/{project_id}/secrets/{settings_name}/versions/latest"
    payload = client.access_secret_version(name=name).payload.data.decode("UTF-8")

    env.read_env(io.StringIO(payload))
else:
    raise Exception("No local .env or GOOGLE_CLOUD_PROJECT detected. No secrets found.")

Secret 用于存储多个 Secret 值,以减少需要配置的不同 Secret 的数量。

CSRF 配置

Django 具有防范跨网站请求伪造 (CSRF) 的内置保护功能。从 Django 4.0 开始,对此功能的工作方式的更改意味着必须告知 Django 此功能的托管网址,以便 Django 可为提交数据的用户提供最佳保护。

您可以在 settings.py 文件中提供应用的网址作为环境变量。这是 Django 用于相关设置的值。

# SECURITY WARNING: It's recommended that you use this when
# running in production. The URL will be known once you first deploy
# to App Engine. This code takes the URL and converts it to both these settings formats.
APPENGINE_URL = env("APPENGINE_URL", default=None)
if APPENGINE_URL:
    # Ensure a scheme is present in the URL before it's processed.
    if not urlparse(APPENGINE_URL).scheme:
        APPENGINE_URL = f"https://{APPENGINE_URL}"

    ALLOWED_HOSTS = [urlparse(APPENGINE_URL).netloc]
    CSRF_TRUSTED_ORIGINS = [APPENGINE_URL]
    SECURE_SSL_REDIRECT = True
else:
    ALLOWED_HOSTS = ["*"]

本地 Secret 替换

如果系统在本地文件系统上发现 .env 文件,则使用该文件,而不是 Secret Manager 中的值。在本地创建 .env 文件有助于进行本地测试(例如,针对 SQLite 数据库进行本地开发,或者进行其他本地设置)。

数据库连接

settings.py 文件包含 SQL 数据库的配置。它使用 django-environ 中的 env.db() 帮助程序将 DATABASE_URL 中设置的连接字符串加载到 DATABASES 设置中。

在本地运行应用并使用 Cloud SQL Auth 代理访问托管数据库时,USE_CLOUD_SQL_AUTH_PROXY 标志会调整数据库设置以使用代理。

# Use django-environ to parse the connection string
DATABASES = {"default": env.db()}

# If the flag as been set, configure to use proxy
if os.getenv("USE_CLOUD_SQL_AUTH_PROXY", None):
    DATABASES["default"]["HOST"] = "127.0.0.1"
    DATABASES["default"]["PORT"] = 5432

托管的静态内容

app.yaml 文件包含用于部署到 App Engine 的配置信息。此 app.yaml 文件指定 App Engine 将从 static/ 目录传送静态文件:

runtime: python39

env_variables:
  # This setting is used in settings.py to configure your ALLOWED_HOSTS
  # APPENGINE_URL: PROJECT_ID.uc.r.appspot.com

handlers:
# This configures Google App Engine to serve the files in the app's static
# directory.
- url: /static
  static_dir: static/

# This handler routes all requests not caught above to your main app. It is
# required when static routes are defined, but can be omitted (along with
# the entire handlers section) when there are no static files defined.
- url: /.*
  script: auto

在本地运行启用了 DEBUG 的应用后,Django 将在本地传送这些文件:

from django.conf import settings
from django.conf.urls.static import static
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("", include("polls.urls")),
    path("admin/", admin.site.urls),
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

清理

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用,请删除包含这些资源的项目,或者保留项目但删除各个资源。

删除项目

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

后续步骤