企业官网建设流程全解析

• 零信任
• 网络
• 后端
• 认证鉴权

导读

本文以 OpenZiti 仓库中的 doc/2.0-metrics-and-config-changes.md 为骨架，系统梳理从 OpenZiti v1.6.8 升级到 v2.0 时所有涉及监控指标、配置项增删、默认值调整、配置解析修复与CLI 行为变化的破坏性与非破坏性变更。读者将获得一份可直接对照自己 controller/router 配置文件的迁移清单，并能理解每一项新指标背后的源码实现与运维含义。文中所有结论均可在当前仓库源码与配置文件中验证。

阅读前提：什么是 Beta Feature

在讨论 2.0 的变更之前，先明确文档中的一个基础定义，因为其中多处新能力被标记为 Beta：

Beta Feature —— 仍处于开发中的特性，未来可能变化。它以发布形态可用，虽然可能性很小，但存在被移除的可能。

因此，本文涉及到的ctrl.dialer、ctrl.listeners、alert事件等 Beta 特性，适合在测试与试点环境先行验证，不建议在正式生产拓扑中依赖其长期稳定性。

一、新增指标（New Metrics）

2.0 在 controller 与 router 两侧新增了一大批指标，全部接入既有 metrics registry。下文按功能域分组说明。

1. Raft 自适应限流器（Controller）

Raft 分布式日志的命令提交现在由自适应窗口限流器控制，新增三项指标：

这些指标名与源码中的常量一一对应，见 controller/config/config.go：

RaftRateLimiterQueueSizeMetricName = "raft.rate_limiter.queue_size" RaftRateLimiterWorkTimerMetricName = "raft.rate_limiter.work_timer" RaftRateLimiterWindowSizeMetricName = "raft.rate_limiter.window_size"

命名空间的重大变化：此前 raft 路径与普通（非 raft）命令分发器共用command.limiter.*命名空间；升级后 raft 路径独立到raft.rate_limiter.*，而普通命令路径继续使用command.limiter.queued_count和command.limiter.work_timer。升级后做监控告警时，务必同时调整这两组指标的采集与看板配置，避免仪表盘数据缺失。

从实现看，raft 限流采用AdaptiveRateLimitTracker（见 controller/command/rate_limiter.go），它不直接执行工作，而是跟踪在途工作并根据成功率直方图动态调整窗口：raftOperation, err := self.raftRateLimiter.RunRateLimited("raft operation")（controller/raft/raft.go）。后台 goroutine 每 30 秒清理一次超过timeout未完成的工作，将其视为 backoff（cleanExpired，controller/command/rate_limiter.go），因此queue_size不会因在途任务丢失而卡死。

2. 后台命令处理（Controller）

当command.background开启（默认true）时，暴露 5 项新指标：

后台队列承载的是与认证相关的模型更新（identity 环境信息、system authenticator 更新等），将这些更新异步化能降低认证路径上的同步阻塞。queue_size与busy_workers是判断后台处理是否积压的关键观测点；若dropped_entries持续增长，说明队列容量不足以承载写入峰值，需要评估调大queueSize或检查上游更新频率。

3. 控制器发起的控制通道拨号（Controller，Beta）

在ctrl.dialer启用时，暴露ctrl_channel.dialer.*前缀下的 4 项指标：

4. 控制通道监听器池（Router，Beta）

当 router 配置了控制通道监听器时，暴露pool.listener.ctrl.*前缀下的 4 项指标：

这组指标的通用生成逻辑在 common/servermetrics/pool_metrics.go：GoroutinesPoolMetricsConfigF为 goroutine 池统一注册queue_size、worker_count、busy_workers三个 FuncGauge，并挂载work_timerTimer 回调。也就是说，凡是基于 foundation goroutine 池构建的组件（ctrl 监听器池、后台命令池等）都会遵循这一套指标契约，运维侧可以复用同一套采集模板。

5. 电路与链路故障计数（Router）

新增两个 Meter 指标，替代原先仅输出 warn 级别日志的故障上报：

从 warn 日志变成可计数的 Meter 指标，意味着故障可以进入监控系统做趋势分析、告警与容量评估，而不是依赖翻阅日志。相关实现位于 router/forwarder/faulter.go。

6. 撤销强制器（Controller）

新增两项指标，服务于周期性的撤销记录清理流程：

源码中这两项指标在 controller/internal/policy/revocation_enforcer.go 定义，执行后以runTimer.UpdateSince(startTime)记录耗时、以deleteMeter.Mark(int64(total))记录删除量。delete的斜率可以直观反映撤销记录积压情况，若与edge.oidc.revocationMaxQueued触顶相关，需要综合评估撤销批量冲刷节奏。

二、移除的事件（Removed Events）

Terminator 创建/更新/删除事件

created、updated、deleted三类 terminator 事件被移除。它们已被entity change 事件取代——该事件体系自 v0.28.0 引入，且同样覆盖 terminator 的创建/更新/删除。

升级影响：任何依赖 terminator 事件流做业务联动（如库存同步、审计、自动化清理）的下游消费者，必须迁移到 entity change 事件订阅，并在迁移期间比对事件字段结构差异（entity change 事件是通用实体变更模型，字段命名与专用 terminator 事件不同）。

三、新增配置（New Configuration）

1. Controller：集群限流器（cluster.rateLimiter）

控制向 Raft 集群提交命令的节奏，采用自适应窗口：

cluster: applyTimeout: 5s rateLimiter: enabled: true # default: true minSize: 5 # default: 5, minimum: 1 maxSize: 250 # default: 250 timeout: 30s # default: 30s restartSelfOnSnapshot: false # default: false preferredLeader: false # default: false

参数说明：

• applyTimeout—— Raft 日志应用超时（默认5s）
• rateLimiter.enabled—— 开启 Raft 命令提交的自适应限流（默认true）
• rateLimiter.minSize—— 在途 Raft 操作的最小并发数（默认5，最小1）
• rateLimiter.maxSize—— 在途 Raft 操作的最大并发数（默认250）
• rateLimiter.timeout—— 在此时间内未完成标记的工作视为失败（默认30s）
• restartSelfOnSnapshot—— 恢复快照后自动重启 controller（默认false）
• preferredLeader—— 将本 controller 标记为首选 Raft 领导者（默认false）

配置加载与校验逻辑在 controller/command/rate_limiter.go：minSize必须 ≥ 1 且 ≤maxSize，timeout必须是可解析的 duration。注意queue通道的容量取MaxSize，即窗口上限同时决定物理排队容量。

2. Controller：后台命令处理（command.background）

允许与认证相关的模型更新（identity 环境信息、system authenticator 更新）异步进入后台队列处理：

command: background: enabled: true # default: true queueSize: 1000 # default: 1000 dropWhenFull: false # default: false delayThreshold: 50ms # default: 50ms rateLimiter: enabled: true maxQueued: 25

• background.enabled—— 开启后台处理（默认true）
• background.queueSize—— 最大队列容量（默认1000）
• background.dropWhenFull—— 队列满时丢弃更新而不是阻塞（默认false）
• background.delayThreshold—— 更新耗时超过该阈值后开始转入后台处理（默认50ms）

注意：commandRateLimiter段现在也可以写在command下作为rateLimiter。若两处同时配置，command下的设置优先；独立的commandRateLimiter段未来可能被废弃，建议逐步迁移到新位置。

在源码层面，command.background的解析位于 controller/config/config.go，其中queueSize有明确的最小/最大值校验（BackgroundQueueMinSize/BackgroundQueueMaxSize），delayThreshold需要按 duration 解析——配置格式错误会导致启动失败而非静默忽略。

3. Controller：连接事件池（connectEvents）

identity 的连接/断开事件改为每 router 单 worker 的 goroutine 池，取代此前每 router 一个 goroutine 的模型（该模型在重连时会泄漏 goroutine）。每 router 单 worker 的设计保证同一 router 的事件永远按 FIFO 顺序处理，避免乱序处理导致状态不一致：

connectEvents: queueSize: 5 # default: 5 idleTime: 30s # default: 30s

注意：minWorkers与maxWorkers两项设置已被移除。出于正确性考虑，每个 router 的池固定为 1 个 worker——这正是文档中「单 worker 保序」设计原则的直接体现，升级配置时请删除这两个字段，否则它们会被静默忽略。

4. Controller：OIDC 自动绑定退出（edge.api.disableOidcAutoBinding）

现在 controller 会自动把edge-oidc绑定到任何托管edge-client的 web listener 上。若需关闭该行为：

edge: api: disableOidcAutoBinding: true # default: false

重要影响：当 OIDC 未启用时，客户端回退到 legacy 认证方式，而 legacy 认证不支持 HA。因此，在 HA 集群中若要启用该开关，必须确保 OIDC 链路可用，否则认证能力会与 HA 目标冲突。

5. Controller：OIDC 撤销调优（edge.oidc）

控制 JWT token 撤销的批量处理与清理：

这组参数与前述revocation.enforcer.*指标直接联动：revocationEnforcerFrequency决定执行周期，revocationBucketMaxSize/revocationMaxQueued决定吞吐与积压边界。若revocation.enforcer.delete的速率长期为 0，说明撤销记录没有进入强制清理路径，需检查是否所有 controller 都在正确的 raft 角色上。

6. Controller：控制器发起的控制通道拨号（ctrl.dialer，Beta）

允许 controller 主动向 router 发起拨号以建立控制通道，适用于部分 controller 位于 router 无法触达的防火墙之后的部署：

ctrl: dialer: enabled: false # default: false groups: ["default"] # default: ["default"] dialDelay: 30s # default: 30s minRetryInterval: 1s # default: 1s maxRetryInterval: 5m # default: 5m retryBackoffFactor: 1.5 # default: 1.5 fastFailureWindow: 5s # default: 5s queueSize: 32 # default: 32 maxWorkers: 10 # default: 10

• enabled—— 是否启用拨号器（默认false）
• groups—— 拨号目标 router 组（默认["default"]）
• dialDelay—— 拨号前的初始延迟（默认30s）
• minRetryInterval/maxRetryInterval—— 重试间隔的下限与上限
• retryBackoffFactor—— 重试退避的倍增因子
• fastFailureWindow—— 快速失败判定窗口
• queueSize—— 拨号任务队列容量
• maxWorkers—— 最大拨号工作 goroutine 数

启用后请监控ctrl_channel.dialer.*四件套指标（见前文新指标第 3 节）确认拨号吞吐与失败节奏。

7. Controller：Azure Service Bus 事件接收器

新增servicebus事件 handler 类型，可将 controller 事件流式投递到 Azure Service Bus：

events: serviceBusLogger: subscriptions: - type: circuit - type: session handler: type: servicebus format: json connectionString: "Endpoint=sb://..." topic: "ziti-events" # or queue: "ziti-events-queue" bufferSize: 100 # default: 50

要点：

• 订阅类型沿用既有事件类型（示例订阅了circuit与session）；
• 输出格式为json；
• 目标是 topic 或 queue（二选一，示例注释给出 queue 写法）；
• bufferSize默认50，示例调至100——事件量较大时建议显式调大，降低阻塞概率。

8. Controller：Alert 事件（Beta）

新增alert事件订阅类型，用于向网络运维人员暴露运营问题：

events: myLogger: subscriptions: - type: alert

配合既有 file/amqp 等 handler 即可将 alert 事件落盘或转发。作为 Beta 特性，alert 事件的具体字段与语义可能在后续版本调整。

9. Router：控制通道监听器（ctrl.listeners，Beta）

允许 router 接受来自 controller 的入站控制通道连接，与 controller 侧ctrl.dialer呼应（一端拨号、一端监听）：

ctrl: listeners: - bind: tls://0.0.0.0:6262 advertise: tls://router.example.com:6262 groups: - default

• bind—— 本地监听地址（TLS 端口，示例 6262）
• advertise—— 对外公布地址，供 controller 拨号使用（请填可达的域名/IP）
• groups—— 归属的 router 组，与 controllerctrl.dialer.groups对应

启用后配合pool.listener.ctrl.*指标观察监听器池的健康度（见前文新指标第 4 节）。

10. 限流器算法调优参数

TLS 握手、raft 命令、router ctrl 通道三处rateLimiter段均可配置以下 5 个新参数。算法核心从「原始队列位置」改为「成功率指标」驱动窗口自适应：

这些参数在 controller/command/rate_limiter.go 的AdaptiveRateLimitTrackerConfig中有严格校验：successThreshold必须在 0~1 之间，increaseFactor必须 ≥ 1（源码注释建议通常小于 2），decreaseFactor必须在 (0,1) 开区间，两个 check interval 都必须 ≥ 1。合法值校验失败会直接报错，避免静默带入非法参数。窗口调整逻辑见success()与backoff()（controller/command/rate_limiter.go）：窗口增长/收缩都基于指数衰减直方图统计的成功率均值。

四、移除的配置（Removed Configuration）

1. Controller：routerDataModel.enabled

router 数据模型（router data model）现已始终启用，enabled字段被删除。已有配置文件中残留的routerDataModel.enabled会被直接忽略，不会导致启动失败，但建议清理以免误导后人。

2. Controller：network.enableLegacyLinkMgmt

Router 管理链路（v0.30.0 引入）已成为唯一选项。enableLegacyLinkMgmt字段以及 controller 侧的 legacy 链路管理代码被整体移除。升级前若配置了该字段，升级后它不再有任何效果。

3. Router：ctrl.ha

HA 已成为 router 侧的常驻行为，ctrl.ha配置键被删除。

五、默认值变更（Changed Defaults）

1. Controller：tls.rateLimiter.maxSize

TLS 握手限流器的默认最大窗口从1000提升到2500。注意：限流器本身默认仍处于禁用状态，该默认值变更只影响启用后的行为。如果此前针对 1000 做过容量规划，启用时请按新默认重新评估。

2. Controller：routerDataModel.logSize最小值

routerDataModel.logSize现在强制最小值为10。低于10的配置会在启动时报配置错误（config error），而不是静默接受——升级后若该字段设过小于 10 的值，启动日志会直接暴露问题。

六、配置解析 Bug 修复（Configuration Bug Fixes）

2.0 修复了若干可能导致配置被静默忽略或被写入错误字段的解析缺陷。文档明确要求：如果你配置过下列任一设置，升级后必须验证其是否真正生效。

其中「OIDC 时长」一项是典型的字段错位 bug：两个独立配置项被同时写入了 access token 时长字段，导致 refresh/id token 时长永远取不到自己配置的值。升级后请重点核验这些场景：

• controller 配置中ctrl.heartbeats、TLS 限流器timeout、cluster段下的commandHandler是否按预期生效；
• router 配置中connectEvents.fullSyncInterval、interfaceDiscovery.minReportInterval是否呈现配置值；
• OIDC 三个 token 时长是否各自独立生效（尤其是设置了 refresh token 时长的场景）；
• 启用了 SPIFFE trust domain 的部署，确认前缀匹配方向正确。

七、CLI 变更（CLI Changes）

• ziti edge quickstart现在始终以 HA 模式运行。ha子命令被移除；添加集群成员请使用ziti edge quickstart join。已有非 HA quickstart 实例必须重建（无法原地升级）。
• ziti create config controller的--clustered标志被移除，生成的配置始终为集群就绪（cluster-ready）。
• ziti edge create identity <type>子命令（device、service、user）被移除，请直接使用ziti edge create identity。

这三项变更共同指向 2.0 的 HA 主线：配置生成默认集群化、quickstart 强制 HA、身份类型收敛。脚本与自动化流程中凡是依赖旧命令形态的，都需要同步改写。

八、升级迁移自查清单

综合上述变更，从 1.6.8 升级到 2.0 时建议按以下清单逐项核对：

1. 监控侧：把raft.rate_limiter.*与command.limiter.*从同一命名空间拆开；新增采集command.background.*、ctrl_channel.dialer.*（如启用 dialer）、pool.listener.ctrl.*（如启用 listeners）、faults.circuit、faults.link、revocation.enforcer.*；移除 terminator 专用事件订阅并切换到 entity change 事件。
2. controller 配置：确认cluster.rateLimiter、command.background、connectEvents（删除minWorkers/maxWorkers）、edge.api.disableOidcAutoBinding（默认关闭，启用需评估 legacy 认证与 HA 的冲突）、edge.oidc撤销调优、ctrl.dialer（Beta）、servicebus/alert 事件订阅等新段；删除routerDataModel.enabled、network.enableLegacyLinkMgmt；核对tls.rateLimiter.maxSize新默认与routerDataModel.logSize最小值约束。
3. router 配置：删除ctrl.ha；按需新增ctrl.listeners（Beta）并确认ctrl.dialer.groups与其匹配。
4. CLI/脚本：将 quickstart 流程迁移到 HA 模式（必要时重建实例），移除--clustered，改用统一的ziti edge create identity。
5. 回验：对照 第六节 的 bug 清单，用ziti或管理 API 确认各项设置真正生效，尤其是 OIDC token 时长与各限流器参数。

本清单与本文所有配置片段均可在仓库的 etc 示例配置、controller/config/config.go 与 router/env/config.go 中对照验证；指标的注册与暴露逻辑可进一步查看 controller/command/rate_limiter.go、common/servermetrics/pool_metrics.go 与 controller/internal/policy/revocation_enforcer.go。

• 零信任
• 网络
• 后端
• 认证鉴权