optimize: 七牛云文档排版优化 - 添加mermaid图表和note提示框

docs/qiniu-cloud/ansible-automation.md

@@ -6,28 +6,41 @@
 
 ## 一、整体结构
 
+```mermaid
+graph TD
+    Root["ansible/"] --> MF["gather-host-facts.yml"]
+    Root --> GF["group_vars/all.yml"]
+    Root --> PG["postgresql-deploy.yml"]
+    Root --> PG_R["postgresql-rollback.yml"]
+    Root --> Tasks["tasks/cleanup-controller-ssh-key.yml"]
+    Root --> Tpl["templates/postgresql-instance.conf.j2"]
+
+    Root --> MySQL["mysql/"]
+    Root --> PGHA["postgresql_ha/"]
+
+    MySQL --> M Deploy["deploy.yml"]
+    MySQL --> M Pre["precheck.yml"]
+    MySQL --> M Fail["failover.yml"]
+    MySQL --> M Roll["rollback.yml"]
+    MySQL --> M Conf["config-apply.yml"]
+    MySQL --> Mvars["vars/ / tasks/ / templates/ / files/"]
+
+    PGHA --> P Deploy["deploy.yml"]
+    PGHA --> P Pre["preflight.yml"]
+    PGHA --> P Accept["final_acceptance.yml"]
+    PGHA --> P Switch["control-switchover.yml"]
+    PGHA --> P Restart["control-restart.yml"]
+    PGHA --> P Clean["cleanup.yml"]
+
+    style Root fill:#e1f5fe
+    style MySQL fill:#fff3e0
+    style PGHA fill:#e8f5e9
 ```
-ansible/
-├── README.md
-├── gather-host-facts.yml              # 目标主机事实采集
-├── inventory.example.yml              # MySQL 本地运行示例 inventory
-├── group_vars/all.yml                 # 全局变量（SSH 密钥管理）
-├── postgresql-deploy.yml              # 单机/主从 PostgreSQL 交付入口
-├── postgresql-rollback.yml            # PostgreSQL 单机/主从回滚
-├── files/
-│   └── postgresql-xinfra@.service     # PostgreSQL systemd 模板单元
-├── tasks/
-│   └── cleanup-controller-ssh-key.yml # 跨服务复用：清理控制端临时 SSH 私钥
-├── templates/
-│   └── postgresql-instance.conf.j2    # 单机/主从 PostgreSQL 配置模板
-├── mysql/                             # MySQL 自动化（独立子目录）
-│   ├── deploy.yml / precheck.yml / rollback.yml / failover.yml / ...
-│   ├── vars/ / tasks/ / templates/ / files/
-└── postgresql_ha/                     # PostgreSQL HA 集群
-    ├── deploy.yml / preflight.yml / cleanup.yml / final_acceptance.yml
-    ├── control-switchover.yml / control-restart.yml / control-acceptance.yml
-    ├── templates/ / inventory.yml / galaxy.yml / README.md
-```
+
+!!! note "💡 三套自动化体系"
+    - `mysql/` — MySQL 原生交付（11 个 Playbook），覆盖部署/回滚/故障切换/巡检/配置变更等
+    - `postgresql-deploy.yml` — 轻量级单机/主从 PostgreSQL 交付
+    - `postgresql_ha/` — 生产级 PostgreSQL HA 集群（Patroni + etcd + HAProxy + Keepalived + pgBackRest）
 
 **角色划分：**
 - `mysql/` — 完整的 MySQL 原生交付生命周期
@@ -44,6 +57,9 @@ ansible/
 | Playbook | 职责 |
 |----------|------|
 | `deploy.yml` | 唯一部署入口：回调(precheck) → 参数校验 → MHA 制品安装 → 回调(install) → MySQL 二进制安装 → 回调(configure) → 账号配置 → 复制配置 → MHA 配置 → 回调(healthcheck) → TCP 端口检查 → 回调(register) |
+
+!!! note "💡 Deploy 流水线"
+    `deploy.yml` 是 MySQL 唯一部署入口，通过回调机制（callback.yml）向 AWX 上报进度。每个阶段都有独立回调，支持前端实时追踪任务状态。
 | `precheck.yml` | 只读预检查：Python 脚本检查磁盘空间、内存、端口、制品可用性、目录冲突，输出结构化 JSON |
 | `rollback.yml` | 回滚：停止 MHA Manager → 清理 SSH 授权 → 删除 MHA 工作目录 → 停止实例 → 删除配置/二进制/数据/运行时目录 |
 | `failover.yml` | 两阶段切换：(1) 普通 primary_replica 主从切换（无 MHA）(2) MHA 模式切换（masterha_master_switch） |
@@ -192,32 +208,43 @@ ansible/
 
 **拓扑：3 节点共置**
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      VIP (Keepalived)                        │
-│                    ┌───────────────┐                         │
-│                    │  HAProxy:5432 │                         │
-│                    │  (读写分离)    │                         │
-│                    └───────┬───────┘                         │
-│           ┌────────────────┼────────────────┐               │
-│     ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐         │
-│     │  Node 1   │   │  Node 2   │   │  Node 3   │         │
-│     │ PG+Patroni│   │ PG+Patroni│   │ PG+Patroni│         │
-│     │ etcd+pgBR │   │ etcd+pgBR │   │ etcd+pgBR │         │
-│     │ HAProxy   │   │ HAProxy   │   │ HAProxy   │         │
-│     │ Keepalived│   │ Keepalived│   │ Keepalived│         │
-│     └───────────┘   └───────────┘   └───────────┘         │
-└─────────────────────────────────────────────────────────────┘
+```mermaid
+graph TD
+    VIP["VIP (Keepalived)"] --> HA["HAProxy:5432 (读写分离)"]
+
+    HA --> N1["Node 1\nPG+Patroni\ndetcd+pgBR\nHAProxy+Keepalived"]
+    HA --> N2["Node 2\nPG+Patroni\ndetcd+pgBR\nHAProxy+Keepalived"]
+    HA --> N3["Node 3\nPG+Patroni\ndetcd+pgBR\nHAProxy+Keepalived"]
+
+    N1 -.->|"etcd quorum"| N2
+    N2 -.->|"etcd quorum"| N3
+    N3 -.->|"etcd quorum"| N1
+
+    style VIP fill:#fff3e0
+    style HA fill:#e1f5fe
+    style N1 fill:#e8f5e9
+    style N2 fill:#e8f5e9
+    style N3 fill:#e8f5e9
 ```
 
 **服务依赖链：**
+
+```mermaid
+graph LR
+    ETCd["etcd"] --> Patroni["Patroni"]
+    Patroni --> Exporter["postgres-exporter"]
+    HAProxy["HAProxy"] -.->|"健康检查 /primary"| Patroni
+    Keepalived["Keepalived"] -.->|"VRRP 心跳"| HAProxy
+
+    style ETCd fill:#e1f5fe
+    style Patroni fill:#e8f5e9
 ```
-xinfra-pgha-etcd@{uuid}.service
-  → xinfra-patroni.service
-    → xinfra-postgres-exporter.service
-xinfra-haproxy.service (独立)
-keepalived.service (依赖 HAProxy 健康检查脚本)
-```
+
+!!! note "💡 HA 架构要点"
+    - **DCS：** 独立 etcd 3 节点集群（非系统 etcd），用于 Patroni 分布式协调
+    - **VIP：** Keepalived unicast 模式在 3 个 HAProxy 之间漂移，nopreempt 避免脑裂
+    - **读写分离：** HAProxy 通过 Patroni REST API `/primary` 健康检查路由到主库
+    - **备份冗余：** pgBackRest 双仓库（repo1/repo2 分布在不同节点）
 
 **关键设计：**
 - DCS：独立 etcd 3 节点集群（非系统 etcd）
@@ -358,10 +385,23 @@ ansible_ssh_private_key_file: "{{ xinfra_ssh_private_key_file }}"
 
 ## 六、设计亮点
 
-1. **原子安装**：aria2 多线程下载 + SHA256 校验 + flock 并发锁，保证二进制安装的原子性和幂等性
-2. **凭据安全**：临时文件存储（`mktemp` + `chmod 600` + `trap`），避免命令行泄露；SSH 密钥 ed25519 + `restrict` 前缀
-3. **GTID 复制**：全流程 GTID 模式，Clone 后自动重新生成 server_uuid，校验 errant/missing GTID
-4. **MHA 集成**：自动化 MHA 制品安装、配置、验收、故障转移回调
-5. **PG HA 全栈**：Patroni + etcd + HAProxy + Keepalived + pgBackRest，VIP 漂移 + 读写分离 + 双仓库备份
-6. **不可变 APT 快照**：内部 PyPI + APT 仓库，GPG 签名，幂等性校验
-7. **AWX 集成**：完整的 Project/Inventory/Template/Workflow 自动化配置
+!!! note "💡 原子安装"
+    aria2 多线程下载 + SHA256 校验 + flock 并发锁，保证二进制安装的原子性和幂等性。
+
+!!! note "💡 凭据安全"
+    临时文件存储（`mktemp` + `chmod 600` + `trap`），避免命令行泄露；SSH 密钥 ed25519 + `restrict` 前缀。
+
+!!! note "💡 GTID 复制"
+    全流程 GTID 模式，Clone 后自动重新生成 server_uuid，校验 errant/missing GTID。
+
+!!! note "💡 MHA 集成"
+    自动化 MHA 制品安装、配置、验收、故障转移回调。
+
+!!! note "💡 PG HA 全栈"
+    Patroni + etcd + HAProxy + Keepalived + pgBackRest，VIP 漂移 + 读写分离 + 双仓库备份。
+
+!!! note "💡 不可变 APT 快照"
+    内部 PyPI + APT 仓库，GPG 签名，幂等性校验。
+
+!!! note "💡 AWX 集成"
+    完整的 Project/Inventory/Template/Workflow 自动化配置。

docs/qiniu-cloud/architecture.md

@@ -24,9 +24,8 @@ config.Load() → vault.New(cfg) → database.Open(dsn) → database.AutoMigrate
   → router.New(deps) → r.Run(cfg.HTTPAddr)
 ```
 
-- Vault 在 `VAULT_ENABLED=false` 时为 nil，不影响启动
-- Redis 在 `REDIS_ENABLED=false` 时为 nil
-- AutoMigrate 通过 `AUTO_MIGRATE` 环境变量控制
+!!! note "💡 启动链路"
+    Vault 和 Redis 都支持通过环境变量禁用（`VAULT_ENABLED=false` / `REDIS_ENABLED=false`），此时对应客户端为 nil，不影响核心服务启动。`AutoMigrate` 通过 `AUTO_MIGRATE` 环境变量控制，生产环境建议关闭自动迁移。
 
 **Receptor Worker 启动流程：**
 
@@ -41,23 +40,24 @@ config.Load() → ValidateReceptorWorkerConfig() → database.Open() → databas
 
 ### 1.2 分层架构
 
+```mermaid
+graph TD
+    A["cmd/ 入口"] --> B["internal/router 路由"]
+    B --> C["internal/handler HTTP处理"]
+    C --> D["internal/service 业务逻辑"]
+    D --> E["internal/model 数据模型"]
+    D --> F["internal/database"]
+    D --> G["internal/auth / sso / vault"]
+    D --> H["internal/cache / config"]
+    D --> I["internal/wayne / artifactmanifest"]
+
+    style A fill:#e1f5fe
+    style C fill:#f3e5f5
+    style D fill:#e8f5e9
 ```
-┌─────────────────────────────────────────────────┐
-│                   cmd/ (入口)                     │
-├─────────────────────────────────────────────────┤
-│              internal/router (路由)                │
-├─────────────────────────────────────────────────┤
-│  internal/handler (HTTP 处理)                     │
-├─────────────────────────────────────────────────┤
-│  internal/service (业务逻辑)                      │
-├─────────────────────────────────────────────────┤
-│  internal/model (数据模型)  internal/database     │
-├─────────────────────────────────────────────────┤
-│  internal/auth  internal/sso  internal/vault     │
-│  internal/cache  internal/config                 │
-│  internal/wayne  internal/artifactmanifest       │
-└─────────────────────────────────────────────────┘
-```
+
+!!! note "💡 分层设计"
+    后端采用经典分层架构：`cmd` 负责启动编排，`router` 定义路由，`handler` 处理 HTTP 请求，`service` 封装业务逻辑，`model` + `database` 管理数据层。`auth/sso/vault/cache` 等作为公共组件被 service 层依赖。
 
 ### 1.3 路由设计
 
@@ -168,6 +168,9 @@ config.Load() → ValidateReceptorWorkerConfig() → database.Open() → databas
 
 共 **40+ 张数据表**，核心模型分组：
 
+!!! note "💡 数据模型概览"
+    模型按业务域划分为 7 大组：用户与权限（7 表）、交付系统（12+ 表）、MySQL HA（5 表）、PostgreSQL HA（8 表）、机器与 Receptor（6 表）、执行配置（3 表）、Archery 集成（5 表）。所有模型通过 GORM AutoMigrate 自动迁移。
+
 **用户与权限：**
 - `User` — ID, Username, DisplayName, Email, Phone, Source, ExternalID, Status, IsAdmin, LastLoginAt（软删除）
 - `BusinessLine` — Name（唯一）
@@ -214,6 +217,24 @@ config.Load() → ValidateReceptorWorkerConfig() → database.Open() → databas
 
 ### 1.7 认证机制
 
+```mermaid
+graph LR
+    subgraph "登录方式"
+        A["本地登录 POST /login"]
+        B["SAML SSO GET /login/internal-sso"]
+        C["OAuth2 /authorize"]
+    end
+
+    A --> JWT["JWT 签发/校验"]
+    B --> JWT
+    C --> JWT
+
+    JWT --> MW["AuthMiddleware (Bearer Token)"]
+
+    style JWT fill:#fff3e0
+    style MW fill:#e8f5e9
+```
+
 **JWT（`internal/auth/`）：**
 - `Claims` — HS256 访问令牌（UserID, Username, Email, DisplayName, IsAdmin）
 - `OAuthCodeClaims` — HS256 OAuth 授权码
@@ -230,6 +251,9 @@ config.Load() → ValidateReceptorWorkerConfig() → database.Open() → databas
 - OAuth Code 存储在 Redis（SetNX + TTL）
 - Token 端点：access_token（HS256）+ id_token（RS256）
 
+!!! note "💡 认证网关"
+    三种登录方式最终都汇聚到 JWT 签发，后端通过统一的 `AuthMiddleware` 校验 Bearer Token。SAML 和 OAuth 作为 SSO 协议接入，本地登录在 SSO 启用时自动禁用。
+
 ### 1.8 配置管理
 
 `Config` 结构体包含 **200+ 个配置项**，全部通过环境变量加载，支持 `.env.local`、`.env.server`、`.env` 文件。
@@ -470,26 +494,28 @@ PaginatedData<T> = { total: number, items: T[] }
 
 ## 三、前后端交互模型
 
+```mermaid
+graph TD
+    FE["Vue 3 SPA (Vite)"] -->|"POST /api/v1/*"| BE["Gin HTTP Server"]
+    BE -->|"JSON Response"| FE
+
+    BE --> MySQL["MySQL (GORM)"]
+    BE --> Redis["Redis (缓存/会话)"]
+    BE --> Vault["Vault (密钥管理)"]
+
+    BE --> AWX["AWX (Ansible)"]
+    BE --> Wayne["Wayne (K8s管理)"]
+    BE --> Archery["Archery (SQL审核)"]
+
+    style FE fill:#e1f5fe
+    style BE fill:#fff3e0
+    style MySQL fill:#fce4ec
+    style Redis fill:#fce4ec
+    style Vault fill:#fce4ec
 ```
-┌──────────────┐     /api/v1/*     ┌──────────────┐
-│   Vue 3 SPA  │ ──────────────── → │   Gin HTTP   │
-│   (Vite)     │ ← ───────────── ─ │   Server     │
-└──────────────┘   JSON Response   └──────┬───────┘
-                                          │
-                    ┌─────────────────────┼─────────────────────┐
-                    │                     │                     │
-              ┌─────▼─────┐       ┌──────▼──────┐      ┌──────▼──────┐
-              │   MySQL   │       │    Redis    │      │    Vault    │
-              │  (GORM)   │       │  (缓存/会话) │      │ (密钥管理)  │
-              └───────────┘       └─────────────┘      └─────────────┘
-                                          │
-                    ┌─────────────────────┼─────────────────────┐
-                    │                     │                     │
-              ┌─────▼─────┐       ┌──────▼──────┐      ┌──────▼──────┐
-              │   AWX     │       │   Wayne     │      │  Archery    │
-              │ (Ansible) │       │ (K8s 管理)  │      │ (SQL 审核)  │
-              └───────────┘       └─────────────┘      └─────────────┘
-```
+
+!!! note "💡 交互模型"
+    前端通过 RESTful API 与后端通信，后端依赖 MySQL 持久化、Redis 缓存与会话、Vault 密钥管理。外部系统 AWX（Ansible 自动化）、Wayne（K8s 管理）、Archery（SQL 审核）通过 HTTP API 集成。
 
 **认证流程：**
 1. 前端存储 JWT token 于 localStorage

docs/qiniu-cloud/deployment-cicd.md

@@ -28,6 +28,9 @@
 - 入口点：`/usr/local/bin/authserver`
 - 本地镜像标签：`xinfra-server:latest`（Makefile）
 
+!!! note "💡 多阶段构建"
+    前端和后端都采用 Docker 多阶段构建：构建阶段使用完整工具链（Node/Go），运行阶段使用最小化镜像（nginx/alpine），最终镜像体积大幅减小。后端以非 root 用户（65532）运行，遵循最小权限原则。
+
 ### 1.3 Nginx 配置 — `nginx.frontend.conf`
 
 **监听端口：** `80`
@@ -43,6 +46,9 @@
 
 代理头：`Host`、`X-Real-IP`
 
+!!! note "💡 Nginx 反向代理"
+    Nginx 作为前端入口，将 `/api/`、`/auth/`、`/swagger/` 统一代理到后端 `8083` 端口，SPA 路由通过 `try_files` fallback 到 `index.html` 实现前端路由。
+
 ### 1.4 本地开发数据库 — `docker-compose.mysql.yml`
 
 **MySQL 服务：**
@@ -65,8 +71,35 @@
 
 ## 二、Kubernetes 部署 (`deploy/k8s/wayne-xinfra.yaml`)
 
+```mermaid
+graph TD
+    subgraph K8s["Kubernetes Cluster"]
+        Secret["Secret: xinfra-secret"]
+        CM["ConfigMap: xinfra-configmap"]
+        Harbor["Secret: harbor-registry"]
+        Redis["StatefulSet: xinfra-redis\n(1 replica, 2Gi)"]
+        Backend["Deployment: xinfra-backend\n(1 replica)"]
+        Frontend["Deployment: xinfra-frontend\n(1 replica)"]
+        SVC_BE["Service: xinfra-backend\nClusterIP:8083"]
+        SVC_FE["Service: xinfra-frontend\nNodePort:80→32002"]
+    end
+
+    Secret --> Backend
+    CM --> Backend
+    Backend --> Redis
+    Frontend --> SVC_BE
+    SVC_FE --> Frontend
+
+    style Redis fill:#e1f5fe
+    style Backend fill:#e8f5e9
+    style Frontend fill:#fff3e0
+```
+
 单一 YAML 文件，包含以下资源，均标注 `wayne-app: xinfra`, `wayne-ns: xinfra`：
 
+!!! note "💡 K8s 部署"
+    整个应用通过单一 YAML 文件部署到 K8s，使用 Wayne 平台管理。Redis 使用 StatefulSet 保证持久化，前后端使用 Deployment 支持滚动更新。前端通过 NodePort 32002 暴露到外部。
+
 ### 2.1 Secret: `xinfra-secret` (Opaque)
 
 | 键 | 说明 |
@@ -158,13 +191,24 @@
 
 ### 3.3 Job 依赖图
 
+```mermaid
+graph TD
+    Prepare["prepare\nGo mod hash"] --> GoCache["go-mod-cache\n依赖缓存"]
+    GoCache --> Backend["backend-unit\ngo vet + test"]
+    FE["frontend-validation\nnpm test + build"] --> Integration["integration\n端到端测试"]
+    Backend --> Integration
+    Backend --> Coverage["coverage-upload\nCodecov"]
+    FE --> Coverage
+    Integration --> Coverage
+
+    style Prepare fill:#e1f5fe
+    style Backend fill:#e8f5e9
+    style FE fill:#fff3e0
+    style Integration fill:#fce4ec
 ```
-prepare ──→ go-mod-cache ──→ backend-unit ──┐
-                                            ├──→ coverage-upload
-frontend-validation ────────────────────────┤
-                                            │
-integration ────────────────────────────────┘
-```
+
+!!! note "💡 CI 流水线"
+    流水线采用 5 个 Job：`prepare` 计算 Go 模块 hash → `go-mod-cache` 缓存依赖 → `backend-unit` 并行跑后端单测 → `frontend-validation` 并行跑前端测试+构建 → `integration` 启动真实 MySQL 做端到端验证。最后 `coverage-upload` 汇总覆盖率上传 Codecov。
 
 ### 3.4 Job 详情
 

docs/qiniu-cloud/resume-tech-points.md

@@ -8,44 +8,68 @@
 
 基于 Patroni + etcd + HAProxy + Keepalived + pgBackRest 构建 3 节点共置高可用架构。通过 Keepalived unicast 模式实现 VIP 漂移，HAProxy 以 Patroni REST API `/primary` 健康检查实现读写分离路由；pgBackRest 双仓库（repo1/repo2 分布在不同节点）保障备份冗余。部署流水线经 preflight 静态预检（CPU/内存/磁盘/端口/L2 可达性/VIP 冲突检测）→ 3-Play 编排部署 → final_acceptance 验收（Patroni 健康/3 running + 1 primary/同步复制 2 streaming + 1 sync/etcd 3 members/HAPRoxy 端点/VIP 所有权）三阶段闭环，支持计划切换（patronictl switchover）、滚动重启、控制验收等运维操作。
 
+!!! note "💡 核心亮点"
+    三阶段闭环部署（预检→部署→验收）+ VIP 漂移 + 读写分离 + 双仓库备份冗余，生产级高可用方案。
+
 ---
 
 ## 2. 实现 Vault Database Secrets Engine 全链路集成
 
 对接 HashiCorp Vault 的 AppRole 认证 + Database Secrets Engine，实现数据库凭据全生命周期自动化。通过 `RegisterMySQLDatabaseConnection` 注册 MySQL 连接（mysql-database-plugin），`RegisterDatabaseStaticRole` 登记静态角色并校验 `skip_static_role_import_rotation` 是否生效——在密码仍被 MHA/Archery 等运行链路依赖时，拒绝静默降级为轮换模式，确保凭据安全。内置 token 自动续期（TTL 前 1 分钟刷新）和 401/403 请求重试机制，消除 Vault token 过期导致的间歇性故障。
 
+!!! note "💡 核心亮点"
+    `skip_static_role_import_rotation` 校验：当密码仍被运行链路依赖时，拒绝静默降级为轮换模式，保障凭据安全。
+
 ---
 
 ## 3. 构建多协议统一认证网关（SAML 2.0 + OAuth 2.0/OIDC + JWT）
 
 从零实现 SAML 2.0 SP：AuthnRequest deflate+base64 编码 → HTTP-Redirect 绑定，SAMLResponse 解析支持加密断言解密（RSA-OAEP 密钥传输 + AES-128/192/256-CBC/GCM 数据加密），SP 元数据 XML 自动生成。同时实现完整 OAuth 2.0 Authorization Code 流程作为 OIDC Provider：OAuth Code 以 Redis SetNX+TTL 存储保证一次性消费，Token 端点按 client 差异化签发（Wayen/CloudDM: HS256 access_token，Archery: RS256 PlatformToken），JWKS 端点暴露 RSA 公钥。JWT 层设计四种 Claims 结构（访问令牌/OAuth Code/OIDC ID Token/平台令牌），支持 HS256/RS256 双算法，Redis 集中吊销。
 
+!!! note "💡 核心亮点"
+    从零实现 SAML 2.0 SP + 完整 OAuth2/OIDC Provider + 四种 JWT Claims 结构，统一认证网关支持三种 SSO 协议。
+
 ---
 
 ## 4. 实现 Ansible MySQL 全生命周期自动化（11 个 Playbook）
 
 覆盖 MySQL 从部署到销毁的完整链路：deploy（参数校验 → MHA 制品安装 → 原子二进制安装[flock 并发锁+SHA256 校验+aria2 多线程] → 账号配置[mktemp+chmod 600+trap 防泄露] → GTID 复制[Clone 全量克隆+server_uuid 重新生成+errant/missing GTID 校验] → MHA 配置 → 健康检查 → 注册回调）、precheck（Python 脚本结构化 JSON 输出）、failover（普通主从切换 + MHA masterha_master_switch 双模式）、config-apply（my.cnf 片段写入 + 逐台滚动重启 + SQL 执行 + root 密码轮换）、decommission（先停从库 → 主库设 read_only → 写下线标记）、rejoin（旧主 Clone 接收 + GTID 复制重建）、purge（校验下线标记 → 验证删除）。MHA 集成包含 deb 包修补（修复 MySQL 8.x 版本解析正则）、ed25519 集群独立 SSH 密钥、故障转移回调脚本。
 
+!!! note "💡 核心亮点"
+    11 个 Playbook 覆盖 MySQL 全生命周期，原子二进制安装（flock+SHA256+aria2）+ GTID 复制校验 + MHA 故障转移回调。
+
 ---
 
 ## 5. 设计交付调度器状态机与幂等性保障
 
 交付系统采用 16 状态状态机（DeliveryTask）+ 幂等键（IdempotencyKey）防重复提交。配额管理通过 ResourceQuota + ResourceReservation 实现业务线级资源预留与释放。PostgreSQL HA 操作引入 14 状态生命周期，支持 AWX Workflow Job 调度、preflight 预检、config 在线变更、control 操作（restart/rolling_restart/switchover）、cleanup 清理等完整运维操作。任务事件流通过 SSE（Server-Sent Events）实现实时进度推送，前端通过 `createTaskLogStream` 订阅。凭证揭示采用一次性消费模式（pending → revealed → expired），支持 JSON 和 XLSX 两种导出格式。
 
+!!! note "💡 核心亮点"
+    16 状态状态机 + 幂等键防重复 + SSE 实时推送 + 凭证一次性揭示，交付调度器的可靠性设计。
+
 ---
 
 ## 6. 实现 Receptor 节点自动化供应系统（独立 Worker 进程）
 
 独立运行的 Receptor Worker 进程，以可配置并发度（RECEPTOR_PROVISIONING_CONCURRENCY）执行节点供应循环。多阶段管线：pending → prechecking → registering_awx → preparing_artifacts → installing → checking_remote → checking_awx → attaching_instance_group → succeeded，失败分支覆盖 precheck_failed/awx_failed/artifact_failed/install_failed/mesh_unreachable/health_check_failed。SSH 凭据采用 PGP + AES 双层加密（随机 DataKey AES 加密私钥，PGP 公钥加密 DataKey）。制品下载支持多架构（amd64/arm64），内置 SHA256 校验。下线流程独立编排：decommissioning → awx_disabled → instance_group_detached → remote_uninstalling → certificate_invalidated → awx_cleaning。
 
+!!! note "💡 核心亮点"
+    独立 Worker 进程 + 多阶段供应管线 + PGP+AES 双层加密 + 多架构制品支持，自动化节点生命周期管理。
+
 ---
 
 ## 7. 构建离线制品清单签名校验体系
 
 实现 `xinfra.artifact-manifest.v1/v2` 清单 schema 的完整校验链：Ed25519 签名验证 + SHA256 digest 计算（排除 digest 和 signature 字段）+ source 前缀白名单 + 可达性检查。支持两种清单模式：Evidence Summary（校验 sha256 digest）和嵌入 Ed25519 签名的 manifest。独立 CLI 工具（`cmd/artifact-manifest`）支持 `--manifest`、`--expected-digest`、`--key-id`、`--public-key`、`--allowed-source-prefix`、`--reachable-source` 参数，校验结果输出 JSON，非 StatusReady 则 exit 2，可集成到 CI/CD 流水线作为门禁。同时实现不可变 APT 快照构建脚本：收集运行时包 → SHA256 校验 → 生成 Packages 索引 → GPG 签名（InRelease + Release.gpg）→ 上传 Nexus，配合幂等性校验脚本确保两次独立演练的 URI 集合和 SHA256 摘要完全一致。
 
+!!! note "💡 核心亮点"
+    Ed25519 签名 + SHA256 digest + 不可变 APT 快照，离线制品完整性校验的完整方案。
+
 ---
 
 ## 8. 实现 Wayne 服务间 HMAC-SHA256 签名与 RBAC 权限模型
 
 服务间调用采用 HMAC-SHA256 签名方案：payload = `METHOD\nURI\nTIMESTAMP\nNONCE\nBODY_SHA256`，通过 `X-Wayne-Service`/`X-Wayne-Timestamp`/`X-Wayne-Nonce`/`X-Wayne-Signature` 四个 headers 传递，验签使用 `hmac.Equal` 常量时间比较防止时序攻击。RBAC 权限模型设计为三级架构：平台级（PlatformRoleBinding → platform_admin）、业务线级（BusinessLineUser owner/member + BusinessLinePermission 细粒度权限）、子系统级（Wayne Namespace Role Binding + Archery Resource/Permission Group）。前端实现四级路由守卫（platformPermission → businessLineMember → businessLineOwner → capability/capabilities），支持权限别名映射（如 `machine.view` → `machine.read` + `machine.credential.read`）。全链路审计日志异步写入，覆盖登录、业务线权限、子系统授权、服务交付四类操作。
+
+!!! note "💡 核心亮点"
+    HMAC-SHA256 常量时间验签 + 三级 RBAC + 四级路由守卫 + 权限别名映射，完整的安全与权限体系。

docs/qiniu-cloud/security-auth-data.md

@@ -8,28 +8,26 @@
 
 XINFRA 实现了多协议统一认证网关，支持本地登录、SAML 2.0 SSO、OAuth 2.0/OIDC 三种认证方式，并通过 JWT 实现会话管理。
 
+```mermaid
+graph TD
+    subgraph "认证网关层"
+        A["本地登录\nPOST /login"]
+        B["SAML 2.0 SSO\nGET /login/internal-sso"]
+        C["OAuth 2.0 / OIDC\n/auth/oauth/*"]
+    end
+
+    A --> JWT["JWT 签发/校验\nHS256/RS256"]
+    B --> JWT
+    C --> JWT
+
+    JWT --> MW["AuthMiddleware\nBearer Token"]
+
+    style JWT fill:#fff3e0
+    style MW fill:#e8f5e9
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                     认证网关层                                │
-│  ┌──────────┐  ┌──────────────┐  ┌──────────────────────┐   │
-│  │ 本地登录  │  │ SAML 2.0 SSO │  │ OAuth 2.0 / OIDC    │   │
-│  │ POST /   │  │ GET /login/  │  │ /auth/oauth/         │   │
-│  │ login    │  │ internal-sso │  │ authorize/token/     │   │
-│  └────┬─────┘  └──────┬───────┘  │ jwks/userinfo        │   │
-│       │               │          └──────────┬───────────┘   │
-│       └───────────────┼─────────────────────┘               │
-│                       ▼                                     │
-│              ┌─────────────────┐                            │
-│              │   JWT 签发/校验  │                            │
-│              │   (HS256/RS256) │                            │
-│              └────────┬────────┘                            │
-│                       ▼                                     │
-│              ┌─────────────────┐                            │
-│              │  AuthMiddleware  │                            │
-│              │  (Bearer Token) │                            │
-│              └─────────────────┘                            │
-└─────────────────────────────────────────────────────────────┘
-```
+
+!!! note "💡 统一认证网关"
+    三种认证方式最终都汇聚到 JWT 签发/校验，后端通过统一的 `AuthMiddleware` 处理所有请求的认证。SSO 启用时本地登录自动禁用，保证认证入口收敛。
 
 ---
 
@@ -60,31 +58,28 @@ XINFRA 实现了多协议统一认证网关，支持本地登录、SAML 2.0 SSO
 
 ### 3.2 登录流程
 
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant FE as 前端
+    participant BE as 后端
+    participant IDP as SAML IDP
+
+    U->>FE: 点击 SSO 登录
+    FE->>BE: GET /login/internal-sso
+    BE->>BE: BuildLoginRedirect()
+    BE->>BE: 构建 AuthnRequest (deflate+base64)
+    BE-->>FE: 302 重定向到 IDP
+    FE->>IDP: 用户在 IDP 认证
+    IDP-->>BE: POST SAMLResponse 到 /saml/acs
+    BE->>BE: DecodeSAMLResponse()
+    BE->>BE: 解密断言 (RSA-OAEP + AES)
+    BE->>BE: 创建/更新用户 + 签发 JWT
+    BE-->>FE: 重定向回前端 (携带 sso_token)
 ```
-用户 → GET /auth/api/v1/login/internal-sso
-         ↓
-       BuildLoginRedirect()
-         ↓
-       从 IDP 元数据获取 SSO URL
-         ↓
-       构建 AuthnRequest（deflate + base64 编码）
-         ↓
-       HTTP-Redirect 绑定 URL → 重定向到 IDP
-         ↓
-       用户在 IDP 完成认证
-         ↓
-       IDP POST SAMLResponse 到 /auth/api/v1/saml/acs
-         ↓
-       DecodeSAMLResponse()
-         ↓
-       Base64 解码 → 提取 NameID 和属性
-         ↓
-       支持加密断言解密（RSA-OAEP + AES-CBC/GCM）
-         ↓
-       创建/更新用户 + 签发 JWT
-         ↓
-       重定向回前端（携带 sso_token）
-```
+
+!!! note "💡 SAML 2.0 实现"
+    完整实现 SAML 2.0 SP：AuthnRequest 构建（deflate + base64 编码）→ HTTP-Redirect 绑定 → IDP 认证 → SAMLResponse 解析。支持加密断言解密（RSA-OAEP 密钥传输 + AES-128/192/256-CBC/GCM 数据加密）。
 
 ### 3.3 加密算法支持
 
@@ -134,14 +129,23 @@ XINFRA 实现了多协议统一认证网关，支持本地登录、SAML 2.0 SSO
 
 ### 4.3 授权码流程
 
+```mermaid
+sequenceDiagram
+    participant FE as 前端
+    participant BE as 后端
+    participant Redis as Redis
+
+    FE->>BE: GET /oauth/authorize?client_id=...
+    BE->>BE: 用户认证 + 生成 OAuth Code
+    BE->>Redis: SetNX + TTL 存储 Code
+    BE-->>FE: 302 redirect_uri?code=...
+    FE->>BE: POST /oauth/token (code)
+    BE->>Redis: 校验 + 消费 Code（一次性）
+    BE-->>FE: access_token + id_token
 ```
-1. 前端重定向到 /auth/oauth/authorize?client_id=...&redirect_uri=...&scope=...&state=...&nonce=...
-2. 用户认证后，后端生成 OAuth Code（HS256 签名的 Claims）
-3. OAuth Code 存储在 Redis（SetNX + TTL）
-4. 重定向回 redirect_uri?code=...&state=...
-5. 前端用 code 换取 token（POST /auth/oauth/token）
-6. 后端校验 code → Redis 消费（一次性）→ 签发 access_token + id_token
-```
+
+!!! note "💡 OAuth2 授权码流程"
+    OAuth Code 使用 Redis SetNX + TTL 存储，保证一次性消费。Token 端点按 client 差异化签发：Wayen/CloudDM 使用 HS256 access_token，Archery 使用 RS256 PlatformToken。
 
 ### 4.4 Token 签发
 
@@ -190,21 +194,33 @@ XINFRA 实现了多协议统一认证网关，支持本地登录、SAML 2.0 SSO
 
 ### 6.1 RBAC 架构
 
+```mermaid
+graph TD
+    subgraph "平台级权限"
+        P1["PlatformRoleBinding\nUserID → Role (platform_admin)"]
+    end
+
+    subgraph "业务线级权限"
+        B1["BusinessLineUser\nUserID → Role (owner/member)"]
+        B2["BusinessLinePermission\nUserID → Permission"]
+    end
+
+    subgraph "子系统级权限"
+        S1["Wayne\nNamespace Role Binding"]
+        S2["Archery\nResource Group / Permission Group"]
+    end
+
+    P1 --> B1
+    B1 --> S1
+    B1 --> S2
+
+    style P1 fill:#e1f5fe
+    style B1 fill:#fff3e0
+    style B2 fill:#fff3e0
 ```
-┌─────────────────────────────────────────────────┐
-│                 平台级权限                         │
-│  PlatformRoleBinding: UserID → Role              │
-│  (platform_admin)                                │
-├─────────────────────────────────────────────────┤
-│                 业务线级权限                       │
-│  BusinessLineUser: UserID → Role (owner/member)  │
-│  BusinessLinePermission: UserID → Permission     │
-├─────────────────────────────────────────────────┤
-│                 子系统级权限                       │
-│  Wayne: Namespace Role Binding                   │
-│  Archery: Resource Group / Permission Group      │
-└─────────────────────────────────────────────────┘
-```
+
+!!! note "💡 三级 RBAC"
+    权限模型分为三级：**平台级**（platform_admin 管理员）→ **业务线级**（owner/member + 细粒度权限）→ **子系统级**（Wayne 命名空间角色 + Archery 资源组/权限组）。前端通过四级路由守卫实现权限控制。
 
 ### 6.2 平台级角色
 
@@ -398,21 +414,25 @@ XINFRA 实现了多协议统一认证网关，支持本地登录、SAML 2.0 SSO
 
 ### 10.1 架构
 
+```mermaid
+graph TD
+    subgraph VaultServer["Vault Server"]
+        KV["KV v2\n通用密钥"]
+        DB["Database Secrets Engine\n数据库凭据自动化"]
+    end
+
+    AppRole["AppRole Auth"] --> KV
+    StaticRole["Static Role"] --> DB
+
+    AppRole -->|"role_id + secret_id"| VaultServer
+    DB -->|"MySQL/PostgreSQL 连接"| DB
+
+    style VaultServer fill:#e1f5fe
+    style AppRole fill:#e8f5e9
 ```
-┌─────────────────────────────────────────────────┐
-│                 Vault Server                      │
-│  ┌──────────────┐  ┌──────────────────────────┐ │
-│  │   KV v2      │  │  Database Secrets Engine  │ │
-│  │  (通用密钥)   │  │  (数据库凭据自动化)       │ │
-│  └──────────────┘  └──────────────────────────┘ │
-└─────────────────────────────────────────────────┘
-         ▲                        ▲
-         │                        │
-    ┌────┴────┐            ┌─────┴─────┐
-    │ AppRole │            │  Static   │
-    │  Auth   │            │  Role     │
-    └─────────┘            └───────────┘
-```
+
+!!! note "💡 Vault 集成"
+    Vault 通过 AppRole 认证获取 token，支持自动续期（TTL 前 1 分钟刷新）和 401/403 请求重试。Database Secrets Engine 实现数据库凭据全生命周期自动化：连接注册 → Static Role 登记 → 凭据读取 → 清理。
 
 ### 10.2 认证方式
 
@@ -583,3 +603,8 @@ METHOD\nURI\nTIMESTAMP\nNONCE\nBODY_SHA256
 - 路由级权限控制（路由守卫四级检查）
 - API 级权限控制（AuthMiddleware + 业务逻辑校验）
 - 全链路审计日志
+
+!!! note "💡 安全设计原则"
+    - **纵深防御：** 传输层（NodePort）→ 认证层（JWT/SAML/OAuth）→ 授权层（三级 RBAC）→ 审计层（全链路日志）
+    - **最小权限：** SSH 凭据 PGP 加密、交付凭据一次性揭示、Vault 自动轮换
+    - **零信任：** OAuth Code 一次性消费、Token 吊销、常量时间签名验证防时序攻击