# 21.3 pgAdmin4

> **警告**
>
> 请注意以下上游已知问题：pgAdmin4 在 FreeBSD 上运行可能受到 [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（Flask 框架）和 React 编写，支持多种操作系统环境（如 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 虚拟环境。

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

以下命令用于安装 `virtualenv`：

使用 pkg 安装：

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

使用 Ports 安装：

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

通过运行以下命令创建 Python 虚拟环境 pgadmin4（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
```

## 文件结构

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/
```

以上错误由系统时间不正确所致，可用命令 `ntpd -q -g pool.ntp.org` 将系统时间同步至 NTP 服务器池 pool.ntp.org：

```sh
(pgadmin4) root@ykla:~# ntpd -q -g pool.ntp.org
```

## 配置并运行 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](/files/mYkLQrtcvDeG4SUYuxms)

箭头所指处可以切换语言。

![pgAdmin4 切换语言](/files/N0ilpoZdrvgYSShiLKTZ)

![pgAdmin4 中文界面](/files/DgSQXoF7rxI9RvNOqcBV)

## 保持 pgAdmin4 后台运行

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

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

## 升级 pgAdmin4

如需升级 pgAdmin4，可按以下步骤操作。

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

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

```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 的安装配置方法，为本节提供了官方指南参考。
* pgAdmin Development Team. pgAdmin 4 GitHub Repository\[EB/OL]. \[2026-04-17]. <https://github.com/pgadmin-org/pgadmin4>. pgAdmin 4 官方仓库，记载其技术栈为 Python（Flask）后端与 React 前端。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://book.bsdcn.org/di-21-zhang-shu-ju-ku-guan-li/di-21.3-jie-pgadmin4-guan-li-gong-ju.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.