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