企业官网建设流程全解析

• 后端
• 认证鉴权
• 安全

Kanidm 作为一套以简单、安全、快速为目标的身份管理平台，其发布与支持策略直接决定了发行版打包者、运维工程师与集成开发者在何时升级、如何规划版本、以及能获得哪些保障。本文以 support.md 为核心，结合仓库内的发布脚本、发布检查清单、域功能级别（Domain Functional Level）与复制版本校验源码，系统讲解 Kanidm 的季度发布周期、major.minor.patch版本规范、4 个月支持窗口、复制与升级兼容边界以及 API 稳定性承诺，帮助读者建立一套可执行的版本规划与升级决策框架。

发布周期与版本规范

Kanidm 采用3 个月（季度）发布节奏，每年固定四个发布日：

• 2 月 1 日
• 5 月 1 日
• 8 月 1 日
• 11 月 1 日

仓库内 RELEASE_NOTES.md 的发布记录与之一致：例如 2026-08-01 发布 1.11.0、2026-05-01 发布 1.10.0，每一条发布说明都会同时提示读者审阅本支持文档与升级文档，说明"支持策略"是每次版本迭代前必须复核的硬性约束。

版本号遵循语义化版本（semver）的major.minor.patch格式，并可携带可选的-tag后缀，形成三条并行线：

以仓库当前状态为例，根目录 Cargo.toml 中[workspace.package]的版本声明为1.12.0-dev，正对应 1.12.0 的开发周期；所有工作区成员（tools/cli、unix_integration/resolver_kanidm等）均通过version = { workspace = true }继承该统一版本号，保证整个仓库的版本号始终同步。

关于首个稳定版本的界定，文档明确指出：第一个稳定发布版本为 1.2.0，此前的所有版本都属于 release candidate、beta 或 alpha 构建，并且自 1.2.0 发布起不再提供支持。这意味着历史遗留的预发布版本不应再作为生产部署的基线。

Git 分支与标签：从-dev到稳定发布的完整流程

发布分支会在正式发布7 天前从开发主线切出，并将版本设置为预发布版本（-pre）。文档用 mermaid gitGraph 给出了清晰的流程（开发主线master上持续推进1.2.0-dev→ 切出1.2.0分支 →1.2.0-pre→1.2.0→ 补丁1.2.1/1.2.2/1.2.3→ Final 1.2.x Release；主线同时推进1.3.0-dev、1.4.0-dev）：

从仓库源码看，这一流程已经脚本化。仓库内的 pre_release_branch_tag.sh 负责在预发布阶段执行"提交 → 打 tag → 推送"：

PACKAGE_FOR_VERSION="kanidm_proto" PKG_VERSION="$(cargo metadata --format-version 1 | jq -r ".packages[] | select(.name==\"$PACKAGE_FOR_VERSION\") | .version")-pre" git commit -m "Release ${PKG_VERSION}" TAG="v${PKG_VERSION}" git tag "$TAG" git push origin "$TAG" --tags

其要点是：

• 依赖jq从cargo metadata动态解析kanidm_proto包的当前版本，并拼接-pre后缀，避免手工维护版本号；
• tag 统一采用v前缀（如v1.11.0-pre），与 release_checklist.md 中"checkout -b 1.x.0（注意不带 v，避免 ref 冲突）"的分支命名规范相呼应；
• 正式发布时执行git tag v1.x.0并推送1.x.0 --tags。

开发者文档 release_checklist.md 进一步给出了发布前后的完整检查项：发布前需执行cargo update、cargo audit、cargo test、升级加密策略（见 libs/crypto/src/lib.rs 的CryptoPolicy）并核对数据库条目变更；发布后需在master上把版本递增并追加-dev后缀、更新 constants/mod.rs 中的DOMAIN_*_LEVEL常量并新增迁移。这些步骤共同保证了"开发主线永远是下一个版本的-dev"这一状态的一致性。

支持窗口：4 个月支持期与 1 个月重叠

稳定版本在发布后提供4 个月的支持窗口，这保证了 N 与 N+1 两个相邻版本之间有1 个月的重叠期。举例来说：若 1.2.0 于 2 月 1 日发布，其支持期覆盖至 6 月 1 日；而 1.3.0 于 5 月 1 日发布，那么 5 月 1 日到 6 月 1 日之间两个版本同时处于支持状态，为滚动升级留出了缓冲。

在支持窗口内，稳定版本可以获得以下修复：

• 安全修复（Security fixes）
• 数据丢失或损坏缺陷修复（Fixes for flaws leading to dataloss or corruption）
• 影响升级能力的修复（Fixes that impact the ability to upgrade）
• 项目团队酌情决定的其他质量修复

由此可以反推出支持策略的设计意图：不支持窗口之外版本的意义在于鼓励用户始终停留在"相邻可升级"的轨道上，避免跨越多版本导致升级路径断裂。文档同时建议发行版（Distributions）应当跟踪 stable 分支，即打包者应以稳定发布为基线，而不是跟踪-dev或-pre。

复制拓扑与升级策略：版本一致性的硬约束

复制：所有节点必须同版本，拓扑最多 2 节点

复制场景下的版本约束是严格的：拓扑中的所有节点必须是同一版本，且一个复制拓扑最多包含2 个节点。这一点在源码层面有对应的防护逻辑：

• repl/consumer.rs 中的consumer_apply_refresh_v1在应用远程刷新前会做三重校验：传入的ctx_domain_version若低于DOMAIN_MINIMUM_REPLICATION_LEVEL或高于DOMAIN_MAXIMUM_REPLICATION_LEVEL会直接以OperationError::ReplDomainLevelUnsatisfiable拒绝；同时通过option_env!("KANIDM_PRE_RELEASE")检测"开发版与稳定版混连"，若远端是开发版而本机是稳定版（或反之）同样拒绝同步，杜绝-dev版本数据污染稳定拓扑；
• constants/mod.rs 注释中阐述了域功能级别的设计动机：它允许拓扑内出现"版本 N 与 N-1 混合滚动升级"的过渡状态——机器 A 升级后支持到 level 2，但机器 B 仍停留在 level 1，此时整体功能级别保持 level 1；只有全部节点都支持时，才由管理员显式干预强制提升。这实际上是"所有节点必须同版本"约束在升级过渡期的工程化妥协：功能级别作为显式的门闩，防止新特性在未完成升级的拓扑中被提前启用。

从源码结构可以推断，DOMAIN_*_LEVEL常量（如DOMAIN_LEVEL_10对应 1.6.0、DOMAIN_LEVEL_1_12对应 1.12.0）与版本号存在一一对应的映射关系，每次发布都会新增一级并废弃更早的级别（如DOMAIN_LEVEL_10在 1.8.0 起弃用）。

升级策略：只支持相邻 minor 版本

升级仅支持从当前稳定版之前的 1 个 minor 版本升级：

示例：运行 1.2.0 的服务器可以升级到 1.3.0；运行 1.2.0 的服务器不能直接升级到 1.4.0。

server_updates.md 将这一策略落实为操作要求：升级必须逐版本顺序进行（1.5 → 1.6 → 1.7），跨版本跳级不被支持；升级前建议运行kanidmd domain upgrade-check对数据施加的新约束进行预检，任何FAIL项都会列出必须解决的条目。此外，be/mod.rs 显示备份恢复同样绑定版本：从备份恢复时，若备份内记录的version与当前实例的KANIDM_PKG_SERIES不一致，会返回DB0001MismatchedRestoreVersion/DB0002MismatchedRestoreVersion错误并拒绝恢复，防止旧数据被错误地灌入新版本。

工具版本：CLI 与同步连接器必须与服务器匹配

命令行工具kanidm以及同步连接器kanidm-ipa-sync、kanidm-ldap-sync在任何时候都必须与它们通信的服务器保持版本一致。这意味着：

• 升级服务器时，tools/cli 构建的kanidm客户端需同步升级；
• 运行 tools/iam_migrations/freeipa 与 tools/iam_migrations/ldap 的同步连接器时，其发布版本应与目标服务器对齐；
• 版本号由工作区统一管理（version = { workspace = true }），因此只要从同一发布 tag 构建，工具与服务器天然同版本。

Unix 客户端：向后兼容一个 minor 版本

服务器支持来自 Unix 客户端的通信版本范围为服务器自身版本的前 1 个 minor 版本：

示例：运行 1.4.0 的服务器支持 1.4.0 与 1.3.0 的 Unix 客户端工具；1.2.0 及以下的 Unix 客户端工具不受支持。

这里的 Unix 客户端覆盖unix_integration目录下的各组件，包括 resolver_kanidm（kanidm-unixd守护进程）、nss_kanidm（NSS 模块）与 pam_kanidm（PAM 模块）。该策略允许客户端侧采用"落后一个版本"的滚动更新节奏：先升级服务器，再在后续维护窗口内分批升级各客户机上的 Unix 集成组件，为大规模主机群部署留出弹性。

API 稳定性：稳定与非稳定的明确分界

Kanidm 拥有多套 API，各自承诺不同的稳定性级别。稳定的 API 仅在发生伦理问题、安全问题或潜在数据损坏问题时才接受破坏性变更，为上层集成提供可靠的契约。

稳定 API 包括：

• LDAP 协议操作（见 集成文档）；
• 使用 proto/src/v1 中元素的 JSON HTTP 端点——该目录包含auth.rs、message.rs、unix.rs等版本化协议定义，是客户端与服务器之间的官方 HTTP 契约。

其余 API 与交互均不被视为稳定，项目会尽可能减少变更，但可能随时调整，包括但不限于：

• kanidm_unixd解析器的Unix 域套接字 API；
• kanidmd服务器的Unix 管理域套接字；
• Web 用户界面的设计与操作；
• 条目 schema；
• kanidm提供的CLI 接口（除非上述另有注明）；
• 使用 proto/src/internal 元素的 JSON HTTP 端点（如credupdate.rs、token.rs等内部协议）；
• proto/src/scim_v1 的SCIM 操作。

对集成开发者而言，这条分界线的实践意义在于：需要长期稳定契约的集成应优先依赖 LDAP 与proto/src/v1端点；而 Web UI、CLI、schema 与 SCIM 的对接则应把"随版本跟进"纳入发布计划。值得注意的是，SCIM 与 Web UI 之所以被划入非稳定区，从代码演进角度可以推断是因为它们迭代更快、更贴近产品体验，稳定化成本高，因此以"尽力减少变更"代替硬性承诺。

弃用策略：提前 1 个发布版本通知

特性或 API 的移除需要1 个发布版本的事先通知。弃用公告统一在 RELEASE_NOTES.md 中发布——这也是每次发布说明都会在显眼位置提醒"审阅支持文档"的原因：对于依赖某个即将被移除特性的用户，一个版本的过渡期意味着从公告发布到特性实际消失之间，至少存在一个完整发布周期的窗口用于迁移。升级前建议结合 server_updates.md 的逐版本升级要求，把弃用公告当作升级路径上的"路线图"使用。

Python 模块与项目自由裁量权

文档对 pykanidm Python 模块给出了务实定位：它通常会滞后于核心 Rust 代码的功能演进，按项目实际需要驱动开发。因此：

• 使用pykanidm的开发者不应假设其与 Rust 核心同步发布全部新特性；
• 项目欢迎贡献者自由添加功能或改进，并以 GitHub issue 方式提出需求；
• 所有代码变更在可能的情况下都会包含完整的类型标注（full type-casting），这保证了pykanidm的 API 面具备可静态检查的稳定性基础——仓库中 pykanidm 同时提供py.typed标记、models 的类型化模型层，正是这一承诺的落地体现。

最后，文档保留了项目自由裁量权：在出现不可预见或非常规情况时，项目团队可以做出与本文件相悖的决定，但会尽力沟通决策理由并最小化对用户的干扰。这也提醒读者：支持策略是"尽力承诺"而非绝对契约，重大安全事件等极端情形下可能触发例外处理。

小结：面向运维的版本决策清单

综合全文，可提炼出面向实际部署的版本管理要点：

1. 跟随季度节奏：每年 2/5/8/11 月 1 日评估升级，跟随 RELEASE_NOTES.md 的弃用与安全公告；
2. 只跟踪稳定分支：生产环境不采用-dev/-pre版本，发行版打包同样以稳定分支为基线；
3. 升级只跨一个 minor：严格按 1.x.0 → 1.(x+1).0 顺序升级，跨版本必须分步执行并用kanidmd domain upgrade-check预检；
4. 工具与服务器同版本：kanidmCLI、kanidm-ipa-sync、kanidm-ldap-sync与服务器保持完全一致；
5. Unix 客户端可落后一个版本：先升级服务器，再分批升级kanidm-unixd/NSS/PAM 组件；
6. 复制拓扑严格同版本：2 节点上限内，所有节点必须同版本，避免-dev与稳定版混连；
7. 集成优先选择稳定 API：LDAP 与proto/src/v1HTTP 端点是长期契约的首选，Web UI/CLI/schema/SCIM 需按非稳定接口管理变更风险。

这套策略的组合效应在于：以"相邻版本可升级、稳定版 4 个月支持"为骨架，把复制、工具链、客户端、API 四条维度的版本一致性约束统一到同一张时间表上，使多节点、多发行版的复杂部署能够以可控的节奏滚动前进。

• 后端
• 认证鉴权
• 安全