# 19.2 pgAdmin4 管理工具

> **警告**
>
> 请注意 [Bug 7836](https://github.com/pgadmin-org/pgadmin4/issues/7836)、[Bug 8869](https://github.com/pgadmin-org/pgadmin4/issues/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 解释器确认是否已安装：

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

> **技巧**
>
> 你可使用以下命令查看已安装的 Python 3 版本：
>
> ```sh
> $ python3 -V
> Python 3.11.12
> ```

## 安装 Python 及 pip

使用 pkg 安装：

```sh
# pkg install python3 py311-pip
```

或者使用 Ports：

```sh
# 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 安装：

```sh
# pkg install devel/py-virtualenv
```

使用 Ports 安装：

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

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

```sh
# virtualenv pgadmin4
```

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

```sh
# 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` 的虚拟环境（省略其他文件输出）：

```sh
# ls
pgadmin4
```

## 相关文件结构

```sh
/
├── 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 安装：

```sh
# pkg install py311-sqlite3
```

> **技巧**
>
> 注意版本要和 Port `lang/python` 相同。

或者使用 Ports 安装：

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

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

```sh
# . pgadmin4/bin/activate
```

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

```sh
(pgadmin4) #



```

## 安装 pgAdmin4

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

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

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

```sh
(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 编程语言环境：

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

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

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

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

### 故障排除

如果报错：

```python
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：

```sh
(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 版本）：

```sh
(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`。实例如下：

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

* `DEFAULT_SERVER` 默认服务器侦听地址更改为 `0.0.0.0`。
* `DEFAULT_SERVER_PORT` 可修改应用程序监听的端口。

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

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

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

启动 pgAdmin4 应用：

```sh
(pgadmin4) root@ykla:~# pgadmin4
```

显示实例如下：

```sh
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](https://338876981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJR3FQGH1PkdRtOljuxb%2Fuploads%2Fgit-blob-82ae64bc15564cd17f38060c915766e9996f2277%2Fpg%E7%99%BB%E5%BD%95.png?alt=media)

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

![pgAdmin4 切换语言](https://338876981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJR3FQGH1PkdRtOljuxb%2Fuploads%2Fgit-blob-8c9adeba881c81f71ea05b4663e902f66d208dc6%2F%E7%99%BB%E5%BD%952.png?alt=media)

![pgAdmin4 中文界面](https://338876981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJR3FQGH1PkdRtOljuxb%2Fuploads%2Fgit-blob-ed7fc8e463d8e3839d1f9e8c79feb4c92e07c95c%2F%E7%99%BB%E5%BD%953.png?alt=media)

## 保持 pgAdmin4 后台运行

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

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

## 升级 pgAdmin4

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

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

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

```sh
root@ykla:~# virtualenv pgadmin4
```

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

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

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

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

完成升级后启动 pgAdmin4 应用：

```sh
(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](https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261652)。