Concourse 8.3.1 配置参数详解

本文以真实服务器视角逐项实测 Concourse 8.3.1 的核心配置参数，覆盖 web 节点（ATC/TSA/PostgreSQL/认证）与 worker 节点（运行时/TSA 客户端/卷/DNS）两大类，参数均来自 concourse web --help 与 concourse worker --help 官方帮助输出，验证方式包括进程环境核对、REST API 返回值核对与构建行为验证。配套部署环境见《Concourse 8.3.1 Docker Compose 部署指南》。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic）
• Concourse 版本：8.3.1（单二进制软件包，concourse web / concourse worker 子命令）
• 部署形态：Docker Compose 三服务栈（db / web / worker），项目名 concourse-831-stack
• 对外端口：8148 → web 默认 8080；TSA 注册端口 2222（栈内网）
• 管理账号：root / q1w2e3r4（main 团队 owner）
• 参数取证来源：concourse web --help（6555 行）、concourse worker --help（1494 行）官方帮助文本，2026-10-20 实测

二、参数体系与映射规则

Concourse 全部组件共用一个二进制，配置通过"命令行参数 + 环境变量"两种方式传入，二选一等价：

1. 环境变量映射规则：CLI 参数 --<foo-bar> 对应环境变量 CONCOURSE_<FOO_BAR>（worker 侧为 CONCOURSE_WORKER_<FOO_BAR>）。例如 --external-url ↔ CONCOURSE_EXTERNAL_URL，--tsa-host ↔ CONCOURSE_WORKER_TSA_HOST。
2. 键值来源：所有参数值均可在启动命令行给出，也可通过环境变量注入；Compose 编排下推荐环境变量（便于 diff 与密钥挂载分离）。
3. 验证手段：concourse web --help / concourse worker --help 可打印每个参数的说明、默认值与环境变量名；运行中的服务用 env | grep CONCOURSE_ 核对实际生效值。

help 输出样式（--bind-port 例，含默认值与环境变量标注）：

      --bind-port=                                                                       Port on
                                                                                         which to
                                                                                         listen for
                                                                                         HTTP
                                                                                         traffic.
                                                                                         (default: 8080)
                                                                                         [$CONCOUR-
                                                                                         SE_BIND_POR-
                                                                                         T]

💡 实测提示：8.3.1 的 help 输出按 100 列宽强制折行，长参数描述会被切断，阅读时需自行拼接。

三、Web 节点（ATC/TSA）核心参数

concourse web 进程同时承担 ATC（API/调度）与 TSA（worker 注册网关）职责，参数按功能分组如下。

3.1 对外服务与集群标识

实测核验：

curl -s http://127.0.0.1:8148/api/v1/info

实测输出：

{"version":"8.3.1","worker_version":"3.0","feature_flags":{"build_rerun":false,"cache_streamed_volumes":false,"global_resources":false,"resource_causality":false},"external_url":"http://192.168.146.128:8148","cluster_name":"quzuo-lab"}

3.2 PostgreSQL 连接参数

web 节点自身无状态，PostgreSQL 是唯一持久化组件。默认值指向本机（127.0.0.1、库名 atc），独立部署数据库时必须显式覆盖：

实测：db 服务带 pg_isready 健康检查（Up (healthy)），web 依赖 condition: service_healthy 后启动，ATC 就绪日志：

{"timestamp":"2026-10-20T06:40:42.805293710Z","level":"info","source":"atc","message":"atc.listening","data":{"debug":"127.0.0.1:8079","http":"0.0.0.0:8080"}}

3.3 认证与团队参数

本地认证是最小可用的认证方式，两个参数必须成对出现：

实测核验：

fly -t main login -c http://127.0.0.1:8148 -u root -p q1w2e3r4
fly -t main userinfo

实测输出：

logging in to team 'main'


target saved
root  main/owner

💡 说明：--add-local-user 可重复传入多个 username:password；除本地认证外，同一参数位族还提供 --github-*、--gitlab-*、--ldap-*、--oidc-*、--saml-*、--oauth-*、--cf-*、--bitbucket-cloud-*、--gitea-* 等企业认证参数组（详见 help 认证分节）。

3.4 密钥与 TSA 服务端参数

💡 实测细节：官方软件包入口脚本对上述密钥参数做了"存在即生效"的探测——挂载到 /concourse-keys 且文件名匹配默认值时，即使不写环境变量也会自动注入。本文为明确起见全部显式声明。

3.5 Web 节点运行时环境核对

docker exec concourse-831-stack-web-1 env | grep CONCOURSE_ | sort

实测输出：

CONCOURSE_ADD_LOCAL_USER=root:q1w2e3r4
CONCOURSE_CLUSTER_NAME=quzuo-lab
CONCOURSE_EXTERNAL_URL=http://192.168.146.128:8148
CONCOURSE_MAIN_TEAM_LOCAL_USER=root
CONCOURSE_POSTGRES_DATABASE=concourse
CONCOURSE_POSTGRES_HOST=db
CONCOURSE_POSTGRES_PASSWORD=concourse_pass
CONCOURSE_POSTGRES_PORT=5432
CONCOURSE_POSTGRES_USER=concourse_user
CONCOURSE_SESSION_SIGNING_KEY=/concourse-keys/session_signing_key
CONCOURSE_TSA_AUTHORIZED_KEYS=/concourse-keys/authorized_worker_keys
CONCOURSE_TSA_HOST_KEY=/concourse-keys/tsa_host_key
CONCOURSE_WORK_DIR=/worker-state
CONCOURSE_WORKER_WORK_DIR=/worker-state

其中 CONCOURSE_WORK_DIR=/worker-state 为软件包内置默认值（单二进制同包跑 web 与 worker，工作目录约定一致）。

四、Worker 节点核心参数

concourse worker 参数决定注册身份、与 TSA 的连接、任务运行时与卷驱动。

4.1 注册与 TSA 连接

实测：worker 注册成功后 fly workers 输出（3.0 为 worker 运行时版本协议号）：

fly -t main workers

worker-01  0  linux  none  none  running  3.0  6s

worker 侧关键注册日志：

{"timestamp":"2026-10-20T06:41:35.406301957Z","level":"info","source":"worker","message":"worker.beacon-runner.beacon.registered","data":{"session":"4.1"}}

4.2 运行时引擎

⚠️ 官方 help 注明：houdini 运行时直接以宿主身份执行任务、无隔离，仅用于调试，生产禁用。containerd 运行时要求宿主使用 cgroup v2（实测宿主 stat -fc %T /sys/fs/cgroup 返回 cgroup2fs，满足）。

实测：worker 进程树中 containerd 与编排传入的启动参数：

    1 root      0:00 dumb-init /usr/local/bin/entrypoint.sh worker --containerd-dns-proxy-enable --containerd-dns-server=223.5.5.5
    6 root      0:00 /usr/local/concourse/bin/concourse worker --containerd-dns-proxy-enable --containerd-dns-server=223.5.5.5
   25 root      0:00 containerd --address=/run/containerd/containerd.sock --root=/worker-state/containerd --config=/worker-state/containerd.toml --log-level=info

4.3 卷与构建缓存

Baggageclaim 负责资源版本缓存、任务输入/输出卷。--baggageclaim-driver=overlay 生效后，资源缓存以只读层 + 写时复制方式复用。实测 hello-world 首跑 13 秒（含远端版本检查与基础环境首次拉取），第二次构建仅 8 秒，即可观测到缓存命中。fly volumes 可查看卷清单：

fly -t main volumes

实测输出（节选）：

42967b0e-4ab7-4413-be7b-d7b77db2e0b3  worker-01  resource-type  registry-image
090a08de-0a6f-4130-88d5-cc7f5dda5786  worker-01  unknown        n/a

4.4 构建环境 DNS 参数（8.3.1 实测重点）

构建隔离环境的 DNS 默认指向 worker 自身地址（如 10.89.58.4:53），由 worker 内置 DNS 代理转发到上游。相关参数：

⚠️ 实测踩坑（重要）：这两个参数在 8.3.1 的环境变量写法（CONCOURSE_WORKER_CONTAINERD_DNS_PROXY_ENABLE / CONCOURSE_WORKER_CONTAINERD_DNS_SERVER）实测不生效，必须以命令行参数传递。Compose 场景写法：

command: worker --containerd-dns-proxy-enable --containerd-dns-server=223.5.5.5

未启用代理时，构建初始化阶段报 lookup <域名> ... on 10.89.58.4:53: read udp ...: connection refused，image check failed。此外 worker 自带防火墙默认拒绝构建网络入站，代理启用后若仍报 no route to host，需放行 53 端口：

docker exec concourse-831-stack-worker-1 iptables -I INPUT 1 -i concourse0 -p udp --dport 53 -j ACCEPT
docker exec concourse-831-stack-worker-1 iptables -I INPUT 2 -i concourse0 -p tcp --dport 53 -j ACCEPT

4.5 密钥缺失的典型故障

worker 密钥目录缺 tsa_host_key.pub 时启动失败循环重启，日志（实测原文）：

error: invalid argument for flag `--tsa-public-key' (expected flag.AuthorizedKeys): failed to read authorized keys: open /concourse-keys/tsa_host_key.pub: no such file or directory

处理：将 web 侧 tsa_host_key.pub 拷入 worker 密钥目录后重建 worker 服务。

4.6 Worker 运行时环境核对

docker exec concourse-831-stack-worker-1 env | grep CONCOURSE_ | sort

实测输出：

CONCOURSE_BAGGAGECLAIM_DRIVER=overlay
CONCOURSE_NAME=worker-01
CONCOURSE_RUNTIME=containerd
CONCOURSE_TSA_HOST=web:2222
CONCOURSE_TSA_PUBLIC_KEY=/concourse-keys/tsa_host_key.pub
CONCOURSE_TSA_WORKER_PRIVATE_KEY=/concourse-keys/worker_key
CONCOURSE_WORK_DIR=/worker-state
CONCOURSE_WORKER_WORK_DIR=/worker-state

五、常用参数速查表

六、参数修改与生效方式

1. web 参数变更：修改编排文件中的环境变量后重建服务即可，流水线与构建历史在 PostgreSQL 中不受影响：

   cd /opt/concourse && docker compose up -d web
   

2. worker 参数变更：重建 worker 服务后需等待重新注册（约数秒），期间队列中的构建会等待 worker 上线：

   docker compose up -d worker && fly -t main workers
   

3. 密钥轮换：替换密钥文件后 web 与 worker 需同时重建；worker 公钥列表支持多行，可实现滚动换钥。
4. 验证生效：/api/v1/info（web 侧）、fly workers（worker 侧）、env | grep CONCOURSE_（进程内环境）三层核对。

七、本系列篇目

• 《Concourse 8.3.1 介绍与选型指南》
• 《Concourse 8.3.1 Docker Compose 部署指南》
• 《Concourse 8.3.1 配置参数详解》（本篇）
• 《Concourse 8.3.1 常用 CLI 命令详解》