回滚与恢复

症状

部署失败、被取消，或者观察流（timeline）中断，你需要判断接下来应该重试、修复配置，还是回滚到历史版本。

可能原因

现象	最可能的原因
Source 无法读取	仓库/镜像地址失效、凭据过期、ref 不存在
Runtime/Profile 不匹配	Source 类型与 Runtime Profile 配置冲突
SSH 或服务器执行失败	服务器连通性、凭据或资源不足
应用启动但健康检查失败	健康检查路径/端口配置与应用实际行为不一致
默认访问地址失败	代理就绪或网络 Profile 配置问题
自定义域名失败	DNS/TLS 配置问题（先确认默认访问地址正常）

如何检查状态、日志、事件或诊断

在采取任何恢复动作之前，先只读检查恢复就绪状态：

appaloft deployments recovery-readiness <deploymentId>

这个查询是只读的，会返回：

recoverable、retryable、redeployable、rollbackReady 等机器可读字段；
retry、redeploy、rollback 各自的阻塞原因；
可用的回滚候选（历史成功部署），以及候选是否缺少必要的产物或快照；
建议的下一步，例如先看日志、事件流或诊断摘要。

安全恢复步骤

根据 readiness 的建议选择动作：

# Retry：基于失败部署的快照，创建一个新的部署尝试
appaloft deployments retry <deploymentId>

# Redeploy：使用当前 Resource Profile 重新部署（会读取最新配置，不复用旧快照）
appaloft deployments redeploy <resourceId>

# Force redeploy：像 redeploy 一样，但强制刷新运行时产物（跳过构建缓存 / 强制拉取镜像）
appaloft deployments force-redeploy <resourceId>

# Rollback：基于历史成功部署的快照和产物，创建新的回滚尝试
appaloft deployments rollback <deploymentId> --candidate <candidateDeploymentId>

# Cancel：停止一个尚未完成的部署尝试（不会删除历史记录）
appaloft deployments cancel <deploymentId> --confirm <deploymentId>

Retry 不是重放旧事件，也不会在旧尝试里继续执行失败阶段——它基于失败部署不可变的输入快照创建一次全新尝试。
Redeploy 会读取当前 Resource Profile；如果当前 Profile 缺失或有明显漂移，recovery-readiness 会把 redeploy 标记为阻塞。
Rollback 不会从当前 Resource Profile 重新规划，也不会恢复数据库、卷或外部依赖的状态——它只回滚应用运行时本身。
Cancel 的 --confirm 必须和部署 id 完全一致；已经处于终态（成功/失败/取消/回滚）的尝试会被拒绝。

何时重试

输入校验失败应该先修正输入再重试；执行阶段的临时失败（例如网络抖动）通常可以直接重试。

何时回滚

Verify 阶段失败、且修复配置需要时间时，优先回滚到已知良好的历史版本，再离线排查根因，而不是让用户长时间面对一个不健康的部署。

长时间无活动的部署

部署长时间停在 created、planning、planned、running 或 cancel-requested 状态时：

# 只读查询：找出长时间无活动的尝试
appaloft deployments stale --stale-after-seconds 900

# 确认确实失去执行所有权后，用返回的 stateVersion 显式协调
appaloft deployments reconcile-stale <deploymentId> \
  --state-version <stateVersion> \
  --stale-after-seconds 900 \
  --confirm <deploymentId>

协调成功后，旧尝试会变为 interrupted；历史和恢复证据仍然保留，之后可以再走一次 recovery-readiness 选择 retry 或 redeploy。

来源重新关联

如果需要把资源指向一个新的仓库、目录或镜像（而不只是重试同一个来源），使用来源重新关联，详见配置部署来源。这是一个显式动作，不应该被当成普通重试。

归档和清理历史

# 把一个终态部署从默认历史列表中隐藏（不删除日志、事件或审计记录）
appaloft deployments archive <deploymentId> --confirm <deploymentId>

# 默认只是预览：清理早于某个时间点、已归档、且没有被引用的终态部署
appaloft deployments prune --before <iso>

什么时候需要复制诊断信息求助

如果 recovery-readiness 显示所有动作都被阻塞，或者同一个失败在修复配置后仍然反复出现，运行生成安全诊断信息中的命令，生成一份不含密钥的诊断摘要再寻求支持。