为你的 PostgreSQL 数据库托管 pgAdmin 4

简介

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

前置条件

Square Cloud 账户：通过注册页面使用你的邮箱进行注册。
有效套餐：为你的应用提供专属资源和优化的性能。查看我们可用的套餐，选择最适合你需求的方案。

本指南运行在 Python 运行时上。

获取项目

pgAdmin 运行在 Python 上，因此项目需要一个 requirements.txt 或 pyproject.toml（请参阅如何创建 requirements.txt）。其中列出 pgadmin4 以及一个用于提供服务的 Web 服务器。本指南使用 gunicorn：

requirements.txt

pgadmin4==9.18
gunicorn==26.2.0

与我们现成的 release 一样，这里固定了版本，因此重新安装时不会跳到带有不兼容变更的新版本。之后要更新时，在这里修改版本并重新上传项目即可。接下来，创建 config_local.py 文件。pgAdmin 启动时会读取它：这些设置让它作为 Web 服务器运行，并把它的数据、日志和 SQLite 数据库保存在应用内的 .pgadmin 文件夹中。

config_local.py

SERVER_MODE = True
MAX_LOGIN_ATTEMPTS = 3
"""
    CRITICAL 50
    ERROR    40
    WARNING  30
    SQL      25
    INFO     20
    DEBUG    10
    NOTSET    0
"""
CONSOLE_LOG_LEVEL = 10
DATA_DIR = "/application/.pgadmin/"
LOG_FILE = "/application/.pgadmin/logfile"
SQLITE_PATH = '/application/.pgadmin/pgadmin4.db'

我们已经在 pgadmin4-web releases 中准备好了部署所需的一切。你只需下载 project.zip，填写下面的两个变量并上传即可。

配置 Square Cloud

在项目根目录创建 squarecloud.app 文件：

squarecloud.app

DISPLAY_NAME=App name
RUNTIME=python
MEMORY=1024
START=python -m gunicorn --bind 0.0.0.0:80 --workers=1 --threads=4 pgadmin4.pgAdmin4:app
VERSION=recommended
SUBDOMAIN=my-pgadmin-subdomain

Gunicorn 在所有网络接口（0.0.0.0）的 80 端口上监听，Square Cloud 会将你子域名的流量转发到这里。请保持单个 worker（--workers=1），改为增加线程：使用多个 worker 时，pgAdmin 会出现 CSRF 错误。通过控制面板上传时，请手动将运行时设置为 Python，并使用相同的 START 命令作为启动命令。

环境变量

设置 2 个环境变量：PGADMIN_SETUP_EMAIL 和 PGADMIN_SETUP_PASSWORD。pgAdmin 首次启动时会用它们创建第一个用户。

.env

PGADMIN_SETUP_EMAIL=accessemail@example.com
PGADMIN_SETUP_PASSWORD=yourSecurePassword

你可以在上传表单的 Advanced configuration 中、在应用的 Environment Variables 页面中（之后重启应用），或使用 squarecloud app env set 设置它们。pgAdmin 不会读取项目根目录的 .env 文件，因此这些值只有设置为环境变量才有效。请参阅环境变量。

ZIP 中包含什么

requirements.txt 或 pyproject.toml
config_local.py
squarecloud.app

部署并验证

通过控制面板

访问上传页面

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

配置你的环境

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

部署你的项目

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

确认你的应用已上线

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

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

通过 CLI

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

配置文件指南

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

安装 CLI

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

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

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

squarecloud auth login

上传你的项目

在项目文件夹中运行下面的命令。CLI 会将当前文件夹打包为 zip（排除 squarecloud.ignore 中列出的内容）并上传：

squarecloud upload

要上传你自己创建的 zip，请通过 --file 传入：

squarecloud upload --file <path/to/zip>

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：

squarecloud app status
squarecloud app logs

如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

首次访问

打开 https://my-pgadmin-subdomain.squareweb.app，使用你设置的邮箱和密码登录。然后添加你的 PostgreSQL 服务器，即可随时随地管理它。

常见错误

自定义域名

若要使用自定义域名（例如 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 的服务器永远收不到请求。

登录后出现 CSRF 错误

pgAdmin 正在使用多个 Gunicorn worker 运行。请在 START 命令中设置 --workers=1，如果需要更多处理能力，请用 --threads 增加线程，然后重启应用。

后续步骤

托管数据库

创建一个用 pgAdmin 管理的 PostgreSQL 数据库。

数据库连接错误

修复 SSL/TLS 和连接错误。

Gunicorn

调优运行 pgAdmin 的 Web 服务器。

有关 pgAdmin 的更多信息，请参阅 pgAdmin 官方文档。

联系我们

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

Bots

网站

API 与后端

数据库

自托管应用

指南

迁移指南

为你的 PostgreSQL 数据库托管 pgAdmin 4

简介

前置条件

获取项目

配置 Square Cloud

环境变量

ZIP 中包含什么

部署并验证

通过控制面板

通过 CLI

配置文件指南

首次访问

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

登录后出现 CSRF 错误

后续步骤

托管数据库

数据库连接错误

Gunicorn

联系我们

​简介

​前置条件

​获取项目

​配置 Square Cloud

​环境变量

​ZIP 中包含什么

​部署并验证

​通过控制面板

​通过 CLI

配置文件指南

​首次访问

​常见错误

​自定义域名

​最低内存要求

​找不到此站点。

​站点响应超时……

​登录后出现 CSRF 错误

​后续步骤

托管数据库

数据库连接错误

Gunicorn

​联系我们

简介

前置条件

获取项目

配置 Square Cloud

环境变量

ZIP 中包含什么

部署并验证

通过控制面板

通过 CLI

首次访问

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

登录后出现 CSRF 错误

后续步骤

联系我们