Coder 2.37.7 配置参数详解

目标：把 coder server 的配置体系讲透——参数从哪来、怎么查、YAML 长什么样、环境变量怎么映射、三者优先级如何、生产环境怎么写。本文所有行数、参数个数、优先级结论均来自 2026-10-27 至 2026-10-28 的实测；安装步骤见《Ubuntu 22.04 安装 Coder 2.37.7 指南》，产品背景见《Coder 介绍与选型指南》。

一、环境信息

• Coder 版本：v2.37.7+b40ba6e
• 操作系统：Ubuntu 22.04.5 LTS，x86_64
• 数据库：PostgreSQL 16.15（同机）
• 配置文件：/etc/coder.d/coder.env（环境变量）、/etc/coder.d/coder.yaml（YAML，实验特性）
• 实测规模：coder server --help 输出 1002 行，含 207 个选项、35 个分组；coder server --write-config 输出 1192 行 YAML

二、配置从哪来

Coder 服务端的配置有四个来源，最终合并成一个运行配置：

三个「显式」来源的优先级实测为 YAML < 环境变量 < 命令行参数（详见第七节）。这与常见的「配置文件优先」直觉相反，排障时必须先确认是不是命令行参数把文件值覆盖了。

2.1 YAML 的实验状态

使用 -c 加载 YAML 时，进程启动会打印：

WARN: YAML support is experimental and offers no compatibility guarantees.

官方明确不保证跨版本兼容，因此建议：

• 生产以环境变量为主，YAML 只承载环境变量不便表达的结构化配置；
• 固定版本升级，升级前对比新版本的 --write-config 输出；
• YAML 文件按 0600 权限保存，避免泄露 OIDC、邮件、模型 API Key 等敏感项。

三、查看与修改配置

3.1 查看全部参数

coder server --help | wc -l
# 1002

coder server --help | grep -c '^\s\+\(-[a-zA-Z], \)\?--'
# 207

参数按功能分成 35 组，组标题形如 NETWORKING / TLS OPTIONS:。帮助文本同时给出参数名、类型、对应环境变量与默认值：

      --http-address string, $CODER_HTTP_ADDRESS (default: 127.0.0.1:3000)
          HTTP bind address of the server. Unset to disable the HTTP endpoint.

3.2 导出当前配置为 YAML

coder server --write-config > /tmp/coder-config.yaml
wc -l /tmp/coder-config.yaml
# 1192

该输出是「当前配置 + 全量注释」的完整样例，最适合作为编写 YAML 的起点。注意它是写到标准输出的，日志也在标准错误，重定向不会混入日志。

3.3 查看每个值的来源

coder server --debug-options

输出三列：Option、Value、Source。Source 取值包括 default、yaml、env、flag，是定位「配置为什么没生效」的最快手段。该命令打印完即退出，不会真正启动服务。

3.4 修改的三种落地方式

# 方式一：临时命令行
coder server --http-address 0.0.0.0:3000 --access-url http://192.168.1.71:3000

# 方式二：systemd 环境变量文件
vi /etc/coder.d/coder.env
systemctl restart coder

# 方式三：YAML + -c
coder server -c /etc/coder.d/coder.yaml

改完必须重启进程才生效；SIGHUP 不会重载配置。

四、参数总览

按 --help 的分组实测统计（括号内为选项数量，合计 207）：

规律：网络、认证、可观测性占了绝大多数；邮件与通知被拆成多层嵌套（EMAIL 与 NOTIFICATIONS/EMAIL 是两套独立配置）；企业版参数在社区版可以设置但不生效。

4.1 最常用参数速查

五、YAML 配置文件实测

5.1 结构与命名

--write-config 生成的是嵌套结构 + 驼峰键名，与命令行参数不是一一对应的「扁平列表」。例如 HTTP 监听地址位于 networking.http.httpAddress，而不是顶层 http_address。

实测顶层键（节选）：

aibridge, aibridgeproxy, ai_gateway, ai_gateway_proxy, retention, networking,
agentFallbackTroubleshootingURL, userQuietHoursSchedule, allowWorkspaceRenames,
autobuildPollInterval, client, cacheDir, introspection, chat, wgtunnelHost,
defaultOAuthRefreshLifetime, defaultTokenLifetime, disableChatSharing,
disableOwnerWorkspaceAccess, disablePathApps, templateBuilder,
disableWorkspaceSharing, email, enableAITasks, oidc, enableSwagger,
ephemeralDeployment, experiments, externalAuthGithubDefaultProviderEnable,
externalAuthProviders, workspace_prebuilds, provisioning,
jobHangDetectorInterval, notifications, pgAuth, pgConnMaxIdle, pgConnMaxOpen,
scimUseLegacy, sshKeygenAlgorithm, supportLinks, telemetry,
termsOfServiceURL, updateCheck

命名并不完全统一：ai_gateway、workspace_prebuilds 是下划线风格，其余多为驼峰。写 YAML 时必须以 --write-config 的实际输出为准，不要凭参数名猜。

5.2 最小可用样例

networking:
  accessURL: http://192.168.1.71:3000
  http:
    httpAddress: 0.0.0.0:3000
  tls:
    enable: false
    minVersion: tls12

introspection:
  logging:
    humanPath: /dev/stdout
    jsonPath: ""
    filter: []
    verbose: false

cacheDir: /var/cache/coder
pgAuth: password
pgConnMaxOpen: 10
pgConnMaxIdle: auto
updateCheck: false
telemetry:
  enable: false

启动：

coder server -c /etc/coder.d/coder.yaml

5.3 实测结论

• 同一份 YAML 中同时设置 accessURL、httpAddress、humanPath 后，--debug-options 的 Source 列分别显示 yaml，说明三项均被正确读取；
• --write-config 本次输出 1192 行，包含大量注释与已废弃的 aibridge.* 键；这些键仍可解析，但新配置应使用 ai_gateway.*；
• 输出中没有出现数据库连接串字段，因此连接凭据仍建议用 CODER_PG_CONNECTION_URL 注入，或在 YAML 中按 schema 手工补充后立即验证；
• YAML 中的数组用 YAML 列表表示（如 filter: []、stunAddresses: 下的多行 -），不是逗号字符串。

5.4 权限与备份

install -m 0600 /dev/null /etc/coder.d/coder.yaml
chown root:root /etc/coder.d/coder.yaml

YAML 可能含 SMTP 密码、OIDC 客户端密钥、模型 API Key，必须 0600；纳入版本管理前先脱敏。

六、环境变量详解

6.1 命名规则

绝大多数参数都有对应的环境变量，规则是 --flag-name → CODER_FLAG_NAME：

例外：数据库连接串的参数名是 --postgres-url，环境变量却是 CODER_PG_CONNECTION_URL，不要写成 CODER_POSTGRES_URL。

6.2 值的写法

• 布尔：true / false（不是 1/0，也不是 yes/no）；
• 时长：Go duration 语法，如 24h、30m、168h0m0s；
• 数组：环境变量用逗号分隔，如 CODER_EXPERIMENTS=example-a,example-b；
• URL：必须带 scheme，含特殊字符的密码需 URL 编码。

6.3 分类速查

七、优先级与 --debug-options 实测

7.1 测试设计

三步叠加，每步都用 coder server --debug-options 查看 Source 列：

1. 仅 YAML：networking.accessURL、networking.http.httpAddress、introspection.logging.humanPath；
2. 再叠加环境变量：CODER_HTTP_ADDRESS=0.0.0.0:3001；
3. 再叠加命令行参数：--http-address 0.0.0.0:3002。

7.2 实测结果

仅 YAML：

Option                                                                  Value Source
"Access URL"                                                            yaml
"HTTP Address"                                                          yaml
"Human Log Location"                                                    yaml

叠加环境变量后：

"HTTP Address"                                                          env

再叠加命令行参数后：

"HTTP Address"                                                          flag
"Config Path"                                                           flag

结论：YAML < 环境变量 < 命令行参数。Config Path 恒为 flag，因为 -c 本身就是命令行参数。

7.3 排障用法

# 快速确认某个值最终来自哪里
coder server --debug-options 2>/dev/null | grep -E 'Access URL|HTTP Address|Postgres|Log'

# 对比“文件里的值”和“实际生效值”
coder server -c /etc/coder.d/coder.yaml --debug-options | grep -E 'yaml|env|flag'

若发现期望是 yaml 却显示 env 或 flag，优先检查 systemd 单元里的 EnvironmentFile 与 ExecStart 是否带了覆盖参数。

八、生产配置模板

8.1 环境变量版（推荐）

/etc/coder.d/coder.env：

CODER_ACCESS_URL=https://coder.example.com
CODER_HTTP_ADDRESS=0.0.0.0:3000
CODER_PG_CONNECTION_URL=postgres://coder:<密码>@127.0.0.1:5432/coder?sslmode=disable
CODER_PG_CONN_MAX_OPEN=20
CODER_PG_CONN_MAX_IDLE=auto
CODER_PROVISIONER_DAEMONS=3
CODER_LOGGING_HUMAN=/dev/stdout
CODER_CACHE_DIRECTORY=/var/cache/coder
CODER_TELEMETRY_ENABLE=false
CODER_UPDATE_CHECK=false

配套 systemd 单元沿用安装篇的加固模板即可，关键是 EnvironmentFile=/etc/coder.d/coder.env 与 Type=notify。

8.2 YAML 版（结构化配置较多时）

networking:
  accessURL: https://coder.example.com
  http:
    httpAddress: 0.0.0.0:3000
    sessionDuration: 24h0m0s
    disablePasswordAuth: true
  wildcardAccessURL: "*.coder.example.com"
  secureAuthCookie: true
  sameSiteAuthCookie: lax
  tls:
    enable: false
    minVersion: tls12
  derp:
    enable: true
    regionName: Coder Embedded Relay

introspection:
  logging:
    humanPath: /dev/stdout
    verbose: false
  prometheus:
    enable: true
    address: 127.0.0.1:2112

pgConnMaxOpen: 20
pgConnMaxIdle: auto
telemetry:
  enable: false
updateCheck: false

⚠️ 注意：上面是「可读性示例」，字段名以你本机 --write-config 输出为准；不同小版本的键名可能调整，加载后用 --debug-options 逐项核对。

8.3 反向代理场景

前置 Nginx/Caddy 终止 TLS 时：

• CODER_ACCESS_URL 写外部 HTTPS 地址，CODER_HTTP_ADDRESS 监听内网；
• 设置 CODER_PROXY_TRUSTED_HEADERS=X-Forwarded-For 与 CODER_PROXY_TRUSTED_ORIGINS=<反代网段>，否则审计日志里的来源 IP 全是反代地址；
• 需要工作区应用子域名时配置 CODER_WILDCARD_ACCESS_URL 与通配证书；
• 若只用子域名访问应用，建议开启 CODER_DISABLE_PATH_APPS=true 降低 XSS 风险。

九、安全相关参数

⚠️ DANGEROUS OPTIONS 分组共 2 项（--allow-workspace-renames、--ephemeral-deployment），帮助文本明确标注了数据丢失风险，改动前先读原文。

十、日志与可观测性

10.1 日志三通道

# 人类可读日志 → journald
CODER_LOGGING_HUMAN=/dev/stdout

# JSON 日志 → 文件，便于采集
CODER_LOGGING_JSON=/var/log/coder/coder.json

# Google Stackdriver 兼容格式
CODER_LOGGING_STACKDRIVER=/var/log/coder/coder.stackdriver

三者可同时开启。CODER_LOGGING_FILTER 用正则过滤 debug 日志，CODER_VERBOSE=true 输出 debug 级别。排障 Terraform 时可临时开启 CODER_ENABLE_TERRAFORM_DEBUG_MODE=true，但日志量会显著增大。

10.2 Prometheus

CODER_PROMETHEUS_ENABLE=true
CODER_PROMETHEUS_ADDRESS=127.0.0.1:2112

指标端点默认只监听回环，抓取端在同机或经反代时保持回环更安全。CODER_PROMETHEUS_COLLECT_DB_METRICS=true 可额外采集数据库指标，CODER_PROMETHEUS_COLLECT_AGENT_STATS=true 采集 agent 维度统计。

10.3 健康检查与剖析

• GET /healthz 返回 OK，适合负载均衡健康探测；
• CODER_PPROF_ENABLE=true + CODER_PPROF_ADDRESS=127.0.0.1:6060 开启 pprof，仅在排障时短时开启；
• 数据库健康检查默认每 10 分钟刷新一次（introspection.healthcheck.refresh）。

十一、FAQ

11.1 改了 YAML 不生效

按第七节顺序排查：--debug-options 看 Source；确认启动命令确实带 -c；确认 systemd 单元没有在 ExecStart 里写死参数覆盖。

11.2 改了 env 不生效

EnvironmentFile 只对 systemd 托管生效，前台手动启动不会读取 /etc/coder.d/coder.env。手动验证时先 set -a; . /etc/coder.d/coder.env; set +a。

11.3 端口改了但浏览器打不开

CODER_HTTP_ADDRESS 只改监听，CODER_ACCESS_URL 决定页面里生成的链接与回连地址。两者必须一起改，且防火墙要放行新端口。

11.4 数据库连接串报错

密码含 @ : / ? # 时先 URL 编码；sslmode=disable 仅限同机或可信内网；连接池上限不要超过 PostgreSQL 的 max_connections。

11.5 YAML 兼容性警告能否消除

不能。2.37.7 中 YAML 被官方标记为实验特性，任何 -c 启动都会打印该警告，只能通过固定版本与回归测试控制风险。

11.6 --write-config 为什么没有数据库连接串

本次 1192 行输出中确实没有该字段（连接串属于敏感项）。数据库地址请用 CODER_PG_CONNECTION_URL 注入；如坚持写在 YAML，需手工补键并用 --debug-options 验证。

11.7 参数太多，如何只保留必要项

最小集：access-url、http-address、postgres-url、log-human、cache-dir。其余按需逐项开启，每加一项都做一次 --debug-options 核对。

11.8 企业版参数设置了会怎样

可以设置，但社区版没有对应授权，功能不会生效。可用 coder features list 查看各项的 ENTITLEMENT 与 ENABLED 状态。

十二、参考链接

• 服务端参数参考：https://coder.com/docs/reference/cli/server
• 配置总览：https://coder.com/docs/admin/configure
• 环境变量参考：https://coder.com/docs/reference/cli/env
• 可观测性：https://coder.com/docs/admin/observability
• GitHub Releases：https://github.com/coder/coder/releases
• 站内：《Coder 介绍与选型指南》、《Ubuntu 22.04 安装 Coder 2.37.7 指南》、《Coder 2.37.7 常用 CLI 与运维命令详解》