草稿状态：本文仅保存到 CSDN 草稿箱，待人工检查和实测后再决定是否发布。

摘要

本文使用 Docker 官方 postgres 镜像运行 PostgreSQL 14，完成命名卷持久化、数据库初始化、就绪检查、psql 连接、客户端连接、备份恢复和重启验证。示例密码只作为占位符，不能直接用于生产环境。

一、前置准备

docker version
docker info

确认 Docker 已启动，主机 5432 端口可用，并为数据库卷和备份文件预留空间。已有 PostgreSQL 服务时，不要直接复用 postgres 容器名和数据卷。

二、拉取官方镜像

docker pull postgres:14
docker image inspect postgres:14

postgres 是 Docker Official Image，14 表示 PostgreSQL 14 系列。固定大版本有利于本地教程复现，但补丁版本仍应以实际镜像输出为准。

三、创建数据卷

docker volume create postgres_data
docker volume inspect postgres_data

PostgreSQL 14 的数据目录挂载到 /var/lib/postgresql/data。命名卷独立于容器，但不是备份。

四、启动 PostgreSQL

替换示例密码后执行：

docker run -d --name postgres -p 5432:5432 -e POSTGRES_USER=appuser -e POSTGRES_PASSWORD=ChangeMe_123456 -e POSTGRES_DB=appdb -v postgres_data:/var/lib/postgresql/data --restart unless-stopped postgres:14

POSTGRES_PASSWORD 通常是初始化必需项。POSTGRES_USER、POSTGRES_DB 和密码只在空数据目录第一次初始化时生效；复用已有卷时，修改环境变量不会自动修改现有用户和数据库。

如果 5432 被占用，可改为 15432:5432，客户端端口也要改成 15432。

五、确认数据库就绪

docker ps --filter "name=postgres"
docker exec postgres pg_isready -U appuser -d appdb
docker logs --tail 100 postgres

pg_isready 返回 accepting connections 后再连接数据库。容器状态 Up 不能单独证明 PostgreSQL 已经可以接受连接。

六、进入 psql

docker exec -it postgres psql -U appuser -d appdb

在 psql 中执行：

SELECT version();
\l
\dt
\q

七、创建测试表并插入数据

示例表包含项目常用的备注、删除状态、创建修改人和时间字段：

CREATE TABLE demo_user (
    id BIGSERIAL PRIMARY KEY,
    user_name VARCHAR(100) NOT NULL,
    remark VARCHAR(500),
    delete_status SMALLINT NOT NULL DEFAULT 0 CHECK (delete_status IN (0, 1)),
    create_user_no BIGINT,
    modified_user_no BIGINT,
    create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    modified_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO demo_user (user_name, remark)
VALUES ('alice', 'Docker PostgreSQL test');

SELECT id, user_name, create_time
FROM demo_user
WHERE delete_status = 0;

modified_time 不会自动像某些 MySQL 定义那样更新，业务更新时应显式维护，或创建触发器。

八、使用 Navicat 或 DBeaver 连接

项目	值
主机	127.0.0.1
端口	5432
用户名	appuser
密码	启动容器时设置的密码
数据库	appdb

若使用 15432:5432，客户端端口填写 15432。

九、备份与恢复

备份：

docker exec postgres pg_dump -U appuser -d appdb > .\appdb-backup.sql

恢复：

Get-Content .\appdb-backup.sql | docker exec -i postgres psql -U appuser -d appdb

备份文件应保存到独立位置，并定期验证恢复，不要只依赖 Docker 卷。

十、重启验证

docker exec postgres psql -U appuser -d appdb -c "SELECT count(*) FROM demo_user;"
docker restart postgres
docker exec postgres pg_isready -U appuser -d appdb
docker exec postgres psql -U appuser -d appdb -c "SELECT count(*) FROM demo_user;"

两次数量一致，说明容器重启后数据仍能读取。

十一、修改密码和创建数据库

已有用户修改密码：

docker exec -it postgres psql -U appuser -d appdb

ALTER ROLE appuser WITH PASSWORD '新的强密码';
CREATE DATABASE otherdb;
\q

十二、常见问题

修改 POSTGRES_PASSWORD 没有生效

数据卷已经初始化，环境变量不会重新初始化数据库。使用 ALTER ROLE 修改密码，或在确认无数据后删除并重新创建卷。

连接失败

依次检查端口映射、容器日志和 pg_isready，不要先删除卷。

删除容器后数据还在吗

只删除容器、保留 postgres_data 时，数据通常仍在。删除卷会永久删除数据库文件。

十三、卸载

只删除容器：

docker rm -f postgres

确认数据不再需要后：

docker volume rm postgres_data
docker image rm postgres:14

十四、官方资料

• PostgreSQL Docker Official Image
• PostgreSQL 官方文档
• Docker Volumes 官方文档

总结

本教程完成了 PostgreSQL 14 镜像拉取、命名卷持久化、初始化、就绪检查、客户端连接、备份恢复和重启验证。密码、端口、补丁版本和备份策略必须根据实际环境人工确认。