GoCD 26.1.0 配置参数详解

GoCD 26.1.0 配置体系详解：cruise-config.xml 中心配置结构与热加载/校验回滚机制、server 属性、security 认证授权（bcrypt 密码文件实测）、pipeline 四层模型逐元素参数、pipeline/stage 双级环境变量注入实测、内置 GO_* 变量清单、JVM 堆限验证与生产配置模板。

GoCDGoCDCI/CD2026/10/20

GoCD 26.1.0 配置参数详解

目标：系统讲解 GoCD 26.1.0 的配置体系——中心配置文件 cruise-config.xml 的结构、server 元素属性、security 认证授权、pipeline 四层模型各元素参数、pipeline/stage 双级环境变量，以及部署层环境变量（JVM 堆、server 接入地址），每项参数配实测验证方法与回显。本文在单机部署环境（1 server + 1 agent）实测，实测日期 2026-10-20；部署过程见《GoCD Docker Compose 部署指南》，选型背景见《GoCD 26.1.0 介绍与选型指南》。

一、环境信息

项目值说明
操作系统Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic）实测
GoCD 版本26.1.0（build 22803）REST API version 实测返回
部署形态Docker Compose 单机（1 server + 1 agent）部署篇实测
Web/API 入口http://localhost:8146（映射到服务 8153）compose 实测
中心配置文件/opt/data/gocd/godata/config/cruise-config.xml（服务内 /godata/config/cruise-config.xml）实测路径
密码文件/opt/data/gocd/godata/config/password.properties（服务内 /godata/config/password.properties）实测路径
管理账号admin / q1w2e3r4密码文件认证，实测可登录
配置 schema 版本schemaVersion="139"26.1.0 自动维护

本文所有 API 示例均以 basic auth admin:q1w2e3r4 调用，端口号 8146 换成你自己的 Web 映射端口即可。

二、前置条件

  1. 已按《GoCD Docker Compose 部署指南》完成部署，server 可访问、认证已启用（password file 插件 + admin 账号）、agent 已授权；
  2. 验证环境就绪：
curl -s -u admin:q1w2e3r4 http://localhost:8146/go/api/version -H 'Accept: application/vnd.go.cd.v1+json' | grep '"version"'

  "version" : "26.1.0",
  1. 配置文件可编辑且属主正确（server 进程以 uid=1000 运行）：
ls -l /opt/data/gocd/godata/config/cruise-config.xml

-rw-r--r-- 1 yahui root 2249 10月 20 15:22 /opt/data/gocd/godata/config/cruise-config.xml

⚠️ 编辑保存后若属主变化，执行 sudo chown 1000:0 /opt/data/gocd/godata/config/cruise-config.xml 保持 server 进程可读写，否则下一轮热加载/回滚写盘会失败。

三、参数查看与修改方式

GoCD 的配置有三种修改通道，本章逐一说明并给出实测结论。

3.1 中心配置文件直改（推荐，本文实测主通道）

直接编辑宿主机 /opt/data/gocd/godata/config/cruise-config.xml，server 每 5 秒轮询文件变更，检测到修改后自动校验 + 热加载，无需重启。实测日志回显：

jvm 1    | 2026-10-20 07:22:02,090 INFO  [goThreadPoolTaskScheduler-3] GoFileConfigDataSource:267 - Config file changed at 2026-10-20T07:22:01.268Z

加载成功后配置立即生效（本文 5.4.4 节的环境变量实测即采用该通道，改完约 20 秒内新配置即可在任务中生效）。

校验失败的自动回滚机制（实测）：新文件通不过 XSD 校验时，server 会把无效文件改名保留为 cruise-config.xml.invalid.<时间戳>，继续沿用上一份有效配置。实测曾在启动阶段触发：

cruise-config.xml.invalid.2026-10-20-06-46-24

这一机制保证改错配置不会打断运行中的服务，但也意味着每次改完配置必须确认加载成功（看日志 Config file changed 之后无 Error 行，或用 API 验证新配置可见），否则会一直用旧配置运行而不自知。

3.2 Web UI 修改

Web UI（Admin → Pipelines → 编辑）本质也是修改同一份 cruise-config.xml：每次保存自动生成配置版本快照，UI 内可 diff 历史并回滚。适合单条流水线的可视化微调；批量改动或需要代码评审的场景仍建议走 3.1 直改文件（可纳入 git 管理）。

3.3 REST API 与 config repo

REST API 覆盖运行态操作（触发、暂停、agent 管理等，实测清单见《GoCD 26.1.0 常用 CLI 命令详解》）；流水线定义层的 API 端点（如 config/current 全量配置导出）在 26.1.0 实测返回 404 未开放，流水线结构管理以文件与 UI 为主。

另一通道是 config repo：把流水线定义以 YAML/JSON 放在独立 Git 仓库，由配置插件解析进 server，与中心配置共存。本文未实测该插件，配置结构仍以中心 cruise-config.xml 为准。

四、参数总览

4.1 顶层结构

<cruise>                         根元素（schemaVersion 自动维护）
├── <server ...>                 服务端全局配置（属性见 4.2）
│   ├── <security>               认证与授权（见 5.2）
│   └── <artifacts>              制品存储位置（见 5.3）
├── <pipelines>                  流水线定义（见 5.4）
│   └── <pipeline>               params → trackingtool → timer → environmentvariables
│                                → dependencies → materials → stage 的严格顺序
└── <environments>/<templates>/<config-repos> 等（可选，本文未启用）

4.2 server 元素属性（实测全文见 5.5 生产模板）

属性实测值说明
schemaVersion139配置结构版本，server 自动维护，禁止手改
serverIdfdb12fb8-532d-4c8c-87f8-6947361dd82d实例唯一 ID，首次启动自动生成
tokenGenerationKey96ee4c80-8397-43c1-aca7-7ea6ef206721agent 注册 token 签名密钥，自动生成
webhookSecret42886f95-d960-445e-8432-f6931466e057SCM webhook 签名密钥，自动生成
agentAutoRegisterKey75f89f53-bea5-4bcd-b05e-a25d18365ee9agent 自动注册密钥：agent 侧提供相同密钥（其数据目录 config/autoregister.properties）可跳过 Pending 审批；本文 agent 未配置该密钥，故走「Pending → enable」审批

⚠️ 四个密钥属性均为实例身份/安全凭据，迁移或重建实例时保留原值可使 agent/webhook 无缝续用；泄露需整体轮换。

4.3 部署层环境变量（compose 注入）

变量作用域详见
GOCD_SERVER_JVM_OPTSserver JVM 参数（堆限制）5.1
GOCD_AGENT_JVM_OPTSagent JVM 参数5.1
GO_SERVER_URLagent 连接 server 的入口5.1

五、核心参数分类详解

5.1 server/agent 环境变量与 JVM 堆

GOCD_SERVER_JVM_OPTS / GOCD_AGENT_JVM_OPTS 是 26.1.0 镜像注入 JVM 参数的正确变量。实测在 compose 中设置 -Xms256m -Xmx512m 后，用进程命令行验证（server）：

docker exec gocd-26.1.0-server sh -c "ps aux | grep '[j]ava' | head -2" | grep -oE '\-Xms[0-9]+m|\-Xmx[0-9]+m|\-XX:MaxMetaspaceSize=[0-9]+m'

输出节选（实测）：

-Xms512m
-Xmx1024m
-XX:MaxMetaspaceSize=400m
-Xms256m
-Xmx512m

镜像 wrapper 配置内置默认 -Xms512m -Xmx1024m 在前，注入参数追加在后——JVM 同参数后者覆盖前者，实际生效 256m/512m。agent 侧同理（agent 工作进程由 bootstrapper 拉起）：

docker exec gocd-26.1.0-agent sh -c "ps aux | grep '[j]ava'" | tail -1 | grep -oE '\-Xms[0-9]+m|\-Xmx[0-9]+m'

-Xms128m
-Xmx256m
-Xms256m
-Xmx512m

⚠️ 旧文档常出现 GO_SERVER_SYSTEM_PROPERTIES/GO_AGENT_SYSTEM_PROPERTIES——实测对 26.1.0 镜像设置堆参数不生效，必须用 GOCD_SERVER_JVM_OPTS/GOCD_AGENT_JVM_OPTS。

GO_SERVER_URL 指定 agent 连接的 server 入口。实测两个关键值约束：26.1.0 server 镜像仅监听 8153（HTTP），8154（HTTPS）未启用——写 http://gocd-server:8154/go 会导致 agent 连接拒绝，改为 8153 后立即注册成功；该值会随 job 下发给任务进程（console log 实测 overriding environment variable 'GO_SERVER_URL' with value 'http://gocd-server:8153/go'），且出现在 agent 工作进程命令行尾部（-serverUrl http://gocd-server:8153/go）。

5.2 security 节（认证与授权）

实测生效的完整配置：

<security>
  <authConfigs>
    <authConfig id="9f2b1c3d4e5f6a7b8c9d0e1f2a3b4c5d" pluginId="cd.go.authentication.passwordfile">
      <property>
        <key>PasswordFilePath</key>
        <value>/godata/config/password.properties</value>
      </property>
    </authConfig>
  </authConfigs>
  <admins>
    <user>admin</user>
  </admins>
</security>

逐项说明：

参数说明
authConfig pluginId认证插件 ID；密码文件插件固定 cd.go.authentication.passwordfile，LDAP/OIDC 换对应插件
authConfig id任意唯一字符串（32 位十六进制为惯例），日志中认证记录会引用它
PasswordFilePath密码文件路径，以 server 进程视角书写
admins/user超级管理员用户名，可多个 <user> 并列

密码文件格式（每行 用户名:bcrypt哈希），实测生成命令（GoCD 内置 jBcrypt 仅识别 $2a$ 前缀，python bcrypt 需显式指定）：

python3 -c "import bcrypt; print(bcrypt.hashpw(b'q1w2e3r4', bcrypt.gensalt(rounds=10, prefix=b'2a')).decode())"

$2a$10$rDlCydKPpOrf2GQukX9A/O8N.Cck/4rbU45bskdUW/RNziBxuusje

写入 /opt/data/gocd/godata/config/password.properties（属主 1000:0）后无需重启——密码文件在每次认证时读取。实测改完后立刻用新凭据调用 API 返回 200：

login验证=200

⚠️ 实测踩坑：<security> 内写空元素 <roles /> 会导致 XSD 校验失败（报 One of '{baseRole}' is expected），不使用角色时直接省略该元素。

💡 技术拓展：GoCD 认证后端不止密码文件一种。常见后端对比——

后端原理适用场景
密码文件（本文所用）本地文件存 bcrypt 哈希，零外部依赖起步、小团队
LDAP/AD对接企业目录，复用账号体系有域控的企业
OIDC对接 Keycloak/GitHub 等 OIDC 提供方已有 SSO 的组织

本文因单机实测且无外部目录服务，采用密码文件插件。

5.3 artifacts 节

<artifacts>
  <artifactsDir>artifacts</artifactsDir>
</artifacts>

artifactsDir 指定制品存储目录名，相对 server 数据根（/godata），即实测落盘的 /opt/data/gocd/godata/artifacts/。job 的控制台日志（cruise-output/console.log）与产物都归档在此。

5.4 pipeline 配置核心

5.4.1 元素顺序（XSD 严格校验）

<pipeline> 子元素顺序由镜像内 cruise-config.xsd 定义，实测顺序：

params? → trackingtool? → timer? → environmentvariables? → dependencies* → materials → stage+

顺序错误即校验失败并触发 .invalid 回滚（3.1 节）。实测两种错误位置——<timer> 放 <materials> 之后、放 <stage> 之后——均加载失败。

5.4.2 timer（定时触发）

<timer>0 0 5 ? * *</timer>

值为 Quartz cron 表达式（6 段：秒 分 时 日 月 周，? 表示不指定）。上式为每日 05:00:00。可选属性 onlyOnChanges="true" 表示仅当物料有新变更时定时触发才生效。

实测约束：pipeline 必须至少绑定一个 SCM 类物料——只写 timer 不写 materials 会被校验拒绝（materials 必须含 Git/SVN/Hg/P4 等版本库物料）。timer 与物料变更触发并存时，物料新提交会立即触发（部署篇 4.7 节实测 counter 1 即由物料变更自动触发，trigger_message: "modified by ops <ops@quzuo.net>"）。

5.4.3 materials（物料）

<materials>
  <git url="/godata/materials/demo-app.git" branch="main" />
</materials>
参数说明
url仓库地址，中心化配置下以 server 进程视角书写（挂载目录即 /godata/...，正式环境写 https://git.example.com/team/app.git）
branch分支，默认 master，实测 main
destination（可选）检出子目录，多物料时必填以隔离目录

一个 pipeline 可并列多个物料（多仓库合并构建）；也可用 <pipeline pipelineName="upstream" stageName="build" /> 把上游流水线作为物料（依赖触发，fan-in/out 编排的基础）。

5.4.4 environmentvariables（pipeline 级与 stage 级，实测）

pipeline 级写在 <timer> 之后、<materials> 之前；stage 级写在 <jobs> 之前：

<pipeline name="hello-cd">
  <timer>0 0 5 ? * *</timer>
  <environmentvariables>
    <variable name="DEMO_ENV">
      <value>pipeline-level</value>
    </variable>
  </environmentvariables>
  <materials>
    <git url="/godata/materials/demo-app.git" branch="main" />
  </materials>
  <stage name="build-stage">
    <environmentvariables>
      <variable name="STAGE_ENV">
        <value>stage-level</value>
      </variable>
    </environmentvariables>
    <jobs>
      ...
    </jobs>
  </stage>
</pipeline>

实测验证：保存后热加载（Config file changed at 2026-10-20T07:22:01.268Z），API 触发运行（counter 4，Passed），job 控制台日志中出现两行注入记录：

pr|07:22:38.725 [go] setting environment variable 'DEMO_ENV' to value 'pipeline-level'
pr|07:22:38.725 [go] setting environment variable 'STAGE_ENV' to value 'stage-level'

pipeline 级与 stage 级变量都注入到该 stage 全部 job 的任务进程。job 级还支持 <job> 内的 <environmentvariables>（同结构）。

5.4.5 stage（阶段与人工审批）

<stage name="build-stage">
  <jobs> ... </jobs>
</stage>
参数说明
name阶段名，串行执行，前一 stage 通过才轮到下一个
<approval type="manual" />（可选）人工审批门：该 stage 需要在 UI 点确认（或有 operate 权限者 API 批准）才执行，是「晋级到生产前人工放行」的载体；缺省为 success 自动通过
<environmentvariables>见 5.4.4
fetchMaterials（可选）是否在 stage 开始时重新拉取物料

5.4.6 job 与 task（任务）

<job name="run-echo">
  <tasks>
    <exec command="echo">
      <arg>hello-from-gocd</arg>
      <runif status="passed" />
    </exec>
  </tasks>
</job>
参数说明
job name作业名；同一 stage 内多个 job 并行调度到不同 agent
exec commandshell 命令；<arg> 子元素逐个传参（等价于命令行参数列表），<runif status="passed" /> 定义执行条件（默认 passed，可配 failed/any）
其他 task 类型ant/nant/rake/gradle/maven/pluggableTask，本质都是预置参数模板的命令包装
<artifacts>（job 内，可选）声明产物上传（<artifact src="target/*.jar" dest="pkg" />），stage 间传递靠后续 stage 的 fetch artifact 任务

任务在 agent 的工作目录（实测 /go-working-dir，物料检出于其下）执行；多任务按定义顺序串行，任一任务失败（且 runif 不含 failed）即 job 失败。

5.5 内置环境变量清单（任务进程实测）

每次 job 运行，GoCD 自动注入以下变量（console log 实测原文，counter 3 运行）：

pr|07:21:27.676 [go] overriding environment variable 'GO_SERVER_URL' with value 'http://gocd-server:8153/go'
pr|07:21:27.676 [go] setting environment variable 'GO_PIPELINE_GROUP_NAME' to value 'defaultGroup'
pr|07:21:27.676 [go] setting environment variable 'GO_TRIGGER_USER' to value 'admin'
pr|07:21:27.676 [go] setting environment variable 'GO_PIPELINE_NAME' to value 'hello-cd'
pr|07:21:27.676 [go] setting environment variable 'GO_PIPELINE_COUNTER' to value '3'
pr|07:21:27.676 [go] setting environment variable 'GO_PIPELINE_LABEL' to value '3'
pr|07:21:27.676 [go] setting environment variable 'GO_STAGE_NAME' to value 'build-stage'
pr|07:21:27.676 [go] setting environment variable 'GO_STAGE_COUNTER' to value '1'
pr|07:21:27.676 [go] setting environment variable 'GO_JOB_NAME' to value 'run-echo'
pr|07:21:27.676 [go] setting environment variable 'GO_REVISION' to value 'bef2adaf466c3d10d0d932973ad31c0e448fe67e'
pr|07:21:27.676 [go] setting environment variable 'GO_TO_REVISION' to value 'bef2adaf466c3d10d0d932973ad31c0e448fe67e'
pr|07:21:27.676 [go] setting environment variable 'GO_FROM_REVISION' to value 'bef2adaf466c3d10d0d932973ad31c0e448fe67e'
pr|07:21:27.676 [go] setting environment variable 'GO_MATERIAL_URL' to value '/godata/materials/demo-app.git'
pr|07:21:27.676 [go] setting environment variable 'GO_MATERIAL_BRANCH' to value 'main'
pr|07:21:27.676 [go] setting environment variable 'GO_MATERIAL_HAS_CHANGED' to value 'false'

任务脚本可直接引用（如 echo "building $GO_PIPELINE_NAME counter=$GO_PIPELINE_COUNTER"）。GO_SERVER_URL 为覆盖注入（agent 自身配置），其余按本次运行上下文生成。

六、生产配置模板

适用场景：小团队（≤10 个 agent、日均百次以内构建）单机起步，2C4G 内存、40GB+ 磁盘（制品目录独立盘更佳）。模板中所有元素均与本文实测语义一致：

<?xml version="1.0" encoding="utf-8"?>
<cruise xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="cruise-config.xsd" schemaVersion="139">
  <server agentAutoRegisterKey="75f89f53-bea5-4bcd-b05e-a25d18365ee9" webhookSecret="42886f95-d960-445e-8432-f6931466e057" serverId="fdb12fb8-532d-4c8c-87f8-6947361dd82d" tokenGenerationKey="96ee4c80-8397-43c1-aca7-7ea6ef206721">
    <security>
      <authConfigs>
        <authConfig id="9f2b1c3d4e5f6a7b8c9d0e1f2a3b4c5d" pluginId="cd.go.authentication.passwordfile">
          <property>
            <key>PasswordFilePath</key>
            <value>/godata/config/password.properties</value>
          </property>
        </authConfig>
      </authConfigs>
      <admins>
        <user>admin</user>
      </admins>
    </security>
    <artifacts>
      <artifactsDir>artifacts</artifactsDir>
    </artifacts>
  </server>
  <pipelines>
    <pipeline name="hello-cd">
      <timer>0 0 5 ? * *</timer>
      <environmentvariables>
        <variable name="DEMO_ENV">
          <value>pipeline-level</value>
        </variable>
      </environmentvariables>
      <materials>
        <git url="/godata/materials/demo-app.git" branch="main" />
      </materials>
      <stage name="build-stage">
        <environmentvariables>
          <variable name="STAGE_ENV">
            <value>stage-level</value>
          </variable>
        </environmentvariables>
        <jobs>
          <job name="run-echo">
            <tasks>
              <exec command="echo">
                <arg>hello-from-gocd</arg>
                <runif status="passed" />
              </exec>
            </tasks>
          </job>
        </jobs>
      </stage>
    </pipeline>
  </pipelines>
</cruise>

配套资源建议：server JVM 堆 -Xms256m -Xmx512m（compose 环境变量 GOCD_SERVER_JVM_OPTS，实测生效验证见 5.1）；agent 每实例同档堆限；磁盘重点给 /godata/artifacts 与 /godata/db（数据库随流水线历史增长，定期清理旧 artifacts 或用磁盘配额）。

七、常见问题（FAQ）

Q1：改了 cruise-config.xml 没生效？

三步排查：① 看日志有无 Config file changed（没出现 = server 没检测到变更，检查文件路径与属主）；② 有 changed 但报 Error = XSD 校验失败，文件被改名为 .invalid.<时间戳>，按报错行修复（常见：空 <roles />、timer 位置）；③ 加载成功但行为没变 = 看的是旧 run，新配置只影响之后的触发。

Q2：配置校验失败后服务还在跑旧配置，怎么知道当前生效的是哪份？

用运行态 API 对照：curl -s -u admin:q1w2e3r4 http://localhost:8146/go/api/admin/pipeline_groups/defaultGroup -H 'Accept: application/vnd.go.cd.v1+json' 返回的流水线清单就是当前生效配置（实测返回 defaultGroup 下 hello-cd）。数据目录里存在 cruise-config.xml.invalid.* 文件即说明曾有失败改动。

Q3：timer 写了为什么没在设定时间触发？

先确认表达式是 Quartz 6 段格式（0 0 5 ? * *，不是 crontab 5 段）；再确认 pipeline 未被 pause（API 暂停后定时与手动触发都不受理，unpause 恢复）；最后确认 materials 里已有 SCM 物料（只有 timer 无版本库物料的配置本身就不会通过校验）。

Q4：GO_SERVER_SYSTEM_PROPERTIES 设置堆为什么不生效？

26.1.0 镜像的 JVM 参数入口是 GOCD_SERVER_JVM_OPTS/GOCD_AGENT_JVM_OPTS，旧变量不参与拼接。改后按 5.1 节用 ps aux 验证。

Q5：密码文件改了但新密码登不上？

检查三处：文件属主是否 1000:0（server 进程需可读）；哈希前缀是否 $2a$（$2b$ 会被 jBcrypt 拒绝）；格式是否严格 用户名:哈希 单行无空格。改完无需重启，直接重试认证即可。

Q6：pipeline 里的环境变量在任务里看不到？

变量定义位置必须与作用层级匹配（pipeline 级在 timer 之后、stage 级在 jobs 之前，见 5.4.4），保存后确认日志热加载成功再触发新的 run（旧 run 不会追加变量）；最终以新 run 控制台日志的 setting environment variable ... 行为准。

参考链接

  1. 官方配置参考：https://docs.gocd.org/current/configuration/configuration_reference.html
  2. schema 快照与 XSD（镜像内 /go-server/config/cruise-config.xsd）说明：https://docs.gocd.org/current/developer_guide/contribute_internals/design/configuration.html
  3. 密码文件认证插件：https://github.com/gocd/gocd-ldap-authentication（passwordfile 插件同系列）
  4. Quartz cron 语法：https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html
  5. GoCD REST API 文档：https://api.gocd.org/26.1.0/
  6. 本文部署环境搭建：《GoCD Docker Compose 部署指南》
  7. 本文运行态命令实测：《GoCD 26.1.0 常用 CLI 命令详解》