CentOS 上使用 pgAdmin 4 的完整教程

一 环境准备与版本选择

• 适用系统：CentOS 7/8（桌面或服务器版均可）。
• 安装方式：优先使用系统包管理器安装 pgAdmin 4（RPM 方式），也可选择 Docker 快速部署。
• 浏览器访问：建议使用 Chrome/Edge/Firefox 最新版。
• 安全建议：仅在受信任网络中开放访问，并启用 HTTPS 与强口令。

二 安装与部署

• CentOS 8 使用 RPM 仓库安装（推荐）

  1. 启用 EPEL 与 PowerTools（或 CRB）： sudo dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm sudo dnf config-manager --set-enabled powertools # 或 dnf config-manager --set-enabled crb
  2. 添加 PostgreSQL 官方 RPM 仓库并安装 pgAdmin 4： sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm sudo dnf -qy module disable postgresql sudo dnf install pgadmin4
  3. 启动 Web 服务（pgAdmin 4 RPM 包自带 httpd/Wsgi 集成，安装完成后即可通过浏览器访问）： sudo systemctl enable --now httpd
  4. 防火墙放行（若启用 firewalld）： sudo firewall-cmd --permanent --add-service=http sudo firewall-cmd --reload
  5. 访问地址：http://服务器IP/（RPM 包默认部署在根路径）。

• CentOS 7 使用 RPM 仓库安装（Apache + mod_wsgi）

  1. 安装 EPEL 与 PostgreSQL 仓库并安装 pgAdmin 4： sudo yum -y install epel-release sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm sudo yum -y update sudo yum -y install pgadmin4
  2. 启用并配置 Apache（示例使用 Python 3 路径，具体以系统为准）： sudo cp /etc/httpd/conf.d/pgadmin4.conf.sample /etc/httpd/conf.d/pgadmin4.conf

     在 /etc/httpd/conf.d/pgadmin4.conf 的 中确保包含：

     LoadModule wsgi_module modules/pgadmin4-python3-mod_wsgi.so

     WSGIScriptAlias /pgadmin4 /usr/lib/python3.6/site-packages/pgadmin4-web/pgAdmin4.wsgi

     <Directory …> Require all granted …

     sudo httpd -t && sudo systemctl restart httpd sudo systemctl enable --now httpd
  3. 创建数据与日志目录并赋权： sudo mkdir -p /var/lib/pgadmin4 /var/log/pgadmin4 sudo chown -R apache:apache /var/lib/pgadmin4 /var/log/pgadmin4
  4. 初始化 pgAdmin 配置数据库（注意 Python 版本与路径一致）： sudo python3 /usr/lib/python3.6/site-packages/pgadmin4-web/setup.py

     按提示设置管理员邮箱与密码

  5. 防火墙放行： sudo firewall-cmd --permanent --add-service=http sudo firewall-cmd --reload
  6. 访问地址：http://服务器IP/pgadmin4。

• Docker 快速部署（适用于任何 CentOS 7/8）

  1. 安装 Docker 并启动： sudo yum -y install docker sudo systemctl enable --now docker
  2. 启动 pgAdmin 容器（将 5050 映射到容器 80）： docker run -p 5050:80
     -e “PGADMIN_DEFAULT_EMAIL=admin@example.com”
     -e “PGADMIN_DEFAULT_PASSWORD=StrongPass!”
     -d dpage/pgadmin4
  3. 访问地址：http://服务器IP:5050。

三 首次登录与连接 PostgreSQL

• 登录 pgAdmin：使用安装时设置的管理员邮箱与密码登录 Web 界面。
• 添加服务器连接：
  • 左侧点击 Servers +，选择 Create > Server。
  • General 页：填写 Name（自定义连接名）。
  • Connection 页：填写
    • Host name/address：PostgreSQL 主机（如 localhost 或服务器 IP）
    • Port：5432
    • Maintenance database：postgres
    • Username / Password：数据库账户凭据
  • 保存后即可浏览与操作数据库对象。
• 常用功能：
  • 使用内置 SQL 工具 编写、执行查询
  • 管理对象：表、视图、索引、函数、模式 等
  • 备份与还原：使用 pgAdmin 的导出/导入工具进行逻辑备份与恢复。

四 常见问题与排错

• 访问被拒绝或 404：
  • 确认 httpd 已启动（systemctl status httpd），防火墙放行 http/80。
  • 若使用 RPM 包，默认根路径访问；若使用 Apache 配置，确认 WSGIScriptAlias 路径为 /pgadmin4 并已 Require all granted。
• Internal Server Error：
  • 检查 /var/log/pgadmin4/pgadmin4.log 与 httpd error_log。
  • 确认数据与日志目录权限为 apache:apache，且 setup.py 已成功初始化。
• SELinux 拦截：
  • 临时排查可 setenforce 0；生产环境请按需配置 SELinux 布尔值或策略，而非长期关闭。
• Python 路径错误：
  • 编辑 config_distro.py 或 config_local.py 时，确保 LOG_FILE、SQLITE_PATH、SESSION_DB_PATH、STORAGE_DIR 路径存在且可写，且 WSGI 指向的 pgAdmin4.wsgi 路径与系统 Python 版本一致（如 /usr/lib/python3.6/site-packages/pgadmin4-web/）。