Docker Compose部署PostgreSQL时psql密码认证失败求助

Docker Compose配置文件（compose.yaml） #

name: postgres-container
services:
  database:
    image: postgres
    restart: always
    environment:
      - POSTGRES_PASSWORD
    // OR POSTGRES_PASSWORD = ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

连接报错信息 #

执行psql -h localhost -U postgres输入对应密码后，报错：

psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL:  password authentication failed for user "postgres"

connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL:  password authentication failed for user "postgres"

.env文件内容 #

# When adding additional env variables, the schema in /env/schema.mjs should be updated accordingly

# Prisma
DATABASE_URL=postgres://postgres:postgres@localhost/crud?connect_timeout=10

# Next Auth
NEXTAUTH_SECRET=...
NEXTAUTH_URL=http://localhost:3000

# Next Auth Google Provider
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# Next Auth Discord Provider
DISCORD_CLIENT_ID=...
DISCORD_CLIENT_SECRET=...

# PostgreSQL Auth
POSTGRES_PASSWORD=postgres

已尝试的操作 #

• 删除存储数据的卷
• 删除运行的容器
• 删除PostgreSQL镜像

docker compose convert验证结果 #

执行命令后显示环境变量已正确注入：

name: postgres-container
services:
  database:
    environment:
      POSTGRES_PASSWORD: postgres
    image: postgres
    networks:
      default: null
    restart: always
    volumes:
    - type: volume
      source: pgdata
      target: /var/lib/postgresql/data
      volume: {}
networks:
  default:
    name: postgres-container_default
volumes:
  pgdata:
    name: postgres-container_pgdata

问题 #

请问该如何解决此问题？

排查与解决步骤 #

1. 修复Compose文件的注释语法错误
   YAML不支持//风格注释，你的配置里这行注释会导致语法解析异常，虽然convert命令显示变量正常，但实际启动时可能出问题。改成YAML标准的#注释：

name: postgres-container
services:
  database:
    image: postgres
    restart: always
    environment:
      - POSTGRES_PASSWORD
    # OR POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

2. 添加端口映射
   你的配置没把容器的5432端口暴露到宿主机，存在连接目标错误的可能，补充端口映射：

services:
  database:
    # ... 其他配置
    ports:
      - "5432:5432"

3. 彻底重置所有资源
   执行命令完全清除相关容器、卷和镜像，避免旧数据残留：

docker compose down -v --rmi all

之后重新启动服务：

docker compose up -d

4. 在容器内部验证密码
   直接进入容器用psql连接，确认密码是否生效：

docker exec -it postgres-container-database-1 psql -U postgres

如果能成功连接，说明宿主机连接时可能有端口冲突或本地服务干扰。

5. 检查宿主机端口占用
   执行lsof -i :5432查看5432端口是否被本地PostgreSQL服务占用，如果是，停止本地服务后再尝试连接。

6. 修改环境变量写法
   把环境变量从数组形式改成键值对形式，避免潜在解析问题：

environment:
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

内容的提问来源于stack exchange，提问作者fisherbone