【用途】 本技能用于把一个已经能够构建的 Internet Computer 项目,从编码智能体(coding agent)中部署到云引擎(cloud engine)。云引擎是用户自有的 Internet Computer 容量切片,通过网页控制台管理,默认控制台为 https://opencloud.org;每个引擎运行在单一子网上。本技能只处理云引擎特有的两个环节:把 CLI 与控制台身份关联,以及面向指定子网的部署。其余 CLI 相关内容(icp.yaml、recipes、environments、bindings、identities)需加载 icp-cli 技能。
【所需信息】 需要两个值。优先在 icp.yaml 或此前对话中查找:
- 控制台源(Console origin)——用户登录其云引擎控制台所用的 URL,默认为 https://opencloud.org。它作为第 1 步中的 --auth origin,使关联的 CLI 身份派生出与引擎管理员相同的 principal。应使用默认值,但要告知用户并允许其覆盖。只有在用户明确给出其他源时才使用其他 URL,不要自行替换。
- 子网 id(Subnet id)——引擎部署到的子网,icp deploy --subnet 必需。没有默认值,绝不能猜测。用户可在控制台的引擎 Settings 页面(引擎标识符下)或从控制台命令面板中获取。若缺失,必须询问,未获得前不要继续。两者都应记录,以免在会话中重复询问。
【前提条件】 icp 需在 $PATH 中;验证用 icp --version(本技能命令对照 0.3.0 和 1.0.2 验证)。若版本不同,运行前先用 icp <cmd> --help 确认参数。项目必须已能构建,否则先设置构建再回来。macOS 上 icp 数据存储在 ~/Library/Application Support/org.dfinity.icp-cli/,若因 TCC 无法写入,可用 HOME=/tmp/icp-home icp … 重定向数据路径,并在后续所有 icp 命令中保持同一 HOME。运行不确定的 icp 命令前,先运行 icp <subcommand> --help 确认命令与参数存在,不要推断参数。
【使用方式】 第 1 步——将 CLI 关联到引擎身份(每台机器一次)。CLI 必须以管理该引擎的同一身份签名。先确定 CLI 相对浏览器的运行位置:
- CLI 与浏览器在同一台机器且有网络:使用常规关联流程 icp identity link web <name> --auth <console-origin>,先用 icp identity list 检查现有身份。
- CLI 在远程或隔离沙箱(浏览器在不同机器):常规流程无法工作,需使用 delegation handoff:在 CLI 主机运行 icp identity delegation request <name> 生成会话公钥 PEM;用户在本地机器运行 icp identity delegation sign --identity <local-name> --key-pem session-key.pem --duration 8h > delegation.json;再在 CLI 主机运行 icp identity delegation use <name> --from-json delegation.json,然后 icp identity default <name> 并验证 icp identity principal。delegation.json 应视为限时凭证,保持较短的时长。
- CLI 完全无网络:该环境无法运行任何 icp 网络命令,不要让用户打开沙箱的 127.0.0.1 URL。准备项目并给用户一段脚本在其真实终端运行,脚本包含版本检查、身份关联、设为默认、以及 icp deploy -e ic --subnet <subnet-id>,让用户运行后回传输出。 常规关联流程中,--auth 必须为精确的控制台源(scheme + host);绝不要省略 --auth,因为它有内置默认值 https://id.ai,会静默派生出错误的 principal。命令会先停在“Press Enter to log in”提示,非交互环境需管道传入真实换行(不要用 /dev/null)。之后会打开浏览器标签,用户完成 Internet Identity 登录,无法代其完成。这是每台机器一次性的步骤。完成后设为活动身份并验证。
第 2 步——在控制台中为应用命名并设置图标(推荐)。默认情况下,CLI 部署的 canister 在控制台 Applications 页面只显示为仅带 principal id 的裸行。通过一组 canister 环境变量可以使其归组为一个命名应用。变量包括:__META_PROJECT(应用名,同一应用的所有 canister 设相同值)、__META_NAME(每 canister 显示标签)、__META_MAIN_CANISTER(在恰好一个 canister 上设为字面字符串 "true")、__META_BASE_URL(主 canister 上的绝对 https:// URL)、__META_ICON_PATH(主 canister 上相对 __META_BASE_URL 解析的图标路径)。图标和 Open 链接只从主 canister 读取。这些变量设置在每个 canister 的 settings.environment_variables 下,可与 recipe 同时使用。前端 canister id 只有在首次部署后才可知,通常流程是先部署一次、读取 id、设置 __META_BASE_URL 后重新部署。
此外,若应用需要用户登录,应固定 Internet Identity 派生源(derivation origin),使用前端 canister 的地址 https://<frontend-canister-id>.icp.net,避免同一人在 canister 地址与自定义域名下被识别为两个不同用户。
【限制】 本技能仅覆盖云引擎特有步骤,其余 CLI 细节需查阅 icp-cli 技能。subnet id 无默认值,不可猜测。--auth 必须精确匹配控制台源。delegation.json 为限时凭证,过期需重新交接。引擎环境变量值有长度上限(观察到 ≤128 字符),__META_ICON_PATH 必须是前端实际提供的资源路径而非内联图片。__META_BASE_URL 必须是绝对 https:// URL,否则图标不渲染且 Open 按钮回退到主 canister 的网关 URL。沙箱的 127.0.0.1 URL 对用户机器不可达,不要展示给用户。