19.2 pgAdmin4 管理工具

警告

请注意 Bug 7836、Bug 8869。

本文基于 FreeBSD 14.3-RELEASE 操作系统环境展开。

pgAdmin4 是一款用于管理 PostgreSQL 数据库服务器的开源软件，作为 PostgreSQL 官方推荐的图形化管理工具，在数据库开发与运维领域具有广泛应用。它提供功能丰富的图形用户界面，便于数据库管理。pgAdmin4 使用 Python 和 JavaScript/jQuery 编写，支持多种操作系统环境（如 Windows、UNIX、Linux 等），可在桌面模式和服务器模式下运行。

注意

在安装 pgAdmin4 前，请先安装 PostgreSQL 数据库，否则 pgAdmin4 会安装失败。

pgAdmin4 需要在 Python 环境下运行，且安装时需使用 Python 的 pip 包管理工具。因此，应先安装 Python。本文以系统默认的 Python 版本为例进行说明，请注意，FreeBSD 系统可能默认未安装 Python。可通过启动 Python 解释器确认是否已安装：

# python
python: Command not found   # 说明当前未安装 python 环境

技巧

你可使用以下命令查看已安装的 Python 3 版本：

$ python3 -V
Python 3.11.12

安装 Python 及 pip

使用 pkg 安装：

# pkg install python3 py311-pip

或者使用 Ports：

# cd /usr/ports/lang/python/ && make install clean
# cd /usr/ports/devel/py-pip/ && make install clean

说明：pip 是 Python 的包管理器，用于安装和管理 Python 包以及依赖包的关系。

安装配置 virtualenv

virtualenv 的功能是创建虚拟 Python 环境，即为每个项目提供独立的 Python 环境。virtualenv 会创建独立的 Python 安装环境，不会使用全局或其他虚拟环境的库。

本文通过 virtualenv 创建独立的 Python 环境来安装 pgAdmin4。

以下命令用于安装 virtualenv：

使用 pkg 安装：

# pkg install devel/py-virtualenv

使用 Ports 安装：

# cd /usr/ports/devel/py-virtualenv/
# make install clean

通过运行以下命令创建名为 pgadmin4 的 Python 虚拟环境（virtual environment）：

# virtualenv pgadmin4

创建完成后，将显示如下信息：

# virtualenv pgadmin4
created virtual environment CPython3.11.12.final.0-64 in 607ms
  creator CPython3Posix(dest=/root/pgadmin4, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, via=copy, app_data_dir=/root/.local/share/virtualenv)
    added seed packages: pip==25.1.1, setuptools==80.3.1
  activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator

在 root 用户的根目录下生成了名为 pgadmin4 的虚拟环境（省略其他文件输出）：

# ls
pgadmin4

相关文件结构

/
├── root/
│   ├── pgadmin4/              # pgAdmin4 虚拟环境目录
│   │   ├── bin/
│   │   │   └── activate       # 虚拟环境激活脚本
│   │   └── lib/
│   │       └── python3.11/
│   │           └── site-packages/
│   │               └── pgadmin4/
│   │                   ├── config.py        # pgAdmin4 配置文件
│   │                   └── config_local.py  # pgAdmin4 本地配置文件
│   └── .config/
│       └── pip/
│           └── pip.conf       # pip 配置文件
├── var/
│   ├── lib/
│   │   └── pgadmin/           # pgAdmin4 数据存储目录
│   └── log/
│       └── pgadmin/           # pgAdmin4 日志目录
└── usr/
    └── ports/
        ├── lang/
        │   └── python/        # Python Port
        ├── devel/
        │   ├── py-pip/        # pip Port
        │   └── py-virtualenv/ # virtualenv Port
        └── databases/
            └── py-sqlite3/    # py-sqlite3 Port

安装 sqlite3

使用 pkg 安装：

# pkg install py311-sqlite3

技巧

注意版本要和 Port lang/python 相同。

或者使用 Ports 安装：

# cd /usr/ports/databases/py-sqlite3/
# make install clean

激活 pgadmin4 虚拟环境（命令前须加点 . 和空格）：

# . pgadmin4/bin/activate

你会看到 shell 已经变为（pgadmin4）（以下操作均在该 shell 下进行）：

(pgadmin4) #

安装 pgAdmin4

当前 pip 源要求使用 HTTPS，如系统缺少 SSL 证书，则需先安装证书包。

(pgadmin4) root@ykla:~# pkg install ca_root_nss

如遇网络问题，可通过更改 pip 镜像源，设置为清华大学镜像源：

(pgadmin4) root@ykla:~# pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
Writing to /root/.config/pip/pip.conf

安装依赖项，包括 OpenJPEG 库和 Rust 编程语言环境：

(pgadmin4) root@ykla:~# pkg install openjpeg rust

安装指定版本的 pgAdmin4（版本 9.4）：

(pgadmin4) root@ykla:~# pip install pgadmin4==9.4

注意

如果内存不足（小于 4 GB）且没有 swap，会提示 killed，如出现该问题请先添加交换空间（swap）。

故障排除

如果报错：

WARNING: Retrying (Retry(total=3, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: certificate is not yet valid (_ssl.c:1136)'))': /simple/pgadmin4/

这是由于时间不正确引发的，使用 ntpdate 同步系统时间到服务器 ntp.api.bz：

(pgadmin4) root@ykla:~# ntpdate ntp.api.bz
17 Dec 16:35:36 ntpdate[1453]: step time server 114.118.7.161 offset +401965.911037 sec

配置并运行 pgAdmin4

安装完成后，需要进行一些配置才能正常运行 pgAdmin4。

安装完成后创建 pgAdmin4 本地配置文件（注意 Python 版本）：

(pgadmin4) root@ykla:~# touch ./pgadmin4/lib/python3.11/site-packages/pgadmin4/config_local.py

警告

请不要直接将 ./pgadmin4/lib/python3.11/site-packages/pgadmin4/config.py 复制为 ./pgadmin4/lib/python3.11/site-packages/pgadmin4/config_local.py，无论怎样改动配置都不会生效，请直接创建空文件。

编辑配置 ./pgadmin4/lib/python3.11/site-packages/pgadmin4/config_local.py。实例如下：

DEFAULT_SERVER = '0.0.0.0'        # 设置 pgAdmin4 监听所有网络接口
DEFAULT_SERVER_PORT = 5050        # 设置 pgAdmin4 服务端口为 5050

• DEFAULT_SERVER 默认服务器侦听地址更改为 0.0.0.0。

• DEFAULT_SERVER_PORT 可修改应用程序监听的端口。

手动创建 pgAdmin4 数据和日志目录：

(pgadmin4) root@ykla:~# mkdir -p /var/lib/pgadmin   # 创建 pgAdmin 数据存储目录及父目录
(pgadmin4) root@ykla:~# mkdir -p /var/log/pgadmin   # 创建 pgAdmin 日志目录

配置文件编辑完成后，执行以下命令来初始化账号和登录密码。

启动 pgAdmin4 应用：

(pgadmin4) root@ykla:~# pgadmin4

显示实例如下：

NOTE: Configuring authentication for SERVER mode.
Enter the email address and password to use for the initial pgAdmin user account:
Email address: your_email		# 输入你的邮件地址
Password: your_new_password		# 输入你的登录密码，最少 6 位数；同样不会打印密码，也不会是 ***
Retype password:				# 再次输入密码
pgAdmin 4 - Application Initialisation
======================================

Starting pgAdmin 4. Please navigate to http://0.0.0.0:5050 in your browser.
 * Serving Flask app 'pgadmin'
 * Debug mode: off

现在我们已经安装并运行了 pgAdmin4，并可以通过 http://ip:5050 访问 Web 控制面板：

登录 pgAdmin4

箭头所指方向可以切换语言。

pgAdmin4 切换语言

pgAdmin4 中文界面

保持 pgAdmin4 后台运行

如果服务关闭，下次要运行时需使用 pgadmin4 的安装用户（此处是 root）进入根目录，执行如下命令激活 pgadmin4 虚拟环境并启动服务（& 表示后台运行）：

root@ykla:~# . pgadmin4/bin/activate
(pgadmin4) root@ykla:~# pgadmin4 &

升级 pgAdmin4

如需升级 pgAdmin4，可按以下步骤进行。

在本次测试中，直接使用 pip 升级 pgAdmin4 仍可能显示旧版本信息。

pgadmin4 更新频率较高，如需升级要先删除原有用 virtualenv 创建的 pgadmin4 目录，然后用安装用户再次执行如下命令，创建名为 pgadmin4 的 Python 虚拟环境：

root@ykla:~# virtualenv pgadmin4

虚拟目录创建完成后，激活 pgadmin4 虚拟环境：

root@ykla:~# . pgadmin4/bin/activate

激活后不要开启服务，直接升级 pgAdmin4 到最新版本：

(pgadmin4) root@ykla:~# pip install --upgrade pgadmin4

完成升级后启动 pgAdmin4 应用：

(pgadmin4) root@ykla:~# pgadmin4

登录账户和密码保持不变（登录后不会提示更新，版本已为最新）。

参考文献

• FreeBSD Project. PostgreSQL/Setup - FreeBSD Wiki[EB/OL]. (2024-06-09)[2026-03-25]. https://wiki.freebsd.org/PostgreSQL/Setup. 系统介绍了 FreeBSD 环境下 PostgreSQL 的安装配置方法，为本章提供了官方指南参考。

课后习题

1. 为 pgAdmin4 编写 FreeBSD rc 启动脚本，使其能随系统自动启动并以非 root 用户运行。

2. 编写 Port pgAdmin4。