华为云用户手册

请求示例：上传对象 1 2 3 4 5 6 7 8 9 10 PUT /object01 HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: WED, 01 Jul 2015 04:11:15 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:gYqplLq30dEX7GMi2qFWyjdFsyw= Content-Length: 10240 Expect: 100-continue [1024 Byte data content]

功能介绍 用户在OBS系统中创建了桶之后，可以采用PUT操作的方式将对象上传到桶中。上传对象操作是指在指定的桶内增加一个对象，执行该操作需要用户拥有桶的写权限。 同一个桶中存储的对象名是唯一的。 在桶未开启多版本的情况下，如果在指定的桶内已经有相同的对象键值的对象，用户上传的新对象会覆盖原来的对象；为了确保数据在传输过程中没有遭到破坏，用户可以在请求消息头中加入Content-MD5参数。在这种情况下，OBS收到上传的对象后，会对对象进行MD5校验，如果不一致则返回出错信息。 用户还可以在上传对象时指定x-obs-acl参数，设置对象的权限控制策略。如果匿名用户在上传对象时未指定x-obs-acl参数，则该对象默认可以被所有OBS用户访问。 该操作支持服务端加密功能。 单次上传对象大小范围是[0, 5GB]，如果需要上传超过5GB的大文件，需要通过多段操作来分段上传。 OBS没有文件夹的概念。为了使用户更方便进行管理数据，OBS提供了一种方式模拟文件夹：通过在对象的名称中增加“/”，例如“test/123.jpg”。此时，“test”就被模拟成了一个文件夹，“123.jpg”则模拟成“test”文件夹下的文件名了，而实际上，对象名称（Key）仍然是“test/123.jpg”。此类命名方式的对象，在控制台上会以文件夹的形式展示。当您上传此类方式命名的对象时，如果其大小不为0，控制台上会展示为空文件夹，但是存储总用量为对象大小。 对象名中包含特殊字符时需要进行URL编码，例如：#obj需要编码为%23obj。

与POST上传的区别 PUT上传中参数通过请求头域传递；POST上传则作为消息体中的表单域传递。 PUT上传需在URL中指定对象名；POST上传提交的URL为桶域名，无需指定对象名。两者的请求行分别为： PUT /ObjectName HTTP/1.1 POST / HTTP/1.1 使用PUT上传请求时，消息体中如果使用POST格式，则上传到OBS中的对象会以表单形式呈现。 关于POST上传的更多详细信息，请参考POST上传。

请求示例：上传对象的同时设置ACL 1 2 3 4 5 6 7 8 9 10 11 PUT /object01 HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: WED, 01 Jul 2015 04:13:55 GMT x-obs-grant-read:id=52f24s3593as5730ea4f722483579ai7,id=a93fcas852f24s3596ea8366794f7224 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:gYqplLq30dEX7GMi2qFWyjdFsyw= Content-Length: 10240 Expect: 100-continue [1024 Byte data content]

响应示例：上传对象 1 2 3 4 5 6 7 HTTP/1.1 200 OK Server: OBS x-obs-request-id: BF2600000164364C10805D385E1E3C67 ETag: "d41d8cd98f00b204e9800998ecf8427e" x-obs-id-2: 32AAAWJAMAABAAAQAAEAABAAAQAAEAABCTzu4Jp2lquWuXsjnLyPPiT3cfGhqPoY Date: WED, 01 Jul 2015 04:11:15 GMT Content-Length: 0

响应示例：上传对象的同时设置ACL 1 2 3 4 5 6 7 HTTP/1.1 200 OK Server: OBS x-obs-request-id: BB7800000164845759E4F3B39ABEE55E ETag: "d41d8cd98f00b204e9800998ecf8427e" x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAA BCS ReVRNuas0knI+Y96iXrZA7BLUgj06Z Date: WED, 01 Jul 2015 04:13:55 GMT Content-Length: 0

功能介绍 跨区域复制是指跨不同区域中的桶自动、异步地复制对象。通过激活跨区域复制，OBS可将新创建的对象及修改的对象从一个源桶复制到不同区域中的目标桶。 配置跨区域复制需要选择 IAM 委托，配置方法请参见创建IAM委托。 设置桶的跨区域复制，需要满足以下两个要求： 要求源桶和目标桶多版本状态保持一致，否则不能设置replication。如何设置桶的多版本，请参见设置桶的多版本状态。 源桶的拥有者和代理人（OBS）必须要有目标桶的写权限（目标桶需要配置BucketPolicy），同时代理人（OBS）还要有源桶的读权限。这需要通过“BucketPolicy”来实现这个权限委托。 如何设置桶策略，请参见设置桶策略。设置桶策略后，代理人（OBS）就有权限可以读取源桶的对象，也有权限将对象复制到目标桶中。

响应示例 1 2 3 4 5 6 HTTP/1.1 200 OK Server: OBS x-obs-request-id: B59500000164417839932E5A2295674C x-obs-id-2: 32AAAQAAEAABKAAQAAEAABAAAQAAEAAB CS tv51t2NMMx+Ou+ow7IWV4Sxo231fKe Date: Wed, 27 Jun 2018 13:39:15 GMT Content-Length: 0

请求消息头 该请求使用的消息头如下所示。 表1 设置桶的复制配置请求消息头 名称 描述 是否必选 Content-MD5 按照RFC 1864标准计算出消息体的MD5摘要字符串，即消息体128-bit MD5值经过base64编码后得到的字符串。也支持设置Content-SHA256头域，其值为消息体256-bit SHA256值经过base64编码后得到的字符串，Content-MD5和Content-SHA256二选一。 是

请求消息元素 在此请求中，需要在请求的消息体中配置桶的复制配置，通知的配置信息以XML格式上传。具体的配置元素如下描述。 表2 设置桶的复制配置元素 名称 描述 是否必须 ReplicationConfiguration 复制规则的容器，最多可以达到100条规则，所有的复制配置大小可达到50KB。 类型：Container 子节点:Rule 父节点:无 是 Agency 用户创建的委托名字，最大长度为64字符。 类型：String 父节点：ReplicationConfiguration 是 Rule 一条特定复制规则信息的容器。 复制配置必须至少配置一条规则，最多能达到100条规则。 类型：Container 父节点: ReplicationConfiguration 是 ID 规则的特殊辨识符，最大长度为255字符。 类型：String 父节点:Rule 否 Status 如果Status为Disabled，这条规则会被忽略。 类型：String 父节点：Rule 有效值：Enabled,Disabled 是 Prefix 对象键值名的前缀，适配于一个或者多个对象。如果前缀配置为空，则跨区域复制规则将作用于整个桶。 经过UTF-8编码的长度大于0且不超过1024的字符序列，不支持重叠的前缀。 类型：String 父节点:Rule 是 Destination 目标桶信息的容器。 类型：Container 父节点:Rule 是 Bucket 存储被规则标识的对象副本的桶名称。 如果在复制配置中有多条规则，这些规则必须都要标识同一个桶作为目标桶。 类型：String 父节点：Destination 是 StorageClass 对象的存储类型。 类型：String 父节点：Destination 有效值：STANDARD|WARM|COLD 否 DeleteData 删除同步复制关键字，如果为Enabled，源桶的对象删除操作会复制到目标端。 类型：String 父节点：Destination 有效值：Enabled,Disabled（如果不设置，则默认为Disabled） 否 HistoricalObjectReplication 历史对象复制关键字，如果为Enabled，会复制符合这条规则的历史对象。 类型：String 父节点：Rule 有效值：Enabled, Disabled（如果不设置，则默认为Disabled） 否

响应消息头 该请求的响应消息使用公共消息头，具体请参考表1。 ETag返回的是本次追加上传数据的Hash值，不是整个对象的Hash值。 表4 附加响应消息头 消息头名称 描述 x-obs-version-id 对象的版本号。如果桶的多版本状态为开启，则会返回对象的版本号。 类型：String x-obs-server-side-encryption 如果服务端加密是SSE-KMS方式，响应包含该头域。 类型：String 示例：x-obs-server-side-encryption：kms x-obs-server-side-data-encryption 如果服务端加密是SSE-KMS方式，且 数据加密 算法为SM4，响应包含该头域。 类型：String 示例：x-obs-server-side-data-encryption：SM4 x-obs-server-side-encryption-kms-key-id 如果服务端加密是SSE-KMS方式，响应包含该头域，该头域表示主密钥。 类型：String 格式为： regionID:domainID(租户ID):key/key_id 其中regionID是使用密钥所属region的ID；domainID是使用密钥所属租户的租户ID；key_id是本次加密使用的密钥ID。 示例： x-obs-server-side-encryption-kms-key-id：cn-north-4:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0 x-obs-server-side-encryption-customer-algorithm 如果服务端加密是SSE-C方式，响应包含该头域，该头域表示加密使用的算法。 类型：String 示例：x-obs-server-side-encryption-customer-algorithm：AES256 x-obs-server-side-encryption-customer-key-MD5 如果服务端加密是SSE-C方式，响应包含该头域，该头域表示加密使用的密钥的MD5值。 类型：String 示例：x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== x-obs-next-append-position 指明下一次请求应该提供的position。 类型：Integer

请求示例：普通追加写对象 POST /object?append&position=0 HTTP/1.1 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Expires: Wed, 27 Jun 2015 13:45:50 GMT Date: Wed, 08 Jul 2015 06:57:01 GMT Content-Type: image/jpg Content-Length: 1458 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk= [1458 bytes of object data]

请求示例：已启用版本控制 POST /object01?append&position=0 HTTP/1.1 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4= User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.com Date: WED, 01 Jul 2015 02:37:22 GMT Content-Type: application/octet-stream [1458 bytes of object data]

错误响应消息 如果本次追加上传使对象长度超过对象长度限制，OBS返回400 Bad Request，错误码为AppendTooLarge。 如果position的值和当前对象的原始长度不一致，OBS返回409 Conflict，错误码为PositionNotEqualToLength。 如果指定桶中存在相同对象键值的对象，对象类型非Appendable，OBS返回409 Conflict，错误码为ObjectNotAppendable。 如果对象追加写次数超过10000次，OBS返回409 Conflict，错误码为ObjectNotAppendable。 如果对象存储类型为COLD（归档存储）或DEEP_ARCHIVE（深度归档存储），则不能调用该接口，否则OBS返回409 Conflict，错误码为ObjectNotAppendable。 如果桶设置了跨区域复制配置，则不能调用该接口，否则OBS返回400 Bad Request，错误码为OperationNotSupported。 其他错误已包含在表2中。

响应示例：普通追加写对象 1 2 3 4 5 6 7 8 HTTP/1.1 200 OK Date: Wed, 27 Jun 2015 13:45:50 GMT ETag: "d41d8cd98f00b204e9800998ecf8427e" Content-Length: 0 Server: OBS x-obs-request-id: 8DF400000163D3F0FD2A03D2D30B0542 x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCTjCqTmsA1XRpIrmrJdvcEWvZyjbztdd x-obs-next-append-position: 1458

请求示例：带redirect和自定义头域追加写对象 用户存在桶examplebucket，对象obj001不存在，通过追加写接口创建新对象， 设置重定向头域"x-obs-website-redirect-location":"http://www.example.com/"，自定义头域"x-obs-meta-redirect":"redirect"，请求为 POST /obj001?append&position=0 HTTP/1.1 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Expires: Wed, 27 Jun 2015 13:45:50 GMT Date: Wed, 08 Jul 2015 06:57:01 GMT x-obs-website-redirect-location: http://www.example.com/ x-obs-meta-redirect: redirect Content-Length: 6 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk= [6 bytes of object data]

响应示例：带redirect和自定义头域追加写对象 1 2 3 4 5 6 7 8 HTTP/1.1 200 OK Date: Wed, 27 Jun 2015 13:45:50 GMT ETag: "9516dfb15f51c7ee19a4d46b8c0dbe1d" Content-Length: 0 Server: OBS x-obs-request-id: 5DEB00000164A3150AC36F8F0C120D50 x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCSrVlTYwsA4p9GEW+LYqotSl5BYDxHfT x-obs-next-append-position: 6

响应示例：已启用版本控制 x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSZbDadL1f7fYU44bvRLvc0l6D10+wzG x-obs-request-id: 0000018A2BCBB3ABD3046B99E3ED2E30 Server: OBS Content-Length: 0 Date: WED, 01 Jul 2015 02:37:22 GMT x-obs-next-append-position: 4 ETag: "56468d5607a5aaf1604ff5e15593b003" x-obs-version-id: G001118A6803675AFFFFD3043F7F91D0

功能介绍 追加写对象操作是指在指定桶内的一个对象尾追加上传数据，不存在相同对象键值的对象则创建新对象。 通过Append Object操作创建的Object类型为Appendable Object，而通过Put Object上传的Object是Normal Object。 用户上传的对象存储在桶中。用户必须对桶有WRITE权限，才可以在桶中上传对象。同一个桶中存储的对象名必须是唯一的。 为了确保数据在传输过程中没有遭到破坏，用户可以在请求消息头中加入Content-MD5参数，OBS收到上传数据后，会对数据进行MD5校验，如果不一致则返回出错信息。 该操作支持在创建Appendable对象时指定x-obs-acl参数，设置对象的权限控制策略。 该操作支持服务端加密功能。

约束 每次追加上传都会更新该对象的最后修改时间。 服务端加密SSE-C方式，那么追加上传和初始化段一样，设置诸如x-obs-server-side-encryption之类的请求Header，后续追加上传也必须携带。 服务端加密SSE-KMS方式，有且只有第一次上传且桶内不存在同名对象时，才设置诸如x-obs-server-side-encryption之类的请求Header，后续追加上传不携带。 每次追加上传的长度不能超过对象长度上限5G的限制。 每个Appendable对象追加写次数最多为10000次。 如果对象存储类型为COLD（归档存储）或DEEP_ARCHIVE（深度归档存储），则不能调用该接口。 如果桶设置了跨区域复制配置，则不能调用该接口。 并行文件系统不支持追加写对象。

请求消息参数 该请求需要在消息中指定参数，表明这是追加写上传，同时指定本次追加上传位置，参数的具体意义如表1所示 表1 请求消息参数 参数名称 描述 是否必选 append 表明这是以追加写方式上传。 类型：String 是 position 追加写位置。需要追加写的对象首次上传时就必须指定position为0，下次追加需要填写的position会在服务端本次上传成功返回消息的头域x-obs-next-append-position中携带。 类型：Integer 是

请求消息参数 该请求通过请求消息参数指定多段上传任务以及列出的段数量，参数的具体含义如表1所示。 表1 请求消息参数 参数名称 描述 是否必选 uploadId 多段上传任务的id。 类型：String 默认值：无。 是 max-parts 规定在列举已上传段响应中的最大Part数目。 类型：Integer 默认值：1,000。 否 part-number -marker 指定List的起始位置，只有Part Number数目大于该参数的Part会被列出。 类型：Integer 默认值：无。 否 encoding-type 对响应中的Key进行指定类型的编码。如果Key包含xml 1.0标准不支持的控制字符，可通过设置encoding-type对响应中的Key进行编码。 类型：String 默认值：无。 可选值：url。 否

响应消息元素 该请求的响应通过消息元素返回已上传了的段信息，元素的具体含义如表2所示。 表2 响应消息元素 响应字段名称 描述 ListPartsResult 保存List Part请求结果的容器。 类型：Container 子节点： Bucket, Key, UploadId, PartNumberMarker,NextPartNumberMarker, MaxParts, IsTruncated, Part。 父节点：无。 Bucket Bucket名称。 类型：String 父节点：ListPartsResult。 EncodingType 对象Key的编码类型。如果请求中设置了encoding-type，那响应中的Key会被编码。 类型：String 父节点：ListPartsResult。 Key Object名称。 类型：String 父节点：ListPartsResult。 UploadId Upload任务ID。 类型：String 父节点：ListPartsResult。 Initiator Upload任务的创建者。 类型：Container 子节点：ID。 父节点：ListPartsResult。 Owner 和Initiator相同。 类型：Container 子节点: ID。 父节点: ListPartsResult。 ID 创建者的DomainId。 类型：String 父节点: Initiator、Owner。 StorageClass 存储类型。 类型：String 有效值： STANDARD | WARM | COLD 父节点：ListPartsResult。 PartNumberMarker 本次List结果的Part Number起始位置。 类型：Integer 父节点：ListPartsResult。 NextPartNumberMarker 如果本次没有返回全部结果，响应请求中将包含NextPartNumberMarker元素，用于标明接下来请求的PartNumberMarker值。 类型：Integer 父节点：ListPartsResult。 MaxParts 返回请求中最大的Part数目。 类型：Integer 父节点：ListPartsResult。 IsTruncated 标明是否本次返回的List Part结果列表被截断。“true”表示本次没有返回全部结果；“false”表示本次已经返回了全部结果。 类型：Boolean。 父节点：ListPartsResult。 Part 保存Part信息的容器。 类型：String 子节点：PartNumber, LastModified, ETag, Size。 父节点：ListPartsResult。 （PartNumber表示Part的数字。） PartNumber 已上传Part的编号。 类型：Integer 父节点：ListPartsResult.Part。 LastModified Part上传的时间。 类型：Date 父节点：ListPartsResult.part。 ETag 已上传段内容的ETag，是段内容的唯一标识，用于段合并时校验数据一致性。 类型：String 父节点：ListPartsResult.Part Size 已上传Part大小。 类型：Integer 父节点：ListPartsResult.Part。

错误响应消息 如果AccessKey或签名无效，OBS返回403 Forbidden，错误码为AccessDenied。 如果请求的桶不存在，OBS返回404 Not Found，错误码为NoSuchBucket。 如果请求的多段上传任务不存在，OBS返回404 Not Found，错误码为NoSuchUpload。 OBS判断用户DomainId是否具有指定桶的读权限，如果没有权限，则OBS返回403 Forbidden，错误码为AccessDenied。 其他错误已经包含在表2中。

请求示例 1 2 3 4 5 6 GET /object02?uploadId=00000163D40171ED8DF4050919BD02B8 HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: WED, 01 Jul 2015 05:20:35 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:xkABdSrBPrz5yqzuZdJnK5oL/yU=

修订记录 发布日期 修订记录 2024-04-02 第三十三次正式发布。 本次更新说明如下： 设置桶的加密配置接口丰富请求消息样式、请求和响应示例。 2024-03-22 第三十二次正式发布。 本次更新说明如下： 创建桶接口支持配置桶加密。 2024-02-19 第三十一次正式发布。 本次更新说明如下： 优化SSE-OBS加密方式相关描述。 2024-02-07 第三十次正式发布。 本次更新说明如下： PUT上传章节优化SSE-KMS加密方式相关参数描述。 2024-01-10 第二十九次正式发布。 本次更新说明如下： 服务端加密SSE-KMS方式章节新增默认密钥相关说明。 2024-01-05 第二十八次正式发布。 本次更新说明如下： 新增回调相关内容。 2023-12-25 第二十七次正式发布。 本次更新说明如下： 丰富多个接口请求和响应示例。 2023-11-13 第二十六次正式发布。 本次更新说明如下： 优化设置桶的网站配置参数描述。 2023-11-03 第二十五次正式发布。 本次更新说明如下： 刷新表1表格。 2023-09-28 第二十四次正式发布。 本次更新说明如下： 新增SSE-OBS服务端加密方式相关内容。 刷新获取账号、IAM用户、项目、用户组、区域、委托的名称和ID章节。 2023-06-28 第二十三次正式发布。 本次更新说明如下： 获取桶存量信息章节新增响应消息元素。 2023-06-21 第二十二次正式发布。 本次更新说明如下： 新增SM4加密算法相关内容。 2023-04-23 第二十一次正式发布。 本次更新说明如下： 新增WORM特性相关接口和说明。 2023-01-13 第二十次正式发布。 本次更新说明如下： 下线 SMN 通知功能。 2022-12-27 第十九次正式发布。 本次更新说明如下： 刷新深度归档存储（受限公测中）相关章节。 2021-08-11 第十八次正式发布。 本次更新说明如下： 获取桶列表接口新增响应消息头BucketType。 2021-07-19 第十七次正式发布。 本次更新说明如下： 新增消息头encoding-type，详细介绍参见如下接口： 列举桶内对象 批量删除对象 列举桶中已初始化多段任务 初始化上传段任务 列举已上传未合并的段 合并段 2021-07-09 第十六次正式发布。 本次更新说明如下： 新增自定义消息头x-obs-persistent-headers，涉及如下接口： PUT上传 POST上传 复制对象 追加写对象 初始化上传段任务 2020-09-10 第十五次正式发布。 本次更新说明如下： 新增Data+相关接口。 2020-06-30 第十四次正式发布。 本次更新说明如下： 新增镜像回源相关接口。 2020-01-20 第十三次正式发布。 本次更新说明如下： 更新“权限及授权项说明”的内容。 2019-12-25 第十二次正式发布。 本次更新说明如下： 新增桶加密相关接口。 2019-08-15 第十一次正式发布。 本次更新说明如下： 新增并行文件系统相关接口：修改写对象、截断对象、重命名对象。 创建桶接口的请求消息头中增加并行文件系统相关头域。 获取桶元数据接口的响应消息头中增加并行文件系统相关头域。 列举桶列表接口的请求消息头中增加x-obs-bucket-type头域。 2019-07-18 第十次正式发布。 本次更新说明如下： 新增归档对象直读相关接口：设置桶归档对象直读策略、获取桶归档对象直读策略、删除桶归档对象直读策略。 2019-07-01 第九次正式发布。 本次更新说明如下： 新增桶清单相关接口：设置桶清单、获取桶清单、列举桶清单、删除桶清单。 2019-06-12 第八次正式发布。 本次更新说明如下： 补充临时授权访问OBS的方法说明。 优化调整文档大纲。 2019-02-03 第七次正式发布。 本次更新说明如下： 修复部分易用性问题。 2019-01-18 第六次正式发布。 本次更新说明如下： 修复部分易用性问题。 2018-12-14 第五次正式发布。 本次更新说明如下： 上线 对象存储服务 新域名。 优化大纲。 新增修改对象元数据接口。 2018-10-19 第四次正式发布。 本次更新说明如下： 修复部分易用性问题。 2018-08-01 第三次正式发布。 本次更新说明如下： 修复部分易用性问题。 丰富部分接口的请求示例和响应示例。 2018-07-02 第二次正式发布。 本次更新说明如下： 修复部分易用性问题。 补充接口的请求示例和响应示例。 2018-06-08 第一次正式发布。

Notebook 自定义镜像 故障基础排查 当制作的自定义镜像使用出现故障时，请用户按照如下方法排查： 用户自定义镜像没有ma-user用户及ma-group用户组； 用户自定义镜像中/home/ma-user目录，属主和用户组不是ma-user和ma-group； 用户自定义镜像必须满足用户目录/home/ma-user权限为750，不能为其他权限； 用户自定义镜像使用远程SSH功能，OpenSSH版本要兼容或高于8.0； 用户制作的自定义镜像，在本地执行docker run启动，无法正常运行； 用户自行安装了Jupyterlab服务导致冲突的，需要用户本地使用Jupyterlab命令罗列出相关的静态文件路径，删除并且卸载镜像中的Jupyterlab服务； 用户自己业务占用了开发环境官方的8888、8889端口的，需要用户修改自己的进程端口号； 用户的镜像指定了PYTHONPATH、sys.path导致服务启动调用冲突的，需在实例启动后，再指定PYTHONPATH、sys.path； 用户使用了已开启sudo权限的专属池，使用自定义镜像时，sudo工具未安装或安装错误； 用户使用的cann、cuda环境有兼容性问题； 用户的docker镜像配置错误、网络或防火墙限制、镜像构建问题（文件权限、依赖缺失或构建命令错误）等原因导致的。 父主题： Notebook中使用自定义镜像

创建AI应用的自定义镜像规范 针对您本地开发的模型，在制作AI应用的自定义镜像时，需满足ModelArts定义的规范。 自定义镜像中不能包含恶意代码。 自定义镜像大小不超过50GB。 对于同步请求模式的AI应用，如果预测请求时延超过60s，会造成请求失败，甚至会有服务业务中断的风险，预测请求时延超过60s时，建议制作异步请求模式的镜像。 镜像对外接口 设置镜像的对外服务接口，推理接口需与config.json文件中apis定义的url一致，当镜像启动时可以直接访问。下面是mnist镜像的访问示例，该镜像内含mnist数据集训练的模型，可以识别手写数字。其中listen_ip为容器IP，您可以通过启动自定义镜像，在容器中获取容器IP。 请求示例 curl -X POST \ http://{listen_ip}:8080/ \ -F images=@seven.jpg 图1 listen_ip获取示例 返回示例 {"mnist_result": 7} （可选）健康检查接口 如果在滚动升级时要求不中断业务，那么必须在config.json文件中配置健康检查的接口，供ModelArts调用，在config.json文件中配置。当业务可提供正常服务时，健康检查接口返回健康状态，否则返回异常状态。 如果要实现无损滚动升级，必须配置健康检查接口。 自定义镜像如果需要在“在线服务”模块使用OBS外部存储挂载功能，需要新建一个OBS挂载专属目录如“/obs-mount/”，避免选择存量目录覆盖已有文件。OBS挂载仅开放对挂载目录文件新增、查看、修改功能不支持删除挂载目录文件对象，若需要删除文件请到OBS并行文件系统中手动删除。 健康检查接口示例如下。 URI GET /health 请求示例curl -X GET \ http://{listen_ip}:8080/health 响应示例 {"health": "true"} 状态码 表1 状态码 状态码 编码 状态码说明 200 OK 请求成功 日志文件输出 为保证日志内容可以正常显示，日志信息需要打印到标准输出。 镜像启动入口 如果需要部署批量服务，镜像的启动入口文件需要为“/home/run.sh”，采用CMD设置默认启动路径，例如Dockerfile如下： CMD ["sh", "/home/run.sh"] 镜像依赖组件 如果需要部署批量服务，镜像内需要安装python、jre/jdk、zip等组件包。 （可选）保持Http长链接，无损滚动升级 如果需要支持滚动升级的过程中不中断业务，那么需要将服务的Http的“keep-alive”参数设置为200s。以gunicorn服务框架为例，gunicorn缺省情形下不支持keep-alive，需要同时安装gevent并配置启动参数“--keep-alive 200 -k gevent”。不同服务框架参数设置有区别，请以实际情况为准。 （可选）处理SIGTERM信号，容器优雅退出 如果需要支持滚动升级的过程中不中断业务，那么需要在容器中捕获SIGTERM信号，并且在收到SIGTERM信号之后等待60秒再优雅退出容器。提前优雅退出容器可能会导致在滚动升级的过程中业务概率中断。要保证容器优雅退出，从收到SIGTERM信号开始，业务需要将收到的请求全部处理完毕再结束，这个处理时长最多不超过90秒。例如run.sh如下所示： #!/bin/bash gunicorn_pid="" handle_sigterm() { echo "Received SIGTERM, send SIGTERM to $gunicorn_pid" if [ $gunicorn_pid != "" ]; then sleep 60 kill -15 $gunicorn_pid # 传递 SIGTERM 给gunicorn进程 wait $gunicorn_pid # 等待gunicorn进程完全终止 fi } trap handle_sigterm TERM 父主题： 使用自定义镜像创建AI应用（推理部署）

PyTorch框架启动原理 规格和节点个数 下面以选择“GPU: 8*GP-Vnt1 | CPU: 72核 | 内存：512GB”规格为例，介绍在单机和分布式场景下ModelArts规格资源的分配情况。 单机作业时（即选择的节点数为1），ModelArts只会在一个节点上启动一个训练容器，该训练容器独享节点规格的可使用资源。 分布式作业时（即选择的节点数大于1），worker的数量和创建作业时选择的节点数一致，每个worker将被分配到所选规格对应的计算资源。例如计算节点个数为“2”时，将启动2个worker，每个worker拥有“GPU: 8*GP-Vnt1 | CPU: 72核 | 内存：512GB”的计算资源。目前PyTorch引擎仅支持GPU和CPU类型的规格，如果需要使用昇腾规格，请参考Ascend-Powered-Engine。 网络通信介绍 单机作业不涉及网络通信情况。 分布式作业的涉及网络通信则可以分为节点内网络通信和节点间网络通信。 节点内网络 使用NVLink和共享内存通信。 节点间网络 当计算节点个数大于1时，将启动PyTorch引擎分布式训练模式。PyTorch引擎的分布式模式如下图所示，worker之间可通过容器网络和100Gbps的InfiniBand网卡或RoCE网卡通信，部分规格中使用RoCE网卡，将在规格中额外提示。其中，容器网络可以通过DNS域名通信，但网络性能一般，可用于点对点小规模通信需求；InfiniBand网络和RoCE网络为高性能网络，可用于集合通信等分布式训练的场景。 图1 分布式模式

Tensorflow框架启动原理 规格和节点个数 下面以选择“GPU: 8*GP-Vnt1 | CPU: 72核 | 内存：512GB”规格为例，介绍在单机和分布式场景下ModelArts规格资源的分配情况。 单机作业时（即选择的节点数为1），ModelArts只会在一个节点上启动一个训练容器，该训练容器独享节点规格的可使用资源。 分布式作业时（即选择的节点数大于1），ModelArts会优先在相同节点上启动一个parameter server（以下简称ps）和一个worker，其中ps将分配一半的CPU和内存资源，即ps拥有“CPU: 36核 | 内存：256GB”的计算资源，worker拥有“GPU: 8*GP-Vnt1 | CPU: 36核 | 内存：256GB”的计算资源。 需要注意的是ps只会分配到CPU和内存资源，而worker除CPU和内存外，还可能分配到加速卡（纯CPU规格除外）。如本例中，每个worker将分配到八张GP Vnt1加速卡，如果ps和worker在相同节点上启动，则磁盘资源由ps和worker共享。 网络通信介绍 单机作业不涉及网络通信情况。 分布式作业的涉及网络通信则可以分为节点内网络通信和节点间网络通信。 节点内网络 节点内网络通信即同一个节点上的ps和woker间的网络通信，又可以分为两种情况：容器网络和主机网络。 在使用公共规格进行训练时，使用的是容器网络。 在使用专属池训练时，如果节点配置的是RoCE网卡，使用的是主机网络；如果节点配置的是Infiniband网卡，使用的是容器网络。 节点间网络 分布式作业存在节点间ps和worker的通信，当前ModelArts主要提供了Infiniband网卡或RoCE网卡，带宽高达100Gb/s。