配置部署来源

目标

告诉 Appaloft “要部署什么”：本地目录、Git 仓库、容器镜像、Compose 清单，还是已经构建好的静态目录。

适用场景

• 第一次为一个资源配置部署来源。
• 仓库迁移、目录重组或镜像地址变化后，需要把资源重新指向新的来源。
• 排查”Appaloft 读取的代码不是我期望的版本”。

前置条件

• 已经创建 Project 和 Resource（见项目、资源）。
• 如果来源是私有 Git 仓库，已经完成 GitHub 与集成中的仓库授权。

输入与默认值

来源不承担 Project、Server、Environment 或域名的职责——这些是独立的输入，见产品心智模型。

零配置检测的诚实覆盖范围

“零配置”是指 Appaloft 能检查已选定的应用目录，自动推导构建/启动方式，而不需要你手工填写 Runtime Profile。以下按诚实的成熟度标注（不是营销口径）：

Appaloft 在无法安全生成完整计划时会 fail closed（停止并说明原因），不会猜测——这是设计选择，不是缺陷。

GitHub 自动部署检查闸门

Resource 的 GitHub 自动部署策略可以声明一组精确、区分大小写的 requiredChecks。Appaloft 收到 push 后会把对应提交标记为“等待检查”，只有每个名称都收到该提交 SHA 的已完成 check_run，且结论为 success、neutral 或 skipped，才创建普通部署。

autoDeploy:
  enabled: true
  trigger: git-push
  refs:
    - main
  events:
    - push
  requiredChecks:
    - build
    - lint

也可以通过 CLI 或共享 API 配置同一策略：

appaloft resource auto-deploy res_web \
  --mode enable \
  --ref main \
  --required-check build \
  --required-check lint

{
  "resourceId": "res_web",
  "mode": "enable",
  "policy": {
    "triggerKind": "git-push",
    "refs": ["main"],
    "eventKinds": ["push"],
    "requiredChecks": ["build", "lint"]
  }
}

这不是 branch protection 的镜像：名称必须显式写入 Appaloft 策略。GitHub App 需要 Checks 读取权限并订阅 check_run webhook。失败、取消、超时等结论会显示为“检查未通过”；同名检查 后续成功重跑可以解除阻塞。相同 Resource/ref 的新 push 会取代旧的等待项，旧 SHA 的迟到事件 不会触发部署。

用 appaloft source-event list --resource res_web 和 appaloft source-event show <sourceEventId> --resource res_web 检查 waiting-checks、 checks-blocked、superseded 或 dispatched 状态。要停用闸门，替换策略并移除 requiredChecks，然后推送新提交；Appaloft 不会用计时器自动放行旧提交。

CLI 操作步骤

# 从当前目录发起零配置部署（无路径时同样部署当前目录，不会静默复用会话）
appaloft up
appaloft up .

# 本地目录，显式指定静态发布方式（相对路径保持相对，public 不会被改写成 /public）
appaloft up ./apps/web --method static --publish-dir build
appaloft up . --as static-site --publish-dir public

# 已经构建好的静态输出目录，跳过构建
appaloft up ./dist --as static-site

# Git 仓库作为来源
appaloft up https://github.com/example/web \
  --method static \
  --publish-dir dist \
  --resource-name web

# 为已存在的资源配置/更新 Git source profile
appaloft resource configure-source res_web \
  --kind git-repository \
  --locator https://github.com/example/web \
  --git-ref main \
  --base-directory apps/web

# 部署前先只看计划，不创建部署尝试
appaloft deployments plan --project prj_prod --environment env_prod --resource res_web --server srv_prod

appaloft deploy 在 1.x 中仍是同一工作流的受支持兼容写法；新的命令和自动化应优先使用 appaloft up。两种写法使用完全相同的来源解析和部署生命周期。

HTTP/API 操作步骤

POST /api/deployments
Content-Type: application/json

{
  "projectId": "prj_example",
  "environmentId": "env_production",
  "serverId": "srv_primary",
  "resourceId": "res_web",
  "source": {
    "kind": "git-repository",
    "locator": "https://github.com/example/web",
    "gitRef": "main",
    "baseDirectory": "."
  }
}

预期输出与状态

appaloft deployments plan 会返回：选中的应用根目录、检测到的 framework/runtime、使用的 planner、推导出的 install/build/start 命令、监听端口、健康检查、以及告警或阻塞原因。计划还会附带 planVersion 和一个稳定的 sha256: 指纹，方便你确认两次计划是否等价。

验证

• 运行 appaloft resource show res_web --json，确认 source 摘要（仓库、ref、目录或镜像 tag）符合预期。
• 触发一次部署，确认 deployments plan 阶段没有被阻塞。

回滚 / 恢复

• 来源不再可访问或需要切换到新仓库/镜像时，这是显式的 来源重新关联（source relink）动作，不是普通重试。执行前确认目标资源、当前来源、新来源和预期环境；执行后通过下一次部署或资源详情确认 Appaloft 读取的是新来源。
• 用 appaloft source-links list / show 查看当前仓库到 Project/Environment/Resource 的安全映射，用 relink 显式改变映射，用 delete 只移除映射（不会删除资源或部署历史）。

故障排查链接

• 排障总览
• 回滚与恢复

相关参考页面

• 部署生命周期
• 运行时 / 健康 / 网络 Profile
• GitHub 与集成