RMDC系统设计文档 整体转换为SKILL
This commit is contained in:
zeaslity
65
7-JenBranchRBAC/1-原始需求/1-初始需求稿.md
Normal file
65
7-JenBranchRBAC/1-原始需求/1-初始需求稿.md
Normal 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
414
7-JenBranchRBAC/1-原始需求/2-优化产品需求文档PRD.md
Normal 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{}` 配合断言处理动态字段。
|
||||
Reference in New Issue
Block a user