4. 平台门户架构设计：前端框架选择、后端API设计、与K8s API Server的交互模式

平台门户是 GitOps 调度优化的统一入口，承担着可视化集群状态、触发部署流水线、管理多集群资源的核心职责。本章从架构视角拆解门户的三个关键层次：前端框架选型、后端 API 设计模式、以及与 Kubernetes API Server 的安全交互链路。

4.1 前端框架选择：面向运维场景的对比

平台门户的前端并非通用后台管理界面，而是面向高频操作、实时状态刷新、多级资源嵌套的运维控制台。以下对比主流框架在 K8s 门户场景下的适配度：

4.2 后端 API 设计：RESTful + 长轮询/WebSocket 双通道

平台门户后端承担 API 聚合、鉴权代理、事件推送三大职责。设计上采用分层架构：

• 接入层：统一入口，处理认证（JWT/OIDC）、限流、审计日志。
• 聚合层：将多个 K8s API 调用合并为一次业务请求，减少前端网络开销。
• 缓存层：使用 Redis 缓存高频读取的集群状态（Node/Pod/Event），降低对 API Server 的重复查询。
• 推送层：基于 WebSocket 或 Server-Sent Events (SSE) 推送资源变更事件，实现实时仪表盘。

// 示例：聚合层 API 设计 —— 获取命名空间概览
// GET /api/v1/clusters/{clusterId}/namespaces/{ns}/overview
// 后端聚合以下 K8s API 调用：
//   1. GET /api/v1/namespaces/{ns}/pods
//   2. GET /api/v1/namespaces/{ns}/deployments
//   3. GET /api/v1/namespaces/{ns}/services
//   4. GET /api/v1/namespaces/{ns}/events?fieldSelector=involvedObject.kind!=Pod
// 返回统一结构：
{
  "namespace": "production",
  "pods": { "total": 24, "running": 22, "pending": 1, "failed": 1 },
  "deployments": [ { "name": "web-app", "replicas": 5, "ready": 5 } ],
  "services": [ { "name": "web-svc", "type": "ClusterIP", "ports": ["80:8080"] } ],
  "recentEvents": [ { "type": "Warning", "message": "Back-off restarting failed container", "lastTimestamp": "2025-03-21T10:15:00Z" } ]
}

4.3 与 K8s API Server 的交互模式

后端与 K8s API Server 的交互是门户架构的核心难点。以下 SVG 图展示了三种主流交互模式及其适用场景：

4.4 安全交互：RBAC + ServiceAccount + 细粒度令牌

后端与 K8s API Server 的交互必须遵循最小权限原则。以下是推荐的安全配置清单：

• ServiceAccount 隔离：每个集群/租户使用独立的 ServiceAccount，绑定最小 RBAC 权限。
• 令牌轮换：使用 Bound Service Account Volume，自动轮换，避免静态 Secret 泄露。
• 请求审计：在 API Server 侧开启审计日志，记录所有来自门户的请求。
• 网络策略：仅允许门户后端 Pod 的 IP 范围访问 API Server，拒绝外部直接访问。

# 示例：最小 RBAC 配置 —— 只读 + 特定资源
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: portal-reader
rules:
- apiGroups: [""]
  resources: ["pods", "services", "endpoints", "events"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "statefulsets"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: portal-reader-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: portal-reader
subjects:
- kind: ServiceAccount
  name: portal-backend
  namespace: platform-portal

4.5 架构总览：门户与 K8s 的完整交互链路

以下 SVG 图展示从前端浏览器到 K8s API Server 的完整请求链路：

4.6 关键设计决策总结