中文英文
 编辑文档
 反馈问题
 社区讨论

本页导航

构建

# 新建构建

请求

POST /openapi/build?projectKey=<项目标识>
1

body 参数说明

参数名说明类型必填
name构建名称string是
project_key项目标识string是
infrastructure基础设施，kubernetes 为 kubernetes 集群，vm 为主机string是
build_os构建操作系统string是
installs依赖的软件包string是
script_type脚本类型，支持 shell、batch_file、powershellstring是
build_script构建操作系统string是
repo_info代码信息[]RepoInfo否
parameters自定义变量[]Parameter否
services绑定的服务[]ServiceWithModule是
docker_build_step镜像构建步骤[]DockerBuildStep否
advanced_settings高级设置[]AdvancedSettings否

ServiceWithModule 参数说明

参数名说明类型必填
service_module服务组件名称string是
service_name服务名称string是

RepoInfo 参数说明

参数名说明类型必填
codehost_name代码源标识string是
repo_namespace代码库所属命名空间（组织/个人）string是
repo_name代码库名称string是
branch分支信息string是

Parameter 参数说明

参数名说明类型必填
key变量的键值string是
type变量的类型，支持 string、choice、multi-selectstring是
is_credential是否为敏感信息bool否
description变量的描述string否
default_value变量的默认值string是
choice_value变量的多选值列表[]string否
choice_option变量的可选值列表[]string否

Input 参数说明

参数名说明类型必填
key变量的键值string是
value变量的值string是

DockerBuildStep 参数说明

参数名说明类型必填
dockerfile_sourceDockerfile 源，local 为代码库，template 为模板库string是
build_context_dir构建上下文目录string是
dockerfile_directoryDockerfile 的绝对路径string是
build_args构建参数string否
template_name模板名称string否
enable_buildkit是否启用 Buildkitstring否
platformsBuildkit 构建平台string否

AdvancedSettings 参数说明

参数名说明类型必填
cluster_name集群名称string否
strategy_name调度策略名称string否
timeout构建超时时间int否
resource_spec集群配置项列表ResourceSpec否
use_host_docker_daemon是否使用宿主机docker daemonbool否
privileged_mode是否启用特权模式bool否
cache_setting缓存配置CacheSetting否
storages存储配置StorageSetting否
custom_annotations自定义注解[]Input否
custom_labels自定义标签[]Input否
outputs输出变量[]string否

ResourceSpec 参数说明

参数名说明类型必填
cpu_reqCPU 请求int是
cpu_limitCPU 限制int是
memory_req内存请求int是
memory_limit内存限制int是
gpu_limitGPU 限制string否

CacheSetting 参数说明

参数名说明类型必填
enabled是否启用缓存bool是
cache_dir缓存目录string是

StorageSetting 参数说明

参数名说明类型必填
enabled是否启用存储bool是
storages_properties存储属性列表[]StoragesProperty是

StoragesProperty 参数说明

参数名说明类型必填
access_mode访问模式，如不设置则默认为 ReadWriteMany，支持 ReadWriteOnce、 ReadOnlyMany、 ReadWriteMany、 ReadWriteOncePodstring否
is_temporary是否为临时存储bool否
mount_path挂载路径string是
provision_type存储类型，dynmaic 为动态资源，static 为已有存储string是
pvcPVC名称，provision_type 为 static 时使用该字段string否
storage_class存储类名称，provision_type 为 dynamic 时使用该字段string否
storage_size_in_gib存储大小，provision_type 为 dynamic 时使用该字段int是
subpath存储卷子路径string是

body 参数示例

{
    "build_os": "ubuntu 20.04",
    "build_script": "#!/bin/bash\nset -e\necho 'hello from api'\ncd $REPONAME_0\nmake build-$SERVICE",
    "docker_build_step": {
        "build_args": "--build-arg service=$SERVICE",
        "build_context_dir": "$REPONAME_0",
        "dockerfile_directory": "$REPONAME_0/Dockerfile",
        "dockerfile_source": "local",
        "enable_buildkit": true,
        "platforms": "linux/amd64",
        "template_name": ""
    },
    "infrastructure": "kubernetes",
    "installs": [
        {
            "name": "go",
            "version": "1.20.7"
        }
    ],
    "name": "api-test",
    "parameters": [
        {
            "choice_option": [
                "a",
                "b",
                "c"
            ],
            "choice_value": [
                "a",
                "b"
            ],
            "default_value": "a",
            "description": "a multi-select var",
            "is_credential": false,
            "key": "aa",
            "type": "multi-select"
        },
        {
            "default_value": "abc123",
            "description": "a string values",
            "is_credential": true,
            "key": "bb",
            "type": "string"
        }
    ],
    "project_key": "yaml",
    "repo_info": [
        {
            "branch": "main",
            "codehost_name": "gitlab",
            "repo_name": "multi-service-demo",
            "repo_namespace": "kr-test-org1"
        }
    ],
    "script_type": "shell",
    "services": [
        {
            "service_module": "service1",
            "service_name": "service1"
        },
        {
            "service_module": "service2",
            "service_name": "service2"
        }
    ],
    "advanced_settings": {
        "cache_setting": {
            "cache_dir": "$WORKSPACE",
            "enabled": true
        },
        "cluster_name": "local-20250523164625",
        "custom_annotations": [
            {
                "key": "test-a",
                "value": "abc"
            }
        ],
        "custom_labels": [
            {
                "key": "test-a",
                "value": "abc"
            }
        ],
        "outputs": [
            "bb"
        ],
        "privileged_mode": false,
        "resource_spec": {
            "cpu_limit": 1000,
            "cpu_req": 100,
            "memory_limit": 2000,
            "memory_req": 200
        },
        "storages": {
            "enabled": true,
            "storages_properties": [
                {
                    "access_mode": "ReadOnlyMany",
                    "is_temporary": true,
                    "mount_path": "/workspace",
                    "provision_type": "dynamic",
                    "pvc": "share-storage-cfs-10",
                    "storage_class": "cfs",
                    "storage_size_in_gib": 2,
                    "subpath": "$PROJECT"
                }
            ]
        },
        "strategy_name": "优先调度",
        "timeout": 30,
        "use_host_docker_daemon": false
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

返回

{
  "message": "success"
}
1
2
3

# 更新构建

请求

PUT /openapi/build?projectKey=<项目标识>
1

body 参数说明

参数名说明类型必填
name构建名称string是
project_key项目标识string是
infrastructure基础设施，kubernetes 为 kubernetes 集群，vm 为主机string是
build_os构建操作系统string是
installs依赖的软件包string是
script_type脚本类型，支持 shell、batch_file、powershellstring是
build_script构建操作系统string是
repo_info代码信息[]RepoInfo否
parameters自定义变量[]Parameter否
services绑定的服务[]ServiceWithModule是
docker_build_step镜像构建步骤[]DockerBuildStep否
advanced_settings高级设置[]AdvancedSettings否

body 参数示例

{
    "build_os": "ubuntu 20.04",
    "build_script": "#!/bin/bash\nset -e\necho 'hello from api'\ncd $REPONAME_0\nmake build-$SERVICE",
    "docker_build_step": {
        "build_args": "--build-arg service=$SERVICE",
        "build_context_dir": "$REPONAME_0",
        "dockerfile_directory": "$REPONAME_0/Dockerfile",
        "dockerfile_source": "local",
        "enable_buildkit": true,
        "platforms": "linux/amd64",
        "template_name": ""
    },
    "infrastructure": "kubernetes",
    "installs": [
        {
            "name": "go",
            "version": "1.20.7"
        }
    ],
    "name": "api-test",
    "parameters": [
        {
            "choice_option": [
                "a",
                "b",
                "c"
            ],
            "choice_value": [
                "a",
                "b"
            ],
            "default_value": "a",
            "description": "a multi-select var",
            "is_credential": false,
            "key": "aa",
            "type": "multi-select"
        },
        {
            "default_value": "abc123",
            "description": "a string values",
            "is_credential": true,
            "key": "bb",
            "type": "string"
        }
    ],
    "project_key": "yaml",
    "repo_info": [
        {
            "branch": "main",
            "codehost_name": "gitlab",
            "repo_name": "multi-service-demo",
            "repo_namespace": "kr-test-org1"
        }
    ],
    "script_type": "shell",
    "services": [
        {
            "service_module": "service1",
            "service_name": "service1"
        },
        {
            "service_module": "service2",
            "service_name": "service2"
        }
    ],
    "advanced_settings": {
        "cache_setting": {
            "cache_dir": "$WORKSPACE",
            "enabled": true
        },
        "cluster_name": "local-20250523164625",
        "custom_annotations": [
            {
                "key": "test-a",
                "value": "abc"
            }
        ],
        "custom_labels": [
            {
                "key": "test-a",
                "value": "abc"
            }
        ],
        "outputs": [
            "bb"
        ],
        "privileged_mode": false,
        "resource_spec": {
            "cpu_limit": 1000,
            "cpu_req": 100,
            "memory_limit": 2000,
            "memory_req": 200
        },
        "storages": {
            "enabled": true,
            "storages_properties": [
                {
                    "access_mode": "ReadOnlyMany",
                    "is_temporary": true,
                    "mount_path": "/workspace",
                    "provision_type": "dynamic",
                    "pvc": "share-storage-cfs-10",
                    "storage_class": "cfs",
                    "storage_size_in_gib": 2,
                    "subpath": "$PROJECT"
                }
            ]
        },
        "strategy_name": "优先调度",
        "timeout": 30,
        "use_host_docker_daemon": false
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

返回

{
  "message": "success"
}
1
2
3

# 使用模板新建构建

请求

POST /openapi/build?source=template
1

body 参数说明

参数名说明类型必填
name构建名称string是
project_key项目标识string是
template_name构建模板名称string是
target_services服务配置[]TargetService是

TargetService 参数说明

参数名说明类型必填
service_module服务组件名称string是
service_name服务名称string是
repo_info代码库信息[]RepoInfo是
inputs变量信息[]Input是

RepoInfo 参数说明

参数名说明类型必填
codehost_name代码源标识string是
repo_namespace代码库所属命名空间（组织/个人）string是
repo_name代码库名称string是
branch分支信息string是

Input 参数说明

参数名说明类型必填
key变量的键值string是
value变量的值string是

body 参数示例

{
    "name": "demo-build",
    "project_key": "demo",
    "template_name": "demo-template",
    "target_services": [
        {
            "service_module": "aslan",
            "service_name": "zadigx",
            "repo_info": [
                {
                    "codehost_name": "github-demo",
                    "repo_namespace": "kr-test-org",
                    "repo_name": "zadig",
                    "branch": "main"
                }
            ],
            "inputs": [
                {
                    "key": "name",
                    "value": "admin"
                },
                {
                  "key": "password",
                  "value": "zadigx"
                }
            ]
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

返回

{
  "message": "success"
}
1
2
3

# 更新从模版创建的构建

请求

PUT /openapi/build/<构建名称>/template?projectKey=<项目标识>
1

body 参数说明

参数名说明类型必填
name构建名称string是
project_key项目标识string是
template_name构建模板名称string是
target_services服务配置[]TargetService是

body 参数示例

{
    "name": "demo-build",
    "project_key": "demo",
    "template_name": "demo-template",
    "target_services": [
        {
            "service_module": "aslan",
            "service_name": "zadigx",
            "repo_info": [
                {
                    "codehost_name": "github-demo",
                    "repo_namespace": "kr-test-org",
                    "repo_name": "zadig",
                    "branch": "main"
                }
            ],
            "inputs": [
                {
                    "key": "name",
                    "value": "admin"
                },
                {
                  "key": "password",
                  "value": "zadigx"
                }
            ]
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

返回

{
  "message": "success"
}
1
2
3

# 查询构建列表

请求

GET /openapi/build?projectKey=<项目标识>&pageNum=<当前页数>&pageSize=<当前页显示条数>
1

query 参数说明

参数名类型描述是否必须默认值
projectKeystring项目标识是无
pageNumint分页参数-当前页数否1
pageSizeint分页参数-当前页显示条数否20

返回说明

参数名类型描述
totalint构建模块总数
builds[]Build构建模块列表

Build 参数说明

参数名类型描述
namestring构建名称
project_keystring项目标识
sourcestring构建方式，有以下两种：zadig、jenkins
update_bystring更新者
update_timeint更新时间
target_services[]TargetService服务组件列表

TargetService 参数说明

参数名类型描述
service_namestring服务名称
service_modulestring服务组件名称

正常返回

点击查看
{
    "total": 2,
    "builds": [
        {
            "name": "s-build",
            "project_key": "lilian-test",
            "source": "zadig",
            "update_by": "admin",
            "update_time": 1686192895,
            "target_services": [
                {
                    "service_name": "service1",
                    "service_module": "service1"
                },
                {
                    "service_name": "service2",
                    "service_module": "service2"
                }
            ]
        },
        {
            "name": "openapi-build",
            "project_key": "lilian-test",
            "source": "zadig",
            "update_by": "admin",
            "update_time": 1688040721,
            "target_services": [
                {
                    "service_name": "service1",
                    "service_module": "service1"
                }
            ]
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# 获取构建详情

请求

GET /openapi/build/:buildName/detail?projectKey=<项目标识>
1

query 参数说明

参数名类型描述是否必须默认值
projectKeystring项目标识是无
serviceNamestring服务名称是无
serviceModulestring服务组件名称是无

路径参数说明

参数名类型描述是否必须默认值
buildNamestring构建名称是无

返回说明

点击查看
{
    "project_key": "lilian-test", // 项目标识
    "name": "openapi-build", // 构建名称
    "source": "",	// 构建方式，分别有 zadig,jenkins两种
    "target_services": [	// 服务列表
        {
            "service_name": "service1", // 服务名称
            "service_module": "service1" // 服务组件名称
        }
    ],
    "template_name": "test", // 模板名称
    "update_by": "admin",	// 更新的用户名称
    "update_time": 1690215924, // 更新时间，秒级时间戳
    "repos": [ // 代码源信息
      {
            "source": "gitee", // 有以下几种类型：github、gitlab、gerrit、codehub、gitee、gitee-enterprise、other
            "repo_owner": "liyue326",	// 组织名/用户名
            "repo_name": "hello",	// 代码库名称
            "remote_name": "origin", // Remote name
            "branch": "master",	// 分支名称
        		"address":"https://gitlab.com",	// 代码源
        		"checkout_path":"", // 克隆目录名
        		"submodules":false,	 // 子模块
        },
    ],
    "build_env": { // 构建环境
        "basic_image_id": "63047770931401b9baa6e396",	// 操作系统镜像ID
        "basic_image_label": "ubuntu 20.04",	// 操作系统镜像名称
        "installs": [	// 构建依赖的软件包列表
            {
                "name": "go",
                "version": "1.13"
            }
        ]
    },
    "advanced_settings": { // 高级配置
        "cluster_name": "local-20220823144517",	// 集群名称
        "timeout": 60,	// 构建超时时间
        "resource_spec": {	// 集群配置项列表
            "cpu_limit": 1000,
            "memory_limit": 512,
            "gpu_limit": ""
        },
      	"use_host_docker_daemon": false, // 是否使用宿主机docker daemon
        "cache_setting": {	// 缓存配置
            "enabled": false,	// 是否使用自定义工作空间
            "cache_dir": ""	// 自定义工作流空间下的缓存路径
        }
    },
    "build_script": "#!/bin/bash\nset -e",	// 构建脚本
    "parameters": [	// 自定义变量列表
        {
            "key": "a",
            "value": "1",
            "type": "string",
            "is_credential": false
        }
    ]
    "outputs": [	// 输出变量列表
        {
            "name": "IMAGE",
            "description": ""
        },
        {
            "name": "PKG_FILE",
            "description": ""
        },
        {
            "name": "xx",
            "description": ""
        }
    ],
    "post_build": {	// 添加步骤
        "docker_build": {	// 镜像构建配置
            "work_dir": "temp",	// 构建上下文目录
            "docker_file": "temp",	// Dockerfile 的绝对路径
            "build_args": "",	// 构建参数
            "source": "local",	// Dockerfile 来源
            "template_name": ""	// template名称（如果dockerfile来源是模板)
        },
        "object_storage_upload": {	// 文件存储
            "enabled": true,	// 是否使用工作空间缓存
            "object_storage_id": "63422e0690069fe35f4e62bb",	// sidebarMenu.objectStorage
            "upload_detail": [	// 上传文件配置
                {
                    "file_path": "test",
                    "abs_file_path": "",
                    "dest_path": "temp"
                }
            ]
        },
        "file_archive": {	// 二进制包存储
            "file_location": "temp"	// 二进制包存储路径
        },
        "scripts": "#!/bin/bash\nset -e"	// Shell 脚本
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# 删除构建

请求

DELETE /openapi/build?name=<构建名称>&projectKey=<项目标识>
1

query 参数说明

参数名说明类型必填
name构建名称string是
projectKey项目标识string是

返回说明

{
  "message": "success"
}
1
2
3

← 测试→

资源
教程
论坛
博客
公司
关于
客户故事
加入我们
联系我们
微信扫一扫
hello@koderover.com

© 2026 筑栈（上海）信息技术有限公司 沪 ICP 备 19000177 号 - 1