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，APIKey 遵循最小授权范围
• 审计留痕：数据库变更、容器发布、权限申请等关键操作全程可追溯
• 机房就近：服务部署和数据访问遵循机房就近原则，降低跨机房延迟
• 平台化自治：自助申请资源、自助发布、自助诊断，减少人工工单流转

---

核心概念

组内约定

概念	定义
主系统	XINFRA 平台自身的统管层，负责子系统无法覆盖的能力，如跨子系统的权限收敛、统一入口、全局调度和审计聚合
子系统	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% 可用率
CNI	容器网络接口（Container Network Interface），K8s 中负责 Pod 网络通信的插件规范
IaC	基础设施即代码（Infrastructure as Code），通过 Ansible Playbook 等工具实现基础设施自动化管理
运维分层	故障按层级自愈：子系统处理应用与中间件故障，主系统管理员通过 Ansible / SSH 兜底基础设施层故障，跨层操作需管理员权限
Console + Sidecar	CloudDM 的集群部署模式，Console 负责管理界面，Sidecar 负责实际 SQL 执行和代理
Air-gap	离线部署模式，适配无外网访问的内网环境，所有依赖包需预先下载
Harbor	企业级容器镜像仓库，用于存储和分发 Docker/OCI 镜像
跨系统认证	主系统统一 LDAP 认证，一个主系统用户对应各子系统中的多个用户（1:N 映射）。主系统管身份（Authentication），子系统管授权（Authorization）
containerd	K8s 默认的容器运行时（CRI 标准），负责容器生命周期管理，取代 Docker

平台架构总览

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

    subgraph 平台层["平台层（主系统 + 子系统）"]
        subgraph 主系统["主系统（XINFRA 统管层）"]
            Portal[统一门户<br/>LDAP 认证入口]
            AuditAgg[审计聚合中心]
            CICD[CI/CD 流水线]
            CostBoard[多云成本看板]
            OpsTerminal[运维终端<br/>Ansible / SSH<br/>「仅管理员」]
        end
        subgraph 子系统["子系统（独立部署，各自授权）"]
            Wayne[Wayne 多集群管理]
            CloudDM[CloudDM SQL 审核<br/>多实例 HA]
            CacheCloud[CacheCloud Redis 管理]
        end
    end

    subgraph 工具层
        Ansible[Ansible Playbook<br/>「基础设施初始化」]
    end

    subgraph 基础设施层
        Ingress["Ingress / WAF<br/>「安全防护入口」"]
        RKE2[RKE2 集群 x7 机房]
        Network[大内网互联]
    end

    subgraph 监控告警["监控告警（外部依赖）"]
        Prometheus[(Prometheus<br/>Metrics 采集)]
        Grafana[Grafana 可视化]
        Alert[告警路由<br/>邮件 / 企业 IM]
    end

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

    Dev -->|1: N 用户映射| Portal
    DBA -->|1: N 用户映射| Portal
    SRE -->|1: N 用户映射| Portal
    Sec -->|1: N 用户映射| Portal
    Portal --> Wayne
    Portal --> CICD
    Portal --> CloudDM
    Portal --> CacheCloud
    Portal --> CostBoard
    SRE --> OpsTerminal
    Wayne -.->|审计上报| AuditAgg
    CloudDM -.->|审计上报| AuditAgg
    CacheCloud -.->|审计上报| AuditAgg

    Wayne -->|Client-Go| RKE2
    CloudDM -->|SQL 审核接入<br/>MySQL / PG / Oracle / CH / MongoDB| MySQL
    CacheCloud --> Redis
    CICD --> Harbor
    CICD -->|APIKey 触发部署| Wayne
    Ansible --> RKE2
    Ansible --> MySQL
    Ansible --> Redis
    OpsTerminal -->|兜底操作| RKE2
    OpsTerminal -->|兜底操作| Network

    Ingress --> RKE2
    RKE2 --> Network

    Wayne -.->|Metrics| Prometheus
    CloudDM -.->|Metrics| Prometheus
    CacheCloud -.->|Metrics| Prometheus
    Prometheus --> Grafana
    Prometheus --> Alert
    Sec -->|安全事件查询| Ingress

    CostBoard -.->|云账单 API| CH
    CostBoard -.->|K8s / 节点指标| Prometheus

    classDef subsystem fill:#e8f0fe,stroke:#4285f4,stroke-width:2px
    classDef mainsys fill:#f3e8fd,stroke:#9333ea,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
    class Wayne,CloudDM,CacheCloud subsystem
    class Portal,AuditAgg,CICD,CostBoard,OpsTerminal mainsys
    class Ansible tool
    class Prometheus,Grafana,Alert monitor
    class Ingress,RKE2,Network infra

[!tip] 图例说明

• 紫色节点 = 主系统（XINFRA 统管层：统一门户、审计聚合、CI/CD、成本看板、运维终端）
• 蓝色节点 = 子系统（有独立 WebUI 的平台：Wayne、CloudDM、CacheCloud）
• 黄色节点 = 工具层（CLI/IaC 脚本，无常驻 WebUI：Ansible Playbook）
• 橙色节点 = 监控告警（外部依赖：Prometheus + Grafana + 告警路由）
• 绿色节点 = 基础设施层（Ingress/WAF、RKE2 集群、大内网互联）

---

干系人与角色

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

---

功能需求

FR-1 容器编排与资源池化

底层基于 Rancher RKE2，覆盖七机房 K8s 集群的统一生命周期管理。

目标：为全公司业务提供统一的容器运行时环境，支持跨机房资源调度。

编号	需求描述	优先级
FR-1.1	每个机房独立部署一套 RKE2 集群，各集群拥有独立的 cluster-cidr（10.42.0.0/16）和 service-cidr（10.43.0.0/16）	P0
FR-1.2	集群使用 Canal（Calico + Flannel）作为 CNI 插件，kube-proxy 默认 iptables 模式	P0
FR-1.3	支持 Air-gap 离线部署能力，适配内网无外网环境	P0
FR-1.4	节点注册支持静态 Token 和 Bootstrap 证书签名两种模式	P1
FR-1.5	提供容器运行时为 containerd（默认），不依赖 Docker	P0
FR-1.6	支持 Systemd 服务管理方式部署，确保生产环境标准化	P0

验收标准：

• 七机房集群均可达 Ready 状态
• Pod 跨节点通信正常（验证 CNI 插件）
• 离线环境可完成集群初始化和节点扩容

---

FR-2 多集群容器管理（Wayne）

基于 360 开源的 Wayne 平台，作为服务发布和容器管理的统一入口。

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

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

用户故事：

作为开发人员，我希望通过 Wayne 界面选择项目、环境和集群，上传或编辑 Deployment YAML 后一键发布，发布后能在历史记录中查看变更详情并在异常时快速回滚。

验收标准：

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

---

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

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

目标：所有 MySQL 操作必须经过 CloudDM 审核，防止误操作直接打到生产库。

编号	需求描述	优先级
FR-3.1	支持 Console + Sidecar 集群部署模式，Console 端口 8222，Sidecar 端口 8080	P0
FR-3.2	支持 20+ 数据源类型（MySQL、Oracle、PG、ClickHouse、Redis、MongoDB 等）	P0
FR-3.3	内置 54 条 SQL 审核规则，支持规则脚本自定义扩展	P0
FR-3.4	SQL 上线工单流程：编写 → 预检 → DBA 审核 → 执行，支持手动/立即/定时三种执行方式	P0
FR-3.5	权限控制：资源权限（实例/库/Schema/表粒度）+ 功能权限（RBAC），支持申请/赋予/临时权限	P0
FR-3.6	数据脱敏能力，对查询结果中的敏感字段进行隐藏或转换	P1
FR-3.7	数据库 CI/CD：支持 Git Push / WebHook / HttpCall 三种触发方式	P1
FR-3.8	统一认证：支持 OpenLDAP / OIDC SSO	P1
FR-3.9	全程审计留痕，工单流转记录可追溯	P0

用户故事：

作为开发人员，我希望在 CloudDM Web 界面编写 SQL 变更语句后，系统自动进行 54 条规则预检，通过后提交 DBA 审核，审核通过后在指定时间窗口执行，全程结果回填工单。

作为 DBA，我希望审核规则可按业务场景自定义，DML 和 DDL 采用不同审核标准和执行窗口。

验收标准：

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

---

FR-4 缓存管理（CacheCloud）

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

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

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

用户故事：

作为开发人员，我希望通过 CacheCloud 平台自助申请 Redis 实例，选择合适的架构类型和规格，审批通过后自动部署，客户端通过 SDK 获取连接信息即可使用。

验收标准：

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

---

FR-5 CI/CD 流水线

双引擎架构，实现代码提交到服务上线的全自动化。

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

编号	需求描述	优先级
FR-5.1	CI 阶段：代码编译、单元测试、镜像构建并推送到 Harbor 镜像仓库	P0
FR-5.2	CD 阶段：CI 成功后自动调用 Wayne API，传入镜像 tag 触发部署	P0
FR-5.3	支持 GitLab CI 作为主要 CI 引擎	P0
FR-5.4	部署支持多环境（dev / staging / prod），生产环境需审批卡点	P0
FR-5.5	部署失败时支持自动回滚到上一个稳定版本	P1
FR-5.6	流水线执行状态和日志可在统一界面查看	P1

用户故事：

作为开发人员，我希望提交代码后 GitLab CI 自动编译、构建镜像并推送到 Harbor，随后自动调用 Wayne API 部署到 dev 环境；部署到 prod 环境时需要主管审批后方可执行。

验收标准：

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

---

FR-6 自动化部署（Ansible）

通过 Ansible Playbook 实现基础设施即代码（IaC），用于部署和管理中间件。

目标：MySQL Server、PostgreSQL、Redis Cluster 等中间件的部署和配置管理实现自动化。

编号	需求描述	优先级
FR-6.1	Playbook 覆盖 MySQL Server、PostgreSQL、Redis Cluster 的部署场景	P0
FR-6.2	Inventory 按环境分层管理（dev / test / prod）	P0
FR-6.3	使用 Ansible 模块保证幂等性，避免 shell/command 破坏幂等	P0
FR-6.4	首次运行支持 Dry Run（--check --diff）预检	P1
FR-6.5	Playbook 纳入 Git 版本管理，变更可追溯	P0
FR-6.6	Jinja2 模板实现一套代码适配多环境	P1

验收标准：

• 一套 Playbook 可在 dev / test / prod 环境分别执行，结果一致
• 重复执行 Playbook 不产生副作用（幂等性）
• Dry Run 输出与实际执行 diff 一致

---

FR-7 安全态势（WAF）

Web 应用防火墙，提供常态化的安全防护能力。

目标：为平台和业务服务提供 WAF 防护，及时发现和拦截安全威胁。

编号	需求描述	优先级
FR-7.1	支持常见 Web 攻击防护（SQL 注入、XSS、CSRF 等）	P0
FR-7.2	安全规则可按业务场景自定义和调整	P1
FR-7.3	安全事件实时告警，支持与企业 IM 集成	P0
FR-7.4	安全日志可查询和分析，支持审计追溯	P0

验收标准：

• WAF 覆盖所有对外暴露的 HTTP/HTTPS 入口
• 安全事件从发现到告警 < 1 分钟

---

FR-8 大内网互联

实现七机房之间的网络互通，保障跨机房服务调用和数据同步。

目标：七机房容器网络、服务网络互联互通，延迟可控。

编号	需求描述	优先级
FR-8.1	七机房容器网络互通，Pod 跨机房可达	P0
FR-8.2	跨机房服务调用延迟监控与告警	P0
FR-8.3	网络链路冗余，单链路故障不影响跨机房通信	P0
FR-8.4	跨机房流量可视化，支持按机房/服务维度查看	P1

验收标准：

• 同城机房间 Pod 通信延迟 < 2ms
• 跨机房服务调用成功率 > 99.99%

---

FR-9 多云成本看板

统一归集多云资源成本，按业务维度可视化呈现。

目标：管理层和团队负责人可按部门、项目、机房维度查看资源成本。

编号	需求描述	优先级
FR-9.1	支持多云厂商（AWS、阿里云、腾讯云等）成本数据接入	P1
FR-9.2	按部门 / 项目 / 机房三个维度聚合展示成本	P0
FR-9.3	支持月度/季度成本趋势对比	P1
FR-9.4	资源闲置告警，识别利用率过低的资源	P2

验收标准：

• 成本数据延迟 < 24 小时
• 支持按维度下钻到具体资源粒度
• 云资源通过各厂商 Billing API 经 Exporter 采集入 ClickHouse；自建机房成本由 Prometheus 节点指标 + SNMP 网络指标汇总，按 Namespace → Project → Department 路径归属

---

非功能需求

性能

指标	要求
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 权限校验
• 数据库操作全程审计留痕
• 敏感数据（Secret、密码）加密存储
• 生产环境禁止使用默认凭证

可观测性

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

可扩展性

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

---

系统集成与依赖关系

graph LR
    subgraph 认证
        LDAP[(企业 LDAP)] -->|统一身份认证| Portal[XINFRA 统一门户]
    end

    subgraph 自动化流水线
        GitLab[GitLab CI] -->|镜像推送| Harbor[Harbor]
        GitLab -->|触发部署 API| Wayne
    end

    subgraph 平台层
        Portal -->|1:N 用户映射| Wayne
        Portal -->|1:N 用户映射| CloudDM
        Portal -->|1:N 用户映射| CacheCloud
        Wayne -->|Client-Go| K8s[RKE2 集群]
        CloudDM -->|Sidecar SQL 代理| MySQL[(MySQL)]
        CacheCloud -->|Agent 管理| Redis[(Redis)]
        Ansible -->|SSH| K8s
        Ansible -->|SSH| MySQL
        Ansible -->|SSH| Redis
        Wayne -.->|审计上报| AuditAgg[审计聚合]
        CloudDM -.->|审计上报| AuditAgg
        CacheCloud -.->|审计上报| AuditAgg
    end

    subgraph 跨集群
        Wayne -->|调度| ClusterA[机房 A]
        Wayne -->|调度| ClusterB[机房 B]
        Wayne -->|调度| ClusterN[机房 N...]
    end

    subgraph 安全与网络
        WAF[WAF] -->|HTTP/HTTPS 防护| Ingress[Ingress 入口]
        Ingress --> K8s
        Network[大内网] -->|互联| ClusterA
        Network -->|互联| ClusterB
    end

    subgraph 监控告警
        K8s -.->|Metrics| Prometheus[(Prometheus)]
        MySQL -.->|Metrics| Prometheus
        Redis -.->|Metrics| Prometheus
        Prometheus --> Grafana[Grafana]
        Prometheus --> Alert[告警路由]
    end

    subgraph 成本采集
        CloudAPI[云厂商 Billing API] -->|Exporter| CH[(ClickHouse)]
        Prometheus -->|节点/网络指标| CostBoard[成本看板]
        CH --> CostBoard
    end

关键集成点：

源	目标	接口方式	说明
企业 LDAP	XINFRA 统一门户	LDAP Bind	统一身份认证，1:N 用户映射到子系统
XINFRA 统一门户	各子系统	内部 API / 会话代理	用户选择子系统后代入本地身份
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（SSH + 心跳）	实例生命周期管理
Ansible	各主机	SSH	基础设施初始化部署
各子系统	审计聚合中心	HTTP Webhook	操作审计统一归集
各子系统 + 基础设施	Prometheus	HTTP / Exporter	Metrics 采集
云厂商 Billing API	ClickHouse	Exporter 定时拉取	多云成本数据归集
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