tecnativa/postgres-autoconf

PostgreSQL Auto-Conf 镜像文档

镜像概述

PostgreSQL Auto-Conf是一个在启动前自动配置PostgreSQL的镜像，旨在简化特定用户从特定网络访问PostgreSQL服务器的自动化配置流程。通过动态识别Docker网络环境，区分局域网（LAN，已连接的Docker网络）和广域网（WAN，其他网络）连接，自动生成适配的配置文件，解决手动配置网络访问控制的复杂性。

核心功能与特性

• 动态网络识别：在容器入口点阶段识别Docker附加网络的动态IP范围，区分LAN（Docker网络内）和WAN（外部网络）连接。
• 自动配置生成：根据网络类型动态生成postgres.conf（运行时配置）和pg_hba.conf（主机认证配置）文件，无需手动编写。
• 网络隔离控制：分别配置LAN和WAN连接的认证方法、允许访问的数据库及用户，实现精细化权限管理。
• 安全增强支持：支持TLS加密（通过证书配置）和多种认证方式（如证书认证、密码认证等），满足不同安全需求。

使用场景

• Docker环境中需自动化配置PostgreSQL网络访问控制的场景。
• 需要区分局域网和外部网络用户访问权限的PostgreSQL部署（如内部服务与外部客户端隔离）。
• 希望简化pg_hba.conf和postgres.conf配置流程，避免手动维护复杂配置文件的场景。

使用方法与配置说明

基本使用

容器启动时，入口点脚本会根据环境变量和网络环境动态生成配置文件，随后启动PostgreSQL服务。使用方式与标准PostgreSQL镜像类似，主要通过环境变量进行配置。

环境变量配置

所有环境变量的默认值可在https://github.com/Tecnativa/docker-postgres-autoconf/blob/master/Dockerfile%E4%B8%AD%E6%9F%A5%E7%9C%8B%E3%80%82%E5%85%B3%E9%94%AE%E9%85%8D%E7%BD%AE%E5%8F%98%E9%87%8F%E5%A6%82%E4%B8%8B%EF%BC%9A

CERTS

JSON对象，用于配置TLS证书和CA，支持以下键：

• client.ca.cert.pem：PostgreSQL ssl_ca_file参数的PEM内容，启用客户端证书认证（最安全的远程认证方式），客户端需使用此CA签名的证书。
• server.cert.pem：PostgreSQL ssl_cert_file参数的PEM内容，服务器身份标识及加密连接证书。
• server.key.pem：PostgreSQL ssl_key_file参数的PEM内容，服务器私钥。

注意：server.cert.pem与server.key.pem需同时提供以启用TLS；使用client.ca.cert.pem时也需同时提供服务器证书和密钥。
安全建议：优先通过挂载文件（/etc/postgres/client.ca.cert.pem、/etc/postgres/server.cert.pem、/etc/postgres/server.key.pem）传递证书，而非环境变量。

CONF_EXTRA

追加到生成的postgres.conf文件末尾的字符串，用于添加额外的PostgreSQL配置参数（如性能调优参数）。

LAN连接配置（Docker网络内）

• LAN_AUTH_METHOD：LAN连接的认证方法（如trust、password、cert）。
• LAN_CONNECTION：允许的LAN连接类型。
• LAN_DATABASES：JSON数组，允许从LAN访问的数据库名称（如["db1", "db2"]）。
• LAN_HBA_TPL：pg_hba.conf中LAN规则的模板，支持占位符（具体占位符见Dockerfile）。
• LAN_TLS：是否为LAN连接启用TLS（true/false）。
• LAN_USERS：JSON数组，允许从LAN访问的用户（如["user1", "user2"]）。

WAN连接配置（外部网络）

• WAN_AUTH_METHOD：WAN连接的认证方法。
• WAN_CONNECTION：允许的WAN连接类型（若设为hostssl，需配合TLS证书生效）。
• WAN_DATABASES：JSON数组，允许从WAN访问的数据库名称。
• WAN_HBA_TPL：pg_hba.conf中WAN规则的模板，支持占位符（具体占位符见Dockerfile）。
• WAN_TLS：是否为WAN连接启用TLS（true/false）。
• WAN_USERS：JSON数组，允许从WAN访问的用户。

注意事项

• 镜像不验证配置有效性，需自行确保配置正确：
  • 未提供client.ca.cert.pem时，不要使用cert认证方式。
  • 未提供server.cert.pem和server.key.pem时，不要启用TLS。
  • 避免在未加密情况下暴露端口。
  • 不使用证书认证时，需为用户设置强密码。

部署示例

基本启动（默认配置）

bash
docker run -d --name postgres-autoconf tecnativa/postgres-autoconf

带LAN/WAN隔离与TLS的配置示例

允许LAN用户lan_user访问lan_db（trust认证），WAN用户wan_user通过password认证访问wan_db，并启用TLS：

bash
docker run -d \
  --name postgres-autoconf \
  -e LAN_USERS='["lan_user"]' \
  -e LAN_DATABASES='["lan_db"]' \
  -e LAN_AUTH_METHOD=trust \
  -e WAN_USERS='["wan_user"]' \
  -e WAN_DATABASES='["wan_db"]' \
  -e WAN_AUTH_METHOD=password \
  -e CERTS='{"server.cert.pem":"-----BEGIN CERTIFICATE...","server.key.pem":"-----BEGIN PRIVATE KEY..."}' \
  tecnativa/postgres-autoconf

注：实际部署时需将CERTS值替换为有效的PEM格式证书内容。