Traefik File Provider 动态路由配置全解析用 YAML/TOML 声明 Router、Service、Middleware 与 TLS【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik导读File Provider 是 TraefikThe Cloud Native Application Proxy中最灵活、最基础的动态配置提供方式它不依赖任何外部服务发现机制而是直接读取你手动维护的 YAML 或 TOML 文件按需声明 HTTP/TCP/UDP 路由、负载均衡服务、中间件与各类 TLS 资源并通过文件系统监听实现配置热更新。阅读本文后你将掌握 file provider 的启用方式单文件/目录 热更新、完整的路由配置字段语义、file跨 Provider 资源引用规则以及用 Go 模板自动生成大规模重复配置段落的进阶技巧。本文对应仓库参考页routing-configuration/other-providers/file.md 与 install-configuration/providers/others/file.md源码实现见 pkg/provider/file/file.go。File Provider 在 Traefik 中的定位在 Traefik 的双层配置模型里providers.file负责提供动态配置dynamic configuration——它既可以指向单个文件也可以指向一个目录目录会被递归扫描且支持与文件一样的模板渲染能力。与 Docker、Kubernetes CRD 等自动发现型Provider 不同file provider不会自动发现任何服务每一个 router、service、middleware 与 TLS 资源都必须显式书写在配置文件中详见本文配置选项部分。在实际部署中file provider 最常见的用法是复用公共元素例如把 IP 白名单allowlist、Basic Auth 这类与业务服务无关的通用中间件统一写在一个文件里再被 Docker、K8s 等其他 Provider 中的 router 引用避免在每套业务配置里重复声明。File provider 自身的启用选项filename、directory、watch、debugLogGeneratedTemplate等属于静态配置需要在 Traefik 主配置文件或命令行参数中设置详见 file provider 安装配置。官方文档中大量功能的配置示例也正是以 file provider 的格式给出的它是理解 Traefik 全部动态配置能力的最佳入口。启用 File Provider单文件还是目录方式一指定单个配置文件filename在静态配置中通过providers.file.filename指向一个具体的动态配置文件# 静态配置如 traefik.yml providers: file: filename: /etc/traefik/dynamic.yml等价 TOML 与 CLI 写法[providers.file] filename /etc/traefik/dynamic.toml--providers.file.filename/etc/traefik/dynamic.yml方式二指定配置目录directory推荐当希望把动态配置拆分到多个文件时使用directory并配合watch开启热更新providers: file: directory: /etc/traefik/dynamic watch: true[providers.file] directory /etc/traefik/dynamic watch true--providers.file.directory/etc/traefik/dynamic --providers.file.watchtrue从 pkg/provider/file/file.go 的 Provider 结构与SetDefaults可以看到Filename与Directory是互斥的两个字段Watch的默认值为truebuildConfiguration中若两者都为空会直接报错neither filename nor directory is defined。directory模式下 Traefik 会递归收集目录下的配置文件。从源码collectFileConfigsfile.go可以确认如下行为细节子目录会被递归遍历prefix用于保留相对目录层级仅支持.toml、.yaml、.yml扩展名其余文件一律跳过见isFileSupportedfile.go目录下每个文件被解析为一个独立的dynamic.Configuration最终通过provider.Merge(..., ResourceStrategySkipDuplicates)合并为一份完整配置file.go。于是你可以把不同关注点拆到不同文件例如/etc/traefik/dynamic/http.yml放路由规则/etc/traefik/dynamic/tls.yml放证书# /etc/traefik/dynamic/http.yml http: routers: app: rule: Host(example.com) service: app services: app: loadBalancer: servers: - url: http://127.0.0.1:8080# /etc/traefik/dynamic/tls.yml tls: certificates: - certFile: /certs/example.crt keyFile: /certs/example.key热更新机制与文件监听局限当watch: true默认开启file provider 会为目录或文件注册文件系统监听。源码中Provide会分别把Directory下的每个受支持文件、或Filename所在目录与文件本身加入监听队列file.go事件到达后重新构建并下发配置。从 install-configuration 的 file 文档 的Limitations一节要特别注意Traefik 依赖 fsnotify 获取文件系统事件因此在 Docker / Kubernetes 等容器场景中如果使用挂载或绑定bound文件系统宿主文件被改名/替换可能导致容器内文件系统事件丢失配置不再更新。规避建议将 Traefik 的directory配置指向父目录挂载/绑定该父目录而不是单个文件避免单文件链接被替换后失联。此外Provide中还存在一个 SIGHUP 信号处理分支收到 SIGHUP 即重新加载配置file.go可用于手动触发重载。跨 Provider 引用file后缀file provider 声明的 middleware、service、TLS option 等资源是全局可用的file provider 自己的 router 可以直接引用其他 Provider 的 router 也能引用但必须带上file后缀。例如在 Docker 的标签中引用 file provider 声明的中间件要写成secure-headersfile。这条file命名规则同样适用于同一文件内部 router 引用其他文件里的 service/中间件时的语义Traefik 内部通过按切分资源名来区分 provider 归属与资源名参见 pkg/server/router/router.go 等处的strings.Split(routerName, )。注意资源名本身不允许包含字符否则会被当作分隔符而产生歧义。HTTP 层路由配置下面展示 HTTP 层四类资源routers / services / middlewares / serversTransports的声明位置与完整字段。本节示例字段路径使用 YAML 风格若使用 TOML请改用等价的表/数组语法例如[http.routers.router_name]与[[http.services.service_name.loadBalancer.servers]]。配置示例一启用 file provider 并暴露一个 HTTP 服务声明在websecure入口点监听example.com、启用 TLS 并把流量转发到127.0.0.1:8080的完整链路http: routers: app: rule: Host(example.com) entryPoints: - websecure service: app tls: {} services: app: loadBalancer: servers: - url: http://127.0.0.1:8080[http.routers.app] rule Host(example.com) entryPoints [websecure] service app [http.routers.app.tls] [http.services.app.loadBalancer] [[http.services.app.loadBalancer.servers]] url http://127.0.0.1:8080配置示例二声明多个 Router 与 Service每个 router 都要显式绑定处理其匹配请求的 servicehttp: routers: app: rule: Host(example-a.com) service: app admin: rule: Host(example-b.com) service: admin services: app: loadBalancer: servers: - url: http://127.0.0.1:8000 admin: loadBalancer: servers: - url: http://127.0.0.1:9000[http.routers.app] rule Host(example-a.com) service app [http.routers.admin] rule Host(example-b.com) service admin [http.services.app.loadBalancer] [[http.services.app.loadBalancer.servers]] url http://127.0.0.1:8000 [http.services.admin.loadBalancer] [[http.services.admin.loadBalancer.servers]] url http://127.0.0.1:9000配置示例三声明并引用 Middlewares 与 TLS OptionsFile provider 声明的中间件既可供 file provider 自身 router 使用也可被其他 Provider 的 router 通过file后缀引用http: routers: app: rule: Host(secure.example.com) entryPoints: - websecure middlewares: - secure-headers service: app tls: options: modern middlewares: secure-headers: headers: stsSeconds: 31536000 forceSTSHeader: true services: app: loadBalancer: servers: - url: http://127.0.0.1:8080 tls: options: modern: minVersion: VersionTLS12 sniStrict: true[http.routers.app] rule Host(secure.example.com) entryPoints [websecure] middlewares [secure-headers] service app [http.routers.app.tls] options modern [http.middlewares.secure-headers.headers] stsSeconds 31536000 forceSTSHeader true [http.services.app.loadBalancer] [[http.services.app.loadBalancer.servers]] url http://127.0.0.1:8080 [tls.options.modern] minVersion VersionTLS12 sniStrict trueHTTP Routershttp.routers.router_name⚠️ 命名约束router 名称router_name中不允许出现字符。字段说明取值示例http.routers.router_name.rule路由匹配规则详见 rules-and-priorityHost(example.com)http.routers.router_name.ruleSyntax按 router 指定规则解析语法。已废弃将在下一个大版本移除v3http.routers.router_name.entryPoints[n]关联的入口点详见 entrypointswebsecurehttp.routers.router_name.middlewares[n]引用中间件可用namefile跨 Provider详见 middlewares overviewsecure-headershttp.routers.router_name.service该 router 绑定的服务详见 serviceapphttp.routers.router_name.parentRefs[n]父级 router 引用多层路由详见 multi-layer-routingparent-routerfilehttp.routers.router_name.tls启用/配置 TLS详见 TLS overview{}http.routers.router_name.tls.certResolver指定 ACME 证书解析器详见 certificate-resolversmyresolverhttp.routers.router_name.tls.domains[n].mainACME 证书主域名详见 ACME domainexample.orghttp.routers.router_name.tls.domains[n].sans[n]SAN 附加域名www.example.orghttp.routers.router_name.tls.options引用的 TLS options详见 tls-optionsmodernhttp.routers.router_name.observability.accessLogs是否对该 router 记录访问日志truehttp.routers.router_name.observability.metrics是否对该 router 采集指标truehttp.routers.router_name.observability.tracing是否对该 router 启用链路追踪truehttp.routers.router_name.observability.traceVerbosity追踪采样详细程度详见 observabilityminimalhttp.routers.router_name.priority路由优先级详见 priority 计算42HTTP Serviceshttp.services.service_name⚠️ 命名约束service 名称service_name中不允许出现。字段说明取值示例http.services.service_name.loadBalancer.servers[n].url后端服务器地址详见 servershttp://127.0.0.1:8080http.services.service_name.loadBalancer.servers[n].weight负载权重1http.services.service_name.loadBalancer.servers[n].preservePath是否保留请求路径truehttp.services.service_name.loadBalancer.strategy负载均衡策略如wrr加权轮询、rr、p2c详见 load-balancing-strategieswrrhttp.services.service_name.loadBalancer.passHostHeader是否把原始 Host 头传给后端truehttp.services.service_name.loadBalancer.healthCheck.*主动健康检查详见 health-checkpath: /healthhttp.services.service_name.loadBalancer.passiveHealthCheck.*被动健康检查熔断详见 passive-health-checkmaxFailedAttempts: 3http.services.service_name.loadBalancer.sticky.cookie.*会话粘性Cookie详见 sticky-sessionsname: app-cookiehttp.services.service_name.loadBalancer.responseForwarding.flushInterval响应刷新间隔100mshttp.services.service_name.loadBalancer.serversTransport连接后端所用的 ServersTransport详见 serverstransportsecure-transporthttp.services.service_name.weighted.services[n].nameWRR 聚合服务中的子服务详见 weighted-round-robinapp-v1http.services.service_name.weighted.services[n].weight子服务权重3http.services.service_name.weighted.sticky.cookie.*加权服务上的粘性 Cookiename: app-cookiehttp.services.service_name.weighted.healthCheck加权服务健康检查{}http.services.service_name.highestRandomWeight.services[n].name最高随机权重策略子服务详见 highest-random-weightapp-v1http.services.service_name.highestRandomWeight.services[n].weight子服务权重3http.services.service_name.highestRandomWeight.healthCheck健康检查{}http.services.service_name.mirroring.service镜像流量的主服务详见 mirroringapp-mainhttp.services.service_name.mirroring.mirrorBody是否镜像请求体truehttp.services.service_name.mirroring.maxBodySize允许镜像的最大请求体字节数1048576http.services.service_name.mirroring.mirrors[n].name被镜像的副服务app-shadowhttp.services.service_name.mirroring.mirrors[n].percent镜像流量比例0-10010http.services.service_name.mirroring.healthCheck镜像服务健康检查{}http.services.service_name.failover.service故障转移主服务详见 failoverapp-mainhttp.services.service_name.failover.fallback兜底服务app-backuphttp.services.service_name.failover.healthCheck健康检查{}HTTP Middlewareshttp.middlewares.middleware_name中间件在http.middlewares.middleware_name下声明每个中间件名对应一种具体类型。例如声明名为add-api的AddPrefix中间件在请求路径前追加/apihttp: middlewares: add-api: addPrefix: prefix: /api等效 TOML 语义为http.middlewares.add-api.addPrefix.prefix /api。全部可用中间件清单见 middlewares overview。⚠️ 命名约束middleware_name不允许含。⚠️ 声明冲突若以同名但参数不同的方式重复声明某个中间件该中间件会声明失败。命名空间共享意味着所有 Providerfile、Docker、K8s 等最终会合并到同一张资源表里重复声明同名中间件是常见错误来源。字段说明取值示例http.middlewares.middleware_name.middleware_type.middleware_option其中middleware_type是中间件类型如addPrefix、headersmiddleware_option是要设置的参数prefix: /apiHTTP ServersTransportshttp.serversTransports.servers_transport_nameServersTransport 用于定义 Traefik 与后端服务器建立连接时的传输层参数TLS、HTTP/2、根证书等。在 file provider 中通常需要将证书等文件内容预读为内联数据源码loadFileConfig中对 HTTP ServersTransports 的Certificates与RootCAs字段做了显式Read()处理file.go。字段说明取值示例http.serversTransports.servers_transport_name.*详见 serverstransportserverName: example.orgTCP 层路由配置File provider 同样支持声明 TCP 的 routers、services、middlewares 与 ServersTransports。TCP Routerstcp.routers.router_name⚠️ 命名约束不允许出现。字段说明取值示例tcp.routers.router_name.entryPoints[n]关联入口点websecuretcp.routers.router_name.ruleTCP 匹配规则详见 TCP rulesHostSNI(example.com)tcp.routers.router_name.ruleSyntax逐 router 指定规则解析语法。已废弃将在下一个大版本移除v3tcp.routers.router_name.middlewares[n]引用 TCP 中间件详见 TCP middlewaresip-allowlisttcp.routers.router_name.service绑定的 TCP 服务详见 TCP servicetcp-apptcp.routers.router_name.tlsTLS 配置详见 TCP TLS{}tcp.routers.router_name.tls.certResolver证书解析器myresolvertcp.routers.router_name.tls.domains[n].main证书主域名example.orgtcp.routers.router_name.tls.domains[n].sans[n]SAN 域名www.example.orgtcp.routers.router_name.tls.options引用的 TLS optionsmoderntcp.routers.router_name.tls.passthrough是否 TLS 透传不解密直接转发truetcp.routers.router_name.priority优先级42TCP Servicestcp.services.service_name⚠️ 命名约束不允许出现。字段说明取值示例tcp.services.service_name.loadBalancer.servers[n].address后端地址详见 TCP servers-load-balancer127.0.0.1:9000tcp.services.service_name.loadBalancer.servers[n].tls连接后端时是否启用 TLStruetcp.services.service_name.loadBalancer.serversTransport使用的 TCP ServersTransport详见 TCP serverstransportsecure-tcptcp.services.service_name.loadBalancer.proxyProtocol.version对后端连接启用 Proxy Protocolv1/v22tcp.services.service_name.loadBalancer.terminationDelay连接终止前的延迟毫秒100tcp.services.service_name.loadBalancer.healthCheck.*TCP 健康检查详见 TCP health-checkinterval: 10stcp.services.service_name.weighted.services[n].nameWRR 子服务详见 TCP weighted-round-robintcp-v1tcp.services.service_name.weighted.services[n].weight子服务权重3tcp.services.service_name.weighted.healthCheck加权服务健康检查{}TCP Middlewarestcp.middlewares.middleware_name例如声明名为limit的InFlightConn限制同时连接数TCP 中间件tcp: middlewares: limit: inFlightConn: amount: 10更多 TCP 中间件见 TCP middlewares overview。命名约束不允许与同名不同参即声明失败的规则与 HTTP 中间件一致。字段说明取值示例tcp.middlewares.middleware_name.middleware_type.middleware_optionmiddleware_type如inFlightConnmiddleware_option为参数amount: 10TCP ServersTransportstcp.serversTransports.servers_transport_name与 HTTP 侧类似TCP ServersTransport 中 TLS 相关的Certificates与RootCAs也会在加载阶段被 file provider 从文件读入内存file.go。字段说明取值示例tcp.serversTransports.servers_transport_name.*详见 TCP serverstransportdialTimeout: 30sUDP 层路由配置File provider 也支持声明 UDP 的 router 与 serviceUDP 不支持中间件。UDP Routersudp.routers.router_name⚠️ 命名约束不允许出现。字段说明取值示例udp.routers.router_name.entryPoints[n]关联入口点详见 UDP entrypointsdnsudp.routers.router_name.service绑定的 UDP 服务dns-serviceUDP Servicesudp.services.service_name⚠️ 命名约束不允许出现。字段说明取值示例udp.services.service_name.loadBalancer.servers[n].address后端地址详见 UDP service127.0.0.1:5353udp.services.service_name.weighted.services[n].nameWRR 子服务dns-v1udp.services.service_name.weighted.services[n].weight子服务权重3TLS 资源配置File provider 可以声明三类 TLS 资源证书certificates、选项options与证书存储stores。Certificatestls.certificates[n]字段说明取值示例tls.certificates[n].certFile证书文件路径详见 tls-certificates/certs/example.crttls.certificates[n].keyFile私钥文件路径/certs/example.keytls.certificates[n].stores[n]该证书要装入的证书存储详见 certificate-storesdefault源码行为提示在 loadFileConfig 中file provider 会对声明的证书、TLS option 的ClientAuth.CAFiles、TLS store 的DefaultCertificate逐一执行文件读取并内联到配置中随后通过flattenCertificates摊平证书列表。因此动态文件里给出的 certFile/keyFile 路径在配置生成阶段即被解析。TLS Optionstls.options.options_name字段说明取值示例tls.options.options_name.minVersion最低 TLS 版本详见 tls-optionsVersionTLS12tls.options.options_name.maxVersion最高 TLS 版本VersionTLS13tls.options.options_name.cipherSuites[n]允许的密码套件TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256tls.options.options_name.curvePreferences[n]椭圆曲线偏好CurveP256tls.options.options_name.clientAuth.caFiles[n]mTLS 客户端 CA 证书详见 client-authentication/certs/client-ca.crttls.options.options_name.clientAuth.clientAuthType客户端认证模式RequireAndVerifyClientCerttls.options.options_name.sniStrict严格 SNI 校验关闭默认证书兜底详见 strict-SNItruetls.options.options_name.alpnProtocols[n]允许的 ALPN 协议h2tls.options.options_name.disableSessionTickets禁用 TLS session ticketstruetls.options.options_name.preferServerCipherSuites已废弃该选项已不生效会被 Go TLS 栈忽略trueTLS Storestls.stores.store_name字段说明取值示例tls.stores.store_name.defaultCertificate.certFile默认证书文件详见 default-certificate/certs/default.crttls.stores.store_name.defaultCertificate.keyFile默认证书私钥/certs/default.keytls.stores.store_name.defaultGeneratedCert.resolver用 ACME 生成默认证书详见 ACME-default-certificatemyresolvertls.stores.store_name.defaultGeneratedCert.domain.main生成证书主域名example.orgtls.stores.store_name.defaultGeneratedCert.domain.sans[n]SAN 域名www.example.org进阶用 Go Templating 批量生成重复配置当配置中包含大量结构相似的 router、service 或证书时file provider 支持Go 模板渲染模板内可使用 sprig 的全部函数以及env读取环境变量等能力。仓库源码中CreateConfiguration明确构建了基于text/template的渲染管线并注册sprig.TxtFuncMap()、normalize、split等函数file.go模板渲染结果最终仍按 YAML/TOML 解码为dynamic.Configuration。⚠️ 重要限制Go Templating只对独立的动态配置文件生效在 Traefik 主静态配置文件中不进行模板渲染。若希望观察模板渲染过程可开启providers.file.debugLogGeneratedTemplate: true它会把模板原文与渲染结果以 debug 级别打印到日志见CreateConfiguration中DebugLogGeneratedTemplate分支file.go。YAML 模板示例循环生成 100 个 HTTP/TCP 路由与 10 张证书http: routers: {{range $i, $e : until 100 }} router{{ $e }}-{{ env MY_ENV_VAR }}: # ... {{end}} services: {{range $i, $e : until 100 }} application{{ $e }}: # ... {{end}} tcp: routers: {{range $i, $e : until 100 }} router{{ $e }}: # ... {{end}} services: {{range $i, $e : until 100 }} service{{ $e }}: # ... {{end}} tls: certificates: {{ range $i, $e : until 10 }} - certFile: /etc/traefik/cert-{{ $e }}.pem keyFile: /etc/traefik/cert-{{ $e }}.key stores: - my-store-foo-{{ $e }} - my-store-bar-{{ $e }} {{end}}TOML 模板示例TOML 文件同样支持模板语法。注意在 TOML 中数组表如[[tls.certificates]]需要放在 range 循环体内逐条生成# template-rules.toml [http] [http.routers] {{ range $i, $e : until 100 }} [http.routers.router{{ $e }}-{{ env MY_ENV_VAR }}] # ... {{ end }} [http.services] {{ range $i, $e : until 100 }} [http.services.service{{ $e }}] # ... {{ end }} [tcp] [tcp.routers] {{ range $i, $e : until 100 }} [tcp.routers.router{{ $e }}] # ... {{ end }} [tcp.services] {{ range $i, $e : until 100 }} [tcp.services.service{{ $e }}] # ... {{ end }} {{ range $i, $e : until 10 }} [[tls.certificates]] certFile /etc/traefik/cert-{{ $e }}.pem keyFile /etc/traefik/cert-{{ $e }}.key stores [my-store-foo-{{ $e }}, my-store-bar-{{ $e }}] {{ end }} [tls.options] {{ range $i, $e : until 10 }} [tls.options.TLS{{ $e }}] # ... {{ end }}上面的例子利用until 100生成编号为 0–99 的资源再配合env MY_ENV_VAR把环境变量嵌入资源名如router42-production适合对大量规则做脚本化模板化管理的场景。配置校验建议与常见误区是保留字符router / service / middleware 的名称都不允许含因为用作资源名 Provider 名如secure-headersfile的分隔符。同源声明冲突同一个名字在不同参数下重复声明无论在同一文件还是跨 Provider都会导致该资源声明失败改名前需全局排查。目录监听注意挂载方式容器环境请挂载父目录并让 Traefik 监听directory避免单文件绑定被替换后 fsnotify 收不到事件。ruleSyntax已废弃HTTP 与 TCP router 上的ruleSyntax字段均标注为 deprecated将在下一个大版本移除新配置不应再使用。preferServerCipherSuites已失效Go TLS 栈已忽略该选项配置后不会产生实际效果。模板与静态配置文件互斥Go Templating 只在动态配置文件filename/directory 指向的文件中生效不会渲染主静态配置。在仓库中可进一步研读 pkg/provider/file/file_test.go 了解各字段解析与目录合并逻辑的测试用例参考 http/load-balancing/service.md 与 http/routing/rules-and-priority.md 掌握 rule 语法、负载均衡策略与优先级规则的完整定义。【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考