ProjectAGiPrompt/7-JenBranchRBAC/1-原始需求/2-优化产品需求文档PRD.md

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 系统配置

数据存储配置

{
  "database": {
    "type": "sqlite3",
    "path": "./data/jenbranchrbac.db",
    "options": {
      "journal_mode": "WAL",  // 显式开启 WAL 模式以提升并发性能
      "synchronous": "NORMAL"
    },
    "backup": {
      "enabled": true,
      "interval": "daily",
      "retention": 30
    }
  }
}

安全配置

{
  "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 集成配置

{
  "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）

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）

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）

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）

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{} 配合断言处理动态字段。