sosedoff/pgweb

Pgweb Docker镜像文档

1. 镜像概述和主要用途

1.1 概述

Pgweb 是一款跨平台、基于 Web 的 PostgreSQL 数据库浏览器，采用 Go 语言开发。它提供直观的 Web 界面，支持用户通过浏览器便捷地管理、查询和浏览 PostgreSQL 数据库。

1.2 主要用途

• 数据库日常管理：包括表结构查看、数据增删改查等操作。
• SQL 查询执行：支持编写、运行 SQL 语句并查看执行结果。
• 数据可视化：以表格形式展示查询结果，方便数据浏览和分析。
• 跨环境数据库访问：通过容器化部署，可在本地或远程环境中快速接入 PostgreSQL 服务。

2. 核心功能和特性

2.1 核心功能

• Web 界面管理：无需安装客户端，通过浏览器即可访问和操作数据库。
• PostgreSQL 兼容性：全面支持 PostgreSQL 数据库特性，包括表、视图、索引、存储过程等对象的管理。
• SQL 查询工具：内置 SQL 编辑器，支持语法高亮、查询执行及结果展示。
• 数据浏览：以分页表格形式展示表数据，支持排序和筛选。

2.2 主要特性

• 跨平台：支持 Windows、macOS、Linux 等主流操作系统（通过 Docker 容器化实现环境一致性）。
• 轻量级：基于 Go 语言开发，体积小、资源占用低，启动速度快。
• 容器化部署：提供 Docker 镜像，支持快速部署和环境隔离。
• 灵活配置：通过环境变量或命令行参数自定义数据库连接信息。

3. 使用场景和适用范围

3.1 适用场景

• 本地开发环境：开发人员在本地调试时，通过 Pgweb 快速查看和修改开发数据库数据。
• 远程数据库管理：对云服务器或私有部署的 PostgreSQL 数据库进行远程访问和监控。
• 团队协作：作为轻量级数据库管理工具，供团队成员共享数据库访问入口（需注意权限控制）。
• 临时数据查询：无需安装客户端，通过浏览器临时查询数据库数据。

3.2 目标用户

• 开发人员：用于开发过程中的数据库调试和数据验证。
• 数据库管理员（DBA）：执行日常数据库巡检、简单查询和数据导出。
• 测试人员：验证测试环境数据库数据是否符合预期。

4. 使用方法和配置说明

4.1 基础使用（Docker 命令行）

4.1.1 拉取镜像

从 Docker Hub 拉取 Pgweb 最新镜像：

bash
docker pull sosedoff/pgweb

4.1.2 启动容器

运行容器并映射端口（默认使用 8081 端口提供 Web 服务）：

bash
docker run -p 8081:8081 sosedoff/pgweb

• 参数说明：-p 8081:8081 表示将容器内的 8081 端口映射到主机的 8081 端口，确保外部可通过主机端口访问 Pgweb 服务。

4.1.3 访问 UI

容器启动后，通过浏览器访问 http://localhost:8081 即可打开 Pgweb 界面。首次访问需手动配置数据库连接信息（如未通过环境变量预设）。

4.2 Docker Compose 配置

通过 Docker Compose 可实现 Pgweb 与 PostgreSQL 数据库的联动部署，简化多容器协调。

4.2.1 创建配置文件

新建 docker-compose.yml 文件，内容如下：

yaml
version: '3'  # 需根据 Docker Compose 版本调整，如 '2' 或 '3.8'

services:
  pgweb:
    container_name: pgweb  # 容器名称
    restart: always       # 容器退出后自动重启
    image: sosedoff/pgweb # 使用的 Docker 镜像
    ports:
      - "8081:8081"       # 端口映射：主机端口:容器端口
    links:
      - postgres:postgres # 链接到名为 postgres 的数据库容器（需确保数据库容器名称为 postgres）
    environment:
      # 数据库连接 URL，格式：postgres://用户:密码@主机:端口/数据库名?sslmode=disable
      - DATABASE_URL=postgres://postgres:postgres@postgres:5432/postgres?sslmode=disable
    depends_on:
      - postgres  # 依赖 postgres 服务，确保先启动数据库

  postgres:  # 示例 PostgreSQL 服务（实际使用时可替换为已有数据库）
    image: postgres:14
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=postgres
    ports:
      - "5432:5432"

4.2.2 启动服务

在配置文件所在目录执行以下命令启动服务：

bash
docker-compose up -d  # -d 表示后台运行

服务启动后，通过 http://localhost:8081 访问 Pgweb，无需手动配置连接（已通过 DATABASE_URL 自动注入）。

4.3 配置参数说明

4.3.1 核心环境变量

DATABASE_URL 格式说明：

postgres://<用户名>:<密码>@<主机地址>:<端口>/<数据库名>?<额外参数>

• <用户名>：数据库访问用户名（如 postgres）。
• <密码>：用户名对应的密码。
• <主机地址>：PostgreSQL 服务地址（Docker 环境中可使用容器名，如 postgres）。
• <端口>：PostgreSQL 服务端口（默认 5432）。
• <数据库名>：要连接的数据库名称。
• <额外参数>：可选，如 sslmode=disable（禁用 SSL，适合本地开发环境）。

4.3.2 端口映射

Pgweb 默认使用 8081 端口提供 Web 服务，容器部署时需通过 -p <主机端口>:8081 映射端口，确保外部可访问。若主机 8081 端口被占用，可替换为其他端口（如 -p 8082:8081）。

5. 注意事项

• 权限控制：Pgweb 直接关联数据库用户权限，建议使用只读或有限权限的数据库用户连接，避免误操作。
• 远程访问安全：若需开放公网访问，需启用 SSL 加密（通过 sslmode=require 配置）并限制访问 IP。
• 容器依赖：使用 Docker Compose 时，depends_on 仅保证启动顺序，不保证数据库完全就绪，生产环境建议添加健康检查（如 healthcheck 配置）。