容器与云原生 / 系统课时
接入数据库容器
接入数据库容器
把数据库放进容器并不只是“启动一个 PostgreSQL 镜像”。要想让数据可保留、首次启动可自动建表、应用能判断数据库是否就绪,至少要同时处理环境变量、命名卷、初始化脚本和健康检查。本节以 PostgreSQL 为例完成一套可验证的本地开发配置。
学习目标
- 配置 PostgreSQL 初始化所需的账号、密码和数据库名
- 使用命名卷保存数据库数据,并理解初始化脚本的触发条件
- 通过健康检查和
psql验证数据库真正可用
准备数据库配置与初始化脚本
建立 compose.yaml,再创建 db/init/001_schema.sql。数据库密码通过 ${POSTGRES_PASSWORD} 注入,不写死在 Compose 文件中;POSTGRES_USER 和 POSTGRES_DB 则定义首次初始化时要创建的角色和数据库。
compose.yaml 内容如下:
services:
db:
image: postgres:17-alpine
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: appdb
volumes:
- postgres-data:/var/lib/postgresql/data
- ./db/init:/docker-entrypoint-initdb.d:ro
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
interval: 5s
timeout: 3s
retries: 10
start_period: 5s
volumes:
postgres-data:db/init/001_schema.sql 使用一条简单建表语句验证初始化链路:
CREATE TABLE IF NOT EXISTS app_note (
id BIGSERIAL PRIMARY KEY,
body TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);挂载到 /docker-entrypoint-initdb.d 的脚本只会在 PostgreSQL 初始化空数据目录时执行。后续即使修改 SQL 文件并重启容器,只要 postgres-data 仍然已有数据,入口脚本就不会再次自动执行。

启动数据库并观察健康状态
在包含 compose.yaml 的目录执行下面的命令。这里的密码只用于本地演示,实际项目应由安全的环境变量或密钥管理机制提供。
POSTGRES_PASSWORD=dev-only docker compose up -d db
docker compose ps db预期输出
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
<NAME> postgres:17-alpine "docker-entrypoint..." db <TIME> ago Up <TIME> (healthy) 5432/tcp容器名和时间会因项目目录与启动时间不同而变化,因此用 <NAME>、<TIME> 表示动态值。关键是 STATUS 最终出现 healthy;如果长期停留在 starting 或变为 unhealthy,应先查看数据库日志和健康检查命令。
验证初始化结果
数据库健康后,直接在容器中调用 psql 查询表清单。这样能同时验证容器运行、账号配置、数据库名称和初始化脚本四个环节。
docker compose exec db psql -U app -d appdb -c '\dt'预期输出
List of relations
Schema | Name | Type | Owner
--------+----------+-------+-------
public | app_note | table | app
(<N> row)<N> 表示实际返回行数。只要能看到 app_note,就说明首次初始化脚本已经执行。若提示数据库或角色不存在,优先检查环境变量;若连接成功但没有表,则检查脚本挂载路径以及该命名卷是否早已完成过初始化。
理解数据卷与“重新初始化”
停止并删除容器不会自动删除命名卷,因此下面的操作可以安全地重建数据库容器而保留数据:
docker compose down
POSTGRES_PASSWORD=dev-only docker compose up -d db预期结果
数据库容器会被重新创建,但 postgres-data 命名卷继续复用;已有 app_note 表仍然存在,初始化脚本不会再次执行。如果你明确要清空本地实验数据并重新执行初始化脚本,可以删除 Compose 项目的卷后再启动。但该操作会永久删除卷中的数据库内容,只适用于确认可丢弃的数据。
docker compose down -v
POSTGRES_PASSWORD=dev-only docker compose up -d db预期结果
旧的 postgres-data 卷被删除;下一次启动会创建空数据目录,并重新执行 /docker-entrypoint-initdb.d 中的初始化脚本。健康检查解决的不是数据迁移
pg_isready 只能证明 PostgreSQL 已经接受连接,不能证明所有业务表、迁移版本或种子数据都符合应用要求。接入真实应用时,数据库迁移应由专门的迁移工具或一次性任务管理,应用启动逻辑也应能处理短暂连接失败。
完成接入后,应把验收标准保持在三个层面:容器状态为 healthy,命名卷在重建容器后仍保留数据,业务需要的表结构可通过数据库查询确认。这样数据库容器才从“能启动”变成“可重复使用、可验证、可恢复”的基础服务。