21.3 pgAdmin4
警告
请注意以下上游已知问题：pgAdmin4 在 FreeBSD 上运行可能受到 Bug 7836 和 Bug 8869 的影响。
本节基于 FreeBSD 14.3-RELEASE 操作系统环境展开。
pgAdmin4 是一款用于管理 PostgreSQL 数据库服务器的开源软件，也是 PostgreSQL 官方推荐的图形化管理工具。pgAdmin4 使用 Python（Flask 框架）和 React 编写，支持多种操作系统环境（如 Windows、UNIX、Linux 等），可在桌面模式和服务器模式下运行。
注意
在安装 pgAdmin4 前，应先安装 PostgreSQL 数据库，否则 pgAdmin4 会安装失败。
pgAdmin4 需在 Python 环境下运行，安装时需使用 Python 的 pip 包管理工具，应先安装 Python。本节以系统默认的 Python 版本为例。注意，FreeBSD 系统可能默认未安装 Python，可通过启动 Python 解释程序确认：
# python
python: Command not found # 说明当前未安装 python 环境技巧
可使用以下命令查看已安装的 Python 3 版本：
sh$ python3 -V Python 3.11.12
21.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 包及其依赖。
21.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 用户的根目录下生成了虚拟环境 pgadmin4（省略其他文件输出）：
# ls
pgadmin421.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 Port21.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) #21.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）。
21.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 将系统时间同步至 NTP 服务器池 pool.ntp.org：
(pgadmin4) root@ykla:~# ntpd -q -g pool.ntp.org21.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 控制面板：
箭头所指处可以切换语言。
21.3.7 保持 pgAdmin4 后台运行
服务关闭后，若需再次运行，请使用 pgadmin4 的安装用户（此处是 root）进入根目录，执行如下命令激活 pgadmin4 虚拟环境并启动服务（& 表示后台运行）：
root@ykla:~# . pgadmin4/bin/activate
(pgadmin4) root@ykla:~# pgadmin4 &21.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登录账户和密码保持不变（登录后不会提示更新，版本已为最新）。
21.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 前端。