Skip to main content

简介

要在 Square Cloud 上开发和托管 Django 应用,遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程,从初始设置到生产环境部署。

前置条件

  • Square Cloud 账户:通过注册页面使用你的邮箱进行注册。
  • 有效套餐:为你的应用提供专属资源和优化的性能。查看我们可用的套餐,选择最适合你需求的方案。
本指南运行在 Python 运行时上。已于 2026 年 9 月在 Python 3.13 上使用 Django 6 测试。

创建项目

你的电脑上需要安装 Python 和 pip。如果尚未安装,可以从 Python 官方网站 下载 Python。

安装库

安装 Django、生产服务器 Gunicorn,以及用于提供静态文件的 WhiteNoise:

开发项目

创建一个新的 Django 项目并进入其文件夹:
这会创建 manage.py 以及包含 settings.py、urls.py 和 wsgi.py 的 mysite/ 包。要添加一个基础路由,请编辑 mysite/urls.py:
mysite/urls.py

为生产环境配置设置

永远不要在代码中硬编码密钥。在 mysite/settings.py 中,从环境变量读取密钥和生产环境标志,信任你网站的 HTTPS 源,并启用 WhiteNoise。生成的其余设置保持不变:
mysite/settings.py
将 mysite.squareweb.app 替换为你的子域名或自定义域名。然后通过控制面板或使用 squarecloud app env set,在应用中设置以下环境变量:
要在本地运行项目,请在终端中设置 DJANGO_SECRET_KEY(任意值)和 DJANGO_DEBUG=True,然后运行 python manage.py runserver。
然后在 manage.py 旁边的 requirements.txt 文件中列出依赖。Square Cloud 会在启动应用之前用 pip 安装它们。其中至少需要列出:
requirements.txt

选择生产服务器

Django 内置的开发服务器(runserver)不适合用于生产环境。请使用面向生产的 WSGI 服务器 Gunicorn,并由下面的 START 命令启动它。有关 worker 设置和其他选项,请参阅 Gunicorn 指南:

Gunicorn

Gunicorn 是一个用于 UNIX 的 Python WSGI HTTP 服务器。它采用预派生(pre-fork)工作进程模型,会派生多个工作进程来处理请求。 这使它成为在生产环境中运行 Python Web 应用的绝佳选择。

端口和主机

下面的 START 命令会将 Gunicorn 绑定到 0.0.0.0:80:即所有网络接口,以及 Square Cloud 路由到你应用的端口。Django 本身没有需要修改的端口设置。

配置 Square Cloud

在 manage.py 旁边创建 squarecloud.app 文件:
squarecloud.app
每次启动时,该命令会:
  • collectstatic 将你的静态文件复制到 STATIC_ROOT,由 WhiteNoise 从那里提供这些文件。
  • migrate 应用待执行的数据库迁移。数据库已是最新时,它不会做任何事。
  • python -m gunicorn mysite.wsgi --bind 0.0.0.0:80 在 80 端口和所有网络接口上提供 mysite 项目的 WSGI 应用。
MAIN=manage.py 会选择 Python 运行时。通过控制面板上传时,请设置相同的主文件和启动命令。

ZIP 中包含哪些文件

  • manage.py 以及包含你的应用和模板的 mysite/ 包。
  • requirements.txt。
  • squarecloud.app。
manage.py、requirements.txt 和 squarecloud.app 必须位于 ZIP 的根目录。不要包含 .venv、__pycache__、staticfiles/(每次启动时由 collectstatic 重新生成)以及本地的 db.sqlite3。

部署并验证

通过控制面板

1

访问上传页面

访问上传页面并上传你的项目 zip 文件。
2

配置你的环境

上传 zip 后,你需要为项目配置名称、主文件或运行时环境以及其他设置。
如果你上传的是 Web 项目,请务必选择 “Web Publication” 并为项目设置子域名。
3

部署你的项目

最后,点击 “Deploy” 按钮,即可将项目托管到 Square Cloud。
部署完成后,你可以在控制面板中监控项目的状态和日志。
正在上传应用到 Square Cloud
4

确认你的应用已上线

首次部署通常在一分钟内完成。在控制面板中,等待你的应用状态显示为运行中,并检查日志中是否有启动错误。
如果你部署的是网站或 API,请在浏览器中打开 https://<your-subdomain>.squareweb.app,你应该能看到应用正常响应。如果你部署的是机器人,发送一条命令确认它已上线。
应用无法启动?请参见故障排除指南,了解最常见的原因和解决方法。

通过 CLI

要使用此方法,你的项目根目录中需要有一个名为 squarecloud.app 的配置文件。它告诉 Square Cloud 如何运行你的应用。

配置文件指南

了解如何创建定义你应用环境的 squarecloud.app 配置文件。
1

安装 CLI

安装 Square Cloud CLI。如果你已经安装,运行同一条命令即可更新:
2

登录

运行下面的命令。它会打开你的浏览器:在浏览器中批准登录后,CLI 即可使用。无需复制任何 API 密钥。如需在脚本和 CI 中使用,请参阅 CLI 身份验证。
3

上传你的项目

在项目文件夹中运行下面的命令。CLI 会将当前文件夹打包为 zip(排除 squarecloud.ignore 中列出的内容)并上传:
要上传你自己创建的 zip,请通过 --file 传入:
4

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志:
如果你部署的是网站或 API,请在浏览器中打开 https://<your-subdomain>.squareweb.app,你应该能看到应用正常响应。如果你部署的是机器人,发送一条命令确认它已上线。
应用无法启动?请参见故障排除指南,了解最常见的原因和解决方法。

常见错误

自定义域名

若要使用自定义域名(例如 mysite.com)来代替默认 URL mysite.squareweb.app,你需要 Standard 计划或更高等级。默认 URL 由配置文件中的 SUBDOMAIN 字段决定。要连接你的域名,请参阅如何设置自己的域名。

最低内存要求

网站和 API 的最低要求为 512MB RAM,足以在静态运行时上托管静态构建产物。对于在服务器上渲染页面的应用(Next.js、Nuxt、Angular SSR 等),我们建议至少 1GB RAM。对于更大型的应用,请分配更多 RAM,以防止应用内存耗尽而崩溃。

找不到此站点。

请检查子域名/域名是否与 SUBDOMAIN 字段或自定义域名设置中配置的内容一致。如果你刚上传站点,请等待最多 60 秒,让 Square 启用首次访问。

站点响应超时……

你的服务器必须监听端口 80 和主机 0.0.0.0。Square Cloud 会在你的应用中设置 PORT(80)和 HOST(0.0.0.0)环境变量:请在代码中读取它们,而不要硬编码其他值。只监听 localhost 或 127.0.0.1 的服务器永远收不到请求。

KeyError: ‘DJANGO_SECRET_KEY’

缺少该环境变量。请按照为生产环境配置设置中的说明设置 DJANGO_SECRET_KEY,然后重启应用。

Bad Request (400)

你打开的地址不在 DJANGO_ALLOWED_HOSTS 中。请将你的子域名或自定义域名添加进去,然后重启应用。

后续步骤

环境变量

将密钥和设置放在代码之外,并在运行时读取。

自定义域名

在 Standard 及以上计划中,用你自己的域名提供应用。

故障排除

修复无法启动的应用或没有响应的站点。
有关 Django 的更多信息,请参阅 Django 官方文档及其部署检查清单。

联系我们

如果你仍然遇到技术问题,我们的专业支持团队可以为你提供帮助。联系我们,我们很乐意协助你解决任何问题,支持质量正是开发者给予 Square Cloud 4.9/5 评分(共 402 条评价)(Google 与 Trustpilot)的重要原因之一。