Ticket 凭证管理模块架构指南

模块定位: Ticket 是 BK-CI 的凭证管理模块，负责管理各类凭证（Credential）和证书（Cert），为代码库、构建机、部署等场景提供安全的凭证存储和访问服务。

一、模块整体结构

1.1 子模块划分

src/backend/ci/core/ticket/
├── api-ticket/              # API 接口定义层
│   └── src/main/kotlin/com/tencent/devops/ticket/
│       ├── api/                 # REST API 接口
│       ├── constant/            # 常量定义
│       └── pojo/                # 数据对象
│           ├── enums/           # 枚举
│           └── item/            # 凭证项
│
├── biz-ticket/              # 业务逻辑层
├── model-ticket/            # 数据模型层
└── boot-ticket/             # Spring Boot 启动模块

二、核心概念

2.1 凭证类型

enum class CredentialType(val type: String) {
    PASSWORD("PASSWORD"),                       // 密码
    ACCESSTOKEN("ACCESSTOKEN"),                 // AccessToken
    OAUTHTOKEN("OAUTHTOKEN"),                   // OAuth Token
    USERNAME_PASSWORD("USERNAME_PASSWORD"),     // 用户名+密码
    SECRETKEY("SECRETKEY"),                     // SecretKey
    APPID_SECRETKEY("APPID_SECRETKEY"),         // AppId+SecretKey
    SSH_PRIVATEKEY("SSH_PRIVATEKEY"),           // SSH 私钥
    TOKEN_SSH_PRIVATEKEY("TOKEN_SSH_PRIVATEKEY"), // Token+SSH私钥
    TOKEN_USERNAME_PASSWORD("TOKEN_USERNAME_PASSWORD"), // Token+用户名密码
    COS_APPID_SECRETID_SECRETKEY_REGION("COS_APPID_SECRETID_SECRETKEY_REGION"), // COS凭证
    MULTI_LINE_PASSWORD("MULTI_LINE_PASSWORD"), // 多行密码
}

2.2 证书类型

enum class CertType(val type: String) {
    IOS("ios"),           // iOS 证书
    ANDROID("android"),   // Android 证书
    TLS("tls"),           // TLS 证书
    ENTERPRISE("enterprise"), // 企业证书
}

2.3 凭证数据项

三、核心数据库表

3.1 凭证表

3.2 证书表

3.3 字段说明

⚠️ 重要: PROJECT_ID 是 T_PROJECT.english_name

四、API 接口速查

4.1 凭证接口

4.2 证书接口

五、核心流程

5.1 凭证创建流程

用户创建凭证
    │
    ▼
UserCredentialResource.create()
    │
    ├─► 参数校验
    │   └─► 校验凭证 ID 唯一性
    │
    ├─► 加密凭证内容
    │   └─► 使用 AES 加密 v1~v4 字段
    │
    └─► 保存到数据库

5.2 凭证获取流程

构建时获取凭证
    │
    ▼
BuildCredentialResource.get()
    │
    ├─► 权限校验
    │   └─► 检查构建是否有权限使用该凭证
    │
    ├─► 查询凭证
    │   └─► credentialDao.get()
    │
    ├─► 解密凭证内容
    │   └─► 使用 AES 解密
    │
    └─► 返回凭证信息

六、安全机制

6.1 加密存储

• 凭证内容使用 AES 加密后存储
• 密钥由系统配置管理
• 数据库中不存储明文

6.2 访问控制

• 凭证按项目隔离
• 支持跨项目共享（需配置）
• 构建时通过 Build ID 验证权限

七、与其他模块的关系

┌─────────────────────────────────────────────────────────────────┐
│                    Ticket 模块关系                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐                   │
│  │repository │  │  worker   │  │   store   │                   │
│  │(代码库认证)│  │(构建凭证)  │  │(插件凭证)  │                   │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘                   │
│        │              │              │                          │
│        └──────────────┼──────────────┘                          │
│                       ▼                                          │
│               ┌───────────────┐                                  │
│               │    ticket     │                                  │
│               └───────┬───────┘                                  │
│                       │                                          │
│               ┌───────┴───────┐                                  │
│               ▼               ▼                                  │
│        ┌───────────┐   ┌───────────┐                            │
│        │  project  │   │   auth    │                            │
│        └───────────┘   └───────────┘                            │
└─────────────────────────────────────────────────────────────────┘

八、服务间调用示例

// Repository 模块获取凭证
client.get(ServiceCredentialResource::class).get(
    projectId = projectId,  // english_name
    credentialId = credentialId
)

// Worker 获取构建凭证
client.get(BuildCredentialResource::class).get(
    projectId = projectId,
    buildId = buildId,
    credentialId = credentialId,
    publicKey = publicKey  // 用于加密返回的凭证
)

九、常见问题

Q: 凭证如何加密存储？ A: 使用 AES 对称加密，密钥配置在系统配置中。

Q: 如何跨项目使用凭证？ A: 设置 ALLOW_ACROSS_PROJECT = true，并在目标项目中引用。

Q: 构建时如何安全获取凭证？ A: 构建时传入公钥，服务端用公钥加密凭证返回，构建机用私钥解密。

版本: 1.0.0 | 更新日期: 2025-12-11