Skip to Content
GPU 接口文档GPU实例在实例容器内执行命令
GPU API 接口

在实例容器内执行命令

接口说明

在指定 CPod GPU 实例(cpod-...)的业务容器内执行 Bash 命令。命令在容器内执行,不在宿主机执行。

POSThttps://api.compshare.cnActionRunCompShareInstanceCommand

接口支持两种执行方式:

  • 同步执行:Type=sync,也是省略 Type 时的默认行为。等待命令执行结束,返回执行结果及输出。
  • 异步执行:Type=async,校验并创建任务后返回 TaskId,再通过 GetCompShareInstanceCommandResult 查询结果。耗时较长的命令建议使用异步方式。

使用控制台 账户中心 → API 密钥 中的公钥/私钥进行云 API 签名鉴权(前往 API 密钥 )。该凭证与模型服务的 API Key 不同;下方 SDK 示例会自动完成签名。

使用限制

  • 实例须属于当前组织,调用方须有实例操作权限;实例须处于正常运行状态,停止、删除、重装或迁移中的实例不可执行。
  • Command 必须是非空 UTF-8 文本,不含 NUL 字符,按 UTF-8 编码后最多 256 KiB。
  • 标准输出与标准错误合并返回,最多 1 MiB。输出超限或包含非法 UTF-8 时执行失败,保留限制内的有效 UTF-8 前缀。
  • 同步和异步执行共用 1800 秒(30 分钟) 的服务端预算,包含校验、连接和执行时间。同步调用建议将客户端超时设为至少 1900 秒,并确保中间代理允许相应的等待时间。
  • 镜像需具备 /bin/bash、GNU coreutils、util-linux(setsid)、Linux /proc 和可写的临时目录。

执行语义

  • 整段 Command 在同一个 Bash 中执行,沿用容器配置的用户、工作目录和环境,支持多行命令、cd、export、管道及 here-document。
  • 不分配交互式终端,命令的标准输入为 /dev/null,不支持等待用户输入。
  • 默认不启用 set -e 或 pipefail,按 Bash 最终退出状态判断结果。如需中途失败即停止,可在命令开头自行添加 set -e 或 set -euo pipefail。
  • 主 Shell 退出、超时或输出超限后,会清理本次执行的同进程组后台任务。Type=async 仅改变结果获取方式,不能用来保留常驻后台进程。
  • 客户端断开连接不会额外取消命令,命令仍受服务端执行预算约束。

失败或超时不代表命令未执行,也不代表已产生的修改会回滚。请关闭自动重试;异步提交成功后应保存 TaskId 并查询原任务,避免重复提交命令。


请求参数

名称类型必填描述示例值
ActionString是接口名称RunCompShareInstanceCommand
InstanceIdString是CPod 实例 ID,以 cpod- 开头cpod-xxxx
CommandString是要执行的 Bash 命令或多行脚本,最多 256 KiBecho hello
TypeString否执行方式,可选 sync(同步,默认)或 async(异步),区分大小写async

地域、可用区和连接凭据由服务端按 InstanceId 查询,无需传入 Region、Zone 或实例登录密码。


响应参数

同步执行

名称类型描述示例值
RetCodeInteger0 表示执行成功,226656 表示执行相关失败;不是 Bash 进程退出码0
OutputString标准输出与标准错误的合并文本。失败时可能有部分输出,无输出时为空字符串hello\n

异步提交成功

名称类型描述示例值
RetCodeInteger0 仅表示任务提交成功,不表示命令执行成功0
TaskIdString异步任务 ID,用于查询执行状态和结果673000000000000000000001

若异步提交在参数、权限或实例状态等校验阶段失败,也可能直接返回 RetCode=226656 和空 Output,此时没有 TaskId。

错误处理

  • 226656:包括参数或实例校验不通过、连接失败、Bash 非零退出、超时、输出超限、输出编码或结果采集/清理失败等情况。
  • JSON 解析、参数构造、入口策略及框架错误沿用公共错误格式,按 RetCode、Message 排查,此类响应不一定包含 Output。
  • 同步请求未拿到结果时,没有可用于结果查询的 TaskId。需要后续查询的场景应使用异步执行。

请求示例

同步请求参数

以下 JSON 展示业务参数,实际请求还需签名:

{ "Action": "RunCompShareInstanceCommand", "InstanceId": "cpod-xxxx", "Command": "echo hello", "Type": "sync" }

多行脚本使用 JSON 字符串中的 \n 表示换行,例如:

{ "Action": "RunCompShareInstanceCommand", "InstanceId": "cpod-xxxx", "Command": "set -euo pipefail\ncd /workspace\nexport MODEL_DIR=/workspace/models\npython /workspace/check.py" }

异步请求参数

{ "Action": "RunCompShareInstanceCommand", "InstanceId": "cpod-xxxx", "Command": "echo hello", "Type": "async" }

Python(使用 UCloud SDK)

安装示例所用的 SDK 版本:

python -m pip install "ucloud-sdk-python3==0.11.153"

配置环境变量:

export COMPSHARE_ACCESS_KEY_ID='<AccessKey ID>' export COMPSHARE_ACCESS_KEY_SECRET='<AccessKey Secret>' export COMPSHARE_INSTANCE_ID='<实例 ID>'

示例使用 SDK 的泛化调用 invoke:

import json import os from ucloud.client import Client from ucloud.core import exc from ucloud.core.utils.middleware import Middleware def run_instance_command(instance_id, command, execution_type="sync"): captured = {} middleware = Middleware() @middleware.response def capture_response(data, http_response): # SDK 在 RetCode 非零时抛出异常,先保存完整响应以保留 Output。 captured["body"] = data return data client = Client( { "public_key": os.environ["COMPSHARE_ACCESS_KEY_ID"], "private_key": os.environ["COMPSHARE_ACCESS_KEY_SECRET"], "base_url": "https://api.compshare.cn", "timeout": 1900, # 单位:秒 "max_retries": 0, # 避免命令被自动重复提交 }, middleware=middleware, ).ucompshare() try: return client.invoke( "RunCompShareInstanceCommand", { "InstanceId": instance_id, "Command": command, "Type": execution_type, }, ) except exc.RetCodeException: return captured["body"] if __name__ == "__main__": result = run_instance_command( os.environ["COMPSHARE_INSTANCE_ID"], "echo hello", execution_type="sync", # 改为 async 即提交异步任务 ) print(json.dumps(result, ensure_ascii=False, indent=2))

该 SDK 版本的 RetCodeException.json() 不保留 Output,因此示例通过响应中间件保留完整响应。网络错误、HTTP 错误和超时仍会抛出异常,不会自动重新提交命令。

异步提交成功后,保存返回的 TaskId,按 查询实例命令执行结果 中的示例获取结果。


响应示例

同步执行成功

{ "RetCode": 0, "Output": "hello\n" }

同步执行失败

例如执行 echo before-error; exit 1:

{ "RetCode": 226656, "Output": "before-error\n" }

异步提交成功

{ "RetCode": 0, "TaskId": "673000000000000000000001" }
Last updated on