pgweb 安装教程：在网页里查询 PostgreSQL

排查文章统计、订单状态或定时任务记录时，常常只需要查几张表。每次进入数据库终端写命令有些繁琐，又不值得为了查看数据把整个数据库管理面板暴露到公网。

pgweb 提供 PostgreSQL 的网页查询界面。这里接入已经存在的 PostgreSQL 容器，用只读角色限制操作范围。适合自己的运维查询；读权限仍可能包含用户资料，因此“只读”不等于“可以公开”。

连接数据库前，先建只读账号

选服务器之前，先确认它能连接要查询的 PostgreSQL。如果还没有可用 VPS，可以从雨云云服务器查看 Linux 云服务器，重点看数据库所在机房与访问限制。优惠码 KuZhuJi。如有消费返利，以购买页所选规格显示的金额为准。

以下命令在 Linux VPS 上执行，需要有 Docker 操作权限。先运行 docker version 和 docker compose version，确认引擎与 Compose v2 都能工作。没有安装 Docker 时，按 Docker 官方安装说明选择对应发行版；不要把其他发行版的仓库配置直接复制过来。

示例工作目录为 /opt/pgweb，所有相对路径都以这个目录为基准。VPS_IP、SSH 用户和示例域名需要换成自己的值。端口 8081 若已被占用，只改映射左侧的宿主机端口，并同步修改访问地址。

sudo install -d -m 0750 -o "$(id -u)" -g "$(id -g)" /opt/pgweb
cd /opt/pgweb
umask 077

先确认 PostgreSQL 容器所在的 Docker 网络和服务名。用 docker network ls 查看网络，再由数据库管理员建立专用角色。下面以 appdb、public 和对象创建者 app_owner 为例，名称要按实际数据库修改。密码单独生成，不使用示例字符串。

CREATE ROLE pgweb_reader LOGIN PASSWORD 'REPLACE_WITH_RANDOM_PASSWORD';
GRANT CONNECT ON DATABASE appdb TO pgweb_reader;
GRANT USAGE ON SCHEMA public TO pgweb_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO pgweb_reader;
ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA public
  GRANT SELECT ON TABLES TO pgweb_reader;

后四条在目标数据库中执行。默认权限只影响指定角色以后创建的表；其他 schema 和创建者要分别处理。不要为方便把角色加入已有写入组。

保存 .env，其中 postgres 是网络内数据库的服务名或别名，不是 VPS 上的回环地址：

DB_NETWORK=your_existing_database_network
PGWEB_DATABASE_URL=postgres://pgweb_reader:REPLACE_WITH_RANDOM_PASSWORD@postgres:5432/appdb?sslmode=disable

sslmode=disable 仅用于本文同机、隔离的 Docker 网络。跨服务器连接应配置服务端 TLS 和证书校验。URL 密码若包含特殊字符要编码，也可以用 openssl rand -hex 24 生成不需要额外编码的密码。执行 chmod 600 .env，不要将它提交到 Git。

将下面内容保存为 compose.yaml：

services:
  pgweb:
    image: sosedoff/pgweb:latest
    restart: unless-stopped
    environment:
      PGWEB_DATABASE_URL: ${PGWEB_DATABASE_URL:?set database url}
    ports:
      - "127.0.0.1:8081:8081"
    networks:
      - database
networks:
  database:
    external: true
    name: ${DB_NETWORK:?set docker network}

在工作目录启动并检查日志：

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80

启动后按下面的步骤试用。遇到目录不可写的报错，先核对 UID 和挂载路径，不要直接改成 chmod 777。

用 SSH 隧道打开界面

示例仅把应用端口发布到 VPS 的 127.0.0.1。在自己的电脑上运行以下命令，保留终端窗口，再打开 http://127.0.0.1:8081：

ssh -N -L 8081:127.0.0.1:8081 your_ssh_user@VPS_IP

浏览器里的回环地址是自己的电脑，SSH 把请求转到 VPS。若本地同号端口被占用，可换隧道左侧端口；涉及应用外部 URL 的项目也要一起调整。管理界面无需因此开放公网端口。

先查十行，再验证写入被拒绝

登录界面后先核对当前数据库和角色：

SELECT current_database(), current_user;
SELECT table_schema, table_name
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY table_name;

挑一张不含敏感信息的业务表，用明确字段和 LIMIT 10 查询。生产库上不要刚打开界面就执行大范围统计或无条件导出，读查询也可能占用资源。

让管理员在测试库建一张权限验证表，再用这个角色尝试写入，预期应得到权限不足。若写入成功，检查继承角色与表授权。网页界面隐藏按钮并不能代替数据库权限。

需要交接结果时导出这一次查询的 CSV，并核对行数、时间范围和是否包含个人信息。CSV 只覆盖选中的字段，不包含索引、约束、其他表或数据库角色。

备份数据库，升级查询工具

这个配置没有给 pgweb 存储业务数据；数据仍在 PostgreSQL。备份现有数据库时继续使用它自己的 pg_dump 和恢复流程，不要把网页导出当成整库备份。

pgweb 的部署配置和 .env 需要加密保留。升级前记下旧镜像摘要，在测试库上检查登录、查询和导出，再更新生产界面。若无法连接，先检查外部网络名、服务别名和数据库角色，而不是开放 5432 端口。

安装参数和数据路径可对照pgweb 当前 Compose 示例。