第33章 模板别名

模板别名 ​模板别名是 CubeSandbox 模板稳定且易读的名称。应用配置无需保存 tpl-01abc... 这样的生成 ID，可以改用 python-runtime：pythonfrom cubesandbox import Sandbox with Sandbox.create(template="python-runtime") as sandbox: print(sandbox.commands.run("python3 --version").stdout)模板重新构建或替换后，应用仍可使用固定别名，由运维人员将别名切换到新模板。命名规则与行为 ​模板别名必须满足以下规则：只能包含小写字母、数字和连字符；必须以字母或数字开头；长度为 1 到 64 个字符；不能使用保留的 tpl- 或 snap- 前缀；同一时间只能属于一个 READY 模板；不能分配给快照。python、python-3-12 和 app-v2 都是有效别名；MyApp、my_app、-my-app 和 tpl-custom 无效。每个模板最多拥有一个别名。如果把已有别名分配给另一个模板，别名会转移到目标模板，并从原模板清除。应将其视为一次部署变更：已经运行的沙箱不受影响，后续通过该别名执行的操作会解析到新模板。创建模板时设置别名 ​从 OCI 镜像创建模板时传入 --alias：bashcubemastercli tpl create-from-image \ --image ghcr.io/example/python-runtime:3.12 \ --alias python-runtime \ --writable-layer-size 2G \ --expose-port 49983 \ --probe 49983 \ --probe-path /health模板 ID 仍由服务端生成。模板达到 READY 并成功取得别名后，该别名才可使用。通过 CubeAPI 兼容的 SDK 构建模板时，E2B 风格的 name 字段会作为稳定别名：pythonfrom cubesandbox import Template job = Template.build( image="ghcr.io/example/python-runtime:3.12", name="python-runtime", writable_layer_size="2G", exposed_ports=[49983], probe_port=49983, probe_path="/health", ) print(job.template_id)设置、修改或清除别名 ​为已有的 READY 模板设置或修改别名：bashcubemastercli tpl set-alias tpl-01abc --alias python-runtime第一个参数既可以是生成的模板 ID，也可以是模板当前的别名：bashcubemastercli tpl set-alias python-runtime --alias python-runtime-v2清除别名：bashcubemastercli tpl set-alias tpl-01abc --clear各语言 SDK 提供相同操作：PythonGoNode.jspythonfrom cubesandbox import Template Template.set_alias("tpl-01abc", "python-runtime") Template.set_alias("tpl-01abc", None) # 清除goinfo, err := client.SetTemplateAlias(ctx, "tpl-01abc", "python-runtime") if err != nil { panic(err) } _, err = client.SetTemplateAlias(ctx, info.TemplateID, "") // 清除tsimport { Template } from "@cubesandbox/sdk"; await Template.setAlias("tpl-01abc", "python-runtime"); await Template.setAlias("tpl-01abc", null); // 清除使用和查询别名 ​任何接受模板标识符的位置都可以传入别名，包括创建沙箱：PythonGoNode.jspythonsandbox = Sandbox.create(template="python-runtime")gosandbox, err := client.Create(ctx, cubesandbox.CreateOptions{ TemplateID: "python-runtime", })tsconst sandbox = await Sandbox.create({ template: "python-runtime" });模板列表和详情响应会在 aliases 数组中返回已配置的别名。也可以直接通过 CubeAPI 解析别名：bashcurl http://:3000/templates/aliases/python-runtime响应示例：json{ "templateID": "tpl-01abc", "public": false }安全发布流程 ​建议按以下步骤更新生产模板：构建新模板，暂时不修改生产环境使用的别名。等待新模板达到 READY，并通过生成的模板 ID 完成验证。将生产别名分配给新模板。使用别名创建测试沙箱，确认别名解析符合预期。根据回滚策略保留或删除旧模板。修改别名不会改变或重启已经存在的沙箱。