云边协同物联网平台系统架构文档

1. 执行摘要

• 目的与范围：

  • 面向数百万设备的云边协同平台，提供设备注册/认证、在线状态管理、命令下发、遥测采集、规则处理、OTA 升级、告警/工单、报表与监控。
  • 支持多协议接入（MQTT/CoAP），设备直连或经网关接入；边缘具备轻量代理、规则引擎与离线缓冲；云端基于 Kubernetes 的微服务架构。

• 关键架构决策：

  • 接入与传输：统一采用双向 TLS 与设备证书进行认证；MQTT/CoAP 接入按协议与地域水平扩展。
  • 流处理与一致性：Kafka + 流式计算框架（支持恰好一次语义）；按设备粘性分区与序列号保证消息顺序与幂等。
  • 时序存储：高吞吐时序数据库（压缩与冷热分层），对象存储用于固件和遥测归档。
  • 规则引擎：支持条件、阈值与风控，云边协同执行；P95 延迟 < 500ms。
  • 安全与合规：TLS1.2+ 强制启用，命令/固件签名校验，设备证书周期轮换；数据最小留存、脱敏及审计。
  • 运维与治理：统一 API 网关提供租户隔离、鉴权与速率限制；集中审计与准入控制；变更窗口与灰度发布。

• 规模与性能目标：

  • 单集群支持 500 万设备；峰值写入 200 万条/分钟；边缘断网缓冲 24 小时；云端 RPO ≤ 10 分钟。

2. 系统概述

• 高层级描述：

  • 设备端/边缘侧：轻量代理与规则引擎，支持本地缓存与断点续传。
  • 接入层：MQTT Broker 集群、CoAP 网关，统一接入与设备会话管理。
  • 云端微服务：设备管理、身份与密钥、遥测采集、时序存储、规则处理、OTA 升级、告警与工单、地理围栏、报表。
  • 数据层：Kafka、时序数据库、对象存储、关系型元数据仓库、缓存（Redis）。
  • 外部网关：统一 API 网关（租户隔离、鉴权/授权、速率限制）。
  • 监控：设备在线率、消息堆积、边缘健康、规则执行指标。

• 高层架构图：

flowchart LR
  subgraph Edge["边缘侧"]
    EA[边缘代理/规则引擎]
    LC[本地缓存/断点续传]
    GW[现场网关]
    Dev[设备群]
    Dev --> GW --> EA -->|MQTT/CoAP+mTLS| Ingest
    EA --> LC
  end

  subgraph Ingress["接入层"]
    Ingest[协议接入集群(MQTT/CoAP)]
    ConnMgr[连接/会话管理]
    Ingest --> ConnMgr
  end

  subgraph Cloud["云端微服务(Kubernetes)"]
    APIGW[统一API网关(租户隔离/鉴权/限流)]
    DM[设备管理]
    IK[身份与密钥]
    TI[遥测采集]
    RE[规则处理]
    OTA[OTA升级]
    ALR[告警与工单]
    GF[地理围栏]
    RPT[报表/查询]
    APIGW --> DM
    APIGW --> OTA
    APIGW --> ALR
    APIGW --> RPT
  end

  subgraph Data["数据层"]
    KFK[Kafka/流处理]
    TSDB[时序数据库(冷热分层)]
    OBJ[对象存储(固件/归档)]
    RDB[元数据数据库]
    REDIS[缓存/会话]
    TI --> KFK --> RE
    RE --> ALR
    KFK --> TSDB
    OTA --> OBJ
    DM --> RDB
    ConnMgr --> REDIS
  end

  Ingest --> TI
  APIGW --- Ingest

3. 架构目标与约束

• 关键目标：

  • 高并发接入与吞吐；低延迟规则处理；云边协同；多租户隔离与计费。
  • 离线容忍与断点续传；消息顺序与幂等；可观测性与可运营性。

• 性能与扩展：

  • 单集群 500 万设备；200 万条/分钟峰值写入；规则处理 P95 < 500ms。
  • 多区域部署，接入层按照协议与地域水平扩展；TSDB 分区与分层存储。

• 安全与合规：

  • TLS1.2+ 强制；设备证书定期轮换；命令/固件签名校验。
  • 数据最小留存、脱敏；遵循当地物联网安全与隐私法规。

• 可靠性与灾备：

  • 边缘断网缓冲 24 小时；云端 RPO ≤ 10 分钟；支持灾备切换演练。

• 技术栈约束：

  • 流处理具备恰好一次语义（Kafka 事务 + 流引擎）；时序库支持压缩与冷热分层；OTA 支持灰度、暂停与回滚。

• 运维与治理：

  • 集中审计、准入控制与变更窗口；统一 API 网关限流与计费；SLO/SLI 报告。

• 假设：

  • 设备支持客户端证书与心跳；网关具备本地存储；设备可报告序列号或递增计数用于去重。

4. 架构模式与风格

• 微服务架构：按领域拆分（设备管理、身份密钥、遥测采集、规则处理、OTA、告警工单、报表）。
• 事件驱动与流式处理：Kafka 作为事实事件总线，使用恰好一次语义；规则引擎与告警基于流计算。
• CQRS：命令/控制与遥测读写分离；写入路径与查询路径独立优化。
• 云边协同：边缘代理执行部分规则，云端统一编排与下发。
• API 网关 + 多租户隔离：统一入口进行鉴权授权、限流、审计与计费。
• 可靠交付与幂等：Outbox/事务消息、设备级序列号、粘性分区、幂等消费者。
• 弹性与容错：按协议与地域水平扩展；断网缓冲与断点续传；回压与自适应心跳。
• 安全内生：mTLS、密钥轮换、签名校验、零信任网络分段。

5. 系统组件

5.1 边缘代理与规则引擎（Edge Agent）

• 责任与特性：
  • 协议适配（Modbus/OPC-UA/自定义）到 MQTT/CoAP。
  • 本地规则执行（阈值、简单条件、预聚合）；断网缓冲（≥24h）。
  • 本地缓存与断点续传，包序与去重；带宽/功耗优化（批处理、心跳动态）。
• 交互：
  • 与设备/网关交互采集数据；与云接入层进行 mTLS 通信；接收云下发边缘任务/规则。
• 内部结构图：

flowchart LR
  SA[采集适配器] --> RP[规则处理器(边缘)]
  RP --> PQ[持久化队列/缓存]
  PQ --> UPL[上传管道(断点续传)]
  CFG[配置/策略管理] --> SA
  CFG --> RP

5.2 协议接入集群（MQTT/CoAP）

• 责任与特性：
  • 处理设备连接、会话、订阅、心跳与消息收发；双向 TLS；设备证书认证。
  • 支持 LWT（最后遗言）报告离线；低功耗心跳优化（可变 KeepAlive、ACK 聚合）。
• 交互：
  • 向遥测采集服务转发消息；与连接管理共享会话状态；与 API 网关互通命令通道。
• 内部结构：

flowchart LR
  LB[接入负载均衡] --> MB[MQTT Broker Shards]
  LB2[接入负载均衡] --> COAP[CoAP 网关]
  MB --> CM[连接/会话管理]
  COAP --> CM
  MB --> TI[遥测采集]
  COAP --> TI

5.3 连接/会话管理（Connection Manager）

• 责任与特性：
  • 维护设备在线状态、心跳、最后活动时间；提供在线率指标。
  • 会话粘性分配；支持 LWT 触发告警；租户/分组维度统计。
• 交互：
  • 从接入集群获取会话事件；写入缓存（Redis）；向设备管理上报状态；暴露查询接口。

5.4 设备管理（Device Management）

• 责任与特性：
  • 设备注册/分组/标签；拓扑（设备-网关）；租户隔离与配额。
  • 设备元数据、影子文档（Desired/Reported）；审计日志。
• 交互：
  • 与身份与密钥服务协作完成入网与证书发放；为命令/OTA/规则提供设备选择。
• 内部结构：

flowchart LR
  API[管理API] --> REG[注册/入网]
  API --> META[元数据/影子]
  REG --> IK[身份与密钥]
  META --> RDB[(RDB)]

5.5 身份与密钥（Identity & Key）

• 责任与特性：
  • 设备证书颁发与轮换；命令与固件签名校验；租户与用户身份（OIDC/OAuth2）。
  • 与 KMS/HSM 集成，保证密钥安全。
• 交互：
  • 与接入层进行证书校验；与 OTA/命令服务进行签名验证；与 API 网关进行用户鉴权。

5.6 遥测采集（Telemetry Ingestor）

• 责任与特性：
  • 接收来自接入层的遥测数据；进行轻量校验、结构化、打标签（设备/租户/时间）。
  • 通过 Kafka 写入流处理与时序数据库（Exactly-once）。
• 交互：
  • 生产 telemetry_raw 主题；触发规则处理；归档至 TSDB。
• 内部结构：

flowchart LR
  RX[接收器] --> VAL[校验/规范化]
  VAL --> OUTBOX[事务Outbox]
  OUTBOX --> KFK[(Kafka)]
  KFK --> TSDB[TSDB 写入器]

5.7 规则处理（Rule Engine）

• 责任与特性：
  • 可视化规则编排；条件、阈值、风控；云边协同下发。
  • P95 延迟 < 500ms；支持状态ful计算、窗口与地理围栏。
• 交互：
  • 消费 Kafka 遥测流；触发告警与工单；可下发命令或边缘任务。
• 内部结构：

flowchart LR
  CFG[规则配置/编排] --> DIST[规则发布(云/边缘)]
  KFK[(telemetry_enriched)] --> ENG[流式计算引擎]
  ENG --> EVT[规则事件/告警]
  EVT --> ALR[告警/工单]
  EVT --> CMD[命令下发]

5.8 OTA 升级（OTA Service）

• 责任与特性：
  • 灰度发布、分批、暂停与回滚；固件签名校验；下载断点续传；进度与失败分析。
• 交互：
  • 与对象存储管理固件；向设备/边缘下发升级指令；与规则/告警联动。

5.9 告警与工单（Alert & Ticketing）

• 责任与特性：
  • 多级告警（信息/警告/严重）；地理围栏触发；工单闭环（创建、派发、处理、归档）。
• 交互：
  • 接收规则事件；通知渠道（短信/邮件/Webhook）；与设备管理、报表集成。

5.10 地理围栏（Geofence）

• 责任与特性：
  • 定义区域、边界策略；检测设备位置与越界事件；与规则引擎结合。
• 交互：
  • 消费位置流；触发告警与工单。

5.11 报表与查询（Reporting）

• 责任与特性：
  • 实时/离线报表；设备在线率、消息堆积、规则执行指标；租户级计费/用量。
• 交互：
  • 查询 TSDB 与归档；汇总 Kafka 指标；输出到 API 与可视化。

5.12 数据层（Kafka/TSDB/Object/RDB/Redis）

• Kafka：主题分区按租户/设备键；Exactly-once 生产/消费；DLQ 与重试。
• TSDB：压缩、分区、冷热分层；写入批量与时间窗口优化；索引设备/租户。
• 对象存储：固件与历史归档；生命周期策略；加密存储。
• RDB：设备元数据、规则配置、工单、审计日志；主从与读写分离。
• Redis：会话状态、速率限制、短期缓存；TTL 与淘汰策略。

5.13 统一 API 网关（API Gateway）

• 责任与特性：
  • 鉴权（OIDC/OAuth2/API Key）、授权（RBAC/ABAC）、租户隔离、速率限制与配额、审计。
• 交互：
  • 北向 API 暴露；南向命令通道与接入层协同；与监控集成。

5.14 监控与可观测性

• 指标：设备在线率、消息堆积（队列滞留）、边缘健康（CPU/内存/缓存使用）、规则执行延迟与失败率、OTA 成功率、TSDB 写入延迟、API 网关拒绝率。
• 日志与追踪：集中日志（结构化）、分布式追踪（TraceID 贯穿接入→处理→存储）。
• 告警：基于阈值与异常检测；演练与抑制策略。

6. 数据模型与流

6.1 关键实体与关系（选摘）

• 存储映射：
  • TSDB：TelemetryPoint 按 tenantId/deviceId/metric/ts 分区。
  • RDB：Device/Rule/Alert/Ticket/Firmware/OTAJob/Geofence/AuditLog。
  • Redis：会话状态与速率限制；命令短期状态。
  • Object：Firmware 二进制、遥测归档（压缩 Parquet/ORC）。

6.2 数据流动路径

• 遥测数据流（设备→云→规则→存储）：

sequenceDiagram
  participant Dev as 设备/边缘
  participant Ingest as 接入(MQTT/CoAP)
  participant TI as 遥测采集
  participant KFK as Kafka
  participant RE as 规则引擎
  participant TSDB as TSDB

  Dev->>Ingest: Telemetry(mTLS, seq)
  Ingest->>TI: 标准化消息
  TI->>KFK: telemetry_raw(事务/幂等)
  KFK->>RE: 消费/富化(设备/租户标签)
  RE->>TSDB: 指标写入(批量)
  RE->>KFK: rules_events(触发告警/命令)

• 命令下发与回执：

sequenceDiagram
  participant API as API网关
  participant CMD as 命令服务
  participant Ingest as 接入(MQTT)
  participant Dev as 设备
  API->>CMD: POST /devices/{id}/commands
  CMD->>Ingest: 下行消息(mTLS, 签名)
  Ingest->>Dev: 命令交付
  Dev-->>Ingest: ACK/Result(seq, signature)
  Ingest-->>CMD: 回执
  CMD-->>API: 状态更新

• OTA 升级：

sequenceDiagram
  participant API as 控制台/API
  participant OTA as OTA服务
  participant OBJ as 对象存储
  participant Dev as 设备/边缘
  API->>OTA: 创建OTAJob(灰度策略)
  OTA->>Dev: 下发升级指令
  Dev->>OBJ: 断点续传下载(校验/签名)
  Dev-->>OTA: 进度/结果上报
  OTA-->>API: 报告/可回滚

7. 集成与接口

7.1 组件间通信

• 内部通信：
  • gRPC/HTTP2（服务间低延迟调用）。
  • Kafka（异步事件/流处理）。
  • Redis（会话/限流）。
• 接入与云：
  • MQTT 3.1.1/5，CoAP；mTLS 双向认证。
• API 网关：
  • OAuth2/OIDC 用户认证；RBAC/ABAC 授权；租户隔离；速率限制与配额。

7.2 外部接口与 API（示例）

• MQTT 主题约定（示例）：
  • 上行：tenant/{t}/device/{d}/telemetry
  • 下行命令：tenant/{t}/device/{d}/cmd
  • 回执：tenant/{t}/device/{d}/cmd/ack

7.3 集成架构图

flowchart LR
  APIGW[API网关] --> DM[设备管理]
  APIGW --> RE[规则管理]
  APIGW --> OTA[OTA服务]
  APIGW --> RPT[报表]
  RE --> ALR[告警/工单]
  ALR --> WH[Webhook/通知]
  OTA --> OBJ[对象存储]
  TI[遥测采集] --> KFK[(Kafka)]
  KFK --> RE
  KFK --> TSDB[时序库]

8. 安全架构

• 认证：

  • 设备：mTLS（双向 TLS1.2+），设备证书（X.509），证书吊销/轮换；接入层验证证书与 CRL/OCSP。
  • 用户与第三方：OIDC/OAuth2；API Key；多因素认证（可选）。

• 授权：

  • RBAC（角色）、ABAC（属性：租户、设备组、标签）；细粒度资源权限。
  • API 网关实施策略；服务内二次校验。

• 数据保护：

  • 在途：TLS；命令与固件签名校验（防篡改）。
  • 在静：TSDB/RDB/Object 加密；KMS/HSM 管理密钥；最小留存与脱敏（PII、位置数据）。
  • 审计：所有敏感操作写入不可变审计日志；合规报告。

• 安全运营：

  • 秘钥轮换策略（设备证书、服务令牌）；漏洞扫描与镜像签名；供应链安全。
  • 网络分段与零信任：接入层、应用层、数据层隔离；安全组与策略。
  • 租户隔离：命名空间/资源配额；数据与主题分区隔离；速率限制与配额。

9. 可扩展性与性能

• 水平扩展：
  • 接入层按协议与地域扩展；Kafka/TSDB 分片与分区；微服务无状态化水平扩容。
• 分区与粘性：
  • Kafka 按租户/设备键进行粘性分区，保证设备消息顺序；消费者组扩展以吞吐。
• 恰好一次与幂等：
  • Kafka 事务 + Idempotent Producer；Outbox 模式；设备级序列号/幂等键。
• 缓存与批处理：
  • 边缘批量上传与断点续传；云端批写 TSDB；规则引擎窗口聚合。
• 低功耗优化：
  • 动态心跳；ACK 合并；命令合并与优先级；重传退避。
• 回压与限流：
  • 网关/接入对高负载施加回压；租户级速率限制；DLQ 与重试策略。
• 容量规划（示例）：
  • 接入层：每节点 50k 并发连接目标；集群 100 节点支撑 5M。
  • Kafka：每主题按 1k 分区规划；磁盘 IO 与网络冗余。
  • TSDB：冷热分层策略（7-30 天热数据，归档/压缩）与索引规划。

10. 部署与基础设施

• 环境拓扑：

flowchart TB
  subgraph Region A
    K8S_A[Kubernetes Cluster]
    MQTT_A[MQTT Broker Cluster]
    COAP_A[CoAP Gateways]
    KFK_A[Kafka Cluster]
    TSDB_A[TSDB Cluster]
    RDB_A[RDB HA]
    REDIS_A[Redis]
    OBJ_A[对象存储(区域化)]
    K8S_A --- MQTT_A
    K8S_A --- COAP_A
    K8S_A --- KFK_A
    K8S_A --- TSDB_A
    K8S_A --- RDB_A
    K8S_A --- REDIS_A
    K8S_A --- OBJ_A
  end
  subgraph Region B
    K8S_B[Kubernetes Cluster]
    MQTT_B[MQTT Broker Cluster]
    KFK_B[Kafka Cluster]
    TSDB_B[TSDB Cluster]
  end
  KFK_A <--> KFK_B
  TSDB_A <--> TSDB_B

• 部署原则：

  • 基于 IaC（Terraform）与 GitOps（ArgoCD）管理；蓝绿/金丝雀发布；有状态组件滚动升级与读写分离。
  • 多区域容灾：Kafka Mirror/Replicator；TSDB 异步复制；对象存储跨区域冗余。
  • 运维：集中审计与准入控制；变更窗口；演练剧本。

• 部署流程（简要）：

  1. 基础设施：VPC/子网/安全组 → K8S 集群 → 存储集群（Kafka/TSDB/Redis/RDB）。
  2. 平台服务：API 网关 → 身份与密钥 → 设备管理 → 接入层（MQTT/CoAP）。
  3. 数据管道：遥测采集 → 规则引擎 → 告警/工单 → 报表。
  4. 边缘侧：代理安装与注册 → 策略/规则下发。
  5. 观测：Prometheus/Grafana/Logging → SLO 校准。
  6. 演练：故障注入、切换、回滚测试。

11. 附录

11.1 Kafka 主题与分区建议

11.2 规则 DSL 示例（简要）

• 设备温度超阈值触发告警并下发降功耗命令：

WHEN telemetry.metric == "temp" AND telemetry.value > 80
THEN alert(severity="high", message="Overheat")
AND sendCommand(deviceId, "reduce_power", {"level": "medium"})

11.3 SLI/SLO

• 接入可用性 ≥ 99.95%
• 规则处理 P95 延迟 < 500ms
• TSDB 写入成功率 ≥ 99.9%
• OTA 成功率 ≥ 99%
• 云端 RPO ≤ 10 分钟；边缘缓冲 ≥ 24h

11.4 监控指标（部分）

• 设备在线率：在线设备数/总设备数
• MQTT/CoAP 队列滞留：每分区滞留消息
• 边缘健康：CPU、内存、缓存利用率、上传失败率
• 规则执行：处理吞吐、延迟、失败率
• OTA：下载失败率、校验失败率、回滚率
• TSDB：写入延迟、批量大小、压缩比
• API 网关：拒绝率、限流命中率、延迟

总结

本架构通过云边协同、事件驱动与微服务拆分，满足海量设备接入、低延迟规则处理与高吞吐存储的需求。以 mTLS 与签名保障端到端安全，以 Kafka 与 TSDB 实现可靠与可扩展的数据管道。统一 API 网关实现多租户治理与运营能力，配合完善的监控审计，确保平台在性能、可靠性、安全与合规方面达到既定目标。

云原生 B2B 多租户平台架构文档

版本: 1.0
作者: 技术架构组
日期: 2025-11-24

1. 执行摘要

本平台面向不同行业的企业客户提供统一的 B2B 多租户应用能力，支持快速开通、租户级个性化配置与扩展、严格的租户隔离以及高可靠与合规。平台运行在 Kubernetes 上，采用服务网格实现零信任通信与细粒度流量控制，通过 API 网关统一鉴权与路由，微服务架构支撑租户管理、账户与权限、配置中心、计费与用量、业务域服务、报表与导出、通知与集成等核心能力。

关键架构决策：

• 多租户数据层采用“混合租户模型”：小租户共享数据库（行级安全 + 分片），大租户采用专属实例/模式（schema）隔离，支持在线热迁移。
• 全链路零信任：网格内 mTLS、基于 OIDC 的统一身份与凭证、细粒度授权（RBAC/ABAC），权限变更实时生效（事件驱动下发）。
• 可观测与配额：租户级指标、分布式追踪、慢查询可见；按租户配额与配速（限流+配额）保障公平与稳定性。
• 合规与数据驻留：SOC 2 控制覆盖，按租户地区进行数据驻留与路由，导出文件以短期签名 URL 访问。
• 可扩展性：K8s 横向扩展，支持 1 万+ 租户并发，单租户 P95 < 200ms；网关与服务网格支持灰度与金丝雀发布；插件化集成与 Marketplace。

2. 系统概述

平台按“控制平面 + 多区域数据平面”划分：

• 控制平面：租户入驻、订阅/计费策略、全局配置、插件市场、API 文档与 SDK 生成、全局审计与合规模块。
• 数据平面（按区域部署）：租户运行时服务（账户与权限、业务域、报表与导出、通知/集成）、数据库与对象存储就近驻留、队列与缓存等基础设施。

高层架构图（逻辑视图）：

graph LR
  subgraph Edge
    CDN[CDN/WAF]
    AGW[API 网关]
  end

  subgraph Mesh[服务网格 (mTLS, 策略, 遥测)]
    ACC[账户与权限服务]
    TEN[租户管理服务]
    CFG[配置中心]
    BUS[业务域服务(若干)]
    BIL[计费与用量]
    RPT[报表与导出]
    NOT[通知与集成]
    OBS[可观测性代理]
    PLG[插件运行时]
  end

  QUE[消息队列(Kafka/NATS)]
  CCH[缓存(Redis/KeyDB)]
  OBJ[对象存储(S3/GCS)]
  subgraph DB[多租户数据层]
    SHD[(共享DB + RLS + 分片)]
    DED[(专属DB/Schema)]
  end

  CDN --> AGW
  AGW --> Mesh
  Mesh --> QUE
  Mesh --> CCH
  Mesh --> DB
  RPT --> OBJ
  NOT -->|邮件/短信/Webhook| Ext[(第三方服务)]

  subgraph ControlPlane[控制平面]
    OP[租户/资源编排器(Operator)]
    FF[功能开关/灰度]
    MKP[Marketplace]
    DOC[API 文档/SDK 生成]
  end
  TEN <-->|注册/开通| OP
  PLG <-->|安装/更新| MKP
  ACC --> FF
  AGW --> FF
  DOC --> AGW

3. 架构目标与约束

目标与需求：

• 性能：支持 1 万+ 租户并发；单租户常规操作 P95 < 200ms。
• 隔离与安全：逻辑与物理双重隔离；跨租户访问强制阻断；零信任通信，审计可追溯。
• 可扩展性：自动选择共享或专属模式；在线热迁移；弹性扩容。
• 合规与数据驻留：覆盖 SOC 2 控制；数据驻留满足客户地区要求。
• 可靠性：备份周期 6 小时；RPO ≤ 15 分钟；RTO ≤ 45 分钟；定期演练。

假设：

• 主要后端使用 Node.js/Go；前端为单页应用（SPA）+ 服务端渲染（SSR）。
• 数据库支持行级安全（RLS）与细粒度审计（推荐 PostgreSQL）。
• 服务间通信在服务网格内（如 Istio/Linkerd），统一 mTLS。

约束：

• 不允许跨租户共享缓存键（必须带租户前缀）。
• 导出文件通过短期签名 URL 访问。
• 权限变更需实时生效（秒级）。

4. 架构模式与风格

• 微服务架构 + 事件驱动（CQRS/异步处理关键路径外任务）。
• 云原生 12 要素应用，声明式配置与 GitOps。
• 零信任网络：身份优先、最小权限、持续验证。
• 多租户混合模型：共享数据库 + 行级安全 + 分片；大租户专属实例/Schema。
• 观测优先：指标、日志、追踪三大支柱，租户标签贯穿链路。
• 弹性可靠：幂等、重试、断路器、舱壁隔离、背压、限流。

5. 系统组件

下表概述组件职责与交互，随后附统一内部结构图。

• API 网关
  • 职责：统一入口、路由、WAF、速率限制、OAuth2/OIDC 验证、金丝雀/灰度、流量镜像。
  • 交互：前端/第三方客户端、服务网格、功能开关服务、审计。
• 租户管理服务（Tenant Service）
  • 职责：租户生命周期、一键开通、数据驻留策略、隔离级别决策、热迁移编排。
  • 交互：编排器、数据库路由、计费与用量、配置中心。
• 账户与权限服务（Identity & AuthZ）
  • 职责：用户/组织、RBAC/ABAC、SSO/OIDC、SCIM、令牌签发、权限策略实时分发。
  • 交互：API 网关、业务服务、策略缓存、审计。
• 配置中心（Config Center）
  • 职责：租户/环境/版本化配置，动态生效；功能开关；Schema 扩展与自定义字段。
  • 交互：所有业务服务、Marketplace、审计。
• 计费与用量（Billing & Usage）
  • 职责：订阅计划、配额、用量计量、账单生成、超额控制、限流联动。
  • 交互：网关（限流）、业务服务（用量事件）、支付网关。
• 业务域服务（Domain Services, 多个）
  • 职责：各垂直业务能力，遵循租户上下文与数据驻留。
  • 交互：身份授权、配置中心、缓存/队列/数据库、报表。
• 报表与导出（Reporting & Export）
  • 职责：可视化报表、预聚合、批量导出；生成短期签名 URL。
  • 交互：对象存储、队列、数据库、计费（大任务配额）。
• 通知与集成（Notification & Integration）
  • 职责：邮件/短信/Webhook 连接器、重试与幂等、失败回执。
  • 交互：第三方通道、队列、审计。
• 插件运行时与市场（Plugin Runtime & Marketplace）
  • 职责：插件注册/安装/版本发布；隔离运行（容器或 WASM）；受限权限访问。
  • 交互：配置中心、业务服务（扩展点）、对象存储（包分发）、签名与验签。
• 可观测性（Observability）
  • 职责：指标、日志、追踪；租户级查询；慢查询采样；错误预算。
  • 交互：所有服务、告警通道。
• 数据平面设施
  • 职责：数据库（PostgreSQL+Citus/分片）、缓存（Redis）、队列（Kafka/NATS）、对象存储（S3/GCS）。
  • 交互：所有服务。

组件内部结构与交互（统一视图）：

flowchart LR
  subgraph API[API 网关]
    WAF[WAF/规则]
    OIDC[OIDC 验证]
    RL[分布式限流(租户维度)]
    ROUTE[路由/金丝雀]
  end

  subgraph AuthZ[账户与权限]
    IdP[IdP/OIDC/SSO]
    RBAC[RBAC/ABAC 引擎(OPA/Cedar)]
    CACHE[pdp缓存/订阅]
  end

  subgraph Tenant[租户管理]
    Prov[开通/迁移编排]
    Policy[数据驻留/隔离策略]
    Router[DB路由表]
  end

  subgraph Config[配置中心]
    Ver[版本化配置]
    Flag[功能开关]
    Schema[扩展字段/校验]
  end

  subgraph Billing[计费与用量]
    Plan[套餐/计费项]
    Meter[用量上报/聚合]
    Invoice[账单]
  end

  subgraph Domain[业务域服务]
    API1[API]
    Worker[异步作业]
  end

  subgraph Report[报表与导出]
    PreAgg[预聚合]
    Export[导出任务]
  end

  subgraph Notify[通知与集成]
    Email[邮件]
    SMS[短信]
    WH[Webhook]
  end

  Q[(队列)]
  R[(缓存)]
  S3[(对象存储)]
  DB[(Postgres: 共享分片+专属实例)]
  Mesh[(服务网格 mTLS/策略/遥测)]

  API --> Mesh
  Mesh --> AuthZ
  Mesh --> Tenant
  Mesh --> Config
  Mesh --> Billing
  Mesh --> Domain
  Domain --> Q
  Domain --> R
  Domain --> DB
  Report --> Q
  Report --> S3
  Notify --> Q
  Notify --> WH
  AuthZ --> R
  Tenant --> DB
  Billing --> DB
  Config --> R

说明：

• 所有内部通信经服务网格，启用 mTLS 与细粒度授权策略。
• 限流与配额在网关与计费服务联动执行（租户维度）。
• 权限引擎采用本地缓存 + 事件订阅，确保变更秒级生效。

6. 数据模型与流

关键实体（简化展示）：

• Tenant（租户）、TenantRegion（驻留区域）、TenantIsolation（隔离级别）
• User、Org（组织）、Role、Policy、Permission、ApiClient
• Subscription、Plan、Quota、UsageRecord、Invoice
• ConfigItem（版本化配置）、FeatureFlag、SchemaExtension
• AuditEvent、LoginEvent
• Job、ExportTask、ReportView
• IntegrationConnector、WebhookEndpoint、DeliveryAttempt
• DbShard、DbInstance、ShardMapping
• ObjectFile（导出/附件）、PresignedUrl

ER 模型图（核心关系）：

erDiagram
  TENANT ||--o{ USER : "has"
  TENANT ||--o{ ORG : "has"
  ORG ||--o{ USER : "member"
  USER ||--o{ ROLE : "assigned"
  ROLE ||--o{ PERMISSION : "grants"
  POLICY ||--o{ ROLE : "binds"
  TENANT ||--|| TENANTREGION : "resides_in"
  TENANT ||--|| TENANTISOLATION : "isolation"

  TENANT ||--|| SUBSCRIPTION : "has"
  SUBSCRIPTION }o--|| PLAN : "of"
  SUBSCRIPTION ||--o{ QUOTA : "defines"
  TENANT ||--o{ USAGERECORD : "emits"
  TENANT ||--o{ INVOICE : "billed"

  TENANT ||--o{ CONFIGITEM : "versioned"
  TENANT ||--o{ FEATUREFLAG : "targets"
  TENANT ||--o{ SCHEMAEXTENSION : "custom_fields"

  TENANT ||--o{ AUDITEVENT : "logs"
  USER ||--o{ AUDITEVENT : "actor"

  TENANT ||--o{ JOB : "async"
  TENANT ||--o{ EXPORTTASK : "reports"
  EXPORTTASK ||--|| OBJECTFILE : "outputs"

  TENANT ||--o{ INTEGRATIONCONNECTOR : "uses"
  INTEGRATIONCONNECTOR ||--o{ WEBHOOKENDPOINT : "provides"
  WEBHOOKENDPOINT ||--o{ DELIVERYATTEMPT : "delivers"

  TENANT ||--o{ SHARDMAPPING : "mapped_to"
  SHARDMAPPING }o--|| DBINSTANCE : "on"

数据流（示例）：

• 在线读写请求：API 网关校验 → 服务网格 → 业务服务读取租户上下文 → DB 路由选择共享/专属库 → 访问数据库 → 响应。
• 报表导出：用户请求 → 生成导出任务 → 异步 Worker 处理 → 对象存储生成文件 → 计费上报用量 → 返回短期签名 URL。
• 权限变更：管理员调整角色/策略 → 权限服务持久化 → 事件总线发布 → 各服务策略缓存收到推送立即失效/刷新 → 实时生效。
• 租户热迁移：编排器创建新目标库 → CDC/双写或日志回放 → 切换 DB 路由 → 回收旧资源。

请求-响应序列图（简化）：

sequenceDiagram
  participant B as Browser/SDK
  participant G as API网关
  participant S as 业务服务
  participant T as 租户管理/DB路由
  participant A as 权限服务
  participant D as 数据库

  B->>G: 请求 + OIDC Token + tenant_id
  G->>A: 验证Token/权限(租户上下文)
  A-->>G: OK + Claims(ABAC)
  G->>S: 透传租户上下文(Headers)
  S->>T: 查询租户DB路由/隔离模式
  T-->>S: 共享/专属连接信息
  S->>A: 检查细粒度权限(资源/属性)
  A-->>S: 允许
  S->>D: 带 RLS 的查询/写入
  D-->>S: 结果
  S-->>G: 响应
  G-->>B: 200 OK

缓存键规范：

• 必须包含租户维度：t:{tenantId}:{namespace}:{key}，禁止跨租户共享。
• 变更事件驱动失效：policy_update、config_update、feature_flag_update、quota_update。

7. 集成与接口

内部通信：

• 同步：HTTP/gRPC（服务网格内 mTLS，基于 SPIFFE/SPIRE 身份）。
• 异步：Kafka/NATS 事件主题（按租户分区键，确保有序性）。

外部接口：

• API：OpenAPI 3.x 定义，自动生成 SDK（TS/Go/Java/Python）；速率限制与配额按租户与客户端区分。
• 认证：OIDC/OAuth2（Auth Code + PKCE，Client Credentials 用于服务器对服务器），SCIM 用于用户同步。
• Webhook：可配置事件订阅，重试与签名校验（HMAC-SHA256）。
• 通知：SMTP/邮件服务、SMS 提供商、Webhook 自定义。
• 对象存储：导出/附件使用 S3/GCS，短期签名 URL（默认 5 分钟有效），最小权限策略。

集成架构图：

graph LR
  API[OpenAPI/REST gRPC] --> SDK[SDK 生成器]
  SDK --> Dev[第三方/客户集成]
  Webhook[Webhook 事件] --> ExtSys[客户/第三方系统]
  SCIM[SCIM 目录同步] --> IdP[企业IdP]
  OIDC[OIDC/OAuth2] --> IdP
  Email[邮件] --> ESP[邮件服务商]
  SMS[短信] --> SMSP[短信网关]

8. 安全架构

• 身份与认证
  • 外部：OIDC/OAuth2，与企业 IdP（Azure AD/Okta）对接；多因素认证（MFA）。
  • 内部：服务网格签发的工作负载身份（SPIFFE ID），强制 mTLS。
• 授权
  • RBAC + ABAC：角色与属性（租户、组织、数据标签）结合；策略语言建议 OPA Rego 或 Cedar。
  • 策略变更实时下发：事件总线 + 本地 PDP 缓存，TTL 秒级；强制缓存失效通道。
• 数据保护
  • 传输层：TLS1.2+，网格内 mTLS。
  • 存储层：静态加密（数据库 TDE/卷加密、对象存储 SSE-KMS），敏感字段列级/应用层加密（Envelope per-tenant 可选）。
  • 行级安全（RLS）：数据库策略强制 tenant_id 过滤，不可信默认拒绝。
• 隔离与最小权限
  • 共享数据库：强制 RLS + schema 限制；大租户专属实例/Schema。
  • 插件沙箱：容器/WASM，限制网络、文件与密钥访问，通过受控 gRPC 接口调用。
• 安全运维
  • 秘钥管理：KMS + Vault；密钥轮换与最小暴露。
  • 审计：管理/数据访问/配置变更全量审计，支持合规报表。
  • 供应链安全：镜像签名（Sigstore/Cosign）、SBOM、镜像准入策略。
  • 边界防护：WAF、Bot 防护、API 签名（可选）。

9. 可扩展性与性能

• 扩展策略
  • 横向扩展：HPA（CPU/内存/自定义指标），KEDA 驱动队列消费者。
  • 数据库：Citus/分片按 tenant_id 哈希；热门租户可迁移至专属实例/Schema；读写分离与连接池（PgBouncer）。
  • 缓存：按租户命名空间；热点键本地缓存 + 版本戳。
• 性能优化
  • 关键路径内仅做轻量校验与路由；重任务异步化（报表、导出、通知）。
  • 预聚合（物化视图/Columnar 引擎如 ClickHouse 可选）加速报表。
  • N+1 查询避免；索引与分区（按 tenant_id + 时间）。
  • 网关与网格：连接复用、压缩、超时/重试/断路器合理配置。
• 容量规划
  • 租户画像：小/中/大租户基线资源与突发系数；配额控制峰值。
  • SLO：P95 < 200ms；错误预算驱动发布节奏。
• 权限变更实时性
  • 事件总线直达各服务 PDP；本地缓存 TTL 1~5s，变更触发主动失效；客户端通过 SSE/WebSocket 刷新。

10. 部署与基础设施

• 基础设施
  • Kubernetes（多区域集群）；服务网格（Istio/Linkerd）；Ingress（Envoy/Nginx）。
  • 数据库 PostgreSQL（主从、分片/Citus）、Redis、Kafka/NATS、对象存储 S3/GCS。
  • 证书管理（cert-manager）、密钥管理（KMS + Vault）。
• 部署模型
  • 控制平面（全局）+ 多区域数据平面（按驻留地区）。
  • GitOps：Terraform（底座）、Helm/Argo CD（应用）；环境分层（dev/staging/prod）。
  • 发布策略：蓝绿/金丝雀（网关/网格流量分配 + 功能开关）；回滚一键化。
• 租户一键开通流程
  • 触发：控制台/API。
  • 编排器创建：命名空间/配额/路由条目，选择共享或专属数据库，初始化配置与默认策略，生成观测标签与告警规则。
• 备份与恢复
  • 数据库：基础全量快照（每 6 小时）+ 增量/PITR；RPO ≤ 15 分钟；RTO ≤ 45 分钟。
  • 共享库的租户级恢复：逻辑备份（按 tenant_id 导出）+ 影子库重放 + 验证后回切。
  • 对象存储版本化与生命周期策略。
• 灰度与功能开关
  • 以租户/用户/比例为维度；支持影子写入与读写分流。
• 可观测与运维
  • Prometheus + Loki/ELK + Tempo/Jaeger；Grafana 大盘（含租户过滤）。
  • SLO/告警：延迟、错误率、饱和度、队列滞留、慢查询。

多区域部署图：

graph TD
  CP[控制平面: 编排/市场/文档/全局审计]
  subgraph R1[区域A 数据平面]
    AG1[API网关]
    M1[服务网格]
    SVC1[服务集合]
    DB1[DB分片/专属]
    C1[缓存]
    Q1[队列]
    S31[S3桶A]
  end
  subgraph R2[区域B 数据平面]
    AG2[API网关]
    M2[服务网格]
    SVC2[服务集合]
    DB2[DB分片/专属]
    C2[缓存]
    Q2[队列]
    S32[S3桶B]
  end

  CP --> R1
  CP --> R2
  USERS[全球用户] --> CDN[CDN/WAF] --> |驻留策略| AG1
  USERS --> CDN --> |驻留策略| AG2

11. 附录

A. 关键接口与事件

• 认证与令牌：/oauth2/authorize, /oauth2/token, /userinfo
• 租户：POST /tenants（开通）、POST /tenants/{id}/migrate（热迁移）
• 权限：PUT /tenants/{id}/roles, POST /policies
• 配置：PUT /tenants/{id}/config?version=…，GET /flags
• 计费：POST /usage, GET /invoices
• 报表：POST /exports, GET /exports/{id}/url（返回短期签名 URL）
• 通知：POST /webhooks/endpoints, 回调签名 Header：X-Signature
• 事件主题（Kafka/NATS）：
  • tenant.created/updated/migrated, policy.updated, config.updated, flag.updated
  • usage.recorded, quota.exceeded, export.completed, webhook.delivery_failed

B. 数据库分片与路由策略

• ShardKey：tenant_id 哈希；热租户支持 sticky shard 与专属库切换。
• 路由表：Tenant → {SharedShard|DedicatedDB, Region, RLSPolicy}，由租户管理服务维护并带版本号。

C. 缓存策略

• Key 格式：t:{tenantId}:{svc}:{entity}:{id}
• 失效：事件驱动 + TTL；权限与配置强制事件触发失效。

D. 灰度发布与回滚

• 金丝雀：按租户/比例切流；失败自动回滚（错误预算门槛）。
• 功能开关：服务端评估，确保一致性；客户端 SDK 缓存并订阅增量更新。

E. 安全基线与合规

• SOC 2 控制项映射：访问控制、变更管理、日志审计、备份恢复、可用性与完整性。
• 数据驻留：租户元数据包含 region，边缘路由选择最近合规区域；跨域访问默认拒绝。

F. 典型时序：租户热迁移（简化）

sequenceDiagram
  participant Admin as 管理员
  participant OP as 编排器
  participant TS as 租户服务
  participant DB as DB集群
  participant APP as 业务服务

  Admin->>OP: 请求迁移(tenant T -> 专属DB)
  OP->>TS: 创建目标DB/Schema, 初始化
  TS->>DB: 建立CDC/逻辑复制
  OP->>APP: 配置双写(可选阶段)
  DB-->>TS: 同步完成信号(滞后<阈值)
  OP->>APP: 短暂停写(瞬时)
  OP->>TS: 切换路由表(版本+1)
  TS-->>APP: 新连接信息
  OP->>APP: 恢复写入
  OP-->>Admin: 迁移完成

G. 术语说明

• RPO（恢复点目标）：灾难后允许的数据丢失时间窗口。
• RTO（恢复时间目标）：从故障到恢复服务的时间目标。
• RLS（行级安全）：数据库级按行限制访问策略。
• HPA/KEDA：K8s 自动扩缩容机制（基于指标/队列）。

本架构文档覆盖了系统目的、组件、交互、数据模型、集成、安全、可扩展性与部署要求，且与给定约束一致。后续迭代将补充更细的 SLA 指标、运行手册、灾备演练剧本与合规证据库映射。