boky/postgresql

boky/postgresql

• 简介
  • 贡献
  • 问题反馈
• 快速开始
  • 安装
  • 快速启动
  • 数据持久化
  • 信任本地连接
  • 设置postgres用户密码
  • 创建数据库用户
  • 创建数据库
  • 授予用户数据库访问权限
  • 启用扩展
  • 创建复制用户
  • 设置复制集群
  • 启用日志归档
  • 创建快照
  • 创建备份
  • 命令行参数
  • 日志
  • UID/GID映射
• 维护
  • 升级
  • Shell访问

简介

本Dockerfile用于创建PostgreSQL数据库的Docker容器镜像。该镜像基于Alpine Linux构建，包含PostgreSQL的多个可选功能，镜像大小约为130MB。

PostgreSQL是一个强调可扩展性和标准合规性的对象关系型数据库管理系统（ORDBMS）[来源]。

此镜像包含以下PostgreSQL模块：

• --with-openssl：支持TLS连接（端口5433，详见启用方法）
• --with-ldap：支持LDAP认证
• --with-libxml：支持XML列类型
• --with-libxslt：支持XSLT转换和XPath查询
• --with-perl：支持PERL PL模块
• --with-python：支持Python PL模块

注意：本镜像基于https://github.com/sameersbn/docker-postgresql%E7%9A%84%E4%BC%98%E7%A7%80%E5%B7%A5%E4%BD%9C%E4%BF%AE%E6%94%B9%E8%80%8C%E6%9D%A5%EF%BC%8C%E4%B8%BB%E8%A6%81%E5%8C%BA%E5%88%AB%E5%A6%82%E4%B8%8B%EF%BC%9A

• 基于Alpine以减小镜像体积
• 直接编译Postgres并包含部分插件（便于在其他平台构建）

贡献

如果您觉得此镜像有用，您可以通过以下方式提供帮助：

• 提交包含新功能或错误修复的Pull Request
• 帮助用户解决问题

问题反馈

在报告问题前，请尝试更新Docker至最新版本，查看是否解决问题。Docker安装指南可参考官方文档。

SELinux用户可尝试使用setenforce 0命令禁用SELinux，查看是否解决问题。

如果上述方法无效，请报告问题并提供以下信息：

• docker version和docker info命令的输出
• 启动镜像使用的docker run命令或docker-compose.yml文件（敏感信息请脱敏）
• 说明是否使用http://www.boot2docker.io%E3%80%81VirtualBox%E7%AD%89%E5%B7%A5%E5%85%B7

快速开始

安装

推荐通过Dockerhub的自动构建获取镜像：

注意：镜像也可在Quay.io获取

bash
docker pull boky/postgresql

也可手动构建镜像：

bash
docker build -t boky/postgresql github.com/bokysan/docker-postgresql

快速启动

使用以下命令启动PostgreSQL：

bash
docker run --name postgresql -itd --restart always \
  --publish 5432:5432 \
  --volume /srv/docker/postgresql:/var/lib/postgresql \
  boky/postgresql

通过以下命令登录PostgreSQL服务器：

bash
docker exec -it postgresql psql -Upostgres

或者，可使用示例docker-compose.yml文件通过Docker Compose启动容器

数据持久化

为使PostgreSQL在容器重启后保留数据，需挂载/var/lib/postgresql卷。

快速启动命令已包含持久化卷挂载

SELinux用户需更新主机挂载点的安全上下文，以确保与Docker兼容：

bash
mkdir -p /srv/docker/postgresql
chcon -Rt svirt_sandbox_file_t /srv/docker/postgresql

信任本地连接

默认情况下，PostgreSQL服务器连接需要密码认证。若需信任本地网络连接，可设置PG_TRUST_LOCALNET变量：

bash
docker run --name postgresql -itd --restart always \
  --env 'PG_TRUST_LOCALNET=true' \
  boky/postgresql

注意

此处的"本地网络"指容器所连接的网络，具体含义取决于启动容器时指定的--net参数。默认配置下，此参数将信任docker0桥接网络上的其他容器连接。

设置postgres用户密码

默认情况下，postgres用户未设置密码，因此只能本地登录。若需远程登录postgres用户，需通过PG_PASSWORD变量设置密码：

bash
docker run --name postgresql -itd --restart always \
  --env 'PG_PASSWORD=passw0rd' \
  boky/postgresql

注意

• 启用数据持久化时，PG_PASSWORD仅在首次运行时生效
• 此功能仅在latest及版本>9.4-10中可用

创建数据库用户

启动容器时，可通过DB_USER和DB_PASS变量创建PostgreSQL数据库用户：

bash
docker run --name postgresql -itd --restart always \
  --env 'DB_USER=dbuser' --env 'DB_PASS=dbuserpass' \
  boky/postgresql

也可使用https://github.com/docker-library/postgres%E7%9A%84%E5%8F%98%E9%87%8F%60POSTGRES_USER%60%E3%80%81%60POSTGRES_PASSWORD%60%E5%92%8C%60POSTGRES_PASSWORD_FILE%60%E3%80%82

若需创建多个用户，可用空格分隔用户名。因此，包含空格的密码将无法正常使用。

bash
docker run --name postgresql -itd --restart always \
  --env 'POSTGRES_USER=dbuser1 dbuser2' --env 'POSTGRES_PASSWORD=dbuserpass1 dbuserpass2' \
  boky/postgresql

密码将按顺序分配。例如，可为多个用户设置相同密码：

bash
docker run --name postgresql -itd --restart always \
  --env 'POSTGRES_USER=dbuser1 dbuser2 dbuser3 dbuser4 dbuser5 dbuser6' --env 'POSTGRES_PASSWORD=samepass' \
  boky/postgresql

注意

• 创建的用户可远程登录
• 若未指定用户密码，容器将启动失败
• 若用户已存在，则不会进行更改
• 每次启动仅能创建一个用户

创建数据库

启动容器时，可通过DB_NAME（或为兼容官方镜像使用POSTGRES_DB）变量创建PostgreSQL数据库：

bash
docker run --name postgresql -itd --restart always \
  --env 'DB_NAME=dbname' \
  boky/postgresql

默认情况下，数据库通过复制标准系统数据库template1创建。可通过DB_TEMPLATE参数指定其他模板，详情参考模板数据库。

此外，可通过在DB_NAME中指定空格或逗号分隔的数据库名称列表创建多个数据库。例如，以下命令创建dbname1和dbname2两个数据库：

此功能仅在版本>9.1-1中可用

bash
docker run --name postgresql -itd --restart always \
  --env 'DB_NAME=dbname1 dbname2' \
  boky/postgresql

授予用户数据库访问权限

若同时指定DB_USER、DB_PASS和DB_NAME变量，DB_USER指定的用户将被授予DB_NAME列表中所有数据库的访问权限。若用户或数据库不存在，将自动创建。

bash
docker run --name postgresql -itd --restart always \
  --env 'DB_USER=dbuser' --env 'DB_PASS=dbuserpass' \
  --env 'DB_NAME=dbname1,dbname2' \
  boky/postgresql

上述示例中，dbuser将被授予dbname1和dbname2数据库的访问权限。若DB_USER包含多个用户名，第一个用户将被授予数据库访问权限。若需显式指定用户，可使用以下语法：

bash
docker run --name postgresql -itd --restart always \
  --env 'DB_USER=dbuser1 dbuser2' --env 'DB_PASS=dbuserpass' \
  --env 'DB_NAME=dbuser1@dbname1 dbuser2@dbname2' \
  boky/postgresql

启用扩展

镜像包含postgres contrib模块。可通过DB_EXTENSION参数指定逗号分隔的扩展列表：

bash
docker run --name postgresql -itd \
  --env 'DB_NAME=db1,db2' --env 'DB_EXTENSION=unaccent,pg_trgm' \
  boky/postgresql

上述命令将在DB_NAME指定的db1和db2数据库上启用unaccent和pg_trgm扩展。

注意：此选项替代了DB_UNACCENT参数

创建复制用户

与创建数据库用户类似，可通过REPLICATION_USER和REPLICATION_PASS变量创建PostgreSQL复制用户：

bash
docker run --name postgresql -itd --restart always \
  --env 'REPLICATION_USER=repluser' --env 'REPLICATION_PASS=repluserpass' \
  boky/postgresql

注意

• 创建的用户可远程登录
• 若未指定用户密码，容器将启动失败
• 若用户已存在，则不会进行更改
• 每次启动仅能创建一个用户

建议创建复制用户，即使暂时不使用，以便后续设置从节点、生成快照或备份

设置复制集群

容器默认配置为复制集群的主节点，可在需要时扩展PostgreSQL数据库后端而不中断服务。但需确保主节点存在复制用户。

首先创建集群主节点：

bash
docker run --name postgresql-master -itd --restart always \
  --env 'DB_USER=dbuser' --env 'DB_PASS=dbuserpass' --env 'DB_NAME=dbname' \
  --env 'REPLICATION_USER=repluser' --env 'REPLICATION_PASS=repluserpass' \
  boky/postgresql

启动主节点时无需额外参数。

创建复制从节点需设置REPLICATION_MODE=slave，并指定REPLICATION_HOST、REPLICATION_PORT、REPLICATION_SSLMODE、REPLICATION_USER和REPLICATION_PASS变量：

bash
docker run --name postgresql-slave01 -itd --restart always \
  --link postgresql-master:master \
  --env 'REPLICATION_MODE=slave' --env 'REPLICATION_SSLMODE=prefer' \
  --env 'REPLICATION_HOST=master' --env 'REPLICATION_PORT=5432'  \
  --env 'REPLICATION_USER=repluser' --env 'REPLICATION_PASS=repluserpass' \
  boky/postgresql

上述命令使用Docker链接，因此可通过master别名在REPLICATION_HOST中引用主节点

注意

• REPLICATION_PORT默认值为5432
• REPLICATION_SSLMODE默认值为prefer
• REPLICATION_USER和REPLICATION_PASS需与主节点设置一致
• 启用数据持久化时，若容器重启，需确保REPLICATION_MODE=slave环境变量存在，否则从节点配置将被禁用，节点将允许写入并保留与主节点的最后同步数据

PostgreSQL复制集群重要说明：

• 仅主节点可写入数据
• 从节点为只读
• 为获得最佳性能，应将读操作限制在从节点

启用日志归档

若需启用日志归档（用于时间点恢复），设置PG_LOG_ARCHIVING=true。日志将复制到/var/lib/postgresql/{version}/log-archive/。若该目录存在archive.sh文件，日志复制成功后将执行该脚本。可通过PG_LOG_ARCHIVING_COMMAND变量覆盖复制命令。

创建快照

与创建复制从节点类似，可通过REPLICATION_MODE=snapshot创建主节点快照。

按设置复制集群创建主节点后，可使用以下命令创建快照：

bash
docker run --name postgresql-snapshot -itd --restart always \
  --link postgresql-master:master \
  --env 'REPLICATION_MODE=snapshot' --env 'REPLICATION_SSLMODE=prefer' \
  --env 'REPLICATION_HOST=master' --env 'REPLICATION_PORT=5432'  \
  --env 'REPLICATION_USER=repluser' --env 'REPLICATION_PASS=repluserpass' \
  boky/postgresql

从节点与快照的区别：从节点为只读，会随主节点数据更新（流复制）；快照为可读写，初始数据同步后不再更新。

此功能便于开发人员快速快照生产数据库状态，用于开发/调试而不影响生产实例。

创建备份

与设置从节点或生成快照类似，可通过REPLICATION_MODE=backup创建主节点数据备份。

备份通过pg_basebackup使用复制协议生成

按设置复制集群创建主节点后，可使用以下命令创建时间点备份：

bash
docker run --name postgresql-backup -it --rm \
  --link postgresql-master:master \
  --env 'REPLICATION_MODE=backup' --env 'REPLICATION_SSLMODE=prefer' \
  --env 'REPLICATION_HOST=master' --env 'REPLICATION_PORT=5432'  \
  --env 'REPLICATION_USER=repluser' --env 'REPLICATION_PASS=repluserpass' \
  --volume /srv/docker/backups/postgresql.$(date +%Y%m%d%H%M%S):/var/lib/postgresql \
  boky/postgresql

备份生成后，容器将退出，主节点数据备份可在/srv/docker/backups/postgresql.XXXXXXXXXXXX/目录找到。恢复备份需启动一个使用/srv/docker/backups/postgresql.XXXXXXXXXXXX目录数据的容器。

命令行参数

可通过在docker run命令中指定postgres参数自定义PostgreSQL服务器启动命令。例如，以下命令启用连接日志：

bash
docker run --name postgresql -itd --restart always \
  boky/postgresql -c log_connections=on

完整参数列表请参考postgres文档。

日志

默认情况下，PostgreSQL服务器日志输出到标准输出。可通过命令行参数使用-c logging_collector=on将日志输出到文件：

bash
docker run --name postgresql -itd --restart always \
  boky/postgresql -c logging_collector=on

可通过docker exec访问PostgreSQL日志，例如：

bash
docker exec -it postgresql tail -f /var/log/postgresql/postgresql-10.0-main.log

UID/GID映射

容器创建的文件和进程由容器内部的postgres用户拥有。在Docker未启用用户命名空间的情况下，容器postgres用户的UID和GID在主机上可能有不同含义。

例如，主机上与容器postgres用户UID/GID相同的用户将能够访问从主机挂载的持久卷数据，甚至终止容器启动的postgres服务器进程。

为解决此问题，可通过USERMAP_UID和USERMAP_GID变量指定容器postgres用户的UID和GID。

例如，将容器postgres用户的UID和