Qiniu/xinfra/requirements.md

tags, create time

tags	create time
xinfra requirements infra	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）

---

平台架构总览

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