CNB 文档

简体中文

English

简体中文

English

外观

FAQ 常见问题

复制页面

2053 字约 7 分钟

问题反馈前，建议先查看对应文档，在下面常见问题和 feedback 中查看问题是否已经存在。

若未能找到答案，请于 feedback 中提交 issue。

流水线相关

流水线为什么没触发？

要定位流水线没触发问题，先要了解流水线从触发到执行的流程。

以 push 事件为例：

其中 skip 检测 包括 ifNewBranch、ifModify，参考语法。

那么可以按照这个流程一层层查下去：

  1. 代码是否 push 到远端？
  2. 对应分支是否有 .cnb.yml？
    1. include 的文件是否有权限
    2. 配置内容无格式、语法问题
  3. .cnb.yml 是否声明了当前分支的 push 事件流水线？
  4. 是否命中了 skip 检测？

CNB 中默认分支通常为 main，一些迁移自其他平台的仓库可能默认分支为 master，请注意区分。

在本地明明好的，为什么在 CI 上跑失败了？

要定位这个问题，首先要明确本地环境和 CI 环境的区别：

本地CI 环境
网络本地网络（比如一些办公内网）CI 机器所在网络
文件本地整个目录下所有文件GIT仓库对应分支代码
环境原生指定的 Docker 容器环境
Shell本地指定sh

了解到差异，我们可以依次排查：

  1. 是否有文件未提交？
  2. 构建依赖的文件是否命中 .gitignore？
  3. 是否依赖本地才有的资源（如本地接口、凭证等）？
  4. CI 声明的 cpus 是否满足要求？
  5. 本地运行相同的镜像，得到与 CI 相同的构建环境，进行调试。

云原生构建 的默认镜像为 cnbcool/default-build-env。

那么，我们可以执行下面命令，进入默认 CI 环境进行调试

docker run --rm -it -v $(pwd):$(pwd) -w $(pwd) cnbcool/default-build-env sh

如果声明了其他镜像作为流水线构建环境，请将上述命令中 cnbcool/default-build-env 替换成对应镜像地址。

如何登录到流水线容器调试？

参考 登录调试

流水线执行脚本和登陆调试执行脚本结果不一样?

流水线里的默认使用 sh，登陆调试的是 bash。

如果确认指定的流水线容器是支持bash的（默认的流水线容器是支持的，但如果是自定义容器，可能不支持），可以把执行脚本改成 bash xxx.sh 或者 bash -c '{原来的语句}'。

流水线超时无输出？

一个 job 如果超过 10 分钟没有 log 输出，那么就会被终止掉。可以考虑增加 log，例如针对 npm install 的情况，可以加上 verbose 参数。

注意这个跟 job 的 timeout 声明的超时不一样，不能通过配置修改。

没改代码为什么流水线就失败了？

可以检查依赖的其他资源是否有变动，比如：

  1. 插件任务声明镜像版本为 latest，镜像是否有变动。
  2. CI 配置文件引用了其他仓库文件，被引用文件是否有变动。
  3. 有可能网络波动，Rebuild 试试。

如何查看流水线完整日志？

CI 服务发送插件任务和脚本任务至 Runner 执行。如果任务日志过长，将会被截断并返回给 CI 服务。

阶段会汇总其下所有任务的日志。若阶段日志过长，也会被截断以便更好地展示在日志页面上。

构建完成后，您可在日志页面流水线右上角点击日志下载按钮查看完整日志。

为什么不提供固定的出口 IP？

CNB 的出口 IP 地址是动态的，可能会随时间变化。

这是因为：

  1. 运维弹性：平台会根据负载自动扩缩容、迁移节点等运维操作，出口 IP 随之动态变化。
  2. 安全建议：不建议对 CNB 出口 IP 加白名单。CNB 是公开开放的平台，对出口 IP 加白等同于对公网加白，存在安全风险。

替代方案（如需固定 IP 访问内部服务）：

如何构建多架构/多平台镜像？

若需要使用buildx构建多种架构/平台的镜像，可以开启rootlessBuildkitd特性。需要在服务中声明：

.cnb.yml
main:
  push:
    - docker:
        image: golang:1.24
      services:
        - name: docker
          options:
            rootlessBuildkitd:
              enabled: true
      env:
        IMAGE_TAG: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
      stages:
        - name: go build
          script: ./build.sh
        - name: docker login
          script: docker login -u ${CNB_TOKEN_USER_NAME} -p "${CNB_TOKEN}" ${CNB_DOCKER_REGISTRY}
        - name: docker build and push
          script: docker buildx build -t ${IMAGE_TAG} --platform linux/amd64,linux/amd64/v2,linux/amd64/v3,linux/arm64,linux/riscv64,linux/ppc64le,linux/s390x,linux/386,linux/mips64le,linux/mips64,linux/loong64,linux/arm/v7,linux/arm/v6 --push .

为什么流水线的仓库存储用量跟页面上显示不一致？

一般来说，流水线上看到的仓库大小应该是跟页面上显示接近的。

但对于所有公开的Fork仓库，为了加速构建流程和优化存储空间，目前所有的Fork仓库，在构建节点上都会复用其祖先仓库的.git目录，然后再通过OverlayFS技术裂变出多份副本供不同仓库使用。因此在流水线上看到的仓库大小，实际上是包含祖先仓库和所有子孙仓库的仓库大小。

另外，对于普通的仓库，在页面上触发仓库GC之后，流水线上仓库大小也不会立马变化，需要等待构建机本身的缓存gc逻辑运行后，才会跟页面上显示一致。

流水线中运行 Docker 镜像时报错 UID/GID 超过 65535？

如果在流水线中遇到类似以下错误：

docker: failed to extract layer ... failed to Lchown ... for UID 100000, GID 100000: lchown ...: invalid argument
(Hint: try increasing the number of subordinate IDs in /etc/subuid and /etc/subgid)

原因：

CNB 上的 Docker 采用了 uidmap 技术，会将容器内的 UID 范围限制在 0-65535。当使用的镜像中存在 UID/GID 超过 65535 的文件时，Docker 无法正确映射这些高位 UID/GID，从而导致镜像层解压失败。

解决方案：

重新制作镜像，将这类文件清理掉或者改成正常 UID/GID，不要使用超过 65535 的 UID/GID 的基础镜像来规避此问题。

代码仓库相关

如何解决代码合并冲突？

若创建 PR 或在 PR 相关事件的构建中碰到代码冲突问题，可以通过如下命令解决：

git fetch origin          # 从远端仓库获取更新
git rebase -i origin/main # 实际的目标分支名

# 本地处理冲突
git commit  # 根据实际情况提交代码到本地仓库
git push -f # 推送到远端仓库

如何彻底删除GIT仓库里的文件，释放空间？

由于GIT仓库支持恢复任意历史提交，因此.git目录会存储历史上提交的所有文件。单纯删除工作目录中的文件，并不会释放空间。

因此要彻底删除GIT仓库里的文件，释放空间，建议通过以下两种方法进行：

方法一(操作最简单): 直接远端建一个新的仓库, 然后把需要的文件复制过去，再改名为原来的仓库。

方法二(操作复杂): 通过git filter-branch命令或者其他第三方工具（如：BFG Repo-Cleaner）。在本地彻底删除对应文件后，再强制推送到远程，然后再触发远程仓库GC流程。

© 2026 cnb.cool