TiProxy 配置文件
本文档介绍了与 TiProxy 部署和使用相关的配置参数。关于 TiUP 的拓扑文件配置参数，请参阅 tiproxy-servers 配置参数。
以下是一个配置示例：
[proxy]
addr = "0.0.0.0:6000"
max-connections = 100
[api]
addr = "0.0.0.0:3080"
[ha]
virtual-ip = "10.0.1.10/24"
interface = "eth0"
[security]
[security.cluster-tls]
skip-ca = true
[security.sql-tls]
skip-ca = true
配置 tiproxy.toml 文件
本小节介绍了 TiProxy 的配置参数。
proxy
SQL 端口的配置。
addr
- 默认值：
0.0.0.0:6000 - 支持热加载：否
- SQL 服务的监听地址。格式为
<ip>:<port>。使用 TiUP 或 TiDB Operator 部署 TiProxy 时，此配置项会自动设置。
advertise-addr
- 默认值：
"" - 支持热加载：否
- 指定其他组件连接 TiProxy 时使用的地址，该地址只包含主机名，不包含端口。该地址可能与
addr中的主机名不同。例如，TiProxy 的 TLS 证书中的Subject Alternative Name只包含域名时，其他组件通过 IP 连接 TiProxy 会失败。使用 TiUP 或 TiDB Operator 部署 TiProxy 时，此配置项会自动设置。如果未设置该配置项，将使用该 TiProxy 实例的外部 IP 地址。
graceful-wait-before-shutdown
- 默认值：
0 - 支持热加载：是
- 单位：秒
- 在 TiProxy 关闭时，在
graceful-wait-before-shutdown秒内，HTTP 状态返回不健康，但 SQL 端口仍接受新连接。graceful-wait-before-shutdown秒之后 SQL 端口将拒绝新连接并关闭现有连接。如果客户端和 TiProxy 之间没有其他代理（例如 NLB），建议将这个配置的值设置为0。
graceful-close-conn-timeout
- 默认值：
15 - 支持热加载：是
- 单位：秒
- 在 TiProxy 关闭前，最多等待
graceful-close-conn-timeout秒，连接的当前事务完成后将关闭连接。超时之后 TiProxy 将强制关闭所有连接。graceful-close-conn-timeout发生在graceful-wait-before-shutdown之后。建议将此超时时间设置为长于事务的生命周期。
fail-backend-list 从 v1.3.3 版本开始引入
默认值：
[]支持热加载：是
指定需要从路由中剔除的后端列表。确认某个 TiDB server 发生故障后，可将其加入该列表。TiProxy 会停止向这些后端路由新连接，并迁出其上的现有连接。列表中的每一项可以是以下两种形式之一：
- 后端 Pod 名称，例如
"db-tidb-0" - 后端地址，格式为
<ip>:<port>，例如"10.0.0.10:4000"
- 后端 Pod 名称，例如
如果应用该列表后将没有任何可路由的后端，TiProxy 会忽略该列表，以保证连接请求仍可路由。
failover-timeout 从 v1.3.3 版本开始引入
- 默认值：
60 - 支持热加载：是
- 单位：秒
- 取值范围：
>= 0 - 当后端出现在
fail-backend-list中时，TiProxy 会迁出该后端上的现有连接。如果超过failover-timeout秒后该后端上仍有剩余连接，TiProxy 将强制关闭这些连接。0表示立即强制关闭剩余连接。
max-connections
- 默认值：
0 - 支持热加载：是
- 每个 TiProxy 实例最多可以接受
max-connections个连接。0表示没有限制。
high-memory-usage-reject-threshold 从 v1.3.3 版本开始引入
默认值：
0.9支持热加载：是
取值范围：
[0, 1]当 TiProxy 的内存使用率达到或超过该阈值时，TiProxy 拒绝新连接，同时状态端口会返回不健康状态，已有连接不受影响。如果配置了
ha.virtual-ip，该实例还会释放虚拟 IP。例如，0.9表示内存使用率达到 90% 时，TiProxy 拒绝新连接。0表示不因内存使用率拒绝新连接。如果设置的值大于0且小于0.5，TiProxy 会将其调整为0.5。
conn-buffer-size
- 默认值：
32768 - 支持热加载：是，但只对新连接有效
- 单位：字节
- 取值范围：
[1024, 16777216] - 每个连接的缓冲区大小，读和写分别使用一个缓冲区。它是内存空间和性能之间的平衡，较大的缓冲区可能会有更高的性能，但占用更多内存。当值为
0时，TiProxy 会使用默认大小的缓冲区。
pd-addrs
- 默认值：
127.0.0.1:2379 - 支持热加载：否
- TiProxy 连接的 PD 地址。TiProxy 通过从 PD 获取 TiDB 列表来发现 TiDB 实例。如果使用 TiUP 或 TiDB Operator 部署 TiProxy，则会自动设置此项。
proxy-protocol
- 默认值：
"" - 支持热加载：是，但只对新连接有效
- 可选值：
"","v2" - 在 SQL 端口启用 PROXY 协议。开启 PROXY 协议后能让 TiProxy 透传客户端真实的 IP 地址给 TiDB。
"v2"代表使用 PROXY 协议 v2 版本，""代表不使用 PROXY 协议。在 TiProxy 启用 PROXY 协议后，需要同时在 TiDB 服务器上启用 PROXY 协议。
api
HTTP 网关的配置。
addr
- 默认值：
0.0.0.0:3080 - 支持热加载：否
- API 网关地址。格式为
<ip>:<port>。
proxy-protocol
- 默认值：
"" - 支持热加载：否
- 可选值：
"","v2" - 在端口启用 PROXY 协议。
"v2"代表使用 PROXY 协议 v2 版本，""代表不使用 PROXY 协议。
balance
TiProxy 负载均衡策略的配置。
label-name
- 默认值：
"" - 支持热加载：是
- 指定用于基于标签的负载均衡的标签名。TiProxy 根据该标签名匹配 TiDB server 的标签值，并优先将请求路由到与自身具有相同标签值的 TiDB server。
label-name的默认值为空字符串，表示不使用基于标签的负载均衡。要启用该负载均衡策略，需要将此配置项设置为非空字符串，并配置 TiProxy 的labels和 TiDB 的labels配置项。有关详细信息，请参阅基于标签的负载均衡。
policy
- 默认值：
resource - 支持热加载：是
- 可选值：
resource、location、connection - 指定负载均衡策略。各个可选值的含义请参阅 TiProxy 负载均衡策略。
routing-policy 从 v1.3.3 版本开始引入
默认值：
prefer-idle支持热加载：是
可选值：
prefer-idle、random、idlest指定新连接的路由策略：
prefer-idle：排除需要迁出连接的后端后，在剩余可路由后端中随机选择。适用于大多数场景。random：在可路由的后端中随机选择，其中最空闲的后端被选中的概率略高。适用于新连接创建较为密集的场景。idlest：始终将新连接路由到最空闲的可路由后端。适用于长连接且连接创建不密集的场景。
status 从 v1.3.3 版本开始引入
基于状态的负载均衡配置。
migrations-per-second 从 v1.3.3 版本开始引入
- 默认值：
0 - 支持热加载：是
- 取值范围：
>= 0 - 指定基于状态的负载均衡每秒迁移的连接数。
0表示由 TiProxy 根据当前连接数自动计算迁移速率。当 TiDB server 正在关闭时，可适当增大该值以加快连接迁移。
health 从 v1.3.3 版本开始引入
基于健康度的负载均衡配置。仅当 policy 为 resource 或 location 时生效。
enabled 从 v1.3.3 版本开始引入
- 默认值：
true - 支持热加载：是
- 是否启用基于健康度的负载均衡。
migrations-per-second 从 v1.3.3 版本开始引入
- 默认值：
0 - 支持热加载：是
- 取值范围：
>= 0 - 指定基于健康度的负载均衡每秒迁移的连接数。
0表示由 TiProxy 自动计算迁移速率。
memory 从 v1.3.3 版本开始引入
基于内存的负载均衡配置。仅当 policy 为 resource 或 location 时生效。
enabled 从 v1.3.3 版本开始引入
- 默认值：
true - 支持热加载：是
- 是否启用基于内存的负载均衡。
migrations-per-second 从 v1.3.3 版本开始引入
- 默认值：
0 - 支持热加载：是
- 取值范围：
>= 0 - 指定基于内存的负载均衡每秒迁移的连接数。
0表示由 TiProxy 自动计算迁移速率。
cpu 从 v1.3.3 版本开始引入
基于 CPU 的负载均衡配置。仅当 policy 为 resource 或 location 时生效。
enabled 从 v1.3.3 版本开始引入
- 默认值：
true - 支持热加载：是
- 是否启用基于 CPU 的负载均衡。
migrations-per-second 从 v1.3.3 版本开始引入
- 默认值：
0 - 支持热加载：是
- 取值范围：
>= 0 - 指定基于 CPU 的负载均衡每秒迁移的连接数。
0表示由 TiProxy 自动计算迁移速率。不建议在 CPU 热点不稳定时将该值设置得过大，以免引起连接来回迁移。
min-balance-usage 从 v1.3.3 版本开始引入
- 默认值：
0 - 支持热加载：是
- 取值范围：
[0, 1] - 当源后端的 CPU 使用率低于该阈值时，不触发基于 CPU 的连接迁移。例如，
0.2表示源后端 CPU 使用率低于 20% 时不迁移。
max-usage-gap 从 v1.3.3 版本开始引入
- 默认值：
1 - 支持热加载：是
- 取值范围：
0或[0.05, 1] - 指定触发基于 CPU 的连接迁移所需的最小 CPU 使用率差值。当源后端与目标后端的 CPU 使用率差值达到该阈值时触发迁移。例如，
0.1表示差值达到 10% 时即可触发迁移。默认值1表示仅依赖自适应规则判断是否迁移。0表示该参数使用默认值。当需要后端 CPU 使用率更均衡时，可以适当调小该值。
location 从 v1.3.3 版本开始引入
基于地理位置的负载均衡配置。仅当 policy 为 resource 或 location 时生效。
enabled 从 v1.3.3 版本开始引入
- 默认值：
true - 支持热加载：是
- 是否启用基于地理位置的负载均衡。
migrations-per-second 从 v1.3.3 版本开始引入
- 默认值：
0 - 支持热加载：是
- 取值范围：
>= 0 - 指定基于地理位置的负载均衡每秒迁移的连接数。
0表示使用默认迁移速率。
conn-count 从 v1.3.3 版本开始引入
基于连接数的负载均衡配置。
migrations-per-second 从 v1.3.3 版本开始引入
- 默认值：
0 - 支持热加载：是
- 取值范围：
>= 0 - 指定基于连接数的负载均衡每秒迁移的连接数。
0表示由 TiProxy 自动计算迁移速率。若观察到连接频繁来回迁移，可适当减小该值。
count-ratio-threshold 从 v1.3.3 版本开始引入
- 默认值：
1.2 - 支持热加载：是
- 取值范围：
0或> 1 - 指定触发基于连接数迁移的连接数比值阈值。当连接数最多的后端与连接数最少的后端之比超过该阈值时，TiProxy 开始迁移连接。增大该值可降低迁移频率。
0表示该参数使用默认值。
ha
TiProxy 的高可用配置。
virtual-ip
- 默认值：
"" - 支持热加载：否
- 指定虚拟 IP 地址，使用 CIDR 格式表示，例如
"10.0.1.10/24"。当集群中有多台 TiProxy 配置同一虚拟 IP 时，只有一台 TiProxy 会绑定该虚拟 IP。当该 TiProxy 下线时，另外一台 TiProxy 会自动绑定该 IP，确保客户端始终能通过虚拟 IP 连接到可用的 TiProxy。
配置示例：
server_configs:
tiproxy:
ha.virtual-ip: "10.0.1.10/24"
ha.interface: "eth0"
从 v1.3.1 开始，TiProxy 支持配置多个虚拟 IP。当需要隔离计算层资源时，可以配置多个虚拟 IP，并结合基于标签的负载均衡使用。示例可参见基于标签的负载均衡。
interface
- 默认值：
"" - 支持热加载：否
- 指定绑定虚拟 IP 的网络接口，例如
"eth0"。只有同时设置ha.virtual-ip和ha.interface时，该 TiProxy 实例才能绑定虚拟 IP。
garp-burst-count 从 v1.3.3 版本开始引入
- 默认值：
5 - 支持热加载：否
- 取值范围：
>= 0 - 指定 TiProxy 实例接管并绑定虚拟 IP 后立即发送的 GARP（Gratuitous ARP，无偿 ARP）包数量。GARP 用于通知交换机和主机更新虚拟 IP 对应的 MAC 地址，使客户端流量尽快切换到接管虚拟 IP 的 TiProxy 实例。连续发送多个包可以降低首个 GARP 报文丢失导致切换延迟的风险。
0会被自动调整为1。
garp-refresh-count 从 v1.3.3 版本开始引入
- 默认值：
30 - 支持热加载：否
- 取值范围：
>= 0 - 指定接管虚拟 IP 后补充发送 GARP 的次数，两次发送间隔为 1 秒，每次发送
garp-burst-count个包。用于在故障切换后的一段时间内刷新上游设备中之前的虚拟 IP 到 MAC 地址映射，避免流量仍被转发到旧实例。0表示接管后不再补充发送。
labels
- 默认值：
{} - 支持热加载：是
- 指定服务器标签，例如
{ zone = "us-west-1", dc = "dc1" }。
log
level
- 默认值：
info - 支持热加载：是
- 可选值：
debug,info,warn,error,panic - 指定日志的级别。当指定
panic级别时，TiProxy 遇到错误时会 panic。
encoder
默认值：
tidb可选值：
tidb：TiDB 使用的格式。有关详细信息，请参见统一日志格式。json：结构化 JSON 格式。console：易读的日志格式。
log.log-file
filename
- 默认值：
"" - 支持热加载：是
- 日志文件路径。非空值将启用日志记录到文件。使用 TiUP 部署时会自动设置文件路径。
max-size
- 默认值：
300 - 支持热加载：是
- 单位：MB
- 日志文件的最大大小。超过该大小后，日志将被轮转。
max-days
- 默认值：
3 - 支持热加载：是
- 指定保留旧日志文件的最大天数。超过此期限后，将删除过时的日志文件。
max-backups
- 默认值：
3 - 支持热加载：是
- 指定要保留的日志文件的最大数量。当超过此数量时，将自动删除多余的日志文件。
security
在 [security] 部分有四个名称不同的 TLS 对象，它们共享相同的配置格式和字段，但是不同名称对象的字段解释可能不同。
[security]
[sql-tls]
skip-ca = true
[server-tls]
auto-certs = true
所有 TLS 选项都支持热加载。
TLS 对象字段：
ca：指定 CAcert：指定证书key：指定私钥auto-certs：主要用于测试。如果没有指定证书或密钥，则会生成证书。skip-ca：在客户端对象上跳过使用 CA 验证证书，或在服务器对象上跳过服务器端验证。min-tls-version：设置最低 TLS 版本。可选值：1.0、1.1、1.2和1.3。默认为1.2，代表支持 TLSv1.2 及以上版本。rsa-key-size：启用auto-certs时设置 RSA 密钥大小。autocert-expire-duration：设置自动生成证书的默认到期时间。
对象根据名称被分类为客户端或服务器对象。
对客户端 TLS 对象：
- 必须设置
ca或skip-ca来跳过验证服务器证书。 - 可选：可以设置
cert或key来通过服务器端客户端验证。 - 无用字段：
auto-certs。
对服务器 TLS 对象：
- 设置
cert、key或auto-certs后支持 TLS 连接，否则不支持 TLS 连接。 - 可选：如果
ca不为空，则启用服务器端的客户端验证。客户端必须提供证书。如果skip-ca为true且ca不为空，则服务器仅在客户端提供证书时才验证客户端证书。
cluster-tls
客户端 TLS 对象。用于访问 TiDB 或 PD。
require-backend-tls
- 默认值：
false - 支持热加载：是，但只对新连接有效
- 要求 TiProxy 和 TiDB 服务器之间使用 TLS 连接。如果 TiDB 服务器不支持 TLS，则客户端在连接到 TiProxy 时会报错。
sql-tls
客户端 TLS 对象。用于访问 TiDB SQL 端口（4000）。
server-tls
服务器 TLS 对象。用于在 SQL 端口（6000）上提供 TLS。
server-http-tls
服务器 TLS 对象。用于在 HTTP 状态端口（3080）上提供 TLS。