跳到主要内容

AI项目部署失败自动排查：从构建日志到访问验证

部署失败后，先别连续点“重新部署”。如果代码、配置和资源都没有变化，重试只会再跑一遍同样的错误。先看页面上停在哪一步，再去找对应的日志和事件。

可以直接这样描述任务：

帮我检查当前应用为什么部署失败。先判断失败层级并给出证据，不要直接修改业务代码。

别急着重试，先看现象​

你不需要先理解所有 Kubernetes 状态。先从屏幕上看到的现象开始：

你看到的现象最可能先检查的位置
一直停在构建中，最后提示失败构建日志中的第一个错误、依赖和运行时版本
构建成功，但组件没有实例镜像拉取、节点调度、资源和存储事件
组件反复重启运行日志、启动命令、环境变量和健康检查
前端可以打开，接口全部失败前端 API 地址、后端端口和组件依赖
平台显示运行中，外部却打不开网关、域名、证书、访问端口和页面路径
一段时间后才报错或变慢CPU、内存、磁盘、连接数和外部服务

找到最接近的一行后，再让 Agent 读取对应证据。不要只把“部署失败”四个字交给 Agent，然后允许它无限尝试。

再顺着部署链路往下查​

部署链路通常可以拆成六层。上一层没有通过时，不要急着排查下一层。

层级常见现象优先查看
项目识别缺少组件、错误识别语言或入口仓库结构、构建文件、启动命令
源码构建依赖安装失败、编译报错、产物缺失构建日志、运行时版本、构建命令
镜像与调度镜像拉取失败、实例无法创建平台事件、镜像地址、节点与资源
进程启动容器反复重启、健康检查失败运行日志、启动命令、监听地址
组件依赖API 无法连接数据库或缓存依赖关系、连接变量、服务状态
对外访问组件正常但页面/API 不可访问端口、网关、域名、证书、路径

先定位层级可以避免几个常见误区：构建失败时反复重启实例、端口错误时修改业务代码、数据库未启动时调整网关，或者页面路径错误时盲目扩容。

RainSkills 如何逐层排查​

第一层：项目是否被正确识别？​

让 Agent 先说明它准备部署什么：

列出当前项目中的所有可运行组件、构建命令、启动命令、监听端口、依赖服务和持久化目录。

重点检查：

  • monorepo 中是否遗漏某个子目录。
  • 前端与后端是否被错误合并为一个组件。
  • 实际启动文件是否与 package.json、构建脚本或文档一致。
  • 项目是否需要先生成静态文件或编译产物。
  • Dockerfile 的工作目录、复制路径和启动命令是否正确。

如果项目识别本身错误，后续日志只会反复暴露同一个根因。

第二层：源码是否构建成功？​

构建失败通常包含最直接的错误证据。要求 Agent 读取失败附近的日志，而不是只看最后一行：

读取 backend 最近一次构建日志，找到第一个导致构建中止的错误，并区分依赖、编译、网络还是版本问题。

常见原因：

  • 依赖锁文件与包管理器不一致。
  • Node.js、Python、Go 或 Java 版本不匹配。
  • 私有依赖缺少认证或网络不可达。
  • 前端构建所需变量没有在构建阶段提供。
  • 文件名大小写在本地与 Linux 环境中表现不同。
  • 构建产物目录与启动配置不一致。

修复业务代码或构建脚本后，应在本地重新运行相关测试和构建，再触发新的平台构建。

第三层：镜像能否拉取，实例能否调度？​

如果构建已完成但实例没有创建，查看平台事件和 Pod 诊断：

检查当前组件的 Pod 状态和平台事件，判断是否存在镜像拉取、资源不足、节点选择或存储挂载问题。

需要特别关注：

  • 镜像仓库地址或凭据错误。
  • CPU、内存、GPU 或磁盘资源不足。
  • 节点选择条件没有可用节点。
  • 存储无法挂载或访问模式不匹配。
  • 完全离线环境缺少所需镜像。

资源和节点问题通常不能通过修改应用代码解决。Agent 应停止无效重试，并明确需要平台管理员处理的事项。

第四层：进程为什么没有稳定启动？​

实例创建后反复重启，优先读取运行日志和启动配置：

查看 api 组件最近的运行日志、启动命令和健康检查，判断进程退出原因。

典型问题包括：

  • 应用只监听 127.0.0.1，无法被容器网络访问。
  • 启动命令引用了不存在的文件或目录。
  • 必要环境变量缺失，应用启动时直接退出。
  • 健康检查路径、端口或启动等待时间不正确。
  • 内存不足导致进程被终止。
  • 数据库迁移失败，应用拒绝启动。

第五层：组件依赖是否连通？​

当前端能打开但 API 报错，或 API 启动后持续连接失败，检查依赖：

检查 api 到 MySQL 和 Redis 的依赖关系、内部访问地址、连接变量以及依赖组件状态。

不要把内部组件地址硬编码为 localhost。在多组件应用中，localhost 指向当前组件自身，不是数据库或另一个服务。应使用 Rainbond 提供的组件依赖和连接信息。

第六层：页面和 API 是否真正可访问？​

组件显示“运行中”仍不代表交付完成。继续验证：

检查外部访问端口、网关规则、域名、证书、页面路径和 API 路径，确认最终访问地址。

常见访问问题：

  • 组件监听端口与对外开放端口不一致。
  • 前端仍然请求本地开发地址或错误域名。
  • 单页应用刷新后因网关回退规则缺失而返回 404。
  • API 路径前缀在前端、后端和网关中不一致。
  • HTTPS 页面调用 HTTP API 被浏览器阻止。
  • 域名解析或证书尚未生效。

哪些问题可以自动处理？​

RainSkills 可以在明确证据和安全边界内继续处理低风险配置问题，例如端口、依赖关系、非敏感环境变量、访问规则或健康检查配置。

以下情况不应静默自动处理：

  • 修改业务代码或构建脚本。
  • 删除应用、组件、存储或数据库。
  • 替换生产环境凭据。
  • 调整生产容量和高可用策略。
  • 执行数据库结构变更或数据修复。
  • 问题来自第三方服务、网络策略或平台容量。

遇到这些情况时，Agent 应给出证据、影响范围和建议，让用户明确确认或交给对应负责人。

一个完整的排查提示词​

帮我排查当前应用部署失败的问题。

1. 先确认当前项目绑定的团队、应用和组件。
2. 判断失败发生在项目识别、源码构建、镜像与调度、进程启动、组件依赖还是对外访问。
3. 读取对应的事件、构建日志、运行日志和配置，引用具体证据。
4. 对低风险平台配置问题给出修复方案；涉及业务代码、数据、删除操作或平台容量时先停止并说明。
5. 修复后重新验证组件、Pod、事件、页面和 API。
6. 最后输出访问地址和交付结论。

排查完成后的验证清单​

  • 最近一次构建已成功完成。
  • 所有必要组件都有可用实例。
  • Pod 没有持续重启、拉取失败或调度失败。
  • 运行日志中没有阻塞启动的错误。
  • 数据库、缓存和内部服务依赖连通。
  • 数据与上传文件使用了正确的持久化存储。
  • 页面入口返回预期内容。
  • 核心 API 返回预期状态和数据。
  • 域名、证书和访问路径正确。
  • 最终访问地址已经明确。
  • 仍需人工验证的登录或业务流程已经列出。
  • 生产更新存在备份和回滚方案。

一次有效的排查应该留下什么​

一次有效的排查应该让你清楚知道：

  • 哪里失败：构建、调度、启动、依赖还是访问。
  • 为什么失败：引用具体日志、事件或配置，而不是猜测。
  • 谁来处理：Agent 可以修复、需要开发者改代码，还是需要平台管理员处理资源。
  • 改了什么：列出实际修改的配置或代码，避免不可追踪的试错。
  • 是否恢复：重新验证组件、页面和 API，而不是只看到错误消失。
  • 如何避免复发：补充测试、健康检查、资源配置或交付文档。

如果结论仍然只是“建议重新部署”或“可能是网络问题”，说明证据还不够，应该继续缩小范围。

常见问题​

为什么重新部署很多次仍然失败？

如果配置、代码或资源条件没有变化，重新部署只会重复同一错误。先找到第一个明确的失败证据，再决定修改什么。

构建日志和运行日志有什么区别？

构建日志记录依赖安装、编译和镜像生成过程；运行日志来自已经启动的应用进程。构建未完成时不会产生有效的应用运行日志。

Pod 正常为什么页面打不开？

Pod 正常只说明进程可能在运行。还需要验证监听端口、网关、域名、证书、前端 API 地址和具体页面路径。

AI 能否自动修复生产环境问题？

AI 可以辅助定位和处理低风险配置，但生产环境的数据、权限、容量和删除操作需要明确审批。自动化不能替代变更评估和回滚准备。

相关内容​