PostgreSQL 教程: 在 Ubuntu 服务器上部署 pgAdmin 4

十月 4, 2023

摘要:在本教程中,我们将逐步介绍在 Ubuntu 18.04 服务器上安装和配置最新版本的 pgAdmin,通过 Web 浏览器访问 pgAdmin,并将其连接到 PostgreSQL 数据库服务器的过程。

介绍

pgAdmin 是 PostgreSQL 及其相关数据库管理系统的开源管理和开发平台。它用 Python 和 jQuery 编写,支持 PostgreSQL 中的所有功能。您可以使用 pgAdmin 执行从编写基本 SQL 查询到监控数据库和配置高级数据库架构的所有操作。

前提条件

要完成本教程,您将需要:

  • 运行 Ubuntu 18.04 的服务器。该服务器应该有一个具有 sudo 权限的非 root 用户,以及配置了ufw的防火墙。
  • 安装 Nginx 并配置为http://unix:/tmp/pgadmin4.sock的反向代理。
  • 已在您的服务器上安装 PostgreSQL。您可以按照我们的如何在 Ubuntu 上安装和使用 PostgreSQL指南进行设置。当您遵循本指南时,请务必创建一个新的角色和数据库,因为您将需要两者来将 pgAdmin 连接到您的 PostgreSQL 实例。
  • 您的服务器上安装了Python 3,并在 Python 中部署了虚拟环境venv

步骤 1. 安装 pgAdmin 及其依赖组件

当前 pgAdmin 的最新版本是 pgAdmin 4,而通过官方 Ubuntu 软件仓库提供的最新版本是 pgAdmin 3。不过,pgAdmin 3 不再受社区支持,项目维护者建议安装 pgAdmin 4。在此步骤中,我们将在虚拟环境中逐步安装最新版本的 pgAdmin 4(按照项目开发团队的建议),并使用apt安装依赖的组件。

首先,如果您最近没有更新服务器的软件包索引,请先更新:

sudo apt update

接下来,安装以下依赖项。其中包括libgmp3-dev,它是一个多精度算术库;还有libpq-dev,其中包括一些头文件和有助于与 PostgreSQL 后端通信的静态库:

sudo apt install libgmp3-dev libpq-dev

接下来,创建一些目录,pgAdmin 会在其中存放会话数据、存储数据和日志:

sudo mkdir -p /var/lib/pgadmin4/sessions
sudo mkdir /var/lib/pgadmin4/storage
sudo mkdir /var/log/pgadmin4

然后,将这些目录的所有权更改为您的非 root 用户和组。这是必要的,因为它们当前由您的 root 用户拥有,但我们将从您的非 root 用户拥有的虚拟环境中安装 pgAdmin,并且安装过程会在这些目录中创建一些文件。但是,安装完成后,我们会将所有权更改为 www-data 用户和组,以便可以将其开放给网络访问:

sudo chown -R sammy:sammy /var/lib/pgadmin4
sudo chown -R sammy:sammy /var/log/pgadmin4

接下来,打开您的虚拟环境。导航到您的编程环境所在的目录并激活它。我们将进入environments目录,并激活my_env环境:

cd environments/
source my_env/bin/activate

激活虚拟环境后,请谨慎确保您的系统上安装了最新版本的pip。Ubuntu 18.04 软件仓库默认提供的pip版本是 9.0.1,而最新版本是 21.0.1。如果您按照前提条件中所述安装了python3-pip软件包,但尚未将其升级到最新版本,则在下一步配置 pgAdmin 时将会遇到问题。

要升级pip到最新版本,请运行以下命令:

python -m pip install -U pip

接下来,将 pgAdmin 4 源代码下载到您的计算机上。要查找最新版本的源代码,请导航至 pgAdmin 4 (Python Wheel) 下载页面。单击最新版本的链接(v6.10,截至撰写本文时),然后在下一页单击 pip 的链接。从此文件浏览器页面中,复制以.whl结尾的文件链接,这是用于 Python 发行版的标准内置包格式。然后返回终端并运行以下wget命令,确保将链接替换为从 PostgreSQL 站点复制的链接,这会将.whl文件下载到您的服务器:

wget https://ftp.postgresql.org/pub/pgadmin/pgadmin4/v6.10/pip/pgadmin4-6.10-py3-none-any.whl

接下来安装wheel软件包,请参考下wheel软件包的标准。该软件包是一个 Python 库,可用作构建wheel的扩展,有一个用于处理.whl文件的命令行工具:

python -m pip install wheel

然后使用以下命令安装 pgAdmin 4 软件包:

python -m pip install pgadmin4-6.10-py3-none-any.whl

接下来,安装 Gunicorn,这是一个 Python WSGI 服务,在本教程后面将与 Nginx 一起使用来提供pgadmin的 Web 界面:

python -m pip install gunicorn

这负责安装 pgAdmin 及其依赖项。不过,在将其连接到数据库之前,您需要对程序的配置进行一些更改。

步骤 2. 配置 pgAdmin 4

尽管 pgAdmin 已安装在您的服务器上,但您还是需要执行几个步骤,以确保它具有正确提供 Web 界面所需的权限和配置。

pgAdmin 的主配置文件config.py,是在任何其他配置文件之前读取的。它的内容可以用作进一步配置设置的参考点,这些设置可以在 pgAdmin 的其他配置文件中指定,但为了避免不可预见的错误,您不应编辑config.py文件本身。我们将向名为config_local.py的新文件添加一些配置更改,该文件会在主文件之后被读取。

现在,使用您喜欢的文本编辑器创建此文件。在这里,我们将使用nano

nano my_env/lib/python3.10/site-packages/pgadmin4/config_local.py

在文件my_env/lib/python3.10/site-packages/pgadmin4/config_local.py中,添加以下内容:

LOG_FILE = '/var/log/pgadmin4/pgadmin4.log'
SQLITE_PATH = '/var/lib/pgadmin4/pgadmin4.db'
SESSION_DB_PATH = '/var/lib/pgadmin4/sessions'
STORAGE_DIR = '/var/lib/pgadmin4/storage'
SERVER_MODE = True

以下是这五个参数的作用:

  • LOG_FILE:这定义了 pgAdmin 日志文件的存放路径。
  • SQLITE_PATH:pgAdmin 将用户相关数据存储在 SQLite 数据库中,该参数用于指示 pgAdmin 该配置数据库的存储路径。由于该文件位于持久目录/var/lib/pgadmin4/下,因此在升级后您的用户数据不会丢失。
  • SESSION_DB_PATH:指定用于存储会话数据的目录位置。
  • STORAGE_DIR:指定用于存储其他数据的位置,例如备份和安全证书。
  • SERVER_MODE:设置该参数为True,用于指示 pgAdmin 以服务器模式运行,而不是桌面模式。

请注意,每个文件路径都指向您在步骤 1 中创建的目录。

添加这些行后,保存并关闭文件。如果您使用过nano,请按CTRL + X,然后按Y,然后按ENTER

完成这些配置后,运行 pgAdmin 设置脚本来设置您的登录凭据:

python my_env/lib/python3.10/site-packages/pgadmin4/setup.py

运行此命令后,您将看到一条提示,要求您输入电子邮件地址和密码。当您稍后访问 pgAdmin 时,这些将作为您的登录凭据,因此请务必记住或记下您在此处输入的内容:

. . .
Enter the email address and password to use for the initial pgAdmin user account:

Email address: sammy@example.com
Password:
Retype password:

至此,pgAdmin 已配置完成。但是,您的服务器尚未开放该服务,因此仍然无法访问。为了解决这个问题,我们将配置 Gunicorn 和 Nginx 来为 pgAdmin 提供服务,以便您可以通过 Web 浏览器访问其用户界面。

步骤 3. 启动 Gunicorn 并配置 Nginx

您将使用 Gunicorn 为 pgAdmin 作为 Web 应用程序提供服务。然而,作为应用程序服务器,Gunicorn 只能在本地使用,无法通过互联网访问。为了使其可以远程使用,您需要使用 Nginx 作为反向代理。

完成将 Nginx 设置为反向代理的前提条件后,您的 Nginx 配置文件/etc/nginx/sites-available/your_domain将包含以下内容:

server {
    listen 80;
    listen [::]:80;

    server_name your_domain www.your_domain;
        
    location / {
        proxy_pass http://unix:/tmp/pgadmin4.sock;
        include proxy_params;
    }
}

该反向代理配置使您可以在本地浏览器中访问 Gunicorn 服务器。启动 Gunicorn 服务器和 pgAdmin 应用程序:

gunicorn --bind unix:/tmp/pgadmin4.sock --workers=1 --threads=25 --chdir ~/environments/my_env/lib/python3.10/site-packages/pgadmin4 pgAdmin4:app

输出

[2022-08-29 00:19:11 +0000] [7134] [INFO] Starting gunicorn 20.1.0
[2022-08-29 00:19:11 +0000] [7134] [INFO] Listening at: unix:/tmp/pgadmin4.sock (7134)
[2022-08-29 00:19:11 +0000] [7134] [INFO] Using worker: gthread
[2022-08-29 00:19:11 +0000] [7135] [INFO] Booting worker with pid: 7135

注意:以这种方式调用 Gunicorn 会将进程与您的终端联系起来。对于更长期的解决方案,请使用 Supervisor 等程序调用 Gunicorn。

随着 Gunicorn 充当可通过 Nginx 反向代理访问的应用程序服务器,您就可以在 Web 浏览器中访问 pgAdmin 了。

步骤 4. 访问 pgAdmin

在您的本地计算机上,打开您首选的 Web 浏览器,并导航到 pgAdmin 服务器的 IP 地址:

http://your_server_ip

导航进去后,您将看到类似于以下内容的登录屏幕:

pgAdmin login screen

输入您在步骤 2 中设置的登录凭据,您将进入 pgAdmin 欢迎屏幕:

pgAdmin Welcome Page

现在您已经确认可以访问 pgAdmin 界面,剩下要做的就是将 pgAdmin 连接到您的 PostgreSQL 数据库。不过,在此之前,您需要对 PostgreSQL 超级用户的配置进行一项小更改。

步骤 5. 配置您的 PostgreSQL 用户

如果您遵循了在 Ubuntu 上安装 PostgreSQL 的教程,您应该已经在您的服务器上安装了 PostgreSQL,并设置了新的超级用户角色和数据库。

在 PostgreSQL 中,默认使用“识别协议”或 “ident” 身份验证方法验证您的数据库用户身份。这涉及 PostgreSQL 获取客户端的 Ubuntu 用户名,并将其用作允许的数据库用户名。在许多情况下,这可以提高安全性,但在您希望外部程序(例如 pgAdmin)连接到您的数据库的情况下,它也可能会导致问题。为了解决这个问题,我们将为这个 PostgreSQL 角色设置一个密码,这将允许 pgAdmin 连接到您的数据库。

在终端中,以超级用户角色打开 PostgreSQL 命令提示符:

sudo -u sammy psql

在 PostgreSQL 提示符下,更新用户配置以拥有您选择的强密码:

ALTER USER sammy PASSWORD 'password';

然后退出 PostgreSQL 提示符:

\q

接下来,返回浏览器中的 pgAdmin 4 界面,找到左侧的 浏览器 菜单。右键单击 服务器 以打开上下文菜单,将鼠标悬停在 创建 上,然后单击 服务器…

Create Server context menu

这将导致浏览器中弹出一个窗口,您可以在其中输入有关服务器、角色和数据库的信息。

常规 选项卡中,输入该服务器的名称。这可以是任何您想要的名称,但您可能会发现使其具有描述性会很有帮助。在我们的示例中,服务器名为Sammy-server-1

Create Server - General tab

接下来,单击 连接 选项卡。在 主机名/地址 字段中,输入localhost端口号 默认会设置为5432,这对于本次设置是适用的,因为这是 PostgreSQL 使用的默认端口。

维护数据库 字段中,输入您要连接的数据库的名称。请注意,该数据库必须已在您的服务器上创建。然后,分别在 用户名密码 字段中输入您之前配置的 PostgreSQL 用户名和密码。

Create Server - Connection tab

其他选项卡中的空白字段是可选的,只有当您有需要的特定设置时才需要填写它们。单击 保存 按钮,数据库将出现在 浏览器 菜单中的 服务器 下。

您已成功将 pgAdmin 4 连接到 PostgreSQL 数据库。您可以从 pgAdmin 面板执行与 PostgreSQL 提示符下相同的任何操作。为了说明这一点,我们将创建一个示例表,并通过 Web 界面填充一些示例数据。

步骤 6. 在 pgAdmin 面板中创建表

在 pgAdmin 面板中,找到窗口左侧的 浏览器 菜单。单击 服务器 (1) 旁边的加号 (+) 以展开其中的树形菜单。接下来,单击您在上一步中添加的服务器左侧的加号(在我们的示例中为 Sammy-server-1),然后展开 数据库 以及您添加的数据库的名称(在我们的示例中为 sammy),然后 模式 (1)。您应该看到如下所示的树形菜单:

Expanded Browser tree menu

右键单击 列表项,然后将光标悬停在 创建 上,然后单击 表…

Create Table context menu

这将打开一个 创建表 窗口。在此窗口的 常规 选项卡下,输入表的名称。这可以是任何您想要的名称,但为了简单起见,我们将其称为 table-01

Create Table - General tab

然后导航到 选项卡并单击窗口右上角的 + 号以添加一些列。添加列时,您需要为其指定 名称数据类型,如果您选择的数据类型需要指定长度,您可能需要选择 长度

此外,官方 PostgreSQL 文档指出,向表添加主键通常是一种最佳实践。主键是一种约束,指示可用作表行特殊标识符的特定列或列集。这不是必需的,但如果您想将一列或多列设置为主键,请将最右侧的开关从No切换为Yes

单击 保存 按钮创建表。

Create Table - Columns Tab with Primary Key turned on

至此,您已经创建了一个表并向其中添加了几列。但是,这些列尚不包含任何数据。要将数据添加到新表中,请右键单击 浏览器 菜单中的表名称,将光标悬停在 脚本 上,然后单击 INSERT 脚本

INSERT script context menu

这将在面板上打开一个新面板。在顶部,您将看到一个部分完成的INSERT语句,其中包含相应的表名和列名。继续用一些虚拟数据替换问号 (?),确保您添加的数据与您为每列选择的数据类型一致。请注意,您还可以通过将每行添加到一组新的括号中来添加多行数据,每组括号之间用逗号分隔,如下例所示。

如果您愿意,请随意用以下示例INSERT语句替换部分完成的INSERT脚本:

INSERT INTO public."table-01"(
    col1, col2, col3)
    VALUES ('Juneau', 14, 337), ('Bismark', 90, 2334), ('Lansing', 51, 556);

Example INSERT statement

单击横向三角形图标 () 来执行该INSERT语句。请注意,在旧版本的 pgAdmin 中,执行图标是闪电 ()。

要查看表及其中的所有数据,请再次右键单击 浏览器 菜单中的表名称,将光标悬停在 查看/编辑数据 上,然后选择 所有行

View/Edit Data, All Rows context menu

这将打开另一个新面板,在该面板下方的下部面板的 数据输出 选项卡中,您可以查看该表中保存的所有数据。

View Data - example data output

这样,您就成功创建了一个表,并通过 pgAdmin 的 Web 界面向其中填充了一些数据。当然,这只是您可以用来通过 pgAdmin 创建表的一种方法。例如,也可以使用 SQL 而不是此步骤中描述的基于图形界面的方法来创建和填充表。

结论

在本指南中,您学习了如何从 Python 虚拟环境安装 pgAdmin 4、对其进行配置、使用 Gunicorn 和 Nginx 为其提供网络访问服务,以及如何将其连接到 PostgreSQL 数据库。此外,本指南介绍了一种可用于创建和填充表的方法,但 pgAdmin 的用途不仅仅是创建和编辑表。

有关如何充分利用 pgAdmin 的所有功能的更多信息,我们鼓励您查看该项目的文档。您还可以通过我们提供的社区教程,了解有关 PostgreSQL 的更多信息。