---

精通 PostgreSQL Docker：从入门到实战，构建稳定高效的数据库环境

在现代软件开发与部署中，容器化技术已经成为不可或缺的一部分。Docker 凭借其轻量、便携和隔离的特性，极大地简化了应用的构建、分发和运行。对于数据库这样关键的基础服务，将其容器化同样带来了巨大的便利性，尤其是在开发、测试和CI/CD环境中。

PostgreSQL，作为世界上最先进的开源关系型数据库之一，拥有强大的功能、出色的稳定性和广泛的社区支持。将 PostgreSQL 运行在 Docker 容器中，可以让你快速搭建一个独立的数据库实例，避免复杂的本地安装和依赖冲突，轻松实现数据库环境的复制与管理。

本文将带领你一步步深入了解如何在 Docker 中安装和运行 PostgreSQL，从基础的容器启动到关键的数据持久化，再到连接和一些高级配置，帮助你构建一个稳定高效的 PostgreSQL Docker 环境。

第一章：前置条件 – 准备 Docker 环境

在开始之前，你需要确保你的系统已经安装了 Docker。Docker 支持 Windows、macOS 和 Linux 等主流操作系统。

1. 安装 Docker：

   • Windows/macOS: 访问 Docker 官网（https://www.docker.com/products/docker-desktop）下载并安装 Docker Desktop。Docker Desktop 包含了 Docker Engine、Docker CLI、Docker Compose、Kubernetes（可选）以及一个图形化界面。
   • Linux: 访问 Docker 官方文档（https://docs.docker.com/engine/install/）查找适合你Linux发行版的安装指南。通常通过包管理器（如 apt 或 yum）进行安装。

2. 验证安装：
   安装完成后，打开终端或命令提示符，运行以下命令来验证 Docker 是否安装成功并正在运行：

   bash
docker --version
docker info

   如果这些命令能正确输出版本信息和 Docker 系统的详细信息，说明你的 Docker 环境已经准备就绪。

第二章：获取 PostgreSQL 镜像

Docker 运行容器是基于镜像的。PostgreSQL 官方在 Docker Hub 上提供了官方镜像，这是最推荐的方式来获取 PostgreSQL 镜像。

1. 搜索镜像：
   你可以在 Docker Hub 网站上搜索 postgres 镜像，或者在终端中使用以下命令：

   bash
docker search postgres

   你会看到一个名为 postgres 的官方镜像。

2. 拉取镜像：
   拉取镜像是将镜像下载到本地的过程。为了保证数据库的稳定性，强烈建议拉取特定版本的镜像，而不是使用默认的 latest 标签（它指向最新版本，可能会在你不知情的情况下引入不兼容的变更）。

   你可以访问 Docker Hub 上的 postgres 页面查看所有可用的标签（https://hub.docker.com/_/postgres）。选择一个你需要的版本，例如 14 或 15.4。

   “`bash

   拉取最新稳定版本（不推荐用于生产环境）

   docker pull postgres

   拉取特定版本（推荐）

   docker pull postgres:14

   或者更具体的版本，例如

   docker pull postgres:15.4
   “`

   docker pull 命令会从 Docker Hub 下载指定的镜像及其依赖层到你的本地镜像仓库。

3. 查看本地镜像：
   拉取完成后，你可以使用以下命令查看本地已经存在的 Docker 镜像：

   bash
docker images

   你应该能看到你刚刚拉取的 postgres 镜像及其标签、镜像ID、创建时间和大小。

第三章：运行 PostgreSQL 容器

现在，你已经有了 PostgreSQL 镜像，可以开始运行容器了。运行容器需要使用 docker run 命令，并配置一些必要的参数。

docker run 命令的基本语法是 docker run [OPTIONS] IMAGE [COMMAND] [ARG...]。对于 PostgreSQL 容器，一些关键的选项是必须的。

1. 设置 Superuser 密码 (必需):
   PostgreSQL 镜像启动时，必须设置 postgres（超级用户）的密码。这是通过环境变量 POSTGRES_PASSWORD 来实现的。如果你不设置这个环境变量，容器将无法成功启动。

   bash
-e POSTGRES_PASSWORD=your_strong_password

   请务必替换 your_strong_password 为一个强密码。在实际应用中，避免直接在命令行中暴露密码，可以使用 .env 文件配合 docker run --env-file 或 Docker Secrets。

2. 命名容器 (推荐):
   为容器指定一个有意义的名称，方便后续管理（启动、停止、删除、查看日志等）。使用 --name 选项。

   bash
--name my-postgres

   如果你不指定名称，Docker 会为你生成一个随机名称。

3. 后台运行 (推荐):
   默认情况下，docker run 会在前台运行，并输出容器的日志。使用 -d 选项可以让容器在后台守护态运行。

   bash
-d

4. 端口映射 (可选但常用):
   默认情况下，容器的网络是隔离的。如果你想从宿主机或其他网络中的客户端访问容器内部的 PostgreSQL 服务（默认端口 5432），你需要进行端口映射。使用 -p host_port:container_port 选项。

   bash
-p 5432:5432

   这将宿主机的 5432 端口映射到容器的 5432 端口。你可以将宿主机端口改为其他未被占用的端口，例如 -p 5433:5432。

5. 数据持久化 (强烈推荐 – 核心!):
   这是运行数据库容器中最重要的一环。 Docker 容器是设计为相对短暂和无状态的。容器停止、重启或被删除后，容器内部的文件系统变更（包括你的数据库数据）都会丢失。为了保证数据库数据的安全和持久性，必须将数据存储在容器外部，通常使用 Docker Volume 或 Bind Mount。

   • Docker Volume (推荐): Docker 管理的卷是推荐的方式。它们独立于容器的生命周期，由 Docker 统一管理。创建和管理卷比 Bind Mount 更灵活，且性能更好。
     “`bash
     # 创建一个卷
     docker volume create pg_data_volume

     运行容器时挂载卷

     -v pg_data_volume:/var/lib/postgresql/data
     ``/var/lib/postgresql/data是 PostgreSQL 官方镜像默认存储数据文件的目录。将这个目录映射到一个卷上，数据就会存储在宿主机由 Docker 管理的/var/lib/docker/volumes/pg_data_volume/_data` (Linux) 或 Docker Desktop 指定的位置 (Windows/macOS)。

   • Bind Mount (可选): 将宿主机文件系统上的一个目录直接挂载到容器内部的某个目录。
     bash
-v /path/on/your/host/pg_data:/var/lib/postgresql/data
     这会将宿主机 /path/on/your/host/pg_data 目录映射到容器的 /var/lib/postgresql/data 目录。你需要确保宿主机上的这个目录存在，并且 Docker 进程有权限读写。Bind Mount 在开发和测试中可能方便，但在生产环境中使用 Docker Volume 更常见。

   重要提示： 如果你第一次运行容器并挂载了一个空卷或一个不存在的 Bind Mount 目录到 /var/lib/postgresql/data，PostgreSQL 镜像的入口点脚本会自动执行 initdb 操作，创建新的数据库集群。如果挂载的目录已经包含了之前运行的 PostgreSQL 实例的数据，入口点脚本会跳过 initdb，直接启动数据库。

6. 组合运行命令：
   将以上选项组合起来，一个典型的运行 PostgreSQL 容器的命令如下：

   bash
docker run \
--name my-postgres \
-e POSTGRES_PASSWORD=mysecretpassword \
-p 5432:5432 \
-v pg_data_volume:/var/lib/postgresql/data \
-d \
postgres:15.4
   * \: 在终端中换行，使命令更易读。
   * --name my-postgres: 容器命名为 my-postgres。
   * -e POSTGRES_PASSWORD=mysecretpassword: 设置 postgres 用户的密码为 mysecretpassword。
   * -p 5432:5432: 将宿主机的 5432 端口映射到容器的 5432 端口。
   * -v pg_data_volume:/var/lib/postgresql/data: 将名为 pg_data_volume 的 Docker 卷挂载到容器的数据目录。如果卷不存在，Docker 会自动创建。
   * -d: 后台运行。
   * postgres:15.4: 使用 postgres:15.4 镜像。

   执行此命令后，Docker 会查找本地是否有 postgres:15.4 镜像，如果没有则从 Docker Hub 拉取，然后创建一个新的容器并以后台模式启动。

7. 验证容器状态：
   使用以下命令查看正在运行的容器：

   bash
docker ps
   你应该能看到 my-postgres 容器，状态是 Up ... (运行中)。

   如果容器启动失败，可以使用 docker logs my-postgres 命令查看容器的启动日志，找出原因（通常是密码没设置、端口冲突或卷权限问题）。

第四章：连接到 PostgreSQL 容器

容器运行起来后，你需要连接到数据库进行操作。有几种方式可以连接：

1. 从宿主机使用本地客户端连接：
   如果你的宿主机安装了 PostgreSQL 客户端工具（如 psql），并且你在运行容器时进行了端口映射（例如 -p 5432:5432），你可以直接使用宿主机的 IP 地址（通常是 localhost 或 127.0.0.1）和映射的端口连接。

   bash
psql -h localhost -p 5432 -U postgres -W
   * -h localhost: 指定数据库服务器地址。
   * -p 5432: 指定端口号（宿主机映射的端口）。
   * -U postgres: 指定连接用户（postgres 是默认的超级用户）。
   * -W: 提示输入密码。

   输入你在 docker run 命令中设置的密码，如果连接成功，你将进入 psql 命令行界面。

2. 从容器内部使用 docker exec 连接：
   你可以进入正在运行的容器内部，然后在容器的环境中运行 psql 客户端。

   bash
docker exec -it my-postgres psql -U postgres
   * docker exec: 在运行中的容器中执行命令。
   * -it: 分配一个伪终端（t）并保持标准输入开放（i），这样你就可以与容器内的进程进行交互（输入命令）。
   * my-postgres: 容器的名称。
   * psql -U postgres: 在容器内执行的命令，以 postgres 用户身份运行 psql。

   执行此命令后，如果环境变量 POSTGRES_PASSWORD 设置正确，你应该可以直接进入 psql 命令行（官方镜像的 entrypoint 会处理认证）。如果需要密码，可能需要修改命令或容器启动方式。在某些版本的镜像中，docker exec psql 可能不需要密码，因为它认为是从容器内部发起的本地连接。

   在 psql 命令行中，你可以执行 SQL 命令，例如：

   sql
\l -- 列出所有数据库
\c mydatabase -- 连接到另一个数据库
CREATE DATABASE myappdb; -- 创建一个新数据库
\q -- 退出 psql

3. 从其他 Docker 容器连接：
   如果你的应用（例如一个 Web 服务）也在 Docker 容器中运行，并且需要连接到 PostgreSQL 容器，推荐使用 Docker 网络。将你的应用容器和 PostgreSQL 容器连接到同一个用户定义的网络中。

   • 创建网络：
     bash
docker network create my-app-network
   • 运行 PostgreSQL 容器并加入网络：
     bash
docker run \
--name my-postgres \
-e POSTGRES_PASSWORD=mysecretpassword \
-v pg_data_volume:/var/lib/postgresql/data \
--network my-app-network \
-d \
postgres:15.4
     注意：这里可以省略 -p 5432:5432，因为连接将通过 Docker 网络进行，而不是宿主机端口。
   • 运行你的应用容器并加入同一网络：
     bash
docker run \
--name my-app \
--network my-app-network \
# ... 其他应用配置 ...
my-app-image
     在 my-app 容器内部，可以通过容器名称作为主机名来访问 PostgreSQL 容器：连接字符串中的主机名就是 my-postgres，端口是 5432。例如：host=my-postgres port=5432 user=postgres password=mysecretpassword dbname=mydatabase。

第五章：高级配置与初始化

PostgreSQL 官方 Docker 镜像提供了灵活的方式来在容器首次启动时进行数据库初始化和配置。

1. 设置默认用户和数据库 (可选):
   除了 POSTGRES_PASSWORD，你还可以在首次运行时设置默认的用户和数据库名称：

   • POSTGRES_USER: 设置除了 postgres 之外的初始用户，默认为 postgres。
   • POSTGRES_DB: 设置除了 postgres 之外的初始数据库，默认为 POSTGRES_USER 同名，如果未设置 POSTGRES_USER 则默认为 postgres。

   示例：创建一个名为 myappuser 的用户和一个名为 myappdb 的数据库：
   bash
docker run \
--name my-postgres \
-e POSTGRES_PASSWORD=mysecretpassword \
-e POSTGRES_USER=myappuser \
-e POSTGRES_DB=myappdb \
-p 5432:5432 \
-v pg_data_volume:/var/lib/postgresql/data \
-d \
postgres:15.4
   首次启动时，会创建一个 myappdb 数据库和一个拥有创建数据库权限的 myappuser 用户。

2. 初始化脚本：
   在容器首次启动（并且 /var/lib/postgresql/data 目录是空的，需要进行 initdb）时，镜像会查找 /docker-entrypoint-initdb.d/ 目录下的脚本文件，并按文件名排序依次执行。支持的文件类型包括：

   • .sql
   • .sql.gz
   • .sh

   这使得你可以在数据库初始化时自动执行创建用户、创建表、插入初始数据等操作。

   步骤：
   a. 在宿主机上准备你的初始化脚本文件（例如 init.sql）：
   “`sql
   — init.sql
   CREATE TABLE my_table (
   id SERIAL PRIMARY KEY,
   name VARCHAR(100)
   );

   INSERT INTO my_table (name) VALUES (‘示例数据 1’), (‘示例数据 2’);
   b. 在运行容器时，使用 Bind Mount 将包含脚本的宿主机目录挂载到容器的 `/docker-entrypoint-initdb.d/` 目录：bash
   docker run \
   –name my-postgres \
   -e POSTGRES_PASSWORD=mysecretpassword \
   -p 5432:5432 \
   -v pg_data_volume:/var/lib/postgresql/data \
   -v /path/to/your/init/scripts:/docker-entrypoint-initdb.d/ \
   -d \
   postgres:15.4
   ``
替换/path/to/your/init/scripts为你在宿主机上存放init.sql` 文件的实际目录。

   下次首次启动容器（或者删除数据卷后重新启动），这些脚本就会自动执行。

3. PostgreSQL 配置 (postgresql.conf)：
   要修改 PostgreSQL 的配置参数（通常在 postgresql.conf 文件中），官方镜像提供了几种方法：

   • 环境变量： 一些常用的配置可以通过特定的环境变量设置，例如 POSTGRES_INITDB_ARGS 可以传递给 initdb，但大部分运行时配置需要其他方法。
   • 挂载配置文件或目录： 最直接的方法是使用 Bind Mount 挂载一个自定义的 postgresql.conf 文件，或者更灵活地，挂载一个包含额外配置片段的目录到 /etc/postgresql/conf.d/。

   示例：挂载一个包含额外配置片段的目录：
   a. 在宿主机创建一个目录，例如 /path/to/your/pg_conf.d。
   b. 在该目录中创建 .conf 文件，例如 custom.conf：
   “`conf

   custom.conf

   log_min_duration_statement = 1000
   max_connections = 200
   c. 运行容器时挂载该目录：bash
   docker run \
   –name my-postgres \
   -e POSTGRES_PASSWORD=mysecretpassword \
   -p 5432:5432 \
   -v pg_data_volume:/var/lib/postgresql/data \
   -v /path/to/your/pg_conf.d:/etc/postgresql/conf.d/ \
   -d \
   postgres:15.4
   ``
PostgreSQL 会加载/etc/postgresql/conf.d/目录中的所有.conf` 文件。这是一种推荐的方式，可以保持默认配置不变，只覆盖或添加你需要修改的参数。

第六章：容器生命周期管理

了解如何管理 Docker 容器的生命周期是必不可少的。

• 停止容器：
  bash
docker stop my-postgres
  Docker 会向容器发送 SIGTERM 信号，等待容器内部的进程优雅地关闭（PostgreSQL 会执行检查点并停止）。如果容器在一定时间内（默认为 10 秒）没有停止，Docker 会发送 SIGKILL 信号强制停止。

• 启动已停止的容器：
  bash
docker start my-postgres
  这将启动一个之前创建并停止的容器。由于数据保存在卷中，数据库状态会得到恢复。

• 重启容器：
  bash
docker restart my-postgres
  等同于先执行 docker stop 再执行 docker start。

• 删除容器：
  bash
docker rm my-postgres
  警告： 删除容器只会删除容器本身的文件系统层，不会删除与之关联的卷 (pg_data_volume)。容器被删除后就无法再启动。如果你想删除容器 和 数据卷，需要单独删除卷（见下文）。

• 查看容器日志：
  bash
docker logs my-postgres
  这将输出容器的标准输出和标准错误日志，对于排查启动或运行问题非常有用。添加 -f 选项可以持续跟踪日志输出。

• 查看容器详情：
  bash
docker inspect my-postgres
  输出容器的详细配置信息，包括网络设置、卷挂载、环境变量等，这是一个非常有用的调试工具。

第七章：Docker Compose (多服务编排)

在实际应用中，数据库通常不是孤立存在的，而是作为整个应用栈的一部分（例如，与 Web 服务器、后端服务一起工作）。Docker Compose 是一个用于定义和运行多容器 Docker 应用的工具。通过一个 YAML 文件 (docker-compose.yml) 来配置应用的服务、网络和卷，然后使用一个命令 (docker compose up) 来启动所有服务。

使用 Docker Compose 运行 PostgreSQL 非常方便：

1. 安装 Docker Compose： Docker Desktop 通常已经包含了 Docker Compose。对于 Linux，可能需要单独安装（请参考 Docker 官方文档）。

2. 创建 docker-compose.yml 文件：
   在一个项目目录下创建一个名为 docker-compose.yml 的文件：

   “`yaml
   version: ‘3.8’ # 或者更新的版本

   services:
   db: # 服务名称，你可以在同一网络中的其他服务中使用 ‘db’ 作为主机名访问
   image: postgres:15.4 # 使用 PostgreSQL 镜像
   container_name: my_app_postgres_db # 可选，指定容器名称
   restart: always # 容器退出时总是重启
   ports:
   – “5432:5432” # 映射端口到宿主机 (可选，如果只有其他容器访问则不需要)
   environment:
   POSTGRES_PASSWORD: mysecretpassword # 设置超级用户密码
   POSTGRES_USER: myappuser # 设置用户 (可选)
   POSTGRES_DB: myappdb # 设置数据库 (可选)
   # PGDATA: /var/lib/postgresql/data/pgdata # 可选，如果需要将数据存储在子目录，配合 volume subpath
   volumes:
   – pg_data_volume:/var/lib/postgresql/data # 挂载数据卷
   # – ./init-scripts:/docker-entrypoint-initdb.d # 挂载初始化脚本目录 (可选)
   # – ./pg_conf.d:/etc/postgresql/conf.d # 挂载配置目录 (可选)
   # networks:
   # – my-app-network # 可选，加入用户定义的网络

   networks:

   my-app-network: # 定义用户定义的网络 (可选)

   volumes:
   pg_data_volume: # 定义数据卷
   “`

3. 启动服务：
   在 docker-compose.yml 文件所在的目录中，打开终端执行：

   “`bash
   docker compose up -d

   或者使用旧版语法: docker-compose up -d

   ``
*up: 构建（如果需要）并启动 services。
*-d`: 在后台运行。

   Docker Compose 会读取 docker-compose.yml 文件，创建卷（如果不存在），构建/拉取镜像，然后启动 db 服务。

4. 停止服务：
   在同一目录执行：

   “`bash
   docker compose down

   或者使用旧版语法: docker-compose down

   ``
这将停止并移除docker-compose.yml文件中定义的所有服务容器和默认网络。**注意：默认情况下不会删除卷。**如果要同时删除卷，使用docker compose down -v`。

Docker Compose 大大简化了多容器应用的部署和管理，是容器化应用开发的常用工具。

第八章：总结与最佳实践

通过 Docker 运行 PostgreSQL 容器带来了巨大的便利，但为了确保稳定、安全和高效的数据库环境，还需要遵循一些最佳实践：

1. 数据持久化是基石： 务必使用 Docker Volume 或 Bind Mount 来持久化 /var/lib/postgresql/data 目录。容器是临时的，数据才是核心。推荐使用 Docker Volume。
2. 使用特定版本的镜像： 避免使用 latest 标签，指定具体的 PostgreSQL 版本（如 postgres:15.4）。这可以确保环境的可重复性，避免意外的升级导致兼容性问题。
3. 管理好 Superuser 密码： POSTGRES_PASSWORD 是敏感信息。避免在命令行中直接输入。在生产环境中，考虑使用 Docker Secrets 或其他安全的配置管理方式。
4. 初始化脚本的妙用： 利用 /docker-entrypoint-initdb.d/ 目录在首次启动时执行初始化任务（创建数据库、用户、表、初始数据），实现数据库环境的自动化配置。
5. 合理的端口映射或网络配置： 根据你的需求选择是否需要将端口映射到宿主机。如果只供其他 Docker 容器访问，使用用户定义的 Docker 网络是更安全和灵活的方式。
6. 监控与日志： 定期检查容器日志 (docker logs)，监控数据库的性能和健康状态。
7. 资源限制： 在生产环境中，考虑为数据库容器设置资源限制（CPU、内存），避免其占用过多资源影响宿主机或其他服务。这可以在 docker run 或 docker-compose.yml 中配置。
8. 备份与恢复： 容器化并不意味着不需要备份。即使数据卷持久化了，仍然需要定期备份数据卷中的数据，并测试恢复流程。你可以运行一个临时的容器来连接到数据卷进行备份。
9. 安全加固： 考虑默认的 postgres 用户权限，创建专门的应用用户并限制其权限。配置 pg_hba.conf 来限制哪些主机可以连接（这通常需要通过挂载配置目录或在初始化脚本中修改）。

结论

将 PostgreSQL 运行在 Docker 容器中是提升开发效率、简化部署和增强环境一致性的强大方式。从拉取镜像、运行容器，到配置数据持久化、连接方式以及利用初始化脚本进行自动化设置，掌握这些技能将帮助你更有效地管理数据库环境。结合 Docker Compose，你可以轻松地将 PostgreSQL 集成到你的多容器应用栈中。通过遵循最佳实践，你可以确保你的 PostgreSQL Docker 环境既方便快捷，又稳定可靠。现在，开始你的 PostgreSQL Docker 之旅吧！

---