如何从容器外部连接 Docker 里运行的 PostgreSQL？

核心步骤：启动容器时映射端口 docker run -d -p 127.0.0.1:5432:5432 -e POSTGRES_PASSWORD --name pg postgres:16，之后外部用任意 PostgreSQL 客户端连接：psql -h 127.0.0.1 -p 5432 -U postgres -d postgres。宿主访问需可达端口与正确认证；密码变量用于首次初始化，已初始化数据目录不会因修改变量更新密码。

完整示例

docker run -d \
  --name pg \
  -p 127.0.0.1:5432:5432 \
  -e POSTGRES_PASSWORD \
  -e POSTGRES_DB=mydb \
  -v pg-data:/var/lib/postgresql/data \
  postgres:16

• -p 127.0.0.1:5432:5432：宿主回环 5432 → 容器 5432（宿主 5432 被占用就换 -p 127.0.0.1:15432:5432）
• 启动前通过安全方式设置并导出 POSTGRES_PASSWORD；标准密码认证下首次初始化需要它（或受支持的_FILE方式），已有数据库不依赖它重设密码
• -v pg-data:...：数据卷持久化，官方镜像可能创建匿名卷，不是删除容器必然删除数据；命名卷更便于明确管理。本文postgres:16挂载路径不直接适用于18+的新目录布局

从外部连接

# 本机
psql -h 127.0.0.1 -p 5432 -U postgres -d mydb

# 若需局域网访问，先显式发布到受控宿主地址并放行相应网络
psql -h 192.168.1.10 -p 5432 -U postgres -d mydb

应用连接串：使用机密配置提供连接凭据，不把真实密码写入文档或代码

容器间连接（另一回事）

另一个容器要连它，不用映射端口，接到同一网络用容器名：

docker network create appnet
docker network connect appnet pg  # 将前面已有容器接入，勿重复创建同名容器
docker run -d --name app --network appnet -e DB_HOST=pg myapp

应用里连 pg:5432（Docker 内置 DNS 解析容器名）。

常见问题排查

1. 连不上（connection refused）：确认容器在跑（docker ps）、端口映射存在（docker port pg）。
2. 认证失败：首次初始化使用 POSTGRES_PASSWORD，之后数据库角色密码可能已更改；修改环境变量对已初始化的数据卷无效（密码在首次初始化时写入，应通过授权数据库会话修改角色密码，不要为重设密码清空数据卷）。
3. 能 TCP 连但报 no pg_hba.conf entry：默认配置对映射场景一般没问题；改过配置的话检查容器内 pg_hba.conf 的 host 规则。

业务连接恢复后，如需持续查看数据库状态，可按观测云 PostgreSQL 集成为 DataKit 配置独立监控账号，并使用从采集器所在网络可达的地址。先确认连接与事务等指标上报，再配置告警；应用能访问数据库，不代表采集器使用的地址和权限也正确。

常见问题（FAQ）

Q：生产环境能把数据库跑在 Docker 里吗？
A：可以，但务必挂卷、配备份、评估高可用方案；不少团队生产库仍选云 RDS 或独立部署。

Q：改配置（如 max_connections）怎么生效？
A：启动命令追加参数：postgres:16 -c max_connections=200，或挂载自定义 postgresql.conf。

Q：端口映射后宿主机 5432 被占用冲突？
A：换宿主端口 -p 15432:5432，连接时对应改 -p 参数。