37.3 pgAdmin4
警告
请注意以下上游已知问题：pgAdmin4 在 FreeBSD 上运行可能受到 Bug 7836 和 Bug 8869 的影响。
本节基于 FreeBSD 14.3-RELEASE 操作系统环境展开。
pgAdmin4 是一款用于管理 PostgreSQL 数据库服务器的开源软件，也是 PostgreSQL 官方推荐的图形化管理工具。pgAdmin4 使用 Python（Flask 框架）和 React 编写，支持多种操作系统环境（如 Windows、UNIX、Linux 等），可在桌面模式和服务器模式下运行。
注意
pgAdmin4 通过 pip 安装，使用 SQLite 存储自身配置数据，无需本地安装 PostgreSQL 数据库即可运行。但需连接 PostgreSQL 数据库服务器才能发挥其管理功能。
pgAdmin4 需在 Python 环境下运行，安装时需使用 Python 的 pip 包管理工具，应先安装 Python。本节以系统默认的 Python 版本为例。注意，FreeBSD 系统可能默认未安装 Python，可通过启动 Python 解释程序确认：
# python
python: Command not found # 说明当前未安装 python 环境技巧
可使用以下命令查看已安装的 Python 3 版本：
sh$ python3 -V Python 3.11.12
37.3.1 安装 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 包及其依赖。
37.3.2 安装配置 virtualenv
virtualenv 用于创建相互独立的 Python 虚拟环境。
本节通过 virtualenv 创建独立的 Python 环境来安装 pgAdmin4。
以下命令用于安装 virtualenv：
使用 pkg 安装：
# pkg install devel/py-virtualenv使用 Ports 安装：
# cd /usr/ports/devel/py-virtualenv/
# make install clean通过运行以下命令创建 Python 虚拟环境 pgadmin4（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 用户的主目录（/root）下生成了虚拟环境 pgadmin4（省略其他文件输出）：
# ls
pgadmin437.3.3 文件结构
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 Port37.3.4 安装 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) #37.3.5 安装 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）。
37.3.5.1 故障排除
如果出现以下错误：
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/以上错误由系统时间不准确所致，使用 ntpd -q -g pool.ntp.org 同步系统时间即可解决。详细说明参考本书其他相关章节。
37.3.6 配置并运行 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 服务端口为 5050DEFAULT_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 控制面板：
箭头所指处可以切换语言。
37.3.7 保持 pgAdmin4 后台运行
服务关闭后，如果需要再次运行，请使用 pgadmin4 的安装用户（此处是 root）进入其主目录，执行如下命令激活 pgadmin4 虚拟环境并启动服务（& 表示后台运行）：
root@ykla:~# . pgadmin4/bin/activate
(pgadmin4) root@ykla:~# pgadmin4 &37.3.8 升级 pgAdmin4
如需升级 pgAdmin4，可按以下步骤操作。
在本测试中，直接使用 pip 升级 pgAdmin4 仍可能显示旧版本信息。
pgAdmin4 版本更新频繁，如需升级，必须先删除原来用 virtualenv 创建的 pgadmin4 目录，随后用安装用户再次执行如下命令，创建 Python 虚拟环境 pgadmin4：
root@ykla:~# virtualenv pgadmin4虚拟目录创建完成后，激活 pgadmin4 虚拟环境：
root@ykla:~# . pgadmin4/bin/activate激活后切勿启动服务，直接升级 pgAdmin4 到最新版本：
(pgadmin4) root@ykla:~# pip install --upgrade pgadmin4完成升级后启动 pgAdmin4 应用：
(pgadmin4) root@ykla:~# pgadmin4登录账户和密码保持不变（登录后不会提示更新，版本已为最新）。
37.3.9 参考文献
- FreeBSD Project. PostgreSQL/Setup - FreeBSD Wiki[EB/OL]. (2024-06-09)[2026-03-25]. https://wiki.freebsd.org/PostgreSQL/Setup. 系统介绍了 FreeBSD 环境下 PostgreSQL 的安装配置方法，为本节提供了官方指南参考。
- pgAdmin Development Team. pgAdmin 4 GitHub Repository[EB/OL]. [2026-04-17]. https://github.com/pgadmin-org/pgadmin4. pgAdmin 4 官方仓库，记载其技术栈为 Python（Flask）后端与 React 前端。