zeaslity/ProjectAGiPrompt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

RMDC系统设计文档 整体转换为SKILL

Browse Source
This commit is contained in:
zeaslity
2026-01-21 16:15:49 +08:00
parent fc72a7312e
commit 631cce9e1e
163 changed files with 37099 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
7-JenBranchRBAC/1-原始需求/1-初始需求稿.md Normal file
View File

@@ -0,0 +1,65 @@
# JenBranchRBAC (Jenkins Branch-level Role-Based Access Control)
# 项目简介
本项目基于JenkinsAPI模块，设计用户使用界面，用户使用自己的用户名密码登录，能够查看和构建其拥有权限的项目及分支情况
# 项目说明
## 管理页面
- 页面显示-管理页面
### 用户添加
- 使用sqlite3进行持久化
- 存储在sqlite3中的密码需要进行加密
- 注册用户名及密码
- 密码过期时间为6个月
### 用户查询
- 用户信息包括
- 用户名
- 明文密码
- 权限信息
- 查询sqlite3获取用户信息
- 能够通过用户名模糊查询用户信息
- 能够查询所有的用户名及明文密码
- 支持一键导出用户名密码及分支
### 用户编辑
- 支持用户密码修改
- 支持用户权限修改
- 权限修改调用[用户权限绑定]模块的功能
### 用户权限绑定
- 使用sqlite3进行持久化保存
- 通过[JenkinsAPI模块]获取全部项目全部分支信息
- 通过左右两侧列表的形式,选择赋予项目及分支权限
- 全部项目及分支 支持模糊查询
## 用户页面
- 页面显示-用户页面
- 用户使用账户名密码登录
- 密码传递必须进行加密
### Jenkins项目及分支
- 能够查看,构建自己拥有权限的项目及分支
- 权限检验
- 构建时需要检测是否符合权限信息
### Jenkins构建信息显示
- 能够实时查看获取jenkins特定分支构建信息
- 能够查看特定项目特定分支的历史构建信息
## 配置管理
- sqlite3的保存位置
- 前后端密码加密密钥
- jenkins服务器url
- jenkins访问的token等信息
## JenkinsAPI模块
- 假设API拥有最高的权限
- 能够调用JenkinsAPI
- 获取全部项目及分支信息
- 能够实时获取Jenkins分支的构建信息输出
- 能够查询特定项目特定分支的历史构建信息

414
7-JenBranchRBAC/1-原始需求/2-优化产品需求文档PRD.md Normal file
View File

@@ -0,0 +1,414 @@
# JenBranchRBAC 产品需求文档
**Jenkins 分支级权限管理系统**
## 1. 产品概述
### 1.1 产品定位
JenBranchRBAC 是一个基于 Jenkins REST API 的细粒度权限控制平台，提供项目级、分支级的构建权限管理，解决 Jenkins 原生 RBAC 插件无法满足多分支流水线细粒度授权的痛点。
### 1.2 核心价值
- **细粒度权限控制**：支持到分支级别的读取、构建权限隔离
- **独立认证体系**：与 Jenkins 解耦的用户管理，降低 Jenkins 账户管理复杂度
- **审计合规**：完整的操作日志记录，满足企业安全审计需求
- **高效稳定**：基于 Go 语言构建，低资源占用，高并发响应
## 2. 功能架构
### 2.1 系统角色定义
| 角色 | 权限范围 | 典型场景 |
|------|---------|---------|
| 超级管理员 | 系统全部功能 | 平台运维人员 |
| 项目管理员 | 指定项目的权限分配 | 项目 Leader |
| 普通用户 | 已授权分支的查看和构建 | 开发工程师 |
## 3. 详细功能设计
### 3.1 管理端功能模块
#### 3.1.1 用户生命周期管理
**用户注册**
- 支持单个/批量导入用户（CSV 格式）
- 密码策略：
- 最小长度 8 位，包含大小写字母、数字、特殊字符
- 采用 bcrypt 算法加密存储（cost factor=12）
- 默认密码有效期 180 天，到期前 7 天邮件提醒
- 首次登录强制修改初始密码
**用户查询与导出**
- 支持按用户名、角色、权限范围、状态（启用/禁用/锁定）多维度筛选
- 导出格式包含：用户名、角色、授权项目-分支清单、账户状态、密码到期时间、最后登录时间
- **安全约束**：导出支持 CSV/Excel 格式，敏感数据（密码哈希）不可导出，管理员仅可重置无法查看明文。
**用户编辑**
- 密码重置：管理员可重置用户密码并强制下次登录修改
- 账户状态管理：启用/禁用/锁定（连续 5 次登录失败自动锁定 30 分钟）
- 权限变更：调用权限绑定模块进行项目-分支授权调整
#### 3.1.2 权限绑定系统
**Jenkins 数据同步**
- **定时拉取**：后端使用 `cron` 协程定时（默认 5 分钟）调用 Jenkins API。
- **手动立即同步**：管理界面提供“立即同步”按钮，后端通过 Goroutine 异步执行同步任务，前端通过 WebSocket 或轮询获取进度。
- **缓存机制**：本地缓存分支信息，API 调用失败时使用缓存数据。
- **差异检测**：自动识别新增/删除的项目和分支，提示管理员处理孤立权限。
**权限分配界面**
- 左右穿梭框设计（Material UI 风格）：
- 左侧：所有项目-分支树状结构
- 右侧：已授权清单
- 支持项目级全选/分支级精选
- 搜索功能：支持项目名、分支名模糊匹配及正则过滤（如 `feature/*`）。
- 权限模板：保存常用权限组合为模板，快速应用于同类用户。
#### 3.1.3 操作审计日志
**日志记录维度**
- 用户操作：登录/登出、密码修改、权限变更
- 构建操作：构建触发人、项目、分支、参数、时间戳
- 管理操作：用户创建/删除、权限模板变更、配置修改
- API 调用：Jenkins API 调用记录、响应状态、耗时
**日志查询与分析**
- 支持时间范围、操作类型、用户、项目多维度筛选
- 统计分析：用户活跃度排行、构建频率热力图、异常操作告警
### 3.2 用户端功能模块
#### 3.2.1 安全认证机制
**登录流程**
- 前端使用 RSA 加密密码传输（公钥前端存储，私钥后端保管）
- 后端验证：
1. 解密密码并与数据库 bcrypt 哈希比对
2. 校验账户状态（未过期、未锁定）
3. 生成 JWT Token（有效期 8 小时，支持刷新）
- 支持 MFA（可选）：集成 TOTP 双因素认证
**会话管理**
- 单设备登录限制（可配置允许多会话）
- Token 自动续期机制：活跃用户无感刷新
#### 3.2.2 项目与分支管理
**项目视图**
- 卡片式展示已授权项目（Material Card 组件）：
- 项目名称、描述、授权分支数量、最新构建状态图标
- 分组与排序：按项目名称、最后构建时间排序，支持收藏。
**分支视图**
- DataGrid 表格展示分支信息：
- 分支名称、最后构建状态、时间、Commit 信息
- 快速构建按钮：一键触发构建
#### 3.2.3 构建管理
**构建触发**
- 参数化构建支持：自动识别 Jenkinsfile parameters，前端动态生成 Material UI 表单。
- 权限二次校验：调用 Jenkins API 前验证用户对该分支的构建权限。
**实时构建监控**
- 基于 WebSocket：后端 Go Gin 开启 WebSocket 路由，实时推送 Jenkins 日志。
- **日志渲染优化**：前端解析 ANSI Color Codes，还原 Jenkins 控制台的红/黄/绿色高亮。
**历史构建查询**
- 分页展示历史构建（编号、结果、触发人、时长）。
- **构建产物下载**：提供 .jar/.war/.apk 等构建产物的直接下载链接。
### 3.3 配置管理模块
#### 3.3.1 系统配置
**数据存储配置**
```json
{
"database": {
"type": "sqlite3",
"path": "./data/jenbranchrbac.db",
"options": {
"journal_mode": "WAL", // 显式开启 WAL 模式以提升并发性能
"synchronous": "NORMAL"
},
"backup": {
"enabled": true,
"interval": "daily",
"retention": 30
}
}
}
```
**安全配置**
```json
{
"security": {
"password_encryption": {
"algorithm": "bcrypt",
"cost_factor": 12
},
"rsa_key_pair": {
"public_key_path": "./keys/public.pem",
"private_key_path": "./keys/private.pem"
},
"jwt": {
"secret": "CHANGE_THIS_SECRET",
"expiry": "8h",
"refresh_window": "1h"
},
"mfa": {
"enabled": false,
"issuer": "JenBranchRBAC"
}
}
}
```
**Jenkins 集成配置**
```json
{
"jenkins": {
"url": "https://jenkins.example.com",
"credentials": {
"username": "api_user",
"token": "API_TOKEN_HERE"
},
"sync": {
"interval": 300,
"timeout": 30
},
"proxy": {
"enabled": false,
"url": "http://proxy.example.com:8080"
}
}
}
```
#### 3.3.2 通知配置（增强功能）
**邮件通知**
- SMTP 配置：支持 TLS/SSL
- 通知场景：
- 密码即将过期提醒
- 构建失败告警（可配置失败次数阈值）
- 账户异常登录告警
**Webhook 集成**
- 支持发送构建事件到外部系统（如钉钉、企业微信、Slack）
- 自定义消息模板
### 3.4 Jenkins API 封装模块
#### 3.4.1 API 能力清单
| API 端点 | 功能 | 实现要点 |
|---------|------|---------|
| `/api/json?tree=jobs[...]` | 获取所有项目 | 使用 depth 和 tree 参数优化响应大小 |
| `/job/{name}/api/json` | 获取多分支流水线的分支 | 递归解析 jobs 字段 |
| `/job/{job}/job/{branch}/build` | 触发无参构建 | POST 请求，需 Jenkins Crumb |
| `/job/{job}/job/{branch}/buildWithParameters` | 触发参数化构建 | 表单数据传递参数 |
| `/job/{job}/job/{branch}/{num}/logText/progressiveText` | 增量获取构建日志 | 使用 start 参数实现断点续传 |
| `/job/.../{num}/api/json?tree=artifacts` | 获取构建产物 | **新增：解析下载路径** |
| `/queue/api/json` | 查询构建队列 | 估算等待时间 |
#### 3.4.2 API 调用优化
**性能优化**
- 使用 `tree` 参数精简返回字段，避免全量数据拉取
- 启用 HTTP/2 和连接池复用
- 缓存静态数据（项目列表、分支列表）
**可靠性保障**
- 重试机制：API 调用失败自动重试 3 次（指数退避）
- 熔断降级：Jenkins 不可用时，显示缓存数据并提示用户
- 请求限流：防止单用户频繁调用 Jenkins API
**安全增强**
- 使用 Jenkins API Token 而非用户名密码
- 所有 POST 请求携带 Jenkins Crumb 防止 CSRF
- API Token 加密存储在配置文件中
## 4. 数据库设计
### 4.1 核心表结构
**用户表（users）**
```sql
CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username VARCHAR(50) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
role VARCHAR(20) DEFAULT 'user',
status VARCHAR(20) DEFAULT 'active',
password_expires_at DATETIME NOT NULL,
failed_login_attempts INTEGER DEFAULT 0,
locked_until DATETIME,
mfa_secret VARCHAR(32),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
last_login_at DATETIME
);
```
**权限表（permissions）**
```sql
CREATE TABLE permissions (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL,
project_name VARCHAR(255) NOT NULL,
branch_name VARCHAR(255) NOT NULL,
can_view BOOLEAN DEFAULT 1,
can_build BOOLEAN DEFAULT 1,
granted_by INTEGER NOT NULL,
granted_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
FOREIGN KEY (granted_by) REFERENCES users(id),
UNIQUE(user_id, project_name, branch_name)
);
```
**审计日志表（audit_logs）**
```sql
CREATE TABLE audit_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER,
action VARCHAR(50) NOT NULL,
resource_type VARCHAR(50),
resource_id VARCHAR(255),
details TEXT,
ip_address VARCHAR(45),
user_agent TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id)
);
CREATE INDEX idx_audit_logs_user_time ON audit_logs(user_id, created_at);
CREATE INDEX idx_audit_logs_action ON audit_logs(action);
```
**权限模板表（permission_templates）**
```sql
CREATE TABLE permission_templates (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name VARCHAR(100) UNIQUE NOT NULL,
description TEXT,
permissions_json TEXT NOT NULL,
created_by INTEGER NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (created_by) REFERENCES users(id)
);
```
## 5. 技术选型建议 (Updated)
### 5.1 后端技术栈
- **语言**：Go (Golang) 1.24+
- **Web 框架**：**Gin**
- *选择理由*：高性能、轻量级、中间件生态丰富，适合构建高并发 REST API。
- **ORM 框架**：**GORM**
- *选择理由*：Go 语言事实标准的 ORM，支持 SQLite/MySQL/PostgreSQL 驱动，提供 AutoMigrate 能力，方便未来无缝迁移数据库。
- **身份认证**：`golang-jwt/jwt` (JWT) + `golang.org/x/crypto/bcrypt` (密码哈希)。
- **任务调度**：`robfig/cron`
- *架构优势*：利用 Go 的协程 (Goroutine) 处理定时同步和异步任务，**无需** 额外部署 Redis + Celery 等复杂的消息队列组件，大幅降低运维成本。
- **Jenkins SDK**：`bndr/gojenkins` 或基于 `resty` 封装的 HTTP Client。
- **日志处理**：`zap` 或 `logrus` (高性能结构化日志)。
### 5.2 前端技术栈
- **框架**：**Vue 3** (Composition API)
- **语言**：**TypeScript**
- *选择理由*：提供静态类型检查，增强代码可维护性和智能提示，适合企业级后台管理系统。
- **UI 组件库**：**Vuetify 3** (Material Design for Vue)
- *说明*：严格遵循 Material Design 规范的 Vue 组件库，提供丰富的现成组件（Card, DataGrid, Dialog 等），响应式设计优秀。
- **状态管理**：**Pinia** (Type-safe store)。
- **网络请求**：`Axios` (封装拦截器处理 JWT 刷新)。
- **日志渲染**：`ansi-to-html` (解析构建日志颜色)。
### 5.3 部署方案
- **编译构建**：后端编译为**单二进制文件** (Static Binary)，前端编译为静态资源 (dist)。
- **容器化**：使用 Multi-stage Dockerfile 构建，最终镜像体积可控制在 20MB-50MB 级别（使用 Alpine 基础镜像）。
- **反向代理**：Nginx 托管前端静态文件，并反向代理 API 请求到 Go 服务。
## 6. 非功能性需求
### 6.1 性能指标
- **高并发**：得益于 Go 的 Goroutine 模型，单实例可轻松支持 **1000+ 并发连接**（WebSocket 日志推送）。
- **低延迟**：API 响应时间 < 100ms。
- **资源占用**：空闲状态下内存占用 < 50MB。
- **快速启动**：服务启动时间 < 1s。
### 6.2 安全与合规
- 密码零明文存储（Bcrypt）。
- API 接口实施 RBAC 中间件拦截。
- SQL 注入防御（GORM 参数化查询）。
- XSS 防御（Vue 自动转义 + Gin Secure JSON）。
### 6.3 可维护性
- 前后端完全分离，通过 Swagger/OpenAPI (swag 库自动生成) 定义接口。
- Go 强类型语言特性减少运行时错误。
## 7. 实施路线图
### Phase 1 - MVP（4 周）
- 初始化 Go Gin 项目脚手架与 GORM 模型设计。
- 实现基于 JWT 的用户认证与权限中间件。
- 完成 Jenkins API 的 Go 语言封装与数据同步协程。
- 前端 Vue3 + TS + Vuetify 基础框架搭建及登录页。
- **验证**：SQLite WAL 模式下的 GORM 并发读写稳定性。
### Phase 2 - 增强功能（3 周）
- 实现 WebSocket 路由，对接 Jenkins 实时日志流。
- 开发前端日志组件（支持 ANSI 颜色渲染）。
- 实现构建产物解析与下载接口。
- 完善审计日志的中间件埋点（Aspect-Oriented Programming）。
### Phase 3 - 企业级特性（3 周）
- 集成 TOTP (MFA) 认证。
- 增加 Webhook 通知模块（Go 协程异步发送）。
- 压力测试：验证 500+ 用户同时在线时的内存泄漏情况（pprof 分析）。
- 编写 Dockerfile 与 CI/CD 流水线。
## 8. 风险与挑战 (针对新栈)
- **前端学习曲线**：TypeScript 和 Vuetify 的系统性较强，需确保前端团队熟悉类型系统。
- *缓解*：制定 TS 规范，提供类型定义文件 (*.d.ts)。
- **Jenkins API 结构变动**：Go 是强类型语言，解析 Jenkins 不规范的 JSON 可能报错。
- *缓解*：在 JSON 解析层定义松散的 struct 或使用 `interface{}` 配合断言处理动态字段。

837
7-JenBranchRBAC/2-概要详细设计/3-详细设计说明书.md Normal file
View File

@@ -0,0 +1,837 @@
# JenBranchRBAC 系统详细设计说明书
**Jenkins 分支级权限管理系统架构设计文档**
***
## 1. 系统架构设计
### 1.1 总体架构
JenBranchRBAC 采用前后端分离的三层架构设计,通过 RESTful API 与 WebSocket 实现前后端通信,后端通过 Jenkins REST API 实现与 Jenkins 系统的集成。
```mermaid
graph TB
subgraph "展现层 Presentation Layer"
A[Vue3 + TypeScript]
B[Vuetify 3 UI]
C[Pinia State Management]
end
subgraph "网络通信层 Network Layer"
D[RESTful API]
E[WebSocket]
F[Nginx Reverse Proxy]
end
subgraph "业务逻辑层 Business Layer"
G[Gin Web Framework]
H[JWT Authentication]
I[RBAC Middleware]
J[Jenkins API Client]
K[Cron Job Scheduler]
end
subgraph "数据持久层 Data Layer"
L[GORM ORM]
M[SQLite3 WAL Mode]
N[Backup Service]
end
subgraph "外部系统 External Systems"
O[Jenkins Server]
P[SMTP Server]
Q[Webhook Endpoints]
end
A --> D
A --> E
B --> A
C --> A
D --> F
E --> F
F --> G
G --> H
G --> I
G --> J
G --> K
G --> L
L --> M
M --> N
J --> O
G --> P
G --> Q
```
### 1.2 系统分层职责
| 层次 | 组件 | 职责边界 |
|------|------|----------|
| 展现层 | Vue3 + Vuetify | 用户界面渲染、表单验证、状态管理、路由控制 |
| 网络层 | Nginx + API Gateway | 静态资源托管、请求路由、负载均衡、SSL终止 |
| 业务层 | Gin + 业务逻辑模块 | 认证授权、权限校验、业务流程编排、Jenkins API封装 |
| 数据层 | GORM + SQLite | 数据持久化、事务管理、查询优化、备份恢复 |
***
## 2. 核心模块设计
### 2.1 认证授权模块
#### 2.1.1 认证流程设计
```mermaid
sequenceDiagram
participant U as 用户浏览器
participant F as Vue Frontend
participant N as Nginx
participant B as Gin Backend
participant D as Database
participant J as Jenkins API
U->>F: 输入用户名/密码
F->>F: RSA公钥加密密码
F->>N: POST /api/auth/login
N->>B: 转发请求
B->>B: RSA私钥解密密码
B->>D: 查询用户记录
D-->>B: 返回用户信息
B->>B: bcrypt验证密码
B->>B: 检查账户状态
alt 验证成功
B->>B: 生成JWT Token
B->>D: 记录登录日志
B-->>F: 返回Token + 用户信息
F->>F: 存储Token到LocalStorage
F-->>U: 跳转到项目列表页
else 验证失败
B->>D: 累计失败次数
alt 失败次数>=5
B->>D: 锁定账户30分钟
end
B-->>F: 返回错误信息
F-->>U: 显示错误提示
end
```
#### 2.1.2 权限校验中间件设计
**RBAC 中间件实现逻辑**:
```mermaid
flowchart TD
A[HTTP请求到达] --> B{提取JWT Token}
B -->|Token不存在| C[返回401 Unauthorized]
B -->|Token存在| D[验证Token签名]
D -->|签名无效| C
D -->|签名有效| E{检查Token过期时间}
E -->|已过期| F{在刷新窗口内?}
F -->|是| G[生成新Token并返回]
F -->|否| C
E -->|未过期| H[解析用户ID和角色]
H --> I{检查接口权限}
I -->|超级管理员| J[放行请求]
I -->|项目管理员| K{验证项目权限}
K -->|有权限| J
K -->|无权限| L[返回403 Forbidden]
I -->|普通用户| M{验证分支权限}
M -->|有权限| J
M -->|无权限| L
J --> N[继续处理业务逻辑]
```
***
### 2.2 Jenkins 数据同步模块
#### 2.2.1 定时同步机制
```mermaid
sequenceDiagram
participant C as Cron Scheduler
participant S as Sync Service
participant J as Jenkins API
participant Cache as Local Cache
participant DB as Database
participant WS as WebSocket Server
C->>S: 触发定时任务(每5分钟)
S->>J: GET /api/json?tree=jobs[name,url]
J-->>S: 返回项目列表
loop 遍历多分支项目
S->>J: GET /job/{name}/api/json
J-->>S: 返回分支列表
end
S->>S: 差异检测(对比Cache)
S->>DB: 更新项目/分支元数据
S->>Cache: 更新本地缓存
alt 发现新增/删除
S->>WS: 推送通知给在线管理员
end
S->>DB: 记录同步日志
```
#### 2.2.2 手动同步机制
管理员触发立即同步时,后端启动异步 Goroutine 执行同步任务,前端通过 WebSocket 订阅同步进度:
```mermaid
stateDiagram-v2
[*] --> Idle: 系统空闲
Idle --> Syncing: 点击"立即同步"
Syncing --> FetchingProjects: 获取项目列表
FetchingProjects --> FetchingBranches: 项目获取完成
FetchingBranches --> DiffDetecting: 分支获取完成
DiffDetecting --> Updating: 差异检测完成
Updating --> Success: 更新完成
Updating --> Failed: 更新失败
Success --> Idle: 返回空闲
Failed --> Idle: 返回空闲
note right of Syncing
WebSocket推送: progress=0%
end note
note right of FetchingBranches
WebSocket推送: progress=50%
end note
note right of Success
WebSocket推送: progress=100%
end note
```
***
### 2.3 权限管理模块
#### 2.3.1 权限分配流程
```mermaid
sequenceDiagram
participant A as 管理员
participant F as 前端界面
participant B as 后端API
participant D as 数据库
participant C as 缓存层
A->>F: 选择用户
F->>B: GET /api/users/{id}/permissions
B->>D: 查询现有权限
D-->>B: 返回权限列表
B-->>F: 返回权限数据
F->>F: 渲染左右穿梭框
A->>F: 选择项目/分支并提交
F->>B: POST /api/permissions/assign
B->>B: 验证管理员权限范围
B->>D: 批量插入/更新权限记录
B->>D: 记录审计日志
B->>C: 清除用户权限缓存
B-->>F: 返回操作结果
F-->>A: 显示成功提示
```
#### 2.3.2 权限模板应用
权限模板设计用于快速批量授权相同角色的用户:
```mermaid
flowchart LR
A[创建权限模板] --> B[选择项目-分支组合]
B --> C[保存为JSON格式]
C --> D[存储到permission_templates表]
D --> E[应用模板到用户]
E --> F[解析JSON权限定义]
F --> G[批量插入permissions表]
G --> H[记录审计日志]
```
***
### 2.4 构建管理模块
#### 2.4.1 构建触发流程
```mermaid
sequenceDiagram
participant U as 用户
participant F as 前端
participant B as 后端
participant D as 数据库
participant J as Jenkins
U->>F: 点击"构建"按钮
F->>B: POST /api/build/trigger
B->>D: 查询用户权限
D-->>B: 返回权限信息
B->>B: 二次校验构建权限
alt 有构建权限
B->>J: 获取Jenkins Crumb
J-->>B: 返回Crumb Token
B->>J: POST /job/{job}/job/{branch}/build
J-->>B: 返回Queue ID
B->>D: 记录构建审计日志
B-->>F: 返回Queue ID
F->>F: 建立WebSocket连接
F->>B: 订阅构建日志
else 无权限
B-->>F: 返回403错误
F-->>U: 显示权限不足提示
end
```
#### 2.4.2 实时日志推送
```mermaid
sequenceDiagram
participant F as 前端WebSocket客户端
participant W as 后端WebSocket服务
participant J as Jenkins API
participant L as 日志缓冲区
F->>W: 连接WS /ws/build-log/{buildId}
W->>W: 验证JWT Token
W->>J: GET logText/progressiveText?start=0
J-->>W: 返回日志片段 + nextOffset
W->>L: 写入缓冲区
W->>F: 推送日志数据(JSON格式)
loop 每2秒轮询
W->>J: GET logText/progressiveText?start={nextOffset}
J-->>W: 返回增量日志
W->>F: 推送增量数据
end
alt 构建完成
W->>F: 推送完成标识
W->>W: 关闭连接
end
```
***
## 3. 数据库设计
### 3.1 E-R 关系图
```mermaid
erDiagram
USERS ||--o{ PERMISSIONS : has
USERS ||--o{ AUDIT_LOGS : generates
USERS ||--o{ PERMISSION_TEMPLATES : creates
USERS ||--o{ PERMISSIONS_GRANTED : grants
USERS {
int id PK
string username UK
string password_hash
string role
string status
datetime password_expires_at
int failed_login_attempts
datetime locked_until
string mfa_secret
datetime created_at
datetime updated_at
datetime last_login_at
}
PERMISSIONS {
int id PK
int user_id FK
string project_name
string branch_name
bool can_view
bool can_build
int granted_by FK
datetime granted_at
}
AUDIT_LOGS {
int id PK
int user_id FK
string action
string resource_type
string resource_id
text details
string ip_address
text user_agent
datetime created_at
}
PERMISSION_TEMPLATES {
int id PK
string name UK
text description
text permissions_json
int created_by FK
datetime created_at
}
```
### 3.2 索引优化策略
| 表名 | 索引字段 | 索引类型 | 优化目标 |
|------|----------|----------|----------|
| users | username | UNIQUE | 登录查询加速 |
| permissions | (user_id, project_name, branch_name) | UNIQUE | 防止重复授权 |
| permissions | user_id | BTREE | 用户权限列表查询 |
| audit_logs | (user_id, created_at) | COMPOSITE | 用户操作历史查询 |
| audit_logs | action | BTREE | 操作类型统计分析 |
| audit_logs | created_at | BTREE | 日志归档清理 |
***
## 4. 接口设计规范
### 4.1 RESTful API 设计
#### 4.1.1 认证授权接口
| 接口路径 | 方法 | 功能 | 请求体 | 响应体 |
|---------|------|------|--------|--------|
| /api/auth/login | POST | 用户登录 | `{username, encrypted_password}` | `{token, refresh_token, user_info}` |
| /api/auth/logout | POST | 用户登出 | - | `{message}` |
| /api/auth/refresh | POST | 刷新Token | `{refresh_token}` | `{token}` |
| /api/auth/reset-password | POST | 重置密码 | `{user_id, new_password}` | `{message}` |
#### 4.1.2 用户管理接口
| 接口路径 | 方法 | 功能 | 权限要求 | 请求参数 |
|---------|------|------|----------|----------|
| /api/users | GET | 用户列表 | 管理员 | `page, size, role, status` |
| /api/users | POST | 创建用户 | 管理员 | `{username, password, role}` |
| /api/users/{id} | GET | 用户详情 | 管理员 | - |
| /api/users/{id} | PUT | 更新用户 | 管理员 | `{role, status}` |
| /api/users/{id} | DELETE | 删除用户 | 超级管理员 | - |
| /api/users/batch | POST | 批量导入 | 管理员 | `CSV文件` |
| /api/users/export | GET | 导出用户 | 管理员 | `format=csv/excel` |
#### 4.1.3 权限管理接口
| 接口路径 | 方法 | 功能 | 请求体 |
|---------|------|------|--------|
| /api/permissions/assign | POST | 分配权限 | `{user_id, permissions:[{project, branch, can_view, can_build}]}` |
| /api/permissions/{user_id} | GET | 查询用户权限 | - |
| /api/permissions/templates | GET | 权限模板列表 | - |
| /api/permissions/templates | POST | 创建权限模板 | `{name, description, permissions_json}` |
#### 4.1.4 Jenkins 同步接口
| 接口路径 | 方法 | 功能 | 响应体 |
|---------|------|------|--------|
| /api/jenkins/sync | POST | 手动同步 | `{task_id, status}` |
| /api/jenkins/projects | GET | 项目列表 | `{projects:[{name, branches:[]}]}` |
| /api/jenkins/sync/status | GET | 同步状态 | `{status, progress, message}` |
#### 4.1.5 构建管理接口
| 接口路径 | 方法 | 功能 | 请求体 |
|---------|------|------|--------|
| /api/build/trigger | POST | 触发构建 | `{project, branch, parameters}` |
| /api/build/{build_id}/log | GET | 获取构建日志 | - |
| /api/build/{build_id}/artifacts | GET | 获取构建产物 | - |
| /api/build/history | GET | 历史构建记录 | `project, branch, page, size` |
***
### 4.2 WebSocket 接口设计
| 连接路径 | 事件类型 | 数据格式 | 用途 |
|---------|---------|---------|------|
| /ws/build-log/{build_id} | log_chunk | `{offset, content, is_complete}` | 实时日志推送 |
| /ws/sync-progress | sync_status | `{progress, current_project, message}` | 同步进度通知 |
| /ws/notifications | notification | `{type, title, message, timestamp}` | 系统通知推送 |
***
## 5. 安全设计方案
### 5.1 密码安全策略
```mermaid
flowchart TD
A[用户创建密码] --> B{密码强度校验}
B -->|不符合| C[返回错误提示]
B -->|符合| D[bcrypt哈希 cost=12]
D --> E[存储密码哈希]
E --> F[设置过期时间180天]
F --> G[定时检查过期状态]
G -->|距过期7天| H[发送邮件提醒]
G -->|已过期| I[强制修改密码]
```
**密码策略配置**:
- 最小长度: 8 位
- 必须包含: 大写字母、小写字母、数字、特殊字符
- 历史密码限制: 不能与最近 3 次密码相同
- 加密算法: bcrypt (cost factor = 12)
- 有效期: 180 天
### 5.2 防暴力破解机制
```mermaid
stateDiagram-v2
[*] --> Normal: 正常状态
Normal --> Failed1: 登录失败1次
Failed1 --> Failed2: 登录失败2次
Failed2 --> Failed3: 登录失败3次
Failed3 --> Failed4: 登录失败4次
Failed4 --> Locked: 登录失败5次
Locked --> Normal: 30分钟后自动解锁
Failed1 --> Normal: 登录成功
Failed2 --> Normal: 登录成功
Failed3 --> Normal: 登录成功
Failed4 --> Normal: 登录成功
note right of Locked
账户锁定30分钟
记录审计日志
发送告警邮件
end note
```
### 5.3 API 安全防护
| 安全措施 | 实现方案 | 防护对象 |
|---------|---------|---------|
| SQL 注入防护 | GORM 参数化查询 | 所有数据库操作 |
| XSS 防护 | Vue 自动转义 + Gin SecureJSON | 前后端输出 |
| CSRF 防护 | Jenkins Crumb Token | Jenkins API 调用 |
| 请求限流 | Gin 限流中间件 | 所有 API 端点 |
| 数据加密传输 | RSA 加密密码 + HTTPS | 敏感数据传输 |
| JWT Token 安全 | 8 小时过期 + 刷新机制 | 用户会话管理 |
***
## 6. 性能优化方案
### 6.1 后端性能优化
```mermaid
flowchart LR
A[性能优化策略] --> B[并发优化]
A --> C[缓存优化]
A --> D[数据库优化]
A --> E[网络优化]
B --> B1[Goroutine处理异步任务]
B --> B2[连接池复用]
B --> B3[请求限流防止雪崩]
C --> C1[本地缓存Jenkins数据]
C --> C2[用户权限缓存]
C --> C3[Redis缓存热点数据可选]
D --> D1[SQLite WAL模式]
D --> D2[复合索引优化]
D --> D3[定期清理审计日志]
E --> E1[HTTP/2启用]
E --> E2[Jenkins API tree参数]
E --> E3[WebSocket长连接复用]
```
### 6.2 前端性能优化
| 优化项 | 实现方案 | 性能收益 |
|--------|---------|---------|
| 路由懒加载 | Vue Router 动态 import | 减少首屏加载时间 |
| 组件按需加载 | Vuetify Treeshaking | 减小打包体积 30% |
| 虚拟滚动 | DataGrid 虚拟列表 | 大数据量渲染优化 |
| 请求防抖 | Lodash debounce 搜索 | 减少 API 调用次数 |
| 日志分页加载 | 滚动加载历史日志 | 避免内存溢出 |
***
## 7. 部署架构设计
### 7.1 单机部署方案
```mermaid
graph TB
subgraph "Docker Container"
A[Nginx:alpine] -->|静态资源| B[Vue3 Dist]
A -->|反向代理 :8080| C[Gin Backend]
C --> D[SQLite3 WAL DB]
C --> E[(/data Volume Mount)]
D --> E
end
F[External Client] -->|HTTPS :443| A
C -->|Jenkins API| G[Jenkins Server]
C -->|SMTP :587| H[Mail Server]
```
**Dockerfile 示例**:
```dockerfile
# Stage 1: 前端构建
FROM node:20-alpine AS frontend-builder
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm ci
COPY frontend/ ./
RUN npm run build
# Stage 2: 后端构建
FROM golang:1.24-alpine AS backend-builder
WORKDIR /app/backend
COPY backend/go.* ./
RUN go mod download
COPY backend/ ./
RUN CGO_ENABLED=1 GOOS=linux go build -a -installsuffix cgo -o jenbranchrbac .
# Stage 3: 运行时镜像
FROM alpine:latest
RUN apk --no-cache add ca-certificates nginx
WORKDIR /app
COPY --from=backend-builder /app/backend/jenbranchrbac .
COPY --from=frontend-builder /app/frontend/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80 8080
CMD nginx && ./jenbranchrbac
```
### 7.2 高可用部署方案
```mermaid
graph TB
subgraph "负载均衡层"
A[Nginx/HAProxy]
end
subgraph "应用层"
B1[JenBranchRBAC Instance 1]
B2[JenBranchRBAC Instance 2]
B3[JenBranchRBAC Instance N]
end
subgraph "数据层"
C[PostgreSQL Primary]
D[PostgreSQL Standby]
E[Redis Cluster]
end
A -->|Round Robin| B1
A --> B2
A --> B3
B1 --> C
B2 --> C
B3 --> C
C -->|主从复制| D
B1 --> E
B2 --> E
B3 --> E
```
**扩展建议**:
- 当并发用户超过 500 人时,建议从 SQLite 迁移到 PostgreSQL
- 引入 Redis 作为分布式缓存层,存储用户会话和权限信息
- 使用 Kubernetes 部署多实例,实现水平扩展
***
## 8. 监控与运维设计
### 8.1 日志分级策略
| 日志级别 | 记录场景 | 示例 |
|---------|---------|------|
| DEBUG | 详细调试信息 | Jenkins API 请求参数、SQL 查询语句 |
| INFO | 正常业务流程 | 用户登录成功、构建触发成功 |
| WARN | 潜在问题告警 | API 调用超时重试、缓存未命中 |
| ERROR | 错误但可恢复 | Jenkins 连接失败、数据库锁超时 |
| FATAL | 系统致命错误 | 数据库文件损坏、配置文件缺失 |
### 8.2 监控指标设计
```mermaid
graph LR
A[监控指标体系] --> B[系统指标]
A --> C[业务指标]
A --> D[安全指标]
B --> B1[CPU使用率]
B --> B2[内存占用]
B --> B3[磁盘IO]
B --> B4[Goroutine数量]
C --> C1[API响应时间]
C --> C2[Jenkins同步耗时]
C --> C3[构建触发成功率]
C --> C4[WebSocket连接数]
D --> D1[登录失败次数]
D --> D2[异常IP访问]
D --> D3[权限拒绝次数]
D --> D4[Token刷新频率]
```
**Prometheus 集成方案**:
- 使用 `gin-prometheus` 中间件暴露 `/metrics` 端点
- 监控指标包括:HTTP 请求计数、延迟分布、数据库连接池状态、Goroutine 泄漏检测
***
## 9. 备选技术方案
### 9.1 数据库迁移路径
| 数据库类型 | 适用场景 | 迁移工具 |
|-----------|---------|---------|
| SQLite3 | 单机部署 < 500 用户 | 内置方案 |
| PostgreSQL | 生产环境 > 500 用户 | GORM AutoMigrate |
| MySQL 8.0 | 已有 MySQL 基础设施 | GORM AutoMigrate |
**迁移步骤**:
1. 使用 GORM `AutoMigrate` 在目标数据库创建表结构
2. 通过 SQL 脚本导出 SQLite 数据并转换为目标数据库格式
3. 修改配置文件中的 `database.type` 参数
4. 重启服务并验证数据一致性
### 9.2 认证方案扩展
```mermaid
flowchart TD
A[认证方式扩展] --> B[本地认证]
A --> C[LDAP/AD集成]
A --> D[OAuth2.0]
A --> E[SAML SSO]
B --> B1[当前实现方案]
C --> C1[企业内部用户统一认证]
D --> D1[GitHub/GitLab账户登录]
E --> E1[企业级SSO集成]
```
**实现优先级**:
1. **Phase 1**: 本地认证 + MFA (已设计)
2. **Phase 2**: LDAP 集成 (企业高需求)
3. **Phase 3**: OAuth2.0 (开源社区版)
***
## 10. 技术风险与缓解措施
| 风险项 | 影响等级 | 缓解措施 |
|--------|---------|---------|
| Jenkins API 结构变更 | 中 | 使用松散类型解析 + 版本兼容性测试 |
| SQLite 并发写入冲突 | 中 | WAL 模式 + 写操作重试机制 + 升级 PostgreSQL |
| Go 类型系统学习曲线 | 低 | 代码规范文档 + Code Review |
| TypeScript 类型定义复杂 | 低 | 提供 `*.d.ts` 类型文件 + ESLint 规则 |
| WebSocket 连接稳定性 | 中 | 心跳检测 + 自动重连机制 |
| 密钥文件泄露 | 高 | 密钥文件权限控制 (chmod 600) + 密钥轮换机制 |
***
## 11. 实施时间表
```mermaid
gantt
title JenBranchRBAC 实施路线图
dateFormat YYYY-MM-DD
section Phase 1 - MVP
Go项目脚手架与GORM模型 :a1, 2025-11-22, 7d
JWT认证与RBAC中间件 :a2, after a1, 7d
Jenkins API封装与同步 :a3, after a2, 7d
Vue3前端框架与登录页 :a4, after a1, 14d
section Phase 2 - 增强功能
WebSocket实时日志推送 :b1, after a3, 7d
前端日志组件与ANSI渲染 :b2, after a4, 7d
构建产物解析与下载 :b3, after b1, 7d
审计日志中间件完善 :b4, after b1, 7d
section Phase 3 - 企业特性
TOTP MFA认证集成 :c1, after b3, 7d
Webhook通知模块 :c2, after b4, 7d
压力测试与性能优化 :c3, after c2, 7d
Docker镜像与CI/CD流水线 :c4, after c3, 7d
```
***
## 12. 附录
### 12.1 关键技术栈版本
| 组件 | 版本 | 说明 |
|------|------|------|
| Go | 1.24+ | 后端开发语言 |
| Gin | v1.10+ | Web 框架 |
| GORM | v2.0+ | ORM 框架 |
| Vue | 3.4+ | 前端框架 |
| TypeScript | 5.0+ | 类型系统 |
| Vuetify | 3.5+ | UI 组件库 |
| SQLite | 3.45+ | 嵌入式数据库 |
| Nginx | 1.26+ | 反向代理服务器 |
### 12.2 配置文件示例
**config.yaml**:
```yaml
server:
host: 0.0.0.0
port: 8080
mode: release # debug/release
database:
type: sqlite3
path: ./data/jenbranchrbac.db
max_idle_conns: 10
max_open_conns: 100
conn_max_lifetime: 3600
security:
jwt_secret: CHANGE_THIS_SECRET_IN_PRODUCTION
jwt_expiry: 8h
rsa_private_key: ./keys/private.pem
rsa_public_key: ./keys/public.pem
bcrypt_cost: 12
jenkins:
url: https://jenkins.example.com
username: api_user
token: YOUR_JENKINS_API_TOKEN
sync_interval: 300 # seconds
timeout: 30
logging:
level: info # debug/info/warn/error
format: json
output: ./logs/app.log
max_size: 100 # MB
max_backups: 10
max_age: 30 # days
```
### 12.3 参考文档
- Jenkins REST API 官方文档: https://www.jenkins.io/doc/book/using/remote-access-api/
- Gin Web Framework 文档: https://gin-gonic.com/docs/
- GORM ORM 文档: https://gorm.io/docs/
- Vue 3 官方文档: https://vuejs.org/guide/
- Vuetify 3 组件库: https://vuetifyjs.com/en/components/all/
- JWT 认证最佳实践: https://datatracker.ietf.org/doc/html/rfc7519
***
**文档版本**: v1.0
**编制日期**: 2025-11-21
**编制人**: 系统架构师
**审核状态**: 待评审

70
7-JenBranchRBAC/飞控业务架构图.md Normal file
View File

@@ -0,0 +1,70 @@
# 系统架构图
## 接入层
1. Nginx
2. Ingress Nginx
## 业务层
1. cmii-fly-center
2. cmii-sky-converge
### AI能力调度
1. cmii-uav-ai-core
### 视频接入层
1. cmii-live-operator
2. cmii-live-zlm
## 中间件(持久化)
1. MySQL
2. InfluxDB
3. Redis
4.
## 数据层
1. minio
你是一名非常优秀的系统架构师，非常善于使用draw.io绘制结构清晰，精美的系统架构图，初步的系统架构说明见上文，请你为next-ai-draw-io制作一份提示词，用于构建美观 专业的系统架构图
Create a professional, layered System Architecture Diagram. Use a top-down layout with 4 distinct horizontal containers (layers) spanning the full width.
## Visual Style
- Theme: Clean, modern, enterprise style.
- Colors: Use soft blues and whites for backgrounds; distinct colors for each layer's header.
- Icons: Use standard tech icons (Nginx, Kubernetes, Database, Storage) where appropriate.
## Structure Definition
### 1. Access Layer (Top Layer)
- Group Name: "Access Layer"
- Nodes:
- "Nginx" (Use Nginx icon, placed at the very top)
- "Ingress Nginx" (Use Load Balancer or K8s Ingress icon, placed below Nginx)
- Flow: Connect "Nginx" down to "Ingress Nginx".
### 2. Business Layer (Middle Layer - Large Container)
- Group Name: "Business Layer"
- Inside this layer, create 3 visual sub-groups/clusters to organize the services:
- Cluster A (Core Business): "cmii-fly-center", "cmii-sky-converge"
- Cluster B (AI Scheduling): "cmii-uav-ai-core" (Label this group "AI Capabilities")
- Cluster C (Video Access): "cmii-live-operator", "cmii-live-zlm" (Label this group "Video Services")
- Flow: Connect "Ingress Nginx" from the layer above to these service components.
### 3. Middleware Layer (Bottom-Middle Layer)
- Group Name: "Middleware & Persistence"
- Nodes (Arrange horizontally):
- "MySQL" (Use Relational DB icon)
- "InfluxDB" (Use Time Series DB icon)
- "Redis" (Use Cache/Redis icon)
### 4. Data Layer (Bottom Layer)
- Group Name: "Data Storage"
- Nodes:
- "Minio" (Use Object Storage/Bucket icon)
## Data Flow Connections
- Draw arrows from Business Layer services to the Middleware databases (MySQL, InfluxDB, Redis).
- Draw arrows from "Video Services" and relevant Business services to "Minio" in the Data Layer.