Traefik 证书配置完全指南：用户自定义证书、证书存储与默认证书（Certificates Stores）

Traefik 证书配置完全指南：用户自定义证书、证书存储与默认证书（Certificates & Stores）

【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik

本篇技术指南围绕 Traefik（云原生应用代理）动态配置体系中的 TLS 证书模块展开，系统讲解tls.certificates与tls.stores两大配置区的设计初衷、字段语义与使用限制。你将掌握如何在不重启、不中断服务的前提下为入口点动态加载/卸载用户自备证书，理解 Traefik 基于 SNI 选择证书的内部机制、默认证书与 ACME 默认证书的区别及优先级，并能在 Docker、Swarm、Kubernetes 等典型场景中正确落地证书配置。全文以 docs/content/reference/routing-configuration/http/tls/tls-certificates.md 为主线，并结合仓库中pkg/tls的真实实现代码印证底层原理。

前置认知：路由器如何进入 HTTPS 通道

Traefik 本身并不区分 HTTP 与 HTTPS 入口点，是否启用 TLS 取决于路由器（Router）定义中是否携带tls字段。文档明确给出约定：

当路由器需要处理 HTTPS 流量时，应在路由器定义中用tls字段予以声明。

只有带tls字段的 HTTP 路由才会参与 TLS 握手阶段的证书协商；tls字段可以与tls-options.md（TLS 选项，如最低版本、密码套件、SNI 严格校验等）关联，决定握手细节。也就是说，证书的“存储与选择”和“握手行为”虽然分属tls.stores/tls.certificates与tls.options两套配置，但最终都在 TLS 握手中协同生效。

Certificates Definition：证书的两种来源

在 Traefik 中，一份证书指一对证书文件（certFile）与私钥文件（keyFile）。证书配置层面存在两条供给路径：

自动化签发的完整流程不在本文展开，它归属于 ACME 解析器体系，详见 docs/content/reference/install-configuration/tls/certificate-resolvers/acme.md。本文重点剖析用户自定义这条路径。

用户自定义证书：动态配置语法

用户自定义证书的最大特点是运行时热更新——即使 Traefik 已经启动，也可以随时把证书定义加入动态配置的tls.certificates段，从而动态添加/移除证书，无需重启进程。文档给出的结构化配置如下：

tls: certificates: - certFile: /path/to/domain.cert keyFile: /path/to/domain.key - certFile: /path/to/other-domain.cert keyFile: /path/to/other-domain.key

[[tls.certificates]] certFile = "/path/to/domain.cert" keyFile = "/path/to/domain.key" [[tls.certificates]] certFile = "/path/to/other-domain.cert" keyFile = "/path/to/other-domain.key"

证书字段的源码级细节：路径还是内联内容？

certFile/keyFile对应的 Go 类型定义在 pkg/tls/certificate.go：

// Certificate holds a SSL cert/key pair // Certs and Key could be either a file path, or the file content itself. type Certificate struct { CertFile types.FileOrContent `json:"certFile,omitempty" toml:"certFile,omitempty" yaml:"certFile,omitempty"` KeyFile types.FileOrContent `json:"keyFile,omitempty" toml:"keyFile,omitempty" yaml:"keyFile,omitempty" loggable:"false"` }

从源码注释与字段声明可以确认两个实用细节：

1. FileOrContent双重语义：CertFile/KeyFile既可以填写本地文件路径，也可以直接内联 PEM 内容（实现见 pkg/tls/certificate.go 的FileOrContent.Read()：先尝试按路径os.ReadFile，路径不存在时把字符串本身当作内容读取）。
2. 私钥不进日志：KeyFile字段标记了loggable:"false"，而CertFile提供了GetTruncatedCertificateName()方法对超长 PEM 内容做截断，避免敏感信息与超长内容污染日志。

最终加载时，Certificate.GetCertificate() 读取两者内容并调用 Go 标准库crypto/tls的tls.X509KeyPair(certContent, keyContent)完成 PEM 解析与配对校验——因此证书与私钥必须匹配、格式必须为可被标准库解析的 PEM，否则该证书会被丢弃并在日志中记录错误（Certificates.GetCertificates() 对单个失败证书只跳过、不阻塞整批加载）。

提供方式的限制：File provider 与 Kubernetes Secret

文档特别标注了一条Restriction（限制），需要读者特别注意：

在上面的例子中，我们使用了 File provider 来处理这些定义。它是配置证书（以及 options、stores）的唯一可用方法。而在 Kubernetes 中，证书必须（且只能）通过 Secrets 提供。

也就是说：

• 无论你使用 Docker、Swarm、Consul、etcd 还是其他 Provider 作主数据源，tls.certificates/tls.stores这类敏感密钥型动态配置只能经由 File provider（可参考 file provider 文档）写入动态配置——逻辑上保证密钥数据只存在于本地方可审计的路径中；
• Kubernetes 场景下证书来源被统一收口到Secrets，由 kubernetes-crd provider 与 TLSStore 资源协作完成装载，不直接书写certFile。

Certificate selection (SNI)：握手阶段如何挑选证书

TLS 握手中，服务端在看到 HTTP 内容之前就必须决定向客户端出示哪张证书。Traefik 的策略是：

Traefik 依据客户端在 ClientHello 中发送的Server Name Indication (SNI)来选择握手时出示的证书。由于 HTTP 路由规则（例如Host()）在 TLS 建立之后才被求值，因此它们不会影响证书选择。

对应源码位于 pkg/tls/certificate_store.go 的GetBestCertificate(clientHello *tls.ClientHelloInfo)，其核心逻辑可以概括为：

1. 归一化 SNI：对clientHello.ServerName做小写化与去空白；若客户端完全未携带 SNI，则退而尝试用本地连接的对端地址作匹配键（certificate_store.go）。
2. 命中缓存优先：证书匹配结果会被缓存（默认 1 小时过期，见NewCertificateStore），同一 serverName 的后续握手直接复用，避免每次握手重复遍历。
3. 精确匹配 + 单层通配：遍历动态证书时，先比较证书 SAN 域名与 serverName 是否完全相等；否则把 serverName 的第一个标签替换为*再做匹配（matchDomain，certificate_store.go）——这意味着*.example.com能覆盖api.example.com，但不匹配多层子域a.api.example.com，与浏览器通配证书约定一致。
4. 遍历有序性：证书以“去重排序后的 SAN 列表用逗号连接”为键存储于DynamicCerts映射，遍历时按键逆序，保证匹配行为确定。

每张证书参与匹配的“身份集合”由parseCertificate提取：Subject 的 CommonName、全部 DNSName SAN 与 IP SAN 统一小写化后构成匹配域（certificate_store.go）。换句话说，一张证书能否被某域名命中，取决于证书自身携带的 CN/DNS SAN/IP SAN，而不是配置文件里写了什么名字。

Strict SNI Checking：严格模式与默认证书回退

默认情况下：

若客户端未发送 SNI，或没有任何证书能匹配请求的服务器名，Traefik 会回退使用 TLS Store 中配置的默认证书，该证书仅在有配置时存在。

如果你希望拒绝这类连接（而不是默默回退到默认证书），可以在 TLS Options 中开启sniStrict（严格 SNI 校验）。从 pkg/tls/tlsmanager.go 的配置装配可见，sniStrict取自 TLS Options 的布尔字段，并直接参与握手回调逻辑——开启后，当GetBestCertificate无法返回匹配证书且无默认证书兜底路径可用时，握手即被终止。适合多租户、证书白名单严控等场景。

Certificates Stores：证书存储的真相

在 Traefik 中，证书并非平铺存放，而是按证书存储（Certificate Store）分组。理解存储模型需要把握以下要点。

全局唯一：default store

文档给出的第一条Restriction信息量很大：

除默认存储（名为default）之外的任何 store 定义都会被忽略，因此全局仅存在一个 TLS 存储。

这也解释了为什么你从未见过多 store 的生产配置：虽然语法上tls.stores支持任意键名，Traefik 只会真正维护名为default的那一个。事实上从数据结构看，Store 本身只承担两类职责——承载默认证书、以及承载 ACME 默认证书的解析意图（见 pkg/tls/tls.go）：

type Store struct { DefaultCertificate *Certificate `json:"defaultCertificate,omitempty" ...` DefaultGeneratedCert *GeneratedCert `json:"defaultGeneratedCert,omitempty" ...` }

为证书指定归属（语法上）

在tls.certificates段中，你可以通过stores列表声明证书“存储到哪里”：

tls: certificates: - certFile: /path/to/domain.cert keyFile: /path/to/domain.key stores: - default # Note that since no store is defined, # the certificate below will be stored in the `default` store. - certFile: /path/to/other-domain.cert keyFile: /path/to/other-domain.key

[[tls.certificates]] certFile = "/path/to/domain.cert" keyFile = "/path/to/domain.key" stores = ["default"] [[tls.certificates]] # Note that since no store is defined, # the certificate below will be stored in the `default` store. certFile = "/path/to/other-domain.cert" keyFile = "/path/to/other-domain.key"

紧接着文档又给出第二条Restriction，直接挑明了该字段的现实地位：

stores列表实际上会被忽略，并自动被设置为["default"]。

因此实践中可以有两种等价写法——显式写stores: ["default"]，或者干脆省略；最终效果相同：全部进入全局唯一defaultstore。对应数据结构为CertAndStores（pkg/tls/tls.go），其中Stores []string仅作配置面占位。运行期证书去重则发生在 certificate_store.go 的appendCertificate：同一 store 内若出现 SAN 键完全相同的证书，后者会被跳过并记录 debug 日志。

各 Provider 下如何实际“启用 TLS”并挂载这些证书，文档给出了逐场景示例锚点：

• Docker：启用 TLS
• Swarm：启用 TLS
• Kubernetes：启用 TLS

Default Certificate：显式默认证书与内建回退

对于无 SNI或SNI 无任何证书命中的连接，Traefik 需要一个“最后防线”证书。此时可通过tls.stores.default.defaultCertificate显式指定：

tls: stores: default: defaultCertificate: certFile: path/to/cert.crt keyFile: path/to/cert.key

[tls.stores] [tls.stores.default] [tls.stores.default.defaultCertificate] certFile = "path/to/cert.crt" keyFile = "path/to/cert.key"

文档特别说明：

如果未提供defaultCertificate，Traefik 将使用其自动生成的那张证书。

这段回退链与 pkg/tls/tlsmanager.go 中buildDefaultCertificate的实现相呼应：显式配置的默认证书会被读取解析、注册到证书存储，甚至为它装配 OCSP 装订（OCSP Stapling）；一旦读取/解析失败或压根未配置，则落到 Traefik 进程内自签/自生成的默认证书，保证任何情况下握手都有证书可用。需要留意的是，由于兜底证书是自动生成的，客户端通常会看到不受信任的证书告警——因此生产环境建议要么显式配置可信默认证书，要么用下面介绍的 ACME 默认证书方案。

ACME Default Certificate：让解析器代劳默认证书

除了静态指定一张默认证书，你还可以让 Traefik 通过 ACME 解析器（如 Let's Encrypt）动态取得一张默认证书，并把解析意图写进 TLS store：

tls: stores: default: defaultGeneratedCert: resolver: myresolver domain: main: example.org sans: - foo.example.org - bar.example.org

[tls.stores] [tls.stores.default.defaultGeneratedCert] resolver = "myresolver" [tls.stores.default.defaultGeneratedCert.domain] main = "example.org" sans = ["foo.example.org", "bar.example.org"]

同样地，在 Docker/Swarm 的Labels或 Consul 等 Provider 的Tags中，可以按点分键名书写同一份意图：

labels: - "traefik.tls.stores.default.defaultgeneratedcert.resolver=myresolver" - "traefik.tls.stores.default.defaultgeneratedcert.domain.main=example.org" - "traefik.tls.stores.default.defaultgeneratedcert.domain.sans=foo.example.org, bar.example.org"

{ "Name": "default", "Tags": [ "traefik.tls.stores.default.defaultgeneratedcert.resolver=myresolver", "traefik.tls.stores.default.defaultgeneratedcert.domain.main=example.org", "traefik.tls.stores.default.defaultgeneratedcert.domain.sans=foo.example.org, bar.example.org" ] }

三个关键字段

从类型定义可见其落点（pkg/tls/tls.go）：

type GeneratedCert struct { // Resolver is the name of the resolver that will be used to issue the DefaultCertificate. Resolver string `json:"resolver,omitempty" ...` // Domain is the domain definition for the DefaultCertificate. Domain *types.Domain `json:"domain,omitempty" ...` }

优先级：defaultGeneratedCert 高于 ACME 默认证书

这里有一处文档反复强调、容易踩坑的优先级规则：

defaultGeneratedCert的定义优先于 ACME 默认证书的配置。

结合 tlsmanager.go 中的默认证书装配顺序可以还原完整逻辑：若DefaultGeneratedCert非空且同时具备resolver与有效domain，Traefik 会先尝试经由 ACME 管理器按main/sans取回/签发证书；域非法或解析器取不到证书时，才回退到进程内生成的默认证书。也就是说，一旦你在 store 里写了defaultGeneratedCert，它会取代“解析器在默认规则下顺手产出的 ACME 默认证书”成为首选回退证书；而显式defaultCertificate属于另一条静态路径。三者的完整取舍关系为：显式默认证书 / ACME 默认证书 →defaultGeneratedCert所指定的动态签发结果 → 进程内自生成证书。

实战小结与配置自查清单

归纳本文涉及的全部事实，可作为排查 TLS 证书问题的速查表：

• 路由器须声明tls字段才会进入 HTTPS/证书协商；证书选择只看SNI，Host()等 HTTP 规则在握手后才生效，无法参与选证。
• 用户自定义证书写在动态配置的tls.certificates，支持热增/热删；certFile/keyFile既可以是路径也可以是内联 PEM，但私钥永不进日志。
• 证书定义（含 options、stores）只能通过 file provider 提供；Kubernetes 中必须经由 Secrets，参见 kubernetes-crd provider。
• 全局只有一个defaultstore；stores字段会被忽略并强制为["default"]。
• 无 SNI / 无匹配时默认回退到默认证书；需要严格拒绝时在 TLS Options 中开启sniStrict。
• 默认证书可用静态defaultCertificate指定，否则落到 Traefik 自生成证书；用defaultGeneratedCert可把默认证书交给 ACME 解析器签发，且其优先级高于解析器自身的 ACME 默认证书。
• 证书匹配以证书实体的 CN/DNS SAN/IP SAN 为准，支持单层*通配，与浏览器通配约定一致。

如需深入自动化签发与校验体系，可继续阅读 ACME 解析器文档及 TLS 选项相关章节，完整源码可回溯 pkg/tls/tls.go、pkg/tls/certificate.go、pkg/tls/certificate_store.go 与 pkg/tls/tlsmanager.go。

【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik