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