Knative Bookstore 实战(第 5 步):用 StatefulSet 在 Kubernetes 上部署 PostgreSQL 数据库服务

原创2026-10-14 09:03:271,373 阅读
文章标签:文档教程云原生

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 中。

Bookstore 教程第 5 页:数据库服务部署章节的图示

概念铺垫:什么样的场景才该用 Knative Service?

Knative Service 是 Knative 生态中最强大的特性之一,它由 Knative Serving 控制,能够自动扩缩容、甚至缩容到 0 个副本。在现代云原生应用中,它适合两类典型工作负载:

无状态工作负载(Stateless Workloads)

  • 定义:应用不会在本地保存任何请求间的数据,每次请求相互独立,不依赖之前的交互。
  • 适用场景:Web 服务器、API、微服务等——这类应用的状态由外部管理(例如存放在数据库或缓存中)。
  • 收益:由于任何实例都能处理任何请求、无需会话持久化,扩展与故障切换都非常简单。

事件驱动工作负载(Event-Driven Workloads)

  • 定义:事件驱动架构响应事件或 Trigger 而运行,例如 HTTP 请求、队列中的消息或数据库中的变更。
  • 适用场景:用 Knative Service 部署响应事件的函数,如处理流入的数据、触发工作流、对接第三方 API。
  • 收益:资源利用率极高——不处理事件时服务可以缩容到零,从而降低成本并提升整体效率。

Knative Service 概念示意图

数据库为什么不用 Knative Service?

这是本教程最核心的一个技术判断。数据库是典型的有状态、长连接工作负载,不适合 Knative Service,原因有三:

  1. 数据必须持久化:数据库需要把数据永远记住。StatefulSet 能绑定稳定的存储卷与稳定的网络标识(Pod 名、Service 名不随重建变化),而 Knative Service 的 Pod 生命周期是"用完即弃"的,缩容到零再拉起时实例会重建。
  2. 协议不是 HTTP:Knative Service 天生擅长处理 HTTP 流量与 CloudEvent,而数据库客户端(如 psql、PostgreSQL 连接池)使用的是 PostgreSQL 原生协议(TCP 5432),并不适合直接由 Knative Serving 的流量层接管。
  3. 实例数不随流量抖动:数据库不能因为请求增多就随意横向扩缩,复制、数据一致性都需要专门机制,这超出了 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。

kubectl apply 部署数据库服务配置后的输出示意图

数据库初始化:表结构与示例数据

初始化脚本保存在 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 工作负载,并可通过缩容到零节省成本。

数据库已经准备好接收请求并存储用户评论。下一步,我们将把前面创建的所有组件连接起来,完成整个事件驱动架构的收尾——这正是整个示例"发生魔法"的地方:

继续学习:实现高级事件过滤(Advanced Event Filtering)

登录后查看全文
docs