Docker + PostgreSQL 部署配置

本文档详细介绍如何使用 Docker 部署 PostgreSQL 数据库，包括数据持久化、时区配置和性能优化。

一、环境准备

1.1 检查 Docker 环境

docker --version
docker-compose version

1.2 拉取 PostgreSQL 镜像

docker pull postgres
docker images -a | grep postgres

二、创建数据目录结构

mkdir -p /home/postgres/
mkdir -p /home/postgres/conf/
mkdir -p /home/postgres/data/
mkdir -p /home/postgres/logs/

三、启动 PostgreSQL 容器

docker run --name postgresql \
  --restart=always \
  -d \
  -p 15432:5432 \
  -v /home/postgres/data/:/var/lib/postgresql/18/main \
  --shm-size=10g \
  -e TZ=Asia/Shanghai \
  -e POSTGRES_PASSWORD=aos@cnaos.com \
  postgres

四、参数说明

参数	说明
--name postgresql	容器名称
-d	后台运行容器
-p 15432:5432	端口映射，主机15432端口映射到容器5432端口
-v /home/postgres/data/:/var/lib/postgresql/18/main	数据目录挂载，实现数据持久化
--shm-size=10g	设置共享内存大小（PostgreSQL需要较大的共享内存）
-e TZ=Asia/Shanghai	设置时区为上海时间
-e POSTGRES_PASSWORD=aos@cnaos.com	设置默认用户postgres的密码
--restart=always	自动重启策略

五、连接测试

# 方式一：进入容器连接
docker exec -it postgresql bash
psql -U postgres

# 方式二：使用外部客户端连接
psql -h 127.0.0.1 -p 15432 -U postgres -W

输入密码：aos@cnaos.com

六、常用命令

# 查看容器状态
docker ps | grep postgresql

# 查看日志
docker logs postgresql

# 重启容器
docker restart postgresql

# 进入容器
docker exec -it postgresql bash

# 备份数据库
docker exec -t postgresql pg_dumpall -U postgres > backup_$(date +%Y%m%d).sql
docker exec -t postgresql pg_dump -U postgres database_name > database_backup.sql

# 恢复数据库
cat backup_20240101.sql | docker exec -i postgresql psql -U postgres
cat database_backup.sql | docker exec -i postgresql psql -U postgres -d database_name

# 查看数据库列表
docker exec -it postgresql psql -U postgres -c "\l"

# 查看表列表
docker exec -it postgresql psql -U postgres -d database_name -c "\dt"

七、时区配置

7.1 修改 postgresql.conf

vim /home/postgres/data/postgresql.conf

添加或修改以下配置：

timezone = 'Asia/Shanghai'
log_timezone = 'Asia/Shanghai'

7.2 重启容器使配置生效

docker restart postgresql

7.3 验证时区配置

docker exec -it postgresql bash
psql -U postgres
SELECT now();

八、优化 PostgreSQL 配置

8.1 基础性能参数

vim /home/postgres/data/postgresql.conf

修改以下参数：

max_connections = 1000
shared_buffers = 2GB
work_mem = 64MB
maintenance_work_mem = 512MB
effective_cache_size = 6GB

参数说明：

• max_connections: 最大并发连接数
• shared_buffers: PostgreSQL用于缓存数据的内存，建议设置为系统内存的25%-40%
• work_mem: 每个查询操作可用的内存（排序、哈希等）
• maintenance_work_mem: 维护操作可用的内存（VACUUM、CREATE INDEX等）
• effective_cache_size: 估算的总可用缓存大小（OS缓存 + shared_buffers），建议设置为主机内存的50%-75%

8.2 SSD 环境优化

如果使用 SSD 存储，添加以下参数提升性能：

random_page_cost = 1.1
effective_io_concurrency = 100

8.2.1 PostgreSQL 18 异步 I/O 优化（新特性）

PostgreSQL 18 引入了异步 I/O 子系统，可在 NVMe 存储上实现 2-3 倍的读取性能提升：

io_method = aio
io_workers = 8
io_max_concurrency = 256
io_combine_limit = 4MB
io_max_combine_limit = 8MB

参数说明：

• io_method: 选择 I/O 后端，aio 启用异步 I/O（需要 Linux 5.1+ 内核）
• io_workers: 异步 I/O 后台工作线程数，建议设置为 CPU 核心数的一半或 8
• io_max_concurrency: 最大并发异步 I/O 操作数，建议设置为 2-4 × NVMe 磁盘数量
• io_combine_limit/io_max_combine_limit: 控制相邻 I/O 请求合并，提高顺序读取性能

验证异步 I/O 状态：

SHOW io_method;
SHOW io_max_concurrency;

注意事项：

• 在 Linux 环境下使用 aio 模式前需要进行基准测试
• 如果出现问题，可回退到默认的 sync 设置
• 需要 Linux 5.1+ 内核支持

8.3 WAL 与检查点优化

wal_buffers = 16MB
min_wal_size = 80MB
max_wal_size = 256MB
checkpoint_completion_target = 0.9

8.4 Docker 环境特殊配置

dynamic_shared_memory_type = posix
huge_pages = off

8.5 内存受限环境配置（<2GB）

如果服务器内存有限，使用以下保守配置：

max_connections = 50
shared_buffers = 128MB
work_mem = 4MB
maintenance_work_mem = 64MB
effective_cache_size = 512MB

重启容器使配置生效：

docker restart postgresql

九、安全建议

1. 修改默认密码：生产环境务必修改默认的 postgres 密码
2. 限制访问：配置防火墙，仅允许特定 IP 访问 PostgreSQL 端口
3. 创建专用用户：为每个应用创建独立的数据库用户，避免使用 postgres 用户
4. 配置 SSL：生产环境建议启用 SSL 连接加密
5. 定期备份：建立定期备份策略，确保数据安全

十、注意事项

数据持久化

确保数据目录正确挂载，否则容器重启后数据会丢失。

时区设置

通过 -e TZ=Asia/Shanghai 环境变量设置时区，但还需要在 postgresql.conf 中配置 timezone 参数才能完全生效。

共享内存

PostgreSQL 需要较大的共享内存，建议通过 --shm-size 参数设置合理的值，特别是在 Docker 环境中。

.NET 兼容性

PostgreSQL 是 Linux 环境下 .NET 应用的推荐数据库选择，因为：

• Npgsql.EntityFrameworkCore.PostgreSQL 对 .NET 10 有良好支持
• 性能稳定，资源占用合理
• 社区活跃，文档完善