构建并部署 Hosted Service

Hosted Service 用于把工作区中的后端项目构建成可重复部署的制品，并部署到一个或多个运行环境。

本文是 Hosted Service 使用流程的文档来源。具体调用参数以当前工作区运行时里已安装模块的方法定义为准，不要把市场版本号、模块版本 ID 或内部服务地址写进自动化流程。

核心契约

构建和部署是两个独立阶段：

Project source
  -> BuildJob
  -> immutable Artifact
  -> Hosted Service Environment Deployment

• BuildJob 表示一次构建过程，负责记录状态、日志和失败原因。
• Artifact 是构建成功后生成的不可变制品，用 artifactId 标识。
• Hosted Service 部署只接收 artifactId，不接收 buildJobId，也不会隐式触发构建。
• 同一个 artifactId 可以部署到开发、测试、生产等多个环境，也可以用于回滚。
• 只有源代码或构建参数变化、需要新制品时，才创建新的 BuildJob。

AI 调用前先发现当前方法

AI 或自动化程序应先查询当前运行时的服务和方法定义，再按方法定义组装参数：

1. 查找 workspace-rust-build，确认 BuildJob 和 Artifact 方法及参数。
2. 查找 workspace-hosted-service，确认 Hosted Service、环境、配置绑定和部署方法及参数。
3. 使用运行时返回的 methodDefinition，不要根据本文猜测可选参数。
4. 不要硬编码模块版本 ID、服务内部 URL 或历史接口路径。

本文负责解释流程和不变量；当前运行时的方法定义负责提供精确请求结构。这可以避免文档、Skill、模块版本和 Bundle 版本之间出现重复契约。

第一步：准备项目

构建前确认：

• 项目属于当前工作区，并且已经保存需要构建的源代码。
• Rust 项目能够在平台构建环境中执行测试和构建命令。
• 需要部署的二进制路径明确。
• 密钥、数据库密码和环境差异配置不写入源代码或 Artifact。

第二步：创建 BuildJob

调用 createRustBuildJob，至少传入当前 projectId。如果当前方法定义支持，也可以指定包名、测试命令、构建命令、二进制路径、制品类型和元数据。

示意调用：

{
  "method": "createRustBuildJob",
  "arguments": {
    "projectId": 123
  }
}

调用成功只表示构建任务已创建，不表示已经产生 Artifact，更不表示已经部署。

第三步：等待构建完成

使用 getRustBuildJob 轮询刚创建的 BuildJob。也可以通过 listRustBuildJobs 恢复之前的构建任务。

• 构建未结束时继续轮询，不要发起部署。
• 构建失败时读取任务返回的错误消息和日志，修复项目后创建新的 BuildJob。
• 构建成功后读取返回的 artifactId。
• 如果任务响应只给出 Artifact 关联信息，使用 getRustBuildArtifact 或 listRustBuildArtifacts 查询制品。

不要把 BuildJob 的 id 当成 artifactId。二者属于不同资源，生命周期也不同。

第四步：准备 Hosted Service 和环境

部署前确保目标 Hosted Service 和环境已经存在。根据当前方法定义，可以创建或查询：

• Hosted Service；
• 服务环境；
• 配置 Provider；
• 环境配置绑定。

数据库配置遵守独立边界：数据库服务负责创建工作区数据库 Profile 或 Allocation；Hosted Service 环境只保存对该配置的绑定。不要让构建阶段决定生产、测试或开发环境使用哪个数据库。

环境变量、凭据和 Provider 绑定在部署时解析，不应打进 Artifact。

第五步：部署 Artifact

调用 deployHostedServiceArtifact，传入：

• 当前 projectId；
• 目标 environmentId；
• 构建成功产生的 artifactId。

示意调用：

{
  "method": "deployHostedServiceArtifact",
  "arguments": {
    "projectId": 123,
    "environmentId": 456,
    "artifactId": 789
  }
}

禁止传入：

• buildJobId；
• 任意下载地址或本地文件路径来代替 artifactId；
• 与 Artifact 所属项目不一致的 projectId。

第六步：等待部署并验证

部署请求返回后，使用当前运行时提供的部署查询方法检查状态，例如按项目查询部署记录或查询 Hosted Service 状态。

验证至少包括：

• deployment 最终状态为运行中；
• deployment 记录中的 artifactId 是本次选择的制品；
• 主 endpoint 已生成稳定访问地址；
• 健康检查通过；
• 真实业务请求返回正确结果；
• 失败时 message 和日志能直接说明配置解析、容器启动或健康检查问题。

部署失败不会改变 Artifact。修复环境配置后可以重新部署同一个 artifactId；只有制品内容有问题时才重新构建。

常见错误

把 BuildJob 当成 Artifact

现象：部署参数使用 buildJobId，或者构建尚未成功就开始部署。

处理：等待 BuildJob 成功，取得真正的 artifactId 后再调用部署方法。

每个环境都重新构建

现象：开发、测试和生产环境分别产生内容不确定的新制品。

处理：同一版本只构建一次，把同一个 artifactId 逐级部署到不同环境。

把环境配置打进制品

现象：数据库地址、Token 或生产配置写入源码或构建命令。

处理：使用 Hosted Service 环境配置和 Provider 绑定，在部署阶段解析配置。

只看请求成功，不看最终状态

现象：创建 BuildJob 或 deployment 后立即认为发布完成。

处理：分别轮询 BuildJob 和 deployment，直到进入最终状态，并执行 endpoint 健康和业务验证。

文档与版本治理

Hosted Service 的契约按以下优先级使用：

1. 本页：稳定工作流、资源边界和错误处理原则。
2. 当前运行时方法定义：当前已安装版本的精确参数、返回值和方法描述。
3. BuildJob、Artifact、deployment 记录：一次实际执行的状态来源。

Skill 可以引导 AI 搜索本页或查询运行时方法，但不应复制整套接口定义。平台接口发生不兼容变更时，应在发布引用该能力的新模块版本和 Bundle 版本时同步更新本页。