跳转到主要内容

pgAdmin:PostgreSQL 图形管理工具

使用 Pigsty 的 Docker Compose 应用模板部署 pgAdmin4,并安全加载 PostgreSQL 服务器清单。

pgAdmin 是 PostgreSQL 的开源图形管理与开发工具。Pigsty 提供 app/pgadmin Docker Compose 模板,并可从当前清单生成服务器列表与密码文件。

先修改默认凭据

模板默认登录名为 admin@pigsty.cc、密码为 pigsty,只适合本地演示。部署到共享网络或公网前,必须修改登录凭据、限制端口访问并配置 HTTPS。


快速开始

conf/meta.yml 默认在 app 组声明 pgAdmin。使用明确限定的目标执行部署:

./docker.yml -l app
./app.yml -l app -e app=pgadmin

默认端口为 8885,可从 http://<app_ip>:8885 访问。只有在 infra_portal、Nginx 与 DNS 已配置时,http://adm.pigsty 才是有效入口。

容器首次启动可能需要几十秒,可在应用节点检查:

cd /opt/pgadmin
make info
make log

应用配置

推荐在 pigsty.yml 的 app 组通过 apps.pgadmin.conf 覆盖 .env:

all:
  children:
    app:
      hosts: { 10.10.10.10: {} }
      vars:
        docker_enabled: true
        app: pgadmin
        apps:
          pgadmin:
            conf:
              PGADMIN_DEFAULT_EMAIL: dba@example.com
              PGADMIN_DEFAULT_PASSWORD: <strong-random-password>
              PGADMIN_LISTEN_ADDRESS: 0.0.0.0
              PGADMIN_PORT: 8885
              PGADMIN_SERVER_JSON_FILE: /pgadmin4/servers.json
              PGADMIN_REPLACE_SERVERS_ON_STARTUP: 'False'

app.yml 会把模板复制到 /opt/pgadmin 并将覆盖项写入 /opt/pgadmin/.env。该文件包含登录密码,权限应保持为 0600。

PGADMIN_DEFAULT_EMAIL 与 PGADMIN_DEFAULT_PASSWORD 只用于初始化,不会重置已有账号的密码。模板将服务器列表和密码文件分别挂载到 /pgadmin4/servers.json 与 /pgadmin4/pgpass;修改环境变量不会自动改变这些挂载路径。

当前模板使用未固定标签的 dpage/pgadmin4 镜像。生产环境应在 docker-compose.yml 中固定经过验证的版本或镜像摘要,并把镜像升级当作独立变更验证。


加载服务器列表

env_pgadmin 根据清单生成:

  • /infra/pgadmin/servers.json:PostgreSQL 实例列表
  • /infra/pgadmin/pgpass:数据库管理员密码文件

默认 conf/meta.yml 中 infra 与 app 组指向同一台主机,因此 pgAdmin 可以直接挂载这两个文件。如果 pgAdmin 与 Infra 分离部署,应用节点不会自动拥有 /infra/pgadmin/;必须另行安全分发等价文件或自定义挂载。

轮换数据库凭据后,先重新生成 Infra 文件:

./infra.yml -l infra -t env_pgadmin

生成的服务器定义使用 PassFile: "/.pgpass",在 pgAdmin Server 模式下 相对于用户存储目录解析。make pass 会根据容器当前配置的 PGADMIN_DEFAULT_EMAIL(将 @ 转为 _)定位 /var/lib/pgadmin/storage/<email_dir>/.pgpass,从宿主机最新源文件写入密码并以 0600 权限保存(宿主机需安装 jq)。

容器内置的密码文件初始化仅在首次建库时执行;Pigsty 的 make up、make start 与 make restart 会自动调用 make pass 刷新 .pgpass,且不会改动已有服务器列表。轮换数据库凭据后,可先重新生成 Infra 文件再仅刷新密码:

./infra.yml -l infra -t env_pgadmin
./app.yml -l app -e app=pgadmin -t app_launch -e app_args=pass

首次初始化会自动导入服务器列表。模板默认设置 PGADMIN_REPLACE_SERVERS_ON_STARTUP=False,以保留用户在 Web 界面手工添加的服务器定义。make list、make conf 与 make reload 同样读取当前 PGADMIN_DEFAULT_EMAIL,且仅当 PGADMIN_REPLACE_SERVERS_ON_STARTUP 精确设为首字母大写的字符串 'True'(上游镜像不识别小写 true;在 apps.pgadmin.conf 中请写引号字符串 'True' 而非 YAML 布尔值 true)时才会附加 --replace 替换该用户的全部服务器定义。

pgpass 只写入生成该文件时的 pg_admin_username / pg_admin_password,并使用主机、端口、数据库通配符;各集群使用不同管理员凭据时,需要补齐对应条目。请限制文件、备份和应用主机的访问范围;若不希望 pgAdmin 持有 DBA 凭据,应自行生成最小权限的连接定义。


域名与 HTTPS

在 infra_portal 中添加入口:

all:
  vars:
    infra_portal:
      pgadmin:
        domain: adm.pigsty
        endpoint: "10.10.10.10:8885"

在明确限定的 Infra 组上更新 Nginx:

./infra.yml -l infra -t nginx

公网真实域名还需 DNS 指向服务器,并在 portal 条目中设置 certbot:

infra_portal:
  pgadmin:
    domain: adm.example.com
    endpoint: "10.10.10.10:8885"
    certbot: adm.example.com
./infra.yml -l infra -t nginx_certbot,nginx_reload -e certbot_sign=true

证书前置条件与续期方式参见 CA 与证书。不要把直接暴露的 8885 端口视为 HTTPS 入口。


状态与管理

在 /opt/pgadmin 中可使用:

make up       # 启动容器并自动刷新 .pgpass
make view     # 显示访问地址
make log      # 跟随容器日志
make info     # docker inspect
make list     # 为当前用户导入服务器列表(默认不覆盖,精确设为 True 时才加 --replace)
make pass     # 仅刷新当前用户的 .pgpass 密码文件
make conf     # 依次执行 make list 与 make pass
make stop     # 停止容器
make restart  # 重启容器并刷新 .pgpass

Compose 默认声明命名卷 pgadmin-data 挂载到 /var/lib/pgadmin,在容器重建后保留 pgAdmin 配置数据库、用户存储目录与界面设置。清理或升级前建议先备份该卷中的数据。

pgAdmin

安全检查

  • 修改默认 pgAdmin 登录名与密码,不在脚本、截图或工单中传播真实凭据。
  • 默认端口映射会监听主机网络;用防火墙限制来源,公网入口使用 Nginx 与有效 HTTPS 证书。
  • 保护 /infra/pgadmin/pgpass 与 /opt/pgadmin/.env,优先使用最小权限数据库角色。
  • 固定并验证容器镜像版本,备份任何新增的 pgAdmin 持久状态。
  • pgAdmin 能执行高权限 SQL;删除数据库、表或数据前仍需独立确认目标与近期备份。

这个页面对您有帮助吗?