Knative Bookstore 实战(第 5 步):用 StatefulSet 在 Kubernetes 上部署 PostgreSQL 数据库服务
Knative Bookstore 实战(第 5 步):用 StatefulSet 在 Kubernetes 上部署 PostgreSQL 数据库服务
在 Knative Bookstore 端到端示例应用中,数据库服务是整个事件驱动架构的"数据底座":前端收集用户评论、事件链经过 Broker 与机器学习流水线处理后,最终由数据库完成持久化存储。本教程对应仓库中的 deploy-database-service.md(Bookstore 教程第 5 页),将带你在 Kubernetes 上以一个 PostgreSQL StatefulSet 完成数据库的部署与初始化,并通过真实配置文件与源码,理解"为什么数据库不用 Knative Service,而要用 StatefulSet"这一关键技术取舍。读完本文,你将能独立部署一个带持久化存储、含示例数据的 PostgreSQL 服务,并把它接入书店前端。
本节学习目标与最终交付物
在开始动手前,先明确两个问题:
本节要学习的 Knative 特性:
- 什么样的业务场景适合使用 Knative Service(无状态、事件驱动、可缩容至零);
- 反过来,什么样的工作负载不适合 Knative Service,而应交给 Kubernetes 原生控制器(如 StatefulSet)。
最终交付物:
- 一个运行中的 PostgreSQL StatefulSet,其中包含
book_reviews评论表及 4 条示例数据,可供书店应用读写用户评论。
该示例应用的整体架构可参考 Bookstore 教程开篇 与 示例应用 README:书店前端(Next.js)负责展示,Node.js 服务(node-server)负责事件转发与数据库读写,评论数据最终落在本节部署的 PostgreSQL 中。
概念铺垫:什么样的场景才该用 Knative Service?
Knative Service 是 Knative 生态中最强大的特性之一,它由 Knative Serving 控制,能够自动扩缩容、甚至缩容到 0 个副本。在现代云原生应用中,它适合两类典型工作负载:
无状态工作负载(Stateless Workloads)
- 定义:应用不会在本地保存任何请求间的数据,每次请求相互独立,不依赖之前的交互。
- 适用场景:Web 服务器、API、微服务等——这类应用的状态由外部管理(例如存放在数据库或缓存中)。
- 收益:由于任何实例都能处理任何请求、无需会话持久化,扩展与故障切换都非常简单。
事件驱动工作负载(Event-Driven Workloads)
- 定义:事件驱动架构响应事件或 Trigger 而运行,例如 HTTP 请求、队列中的消息或数据库中的变更。
- 适用场景:用 Knative Service 部署响应事件的函数,如处理流入的数据、触发工作流、对接第三方 API。
- 收益:资源利用率极高——不处理事件时服务可以缩容到零,从而降低成本并提升整体效率。
数据库为什么不用 Knative Service?
这是本教程最核心的一个技术判断。数据库是典型的有状态、长连接工作负载,不适合 Knative Service,原因有三:
- 数据必须持久化:数据库需要把数据永远记住。StatefulSet 能绑定稳定的存储卷与稳定的网络标识(Pod 名、Service 名不随重建变化),而 Knative Service 的 Pod 生命周期是"用完即弃"的,缩容到零再拉起时实例会重建。
- 协议不是 HTTP:Knative Service 天生擅长处理 HTTP 流量与 CloudEvent,而数据库客户端(如
psql、PostgreSQL 连接池)使用的是 PostgreSQL 原生协议(TCP 5432),并不适合直接由 Knative Serving 的流量层接管。 - 实例数不随流量抖动:数据库不能因为请求增多就随意横向扩缩,复制、数据一致性都需要专门机制,这超出了 Knative Service 的职责边界。
值得补充的是:Knative Service 本身也支持挂载卷与持久卷(Volume / PersistentVolume),如果你确实有基于 Knative Service 存储数据的特殊场景,也可以为它配置存储卷。但从 Bookstore 示例的架构意图看,数据库选择 Kubernetes 原生 StatefulSet 是最贴合"事件驱动 + 有状态底座"组合的落地方案。
动手实现:一次 apply 全部数据库配置
本节对应的全部 YAML 文件已经为你准备就绪,位于仓库的 solution/db-service 目录下。你只需要进入该目录(即 code-samples 的 db-service 子目录),一次性应用所有配置:
kubectl apply -f db-service
文件名前缀的数字决定了资源创建的先后顺序:
100-先建依赖的基础资源(ConfigMap / Secret / PVC),200-建 StatefulSet,300-建 Service,400-最后跑初始化 Job,确保 PostgreSQL 就绪后才会灌入示例数据。
六个配置文件逐个拆解
该目录下共 6 个 YAML(另有 sample.sql 与 README.md),各自职责如下:
| 文件 | 资源类型 | 职责 |
|---|---|---|
| 100-create-configmap.yaml | ConfigMap | 存放数据库初始化 SQL 文件 sample.sql |
| 100-create-secret.yaml | Secret | 保存 PostgreSQL 的库名、用户名、密码 |
| 100-create-volume.yaml | PersistentVolumeClaim | 为数据库申请持久化存储(1Gi,ReadWriteOnce) |
| 200-create-postgre.yaml | StatefulSet | 创建 PostgreSQL 数据库实例 |
| 300-expose-service.yaml | Service(Headless) | 在集群内暴露 PostgreSQL,供应用与 Job 访问 |
| 400-create-job.yaml | Job | 执行 SQL 初始化,创建表并灌入示例数据 |
从配置源码看实现细节
① 凭据由 Secret 管理,避免明文入库。 100-create-secret.yaml 中的 data 字段是 Base64 编码:
POSTGRES_DB: bXlkYXRhYmFzZQ== # 解码后为 mydatabase
POSTGRES_USER: bXl1c2Vy # 解码后为 myuser
POSTGRES_PASSWORD: bXlwYXNzd29yZA== # 解码后为 mypassword
② StatefulSet 从 Secret 注入环境变量。 200-create-postgre.yaml 中,POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD 三个环境变量全部通过 secretKeyRef 引用上面的 postgresql-secret,镜像使用 quay.io/enterprisedb/postgresql,容器端口 5432,并将持久卷挂载到 PostgreSQL 数据目录 /var/lib/postgresql/data:
env:
- name: POSTGRES_DB
valueFrom:
secretKeyRef:
name: postgresql-secret
key: POSTGRES_DB
# ... 同理会注入 POSTGRES_USER 与 POSTGRES_PASSWORD
volumeMounts:
- name: postgresql-storage
mountPath: /var/lib/postgresql/data
volumes:
- name: postgresql-storage
persistentVolumeClaim:
claimName: postgresql-pvc
③ 持久化由 PVC 保证。 100-create-volume.yaml 申请 1Gi 的 ReadWriteOnce 存储,即使 Pod 被重建,数据也不会丢失——这正是数据库选择 StatefulSet 而非 Knative Service 的关键原因之一。
④ Headless Service 提供稳定访问地址。 300-expose-service.yaml 设置了 clusterIP: None,这是一个 Headless Service:集群内通过 postgresql 这个服务名即可访问数据库 Pod,且名称不会随 Pod 重建而改变:
spec:
selector:
app: postgresql
ports:
- port: 5432
targetPort: 5432
clusterIP: None
Node.js 后端正是通过完整 DNS 名 postgresql.default.svc.cluster.local 连接数据库(见 node-server/index.js),构建连接池并执行评论读写。
⑤ 初始化 Job 灌入示例数据。 400-create-job.yaml 启动一个一次性客户端容器,用 psql 命令连接 postgresql 服务并执行挂载在 /sql 下的初始化脚本;PGPASSWORD、PGUSER、PGDATABASE 同样从 Secret 读取,restartPolicy: Never 表示失败不自动重启 Pod,backoffLimit: 5 控制重试上限,ttlSecondsAfterFinished: 50 让完成后的 Job 在 50 秒后自动清理:
command: ["psql", "-h", "postgresql", "-U", "myuser", "-d", "mydatabase", "-f", "/sql/sample.sql"]
预期的 apply 输出
配置全部应用成功后,你会看到类似输出:
configmap/sql-configmap created
secret/postgresql-secret created
persistentvolumeclaim/postgresql-pvc created
statefulset.apps/postgresql created
service/postgresql created
job.batch/postgresql-job created
!!! warning "耐心等待"
请等待几分钟直到所有资源就绪。如果看到部分 Job Pod 报错,这属于正常现象,继续等待即可——Kubernetes 会按 backoffLimit 自动重试,直到至少一个初始化 Job 变为 Completed。
数据库初始化:表结构与示例数据
初始化脚本保存在 db-service/sample.sql,同时以 ConfigMap 形式内嵌在 100-create-configmap.yaml 中。它定义了书店评论表 book_reviews 的完整结构:
| 列名 | 类型 | 说明 |
|---|---|---|
id |
SERIAL | 主键,自增 |
post_time |
timestamp NOT NULL | 评论发布时间 |
content |
TEXT NOT NULL | 评论内容 |
sentiment |
TEXT | 情感分析结果,受 CHECK 约束,取值仅限 positive / negative / neutral |
建表语句同时通过 CONSTRAINT sentiment_check CHECK (sentiment IN ('positive', 'negative', 'neutral')) 在数据库层面保证了情感标签的合法取值范围,与教程第 2 步部署的情感分析服务输出保持一致。
初始化时还会灌入 4 条示例评论,用于前端首次打开页面时直接展示:
| id | post_time | content | sentiment |
|---|---|---|---|
| 1 | 2020-01-01 00:00:00 | This book is great! | positive |
| 2 | 2020-01-02 00:02:00 | This book is terrible! | negative |
| 3 | 2020-01-03 00:01:30 | This book is okay. | neutral |
| 4 | 2020-01-04 00:00:00 | Meh | neutral |
验证部署状态
检查 Pod 与 Job 状态
等待片刻后执行 kubectl get pods,理想状态下应看到:postgresql-0 为 Running,至少一个 postgresql-job-* 为 Completed(另一个 Error 的失败 Job 可以忽略,它是重试机制的正常体现):
NAME READY STATUS RESTARTS AGE
bookstore-frontend-7b879ffb78-9bln6 1/1 Running 0 6h53m
camel-k-operator-7989475884-7wk6z 1/1 Running 0 5h26m
event-display-55967c745d-bxrgh 1/1 Running 0 5h26m
node-server-644795d698-r9zlr 1/1 Running 0 5h26m
postgresql-0 1/1 Running 0 5h23m
postgresql-job-55dlv 0/1 Completed 0 10s
postgresql-job-fnv8m 0/1 Error 0 73s
进入 Pod 用 psql 复核数据
确认 postgresql-0 处于 Running 状态后,可以进入容器做更底层的验证:
kubectl exec -it postgresql-0 -- /bin/bash
psql -U myuser -d mydatabase
连接成功后会看到提示符 mydatabase=#。执行 \dt 查看表清单,若出现 book_reviews 表,说明数据库已正确初始化:
List of relations
Schema | Name | Type | Owner
--------+--------------+-------+--------
public | book_reviews | table | myuser
(1 row)
前端 UI 验证:评论出现在页面底部
数据库就绪后,最后通过书店前端做端到端验证。先获取前端服务的公网 IP:
kubectl get svc -o=jsonpath='{.status.loadBalancer.ingress[0].ip}' bookstore-frontend-svc
在浏览器打开 http://${IP},你应该能看到页面底部不断弹出新的评论——这些评论来自数据库中的示例数据,由 Node.js 后端通过 WebSocket 定时(每秒)查询 book_reviews 表并推送给前端(实现细节见 node-server/index.js 中的 /comments WebSocket 端点与 SELECT * FROM book_reviews ORDER BY post_time DESC; 查询)。前端服务的类型是 LoadBalancer,其部署清单位于 frontend/config/100-front-end-deployment.yaml。
故障排查
???+ bug "页面显示 'No comments available'"
这说明数据库尚未初始化完成。请检查数据库相关 Pod 的健康状态,确认 postgresql-0 是否 Running、初始化 Job 是否最终 Completed,定位失败原因后重试。常见情况是:kubectl apply -f db-service 执行后立即刷新页面,此时 Job 还在初始化中,等待片刻再刷新即可。
小结与下一步
至此,你已经完成了 Bookstore 示例应用中数据库服务(Database Service)的部署:
- 用 StatefulSet + PVC 部署了带持久化存储的 PostgreSQL,数据不随 Pod 重建而丢失;
- 用 Secret 管理数据库凭据,用 ConfigMap 存放初始化 SQL;
- 用 Job 完成了表结构与示例数据的初始化;
- 通过前端 UI 验证了评论数据能够正常展示。
同时你也理解了核心概念:有状态、非 HTTP 协议的数据库工作负载应交给 Kubernetes 原生控制器(StatefulSet),而 Knative Service 更适合无状态、事件驱动的 HTTP 工作负载,并可通过缩容到零节省成本。
数据库已经准备好接收请求并存储用户评论。下一步,我们将把前面创建的所有组件连接起来,完成整个事件驱动架构的收尾——这正是整个示例"发生魔法"的地方:


