使用Docker/Docker Compose方式安装部署PostgreSQL指南

文章目录

- 引言
- [1. 快速开始：使用Docker Compose部署PostgreSQL](#1. 快速开始：使用Docker Compose部署PostgreSQL)
- - [1.1 创建docker-compose.yml文件](#1.1 创建docker-compose.yml文件)
  - [1.2 启动PostgreSQL容器](#1.2 启动PostgreSQL容器)
  - [1.3 验证部署](#1.3 验证部署)
- [2. 初始化数据库：自动执行SQL脚本](#2. 初始化数据库：自动执行SQL脚本)
- - [2.1 创建初始化脚本](#2.1 创建初始化脚本)
  - [2.2 修改docker-compose.yml以挂载初始化脚本](#2.2 修改docker-compose.yml以挂载初始化脚本)
  - [2.3 重新启动容器](#2.3 重新启动容器)
- [3. 处理常见的权限和连接问题](#3. 处理常见的权限和连接问题)
- - [3.1 错误示例](#3.1 错误示例)
  - [3.2 错误原因分析](#3.2 错误原因分析)
  - [3.3 解决方案：创建新用户和数据库](#3.3 解决方案：创建新用户和数据库)
  - [3.4 通过环境变量自动创建用户](#3.4 通过环境变量自动创建用户)
- [4. 导入现有SQL文件到数据库](#4. 导入现有SQL文件到数据库)
- - [4.1 基本导入方法](#4.1 基本导入方法)
  - [4.2 处理密码验证](#4.2 处理密码验证)
  - [4.3 处理编码问题](#4.3 处理编码问题)
- [5. 高级配置与优化](#5. 高级配置与优化)
- - [5.1 自定义PostgreSQL配置](#5.1 自定义PostgreSQL配置)
  - [5.2 数据持久化与备份](#5.2 数据持久化与备份)
  - - 备份数据库
    - 恢复数据库
  - [5.3 多脚本初始化管理](#5.3 多脚本初始化管理)
- 常用操作docker命令
- [6. 最佳实践与总结](#6. 最佳实践与总结)
- - [6.1 安全建议](#6.1 安全建议)
  - [6.2 性能优化](#6.2 性能优化)
  - [6.3 故障排除](#6.3 故障排除)
  - [6.4 总结](#6.4 总结)
  - 参考链接

引言

在现代软件开发中，容器化技术已成为部署数据库服务的标准做法。Docker提供了一种轻量级、可移植且一致的环境，使得PostgreSQL的部署和管理变得更加简单高效。本文将详细介绍如何使用Docker和Docker Compose部署PostgreSQL，并解决部署过程中常见的权限和连接问题。

1. 快速开始：使用Docker Compose部署PostgreSQL

1.1 创建docker-compose.yml文件

首先，创建一个docker-compose.yml文件，配置PostgreSQL服务：

yaml 复制代码

version: '3.8'

services:
  postgres:
    image: postgres:17-alpine
    container_name: xiaoshi-db-1
    restart: always
    environment:
      POSTGRES_PASSWORD: mysecretpassword
      POSTGRES_DB: my_app_db
      TZ: Asia/Shanghai
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pg_data:
    driver: local

1.2 启动PostgreSQL容器

在包含docker-compose.yml文件的目录中，运行以下命令启动容器：

bash 复制代码

docker-compose up -d

1.3 验证部署

检查容器是否正常运行：

bash 复制代码

docker ps

查看容器日志，确认PostgreSQL已成功启动：

bash 复制代码

docker logs xiaoshi-db-1

2. 初始化数据库：自动执行SQL脚本

PostgreSQL官方镜像提供了一个强大的初始化机制。容器首次启动时，会自动执行/docker-entrypoint-initdb.d/目录下的所有.sql和.sh脚本。

2.1 创建初始化脚本

创建一个名为init.sql的SQL脚本文件：

sql 复制代码

-- 创建用户信息表
CREATE TABLE IF NOT EXISTS user_info (
  id SERIAL PRIMARY KEY,
  username VARCHAR(50) NOT NULL,
  email VARCHAR(100) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 插入初始数据
INSERT INTO user_info (username, email) VALUES
  ('admin', 'admin@example.com'),
  ('user1', 'user1@example.com');

2.2 修改docker-compose.yml以挂载初始化脚本

更新docker-compose.yml文件，将初始化脚本挂载到容器中：

yaml 复制代码

services:
  postgres:
    # ... 其他配置保持不变
    volumes:
      - pg_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql  # 新增挂载

2.3 重新启动容器

删除现有容器和数据卷，然后重新启动：

bash 复制代码

docker-compose down -v
docker-compose up -d

3. 处理常见的权限和连接问题

3.1 错误示例

尝试使用不存在的用户连接数据库时，会遇到以下错误：

bash 复制代码

docker exec -it xiaoshi-db-1 psql -U xiaoshi -c "CREATE DATABASE xiaoshi_db;"

错误信息：

复制代码

psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: 
FATAL: role "xiaoshi" does not exist

3.2 错误原因分析

角色与数据库分离：在PostgreSQL中，角色（用户）和数据库是两个独立的概念
默认用户 ：PostgreSQL容器默认只创建postgres超级用户
连接要求：连接数据库必须使用已存在的角色

3.3 解决方案：创建新用户和数据库

步骤1：使用超级用户创建新角色

bash 复制代码

docker exec -it xiaoshi-db-1 psql -U postgres -c "CREATE ROLE xiaoshi WITH LOGIN PASSWORD 'your_password';"

步骤2：为新角色创建数据库

bash 复制代码

docker exec -it xiaoshi-db-1 psql -U postgres -c "CREATE DATABASE xiaoshi_db OWNER xiaoshi;"

步骤3：授予权限（可选但建议）

bash 复制代码

docker exec -it xiaoshi-db-1 psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE xiaoshi_db TO xiaoshi;"

3.4 通过环境变量自动创建用户

在docker-compose.yml中设置环境变量，可以在容器初始化时自动创建用户：

yaml 复制代码

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: mysecretpassword
      POSTGRES_USER: xiaoshi  # 指定要创建的用户名
      POSTGRES_DB: xiaoshi_db  # 指定要创建的数据库名
    # ... 其他配置

注意：这种方法仅在数据卷为空时生效。如果数据卷已存在，环境变量不会自动创建新用户。

4. 导入现有SQL文件到数据库

4.1 基本导入方法

将宿主机上的SQL文件导入到已创建的数据库中：

bash 复制代码

cat my_database.sql | docker exec -i xiaoshi-db-1 psql -U xiaoshi -d xiaoshi_db

4.2 处理密码验证

如果设置了密码，可以通过环境变量传递：

bash 复制代码

cat my_database.sql | docker exec -i -e PGPASSWORD='your_password' xiaoshi-db-1 psql -U xiaoshi -d xiaoshi_db

4.3 处理编码问题

如果SQL文件包含非UTF-8编码的字符（如中文GBK编码），需要先转换编码：

bash 复制代码

# 将GBK编码转换为UTF-8
iconv -f GBK -t UTF-8 my_database.sql > my_database_utf8.sql

# 导入转换后的文件
cat my_database_utf8.sql | docker exec -i xiaoshi-db-1 psql -U xiaoshi -d xiaoshi_db

5. 高级配置与优化

5.1 自定义PostgreSQL配置

创建自定义的postgresql.conf文件：

ini 复制代码

# postgresql.conf
shared_buffers = 256MB
effective_cache_size = 1GB
max_connections = 100

在docker-compose.yml中挂载配置文件：

yaml 复制代码

services:
  postgres:
    # ... 其他配置
    volumes:
      - pg_data:/var/lib/postgresql/data
      - ./postgresql.conf:/etc/postgresql/postgresql.conf
    command: postgres -c config_file=/etc/postgresql/postgresql.conf

5.2 数据持久化与备份

备份数据库

bash 复制代码

docker exec xiaoshi-db-1 pg_dump -U postgres my_app_db > backup_$(date +%Y%m%d).sql

恢复数据库

bash 复制代码

cat backup.sql | docker exec -i xiaoshi-db-1 psql -U postgres my_app_db

5.3 多脚本初始化管理

如果有多个初始化脚本，可以按顺序组织：

复制代码

/docker-entrypoint-initdb.d/
├── 01_schema.sql    # 创建表结构
├── 02_functions.sql # 创建函数和存储过程
└── 03_data.sql      # 插入初始数据

在docker-compose.yml中挂载整个目录：

yaml 复制代码

services:
  postgres:
    # ... 其他配置
    volumes:
      - pg_data:/var/lib/postgresql/data
      - ./init-scripts:/docker-entrypoint-initdb.d

常用操作docker命令

bash 复制代码

#创建角色
docker exec -it xiaoshi-db-1 psql -U postgres -c "CREATE ROLE xiaoshi WITH LOGIN PASSWORD 'admin111111';"

#创建数据库
docker exec -it xiaoshi-db-1 psql -U postgres -c "CREATE DATABASE xiaoshi_db OWNER xiaoshi;"

#赋予权限
docker exec -it xiaoshi-db-1 psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE xiaoshi_db TO xiaoshi;"

# 使用新创建的用户 xiaoshi 导入
iconv -f GBK -t UTF-8 user_info_pg.sql > user_info_pg_utf8.sql

# 将宿主机的本机sql导入到容器中的pgsql库中
cat user_info_pg_utf8.sql | docker exec -i xiaoshi-db-1 psql -U xiaoshi -d xiaoshi_db

注意：如果执行时提示密码错误，可以在命令前临时添加环境变量（仅限调试）：
cat my.sql | docker exec -i -e PGPASSWORD='你的密码' xiaoshi-db-1 psql -U xiaoshi -d xiaoshi_db

#查看数据表
docker exec -it xiaoshi-db-1 psql -U xiaoshi -d xiaoshi_db -c "\dt"

#查看具体表的字段、类型、索引和触发器：
docker exec -it xiaoshi-db-1 psql -U xiaoshi -d xiaoshi_db -c "\d user_info"

#上面都是单条指令在宿主机上直接执行，如果要交互，则
#进入pgsql容器交互界面：
docker exec -it xiaoshi-db-1 psql -U xiaoshi -d xiaoshi_db

#在交互界面内使用快捷命令：
\dt : 列出所有表。
\d user_info : 查看 user_info 表的详细结构（推荐）。
\d+ user_info : 查看更详细的信息（包括字段描述/注释、磁盘占用等）。
\q : 退出。

6. 最佳实践与总结

6.1 安全建议

使用强密码：为PostgreSQL用户设置复杂密码
限制网络访问：在生产环境中，避免将5432端口暴露给公网
定期更新：使用最新版本的PostgreSQL镜像，确保安全补丁

6.2 性能优化

调整共享缓冲区 ：根据可用内存调整shared_buffers参数
启用连接池：考虑使用PgBouncer等连接池工具
监控性能：使用pg_stat_statements扩展监控查询性能

6.3 故障排除

检查容器日志 ：使用docker logs xiaoshi-db-1查看错误信息
验证连接 ：使用pg_isready工具检查数据库是否就绪
检查权限：确保数据库用户具有适当的权限

6.4 总结

使用Docker部署PostgreSQL提供了以下优势：

环境一致性：确保开发、测试和生产环境的一致性
快速部署：几分钟内即可启动完整的PostgreSQL实例
易于管理：通过Docker Compose简化多服务管理
资源隔离：每个数据库实例在独立的容器中运行

通过遵循本文的指南，您可以快速部署和管理PostgreSQL数据库，同时避免常见的权限和连接问题。无论是开发环境还是生产环境，Docker都为PostgreSQL部署提供了强大而灵活的解决方案。

参考链接

https://smartsi.blog.csdn.net/article/details/139390099

https://blog.csdn.net/openeis/article/details/148444777