zeaslity/ProjectAGiPrompt

Fork 0

Files

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

2026-01-21 16:15:49 +08:00

22 KiB

Raw Permalink Blame History

JenBranchRBAC 系统详细设计说明书

Jenkins 分支级权限管理系统架构设计文档

1. 系统架构设计

1.1 总体架构

JenBranchRBAC 采用前后端分离的三层架构设计,通过 RESTful API 与 WebSocket 实现前后端通信,后端通过 Jenkins REST API 实现与 Jenkins 系统的集成。

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 认证流程设计

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 中间件实现逻辑:

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 定时同步机制

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 订阅同步进度:

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 权限分配流程

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 权限模板应用

权限模板设计用于快速批量授权相同角色的用户:

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 构建触发流程

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 实时日志推送

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 关系图

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 密码安全策略

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 防暴力破解机制

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 后端性能优化

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 单机部署方案

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 示例:

# 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 高可用部署方案

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 监控指标设计

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

迁移步骤:

使用 GORM AutoMigrate 在目标数据库创建表结构
通过 SQL 脚本导出 SQLite 数据并转换为目标数据库格式
修改配置文件中的 database.type 参数
重启服务并验证数据一致性

9.2 认证方案扩展

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集成]

实现优先级:

Phase 1: 本地认证 + MFA (已设计)
Phase 2: LDAP 集成 (企业高需求)
Phase 3: OAuth2.0 (开源社区版)

10. 技术风险与缓解措施

风险项	影响等级	缓解措施
Jenkins API 结构变更	中	使用松散类型解析 + 版本兼容性测试
SQLite 并发写入冲突	中	WAL 模式 + 写操作重试机制 + 升级 PostgreSQL
Go 类型系统学习曲线	低	代码规范文档 + Code Review
TypeScript 类型定义复杂	低	提供 `*.d.ts` 类型文件 + ESLint 规则
WebSocket 连接稳定性	中	心跳检测 + 自动重连机制
密钥文件泄露	高	密钥文件权限控制 (chmod 600) + 密钥轮换机制

11. 实施时间表

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:

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
编制人: 系统架构师
审核状态: 待评审

22 KiB Raw Permalink Blame History