OpenZiti 2.0.8 常用 CLI 命令详解（ziti CLI）

OpenZiti v2.0.8 两套 CLI 实测详解：ziti 管理命令（login/list/create/update/delete/pki/agent 集群/fabric/ops/policy-advisor）与 ziti-edge-tunnel 隧道命令的子命令、参数与真实回显。

OpenZiti零信任VPN安全网络配置2026/10/21

OpenZiti 2.0.8 常用 CLI 命令详解（ziti CLI）

目标：给出 OpenZiti v2.0.8 日常管理所需的两套命令行工具（ziti 与 ziti-edge-tunnel）的子命令结构、常用参数与实测回显，覆盖登录、实体增删改查、PKI 签发、HA 集群与策略诊断。全部命令与回显均在 Ubuntu 22.04.5 服务器（ziti v2.0.8）实测通过。

一、环境信息

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

项目值
操作系统Ubuntu 22.04.5 LTS（x86_64）
主机名 / 地址ziti-srv / 10.89.57.2（内网静态地址，请按实际替换）
ziti CLI 版本v2.0.8（revision 8dce94600e8c，2026-10-08 构建）
ziti-edge-tunnel 版本v1.18.7
controller 地址tls:ziti-srv:6262（集群通道）、ziti-srv:1280（Edge API）
实体1 controller + 1 edge router（ziti-er1）+ 4 个隧道身份 + 1 个服务 webtest
登录管理员账号 admin（口令以变量传入，不写入命令历史）

二、工具概览

OpenZiti 交付两个独立的命令行工具，分工如下：

工具安装来源管理对象通信方式
ziti官方二进制包 / APT 包 ziticontroller 上的实体（身份、服务、策略、路由器）、PKI、HA 集群、本机 ziti 进程REST API（需 login）+ 本机 IPC agent（unix socket）
ziti-edge-tunnel二进制 zip / APT 包 ziti-edge-tunnel本机隧道器进程：注册身份、启停身份、查看会话与服务本机 IPC（无需登录 controller）

2.1 ziti 顶层命令一览

ziti --help 实测输出（v2.0.8）：

'ziti' is a CLI for working with a Ziti deployment.

Usage:
  ziti [command]

Available Commands:
  agent        Interact with ziti processes using the the IPC agent
  completion   Generate the autocompletion script for the specified shell
  controller   Ziti Controller
  create       creates various entities managed by the Ziti Controller
  delete       deletes various entities managed by the Ziti Controller
  demo         Demos and examples for learning about Ziti
  edge         Manage the Edge components of a Ziti network using the Ziti Edge REST API
  fabric       Manage the Fabric components of a Ziti network using the Ziti Fabric REST and WebSocket APIs
  help         Help about any command
  list         lists various entities managed by the Ziti Controller
  login        logs into a Ziti Edge Controller instance
  ops          Various utilities useful when operating a Ziti network
  pki          Manage a Ziti PKI
  router       Ziti Router
  update       updates various entities managed by the Ziti Controller
  version      Show component version

Flags:
  -h, --help      help for ziti
  -v, --version   version for ziti

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

💡 技术拓展：与 v1 相比，v2.0 的 CLI 有两处结构变化——ziti list/ziti create/ziti update/ziti delete 从 ziti edge controller ... 提升为顶层命令；v1 的 ziti controller init 被移除，引导改用 ziti agent cluster init（见六、常见问题 1）。

ziti version -v 实测（查看构建信息）：

Version:      v2.0.8
Revision:     8dce94600e8c
Build Date:   2026-10-08T16:22:12Z
Go Version:   go1.27.1
OS/Arch:      linux/amd64

2.2 ziti-edge-tunnel 命令一览

ziti-edge-tunnel --help 实测输出（v1.18.7，节选常用部分）：

ziti-edge-tunnel: Ziti Tunnel App
usage: ziti-edge-tunnel <command> [<args>]

Available commands:
  ziti-edge-tunnel
    enroll              enroll Ziti identity
    run                 run Ziti tunnel (required superuser access)
    run-host            run Ziti tunnel to host services
    on_off_identity     enable/disable the identities information
    enable              enable the identities information
    dump                dump the identities information
    ip_dump             dump ip stack information
    submit_mfa          Submit MFA code to authenticate to the controller
    generate_mfa_codes  Generate MFA codes
    get_mfa_codes       Get MFA codes
    tunnel_status       Get Tunnel Status
    refresh             refresh identity
    delete              delete the identities information
    add                 enroll and load the identity
    set_log_level       Set log level of the tunneler
    update_tun_ip       Update tun ip of the tunneler
    version             show version
    help                this message

三、前置条件

  1. 已按《Ubuntu 22.04 安装 OpenZiti 指南》完成安装，controller/router 处于运行状态；
  2. controller 的 Edge API（ziti-srv:1280）可从执行 CLI 的机器访问；
  3. 拥有管理员账号（首次由 ziti agent cluster init 创建，见 4.6 节）；
  4. CLI 命令的登录态保存在 ~/.config/ziti/ziti-cli.json，证书缓存在 ~/.config/ziti/certs/。

四、各工具详解

4.1 登录：ziti login

ziti login 用于与 controller 的 Edge API 建立会话。常用参数实测（ziti login --help 节选）：

Usage:
  ziti login my.controller.hostname[:port]/path [flags]

Available Commands:
  forget      removes stored credentials for a given identity
  use         changes which saved login to use with a Ziti Edge Controller instance

Flags:
      --ca string                 additional root certificates used by the Ziti Edge Controller
  -i, --cli-identity string       Specify the saved identity you want the CLI to use when connect to the controller with
  -c, --client-cert string        A certificate used to authenticate
  -k, --client-key string         The key to use with certificate authentication
  -e, --ext-jwt string            A file containing a JWT from an external provider to be used for authentication
  -f, --file string               An identity file to use for authentication
  -n, --network-identity string   The identity to use to connect to the OpenZiti overlay
  -j, --output-json               Output the full JSON response from the Ziti Edge Controller
  -p, --password string           password to use for authenticating to the Ziti Edge Controller, if -u is supplied and -p is not, a value will be prompted for
      --read-only                 marks this login as read-only. Note: this is not a guarantee that nothing can be changed on the server. Care should still be taken!
  -t, --token string              if an api token has already been acquired, it can be set in the config with this option. This will set the session to read only by default
  -u, --username string           username to use for authenticating to the Ziti Edge Controller
  -y, --yes                       If set, responds to prompts with yes. This will result in untrusted certs being accepted or updated.

登录实测（口令经变量 PASS 传入，文档中以 ${PASS} 占位；首次登录因使用自签证书需 -y 接受）：

ziti login ziti-srv:1280 -u admin -p "${PASS}" -y

Untrusted certificate authority retrieved from server
Verified that server supplied certificates are trusted by server
Server supplied 2 certificates
Server certificate chain written to /root/.config/ziti/certs/ziti-srv_1280
Saving identity 'default' to /root/.config/ziti/ziti-cli.json

登录成功后凭据保存为配置文件中的 default 身份，后续所有 REST 类命令（list/create/update/delete/edge/fabric）自动携带该会话。ziti login use <名> 可切换多套保存的登录，ziti login forget <名> 删除；--read-only 与 -t <token> 方式登录的会话默认只读。

4.2 实体查询：ziti list

ziti list 是 v2.0 的顶层查询命令（别名 ls），覆盖 Edge 与 Fabric 全部实体。ziti list --help 实测的子命令列表（节选）：

lists various entities managed by the Ziti Controller

Usage:
  ziti list [command]

Aliases:
  list, ls

Available Commands:
  api-sessions                  lists api-sessions managed by the Ziti Edge Controller
  auth-policies                 lists auth-policies managed by the Ziti Edge Controller
  circuits                      lists circuits managed by the Ziti Controller
  configs                       lists configs managed by the Ziti Edge Controller
  edge-router-policies          lists edge-router-policies managed by the Ziti Edge Controller
  edge-routers                  lists edge routers managed by the Ziti Edge Controller
  identities                    lists identities managed by the Ziti Edge Controller
  links                         lists links managed by the Ziti Controller
  service-policies              lists service-policies managed by the Ziti Edge Controller
  services                      lists services managed by the Ziti Edge Controller
  ...（另有 authenticators/cas/enrollments/posture-checks/transit-routers 等）

身份列表实测（ziti list identities）：

╭────────────┬───────────┬─────────┬────────────┬─────────────╮
│ ID         │ NAME      │ TYPE    │ ATTRIBUTES │ AUTH-POLICY │
├────────────┼───────────┼─────────┼────────────┼─────────────┤
│ TIpfGr0EB- │ ziti-tun2 │ Default │ dialers    │ Default     │
│ X1fqRSZEB- │ ziti-er1  │ Router  │            │ Default     │
│ klPaqKFvS  │ ziti-srv  │ Default │            │ Default     │
│ qqVxRSZwf  │ ziti-tun4 │ Default │ dialers    │ Default     │
│ vzmuGrZEB  │ ziti-tun3 │ Default │ dialers    │ Default     │
│ z-AqRSZEB  │ ziti-tun1 │ Default │ dialers    │ Default     │
╰────────────┴───────────┴─────────┴────────────┴─────────────╯
results: 1-6 of 6

服务列表实测（ziti list services）：

╭────────────────────────┬─────────┬────────────┬─────────────────────┬────────────╮
│ ID                     │ NAME    │ ENCRYPTION │ TERMINATOR STRATEGY │ ATTRIBUTES │
│                        │         │ REQUIRED   │                     │            │
├────────────────────────┼─────────┼────────────┼─────────────────────┼────────────┤
│ 5ns6cgf8tyRZe6UUn7mUhb │ webtest │ true       │ smartrouting        │ webtest    │
╰────────────────────────┴─────────┴────────────┴─────────────────────┴────────────╯
results: 1-1 of 1

💡 说明：ziti list <实体> -j 输出完整 JSON（含原始数据模型字段），脚本化处理建议用该形态；表格形态每页最多 25 条，底部 results 行显示总条数。

4.3 实体创建：ziti create

ziti create 的子命令实测列表（节选）：

Available Commands:
  auth-policy                creates an authentication policy managed by the Ziti Edge Controller
  ca                         creates a ca managed by the Ziti Edge Controller
  config                     creates a config managed by the Ziti Edge Controller
  edge-router                creates an edge router managed by the Ziti Edge Controller
  edge-router-policy         creates an edge-router-policy managed by the Ziti Edge Controller
  identity                   creates a new identity managed by the Ziti Edge Controller
  service                    creates a service managed by the Ziti Edge Controller
  service-edge-router-policy creates a service-edge-router-policy managed by the Ziti Edge Controller
  service-policy             creates a service-policy managed by the Ziti Edge Controller
  terminator                 creates a service terminator managed by the Ziti Controller
  transit-router             creates a transit router managed by the Ziti Edge Controller

创建身份的用法与参数实测（ziti create identity --help，注意 v2 中不再接受类型参数，只接名称）：

creates a new identity managed by the Ziti Edge Controller

Usage:
  ziti create identity <name> [flags]

Flags:
  -A, --admin                                Give the new identity admin privileges
  -P, --auth-policy string                   The name or id of the auth policy to assign to the identity (default "default")
  -c, --default-hosting-cost uint16          Default cost to use when hosting services using this identity
  -p, --default-hosting-precedence string    Default precedence to use when hosting services using this identity [default,required,failed]
  -o, --jwt-output-file string               File to which to output the JWT used for enrolling the identity
      --permissions strings                  comma-separated permissions for the new identity
  -a, --role-attributes strings              comma-separated role attributes for the new identity
      --updb string                          username to give the identity, will create a UPDB enrollment

本环境实际执行过的创建命令与回显（属性 -a dialers 供拨号策略按 #dialers 圈选）：

ziti create identity ziti-tun1 -a dialers -o $ZITI_HOME/ziti-tun1.jwt
ziti create edge-router ziti-er1 -t -o $ZITI_HOME/ziti-er1.jwt

New identity ziti-tun1 created with id: z-AqRSZEB
Enrollment expires at 2026-10-20T18:57:11.566Z

New edge router ziti-er1 created with id: X1fqRSZEB-
Enrollment expires at 2026-10-20T19:49:32.838Z

服务配置的创建走 ziti create config，用法实测：

Usage:
  ziti create config <name> <type> [JSON configuration data] [flags]
  ziti create config [command]

Available Commands:
  controller  creates a controller config file
  environment display config environment variables
  router      creates a config file for specified router name

Flags:
  -f, --json-file string         Read config JSON from a file instead of the command line

两种形态共存：ziti create config <名> <类型> '<json>' 创建 controller 上的服务配置实体（host.v1/intercept.v1，见《OpenZiti 2.0.8 配置参数详解》5.12 节）；ziti create config controller|router 生成本地进程配置文件模板（注意需先 export ZITI_HOME，否则生成空根路径）。

⚠️ 注意：策略四件套（service-policy、edge-router-policy、service-edge-router-policy 与 service）的完整创建实测链路见《Ubuntu 22.04 安装 OpenZiti 指南》7.2 节；v2.0 默认不自动创建 any-of 策略，漏建会导致拨号报 NO_EDGE_ROUTERS_AVAILABLE。

4.4 实体更新与删除：ziti update / ziti delete

两个命令与 ziti create 同构，均按"子命令=实体类型"组织。ziti update --help 实测子命令（节选）：identity、service、edge-router、edge-router-policy、service-policy、service-edge-router-policy、config、ca、auth-policy、link 等；ziti delete --help 实测子命令（节选）：identity、service、edge-router、edge-router-policy、service-policy、config、ca、circuit、link、enrollment 等。

常用操作形态（以身份为例，实测参数名）：

ziti update identity ziti-tun1 -a dialers,vpn-clients   # 追加角色属性
ziti delete identity ziti-tun3                          # 按名称删除

💡 说明：删除身份不会自动吊销其已签发证书；需吊销场景配合 ziti delete authenticator 或重新签发。路由器删除前先停其进程，否则 controller 会持续尝试重连。

4.5 PKI 管理：ziti pki

ziti pki create 的子命令实测：

Available Commands:
  ca           Creates new Certificate Authority (CA) certificate
  client       Creates new Client certificate (signed by previously created Intermediate-chain)
  csr          Creates new Certificate Signing Request (CSR)
  intermediate Creates new Intermediate-chain certificate (signed by previously created CA)
  key          Creates new private key (to be used when creating server/client certs)
  server       Creates new Server certificate (signed by previously created Intermediate-chain)

ziti pki create ca 的完整参数实测（节选）：

Usage:
  ziti pki create ca [flags]

Flags:
      --ca-file string                   Dir/File name (within PKI_ROOT) in which to store new CA
      --ca-name string                   Name of CA (default "NetFoundry Inc. Certificate Authority")
      --curve string                     If set an EC private key is generated and -private-key-size is ignored, options: P224, P256, P384, P521
      --expire-limit int                 Expiration limit in days (default 3650)
      --max-path-len int                 Intermediate maximum path length (default -1)
      --pki-country string               Country (default "US")
      --pki-locality string              Locality/Location (default "Charlotte")
      --pki-organization string          Organization (default "NetFoundry")
      --pki-organizational-unit string   Organization unit (default "ADV-DEV")
      --pki-province string              Province/State (default "NC")
      --pki-root string                  Directory in which PKI resides
      --private-key-size int             Size of the RSA private key, ignored if -curve is set (default 4096)
      --trust-domain string              An optional spiffe trust domain. spiffe:// will be automatically prefixed, if not provided

本环境按"根 CA → 中级 → server/client"链签发的实际命令（v2.0 controller 证书需携带 SPIFFE URI SAN，--trust-domain 自动为 SPIFFE ID 加前缀）：

export PKI_ROOT=$ZITI_HOME/pki
ziti pki create ca --pki-root "$PKI_ROOT" --ca-name root-ca --trust-domain ziti.example.com
ziti pki create intermediate --pki-root "$PKI_ROOT" --ca-name ziti-srv --intermediate-name ziti-srv --ca-file root-ca
ziti pki create server --pki-root "$PKI_ROOT" --ca-name ziti-srv --server-name ziti-srv \
  --server-file ziti-srv --dns localhost,ziti-srv --ip 127.0.0.1,::1

⚠️ 注意：同一 PKI_ROOT 下重复执行同名签发会报 File exists（证书库串号），排障见《Ubuntu 22.04 安装 OpenZiti 指南》第八节。

4.6 进程代理与 HA 集群：ziti agent

ziti agent 通过本机 unix socket 与 ziti 进程通信，不经过 REST API，是引导集群（此时还没有管理员账号可登录）和排障的通道。子命令实测：

Available Commands:
  cluster                 Manage an HA controller cluster using the IPC agent
  controller              Interact with a ziti controller process using the IPC agent
  dump-heap               Dumps the heap to the specified file path
  gc                      Run garbage collection in the target application
  goversion               Returns the golang version of the target application
  inspect                 Inspect local runtime state of the target process
  list                    List ziti processes
  memstats                Returns memory use summary of the target application
  pprof-cpu               Runs and emits a 30 second pprof from the target application
  pprof-heap              Returns a memory heap pprof of the target application
  ps                      Show Ziti process info
  router                  Interact with a ziti router process using the IPC agent
  set-log-level           Sets the global logrus logging level in the target application
  stack                   Emits a go-routine stack dump from the target application
  stats                   Emits some runtime information (# go-routines, threads, cpus, etc) from the target application
  tunnel                  Interact with a ziti tunnel process using the IPC agent

ziti agent list 实测（列出本机全部 ziti 进程，PID 即后续 -i 的定位依据之一）：

╭──────┬────────────┬────────────┬───────────────────────────┬────────────┬─────────────┬───────────╮
│  PID │ EXECUTABLE │ APP ID     │ UNIX SOCKET               │ APP TYPE   │ APP VERSION │ APP ALIAS │
├──────┼────────────┼────────────┼───────────────────────────┼────────────┼─────────────┼───────────┤
│ 4160 │ ziti       │ ziti-srv   │ /tmp/gops-agent.4160.sock │ controller │ v2.0.8      │           │
│ 6376 │ ziti       │ X1fqRSZEB- │ /tmp/gops-agent.6376.sock │ router     │ v2.0.8      │           │
╰──────┴────────────┴────────────┴───────────────────────────┴────────────┴─────────────┴───────────╯

ziti agent cluster 的子命令实测：

Available Commands:
  add                 adds a node to the controller cluster
  init                Initializes a cluster with a default administrator
  list                lists the nodes in the controller cluster
  remove              removes a node from the controller cluster
  restore-from-db     Restores a cluster to the state in the given database snapshot
  transfer-leadership triggers a new leader election in the controller cluster, optionally selecting a new preferred leader

单节点集群状态实测（ziti agent cluster list -i ziti-srv；本机同时跑 controller 与 router，必须用 -i <控制器ID> 指定目标进程）：

╭──────────┬───────────────────┬───────┬────────┬─────────┬───────────┬───────────╮
│ ID       │ ADDRESS           │ VOTER │ LEADER │ VERSION │ CONNECTED │ PREFERRED │
├──────────┼───────────────────┼───────┼────────┼─────────┼───────────┼───────────┤
│ ziti-srv │ tls:ziti-srv:6262 │ true  │ true   │ v2.0.8  │ true      │ false     │
╰──────────┴───────────────────┴───────┴────────┴─────────┴───────────┴───────────╯

v2.0 集群引导命令（controller 启动后执行一次；用法 ziti agent cluster init <用户名> <口令> <集群节点ID>）：

ziti agent cluster init admin "${PASS}" ziti-srv

扩容 HA 时在新节点上先启动 controller，再在任一存活节点执行 ziti agent cluster add，缩容用 ziti agent cluster remove，主节点迁移用 ziti agent cluster transfer-leadership。

💡 技术拓展：ziti agent inspect <路径>、ziti agent stack、ziti agent memstats 可对运行中进程做运行时快照，无需重启服务；set-log-level 可临时调日志级别（如 debug），重启后恢复配置文件设定值。

4.7 fabric 管理：ziti fabric

ziti fabric 操作 overlay 数据面的链路与电路。子命令实测：

Available Commands:
  create      creates various entities managed by the Ziti Controller
  db          Database management operations for the Ziti Edge Controller
  delete      deletes various entities managed by the Ziti Controller
  inspect     Inspect runtime <application> <values>
  list        Lists various entities managed by the Ziti Controller
  stream      stream fabric operational data
  update      update various entities managed by the Ziti Controller
  validate    validate model data

链路与电路列表实测（当前无活动连接时的空表，表头即字段说明）：

ziti fabric list links
╭────┬────────┬──────────┬─────────────┬─────────────┬─────────────┬───────┬────────┬───────────┬─────────────╮
│ ID │ DIALER │ ACCEPTOR │ STATIC COST │ SRC LATENCY │ DST LATENCY │ STATE │ STATUS │ FULL COST │ CONNECTIONS │
├────┼────────┼──────────┼─────────────┼─────────────┼─────────────┼───────┼────────┼───────────┼─────────────┤
╰────┴────────┴──────────┴─────────────┴─────────────┴─────────────┴───────┴────────┴───────────┴─────────────╯
results: none

ziti fabric list circuits
╭────┬────────┬─────────┬────────────┬───────────┬──────╮
│ ID │ CLIENT │ SERVICE │ TERMINATOR │ CREATEDAT │ PATH │
├────┼────────┼─────────┼────────────┼───────────┼──────┤
╰────┴────────┴─────────┴────────────┴───────────┴──────╯
results: none

💡 说明：circuit 是一次端到端拨号建立的转发路径，HTTP 短连接场景下电路随连接结束即时消失，排查时应在业务流量进行中执行 ziti fabric list circuits；ziti fabric stream circuits 可持续观察电路建立/关闭事件。

4.8 运维工具集：ziti ops

ziti ops 实测子命令：

Available Commands:
  cluster     Controller cluster operations
  db          Management operations for OpenZiti databases and database files
  log-format  Transform pfxlog output into a human readable format
  unwrap      unwrap a Ziti Identity file into its separate pieces (supports PEM only)
  verify      a group of commands used to verify an overlay is setup properly

常用场景：ziti ops unwrap <identity文件> 把注册好的身份 JSON 拆成独立 cert/key 文件（给不支持 identity 文件的组件用）；ziti ops db backup 做数据备份；ziti ops log-format 把 JSON 日志流转为可读格式（配合管道使用）。

4.9 策略诊断：ziti edge policy-advisor

拨号不通（NO_EDGE_ROUTERS_AVAILABLE/no terminators）时的首选诊断命令。ziti edge policy-advisor identities 实测输出（诊断规则说明部分之后的结果行，节选）：

OKAY : ziti-tun4 (1) -> webtest (1) Common Routers: (1/1) Dial: Y Bind: N

OKAY : ziti-tun3 (1) -> webtest (1) Common Routers: (1/1) Dial: Y Bind: N

OKAY : ziti-tun1 (1) -> webtest (1) Common Routers: (1/1) Dial: Y Bind: N

结果行格式：STATUS: 身份 (身份可用路由数) -> 服务 (服务可用路由数) Common Routers: (在线公共路由/公共路由) Dial: 是否可拨 Bind: 是否可绑。状态为 ERROR 时会附 ERROR_LIST，实测中出现过：

  - Identity does not have access to any services. Adjust service policies.

即身份未被任何 Dial 类型 service-policy 覆盖，补建策略（ziti create service-policy）后重跑 advisor 复核。

4.10 隧道器命令：ziti-edge-tunnel

注册身份实测（ziti-edge-tunnel enroll -h 的参数说明，节选）：

usage: ziti-edge-tunnel enroll ( -u|--url <controller URL> | -j|--jwt <enrollment token> ) -i|--identity <identity> [-E|--enroll-to none|cert|token] [-n|--name <name>]

        -u|--url        controller URL for enrollment (requires 3rd party IDP for auth)
        -j|--jwt        enrollment token file, or network JWT when used with -u
        -E|--enroll-to  enrollment mode for -u: none (bootstrap only), cert (OIDC + certificate), token (OIDC + token)
        -i|--identity   output identity file
        -n|--name       identity name
        -v|--verbose N  set log level, higher level -- more verbose (default 3)

典型流程：ziti-edge-tunnel enroll -j <jwt文件> -i <输出identity文件> 注册，ziti-edge-tunnel run -i <identity文件> 运行；软件包形态则用 ziti-edge-tunnel add id <jwt路径> 注册到身份目录并由 systemd 托管。

ziti-edge-tunnel version 实测：

v1.18.7

ziti-edge-tunnel dump 实测（单身份运行时状态，JSON 包裹的长文本，节选关键段）：

======= Application Info ==========
Application:    ziti-edge-tunnel@v1.18.7
ziti-sdk: 1.18.7(gabc980e) Aug 19 2026 19:58:01

Ziti Context:
ID: 1
enabled[true] uptime[1127s]
Config Source:  /opt/openziti/etc/identities/ziti-tun2.json
...
Controller[HA]: [v2.0.8] https://ziti-srv:1280/edge/client/v1
        ziti-srv: online[Y] https://ziti-srv:1280/edge/client/v1
Identity:       ziti-tun2[TIpfGr0EB-]
...
Services:
webtest: id[5ns6cgf8tyRZe6UUn7mUhb] perm(dial=true,bind=false)
        config[intercept.v1]={ "addresses": [ "webtest.svc.ziti" ], "portRanges": [ { "high": 80, "low": 80 } ], "protocols": [ "tcp" ] }
        config[host.v1]={ "address": "127.0.0.1", "port": 8000, "protocol": "tcp" }
...
Channels:
ch[0] ziti-er1
        connected[Y] version[v2.0.8|8dce94600e8c|2026-10-08T16:22:12Z|linux|amd64] address[tls://ziti-srv:3022] latency[0] connected[358s]

从 dump 可读出：身份启用状态、controller 在线判定、可见服务与两类配置、到路由器的通道连接状态。排障时先看 Channels 段的 connected[Y/N]，再对照 Services 段的 perm 与策略诊断（4.9 节）。

⚠️ 注意：隧道器没有 list services 这类子命令，误用会报 ziti-edge-tunnel: list: unknown command（实测）；查看身份与服务信息一律用 dump（或 ip_dump 看拦截 IP 映射）。

五、注意事项

  1. 口令安全：-p 直接跟在命令行会被 shell history 记录，建议 read -s PASS 后用 ${PASS} 引用，或省略 -p 让 CLI 交互式提示输入；
  2. 登录态隔离：~/.config/ziti/ziti-cli.json 保存了会话令牌，多管理员共用跳板机时注意文件权限（建议 600），只读审查用 ziti login --read-only；
  3. agent 命令的作用域：ziti agent ... 只能操作与本机 unix socket 同 PID 空间的进程，管理远程节点需在目标节点执行（或经 SSH）；
  4. 表格输出的分页：ziti list 每页 25 条，翻页用 --limit/--offset 参数确认总条数后再脚本化；
  5. 版本一致性：controller、router、tunneler 三组件版本允许小版本差异，但同批升级可避免 SDK 兼容问题（本文环境三组件同为 v2.0.x 系列）。

六、常见问题

Q1：ziti controller init 命令不存在

v2.0 移除了 v1 的引导命令（ziti controller --help 中无 init），改为启动 controller 后执行 ziti agent cluster init <用户名> <口令> <节点ID>；v1 教程照抄会一直停在"controller 未初始化"日志（实测日志特征：has not yet been initialized）。

Q2：ziti create identity device <名称> 报错

v1 的 ziti create identity <类型> <名称> 双参数用法已废弃，v2 只接受单个名称参数，旧写法实测报错并返回退出码 1：

accepts 1 arg(s), received 2

改为 ziti create identity <名称> -a <属性>，身份类型由使用方式（是否绑定 Router 角色）决定。

Q3：ziti agent cluster list 报 too many processes found

本机同时运行 controller 与 router（或多个 ziti 进程）时，agent 无法从进程列表唯一确定目标，实测报错：

too many processes found matching filter: [4160 6376] use 'ziti agent list' for more information

先 ziti agent list 拿到 APP ID，再用 -i <APP ID> 指定目标：ziti agent cluster list -i ziti-srv。

Q4：ziti list xxx 报连接被拒或 401

未登录或会话过期。重新 ziti login ziti-srv:1280 -u admin -p "${PASS}" -y；若 controller 证书更换过，先 ziti login forget 清理旧凭据再登录。

Q5：policy-advisor 显示 ERROR 但策略刚建好

策略写入与数据模型同步有 20~40 秒延迟窗口（实测），等待后重跑；仍 ERROR 时按 ERROR_LIST 逐项补策略，或核对服务与身份的角色标签是否匹配（# 开头为服务/身份属性，@ 开头为具名实体）。

七、参考链接

  1. HA 集群初始化文档（ziti agent cluster init）：https://openziti.io/docs/reference/ha/bootstrapping/initialization/
  2. 控制器配置参考（CLI 相关的 ctrl/edge 段落）：https://netfoundry.io/docs/openziti/reference/configuration/controller/
  3. Linux 隧道器文档（ziti-edge-tunnel 用法）：https://openziti.io/docs/reference/tunnelers/linux/debian-package/
  4. ziti v2.0.8 发布页：https://github.com/openziti/ziti/releases/tag/v2.0.8
  5. 站内相关文档：《OpenZiti 介绍与选型指南》、《Ubuntu 22.04 安装 OpenZiti 指南》、《OpenZiti 2.0.8 配置参数详解》