OpenZiti 2.0.8 配置参数详解

目标：逐段解读 OpenZiti v2.0.8 的 controller 与 router 配置文件，给出参数总览、修改生效的验证方法与生产配置模板。全部配置摘录、命令与回显均在 Ubuntu 22.04.5 服务器（ziti v2.0.8）实测通过。

一、环境信息

本文所有配置文件、命令与回显均在以下环境实测（2026-10-20）：

项目	值
操作系统	Ubuntu 22.04.5 LTS（x86_64，systemd 249.11 托管服务）
主机名 / 地址	ziti-srv / 10.89.57.2（内网静态地址，请按实际替换）
OpenZiti 版本	ziti v2.0.8（2026-10-20 官方最新稳定版）
ziti-edge-tunnel 版本	v1.18.7
配置文件	controller：/opt/ziti/controller/controller.yaml；router：/opt/ziti/router/ziti-er1.yaml
端口	controller 1280（Edge API）、6262（集群控制通道）；router 3022（边缘接入）、10080（链路）
服务	ziti-controller.service / ziti-router.service / ziti-edge-tunnel.service（均 active）

💡 说明：v2.0 的 controller 配置文件版本标记为 v: 3，与 v1 的配置结构差异较大（新增 cluster 段、ctrl 段取代 v1 的 ctrlListener 等）。v1 时代的配置教程不能直接套用，参见《OpenZiti 介绍与选型指南》中 v2.0 部署变化一节。

二、前置条件

已按《Ubuntu 22.04 安装 OpenZiti 指南》完成 controller、router 与隧道器的安装，controller 与 router 处于运行状态；
已生成 PKI 证书（本文路径以 /opt/ziti/controller/pki/ 为例）；
已设置会话变量 export ZITI_HOME=/opt/ziti/controller（ziti create config 按该变量展开证书路径，未设置会生成空根路径，见七、常见问题 1）；
了解 YAML 基础语法：OpenZiti 配置对缩进敏感，# 为注释。

三、参数查看与修改方式

3.1 用 ziti create config 生成配置模板

v2.0 提供 ziti create config 子命令生成两份配置的官方模板，生成后再把证书路径、地址等替换为实际值（本文第一、五节的配置即由该模板实测修改而来）。controller 模板的命令帮助实测如下：

export ZITI_HOME=/opt/ziti/controller
ziti create config controller --help

creates a controller config file

Usage:
  ziti create config controller [flags]

Aliases:
  controller, ctrl

Examples:
  # Creates a controller config file
  ziti create config controller

  # Create the controller config with a particular ctrlListener host and port
  ziti create config controller --ctrlPort 6262

  # Print the controller config to the console
  ziti create config controller --output stdout

  # Print the controller config to a file
  ziti create config controller --output <path to file>/<filename>.yaml

  # Create the controller config with an edge router enrollment duration of 2 hours
  ziti create config controller --identityEnrollmentDuration 2h
  # OR
  ziti create config controller --identityEnrollmentDuration 120m

Flags:
      --ctrlPort string                       port used for the router to controller communication (default "6262")
  -h, --help                                  help for controller
      --identityEnrollmentDuration duration   the edge identity enrollment duration, use 0h0m0s format (default 3h0m0s)
  -o, --output string                         designated output destination for config, use "stdout" or a filepath. (default "stdout")
      --routerEnrollmentDuration duration     the edge router enrollment duration, use 0h0m0s format (default 3h0m0s)
  -v, --verbose                               Enable verbose logging. Logging will be sent to stdout if the config output is sent to a file. If output is sent to stdout, logging will be sent to stderr

router 模板分 edge 与 fabric 两种，帮助实测如下：

ziti create config router --help

creates a config file for specified router name

Usage:
  ziti create config router [command]

Aliases:
  router, rtr

Available Commands:
  edge        Create an edge router config
  fabric      Create a fabric router config

Flags:
  -h, --help                help for router
  -o, --output string       designated output destination for config, use "stdout" or a filepath. (default "stdout")
  -n, --routerName string   name of the router
  -v, --verbose             Enable verbose logging. Logging will be sent to stdout if the config output is sent to a file. If output is sent to stdout, logging will be sent to stderr

Use "ziti create config router [command] --help" for more information about a command.

ziti create config router edge --help

Creates the edge router config

Usage:
  ziti create config router edge [flags]

Aliases:
  edge, edge

Examples:
  # Create the edge router config for a router named my_router
  ziti create config router edge --routerName my_router

Flags:
  -h, --help                  help for edge
      --lanInterface string   The interface on host of the router to insert iptables ingress filter rules
  -o, --output string         designated output destination for config, use "stdout" or a filepath. (default "stdout")
      --private               Do not listen for router links
  -n, --routerName string     name of the router
      --tunnelerMode string   Specify tunneler mode "none", "host", "tproxy", or "proxy" (default "host")
  -v, --verbose               Enable verbose logging. Logging will be sent to stdout if the config output is sent to a file. If output is sent to stdout, logging will be sent to stderr
      --wss                   Configure a WebSocket edge binding for BrowZer clients

本文实验环境实际使用的两条生成命令（生成成功时无输出）：

ziti create config controller --ctrlPort 6262 --output $ZITI_HOME/controller.yaml
ziti create config router edge --routerName ziti-er1 --tunnelerMode host --output $ZITI_HOME/ziti-er1.yaml

3.2 参数修改与生效验证（实测闭环）

OpenZiti 的配置仅在进程启动时读取，修改后必须重启对应服务才能生效，不存在热加载。以下用 router 的 metrics.reportInterval 做一次完整的修改→验证→还原实测。

第一步，把 /opt/ziti/router/ziti-er1.yaml 中的 reportInterval: 1m 改为 2m 并重启服务：

sed -i "s/reportInterval: 1m/reportInterval: 2m/" /opt/ziti/router/ziti-er1.yaml
grep reportInterval /opt/ziti/router/ziti-er1.yaml
systemctl restart ziti-router

  reportInterval: 2m

第二步，从服务日志确认新值已生效（观测点见 3.3 节）：

journalctl -u ziti-router --no-pager --since "-60s" | grep '"msg":"metrics"'

Oct 20 17:04:05 ziti-srv ziti[6341]: {"file":"github.com/openziti/ziti/v2/router/router.go:573","func":"github.com/openziti/ziti/v2/router.(*Router).showOptions","level":"info","msg":"metrics = {\"ReportInterval\":120000000000,\"IntervalAgeThreshold\":0,\"MessageQueueSize\":10,\"EventQueueSize\":256,\"EnableDataDelayMetric\":false}","time":"2026-10-20T17:04:05.087Z"}

ReportInterval 从 60000000000（纳秒，即 1 分钟）变为 120000000000（2 分钟），证明修改经重启后生效。随后还原为 1m 并重启，回显恢复 ReportInterval":60000000000，端到端拨号验证 curl http://webtest.svc.ziti/ 返回 200 0.003883s，服务链路正常。

⚠️ 注意：重启 router 会短暂中断边缘接入（约 5~10 秒），生产环境请安排在维护窗口执行。controller 重启同理，且多节点 HA 集群应逐节点滚动重启。

3.3 运行时参数观测点：showOptions 日志行

router 启动时会用 showOptions 日志行回显关键运行参数，是核对配置是否按预期生效的最直接观测点。以下两行摘自实测日志（journalctl -u ziti-router --no-pager）：

Oct 20 17:04:05 ziti-srv ziti[6341]: {"file":"github.com/openziti/ziti/v2/router/router.go:567","func":"github.com/openziti/ziti/v2/router.(*Router).showOptions","level":"info","msg":"ctrl = {\"OutQueueSize\":4,\"MaxQueuedConnects\":1,\"MaxOutstandingConnects\":16,\"ConnectTimeout\":5000000000,\"WriteTimeout\":0,\"MessageStrategy\":null}","time":"2026-10-20T17:04:05.087Z"}
Oct 20 17:04:05 ziti-srv ziti[6341]: {"file":"github.com/openziti/ziti/v2/router/router.go:573","func":"github.com/openziti/ziti/v2/router.(*Router).showOptions","level":"info","msg":"metrics = {\"ReportInterval\":60000000000,\"IntervalAgeThreshold\":0,\"MessageQueueSize\":10,\"EventQueueSize\":256,\"EnableDataDelayMetric\":false}","time":"2026-10-20T16:33:26.966Z"}

对照关系：ctrl 行的 OutQueueSize:4 对应配置 link.listeners.options.outQueueSize: 4；metrics 行的 ReportInterval:60000000000（60 秒）对应 metrics.reportInterval: 1m、MessageQueueSize:10 对应 metrics.messageQueueSize: 10。controller 侧的关键参数同样可以从启动日志的 JSON 行中核对（如 Edge API 监听地址、Raft 就绪状态等）。

四、参数总览

controller.yaml 顶层段实测结构（完整内容见第五节逐段摘录）：

顶层段	必填	作用
`v`	是	配置文件结构版本，v2.0.8 生成值为 `3`
`cluster`	是	Raft 集群数据目录（HA 基础，v2 新增）
`identity`	是	controller 自身证书四件套（cert/server_cert/key/ca）
`ctrl`	是	路由器回连控制通道的广播地址与监听地址
`healthChecks`	否	内置健康检查（bolt 读事务探测）
`edge`	是	Edge API 会话超时、注册签名证书与有效期
`web`	是	Web 监听（bindPoints）、TLS 身份、HTTP/TLS 选项与 API 绑定
`network`	否	overlay 路由行为（超时、重试、智能路由），默认值即可用
`metrics`	否	指标导出到 InfluxDB（本环境未启用）
`trace` / `profile`	否	追踪与内存剖析（默认注释）

router 配置 ziti-er1.yaml 顶层段实测结构：

顶层段	必填	作用
`v`	是	配置结构版本 `3`
`identity`	是	路由器证书四件套（由注册流程生成）
`ctrl`	是	回连 controller 的端点清单（endpointsFile 指向自动生成文件）
`link`	是	路由器间链路的拨号器与监听器
`listeners`	是	边缘接入（edge）与隧道模式（tunnel）监听
`edge`	是	边缘证书 CSR 主体与 SAN（注册时提交给 controller 签发）
`forwarder`	否	转发引擎工作队列（默认值来自生成模板）
`metrics`	否	指标上报间隔与队列大小
`transport`	否	WebSocket 传输选项（默认注释）

💡 说明：路由器还有一份由 ziti router enroll 自动生成的 /opt/ziti/router/endpoints.yml，内容为 controller 集群端点清单，实测内容如下。多节点 HA 集群下该文件会列出全部节点，路由器据此回连任一存活节点：

controllers:
- endpoints:
  - address: tls:ziti-srv:6262
    groups: []
  id: ziti-srv
endpoints:
- tls:ziti-srv:6262

五、核心参数分类详解

5.1 controller：cluster 与 healthChecks（Raft 存储与健康检查）

cluster:
  dataDir:         "/opt/ziti/controller/raft"

healthChecks:
  boltCheck:
    # How often to try entering a bolt read tx. Defaults to 30 seconds
    interval: 30s
    # When to time out the check. Defaults to 20 seconds
    timeout: 20s
    # How long to wait before starting the check. Defaults to 30 seconds
    initialDelay: 30s

参数	实测值	说明
cluster.dataDir	/opt/ziti/controller/raft	Raft 日志与快照目录，v2.0 起所有数据（原 v1 的 bolt 数据库）都存于此；HA 集群各节点各有一份，通过 Raft 复制。目录必须独占且持久化
healthChecks.boltCheck.interval	30s	健康检查发起读事务的周期
healthChecks.boltCheck.timeout	20s	单次检查超时，超时即判不健康
healthChecks.boltCheck.initialDelay	30s	启动后延迟多久开始检查

💡 说明：v2.0 的 controller 天生以 Raft 集群形态运行，单节点就是"1 副本集群"。ziti agent cluster init 引导首个节点后，用 ziti agent cluster add 追加节点组成 HA（参见《OpenZiti 2.0.8 常用 CLI 命令详解（ziti CLI）》）。

5.2 controller：identity（身份证书四件套）

identity:
  cert:        "/opt/ziti/controller/pki/ziti-srv/certs/server.chain.pem"
  server_cert: "/opt/ziti/controller/pki/ziti-srv/certs/server.chain.pem"
  key:         "/opt/ziti/controller/pki/ziti-srv/keys/server.key"
  ca:          "/opt/ziti/controller/pki/ziti-srv/certs/ziti-srv.chain.pem"
  #alt_server_certs:
  #  - server_cert:  ""
  #    server_key:   ""

参数	实测值	说明
identity.cert	server.chain.pem	对外出示的证书链（含中间证书）。本环境由 `ziti pki create server` 签发，SPIFFE ID 形如 `spiffe://<trust-domain>/controller/ziti-srv`
identity.server_cert	server.chain.pem	仅用于服务端（TLS 监听）的证书，通常与 cert 相同
identity.key	server.key	与 cert 配对的私钥，权限建议 600
identity.ca	ziti-srv.chain.pem	校验客户端（路由器/CLI）证书所用信任链
alt_server_certs	未启用	备用服务端证书对，用于证书轮换过渡

💡 技术拓展：v2.0 引入基于 SPIFFE ID 的身份体系，controller/router 的证书必须以 URI SAN 形式携带 SPIFFE ID，信任域（trust domain）在签发 CA 时用 -a spiffe://<domain> 指定。若证书缺失 URI SAN，集群节点间互信会失败，证书细节见官方 HA 证书文档（第八节参考链接 3）。

5.3 controller：ctrl（路由器控制通道）

# the endpoint that routers will connect to the controller over.
ctrl:
  options:
    advertiseAddress: tls:ziti-srv:6262
  # (optional) settings
  # set the maximum number of connect requests that are buffered and waiting to be acknowledged (1 to 5000, default 1)
  #maxQueuedConnects:      1
  # the maximum number of connects that have  begun hello synchronization (1 to 1000, default 16)
  #maxOutstandingConnects: 16
  # the number of milliseconds to wait before a hello synchronization fails and closes the connection (30ms to 60000ms, default: 5000ms)
  #connectTimeoutMs:       5000
  listener:             tls:0.0.0.0:6262

参数	实测值	说明
ctrl.options.advertiseAddress	tls:ziti-srv:6262	广播给路由器的回连地址，必须能被路由器解析与访问；HA 集群中该值进入各路由器的 endpoints.yml
ctrl.listener	tls:0.0.0.0:6262	本机监听地址，0.0.0.0 表示全部网卡
ctrl.options.maxQueuedConnects	1（默认，注释态）	缓冲的待确认连接请求数（1~5000）
ctrl.options.maxOutstandingConnects	16（默认，注释态）	正在 hello 同步的连接上限（1~1000）
ctrl.options.connectTimeoutMs	5000（默认，注释态）	hello 同步超时毫秒数（30~60000）

5.4 controller：edge（Edge API 与注册）

edge:
  api:
    sessionTimeout: 30m
    address: ziti-srv:1280
  enrollment:
    signingCert:
      cert: /opt/ziti/controller/pki/ziti-srv/certs/ziti-srv.cert
      key:  /opt/ziti/controller/pki/ziti-srv/keys/ziti-srv.key
    edgeIdentity:
      duration: 180m
    edgeRouter:
      duration: 180m

参数	实测值	说明
edge.api.sessionTimeout	30m	Edge API 会话超时；API 请求与路由器长连接会不断重置该计时器
edge.api.address	ziti-srv:1280	注册回执中使用的 Client API 地址，必须与 web 段某个 bindPoint 的 address 一致
edge.enrollment.signingCert	ziti-srv.cert/key	签发身份/路由器注册证书的签名证书，其证书会进入 /.well-known CA 集合用于引导信任
edge.enrollment.edgeIdentity.duration	180m（默认）	身份注册 JWT 的有效期，过期后 registration 不可用
edge.enrollment.edgeRouter.duration	180m（默认）	路由器注册 JWT 的有效期

生成模板还提供两个默认注释项：activityUpdateInterval: 90s（活动时间落库周期）与 activityUpdateBatchSize: 250（单事务更新的会话数），大并发接入时可按需调低周期。

5.5 controller：web（Web 监听与 API 绑定）

web:
  - name: client-management
    bindPoints:
      - interface: 0.0.0.0:1280
        address: ziti-srv:1280
    identity:
      ca:          "/opt/ziti/controller/pki/ziti-srv/certs/ziti-srv.chain.pem"
      key:         "/opt/ziti/controller/pki/ziti-srv/keys/server.key"
      server_cert: "/opt/ziti/controller/pki/ziti-srv/certs/server.chain.pem"
      cert:        "/opt/ziti/controller/pki/ziti-srv/certs/server.chain.pem"
    options:
      idleTimeout: 5000ms
      readTimeout: 5000ms
      writeTimeout: 100000ms
      minTLSVersion: TLS1.2
      maxTLSVersion: TLS1.3
    apis:
      - binding: edge-management
        options: { }
      - binding: edge-client
        options: { }
      - binding: fabric
        options: { }
      - binding: edge-oidc
        options: { }

参数	实测值	说明
web[].name	client-management	监听器名称，仅用于日志识别，建议唯一
bindPoints[].interface	0.0.0.0:1280	实际监听的本地地址:端口
bindPoints[].address	ziti-srv:1280	对外公布的地址，会出现在注册回执与 API 响应中
web[].identity	同顶层 identity	可为监听器单独指定证书；不写则继承顶层 identity 段
options.minTLSVersion / maxTLSVersion	TLS1.2 / TLS1.3	允许的 TLS 版本区间
options.idleTimeout / readTimeout / writeTimeout	5000ms / 5000ms / 100000ms	HTTP 管道空闲、首字节读、单请求总时限
apis[].binding	edge-management、edge-client、fabric、edge-oidc	挂载到该监听器的 API：管理 API（CLI/控制台用）、客户端 API（身份/隧道器用）、fabric 管理 API、OIDC 认证

⚠️ 注意：edge.api.address 必须与某一个 bindPoint 的 address 完全一致（官方模板注释原文："This value must match one of the addresses defined in this Controller.WebListener.'s bindPoints."），否则注册与部分 API 跳转会异常。模板中另有可选 spa 绑定（BrowZer 控制台静态资源），未启用时保持注释即可。

5.6 router：identity 与 ctrl.endpointsFile（回连 controller）

identity:
  cert:             "/opt/ziti/router/ziti-er1.cert"
  server_cert:      "/opt/ziti/router/ziti-er1.server.chain.cert"
  key:              "/opt/ziti/router/ziti-er1.key"
  ca:               "/opt/ziti/router/ziti-er1.cas"

ctrl:
  endpointsFile:        /opt/ziti/router/endpoints.yml

参数	实测值	说明
identity.cert / server_cert / key / ca	ziti-er1.cert 等	路由器证书四件套，由 `ziti router enroll` 按注册 JWT 与 edge.csr 自动签发生成，文件名前缀即路由器名
ctrl.endpointsFile	/opt/ziti/router/endpoints.yml	controller 集群端点清单（内容见第四节末尾）。enroll 时自动生成；HA 集群扩容后可手工追加节点并重启 router

5.7 router：link（路由器间链路）

link:
  dialers:
    - binding: transport
  listeners:
    - binding:          transport
      bind:             tls:0.0.0.0:10080
      advertise:        tls:ziti-srv:10080
      options:
        outQueueSize:   4

参数	实测值	说明
link.dialers[].binding	transport	链路拨号器类型；transport 即标准 TLS 拨号
link.listeners[].bind	tls:0.0.0.0:10080	接受其他路由器来链的本地监听
link.listeners[].advertise	tls:ziti-srv:10080	通告给 fabric 的链路地址，多路由器组网时必须可达
link.listeners[].options.outQueueSize	4	链路发送队列深度，showOptions 日志中 `OutQueueSize:4` 与之对应

💡 说明：仅部署单路由器时 link 段保持模板默认即可；多路由器组网时 advertise 必须是各路由器互相可达的地址，且防火墙放行 10080（或自定义端口）。--private 参数生成的配置会省略链路监听，适合纯接入型私有路由器。

5.8 router：listeners（边缘接入与隧道模式）

listeners:
# bindings of edge and tunnel requires an "edge" section below
  - binding: edge
    address: tls:0.0.0.0:3022
    options:
      advertise: ziti-srv:3022
      connectTimeoutMs: 5000
      getSessionTimeout: 60
  - binding: tunnel
    options:
      mode: host #tproxy|host

参数	实测值	说明
listeners[edge].address	tls:0.0.0.0:3022	边缘客户端（隧道器）接入监听
listeners[edge].options.advertise	ziti-srv:3022	通告给客户端的接入地址，注册回执与 dial 响应中使用
listeners[edge].options.connectTimeoutMs	5000	边缘连接建立超时
listeners[edge].options.getSessionTimeout	60	获取会话的超时秒数
listeners[tunnel].mode	host	内嵌隧道模式：host（按 host.v1 配置代理本机服务）或 tproxy（透明代理拦截）；模板可选 none/proxy

5.9 router：edge.csr（边缘证书签名请求）

edge:
  csr:
    country: US
    province: NC
    locality: Charlotte
    organization: NetFoundry
    organizationalUnit: Ziti
    sans:
      dns:
        - localhost
        - ziti-srv

      ip:
        - "127.0.0.1"
        - "::1"

参数	实测值	说明
country/province/locality/organization/organizationalUnit	US/NC/Charlotte/NetFoundry/Ziti（模板默认）	证书主体字段，生产建议改为本组织信息
sans.dns	localhost、ziti-srv	路由器证书的 DNS SAN；客户端经 TLS 校验路由器时用 advertised 地址比对，建议包含 `listeners[edge].advertise` 的主机名
sans.ip	127.0.0.1、::1	IP SAN，按需添加

⚠️ 注意：edge.csr 在 ziti router enroll 时一次性提交并由 controller 的 signingCert 签发，签发后修改 csr 不会更新已签证书；需要变更 SAN 应删除证书文件重新注册（或重新 enroll，报错处理见《Ubuntu 22.04 安装 OpenZiti 指南》排障实录）。

5.10 router：forwarder（转发引擎工作队列）

forwarder:
  latencyProbeInterval: 0
  xgressDialQueueLength: 1000
  xgressDialWorkerCount: 128
  linkDialQueueLength: 1000
  linkDialWorkerCount: 32

参数	实测值	说明
forwarder.latencyProbeInterval	0	链路时延探测周期秒数，0 表示关闭主动探测（默认关闭，链路时延由对端上报）
forwarder.xgressDialQueueLength	1000	xgress 拨号队列深度
forwarder.xgressDialWorkerCount	128	xgress 拨号并发工作协程数
forwarder.linkDialQueueLength	1000	链路拨号队列深度
forwarder.linkDialWorkerCount	32	链路拨号并发工作协程数

5.11 router：metrics（指标上报）

metrics:
  reportInterval: 1m
  messageQueueSize: 10

参数	实测值	说明
metrics.reportInterval	1m	指标上报周期；本文 3.2 节以该参数完成了修改生效实测（重启后 showOptions 行 `ReportInterval` 由 60000000000 变 120000000000 纳秒）
metrics.messageQueueSize	10	指标消息队列容量

controller 侧另有可选的 metrics.influxdb 段（url/database），用于把 fabric 指标推送到 InfluxDB，本环境未启用。

5.12 服务配置模板：host.v1 与 intercept.v1

除进程配置外，OpenZiti 的"服务"还携带两类 JSON 配置：host.v1 定义服务端如何承载真实服务，intercept.v1 定义客户端如何拦截流量。二者由 ziti create config <名> <类型> '<json>' 直接创建为服务配置实体，实测命令（端到端 HTTP 200 验证通过）：

ziti create config webtest-host host.v1 '{"protocol":"tcp","address":"127.0.0.1","port":8000}'
ziti create config webtest-int intercept.v1 '{"protocols":["tcp"],"addresses":["webtest.svc.ziti"],"portRanges":[{"low":80,"high":80}]}'

字段	配置类型	实测值	说明
protocol / protocols	host.v1 / intercept.v1	tcp	承载与拦截的传输层协议
address / addresses	host.v1 / intercept.v1	127.0.0.1 / webtest.svc.ziti	承载目标为本机地址；拦截地址为客户端侧虚拟域名（由隧道器内置 DNS 解析到 TUN 网段）
port / portRanges	host.v1 / intercept.v1	8000 / 80~80	承载目标端口；拦截的端口范围

⚠️ 注意：host.v1 若使用 forwardAddress: true 等透明转发字段会触发 if/then 模式校验（要求配套 allowedProtocols 等字段一起出现），最小可用写法就是上面的静态 protocol/address/port 组合，实测直接通过校验并完成拨号。

六、生产配置模板

适用场景：单节点 controller（1 副本 Raft）+ 单边缘路由器 + 若干隧道器的中小规模部署（几十个身份、服务以内），2 核 CPU、8GB 内存、50GB 磁盘起步；数据目录（raft）与证书目录建议随系统盘或独立数据盘持久化。以下模板在实测配置基础上加了行内注释，可直接替换证书路径与主机名后使用。

# ===== /opt/ziti/controller/controller.yaml =====
v: 3

cluster:
  dataDir: "/opt/ziti/controller/raft"   # Raft 数据目录，务必持久化与备份

identity:
  cert:        "/opt/ziti/controller/pki/ziti-srv/certs/server.chain.pem"
  server_cert: "/opt/ziti/controller/pki/ziti-srv/certs/server.chain.pem"
  key:         "/opt/ziti/controller/pki/ziti-srv/keys/server.key"
  ca:          "/opt/ziti/controller/pki/ziti-srv/certs/ziti-srv.chain.pem"

ctrl:
  options:
    advertiseAddress: tls:ziti-srv:6262  # 路由器回连地址，需全网可达
  listener:         tls:0.0.0.0:6262

healthChecks:
  boltCheck:
    interval: 30s
    timeout: 20s
    initialDelay: 30s

edge:
  api:
    sessionTimeout: 30m                  # 会话超时，按安全策略可收紧
    address: ziti-srv:1280               # 必须与下方 bindPoints[].address 一致
  enrollment:
    signingCert:
      cert: /opt/ziti/controller/pki/ziti-srv/certs/ziti-srv.cert
      key:  /opt/ziti/controller/pki/ziti-srv/keys/ziti-srv.key
    edgeIdentity:
      duration: 180m                     # 注册 JWT 有效期，可按需缩短
    edgeRouter:
      duration: 180m

web:
  - name: client-management
    bindPoints:
      - interface: 0.0.0.0:1280
        address: ziti-srv:1280
    identity:
      ca:          "/opt/ziti/controller/pki/ziti-srv/certs/ziti-srv.chain.pem"
      key:         "/opt/ziti/controller/pki/ziti-srv/keys/server.key"
      server_cert: "/opt/ziti/controller/pki/ziti-srv/certs/server.chain.pem"
      cert:        "/opt/ziti/controller/pki/ziti-srv/certs/server.chain.pem"
    options:
      idleTimeout: 5000ms
      readTimeout: 5000ms
      writeTimeout: 100000ms
      minTLSVersion: TLS1.2
      maxTLSVersion: TLS1.3
    apis:
      - binding: edge-management
        options: { }
      - binding: edge-client
        options: { }
      - binding: fabric
        options: { }
      - binding: edge-oidc
        options: { }

# ===== /opt/ziti/router/ziti-er1.yaml =====
v: 3

identity:
  cert:             "/opt/ziti/router/ziti-er1.cert"
  server_cert:      "/opt/ziti/router/ziti-er1.server.chain.cert"
  key:              "/opt/ziti/router/ziti-er1.key"
  ca:               "/opt/ziti/router/ziti-er1.cas"

ctrl:
  endpointsFile:    /opt/ziti/router/endpoints.yml   # enroll 自动生成

link:
  dialers:
    - binding: transport
  listeners:
    - binding:       transport
      bind:          tls:0.0.0.0:10080
      advertise:     tls:ziti-srv:10080           # 多路由器组网时需全网可达
      options:
        outQueueSize: 4

listeners:
  - binding: edge
    address: tls:0.0.0.0:3022
    options:
      advertise: ziti-srv:3022
      connectTimeoutMs: 5000
      getSessionTimeout: 60
  - binding: tunnel
    options:
      mode: host                                 # host 或 tproxy

edge:
  csr:
    country: US
    province: NC
    locality: Charlotte
    organization: NetFoundry
    organizationalUnit: Ziti
    sans:
      dns:
        - localhost
        - ziti-srv
      ip:
        - "127.0.0.1"
        - "::1"

forwarder:
  latencyProbeInterval: 0
  xgressDialQueueLength: 1000
  xgressDialWorkerCount: 128
  linkDialQueueLength: 1000
  linkDialWorkerCount: 32

metrics:
  reportInterval: 1m
  messageQueueSize: 10

本环境各进程实测内存基线（ps -eo rss,pid,args，KiB）：

进程	RSS	说明
ziti controller run	164020（约 160 MB）	含 Raft 存储与全部 Edge API
ziti router run	84728（约 83 MB）	空载单路由器
ziti-edge-tunnel（二进制方式）	17624（约 17 MB）	单身份
ziti-edge-tunnel（软件包方式）	16344（约 16 MB）	systemd 服务，身份目录方式

💡 说明：扩容 HA 集群（3 节点 controller）时，每增加一个节点按约 200 MB 预留；路由器数量增多主要消耗 controller 的连接与订阅内存，按每路由器 20~50 MB 经验预留并观察。

七、常见问题

Q1：生成的配置里证书路径变成 //raft、/ziti-srv.key 这种空根路径

ziti create config 按环境变量 ZITI_HOME 展开路径，未设置时占位符为空。实测启动报错：

unable to load identity (no file found at [/opt/ziti/controller/ziti-srv.key] but a new key spec was not provided)

解决：export ZITI_HOME=/opt/ziti/controller 后重新生成配置，并核对 5.2 节的证书路径。

Q2：controller 启动即退出，日志只有 identity 加载失败

配置中的证书路径与磁盘实际文件不一致（常见于手工改路径后漏改 key 或 ca）。逐项核对 identity 四字段指向的文件是否都存在：

ls -l /opt/ziti/controller/pki/ziti-srv/certs/ /opt/ziti/controller/pki/ziti-srv/keys/

Q3：修改了配置文件但参数没有变化

配置仅启动时读取，systemctl restart ziti-controller（或 ziti-router）后用 3.3 节的 showOptions 日志行核对；确认重启的是对应服务而不是只重启了另一个组件。

Q4：host.v1 服务配置创建失败，提示 if/then 校验

forwardAddress/forwardProtocol 等字段是条件字段，必须成组出现（并搭配 allowed* 字段）；静态写法 {protocol,address,port} 无此依赖，见 5.12 节实测。

八、参考链接

控制器配置参考（controller.yaml 全参数）：https://netfoundry.io/docs/openziti/reference/configuration/controller/
路由器配置参考（router 配置全参数）：https://netfoundry.io/docs/openziti/reference/configuration/router/
HA 引导证书与 SPIFFE 信任域文档：https://netfoundry.io/docs/openziti/reference/ha/bootstrapping/certificates
ziti v2.0.8 发布页：https://github.com/openziti/ziti/releases/tag/v2.0.8
站内相关文档：《OpenZiti 介绍与选型指南》、《Ubuntu 22.04 安装 OpenZiti 指南》、《OpenZiti 2.0.8 常用 CLI 命令详解（ziti CLI）》