云平台系统设计文档

1. 概述

1.1. 文档目的

本文档旨在为正在构建的云平台（下文简称“平台”）提供一个全面的系统级设计蓝图。它将涵盖平台的总体架构、核心功能模块以及关键技术选型，作为后续开发、部署和运维的指导性文件。

1.2. 平台愿景

我们的目标是构建一个稳定、安全、可扩展的云平台，为用户提供包括 IaaS（基于 PVE 和 Hyper-V 的统一云服务器）和 SaaS（基于 Kubernetes 的容器化应用支持）在内的一站式云服务。

2. 总体架构

2.1. 架构原则

平台设计遵循以下核心原则：

• 微服务化：将平台功能拆分为一系列高内聚、低耦合的独立服务，便于独立开发、部署和扩展。

• 云原生优先：优先采用容器化、自动化、可观测性等云原生技术和实践。

• 安全为本：将安全设计贯穿于架构的每一层，从入口流量到内部通信，再到数据存储。

• 高可用性：通过冗余设计、负载均衡和故障转移机制，确保关键服务的持续可用。

2.2. 架构分层图

+------------------------------------------------------+
|                      客户端层                          |
|    (Web Console, CLI, Terraform Provider, API User)    |
+------------------------------------------------------+
                              |
                              v
+------------------------------------------------------+
|                    接入与网关层                        |
|        (API Gateway - Traefik, L4/L7 Load Balancer)  |
+------------------------------------------------------+
                              |
                              v
+------------------------------------------------------+
|                  服务层 (主控平台)                     |
|  (统一认证授权, 计算, 容器, 存储, 网络, 计费, 监控)   |
+------------------------------------------------------+
                              |
                              v
+------------------------------------------------------+
|                 基础设施层 (受控节点)                  |
|     (PVE 虚拟化, Hyper-V 虚拟化, K8s 集群, 分布式存储) |
+------------------------------------------------------+

3. 统一认证授权系统

3.1. 设计选型

• 核心框架: 平台选用业界主流的 OAuth 2.0 授权框架和 OpenID Connect (OIDC) 身份认证协议。所有颁发的访问凭证将采用 JSON Web Token (JWT) 格式，以实现无状态、可扩展的认证机制。

• 技术实现: 推荐使用 Casdoor 作为认证授权中心的具体实现。Casdoor 是一个功能全面的开源 IAM 解决方案，它开箱即用地支持本项目所需的全部认证模式（授权码、设备码、客户端凭证等），并提供了完整的用户管理、角色权限和多租户能力，可以显著加快开发进度。

3.2. 系统架构与部署

系统核心组件的职责与部署位置明确如下：

• 认证授权中心 (Auth Service - Casdoor): 负责身份管理和令牌签发的独立服务。该服务将部署在主控（Controller）微服务集群中，作为平台统一的身份认证源。

• 主控平台服务 (Master Control Services): 平台的各个业务微服务，如计算、存储、网络服务的控制面 API。它们是 IAM 的客户端，同时也是策略执行点 (Policy Enforcement Point - PEP)，负责执行面向最终用户的、精细化的业务授权逻辑。

• 受控节点 (Controlled Nodes): 基础设施层面的执行单元，例如虚拟机管理程序、存储服务器等。它们在架构中扮演资源服务器 (Resource Server) 的角色，仅负责验证来自主控的指令是否合法，不处理终端用户的具体权限。

• 客户端 (Clients): 需要访问平台API的任何应用或服务，如 Web 控制台、CLI 工具等。

3.3. 核心概念解析

• OAuth 2.0 & OpenID Connect (OIDC)：授权与认证的开放标准。OIDC 构建于 OAuth 2.0 之上，专注于用户身份认证。

• JSON Web Token (JWT)：一种紧凑且自包含的令牌格式，用于在各方之间安全地传递身份和权限声明。

• JWKS (JSON Web Key Set)：由认证中心提供的、用于发布 JWT 验签公钥的标准化端点。API 网关和各资源服务通过此端点动态获取公钥，实现对 JWT 的本地化、离线验证。

3.4. 认证授权模式详解

平台的认证授权遵循两种核心模式，以应对不同的交互场景。

3.4.1. 模式一：用户-平台交互 (User-to-Platform)

此模式处理终端用户（如系统管理员）通过客户端与主控平台进行的交互。

• 核心流程:

  1. 用户通过客户端（Web 控制台/CLI）向认证中心 (Casdoor) 请求登录和授权。

  2. 认证中心验证用户身份后，向客户端颁发一个包含用户身份信息（如用户ID、角色）的 用户令牌 (User JWT)。

  3. 客户端携带此 User JWT 访问主控平台的业务 API（例如，“删除虚拟机”）。

  4. 主控平台的 API 网关首先验证 User JWT 的合法性（认证）。

  5. 请求到达具体的业务服务后，由该业务服务执行最终的授权决策。服务会解析 User JWT 中的信息，并结合自身的业务逻辑（例如，查询数据库确认该虚拟机是否属于该用户，或用户角色是否有权操作该项目资源）来判断用户是否有权执行该操作。

  6. 在此流程中，IAM 负责回答 “你是谁？”，而主控业务服务负责回答 “你能做什么？”。

• 交互图:

+--------------+    (1) Login via Browser   +----------------+
|   终端用户   | ---------------------->  | 认证中心(Casdoor) |
+--------------+    <---------------------- +----------------+
      |            (2) Return User JWT
      |
      | (3) Request with User JWT (e.g., Delete VM)
      v
+--------------------------------------------+
|                主控平台 (Controller)           |
| +----------------+     +------------------+ |
| | API Gateway    | ->  |  业务服务(Compute)| |
| | (Validate JWT) |     | (Authorize User) | |
| +----------------+     +------------------+ |
+--------------------------------------------+

3.4.2. 模式二：主控-受控交互 (Machine-to-Machine, M2M)

此模式处理主控平台内部服务向下游的受控节点发送控制指令的场景，是平台内部自动化和系统命令执行的基础。

• 核心流程:

  1. 当主控业务服务在完成对用户请求的授权检查后，需要向受控节点发送具体指令（如物理创建虚拟机）。

  2. 主控服务以自己的机器身份（使用预先配置的 Client ID/Secret）向认证中心 (Casdoor) 请求令牌，采用 客户端凭证模式 (Client Credentials Flow)。

  3. 认证中心验证其身份后，颁发一个代表“主控服务”身份的机器令牌 (Machine JWT)。此令牌生命周期通常很短（例如5-10分钟），以降低泄露风险。

  4. 主控服务携带此 Machine JWT 调用受控节点的 API。

  5. 受控节点只做认证，不做授权。它接收到请求后，使用认证中心的公钥验证 Machine JWT 的签名和有效期，以确认指令来源是合法的主控服务。

  6. 受控节点完全信任主控已经完成了对原始用户的所有权限检查，验证通过后便直接执行指令。该模型实现了清晰的职责分离和信任委托。

• 交互图:

+--------------------------------+     (1) Request Token       +----------------+
|  主控业务服务 (e.g. Compute)   | -------------------------> | 认证中心(Casdoor) |
| (Authorization Logic Complete) | <------------------------- | (Client Credentials) |
+--------------------------------+   (2) Return Machine JWT    +----------------+
                 |
                 | (3) Send Command with Machine JWT
                 |
                 v
+--------------------------------+
|       受控节点 (Hypervisor)      |
|  (Authenticate Machine JWT,    |
|     then execute command)      |
+--------------------------------+

3.5. 典型应用场景映射

• 场景一：用户登录Web控制台 (采用授权码模式)

  • 对应模式: 完全遵循 3.4.1 用户-平台交互模式。

• 场景二：开发者使用CLI (采用设备授权模式)

  • 对应模式: CLI 获取用户令牌的过程遵循设备授权流程，但后续与主控API的交互依然是 3.4.1 用户-平台交互模式。

• 场景三：内部服务间调用 (主控 -> 受控) (采用客户端凭证模式)

  • 对应模式: 完全遵循 3.4.2 主控-受控交互模式。

4. 计算服务 (IaaS)

4.1. 概述

计算服务是平台的核心 IaaS 能力，旨在将底层的 PVE (Proxmox VE) 和 Hyper-V 等异构虚拟化资源抽象为统一、标准化的云服务器（VM）资源。本服务负责云服务器的完整生命周期管理，向用户提供声明式的、与底层平台无关的资源操作体验。

4.2. 核心设计理念

4.2.1. 声明式 API 与协调循环 (Declarative API & Reconciliation Loop)

平台摒弃传统的命令式操作，采用声明式 API 模型。用户只需声明其“期望状态”（例如，“我需要一个 2C4G、状态为 RUNNING 的云服务器”），而无需关心底层的实现步骤。

• 唯一真相来源 (Single Source of Truth)：平台数据库是所有资源“期望状态”和“最后观测状态”的唯一权威记录。

• 协调循环 (Reconciliation Loop)：一个持续运行的后台进程，其核心职责是：

  1. 观察(Observe)：定期查询底层 PVE/Hyper-V 的真实状态。

  2. 比较(Compare)：将真实状态与数据库中的期望状态进行对比。

  3. 行动(Act)：如果存在差异，则调用底层 API 进行修正，使真实世界与期望状态保持一致。

4.2.2. 资源生命周期状态机 (Resource Lifecycle State Machine)

为确保所有操作的可追踪性和可管理性，我们为云服务器等核心资源定义了明确的状态机。

• 核心思想: 任何一个复杂、异步的操作（如创建VM）都被建模为一系列状态的转换。

• 状态机位置: 状态机逻辑和状态数据完全驻留在主控端（Controller），由主控服务进行集中管理和决策。受控节点不维护任何上层状态。

• 核心状态示例:

  • PENDING_CREATE: 等待创建

  • CREATING: 创建中

  • RUNNING: 运行中

  • STOPPING: 停止中

  • STOPPED: 已停止

  • DELETING: 删除中

  • ERROR: 错误状态

  • UNKNOWN: 因受控节点失联等原因导致的未知状态

4.2.3. 分布式事务与 Saga 模式 (Distributed Transactions & Saga Pattern)

跨越平台数据库和底层虚拟化平台的任何操作本质上都是一个分布式事务。为保证数据一致性和操作的原子性，平台采用 Saga（长事务）模式。

• 核心思想: 将一个大的分布式事务拆分为多个小的、本地的子事务。每个子事务都有一个对应的**补偿事务（Compensating Transaction）**用于回滚。

• 工作流程:

  1. 主控端按顺序执行一系列操作（如：更新数据库状态 -> 创建磁盘 -> 创建网卡 -> 创建VM配置）。

  2. 若任何一步失败，Saga 协调器会反向调用已成功步骤的补偿操作（如：删除VM配置 -> 删除网卡 -> 删除磁盘 -> 更新数据库状态为 ERROR）。

  3. 这确保了即使操作中途失败，系统也能回退到一致的初始状态，不会产生“孤儿”资源。

4.3. 架构组件

计算服务遵循清晰的主控-受控（Master-Agent）架构。

• 4.3.1. 计算主控服务 (Compute Controller)

  • 职责: 平台的“大脑”。负责接收 API 请求，管理资源的状态机，运行协调循环，编排 Saga 工作流，并执行调度决策（决定VM在哪台物理机上创建）。

• 4.3.2. 统一适配器层 (Unified Adapter Layer)

  • 职责: 位于主控服务内部，作为翻译层。它将平台内部的通用指令（如 CreateVM）翻译成特定虚拟化平台（PVE/Hyper-V）的 API 调用。这是实现异构平台统一管理的关键。

• 4.3.3. 受控端 (Node Agent / Hypervisor API)

  • 职责: 平台的“手和脚”。它们是部署在物理机上的轻量级代理或直接暴露的 Hypervisor API 端点。它们只负责执行来自主控端的、具体的、原子化的指令（如 qm create 100...），并向主控端报告执行结果和本地资源状态。受控端是无状态的，不包含任何复杂的业务逻辑。

4.4. 核心流程示例：创建云服务器

1. 请求: 用户通过平台 API 发起一个创建 VM 的请求。

2. 持久化: API 服务在数据库中创建一条 VM 记录，初始状态为 PENDING_CREATE。

3. 调度: 计算主控服务的调度器根据负载策略，选择一个合适的物理节点（PVE 或 Hyper-V 主机）。

4. 启动 Saga: 主控服务启动“创建VM”的 Saga 事务，并将数据库中的 VM 状态更新为 CREATING。

5. 指令下发: 主控服务通过适配器层，将创建任务分解为原子指令（如创建磁盘、配置网络），并携带机器令牌（Machine JWT）依次发送给目标节点的 Agent。

6. 执行与报告: 节点 Agent 验证令牌后执行指令，并将结果报告给主控服务。

7. 状态更新/回滚:

   • 成功: 所有步骤成功后，主控服务将数据库中的 VM 状态更新为 RUNNING。

   • 失败: 任何步骤失败，主控服务将触发补偿流程，回滚已执行的操作，并最终将状态更新为 ERROR。

4.5. 技术栈

• 虚拟化: PVE, Hyper-V

• 服务框架: Go, Kratos

• 数据库: PostgreSQL 或 TiDB（用于存储平台状态数据）

5. 容器服务 (SaaS)

(本章节待详细设计)

5.1. 概述

本服务为用户提供标准的 Kubernetes 集群管理能力，支持应用的容器化部署和管理。

5.2. 核心功能

• 集群管理：创建、扩缩容、升级和删除 K8s 集群。

• 应用市场：提供常用应用的 Helm Chart 一键部署。

• CI/CD 集成：与主流的 DevOps 工具链打通。

5.3. 技术栈

• 容器编排：Kubernetes

• 服务框架：Go, Kratos

6. 其他核心服务

(以下各章节待详细设计)

6.1. 存储服务

• 块存储：为云服务器提供高性能、可挂载的云硬盘。

• 对象存储：提供海量、低成本的非结构化数据存储服务。

6.2. 网络服务

• 虚拟私有云 (VPC)：为租户提供逻辑隔离的网络空间。

• 安全组：实现实例级别的网络访问控制。

• 负载均衡：提供流量分发服务。

6.3. 监控与告警系统

• 负责采集平台所有资源和服务的性能指标及日志。

• 提供可视化仪表盘和灵活的告警通知机制。

6.4. 计费系统

• 负责对用户使用的各类资源进行精确计量和计费。

• 提供账单查询、支付和预算管理功能。