流水线卷挂载 YAML 配置说明（volumes / mount）

本文说明如何在流水线 YAML 中声明卷（volumes）以及在任务上挂载卷（mount），包括 plugin 任务的挂载合并规则、内置工作区注意事项和常见报错。

背景

流水线中每个 step 都运行在独立容器里，构建结束即销毁，默认只有内置的 _workspace 卷用于共享克隆下来的源码。用户无法声明自己的卷，也就无法在任务之间共享数据，或把依赖缓存保留到下一次构建。

为此引入两级声明：

• 阶段级 volumes：声明卷的名称、类型和来源；
• 任务级 mount：把已声明的卷挂载到当前容器目录。

同一个卷可以被多个任务挂到不同路径。运行时按声明顺序解析卷。

解决的问题

1. 任务间数据不共享：每个 step 是独立容器，把同一卷挂到多个 step，即可传递构建产物或已下载的依赖。
2. 依赖无法跨构建复用：使用 host 卷把依赖缓存留在宿主机，下次构建直接命中，省去重复下载。
3. 配置/凭据注入：把配置文件挂进容器，无需写死在镜像里。
4. 安全隔离：保留卷名和挂载路径校验，防止覆盖内置卷或工作区，避免错误挂载被静默忽略。

使用手册

1. 基本结构

卷在 CI stage 的 spec.volumes 中声明，然后在 step 的 spec.mount 中按名字引用：

stages:
  - type: ci
    spec:
      volumes:
        - name: cache          # 卷名，stage 内唯一
          type: temp           # host / temp
      steps:
        - name: 写入
          type: run
          spec:
            mount:
              - name: cache
                path: /cache
            script:
              - echo hello > /cache/hello.txt
        - name: 读取
          type: run
          spec:
            mount:
              - name: cache
                path: /cache
            script:
              - cat /cache/hello.txt

要点：

• volumes 是 stage 级的，只能在 type: ci 的 stage 中声明；同一个 stage 的所有任务共享这些卷，跨 stage 不共享。
• mount 是 step 级的，写在 step 的 spec 下。
• 卷通过 name 关联，path 是容器内的挂载路径。

2. 卷定义：volumes

volumes:
  - name: <卷名>
    type: host | temp
    spec:
      ...

2.1 type: host

把宿主机目录挂进容器。

volumes:
  - name: m2
    type: host
    spec:
      path: /data/gitfox/m2      # 宿主机上的绝对路径

2.2 type: temp

由运行器创建临时卷，stage 结束后清理。

volumes:
  - name: tmp
    type: temp

2.3 保留卷名

以下名字由运行器内部使用，用户不能声明：

_workspace  _addons  _docker_socket  socketDir

声明后会报错：

stage volume name "_workspace" is reserved

3. 挂载：mount

steps:
  - name: 自定义脚本
    type: run | plugin
    spec:
      mount:
        - name: <卷名>
          path: <容器内绝对路径>

规则：

• 同一个卷可以挂到多个任务、也可以在同一容器内挂到多个路径。
• 同一任务内挂载路径不能重复；路径会先做规范化（path.Clean），因此 /data/、/a/../data 和 /data 视为同一个路径，重复会报错。

4. 跨任务共享示例

stages:
  - type: ci
    spec:
      volumes:
        - name: tmp
          type: temp
      steps:
        - name: git克隆
          type: plugin
          spec:
            name: scm_git_clone
            mount:
              - name: tmp
                path: /gitfox
            inputs:
              ...
        - name: 自定义脚本
          type: run
          spec:
            mount:
              - name: tmp
                path: /tmp
            script:
              - ls -l /tmp

第一步把内容写进 tmp 卷的 /gitfox，第二步在 /tmp 能看到同一份数据。

5. 内置工作区 /gitfox 与挂载冲突

每个任务默认会追加一个内置工作区挂载：

_workspace -> /gitfox

如果某个任务显式把用户卷挂到了 /gitfox：

• 用户挂载优先，内置工作区挂载会被跳过，并输出一条 warn 日志；
• 该任务里的 /gitfox 是用户卷，不再与其他任务共享工作区内容（除非其他任务也挂同一个卷）；
• GITFOX_WORKSPACE 环境变量仍然是 /gitfox，插件仍会往这个路径写；
• stage 末尾的 clean 任务会操作用户挂载的工作区。

如果你希望多个任务共享同一目录，推荐显式声明一个 temp/host 卷，并在各任务挂载到同一路径：

stages:
  - type: ci
    spec:
      volumes:
        - name: shared
          type: temp
      steps:
        - name: 写入
          type: run
          spec:
            mount:
              - name: shared
                path: /data
            script:
              - echo hi > /data/a.txt
        - name: 读取
          type: run
          spec:
            mount:
              - name: shared
                path: /data
            script:
              - cat /data/a.txt

最佳实践: 编译缓存，构建提速

将编译过程中的依赖缓存在宿主机中，下次构建直接命中，省去重复下载时间，提高编译效率

golang 编译缓存

version: 1
kind: pipeline
spec:
  options:
    clone:
      disabled: true
  stages:
    - id: 0kjuhvvc
      name: 阶段
      desc: ''
      type: ci
      when: ${{ success() }}
      spec:
      # 1. 阶段层声明卷：宿主机目录，跨构建保留
        volumes:
          - name: cache
            type: host
            spec:
              path: /root/tmp/go-cache
        steps:
          - id: wnrv8ek5_scm_git_clone
            when: ${{ success() }}
            name: git克隆
            type: plugin
            spec:
              inputs:
                repository: http://example.com:3000/git/test/go-repo.git
                gitRef: ${{parameters.gitRef}}
                cloneDepth: 1
                cloneDir: ''
              name: scm_git_clone
          - id: r889y3o3_build_go
            when: ${{ success() }}
            name: Golang编译
            type: plugin
            spec:
            # 2. 编译任务挂到 Go 模块缓存目录
              mount:
                - name: cache
                  path: /root/.gvm/pkgsets/go1.26.2/global/pkg/mod # go modules存放目录，挂载至宿主机目录
              inputs:
                compileCommand: pwd && export GOPROXY=https://goproxy.cn,direct && go mod tidy
                workspace: .
                goVersion: 1.26.2
              name: build_go

6.2 编译提速效果

6.3 其他语言缓存目录参考

常见问题

挂载声明会在两处校验：

1. 触发流水线时：解析、插件/模板展开之后校验，错误直接返回给触发方，不生成 stage/step 记录；
2. 运行器编译时：CompilerImpl.Compile 开头再次校验，作为最终校验。

常见错误：

触发阶段的错误会带上 stage 上下文，例如：

stage "stage-1": step "build": mount volume "data" is not declared in stage volumes