Spark Pipeline 问题排查
Traduction en coursCe guide est actuellement disponible en chinois simplifié. Une version traduite sera ajoutée ultérieurement.
Pipeline 问题应按“配置来源 → Git → 源码构建 → 镜像构建/推送 → 部署 → 健康检查”逐层定位。不要看到最终 Deploy 失败就直接修改 K8S 模板。
1. 快速定位表
| 现象 | 优先检查 |
|---|---|
| Repository 分支列表为空 | Git URL、Baseline Branch、Git Secret 权限与网络 |
| Configure Pipeline 无法保存 | Deployment Environment、Cluster 引用、Deploy 阶段类型 |
| Start Build 不可用 | Active Release Branch、部署配置、是否已有活动运行 |
| Maven/NPM/Python 依赖下载失败 | Cluster Maven/NPM 配置、Dockerfile 源、构建网络和证书 |
| Dockerfile not found | Deployment Configuration 的 Dockerfile Path 和 Build Context |
| 镜像 push/pull 失败 | Registry Address、Harbor Secret、repository 权限和集群连通性 |
| Test Gate 一直等待 | 这是人工阶段；由负责人 Approve 或 Reject |
| Deploy 未自动开始 | Deploy 是人工确认阶段；点击 Deploy |
| K8S Pod 不 Ready | Probe、端口、配置、资源、Secret、Pod Events 和容器日志 |
| Docker 发布失败 | SSH、Docker 权限、Host Group、Run Template、Host Port、磁盘 |
2. Repository 层
确认：
- URL 是可克隆的完整 Git URL，没有把 Token 写在 URL 中。
- Baseline Branch 在远端存在。
- Git Secret 类型为 Git，Scope 覆盖当前 App。
- Access Token 未过期，并有读取仓库/分支权限。
- 使用 Create Branch 时还具备创建分支权限。
在本地成功克隆并不能证明 Spark 的构建节点可访问。网络、DNS、CA 和凭据必须从目标 K8S/Docker 构建环境验证。
3. 构建层
Java
- Build Command 是否在仓库根目录可无交互执行。
- Maven
settings.xml是否引用可达的私服。 .m2Host Path 是否存在且构建节点可挂载。- Dockerfile
COPY的 JAR 是否由当前命令生成。
Python
- Dockerfile 中的 OS package、Conda/Pip 源是否可达。
requirements/environment.yml是否固定关键版本。- 构建是否依赖开发机上的未提交文件。
- 架构和原生依赖是否适配构建节点。
Node.js
- Managed NPM Build 的 Frontend Build Path 是否包含
package.json。 - Output Path 是否相对于 Frontend Build Path。
- NPM/Yarn/PNPM 是否与 lockfile 匹配。
.npmrc的 scope、Registry 和 Token 是否正确。- 环境文件存在，且不是错误环境的配置。
images/spark-pipeline-troubleshooting-build-01.webp4. Registry 层
K8S 构建要求 Cluster Harbor Config：
- Registry Address 只填
host[:port]。 - Harbor Secret 用户可以 push 目标 repository。
- K8S 节点可以 pull 生成的镜像。
- 私有 CA 或 HTTP Registry 已按集群安全策略正确配置。
- Image Repository 没有重复拼接 Registry 地址。
Docker LOCAL_BUILD 不要求 Registry；REGISTRY_PULL 必须配置 Docker Registry。先确认 Build Mode，再决定是否排查 Registry。
5. K8S 部署层
按顺序检查：
- Environment 绑定的 Cluster 没有被删除，namespace 仍被允许。
- Deployment Template 与 App Language 兼容。
- Release Details 中生成的 Manifest 使用预期镜像、端口和资源。
- Pod Events 是否有 ImagePullBackOff、调度失败、挂载失败或 Probe 失败。
- 容器日志是否显示配置、端口或依赖服务错误。
- Domain、Service Port 与 Ingress/证书是否匹配。
Remote Debug 只用于受控环境。不要为排查 PROD 启动失败而长期开放调试端口。
6. Docker 部署层
- 重新 Test SSH，确认私钥、用户、跳板机和网络。
- SSH 用户能执行
docker info、拉取/构建镜像和管理容器。 - Host Group 仍包含 Active Host。
- Run Template 的 Language 与 Build Mode 匹配。
- Host Port 未占用；磁盘空间足以保存新旧镜像。
- 多主机发布时检查具体失败主机和 Failure Policy。
json-file日志轮换已配置，避免长期运行耗尽磁盘。
7. 运行控制
- Waiting Approval：点击 Approve 或 Reject，不是系统卡死。
- Waiting Deploy：点击 Deploy；Pipeline 有意避免自动修改运行环境。
- Failed Build：查看日志，修复配置后使用 Retry 或启动新运行。
- Failed Docker Deploy：可 Retry；K8S 失败先核对 Manifest 和集群状态。
- Active Run 无法结束：先确认构建 Job/部署任务真实状态，再 Cancel；仅在旧任务确实失联时使用强制重新开始。
8. 收集问题证据
提交问题时提供：
- App Code、Environment Code、Cluster Type
- Release Order 编号、Run ID 和失败阶段
- 失败阶段前后各一段日志，敏感值打码
- Release Details 中的制品地址和部署状态
- K8S Pod Events/容器日志，或 Docker Host/容器状态
- 最近修改过的 Repository、Deployment、Cluster 配置项
不要提供 Git Token、Harbor 密码、SSH 私钥、kubeconfig、.npmrc Token 或完整生产环境变量。