feat: initialize parent-bff service with full core features

add complete parent-bff implementation including: - GraphQL endpoint with depth/cost validation - ChildGuard越权校验 with redis cache and singleflight - parallel orchestration with partial failure fallback - three-level cache fallback strategy (Redis + LRU + downstream) - Kafka consumer for cache invalidation and notification push - opossum circuit breaker for downstream services - Prometheus metrics and SLO alerts - Helm chart for k8s deployment with multi-environment configs - Grafana dashboard for observability - complete unit and integration tests
2026-07-10 18:49:06 +08:00
parent a7d8f92227
commit 2229309a1e
88 changed files with 11221 additions and 0 deletions
--- a/infra/k8s/helm/parent-bff/Chart.yaml
+++ b/infra/k8s/helm/parent-bff/Chart.yaml
@@ -0,0 +1,13 @@
+apiVersion: v2
+name: parent-bff
+description: parent-bff 服务级 Helm Chart（家长端 BFF 聚合层，GraphQL 端口 3010）
+type: application
+version: 0.1.0
+appVersion: "0.1.0"
+keywords:
+  - edu
+  - bff
+  - parent
+  - graphql
+maintainers:
+  - name: edu-arch
--- a/infra/k8s/helm/parent-bff/templates/_helpers.tpl
+++ b/infra/k8s/helm/parent-bff/templates/_helpers.tpl
@@ -0,0 +1,29 @@
+{{- define "parent-bff.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{- define "parent-bff.fullname" -}}
+{{- if .Values.fullnameOverride -}}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- $name := default .Chart.Name .Values.nameOverride -}}
+{{- if contains $name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "parent-bff.labels" -}}
+helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}
+{{ include "parent-bff.selectorLabels" . }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+app.kubernetes.io/part-of: edu-platform
+app.kubernetes.io/component: bff
+{{- end -}}
+
+{{- define "parent-bff.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "parent-bff.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end -}}
--- a/infra/k8s/helm/parent-bff/templates/configmap.yaml
+++ b/infra/k8s/helm/parent-bff/templates/configmap.yaml
@@ -0,0 +1,13 @@
+{{- if .Values.configMap.enabled }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "parent-bff.name" . }}-config
+  namespace: {{ .Values.namespace }}
+  labels:
+    {{- include "parent-bff.labels" . | nindent 4 }}
+data:
+  {{- range $k, $v := .Values.configMap.data }}
+  {{ $k }}: {{ $v | quote }}
+  {{- end }}
+{{- end }}
--- a/infra/k8s/helm/parent-bff/templates/deployment.yaml
+++ b/infra/k8s/helm/parent-bff/templates/deployment.yaml
@@ -0,0 +1,94 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "parent-bff.name" . }}
+  namespace: {{ .Values.namespace }}
+  labels:
+    {{- include "parent-bff.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "parent-bff.selectorLabels" . | nindent 6 }}
+  strategy:
+    type: {{ .Values.strategy.type }}
+    rollingUpdate:
+      maxSurge: {{ .Values.strategy.maxSurge }}
+      maxUnavailable: {{ .Values.strategy.maxUnavailable }}
+  template:
+    metadata:
+      labels:
+        {{- include "parent-bff.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/part-of: edu-platform
+        app.kubernetes.io/component: bff
+      {{- if .Values.metrics.enabled }}
+      annotations:
+        prometheus.io/scrape: "true"
+        prometheus.io/port: {{ .Values.metrics.port | quote }}
+        prometheus.io/path: {{ .Values.metrics.path | quote }}
+      {{- end }}
+    spec:
+      {{- if .Values.podAntiAffinity.enabled }}
+      affinity:
+        podAntiAffinity:
+          preferredDuringSchedulingIgnoredDuringExecution:
+            - weight: 100
+              podAffinityTerm:
+                labelSelector:
+                  matchLabels:
+                    {{- include "parent-bff.selectorLabels" . | nindent 20 }}
+                topologyKey: {{ .Values.podAntiAffinity.topologyKey }}
+      {{- end }}
+      containers:
+        - name: {{ include "parent-bff.name" . }}
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: {{ .Values.service.targetPort }}
+              protocol: TCP
+          livenessProbe:
+            httpGet:
+              path: {{ .Values.probes.liveness.path }}
+              port: http
+            initialDelaySeconds: {{ .Values.probes.liveness.initialDelaySeconds }}
+            periodSeconds: {{ .Values.probes.liveness.periodSeconds }}
+            timeoutSeconds: {{ .Values.probes.liveness.timeoutSeconds }}
+            failureThreshold: {{ .Values.probes.liveness.failureThreshold }}
+          readinessProbe:
+            httpGet:
+              path: {{ .Values.probes.readiness.path }}
+              port: http
+            initialDelaySeconds: {{ .Values.probes.readiness.initialDelaySeconds }}
+            periodSeconds: {{ .Values.probes.readiness.periodSeconds }}
+            timeoutSeconds: {{ .Values.probes.readiness.timeoutSeconds }}
+            failureThreshold: {{ .Values.probes.readiness.failureThreshold }}
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          env:
+            {{- if .Values.configMap.enabled }}
+            {{- range $k, $v := .Values.configMap.data }}
+            - name: {{ $k }}
+              valueFrom:
+                configMapKeyRef:
+                  name: {{ include "parent-bff.name" $ }}-config
+                  key: {{ $k }}
+            {{- end }}
+            {{- end }}
+            {{- range $secret := .Values.secretRefs }}
+            {{- range $key := $secret.keys }}
+            - name: {{ $key }}
+              valueFrom:
+                secretKeyRef:
+                  name: {{ $secret.name }}
+                  key: {{ $key }}
+            {{- end }}
+            {{- end }}
+            {{- if .Values.kafka.enabled }}
+            - name: KAFKA_BROKERS
+              value: {{ .Values.kafka.brokers | quote }}
+            - name: KAFKA_CONSUMER_GROUP_ID
+              value: {{ .Values.kafka.consumerGroupId | quote }}
+            {{- end }}
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
--- a/infra/k8s/helm/parent-bff/templates/hpa.yaml
+++ b/infra/k8s/helm/parent-bff/templates/hpa.yaml
@@ -0,0 +1,29 @@
+{{- if .Values.hpa.enabled }}
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ include "parent-bff.name" . }}-hpa
+  namespace: {{ .Values.namespace }}
+  labels:
+    {{- include "parent-bff.labels" . | nindent 4 }}
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ include "parent-bff.name" . }}
+  minReplicas: {{ .Values.hpa.minReplicas }}
+  maxReplicas: {{ .Values.hpa.maxReplicas }}
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.hpa.targetCPUUtilizationPercentage }}
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.hpa.targetMemoryUtilizationPercentage }}
+{{- end }}
--- a/infra/k8s/helm/parent-bff/templates/service.yaml
+++ b/infra/k8s/helm/parent-bff/templates/service.yaml
@@ -0,0 +1,16 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "parent-bff.name" . }}
+  namespace: {{ .Values.namespace }}
+  labels:
+    {{- include "parent-bff.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.service.type }}
+  selector:
+    {{- include "parent-bff.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: http
+      port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP
--- a/infra/k8s/helm/parent-bff/values-dev.yaml
+++ b/infra/k8s/helm/parent-bff/values-dev.yaml
@@ -0,0 +1,22 @@
+# parent-bff 开发环境
+
+replicaCount: 1
+
+image:
+  tag: dev
+
+configMap:
+  data:
+    NODE_ENV: development
+    LOG_LEVEL: debug
+    DEV_MODE: "true"
+    CORS_ORIGINS: http://localhost:4002
+
+hpa:
+  enabled: false
+
+podAntiAffinity:
+  enabled: false
+
+kafka:
+  enabled: false
--- a/infra/k8s/helm/parent-bff/values-prod.yaml
+++ b/infra/k8s/helm/parent-bff/values-prod.yaml
@@ -0,0 +1,35 @@
+# parent-bff 生产环境
+
+replicaCount: 3
+
+image:
+  tag: prod
+
+configMap:
+  data:
+    NODE_ENV: production
+    LOG_LEVEL: info
+    DEV_MODE: "false"
+    CORS_ORIGINS: https://parent.edu.example.com
+
+resources:
+  requests:
+    cpu: 500m
+    memory: 512Mi
+  limits:
+    cpu: 2000m
+    memory: 2Gi
+
+hpa:
+  enabled: true
+  minReplicas: 3
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 70
+  targetMemoryUtilizationPercentage: 80
+
+podAntiAffinity:
+  enabled: true
+
+kafka:
+  enabled: true
+  brokers: kafka.edu-system.svc.cluster.local:9092
--- a/infra/k8s/helm/parent-bff/values-staging.yaml
+++ b/infra/k8s/helm/parent-bff/values-staging.yaml
@@ -0,0 +1,22 @@
+# parent-bff 预发布环境
+
+replicaCount: 2
+
+image:
+  tag: staging
+
+configMap:
+  data:
+    NODE_ENV: production
+    LOG_LEVEL: info
+    DEV_MODE: "false"
+    CORS_ORIGINS: https://parent-staging.edu.example.com
+
+hpa:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 5
+
+kafka:
+  enabled: true
+  brokers: kafka.edu-system.svc.cluster.local:9092
--- a/infra/k8s/helm/parent-bff/values.yaml
+++ b/infra/k8s/helm/parent-bff/values.yaml
@@ -0,0 +1,104 @@
+# parent-bff 服务默认值
+
+# 副本数（生产建议 ≥ 2）
+replicaCount: 2
+
+image:
+  repository: edu/parent-bff
+  tag: latest  # 生产请固定 tag
+  pullPolicy: IfNotPresent
+
+# 服务端口（GraphQL :3010）
+service:
+  type: ClusterIP
+  port: 3010
+  targetPort: 3010
+
+# 命名空间
+namespace: edu-services
+
+# 探针配置
+probes:
+  liveness:
+    path: /healthz
+    initialDelaySeconds: 15
+    periodSeconds: 20
+    timeoutSeconds: 3
+    failureThreshold: 3
+  readiness:
+    path: /readyz
+    initialDelaySeconds: 5
+    periodSeconds: 10
+    timeoutSeconds: 5
+    failureThreshold: 2
+
+# 资源配额
+resources:
+  requests:
+    cpu: 250m
+    memory: 256Mi
+  limits:
+    cpu: 1000m
+    memory: 1Gi
+
+# 滚动更新策略
+strategy:
+  type: RollingUpdate
+  maxSurge: 1
+  maxUnavailable: 0
+
+# Prometheus 指标采集
+metrics:
+  enabled: true
+  port: 3010
+  path: /metrics
+
+# 安全上下文
+securityContext:
+  runAsNonRoot: true
+  runAsUser: 1000
+  allowPrivilegeEscalation: false
+  capabilities:
+    drop: ["ALL"]
+
+# podAntiAffinity（跨节点分布）
+podAntiAffinity:
+  enabled: true
+  topologyKey: kubernetes.io/hostname
+
+# HPA
+hpa:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 70
+  targetMemoryUtilizationPercentage: 80
+
+# 服务级 ConfigMap（非敏感配置）
+configMap:
+  enabled: true
+  data:
+    NODE_ENV: production
+    LOG_LEVEL: info
+    DEV_MODE: "false"
+    PORT: "3010"
+    CORS_ORIGINS: https://parent.edu.example.com
+    REDIS_URL: redis://edu-redis.edu-system.svc.cluster.local:6379
+    IAM_GRPC_TARGET: iam.edu-services.svc.cluster.local:50052
+    CORE_EDU_GRPC_TARGET: core-edu.edu-services.svc.cluster.local:50053
+    DATA_ANA_GRPC_TARGET: data-ana.edu-services.svc.cluster.local:50055
+    MSG_GRPC_TARGET: msg.edu-services.svc.cluster.local:50056
+    PUSH_GATEWAY_URL: http://push-gateway.edu-services.svc.cluster.local:8081
+
+# 敏感配置
+secretRefs:
+  - name: edu-platform-secret
+    keys:
+      - REDIS_PASSWORD
+      - OTEL_EXPORTER_OTLP_ENDPOINT
+
+# Kafka
+kafka:
+  enabled: false  # P5+ 启用
+  brokers: ""
+  consumerGroupId: parent-bff