pgAdmin:PostgreSQL 图形管理工具
pgAdmin 是 PostgreSQL 的开源图形管理与开发工具。Pigsty 提供 app/pgadmin Docker Compose 模板,并可从当前清单生成服务器列表与密码文件。
模板默认登录名为 admin@pigsty.cc、密码为 pigsty,只适合本地演示。部署到共享网络或公网前,必须修改登录凭据、限制端口访问并配置 HTTPS。
快速开始
conf/meta.yml 默认在 app 组声明 pgAdmin。使用明确限定的目标执行部署:
默认端口为 8885,可从 http://<app_ip>:8885 访问。只有在 infra_portal、Nginx 与 DNS 已配置时,http://adm.pigsty 才是有效入口。
容器首次启动可能需要几十秒,可在应用节点检查:
应用配置
推荐在 pigsty.yml 的 app 组通过 apps.pgadmin.conf 覆盖 .env:
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 文件:
生成的服务器定义使用 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 文件再仅刷新密码:
首次初始化会自动导入服务器列表。模板默认设置 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 中添加入口:
在明确限定的 Infra 组上更新 Nginx:
公网真实域名还需 DNS 指向服务器,并在 portal 条目中设置 certbot:
证书前置条件与续期方式参见 CA 与证书。不要把直接暴露的 8885 端口视为 HTTPS 入口。
状态与管理
在 /opt/pgadmin 中可使用:
Compose 默认声明命名卷 pgadmin-data 挂载到 /var/lib/pgadmin,在容器重建后保留 pgAdmin 配置数据库、用户存储目录与界面设置。清理或升级前建议先备份该卷中的数据。

安全检查
- 修改默认 pgAdmin 登录名与密码,不在脚本、截图或工单中传播真实凭据。
- 默认端口映射会监听主机网络;用防火墙限制来源,公网入口使用 Nginx 与有效 HTTPS 证书。
- 保护
/infra/pgadmin/pgpass与/opt/pgadmin/.env,优先使用最小权限数据库角色。 - 固定并验证容器镜像版本,备份任何新增的 pgAdmin 持久状态。
- pgAdmin 能执行高权限 SQL;删除数据库、表或数据前仍需独立确认目标与近期备份。
这个页面对您有帮助吗?
感谢反馈,我们会据此改进这篇文档。
哪里没有解决?(可选)