Qiniu/xinfra/requirements.md

---
tags: [xinfra, requirements, infra]
create time: 2026-07-08 13:54
---

# XINFRA 平台需求文档

## 概述

XINFRA 是七牛云的统一基础设施平台，以**开源子系统集成 + 主系统统管**为核心架构，提供容器编排、数据库治理、缓存管理、CI/CD 自动化和资源开销管控等一站式能力。

**核心目标**：

| # | 目标 | 说明 |
|---|------|------|
| 1 | 统一入口 | 所有基础设施操作收敛到平台化界面，降低命令行直接操作风险 |
| 2 | 多机房资源池化 | 七机房 RKE2 集群统一纳管，实现跨机房调度与服务发现 |
| 3 | 安全合规 | 数据库操作全程审计、SQL 上线必须经过审核、WAF 防护常态化 |
| 4 | 效率提升 | CI/CD 流水线自动触发部署，Ansible 实现基础设施即代码 |
| 5 | 指标面板 | 按部门/项目/机房维度呈现资源开销 |

**设计原则**：

- **最小权限**：子系统操作默认走 RBAC，主系统以 LDAP 身份 + 管理员角色区分权限，APIKey 遵循最小授权范围
- **审计留痕**：数据库变更、容器发布、权限申请等关键操作全程可追溯
- **机房就近**：服务部署和数据访问遵循机房就近原则，降低跨机房延迟
- **平台化自治**：自助申请资源、自助发布、自助诊断，减少人工工单流转
- **复用优先**：监控、告警等能力优先复用已有基础设施（Prometheus / Grafana），主系统只自建无法被替代的能力

---

## 核心概念

### 组内约定

| 概念 | 定义 |
|------|------|
| 主系统 | XINFRA 平台自身的统管层，负责子系统无法覆盖的能力：统一门户（SSO 跳转入口）、审计日志聚合、资源指标面板、运维终端 |
| 子系统 | XINFRA 纳管的专项平台（有独立 WebUI 和 API 服务），各司其职：**CloudDM**（数据库管理与 SQL 审核）、**Wayne**（多集群容器管理）、**CacheCloud**（Redis 缓存管理） |
| 工具层 | 纳管的 CLI / IaC 工具，无常驻 WebUI，由运维人员通过命令行或脚本触发：**Ansible Playbook**（自动化部署与基础设施即代码） |

### 通用术语

| 概念 | 定义 |
|------|------|
| APIKey | Wayne 平台对外提供的 API 认证密钥，用于 CI/CD 流水线等自动化场景的身份认证，遵循最小权限原则 |
| RBAC | 基于角色的访问控制（Role-Based Access Control），通过角色分配权限，用户与角色关联实现权限隔离 |
| RKE2 | Rancher 发行的轻量级 Kubernetes 发行版，专为生产环境设计，支持离线安装和安全加固 |
| CI/CD | 持续集成/持续部署，自动化代码构建、测试和部署的流水线 |
| WAF | Web 应用防火墙（Web Application Firewall），防护 SQL 注入、XSS、CSRF 等常见 Web 攻击 |
| SLA | 服务等级协议（Service Level Agreement），定义服务可用性的承诺指标，如 99.9% 可用率 |
| IaC | 基础设施即代码（Infrastructure as Code），通过 Ansible Playbook 等工具实现基础设施自动化管理 |
| 运维分层 | 故障按层级自愈：子系统处理应用与中间件故障，主系统管理员通过 Ansible / SSH 兜底基础设施层故障，跨层操作需管理员权限 |
| 统一认证 | 主系统和所有子系统共用企业 LDAP 做身份认证（SSO），主系统负责跳转入口，各子系统自行管理授权（RBAC） |

---

## 平台架构总览

```mermaid
graph TB
    subgraph 用户层
        Dev[开发人员]
        DBA[DBA]
        SRE[SRE / 运维]
        Sec[安全团队]
    end

    subgraph 主系统["主系统（XINFRA 统管层）"]
        Portal["统一门户<br/>LDAP SSO 跳转入口"]
        AuditDash["审计面板<br/>聚合子系统审计日志"]
        CostBoard["资源指标面板<br/>自建机房开销归集"]
        OpsTerminal["运维终端<br/>Ansible / SSH<br/>仅管理员"]
    end

    subgraph 子系统["子系统（独立部署，各自授权）"]
        Wayne["Wayne<br/>多集群容器管理"]
        CloudDM["CloudDM<br/>SQL 审核与数据库治理"]
        CacheCloud["CacheCloud<br/>Redis 缓存管理"]
    end

    subgraph 工具层
        Ansible["Ansible Playbook<br/>基础设施即代码"]
    end

    subgraph 基础设施层["基础设施层（非平台开发范围）"]
        WAF["WAF / Ingress"]
        RKE2["RKE2 集群 × 7 机房"]
        Network["大内网互联"]
    end

    subgraph 监控告警["监控告警（已有基础设施）"]
        Prometheus[("Prometheus")]
        Grafana["Grafana<br/>监控指标直接复用"]
        Alert["告警路由<br/>邮件 / 企业 IM"]
    end

    subgraph 数据层
        MySQL[("MySQL")]
        PG[("PostgreSQL")]
        Oracle[("Oracle")]
        CH[("ClickHouse")]
        Redis[("Redis")]
        Harbor[("Harbor 镜像仓库")]
    end

    %% 用户 → 主系统（LDAP SSO 跳转）
    Dev -->|LDAP SSO| Portal
    DBA -->|LDAP SSO| Portal
    SRE -->|LDAP SSO| Portal
    Sec -->|LDAP SSO| Portal

    %% 主系统 → 子系统（跳转入口，不做用户映射）
    Portal -->|跳转| Wayne
    Portal -->|跳转| CloudDM
    Portal -->|跳转| CacheCloud
    SRE --> OpsTerminal

    %% 子系统 → 主系统（审计上报）
    Wayne -.->|审计 Webhook| AuditDash
    CloudDM -.->|审计 Webhook| AuditDash
    CacheCloud -.->|审计 Webhook| AuditDash

    %% 子系统 → 基础设施
    Wayne -->|Client-Go| RKE2
    CloudDM -->|SQL 审核| MySQL
    CacheCloud --> Agent["Agent 管理"] --> Redis

    %% CI/CD 流水线
    GitLab["GitLab CI"] -->|镜像推送| Harbor
    GitLab -->|APIKey 触发部署| Wayne

    %% 工具层
    Ansible -->|SSH| RKE2
    Ansible -->|SSH| MySQL
    Ansible -->|SSH| Redis
    OpsTerminal -->|兜底操作| RKE2

    %% 基础设施层
    WAF --> RKE2
    RKE2 --> Network

    %% 监控（子系统直连 Prometheus，Grafana 直接复用）
    Wayne -.->|Metrics| Prometheus
    CloudDM -.->|Metrics| Prometheus
    CacheCloud -.->|Metrics| Prometheus
    Prometheus --> Grafana
    Prometheus --> Alert

    %% 资源指标面板
    Prometheus -->|节点/网络指标| CostBoard

    classDef mainsys fill:#f3e8fd,stroke:#9333ea,stroke-width:2px
    classDef subsystem fill:#e8f0fe,stroke:#4285f4,stroke-width:2px
    classDef tool fill:#fef3c7,stroke:#d97706,stroke-width:2px
    classDef monitor fill:#fff7ed,stroke:#ea580c,stroke-width:2px
    classDef infra fill:#ecfdf5,stroke:#059669,stroke-width:2px
    classDef data fill:#fce7f3,stroke:#db2777,stroke-width:2px
    class Portal,AuditDash,CostBoard,OpsTerminal mainsys
    class Wayne,CloudDM,CacheCloud subsystem
    class Ansible tool
    class Prometheus,Grafana,Alert monitor
    class WAF,RKE2,Network infra
    class MySQL,PG,Oracle,CH,Redis,Harbor data
```

> [!tip] 图例说明
> - **紫色** = 主系统（统一门户、审计面板、资源指标面板、运维终端）
> - **蓝色** = 子系统（Wayne、CloudDM、CacheCloud，各自独立部署和授权）
> - **黄色** = 工具层（Ansible Playbook，CLI/IaC 脚本）
> - **绿色** = 基础设施层（WAF、RKE2 集群、大内网，由基础设施团队维护，非平台开发范围）
> - **橙色** = 监控告警（Prometheus + Grafana + Alertmanager，已有基础设施，直接复用）
> - **粉色** = 数据层

---

## 干系人与角色

| 角色 | 职责 | 平台交互模块 |
|------|------|-------------|
| 开发人员 | 编写代码、提交发布、申请数据库/缓存资源 | Wayne、CI/CD、CloudDM、CacheCloud |
| DBA | SQL 审核、数据库性能优化、容量规划 | CloudDM |
| SRE / 运维 | 集群维护、自动化部署、故障响应 | Wayne、Ansible、RKE2 |
| 安全团队 | WAF 策略制定、安全审计、合规检查 | WAF、审计面板 |
| 平台管理员 | 账号权限管理、资源配置、平台运维 | 全模块管理后台、审计面板 |

---

## 功能需求

### FR-1 容器编排与多集群管理（RKE2 + Wayne）

> 底层基于 RKE2 构建七机房 K8s 集群，上层通过 Wayne 平台提供统一的容器管理入口。

**目标**：开发人员通过 Wayne UI 或 API 完成服务部署，无需直接操作 kubectl。

#### FR-1.1 RKE2 集群（基础设施依赖）

RKE2 集群部署和配置由基础设施团队负责，平台开发团队只需确保 Wayne 能通过 Client-Go 连接各集群。核心约束：

| 约束项 | 说明 |
|--------|------|
| CNI 插件 | Canal（Calico + Flannel） |
| 容器运行时 | containerd（不依赖 Docker） |
| 离线部署 | 支持 Air-gap 环境 |
| 集群规模 | 七机房各一套独立集群 |

> [!info] 详细部署规范（cluster-cidr、service-cidr、节点注册模式、Systemd 服务管理等）参见运维 SOP 文档，此处不展开。

#### FR-1.2 Wayne 多集群管理

| 编号 | 需求描述 | 优先级 |
|------|---------|--------|
| FR-1.2.1 | 支持多集群统一管理，通过 Client-Go 连接各机房 RKE2 集群 | P0 |
| FR-1.2.2 | RBAC 权限管理，部门角色与项目角色分离（Project → Environment → Namespace 三级结构） | P0 |
| FR-1.2.3 | 提供表单式（基础模式）和 YAML/JSON 编辑（高级模式）两种 K8s 对象创建方式 | P0 |
| FR-1.2.4 | 发布历史记录与一键回滚能力 | P0 |
| FR-1.2.5 | 完整审计模块，每次操作留痕，支持自定义 Webhook 回调；审计数据上报主系统审计面板 | P0 |
| FR-1.2.6 | Web Shell 远程终端（基于权限校验的 Pod Exec） | P1 |
| FR-1.2.7 | 资源报表（资源使用占比、上线频次图表） | P1 |
| FR-1.2.8 | APIKey 开放接口，支持 CI/CD 流水线调用 | P0 |
| FR-1.2.9 | 认证支持 DB 内置 + LDAP 混合模式 | P0 |
| FR-1.2.10 | YAML 模板版本锁定，纳入代码仓库管理 | P1 |

**验收标准**：
- 开发人员可在 Wayne 中选择目标集群完成服务部署
- 每次部署操作有完整审计日志
- CI/CD 流水线可通过 APIKey 调用 Wayne API 触发部署
- 回滚操作可在 1 分钟内完成

---

### FR-2 数据库管理与 SQL 审核（CloudDM）

> 基于 ClouGence 开源的 CloudDM，覆盖数据查询、权限管控、SQL 审核、数据脱敏的全链路能力。

**目标**：所有生产库 SQL 操作必须经过 CloudDM 工单流程，无直连通道。

| 编号 | 需求描述 | 优先级 |
|------|---------|--------|
| FR-2.1 | 支持 Console + Sidecar 集群部署模式，保证高可用 | P0 |
| FR-2.2 | 支持 20+ 数据源类型（MySQL、Oracle、PG、ClickHouse、Redis、MongoDB 等） | P0 |
| FR-2.3 | 内置 54 条 SQL 审核规则，支持规则脚本自定义扩展 | P0 |
| FR-2.4 | SQL 上线工单流程：编写 → 预检 → DBA 审核 → 执行，支持手动/立即/定时三种执行方式 | P0 |
| FR-2.5 | 权限控制：资源权限（实例/库/Schema/表粒度）+ 功能权限（RBAC），支持申请/赋予/临时权限 | P0 |
| FR-2.6 | 数据脱敏能力，对查询结果中的敏感字段进行隐藏或转换 | P1 |
| FR-2.7 | 数据库 CI/CD：支持 Git Push / WebHook / HttpCall 三种触发方式 | P1 |
| FR-2.8 | 统一认证：对接企业 LDAP | P0 |
| FR-2.9 | 全程审计留痕，工单流转记录可追溯；审计数据上报主系统审计面板 | P0 |

**验收标准**：
- 所有生产库 SQL 操作必须经 CloudDM 工单流程，无直连通道
- 审核规则可按需配置白名单豁免
- 生产部署已替换默认 JWT 密钥和管理员密码
- Console 多实例部署，单实例故障不影响服务可用性

---

### FR-3 缓存管理（CacheCloud）

> 基于搜狐开源的 CacheCloud，支持 Standalone、Sentinel、Cluster 三种 Redis 架构的一站式管理。

**目标**：所有 Redis 场景通过 CacheCloud 统一实例申请和管理，降低大规模 Redis 运维成本。

| 编号 | 需求描述 | 优先级 |
|------|---------|--------|
| FR-3.1 | 支持三种 Redis 架构：Standalone（测试）、Sentinel（生产常规，内存 ≤ 6GB）、Cluster（大数据量，内存 > 6GB） | P0 |
| FR-3.2 | Agent 代理部署在每个宿主机上，管理 Redis 实例生命周期 | P0 |
| FR-3.3 | 接入层 Nginx 双机房部署 + Virtual IP 双向漂移，保证高可用 | P0 |
| FR-3.4 | 客户端接入支持 REST API（通用）、Java Jedis/Lettuce SDK、Python 接入 | P0 |
| FR-3.5 | 跨机房部署（Cross-Room）：支持双活，客户端 SDK 自动双写双读和机房切换 | P1 |
| FR-3.6 | 运维能力：全局统计、工单审批、应用运维、实例运维、数据迁移 | P0 |
| FR-3.7 | 诊断工具：慢查询分析、连接数诊断、Bigkey 检测 | P1 |
| FR-3.8 | 报警组件：支持邮件、微信、HTTP 接口集成；告警事件同步至主系统审计面板 | P0 |
| FR-3.9 | 临时实例自动回收策略，防止资源浪费 | P1 |

**验收标准**：
- 三种 Redis 架构均可正常创建和访问
- Agent 心跳正常，实例生命周期管理（启停、备份恢复）功能可用
- 跨机房双活场景下故障切换时间 < 30s

---

### FR-4 CI/CD 流水线

> 基于 GitLab CI，实现代码提交到服务上线的全自动化。

**目标**：CI 编译 → 镜像推送 → 触发 Wayne API 部署，全流程自动化。

| 编号 | 需求描述 | 优先级 |
|------|---------|--------|
| FR-4.1 | CI 阶段：代码编译、单元测试、镜像构建并推送到 Harbor 镜像仓库 | P0 |
| FR-4.2 | CD 阶段：CI 成功后自动调用 Wayne API，传入镜像 tag 触发部署 | P0 |
| FR-4.3 | 部署支持多环境（dev / staging / prod），生产环境需审批卡点 | P0 |
| FR-4.4 | 部署失败时支持自动回滚到上一个稳定版本 | P1 |

**验收标准**：
- 代码提交后 10 分钟内完成 dev 环境自动部署
- prod 环境部署必须经过审批
- 部署失败自动回滚，回滚时间 < 2 分钟

> [!info] 流水线执行状态和日志查看直接复用 GitLab CI 原生 Pipeline 页面，平台不自建查看界面。

---

### FR-5 资源指标面板

> 按部门、项目、机房维度归集和呈现自建机房的资源开销。

**目标**：管理层和团队负责人可按维度查看自建机房资源开销，识别闲置资源。

| 编号 | 需求描述 | 优先级 |
|------|---------|--------|
| FR-5.1 | 按部门 / 项目 / 机房三个维度聚合展示资源开销，支持下钻到具体资源粒度 | P0 |
| FR-5.2 | 数据源：Prometheus 节点指标 + SNMP 网络指标，按 Namespace → Project → Department 路径归属 | P0 |
| FR-5.3 | 支持月度/季度资源开销趋势对比 | P1 |
| FR-5.4 | 资源闲置告警，识别利用率过低的资源 | P2 |

**验收标准**：
- 数据延迟 < 24 小时
- 支持按维度下钻到具体资源粒度

> [!tip] 多云厂商（AWS、阿里云、腾讯云等）账单接入推至后续迭代，初期聚焦自建机房。

---

### FR-6 审计面板（主系统）

> 聚合各子系统的审计日志到主系统，提供统一查询入口，减少跨系统跳转。

**目标**：管理员和安全团队在主系统即可查看全平台审计记录，无需逐个进入子系统。

> [!info] 监控指标（集群状态、Pod 异常数、Redis 健康度等）直接在 Grafana 中查看，主系统不做二次聚合。

| 编号 | 需求描述 | 优先级 |
|------|---------|--------|
| FR-6.1 | 聚合子系统审计日志（Wayne 操作审计、CloudDM 工单审计、CacheCloud 操作审计），支持按时间/操作人/子系统/操作类型筛选查询 | P0 |
| FR-6.2 | 安全事件面板：WAF 拦截事件聚合、异常登录检测、敏感操作告警 | P1 |
| FR-6.3 | 统一告警概览：汇总各子系统告警，按严重级别（Critical / Warning / Info）分组展示 | P1 |
| FR-6.4 | 数据源接入规范：子系统通过 HTTP Webhook 上报审计日志 | P0 |
| FR-6.5 | 权限控制：管理员角色可查看全局；普通用户仅查看所属项目/部门范围内的审计数据 | P0 |
| FR-6.6 | 审计面板集成到主系统统一门户，无需独立部署 | P0 |

**验收标准**：
- 子系统审计日志实时上报，查询延迟 < 5s
- 普通用户只能看到自身权限范围内的数据，无越权
- 审计面板可从统一门户直接访问

---

## 基础设施依赖（非平台开发范围）

以下模块由基础设施团队负责，XINFRA 平台在此基础上构建。平台开发团队需了解其约束，但不负责实施。

### 自动化部署（Ansible Playbook）

通过 Ansible Playbook 实现 MySQL、PostgreSQL、Redis Cluster 等中间件的自动化部署。核心要求：

- Playbook 纳入 Git 版本管理，变更可追溯
- 使用 Ansible 模块保证幂等性
- Inventory 按环境分层管理（dev / test / prod）

> [!info] 详细 Playbook 编写规范（Dry Run、Jinja2 模板等）参见运维 SOP 文档。

### 安全防护（WAF）

WAF 作为基础设施层的安全防护入口，覆盖所有对外暴露的 HTTP/HTTPS 入口。安全事件实时告警，支持与企业 IM 集成。安全日志可查询和分析，支持审计追溯。

### 大内网互联

七机房之间的网络互通由网络团队负责搭建和维护。核心 SLA：同城机房间 Pod 通信延迟 < 2ms，跨机房服务调用成功率 > 99.99%。

---

## 非功能需求

### 性能

| 指标 | 要求 |
|------|------|
| Wayne 页面操作响应 | P95 < 2s |
| CloudDM SQL 审核预检 | 单条 SQL < 3s |
| CacheCloud 实例创建 | Sentinel < 5min，Cluster < 10min |
| CI/CD 流水线端到端（代码提交到部署完成） | < 10min（dev 环境） |

### 可用性

| 指标 | 要求 |
|------|------|
| 平台核心服务（Wayne、CloudDM、CacheCloud） | SLA ≥ 99.9% |
| 单集群控制面 | SLA ≥ 99.95% |
| 跨机房网络互联 | SLA ≥ 99.99% |

### 安全

- 子系统操作经过 RBAC 权限校验，主系统以 LDAP 身份 + 管理员角色区分权限
- 数据库操作全程审计留痕
- 敏感数据（Secret、密码）加密存储
- 生产环境禁止使用默认凭证

### 可观测性

- 各子系统暴露 Metrics 接口，接入 Prometheus + Grafana
- 关键操作日志统一收集到日志平台
- 告警通道统一（邮件 + 企业 IM）

### 可扩展性

- 新机房接入时，RKE2 集群部署和 Wayne 注册可在 1 天内完成
- CloudDM / CacheCloud 支持水平扩展（Console + 多 Sidecar）

---

## 系统集成关系

**关键集成点**：

| 源 | 目标 | 接口方式 | 说明 |
|----|------|---------|------|
| 企业 LDAP | 各子系统 + 主系统 | LDAP Bind / SSO | 统一身份认证，主系统做 SSO 跳转入口 |
| GitLab CI | Wayne | REST API（APIKey 认证） | 自动触发部署 |
| GitLab CI | Harbor | Docker Push | 镜像推送 |
| Wayne | RKE2 | Client-Go（K8s API） | 容器编排操作 |
| CloudDM | MySQL | Sidecar SQL 代理 | SQL 审核执行 |
| CacheCloud | Redis | Agent | 实例生命周期管理 |
| Ansible | 各主机 | SSH | 基础设施初始化部署 |
| 各子系统 | 审计面板 | HTTP Webhook | 审计日志统一归集 |
| 各子系统 + 基础设施 | Prometheus | HTTP / Exporter | Metrics 采集 |
| Prometheus | Grafana | PromQL | 监控指标可视化（直接复用） |
| Prometheus | 告警路由 | Alertmanager | 统一告警（邮件 / 企业 IM） |

---

## 风险与约束

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| RKE2 版本升级可能引入不兼容变更 | 集群稳定性 | 先在测试环境验证，灰度发布 |
| Wayne 开源版本维护活跃度不确定 | 功能迭代受限 | 内部 Fork 并保持核心模块可维护 |
| 七机房网络链路故障 | 跨机房服务中断 | 网络冗余 + 自动切换 + 告警监控 |
| SQL 审核规则误判 | 合法 SQL 被拦截 | 白名单机制 + 规则持续调优 |
| Redis 大 Key / 热 Key | 性能劣化 | CacheCloud 诊断工具 + 应用侧治理 |

---

## 运维分层模型

> 故障按层级自愈，跨层操作需主系统管理员权限。

| 故障层级 | 处理方 | 工具链 | 权限要求 |
|---------|--------|--------|---------|
| 应用发布异常 | 子系统自愈 | Wayne 一键回滚 | 项目成员 |
| 中间件故障 | 子系统自恢复 | CacheCloud / CloudDM 内置运维能力 | 子系统运维角色 |
| 基础设施故障 | 主系统管理员 | Ansible Playbook / SSH 终端 | 仅主系统管理员 |
| 机房级故障 | 主系统管理员 | Ansible + 大内网链路切换 | 仅主系统管理员 |

> [!warning] 安全约束
> Ansible / SSH 终端等基础设施级操作仅对主系统管理员角色可见，普通用户菜单中不包含此项。所有跨层操作全程审计留痕。

---

## 关联笔记

- [[technical/xinfra-preview]]
- [[technical/xinfra-preview/k8s-rke2-fundamentals]]
- [[technical/xinfra-preview/wayne-overview]]
- [[technical/xinfra-preview/cloud-dm-overview]]
- [[technical/xinfra-preview/cachecloud-overview]]
- [[technical/xinfra-preview/ansible-playbook-basics]]