接入第一个项目

本教程将一个已有 CloudBase 管理适配器的项目连接到掌序。完成后，你将得到已激活的连接，再分别核对指标和业务能力。

适用条件

先完成开始之前。示例 ID 和文件路径都需要替换；不要直接用示例值操作云环境。

1. 声明接入目标

在项目根目录创建以下文件。两个路径都必须指向项目目录内已经存在的真实文件。

xuji-connect.json

{
  "schemaVersion": "xuji-connect/1",
  "targets": [
    {
      "name": "dev",
      "planPath": "cloudbase/connect/dev-plan.json",
      "artifactPath": "cloudbase/connect/xg_ops-dev.zip"
    }
  ]
}

这里的 xg_ops 是已有蹊光适配器示例，并非适用于所有项目的固定函数名。计划内容见接入配置参考。

2. 先查看计划

项目根目录 · PowerShell

xuji connect --target=dev --platform=<掌序物理开发环境>

预检读取计划和 ZIP，核对范围与摘要，不执行项目构建脚本，也不发起云端部署。存在多个目标时，必须明确指定 --target。

检查项目 ID、物理环境、函数名和允许动作是否与本次接入一致。如果提示缺少产物，先完成受控构包，不能通过修改计划绕过检查。

3. 发起配对并扫码批准

确认预检结果后

xuji connect --target=dev --platform=<掌序物理开发环境> --apply

在掌序运营台的接入页面扫描终端二维码，核对目标项目、环境、函数产物及权限范围，然后批准。首次本机绑定还需要核对完整掌序账号标识。

二维码只是短期会话引用。不要把长期密钥填进二维码或项目配置。

4. 等待连接验证

批准后，工具核对冻结计划和身份、兑换一次性连接信息、上传指定 ZIP、回读验证文件和配置，再由平台发起签名挑战并激活连接。

接入期间避免另一个发布任务同时修改同一函数。若产物或权限范围发生变化，应重新生成并核对计划。

5. 确认结果

连接应显示 ACTIVE。随后打开运营台核对目标环境、能力列表、指标与业务查询。连接激活不会自动批准业务写操作，也不会自动启动维护任务。

继续阅读核对接入结果。

发生中断时

保留本机恢复记录并重新执行原命令，先查询原会话。如果云端已经激活但响应丢失，不应重复部署；若结果未知，应先核实原操作状态。

不要删除恢复记录来强制重试。具体情况见问题排查。