企业官网建设流程全解析

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

OpenZiti 0.15 是零信任网络 Ziti 的一个里程碑版本：它统一了 Fabric 与 Edge 的实体模型，引入基于 Bolt 事务的数据库快照能力，并把 Edge REST API 全面迁移到 go-swagger 生成的 OpenAPI 2.0 规范之上。本文以官方变更日志 CHANGELOG.0.15.md 为主线，结合当前仓库源码逐项解读新特性、破坏性变更与升级路径，帮助你在升级前评估兼容性影响并掌握新 API 的使用方式。

版本概览与升级路径

0.15 系列共发布三个补丁版本（0.15.0 / 0.15.1 / 0.15.2），随后被 0.16 承接。升级前请先阅读 CHANGELOG.0.15.md 了解完整条目，并注意以下结论：

• 0.15.0 引入了大部分新功能，但删除了从 pre-0.9 版本迁移的代码；若你正运行 pre-0.9 的旧实例，必须先升级到 0.14.12，再升级到 0.15+，否则迁移路径不可用。
• 0.15.1 无新功能，仅修复若干 CLI 与 Edge 后端缺陷（详见下文“0.15.1 修复清单”）。
• 0.15.2 修复若干查询与枚举问题，并新增一个ziti-tunnel的 Docker Compose 示例（quickstart/docker/下可找到对应 compose 文件）。
• 0.15.3 仅追加该 Docker Compose 示例的说明，无代码变更。

数据库快照（Database Snapshots）

0.15.0 引入最重要的运维能力：数据库快照/备份。它有三种触发方式，且该能力仅对管理员开放。

三种触发方式

CLI 的两种实现分别位于 ziti/cmd/fabric/db_snapshot.go 与 ziti/cmd/edge/db_snapshot.go：fabric 版本调用client.Database.CreateDatabaseSnapshotWithPath并支持在参数中指定快照文件路径；edge 版本则通过util.ControllerUpdate("edge", "database/snapshot", "", ..., http.MethodPost, ...)直接向控制器发起 POST 请求。两者均复用api.Options提供的通用 flag（如--output-json、--timeout、--verbose）。

REST 侧由 go-swagger 生成的 handler 承接（create_database_snapshot_with_path.go），请求体为DatabaseSnapshotCreate，其核心字段是Path string \json:"path,omitempty"`（[database_snapshot_create.go](https://link.gitcode.com/i/770e2fb5a3069c0236b29d1a0519dda6)）。当前仓库的 swagger 规范中还可见/database、/database/snapshot、/database/check-data-integrity、/database/fix-data-integrity` 等一组数据库运维端点（swagger.yml），说明快照能力是 0.15 引入的数据库自服务运维体系的一部分。

快照特性

• 一致性：快照在bolt 事务内创建，是对数据库文件的拷贝，因此快照点内数据是自洽一致的。
• 命名：文件名会追加创建时的日期与时间，便于区分多个备份。
• 频率限制：快照创建最多每分钟一次，避免高频触发造成 I/O 压力。
• 存放位置：快照文件落在控制器的文件系统上，而非客户端本地；ziti-fabric snapshot-db传入的路径是控制器侧的目标路径。

值得注意的是，0.15 时代的控制器已具备 Raft 集群能力雏形，快照机制与此相关：当前仓库的 controller/raft/fsm.go 中，BoltDbFsm.Snapshot()通过db.StreamToWriter(gzWriter)将 Bolt 数据库流式写入 gzip 压缩缓冲区，生成 raft 快照；Restore则先从.stage临时文件恢复并比较索引后决定是否应用（fsm.go）。这正是“在 bolt 事务内拷贝数据库文件”的底层实现，也与 0.15 变更日志描述的语义一致。

Edge Router 成为 Fabric Router 的子类型

0.15.0 之前，edge router 与 fabric router 虽然概念相近，但并非同一实体：创建 edge router 时，并不会立即生成对应的 fabric router，要等到 edge router 成功注册（enroll）后才会出现对应实体。

0.15.0 起，edge router 是 fabric router 的一种类型：

• 创建 edge router 时，它会立即以 fabric router 的身份可见，但此时没有 fingerprint（指纹），因此对应的 router 进程在完成 enrollment 前无法连接控制器。
• 这带来的直接收益是：enrollment 完成之前，就可以提前把 terminator（服务终止点）绑定到该 edge router 上，简化了编排流程。
• 该行为与 edge#144 Unverified Edge Routers Cannot Be Used For Terminators 的设计相关，即未验证（未注册）的 edge router 不能用于 terminator，而 0.15 通过统一实体模型提前打通了这条链路。

从当前仓库可以看到，控制器在env层以LockingRouterState.IsOnline维护路由器的在线状态（controller/env/sync.go），并在持久化层把isOnline作为FieldControllerIsOnline布尔字段存储（controller/db/controller_store.go）。这也解释了为什么 0.15.1 修复了 “Policy Advisor CLI 因 routersIsOnline值缺失而失败”（edge#237）——统一实体模型后，isOnline必须在所有查询路径上可用。

Fabric Router 与 Service 引入名称（Name）

0.15.0 之前，fabric router 与 service 只有 id，且假设 id 本身就是用户友好的。0.15.0 为两者增加name 属性：

• 若创建时未提供 name，则name 默认取 id。
• 主要动机是保持 fabric 与 edge 两侧的一致性：查看 service 或 router 时，标签（label）总是在同一个字段位置，便于统一 UI/CLI 展示。

结合 0.15.2 的修复（ziti-fabric list支持查询且默认true limit none），可以推断：name 的引入也为 fabric 侧list查询提供了可检索的标签维度，使 edge 与 fabric 的列表体验对齐。

Edge REST API 增强

0.15.0 的 Edge REST API 改动是为未来功能铺路的预备性变更，官方明确要求客户端仔细阅读并采用新模式，以避免未来不兼容。核心变化如下。

OpenAPI 2.0/Swagger 全面接管

Edge REST API 的 REST 呈现现已完全由edge/spec中的 OpenAPI 2.0/Swagger 规范生成，生成代码分布在edge/rest_model、edge/rest_server与edge_rest_client（在当前仓库中对应 controller/rest_model、controller/rest_server、controller/rest_client 三棵目录）。生成工具为go-swagger，当时版本为 0.24.0。当前仓库的 controller/specs/swagger.yml 即为该规范的现役版本，可作后续 API 参考。

生成代码引入以下几类影响客户端的变更：

• content-type与accept头变得有意义且重要（详见下文）；
• enrollment 端点在accept头明确指定 JSON 时，可以返回 JSON；
• 引入统一的API 输入校验错误；
• 修复各类entity ref（实体引用 URL）bug；
• id 属性标准化。

Content-Type / Accept 头语义

• 如果客户端未显式设置accept，通常浏览器/库会发送accept: */*（接受一切）。此时 Edge REST API 会保持与旧版本一致的 content-type 返回。
• 但是，enrollment 端点的非 JSON 响应现已标记为 deprecated（弃用），意味着后续版本可能移除纯文本/HTML 形态的 enrollment 响应。
• 若客户端对大多数端点将accept设置为非application/json，API 将返回错误，提示“这些 content type 不可接受”。即：服务端只愿意按 JSON 交付，客户端必须显式声明接受 JSON。

API 输入校验

输入校验改由 OpenAPI 库与 go-swagger 生成代码负责：

• 错误格式大体保持不变；
• 但所有校验错误现在统一返回相同的外层错误结构，并正确设置 cause 错误。
• 此前各端点校验错误的处理方式不一致，0.15 起得到收敛。

Entity Ref Bug 修复

若干实体引用（URL）被修复，此前它们指向错误或无效的 API URL，现在指向正确端点。

Id 属性类型化

id 属性现在完全类型化，命名模式为<type>Id（请求/响应均如此）。受影响的实体：

而IdentityTypeId引用未更新，因为它们已列入移除计划、现已被标记为deprecated：包括/identity-type端点，以及/identity上 create/update/patch 操作的相关属性。

面向 Fabric REST API 的铺垫变更

以下变更是为了未来 Fabric REST API 腾出空间而做的：

• Edge REST API 基础路径移到/edge/v1；
• GET /versions引入apiVersions字段；
• 实体 id 从 UUID 转向shortId。

基础路径：/edge/v1

Edge REST API 的新基础路径是edge/v1。旧基础路径/已 deprecated，但在后续版本之前仍保持可用。这次迁移的目的：为 Fabric REST API 让出根路径，并允许其他组件注册各自 API。因此新客户端应尽快改用/edge/v1前缀。

API 版本：GET /versions引入 apiVersions

GET /versions目前仍由 Edge REST API 处理，但未来会被 Fabric REST API 取代。0.15 起它报告版本信息采用map 结构，便于未来新 REST API 注册各自支持的版本；Ziti REST API 的目标是同时支持多个 API 版本以向后兼容。

0.15.0 实际响应示例：

{ "data": { "apiVersions": { "edge": { "v1": { "path": "/edge/v1" } } }, "buildDate": "2020-06-11 16:03:13", "revision": "95e78d4bc64b", "runtimeVersion": "go1.14.3", "version": "v0.15.0" }, "meta": {} }

未来引入 Fabric REST API 后的理论形态：

{ "data": { "apiVersions": { "edge": { "v1": { "path": "/edge/v1" } }, "fabric": { "v1": { "path": "/fabric/v1" } } }, "buildDate": "2020-06-20 12:43:03", "revision": "1a27ed4bc64b", "runtimeVersion": "go1.14.3", "version": "v0.15.10" }, "meta": {} }

ShortIds：告别 UUID 文本格式

Edge REST API 此前所有 id 均使用 UUID 及其文本格式；0.15 起改用shortId及其格式。设计动机：

• 让 id 更人类友好（日志、肉眼比对更轻松）；
• 统一 Fabric 与 Edge 实体 id 的观感；
• 保持与 UUID 相当的高唯一性。

对客户端最重要的指导原则：所有 Ziti REST API 都将 id 定义为字符串；只要把 id 当作不透明字符串处理，就不会遇到兼容性问题。官方强烈建议所有客户端遵循此模式——不要把 id 当作 UUID 来解析或依赖其内部结构。

0.15.1 修复清单

0.15.1 未引入新功能，仅修复以下缺陷：

• #129：ziti-tunnel enroll在 ERROR 级别输出成功信息（日志级别错位）；
• #131：创建身份（identity）、CA 及 CA 验证流程的问题；
• #133：创建 service edge router policy 时按名称查找 service 失败；
• edge#191：CLI 修改自身密码时报 404 Not Found；
• edge#231：身份（identity）缺失 enrollmentexpiresAt属性；
• edge#237：Policy Advisor CLI 因 routersIsOnline值缺失而失败；
• edge#233：REST API 错误应尽可能返回application/json；
• edge#240：列出 specs 返回 404。

其中 edge#233 与 0.15.0 的 content-type/accept 语义收紧直接呼应：0.15.1 进一步保证错误响应也以 JSON 交付。edge#237 则印证了isOnline在统一实体模型下必须贯穿查询链路（见上文 Edge Router 子类型化一节的源码佐证）。

0.15.2 修复与新增

• #140：允许 Ziti CLI 记录 JSON 格式的请求（便于审计与调试）；
• #148：ziti edge list edge-routers显示isOnline字段；
• #144：ziti-fabric list支持查询语法，默认true limit none（即默认列出全部，不做分页截断）；
• #142：修复 CLIca create未默认设置身份角色的缺陷；
• #146：修复 edge router 超过 10 个时导出 edge router JWT 偶发失败；
• #147：修复使用limit none时分页输出的问题；
• edge#243：会话创建时只返回 10 个 edge router（查询截断缺陷）；
• edge#245：0.14 到 0.15 之间 fingerprint 计算方式变化，确保 0.15 的 router 能与 0.14 的 controller 协作；
• edge#248：网络缓慢且链路众多时，Edge Router Hello 可能超时；
• foundation#103：修复列表型配置项的环境变量注入（config file env injection）。

edge#245 尤其值得关注：0.15 router 与 0.14 controller 混合部署的兼容性被显式保证，这意味着你可以先升级 router 再升级 controller，从而平滑过渡。

其他变更

• 移除废弃代码与迁移逻辑：postgres store 代码及其迁移已删除（edge#195）；废弃的AppWan与Clusters概念被移除，分别由service policies与service edge router policies取代。
• PayloadBuffer 内存泄漏修复：修复PayloadBuffer子系统中的内存增长失控问题，纠正ziti-router中无界的内存增长。这一修复对长期运行的高吞吐路由器至关重要，值得在升级后观察内存曲线验证。
• 二进制外观调整：ziti-enroller与ziti-tunnel的 enroll 子命令输出做了外观性调整（无功能变更）。
• 示例补充：0.15.2/0.15.3 为ziti-tunnel增加 Docker Compose 示例，可直接在 quickstart/docker 中查找使用。

升级建议与兼容性注意事项

综合 0.15 全系列变更，升级时建议重点核对以下清单：

1. 版本跳跃限制：若运行 pre-0.9 版本，必须先升级到 0.14.12，再继续升级，否则旧迁移代码已被删除。
2. API 路径迁移：客户端需将 Edge REST API 请求从根路径迁移到/edge/v1前缀（旧路径暂可用但已废弃）。
3. accept 头声明：客户端应显式设置accept: application/json；enrollment 端点的非 JSON 响应已废弃。
4. id 处理：将 id 视为不透明字符串，不要依赖 UUID 格式；响应/请求字段遵循<type>Id命名。
5. 校验错误：输入校验错误结构已统一，外层错误一致、cause 字段被正确填充，错误处理代码可据此统一。
6. 实体命名：fabric router 与 service 新增name字段（缺省取 id），列表/查询时可使用 name 作为标签。
7. 混合版本部署：0.15 router 可与 0.14 controller 协同（fingerprint 计算已兼容），可按 router→controller 顺序滚动升级。
8. 运维新能力：可利用ziti edge snapshot-db、ziti-fabric snapshot-db或POST /edge/v1/database/snapshot建立定时备份机制，注意快照频率上限为每分钟一次。

结语

0.15 是 OpenZiti 在“边缘与核心实体模型统一”与“REST API 现代化”两条主线上的关键版本：Edge Router 成为 Fabric Router 子类型、Fabric 实体获得 name、数据库快照成为一等运维能力，而 REST API 则在 OpenAPI 2.0 规范下完成了路径、版本与 id 格式的全面重构。这些变更既是功能性增强，也是未来 Fabric REST API 与多版本 API 兼容策略的基石。若你正在升级或编写客户端，本文所述的新模式（/edge/v1、application/json、不透明字符串 id、<type>Id字段）应尽早采纳，以平滑过渡到后续版本。

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