在实例容器内执行命令
接口说明
在指定 CPod GPU 实例(cpod-...)的业务容器内执行 Bash 命令。命令在容器内执行,不在宿主机执行。
POST
https://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 并查询原任务,避免重复提交命令。
请求参数
| 名称 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| Action | String | 是 | 接口名称 | RunCompShareInstanceCommand |
| InstanceId | String | 是 | CPod 实例 ID,以 cpod- 开头 | cpod-xxxx |
| Command | String | 是 | 要执行的 Bash 命令或多行脚本,最多 256 KiB | echo hello |
| Type | String | 否 | 执行方式,可选 sync(同步,默认)或 async(异步),区分大小写 | async |
地域、可用区和连接凭据由服务端按 InstanceId 查询,无需传入 Region、Zone 或实例登录密码。
响应参数
同步执行
| 名称 | 类型 | 描述 | 示例值 |
|---|---|---|---|
| RetCode | Integer | 0 表示执行成功,226656 表示执行相关失败;不是 Bash 进程退出码 | 0 |
| Output | String | 标准输出与标准错误的合并文本。失败时可能有部分输出,无输出时为空字符串 | hello\n |
异步提交成功
| 名称 | 类型 | 描述 | 示例值 |
|---|---|---|---|
| RetCode | Integer | 0 仅表示任务提交成功,不表示命令执行成功 | 0 |
| TaskId | String | 异步任务 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