在 Ubuntu 上安装 pgAdmin 4 的简明教程
一 安装前准备
- 本教程适用于 Ubuntu 22.04/24.04 LTS，以 pgAdmin 4 为例（pgAdmin 3 已停止维护）。
- 更新索引并安装必要工具：
- sudo apt update && sudo apt install -y curl
- 确认系统代号（用于添加正确的 APT 源），常见为 jammy、noble：
二 通过官方 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 部署。
