diff --git a/docs/qiniu-cloud/architecture.md b/docs/qiniu-cloud/architecture.md index dea082d..901dea5 100644 --- a/docs/qiniu-cloud/architecture.md +++ b/docs/qiniu-cloud/architecture.md @@ -84,6 +84,7 @@ graph TD **`/auth/api/v1` 内部分组:** **公开路由(无认证):** + - `GET /config` — 认证配置 - `POST /login` — 本地登录 - `GET /login/internal-sso` — SAML SSO 登录 @@ -109,6 +110,7 @@ graph TD | 任务日志 | list / get / stream (SSE) | 任务追踪 | **中间件:** + - `AuthMiddleware`:从 `Authorization: Bearer` header 或 `authserver_token` cookie 提取 JWT,调用 `auth.Parse` 校验,可选 token 吊销检查(Redis),将 claims 存入 gin.Context - 回调路由使用独立的 `AWXWebhookToken` Bearer Token 认证 @@ -172,6 +174,7 @@ graph TD 模型按业务域划分为 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(唯一) - `BusinessLineUser` — BusinessLineID, UserID, Role(owner/member), CreatedBy @@ -180,6 +183,7 @@ graph TD - `WayenCredential` — Email, Password, Enabled(软删除) **交付系统:** + - `DeliveryTask` — ID(UUID), BusinessLineID, TaskKind(deploy/config_change/failover/switchover/decommission/restore/purge), Component(mysql/postgresql), Status(16 种状态) - `ResourceQuota` / `ResourceReservation` — 配额与预留 - `DeploymentResult` / `DeploymentCredential` — 部署结果与凭证 @@ -188,11 +192,13 @@ graph TD - `TaskEvent` — 任务事件流 **MySQL HA:** + - `MySQLCluster` — Name, Version, Topology, HAMode(none/mha), FailoverMode, VIP - `MySQLInstance` — Hostname, HostIP, Port, Role(primary/replica), ServerID/UUID - `MySQLReplicationChannel` / `MySQLInternalCredential` / `ServerIDAllocation` **PostgreSQL HA:** + - `PostgreSQLCluster` — Name, ClusterUUID, VersionMajor, PatroniNamespace, PatroniScope - `PostgreSQLInstance` — Hostname, Port, PatroniRESTPort, EtcdClientPort, Role - `PostgreSQLHAOperation` — Status(14 种), AWXWorkflowJobID @@ -200,6 +206,7 @@ graph TD - `PostgreSQLHAAudit` / `PostgreSQLHAControlOperation` / `PostgreSQLHAJobLog` **机器与 Receptor:** + - `MachineResource` — SinaID, Hostname, IntranetIP, Spec, CPUCores, Memory - `MachineCredential` — AuthMethod(password/key), AWXInventoryID - `ReceptorNode` — NodeIdentity, NodeType(hop/execution), ConnectionMode, AWXInstanceID @@ -207,11 +214,13 @@ graph TD - `SSHCredential` — KeyType, PrivateKeyCiphertext(PGP), EncryptedDataKey **执行配置:** + - `ExecutionProfileRelease` — Name, Version, Status(draft/published/blocked), ManifestDigest - `ExecutionBindingRelease` — ProfileReleaseID, Kind, AWX 对象 ID - `TaskExecutionSnapshot` — 快照绑定 **Archery 集成:** + - `BusinessLineArcheryResourceGroup` / `BusinessLineArcheryPermissionGroup` - `ArcheryAccessSyncTask` / `ArcheryInstanceBinding` / `ArcheryUserBinding` @@ -236,16 +245,19 @@ graph LR ``` **JWT(`internal/auth/`):** + - `Claims` — HS256 访问令牌(UserID, Username, Email, DisplayName, IsAdmin) - `OAuthCodeClaims` — HS256 OAuth 授权码 - `IDTokenClaims` — RS256 OIDC ID Token - `PlatformTokenClaims` — RS256 子系统平台令牌 **SAML 2.0(`internal/sso/`):** + - 完整 SP 实现:AuthnRequest 构建、响应解码、加密断言解密(RSA-OAEP + AES-CBC/GCM) - SP 元数据 XML 生成 **OAuth2/OIDC Provider(handler/oauth.go):** + - 完整 Authorization Code 流程 - 多 Client 支持:wayne、clouddm、archery - OAuth Code 存储在 Redis(SetNX + TTL) @@ -348,6 +360,7 @@ src/ | `/observable/alert` | `views/monitor/Alert.vue` | 无 | **路由守卫四级权限检查:** + 1. `platformPermission` — 调用 `authStore.hasPlatformPermission()` 2. `businessLineMember` — 检查 `businessLineStore.current?.id` 是否存在 3. `businessLineOwner` — 检查 `businessLineStore.isCurrentAdmin` @@ -367,6 +380,7 @@ src/ | `isAdmin` | `computed` | 是否拥有 `business_line.manage` 权限 | **关键方法:** + - `hasPlatformPermission(permission)` — 平台级权限检查,admin 额外授予 3 个管理权限 - `isBusinessLineOwner(businessLineId)` — 业务线 owner 检查 - `hasBusinessLinePermission(businessLineId, permission)` — 业务线级权限检查,支持权限别名映射 @@ -374,6 +388,7 @@ src/ - `setAuth / refreshUser / clearAuth / isLoggedIn` **权限别名映射(硬编码):** + - `subsystem.wayne.manage` → `subsystem.wayne.role.grant`, `subsystem.wayne.role.revoke` - `machine.view` → `machine.read`, `machine.credential.read` - `machine.manage` → `machine.create/update/delete/credential.manage/sync` @@ -393,6 +408,7 @@ src/ ### 2.5 API 封装 **请求基础设施:** + - `api/request.ts` — 基于 Axios,`baseURL: '/api/v1'`,`timeout: 10000`,自动注入 Bearer token - `api/authRequest.ts` — 基于原生 fetch 的轻量封装 - 响应拦截器:业务码映射中文提示、401 自动跳转、超时/网络异常处理 @@ -441,12 +457,14 @@ PaginatedData = { total: number, items: T[] } ### 2.7 组件体系 **布局组件:** + - `AppHeader.vue` — 顶部导航:logo + 环境标签 + BusinessLineSwitcher + 主题切换 + 用户信息 - `AppSidebar.vue` — 左侧导航:按分组(概览/业务交付/资源纳管/可观测性/统一入口/审计)动态显示/隐藏 - `AppMain.vue` — 内容区:`` - `DefaultLayout.vue` — CSS Grid 布局 `282px 1fr` / `70px 1fr`,移动端折叠侧边栏 **公共组件:** + - `BusinessLineSwitcher.vue` — 业务线下拉切换器 - `PhoneSetupDialog.vue` — 首次登录手机号补充弹窗 - `SubsystemCard.vue` — 子系统卡片(图标/标签/域名/SSO 状态) @@ -475,6 +493,7 @@ PaginatedData = { total: number, items: T[] } ### 2.10 样式体系 **Design Token(CSS 变量):** + - 背景色 3 级、边框色 2 级、文字色 3 级 - 强调色 green `#00B42A`、状态色 warn/err/info - 圆角 4 级、字体 mono/sans(IBM Plex) @@ -518,6 +537,7 @@ graph TD 前端通过 RESTful API 与后端通信,后端依赖 MySQL 持久化、Redis 缓存与会话、Vault 密钥管理。外部系统 AWX(Ansible 自动化)、Wayne(K8s 管理)、Archery(SQL 审核)通过 HTTP API 集成。 **认证流程:** + 1. 前端存储 JWT token 于 localStorage 2. 请求拦截器自动注入 `Authorization: Bearer ` 3. 后端 AuthMiddleware 校验 JWT,可选 Redis token 吊销检查 diff --git a/docs/qiniu-cloud/deployment-cicd.md b/docs/qiniu-cloud/deployment-cicd.md index d74650a..2db3d30 100644 --- a/docs/qiniu-cloud/deployment-cicd.md +++ b/docs/qiniu-cloud/deployment-cicd.md @@ -52,6 +52,7 @@ ### 1.4 本地开发数据库 — `docker-compose.mysql.yml` **MySQL 服务:** + - 镜像:`mysql:8.0.46` - 容器名:`authserver-mysql` - 端口映射:`3000:3306` @@ -61,6 +62,7 @@ - 数据卷:`./data/mysql:/var/lib/mysql` **Redis 服务:** + - 镜像:`redis:7.4-alpine` - 容器名:`authserver-redis` - 端口映射:`6379:6379` @@ -213,15 +215,18 @@ graph TD ### 3.4 Job 详情 #### `prepare` + - Runner:`github-runner-ubuntu-24-04` - 仅限仓库 `1024XEngineer/xinfra` - 输出:`ci_go_mod_hash`(对 `go.mod`+`go.sum` 做双重 SHA256) #### `go-mod-cache` + - 依赖:`prepare` - 步骤:checkout → Go 环境准备 → `go mod download` → 保存到 S3 #### `backend-unit` + - 依赖:`prepare`, `go-mod-cache` - 步骤: 1. Checkout + Go 环境准备 @@ -230,6 +235,7 @@ graph TD 4. (仅 main push)上传 coverage 到 S3 #### `frontend-validation` + - 无依赖(可并行) - 步骤: 1. Checkout + Node.js setup(版本来自 `.nvmrc`,缓存 npm) @@ -239,6 +245,7 @@ graph TD 5. (仅 main push)上传 lcov.info 到 S3 #### `integration` + - 依赖:`prepare`, `go-mod-cache`, `backend-unit`, `frontend-validation` - **Services:** MySQL 8.0.46(端口 3306) - 步骤: @@ -251,6 +258,7 @@ graph TD 3. 环境变量:`APP_ENV=test`, `HTTP_ADDR=127.0.0.1:8080`, `AUTO_MIGRATE=true`, `SSO_ENABLED=false` #### `coverage-upload` + - 依赖:`backend-unit`, `frontend-validation`, `integration` - 仅在 `main` 分支 push 时运行 - 从 S3 下载前后端 coverage 文件 @@ -259,11 +267,13 @@ graph TD ### 3.5 Composite Actions #### `ci-go-prep` (`.github/actions/ci-go-prep/action.yml`) + - `actions/setup-go@v6`,版本来自 `server/go.mod` - 创建 Go 目录 - 从 S3 恢复 Go 模块缓存 #### `ci-s3-prep` (`.github/actions/ci-s3-prep/action.yml`) + - 安装 `rclone`(如果不存在) ### 3.6 CI 辅助脚本 @@ -345,12 +355,14 @@ graph TD **监听端口:** `8089` **Upstream 后端:** + - `authserver_backend` → `127.0.0.1:8083`(keepalive 32) - `authserver_frontend` → `127.0.0.1:5173`(Vite dev server) - `wayne_backend` → `127.0.0.1:8080` - `wayne_frontend` → `127.0.0.1:4200` **路由规则:** + - `/healthz`, `/readyz` → authserver_backend - `/auth/api/`, `/auth/oauth/`, `/auth/.well-known/` → authserver_backend - `/wayne/` → wayne_frontend(rewrite 去掉 `/wayne/` 前缀) diff --git a/docs/qiniu-cloud/security-auth-data.md b/docs/qiniu-cloud/security-auth-data.md index 7857582..ac4a1cd 100644 --- a/docs/qiniu-cloud/security-auth-data.md +++ b/docs/qiniu-cloud/security-auth-data.md @@ -36,6 +36,7 @@ graph TD **端点:** `POST /auth/api/v1/login` **流程:** + 1. 接收 `username` + `password` 2. 查询数据库用户记录 3. 验证密码哈希 @@ -235,6 +236,7 @@ graph TD ### 6.4 权限清单 **平台级权限(`platformPermission`):** + - `business_line.manage` — 业务线管理 **业务线级权限(`capability`):** @@ -253,12 +255,14 @@ graph TD ### 6.5 前端权限检查 **四级检查(路由守卫):** + 1. `platformPermission` — `authStore.hasPlatformPermission()` 2. `businessLineMember` — `businessLineStore.current?.id` 存在性 3. `businessLineOwner` — `businessLineStore.isCurrentAdmin` 4. `capability` / `capabilities` — `authStore.hasAnyBusinessLinePermission()` **权限别名映射(前端硬编码):** + - `subsystem.wayne.manage` → `subsystem.wayne.role.grant`, `subsystem.wayne.role.revoke` - `machine.view` → `machine.read`, `machine.credential.read` - `machine.manage` → `machine.create/update/delete/credential.manage/sync` @@ -318,6 +322,7 @@ graph TD ### 8.2 核心数据模型分组 #### 用户与权限(7 张表) + - `User` — 用户主表(软删除) - `WayenCredential` — Wayne 平台凭据(软删除) - `BusinessLine` — 业务线 @@ -327,6 +332,7 @@ graph TD - `BusinessLineWayneNamespace` / `BusinessLineSinaOrganization` — 业务线映射 #### 交付系统(12+ 张表) + - `DeliveryTask` — 交付任务(16 种状态) - `ResourceQuota` / `ResourceReservation` — 配额与预留 - `MySQLPrecheckLease` — 预检租约(唯一约束) @@ -339,6 +345,7 @@ graph TD - `AWXRuntimeInventory` — AWX 运行时 Inventory #### MySQL HA(5 张表) + - `MySQLCluster` — 集群(HAMode: none/mha) - `MySQLInstance` — 实例(Role: primary/replica) - `MySQLReplicationChannel` — 复制通道 @@ -346,6 +353,7 @@ graph TD - `ServerIDAllocation` — Server ID 分配 #### PostgreSQL HA(8 张表) + - `PostgreSQLCluster` — 集群 - `PostgreSQLInstance` — 实例 - `PostgreSQLResourceUsage` — 资源使用 @@ -356,6 +364,7 @@ graph TD - `PostgreSQLHAControlOperation` / `PostgreSQLHAJobLog` #### 机器与 Receptor(6 张表) + - `MachineResource` — 机器资源 - `MachineCredential` — 机器凭据 - `MachineSyncState` — 同步状态 @@ -364,16 +373,19 @@ graph TD - `SSHCredential` — SSH 凭据(PGP 加密) #### 执行配置(3 张表) + - `ExecutionProfileRelease` — 配置发布 - `ExecutionBindingRelease` — 绑定发布 - `TaskExecutionSnapshot` — 执行快照 #### Archery 集成(5 张表) + - `BusinessLineArcheryResourceGroup` / `BusinessLineArcheryPermissionGroup` - `ArcheryAccessSyncTask` — 同步任务 - `ArcheryInstanceBinding` / `ArcheryUserBinding` #### 审计(1 张表) + - `AuditLog` — 统一审计日志 ### 8.3 迁移逻辑 @@ -501,12 +513,14 @@ DeleteDatabaseStaticRole(vault, roleName) ### 11.1 SSH 凭据加密 **`SSHCredential` 模型:** + - `PrivateKeyCiphertext` — PGP 加密的私钥 - `EncryptedDataKey` — 加密的 DataKey - `KnownHosts` — 已知主机 - `HostKeyPolicy` — 主机密钥策略 **加密方案:** + - 生成随机 DataKey - 使用 DataKey 的 AES 密钥加密私钥 - 使用 PGP 公钥加密 DataKey @@ -515,12 +529,14 @@ DeleteDatabaseStaticRole(vault, roleName) ### 11.2 交付凭据 **`DeploymentCredential` 模型:** + - `Ciphertext` — 加密的凭据 - `Nonce` — 加密 nonce - `Status` — 状态(pending/revealed/expired) - `ViewedBy` — 查看者 **凭证揭示:** + - `POST /delivery/tasks/:id/credentials/reveal` - 支持 JSON 和 XLSX 下载两种格式 - 一次性揭示,标记为 `revealed` @@ -563,6 +579,7 @@ METHOD\nURI\nTIMESTAMP\nNONCE\nBODY_SHA256 ``` **Headers:** + - `X-Wayne-Service` — 服务名 - `X-Wayne-Timestamp` — 时间戳 - `X-Wayne-Nonce` — 随机 nonce