如何为Docker 25.0.X环境下的Postgres 16.X设置密码？

问题背景 #

使用Docker Compose部署最新版PostgreSQL 16.2时，通过VPS公网IP连接数据库，输入配置的密码却始终提示认证失败，错误信息如下：

Example-Production-Database     | 2024-04-07 01:08:24.202 UTC [93] FATAL:  password authentication failed for user "postgres"
Example-Production-Database     | 2024-04-07 01:08:24.202 UTC [93] DETAIL:  Connection matched file "/var/lib/postgresql/data/pg_hba.conf" line 128: "host all all all scram-sha-256"

环境与配置信息 #

• Docker版本：Docker Engine - Community 25.0.4
• PostgreSQL镜像版本：16.2（2024年4月最新版）

docker-compose.yaml

version: "3.5"

services:
  Database:
    image: postgres
    container_name: Example-Production-Database
    ports: [ "${DATABASE_PORT}:${DATABASE_PORT}" ]
    environment:
      - POSTGRES_PASSWORD=${DATABASE_PASSWORD}
    volumes:
      - DatabaseData:/data/example.jp

volumes:
  DatabaseData: {}

.env文件

DATABASE_ENVIRONMENT_NAME="STAGING"
DATABASE_HOST="Database"
DATABASE_PORT="5432"
DATABASE_USER_NAME="postgres"
DATABASE_PASSWORD="ACTUAL_PASSWORD"

启动命令

sudo docker compose up --build

解决方法 #

1. 去掉.env变量的引号 #

Docker Compose会把.env文件里变量值的引号也当作内容的一部分，导致传递给PostgreSQL的密码是"ACTUAL_PASSWORD"（包含双引号），而非预期的ACTUAL_PASSWORD。修改.env文件，所有变量值去掉引号：

DATABASE_ENVIRONMENT_NAME=STAGING
DATABASE_HOST=Database
DATABASE_PORT=5432
DATABASE_USER_NAME=postgres
DATABASE_PASSWORD=ACTUAL_PASSWORD

2. 清理已初始化的数据库卷 #

PostgreSQL第一次启动时，会根据初始密码生成SCRAM认证哈希并保存到卷中。如果之前用错误的密码启动过容器，卷里的旧认证信息不会自动更新，后续修改密码也无效。执行以下步骤重置：

# 停止并删除容器
sudo docker compose down
# 删除对应的数据库卷（注意：此操作会丢失所有数据，需提前备份）
sudo docker volume rm Example-Production-Database_DatabaseData
# 重新启动容器，初始化新的数据库
sudo docker compose up --build

3. 验证连接参数 #

确保连接时使用的参数正确：

• 用户名：postgres
• 密码：修改后的ACTUAL_PASSWORD（无引号）
• 主机：VPS的公网IP
• 端口：5432

4. 客户端SCRAM兼容性检查（可选） #

错误提示中使用的scram-sha-256是PostgreSQL 10+的默认认证方式，较旧的客户端可能不支持。如果前三个步骤都无效，检查你的数据库客户端版本，升级到支持SCRAM的版本即可。

内容的提问来源于stack exchange，提问作者Takeshi Tokugawa YD