TEN Framework 依赖解析：Mbed TLS 分支架构与版本兼容性策略

本文面向在 TEN Framework 中集成、升级或排查 TLS 相关问题的开发者，围绕仓库自带 Mbed TLS 的分支维护策略文档展开，说明 Mbed TLS 上游的分支划分、语义化版本规则与 API/ABI 兼容性承诺，并结合 third_party/mbedtls 的实际构建配置与 libwebsockets、curl 的集成方式，帮助读者准确判断"当前仓库内 Mbed TLS 处于哪个稳定线、如何安全升级、升级时哪些兼容性承诺可以依赖"。

Mbed TLS 的分支架构：稳定线、开发线与历史线

Mbed TLS 上游通过多条长期维护的分支来组织版本演进，文档 BRANCHES.md 明确了以下分支类型：

• master 分支：始终包含最新发布版本，并持续合入所有公开可用的安全修复。它是"最新稳定可用"的落点。
• development 分支：当前大版本（3.x）的孵化分支，包含相对 2.x 不兼容的 API 变更，也承载新功能、常规缺陷修复与安全修复。
• 长期支持（LTS）分支：只接收缺陷修复与安全修复，不引入新特性。当前官方维护的唯一 LTS 分支是 mbedtls-2.28（文档标注其至少维护到 2024 年底）。
• archive/ 前缀历史分支：如 archive/mbedtls-2.7，仅作历史存档，不再接收任何变更。

对照本仓库实际携带的版本，build_info.h 中定义的版本为 3.2.1（MBEDTLS_VERSION_MAJOR 3、MBEDTLS_VERSION_MINOR 2、MBEDTLS_VERSION_PATCH 1）。也就是说，TEN Framework vendored 的 Mbed TLS 属于文档中所说的 3.x 主线（对应上游 master 稳定线发布版本），而 2.28 LTS 线并未被本仓库采用。这一点可以直接从 output_libs.gni 中 Linux 平台的动态库版本号（如 libmbedtls.so.18、libmbedcrypto.so.12、libmbedx509.so.4，对应 3.2.1 的 soname）得到印证。

语义化版本：API 与 ABI 兼容性的边界

Mbed TLS 遵循语义化版本（Semantic Versioning），其核心承诺可以概括为：

• 同大版本内小版本升级保持 API 兼容：例如 3.x 到 3.(x+1) 之间，已编译通过的代码无需修改即可重新编译运行。
• 仅在大版本变更（如 3.x → 4.0）时允许破坏 API 兼容。
• LTS 分支内部额外维护 ABI 兼容（即无需重新编译、直接重新链接即可），并尽量不增大代码体积、不增加 RAM 占用、不提升构建所需工具链的最低版本。

这一规则直接影响 TEN Framework 的升级决策：在 master 稳定线内（当前为 3.2.1）升到同大版本的更新补丁，属于安全的"缺陷修复 + 安全修复"升级；而一旦跨大版本，就必须重新评估所有直接或间接使用 Mbed TLS API 的依赖方。

应用代码的向后兼容保证

文档明确了应用层的 API 兼容承诺：只要代码基于 Mbed TLS x.y.z 正常工作且未依赖未文档化特性，那么在相同大版本号的后续任意小版本上重新编译即可，代码仍能构建、保持安全并正常工作。

该承诺附有两个重要前提：

1. 编译期配置一致：要么使用默认的 mbedtls/mbedtls_config.h，要么使用与之前完全相同的修改版配置。文档明确警告：改变编译期配置选项可能导致 API 或 ABI 不兼容——尽管通常启用/禁用某个算法不会影响不使用该算法的代码。
2. API 只会扩展、不会随意收缩：下列变更被视为"常见且不构成破坏"：
   • 在结构体或联合体中新增或重排字段；
   • 移除结构体中未文档化为公共的字段；
   • 向枚举新增条目；
   • 为新出现的错误条件返回此前未文档化的错误码；
   • 在多种错误条件同时成立时更换返回的错误码；
   • 将函数从"失败"改为"成功"（若属于当前行为的合理扩展，即新特性的加入）。

在仓库源码中，编译期配置的落点正是 mbedtls_config.h（由 build_info.h 在未定义 MBEDTLS_CONFIG_FILE 时自动引入，并支持通过 MBEDTLS_USER_CONFIG_FILE 覆盖默认配置）。TEN Framework 的构建通过 BUILD.gn 中的 CMake 参数来控制编译期行为，因此"配置一致性"是升级时必须保持的基线。

PSA 持久化密钥存储的向后兼容

除 API/ABI 外，文档还给出了 PSA Crypto 持久化存储的兼容性承诺：

• 自 Mbed TLS 2.25.0 起，只要存储后端（PSA ITS 实现）配置方式兼容，新版本可读取旧版本写入的密钥。
• 该兼容性在整个大版本内保持：例如所有 Mbed TLS 3.y 版本都能读取任意 3.x（x ≤ y）写入的密钥。
• Mbed TLS 3.x 还能读取 2.25.0 至 2.28.x LTS 写入的密钥；但从 2.28.x/3.x 升级到 4.y 时，可能必须使用专门的升级工具。
• 例外：驱动（driver）属于实验特性，上述保证暂未完全覆盖——从 2.28.0 起承诺维护驱动的基本用法兼容，但驱动状态（driver state）等更实验性的接口部分暂不保证向后兼容。

这一节对 TEN Framework 的意义在于：如果上层应用使用 PSA 持久化存储（如设备端密钥落盘），在仓库内 3.2.1 线内升级可放心密钥可读；但涉及驱动接口或未来跨大版本升级时，需提前规划迁移工具。

LTS 分支的额外承诺与安全优先原则

文档对 LTS 分支（mbedtls-2.28）给出了更严格的维护承诺：除 ABI 兼容外，还要避免代码体积与 RAM 用量增加、避免提升构建工具链的最低版本。唯一例外是当这些目标与修复安全问题冲突时——此时安全优先，但会尽量提供兼容性选项。文档也坦承：到目前为止 LTS 分支从未破坏过 ABI 兼容，但偶尔会为安全修复增加代码体积。

对开发者而言，这条规则意味着：当你在 TEN Framework 中看到某个依赖（如 libwebsockets、curl）通过 mbedtls-2.28 LTS 线发布安全补丁时，升级通常只需重新链接，不必重写调用代码；而安全优先级意味着个别补丁可能带来体积增长，属于预期行为。

当前维护分支一览

文档末尾给出了当前仍在维护的分支清单：

• master
• development
• mbedtls-2.28（至少维护到 2024 年底）

并强烈建议用户始终使用维护分支中的最新版本。对于本仓库来说，third_party/mbedtls 目录是一个固定的 vendored 快照（3.2.1），"使用最新版本"对应的是：跟踪上游 3.x 主线（master 稳定线）的缺陷与安全修复，并在仓库内同步升级该快照。

从仓库源码看 Mbed TLS 的构建与集成方式

Mbed TLS 在本仓库中并非孤立存在，而是作为多条链路的基础 TLS 后端。理解它的分支与版本策略，还需结合集成点：

• Mbed TLS 自身的构建：BUILD.gn 通过 cmake_project("mbedtls") 构建，默认关闭 ENABLE_PROGRAMS 与 ENABLE_TESTING（即只产出库、不产出官方示例与测试程序），并通过 mbedtls_use_shared_lib 参数在共享库（USE_SHARED_MBEDTLS_LIBRARY=ON）与静态库之间切换；Linux 下额外设置 CMAKE_BUILD_RPATH_USE_ORIGIN=TRUE，使三个库（mbedtls、mbedx509、mbedcrypto）在运行时能从同一目录通过 $ORIGIN 解析依赖。
• libwebsockets 的 TLS 后端：libwebsockets/BUILD.gn 明确以 LWS_WITH_SSL=ON + LWS_WITH_MBEDTLS=ON 开启基于 Mbed TLS 的 TLS 实现，并通过 ten_mbedtls_copy_deps 将 mbedtls 头文件与运行时库复制到 websockets 的安装目录（BUILD.gn），同时用 CMAKE_PREFIX_PATH 指向 mbedtls 的 install 路径供 CMake 探测。
• curl 的 TLS 后端：curl/BUILD.gn 通过 CURL_USE_MBEDTLS=ON 让 curl 使用 Mbed TLS 做 SSL/TLS，并在 BUILD.gn 中把 mbedtls_output_libs 拷贝到 curl 库所在目录，保证运行时无需额外设置库路径即可加载。

由此可以推断：TEN Framework 内凡是经由 libwebsockets 或 curl 发起的 HTTPS/WSS 等加密连接，其证书校验与密码学原语最终都落在 Mbed TLS 3.2.1 上。因此，Mbed TLS 分支文档中"始终保持维护分支最新版本（含安全修复）"的建议，实际上关系着整个框架所有 TLS 链路的攻防安全基线。

升级实践建议

综合上游分支策略与仓库集成现状，给出如下可操作结论：

1. 当前仓库对应 3.x 主线，升级应沿 3.x 同大版本内进行，可享受 API 兼容承诺（BRANCHES.md 中 master 分支的语义化版本规则）。
2. 保持编译期配置不变是兼容性承诺生效的前提；若修改 mbedtls_config.h 或新增 MBEDTLS_USER_CONFIG_FILE，需要自行验证 API/ABI 影响。
3. 升级后需联动验证：由于 mbedtls 头文件被 libwebsockets、curl 共享（如 libwebsockets/BUILD.gn 将 mbedtls include 目录加入编译路径），更新 mbedtls 后应重新构建并回归测试相关网络链路。
4. 安全修复优先：按文档的安全优先原则，即使个别安全补丁带来代码体积或内存增长，也应尽快同步，尤其是涉及 TLS 握手与证书校验的路径。

<无法成文说明：本篇文章未出现此类判定>

结语

Mbed TLS 的分支策略文档虽然出自上游项目，但它为仓库维护者提供了清晰的升级坐标系：master 稳定线负责"最新且含全部安全修复"，development 负责大版本演进，LTS 线提供长期稳定的 ABI 承诺。在 TEN Framework 中，Mbed TLS 3.2.1 既是独立的三库（mbedtls/mbedx509/mbedcrypto）产物，也是 libwebsockets 与 curl 的共同 TLS 底座，理解这套分支与兼容性规则，是安全、平滑地维护框架网络层的关键前提。