ljwx-harbor/docs/k8s-shared-data-plane.md

Kubernetes 共享数据平面方案（仅文档，禁止直接实施）

目的：在同一集群内为多个项目（bookstore、stock、words、gmc_new …）提供可复用的 PostgreSQL、MySQL、Redis 与监控能力。本文是设计与约束，不可直接 apply。后续实施由任务契约驱动（见文末"Claude 执行契约"）。

1. 命名与分层

1.1 命名空间（Namespaces）

• platform-monitoring：Prometheus、Grafana、Loki、exporters
• shared-data：共享数据库与缓存实例（PostgreSQL、MySQL、Redis）
• app-bookstore、app-stock、app-words、app-gmc-new：各业务命名空间
• shared-ingress（可选）：统一 Ingress/Nginx/Cert-Manager

原则：平台能力在 platform-，共享状态在 shared-，业务在 app-*。

1.2 资源与标注（Labels/Annotations）

• 统一标签：app.kubernetes.io/part-of、app.kubernetes.io/component、cost-center、owner
• 资源配额模板（示例目标）：
  • platform-monitoring：CPU 8、Mem 16Gi、PVC 200Gi
  • shared-data：CPU 16、Mem 64Gi、PVC 2Ti（按需求调整）
  • 业务命名空间：按项目评估（配额与 LimitRange 必配）

2. 多租户模型（强约束）

2.1 PostgreSQL（推荐 Crunchy/Bitnami 任一）

• 租户模式优先级
  1. 同一 PG 集群、每项目一个数据库（推荐，安全/隔离/维护平衡）
  2. 同库多 schema（适合轻量 PoC）
  3. 独立 PG 集群（重度负载或合规隔离）
• 连接标识：postgresql.shared-data.svc.cluster.local:5432
• 凭据：每项目最小权限专用用户：<project>_app，只授予对应 DB
• 网络：仅对 app-* 命名空间开放（NetworkPolicy）

2.2 MySQL

• 场景较少时优先集中单集群 + 逐项目 DB
• 连接：mysql.shared-data.svc.cluster.local:3306
• 账户：<project>_app

2.3 Redis（Bitnami，哨兵或 cluster 选其一）

• 共享 Redis + 多实例：不建议依赖 Redis "逻辑 DB index" 做多租户
• 每项目一个独立 Release/实例或共享大实例中的独立命名前缀（强烈建议独立实例）
• 连接：redis-<project>.shared-data.svc.cluster.local:6379
• RDB+AOF 开启；持久化 PVC

3. 访问与服务发现（不暴露公网）

• 数据库/Redis 不走 Ingress，仅 ClusterIP/Headless
• 统一的 Service DNS：
  • postgresql.shared-data.svc.cluster.local
  • mysql.shared-data.svc.cluster.local
  • redis-<project>.shared-data.svc.cluster.local
• 业务侧通过 ConfigMap+Secret 注入连接（不写死 IP）

3.1 连接约定（示例）

# app-<project>/Deployment env（只示例键名约定）
env:
  - name: DB_HOST
    value: postgresql.shared-data.svc.cluster.local
  - name: DB_NAME
    valueFrom: configMapKeyRef: { name: db-conn, key: DB_NAME }
  - name: DB_USER
    valueFrom: secretKeyRef: { name: db-cred, key: username }
  - name: DB_PASS
    valueFrom: secretKeyRef: { name: db-cred, key: password }
  - name: REDIS_HOST
    value: redis-<project>.shared-data.svc.cluster.local

4. 安全与合规

• Secrets 管理：
  • 开发环境：K8s Secret + SealedSecrets/SOPS（二选一）
  • 严禁把明文凭据提交到 Git
• RBAC：
  • shared-data 仅平台 SRE 拥有管理权限
  • 各 app-* 只能读取本命名空间内的 Config/Secret
• NetworkPolicy：
  • shared-data 默认 deny all
  • 仅允许来自 app-* 命名空间的到端口 5432/3306/6379 流量
• 审计：数据库登录与 DDL/DML 审计表（PG 可用 pgaudit）

5. 备份与恢复（必须有演练）

• PostgreSQL：pgBackRest / WAL 连续备份 + 每日全量；按环境分 Bucket/路径
• MySQL：xtrabackup 或 mysqldump 定期
• Redis：RDB 定时 + AOF 持久化；跨盘快照
• 季度恢复演练：记录 RTO/RPO
• 备份状态上报到 Prometheus（失败告警）

6. 监控与告警

• platform-monitoring 部署 kube-prometheus-stack（或轻量 Prometheus + Grafana + Loki）
• Exporters：
  • PG：postgres-exporter
  • MySQL：mysqld-exporter
  • Redis：redis-exporter
• Grafana 预置看板：
  • 数据库连接数/慢查询/复制延迟/WAL 速率
  • Redis 命中率/内存碎片率/RDB/AOF 状态
• 告警：连接耗尽、磁盘使用 > 80%、复制延迟、备份失败

7. Helm/Operator 选型建议（仅策略）

• Postgres：Crunchy Operator（企业级特性丰富）或 Bitnami（简洁稳）
• MySQL：Bitnami Chart（更轻）或 Percona Operator（更强）
• Redis：Bitnami Redis（Cluster/Sentinel 任选其一）

选型落地由任务契约决定，不在本文中创建任何 Release。

8. 业务项目接入流程（GitOps）

1. 申请表/CR（放仓库 infra/tenants/<project>.yaml）
   • 需求：DB 类型/容量/读写 QPS、备份级别、数据合规标签
2. 生成：数据库/用户/权限/配额申请 PR
3. 平台审核并合入 → 由 CI 触发 Helm/Operator 执行
4. 业务获取 ConfigMap + Secret（仅读本项目所需）
5. 上线前检查：连接可用性、限流策略、告警绑定

9. 可复用的"实施占位模板"（供后续任务使用）

以下清单仅示例结构与参数命名，不能直接 apply。

9.1 命名空间（只文档示例）

apiVersion: v1
kind: Namespace
metadata:
  name: shared-data
  labels:
    app.kubernetes.io/part-of: data-plane
    owner: sre

9.2 NetworkPolicy（仅允许 app-* 访问 DB 端口）

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-app-to-pg
  namespace: shared-data
spec:
  podSelector:
    matchLabels:
      app: postgresql
  policyTypes: [Ingress]
  ingress:
    - from:
        - namespaceSelector:
            matchExpressions:
              - { key: name, operator: In, values: ["app-bookstore","app-stock","app-words","app-gmc-new"] }
      ports:
        - protocol: TCP
          port: 5432

9.3 业务侧连接对象（模板占位）

apiVersion: v1
kind: ConfigMap
metadata:
  name: db-conn
  namespace: app-<project>
data:
  DB_NAME: "<project>"
---
apiVersion: v1
kind: Secret
metadata:
  name: db-cred
  namespace: app-<project>
type: Opaque
stringData:
  username: "<project>_app"
  password: "<autogenerated-by-platform>"

10. SLO/容量基线（起点，实施时再细化）

• PG：p95 查询 < 50ms（关键 OLTP）、连接 > 20% 余量、WAL 可用空间 > 30%
• Redis：命中率 > 90%、内存使用 < 70%、RDB 成功率 100%
• 备份：RPO ≤ 1h、RTO ≤ 4h
• 告警响应：P1 ≤ 15m

11. Claude 执行契约（让 Claude 容易实施）

注意：下面是"任务契约模板"，不是实施指令。把它放到 /docs/contracts/，后续每个任务用一份拷贝，Claude 只能在白名单输出里生成 Helm values/清单草案，不得 apply。

11.1 合同模板：建立共享 PostgreSQL（设计产物）

id: SD-PG-BASE
title: 共享 PostgreSQL 设计与占位清单
scope:
  - 生成 Helm values 草案（Crunchy 或 Bitnami 二选一，列出 pros/cons）
  - 生成 NetworkPolicy 草案（仅示例，禁止生产）
  - 生成 租户 DB 创建 SQL 模板（create database / create role）
artifacts-allowlist:
  - docs/artifacts/postgres/values.example.yaml
  - docs/artifacts/postgres/networkpolicy.example.yaml
  - docs/artifacts/postgres/tenant.sql
acceptance:
  - 不包含 kubectl/helm apply 命令
  - values 以占位符形式（<env>, <storageClass>, <cpu/mem>）
  - SQL 模板仅示例最小权限
notes: "严禁生成可执行命令；仅文档、示例、占位符。"

11.2 合同模板：业务接入（bookstore）

id: SD-ONBOARD-BOOKSTORE
title: bookstore 接入共享数据平面（文档与清单）
scope:
  - 生成 app-bookstore 的 ConfigMap/Secret 占位清单
  - 指定连接 DNS 与端口、只读/读写账户差异
  - 生成最小联通性测试脚本（psql/redis-cli 示例命令，注释掉）
artifacts-allowlist:
  - docs/artifacts/bookstore/configmap.example.yaml
  - docs/artifacts/bookstore/secret.example.yaml
  - docs/artifacts/bookstore/connectivity-check.md
acceptance:
  - 不包含 apply；示例命令前必须带注释
  - Secret 仅示例键名，不给真实值
  - 连接测试包含期望结果描述
notes: "仅示例；凭据由平台流水线生成。"

11.3 Claude 提示骨架（复用）

SYSTEM:
你是平台 SRE。严格遵守任务契约，仅输出"示例与占位符"，不得给出可执行命令。

USER:
[PROJECT CONTEXT]
- 集群已存在 namespaces: platform-monitoring, shared-data, app-*
- 需要共享 PG/MySQL/Redis 与监控
- 不得立即实施

[TASK CONTRACT]
<粘贴上面的合同内容>

[OUTPUT FORMAT]
1) PLAN（不超过10行）
2) ARTIFACTS（逐个文件，使用 ```path\n<content>\n``` 格式）
3) CHECKLIST（逐条对应 acceptance）

12. 里程碑与变更控制

• 本文是架构设计与约束，作为 ADR（Architecture Decision Record）记录。
• 任何实施都必须通过"Claude 执行契约"产出占位清单后，进入变更评审（CR），再由平台流水线执行。
• 生产环境变更需：容量评估、回滚方案、演练记录。

---

附录 A · 项目对接清单（提交即视为需求冻结）

• 需要的能力（PG / MySQL / Redis）与读写模式
• 预计 QPS / 连接数 / 峰值周期
• 数据保留策略与合规标签（含脱敏需求）
• 备份级别与恢复目标（RPO/RTO）
• 告警联系人与通知渠道（飞书/邮件）

---

到这里为止，只有文档，没有实施。 下一步：把"Claude 执行契约"的 YAML 模板拷到 /docs/contracts/，针对 shared-data / bookstore / stock 各写一份任务合同，再把 Claude 拉来生成占位清单（values/example/np/sql 等）。这样 Claude 就会在明确白名单与验收约束下输出，不会乱改动或直接 apply。