permission-model-change-guide

IAM 权限中心资源类型接入最佳实践指南

概述

本指南基于 creative_stream 资源类型接入权限中心的实践经验总结，提供一套可复用的标准流程，帮助团队成员快速完成新资源类型的权限接入。

接入流程总览

┌─────────────────────────────────────────────────────────────────────────────┐
│                         IAM 资源类型接入流程                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────────────────┐  │
│  │ 1.需求   │───▶│ 2.后端   │───▶│ 3.IAM    │───▶│ 4.数据库配置         │  │
│  │   分析   │    │   枚举   │    │   配置   │    │  (SQL 或 API 二选一) │  │
│  └──────────┘    └──────────┘    └──────────┘    └──────────────────────┘  │
│                                                                             │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐                              │
│  │ 5.国际化 │───▶│ 6.用户组 │───▶│ 7.验证   │                              │
│  │   配置   │    │   配置   │    │   测试   │                              │
│  └──────────┘    └──────────┘    └──────────┘                              │
│                                                                             │
│  ⚡ 推荐：使用 API 接口替代 SQL 脚本，更简单、更安全                          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

第一步：需求分析与规划

1.1 确定资源类型信息

项目	说明	示例
资源类型 ID	全局唯一标识，使用 snake_case	creative_stream
中文名称	用于 UI 显示	创作流
英文名称	用于 UI 显示和日志	Creative Stream
父资源	通常为 project	project

1.2 确定权限操作列表

参考已有资源类型（如 pipeline）设计操作列表：

操作类型	命名规范	说明	关联资源类型
create	{resource}_create	创建资源	project（特殊）
list	{resource}_list	列表查看	{resource}
view	{resource}_view	查看详情	{resource}
edit	{resource}_edit	编辑资源	{resource}
delete	{resource}_delete	删除资源	{resource}
execute	{resource}_execute	执行资源	{resource}
manage	{resource}_manage	权限管理	{resource}
其他	按需定义	如 download、share、archive	{resource}

注意: create 操作的 related_resource_type 必须是 project，因为创建时资源还不存在。

1.3 设计权限依赖关系

project_visit (基础权限)
    │
    ├── {resource}_create ──────────────────────────────┐
    │                                                   │
    └── {resource}_list                                 │
            │                                           │
            └── {resource}_view                         │
                    │                                   │
                    ├── {resource}_edit ────────────────┤
                    │       │                           │
                    │       ├── {resource}_manage       │
                    │       └── {resource}_archive      │
                    │                                   │
                    ├── {resource}_delete               │
                    ├── {resource}_execute              │
                    ├── {resource}_download             │
                    └── {resource}_share                │

---

第二步：后端枚举定义

2.1 修改 AuthResourceType.kt

文件路径: src/backend/ci/core/common/common-auth/common-auth-api/src/main/kotlin/com/tencent/devops/common/auth/api/AuthResourceType.kt

enum class AuthResourceType(val value: String) {
    // ... 已有枚举 ...
    
    PIPELINE_DEFAULT("pipeline"),
    PIPELINE_GROUP("pipeline_group"),
    PIPELINE_TEMPLATE("pipeline_template"),
    CREATIVE_STREAM("creative_stream"),  // 新增：创作流类型
    
    // ... 其他枚举 ...
}

命名规范:

• 枚举名：大写下划线 CREATIVE_STREAM
• value：小写下划线 creative_stream

---

第三步：IAM RBAC 配置文件

需要修改 support-files/bkiam-rbac/ 目录下的 5 个 JSON 文件：

3.1 资源类型定义 (0003_resource_*.json)

{
  "operation": "upsert_resource_type",
  "data": {
    "id": "creative_stream",
    "name": "创作流",
    "name_en": "Creative Stream",
    "parents": [
      {
        "system_id": "bk_ci_rbac",
        "id": "project"
      }
    ],
    "provider_config": {
      "path": "/api/open/auth/resource/instances/list?x-devops-project-id=rbac-project"
    },
    "version": 1
  }
}

3.2 实例选择器 (0004_instance-views_*.json)

{
  "operation": "upsert_instance_selection",
  "data": {
    "id": "creative_stream_instance",
    "name": "创作流",
    "name_en": "Creative Stream",
    "resource_type_chain": [
      {
        "system_id": "bk_ci_rbac",
        "id": "project"
      },
      {
        "system_id": "bk_ci_rbac",
        "id": "creative_stream"
      }
    ]
  }
}

3.3 操作定义 (0005_action_*.json)

每个操作需要定义：

{
  "operation": "upsert_action",
  "data": {
    "id": "creative_stream_view",
    "name": "查看创作流",
    "name_en": "Creative Stream View",
    "type": "view",
    "related_resource_types": [
      {
        "system_id": "bk_ci_rbac",
        "id": "creative_stream",
        "selection_mode": "instance",
        "related_instance_selections": [
          {
            "system_id": "bk_ci_rbac",
            "id": "creative_stream_instance"
          }
        ]
      }
    ],
    "related_actions": ["project_visit", "creative_stream_list"],
    "version": 1
  }
}

关键字段说明:

字段	说明
type	操作类型：view/edit/delete/create/execute
related_resource_types	操作关联的资源类型
selection_mode	选择模式：instance（实例级）/ all（全部）
related_actions	依赖的前置操作

create 操作的特殊配置:

{
  "id": "creative_stream_create",
  "related_resource_types": [
    {
      "system_id": "bk_ci_rbac",
      "id": "project",  // 关联 project 而非 creative_stream
      "selection_mode": "instance",
      "related_instance_selections": [
        {
          "system_id": "bk_ci_rbac",
          "id": "project_instance"
        }
      ]
    }
  ],
  "related_actions": ["project_visit"]
}

3.4 权限分组 (0006_group_*.json)

将所有操作归入一个分组，便于 IAM 界面展示：

{
  "operation": "upsert_action_groups",
  "data": {
    "action_groups": [
      {
        "name": "创作流",
        "name_en": "Creative Stream",
        "actions": [
          {"id": "creative_stream_create"},
          {"id": "creative_stream_list"},
          {"id": "creative_stream_view"},
          {"id": "creative_stream_edit"},
          {"id": "creative_stream_delete"},
          {"id": "creative_stream_execute"},
          {"id": "creative_stream_download"},
          {"id": "creative_stream_share"},
          {"id": "creative_stream_manage"},
          {"id": "creative_stream_archive"}
        ]
      }
    ]
  }
}

3.5 资源创建者关联操作 (0007_create-related_*.json)

定义创建资源后自动授予创建者的权限：

{
  "id": "creative_stream",
  "actions": [
    {"id": "creative_stream_list", "required": false},
    {"id": "creative_stream_view", "required": false},
    {"id": "creative_stream_edit", "required": false},
    {"id": "creative_stream_delete", "required": false},
    {"id": "creative_stream_execute", "required": false},
    {"id": "creative_stream_download", "required": false},
    {"id": "creative_stream_share", "required": false},
    {"id": "creative_stream_manage", "required": false},
    {"id": "creative_stream_archive", "required": false}
  ]
}

---

第四步：数据库 DML 脚本

4.1 脚本类型与用途

脚本类型	文件位置	用途	是否必须
初始化脚本	support-files/sql/5001_init_dml/5001_ci_auth-init_dml_mysql.sql	开源社区部署时的数据初始化	✅ 必须
增量脚本	openspec/changes/{change-id}/specs/auth-resource-type/xxx_dml.sql	内部线上已有数据的增量变更	内部使用
API 接口	/api/op/auth/resourceTypeConfig/*	内部线上已有数据的运行时变更	内部使用

重要:

• 初始化脚本是必须的，用于开源社区新部署时初始化权限数据
• 增量脚本和 API 接口二选一，用于内部线上环境的数据变更

4.2 表结构说明

表名	说明
T_AUTH_RESOURCE_TYPE	资源类型定义
T_AUTH_ACTION	操作定义
T_AUTH_RESOURCE_GROUP_CONFIG	用户组配置（资源级 + 项目级）

4.3 新增资源类型

REPLACE INTO T_AUTH_RESOURCE_TYPE (
    `ID`, RESOURCE_TYPE, NAME, ENGLISH_NAME, `DESC`, ENGLISH_DESC,
    PARENT, `SYSTEM`, CREATE_USER, CREATE_TIME, UPDATE_USER, UPDATE_TIME, `DELETE`
) VALUES (
    22,  -- 查询现有最大 ID + 1
    'creative_stream',
    '创作流',
    'Creative Stream',
    '创作流',
    'Creative Stream',
    'project',
    'bk_ci_rbac',
    'system',
    NOW(),
    'system',
    NOW(),
    0
);

4.4 新增操作定义

REPLACE INTO T_AUTH_ACTION(
    `ACTION`, RESOURCE_TYPE, RELATED_RESOURCE_TYPE, ACTION_NAME,
    ENGLISH_NAME, CREATE_USER, CREATE_TIME, UPDATE_TIME, `DELETE`, ACTION_TYPE
) VALUES
    ('creative_stream_view', 'creative_stream', 'creative_stream',
     '查看创作流', 'Creative Stream View', 'system', NOW(), NOW(), 0, 'view'),
    ('creative_stream_create', 'creative_stream', 'project',  -- 注意：关联 project
     '创建创作流', 'Creative Stream Create', 'system', NOW(), NOW(), 0, 'create'),
    -- ... 其他操作
;

4.5 新增资源级用户组

资源级用户组用于单个资源实例的权限管理：

-- 拥有者组 (全部权限)
REPLACE INTO T_AUTH_RESOURCE_GROUP_CONFIG(
    `ID`, `RESOURCE_TYPE`, `GROUP_CODE`, `GROUP_NAME`, `CREATE_MODE`, `GROUP_TYPE`,
    `DESCRIPTION`, `AUTHORIZATION_SCOPES`, `ACTIONS`
) VALUES (
    70,  -- 查询现有最大 ID + 1
    'creative_stream',
    'manager',
    '拥有者',
    0,
    0,
    '创作流拥有者，可以管理当前创作流的权限',
    '[授权范围 JSON]',
    '["creative_stream_view","creative_stream_edit",...]'
);

资源级用户组标准配置:

组代码	组名	典型权限
manager	拥有者	全部权限（除 create）
editor	编辑者	view + edit + execute + list + download + share
executor	执行者	view + execute + list + download + share
viewer	查看者	view + list + download + share

4.6 更新项目级用户组

为现有项目级用户组添加新资源的权限：

-- 使用 JSON_ARRAY_APPEND 追加权限
UPDATE T_AUTH_RESOURCE_GROUP_CONFIG
SET AUTHORIZATION_SCOPES = JSON_ARRAY_APPEND(
    AUTHORIZATION_SCOPES,
    '$',
    JSON_OBJECT(
        'system', '#system#',
        'actions', JSON_ARRAY(
            JSON_OBJECT('id', 'creative_stream_list'),
            JSON_OBJECT('id', 'creative_st

---

*Content truncated.*