pgAdmin在Ubuntu上的安装教程

在 Ubuntu 上安装 pgAdmin 4 的简明教程

一 安装前准备

• 本教程适用于 Ubuntu 22.04/24.04 LTS，以 pgAdmin 4 为例（pgAdmin 3 已停止维护）。
• 更新索引并安装必要工具：
  • sudo apt update && sudo apt install -y curl
• 确认系统代号（用于添加正确的 APT 源），常见为 jammy、noble：
  • lsb_release -cs

二 通过官方 APT 仓库安装（推荐）

• 导入 pgAdmin 仓库公钥并添加 APT 源（使用系统代号自动匹配仓库）：
  • curl -fsS https://www.pgadmin.org/static/packages_pgadmin_org.pub | sudo gpg --dearmor -o /usr/share/keyrings/packages-pgadmin-org.gpg
  • echo “deb [signed-by=/usr/share/keyrings/packages-pgadmin-org.gpg] https://ftp.postgresql.org/pub/pgadmin/pgadmin4/apt/$(lsb_release -cs) pgadmin4 main” | sudo tee /etc/apt/sources.list.d/pgadmin4.list
  • sudo apt update
• 安装模式选择：
  • 桌面 + Web 集成模式（会安装桌面与 Web 组件，适合本机或含桌面环境的服务器）：sudo apt install -y pgadmin4
  • 仅 Web 模式（更轻量，适合服务器部署）：sudo apt install -y pgadmin4-web
• 运行 Web 配置向导（两种包安装后脚本路径一致）：
  • sudo /usr/pgadmin4/bin/setup-web.sh
  • 按提示设置 邮箱 与 登录密码，并选择是否自动配置 Apache 反向代理（常见选择为 y，完成后会自动重启 Apache）
• 访问地址：
  • 本机：http://127.0.0.1/pgadmin4
  • 服务器：http://服务器IP/pgadmin4
• 说明：
  • 若使用 pgadmin4-web，系统通过 Apache 提供服务；若使用 pgadmin4，仍会安装 Web 组件，但桌面环境也可用。两者均可使用同一配置脚本完成初始化。

三 连接 PostgreSQL 数据库

• 登录 pgAdmin 后，右键 Servers → Register → Server。
• General 页：填写 Name（自定义名称）。
• Connection 页：填写
  • Host name/address：PostgreSQL 主机（如 localhost 或服务器 内网/公网 IP）
  • Port：5432（若自定义请填写实际端口）
  • Maintenance database：postgres
  • Username / Password：具有登录权限的数据库用户凭据
• 保存后即可在左侧树形视图中浏览与管理对象（表、视图、函数、角色等）。

四 常见问题与排查

• 访问被拒绝或 404：
  • 确认已运行 sudo /usr/pgadmin4/bin/setup-web.sh 并完成 Apache 配置
  • 检查防火墙是否放行 80/443 端口（云服务器需在安全组放行）
  • 访问地址应为 /pgadmin4（注意路径前缀）
• APT 找不到包或签名错误：
  • 确认已正确导入公钥到 /usr/share/keyrings/packages-pgadmin-org.gpg
  • 确认 /etc/apt/sources.list.d/pgadmin4.list 中的发行代号与系统一致（如 jammy、noble）
  • 再次执行 sudo apt update
• 无法连接 PostgreSQL：
  • 确认 PostgreSQL 允许来自 pgAdmin 主机的连接（pg_hba.conf 与 postgresql.conf 的 listen_addresses 配置）
  • 如使用云数据库，确保安全组/防火墙放行 5432 端口，并使用正确的用户名与密码

五 可选方案 使用 pip 与虚拟环境安装

• 适合需要隔离依赖或无法使用 APT 的场景（示例为服务器模式）：
  • sudo apt update && sudo apt install -y python3-venv python3-pip libpq-dev
  • python3 -m venv ~/pgadmin4-venv && source ~/pgadmin4-venv/bin/activate
  • pip install --upgrade pip wheel
  • pip install pgadmin4
  • 创建数据与日志目录并赋权：
    • sudo mkdir -p /var/lib/pgadmin4/sessions /var/lib/pgadmin4/storage /var/log/pgadmin4
    • sudo chown -R $USER:$USER /var/lib/pgadmin4 /var/log/pgadmin4
  • 首次初始化（按提示设置邮箱与密码）：
    • python ~/pgadmin4-venv/lib/python3.*/site-packages/pgadmin4/setup.py
  • 启动服务（示例，使用 Gunicorn + Nginx 反向代理更稳妥）：
    • python ~/pgadmin4-venv/lib/python3.*/site-packages/pgadmin4/pgAdmin4.py
  • 说明：此方式更灵活，但需要自行维护进程与反向代理配置；生产环境建议使用 pgadmin4-web + Apache 或配合 Nginx/Gunicorn 部署。