# 发布验证与故障排查

验证后端项目版本、Deployment、Endpoint、鉴权和业务请求的完整链路。

## 发布完成标准

每次部署至少验证：

1. Release Operation 最终成功，`sourceCommitId` 与预期主线 HEAD 一致。
2. 返回的 `projectVersion` 与根 `Cargo.toml` 的 `package.version` 一致。
3. 底层 Artifact 属于当前工作区和 Project，类型为 `hosted_service_release`。
4. deployment 引用的是预期 `projectVersion`。
5. 环境配置与 Provider 绑定能够解析。
6. 若版本包含数据库迁移，每个 Migration Operation 及其 Attempt 都成功，执行顺序与发布清单一致。
7. deployment 进入最终运行状态。
8. 稳定 Endpoint 已生成且固定 `/healthz` 通过。
9. 携带正确身份的真实业务请求成功。
10. 无 token、错误 token 和越权用户请求被拒绝。
11. 日志能够通过请求标识关联到本次调用，且不包含密钥。

## 查询业务运行和迁移日志

使用 [环境日志查询与错误排查](/development/backend-development/logs-and-errors/) 中的 `logs-search` 和
`logs-trace`，按当前工作区、项目、环境及故障时间查询。Release Operation 的构建日志、Deployment 状态和
环境运行日志需要分别核对；日志查询失败不能显示成空列表，HTTP 200 也不能替代 CModel `errorCode` 判断。

## release 没有创建 Operation

`project release` 成功响应必须返回 `releaseOperationId`。若返回业务错误且没有 ID，失败发生在同步预检：依次
核对 Project 访问权限、主线 HEAD、根 `Cargo.toml`、`hosted-service.toml`、版本唯一性，以及 Artifact
Service 的版本解析结果。不要把旧 `hosted_service_bundle` 当成已经发布的项目版本，也不要改用已移除的
`deploy-artifact` 绕过预检。

## deploy-version 提示版本不存在

先用 `release-status` 确认对应 Release Operation 已进入 `SUCCEEDED`，再从 Artifact 查询中核对是否存在完全
匹配 `projectId + hosted_service_release + projectVersion` 的记录。一个成功的旧 BuildJob 或
`hosted_service_bundle` 不满足这项条件。

## 部署长时间未完成

查询 deployment 的最新状态和公开错误消息，再检查配置解析、迁移、容器启动、端口和健康检查。不要因为
控制面已经接受请求就认定服务已经上线。

如果 Endpoint 的 `/healthz` 返回 404，说明业务进程没有在对应 listener 实现固定健康协议；应修改应用源码，
提升 `Cargo package.version`，合并主线并发布新版本。不要在 Environment 或 Manifest 中增加健康路径覆盖字段。

如果 deployment 包含数据库迁移，先检查 `databaseMigrations` 中按 Schema → Data 排列的 Operation，再检查
最新 Attempt 的阶段、返回码、候选行数和影响行数。迁移失败时不要绕过失败 Operation 手工切换运行程序；
修复源码并发布新的完整项目版本后重新部署。

## Endpoint 返回未授权

依次检查：

1. 目标环境的鉴权模式。
2. consumer 是否属于该环境。
3. token 是否有效、未撤销并发给了正确调用方。
4. 请求是否使用服务要求的认证头。
5. 业务应用自身是否还有第二层用户鉴权。

## 回滚

环境配置错误时，修复配置后可以重新部署同一个项目版本。程序内容错误时，选择此前已经验证的
`projectVersion` 重新部署，或修复源码、提升版本并发布新版本。

程序回滚不等于数据库回滚。平台不会自动反向执行已经成功的数据定义或数据变更。数据库变更必须采用
expand/contract：先发布能与新旧程序共同工作的扩展，再切换程序，确认旧版本不再使用后才在后续版本
收缩。迁移失败或程序需要回退时，优先修复并向前迁移；不要依赖破坏性逆向 SQL 恢复旧结构。

回滚也必须等待 deployment 进入最终状态并执行健康、鉴权和业务验证，不能只看部署请求返回成功。