企业官网建设流程全解析

codex-auth的registry.json是如何版本演进的：Schema v2到v4迁移完整指南

【免费下载链接】codex-authA CLI tool to switch and manage Codex accounts项目地址: https://gitcode.com/gh_mirrors/co/codex-auth

codex-auth是一个用来切换和管理多个 Codex 账号的命令行工具，而它的核心数据都存放在~/.codex/accounts/registry.json这个文件里。这篇指南带你完整看懂registry.json从 Schema v2 到 v4 的版本演进：每个版本改了什么、codex-auth 是如何在启动时自动完成迁移的，以及迁移过程中数据如何被备份保护。

registry.json：codex-auth 账号管理的核心存储

codex-auth 把每个 Codex 账号的"身份信息 + 本地状态"集中记录在一个 JSON 文件里，路径固定为：

~/.codex/accounts/registry.json

路径的构造逻辑见 registryPath，而写入时采用的是"先备份、再原子替换"的安全流程，实现位于 saveRegistry。

理解版本演进前，先分清两个容易混淆的概念（官方定义见 docs/schema-migration.md）：

current_schema_version = 4、min_supported_schema_version = 2两个常量定义在 src/registry/common.zig。

Schema 演进时间线：v2 → v3 → v4 一图看懂

三个版本之间最大的"质变"发生在 v2 → v3：账号身份从"邮箱"换成了平台侧的account_key。这是因为同一个邮箱在 ChatGPT 侧可能对应多个账号上下文，而 v3 起每个账号都带有独立的 chatgpt_account_id 与 chatgpt_user_id，快照文件也随之从"按邮箱命名"改为"按 account_key 命名"。

自动迁移如何工作：升级一次，直达 v4

很多工具要求用户"逐级安装中间版本"，codex-auth 不需要。它的迁移策略是（规则见 docs/schema-migration.md 的Upgrade Behavior章节）：

1. 加载即检测：每次命令运行都会读取registry.json，detectSchemaVersion 会优先读schema_version字段，兼容旧文件里的version字段，甚至能识别"没有任何版本字段但有active_email"的 v2 老文件；
2. 检测到旧版本就直接升到位：v2 和 v3 文件都会一次性改写为最终的 v4 格式，用户无需安装任何中间版本的 codex-auth；
3. 只向前兼容，不向下猜测：如果文件里的schema_version比当前版本更大（比如被未来版本写成了 5），codex-auth 会报UnsupportedRegistryVersion并拒绝写入，防止覆盖未来格式的数据。

💡 这里有个容易忽略的细节：即使是schema_version = 4的文件，如果还残留旧字段（如旧的全局last_attributed_rollout形状、auto_switch块、live.interval_seconds），加载时也会被"规范化重写"一次。判断逻辑在 currentLayoutNeedsRewrite。

以 v2 老文件为例，迁移时 loadLegacyRegistryV2 会遍历每个按邮箱存储的旧账号，从磁盘快照文件中读出真实的account_key与chatgpt_*标识，再把旧快照文件复制为按新 key 命名的新文件——账号数据在这个过程中被完整保留。

v4 相比 v3 的四个关键变化

1. Live 刷新间隔上移：从嵌套的live.interval_seconds变为顶层interval_seconds，旧的auto_switch配置块在重写时直接省略（后台自动切换功能已在 v0.3.0 移除）；
2. 新增previous_active_account_key：支撑codex-auth -/switch -"切回上一个账号"能力，设计文档见 docs/brainstorm/2026-05-31-previous-account-switch-design.md；
3. 套餐语义收敛为产品名：遗留的team统一改为business，旧business改为enterprise，账号级last_usage.plan_type同样适用。解析入口是 parseStoredPlanType，可以明显看到它对schema_version < 4和≥ 4走了两套解析逻辑；
4. 顶层旧version字段规范化：写成"version": 3的旧文件加载后会重写成"schema_version": 4。

迁移过程中的数据安全：备份机制

自动迁移虽然省心，但改动用户凭证文件这件事必须可回滚。codex-auth 做了三层保护：

• 迁移前先备份：任何一次改写都会先调用 backupRegistryIfChanged 生成带时间戳的registry.json.bak.<时间戳>备份文件；
• 备份数量上限：最多保留 5 份（max_backups = 5，见 src/registry/common.zig），超出后自动裁剪最旧的；
• 写入是原子的：新内容先写入临时文件，成功后才替换原文件（Windows 上用"临时文件 + 重命名"模拟原子替换），避免写一半损坏 registry；
• 兜底恢复路径：如果 registry 损坏或版本过旧（低于 v2），可以手动用codex-auth import --purge从导入源重建，这是官方文档明确保留的恢复手段。

迁移与备份行为都有对应的自动化测试覆盖，例如"v3 文件加载后落盘为 v4""plan 值team/business迁移为规范名""未知高版本号（如 999）拒绝迁移"等用例，集中在 tests/registry_test.zig。

什么时候该给 schema_version 升号？

如果你是项目的贡献者，docs/schema-migration.md 的When To Bumpschema_version给出了清晰的判断标准：

必须升号的情形：

• 增删、重命名任何持久化字段
• 变更字段类型，或重定义已有字段语义（如active_email→active_account_key这种身份键变更）
• 改变快照文件命名规则等"找到持久化文件所需的任何规则"

不需要升号的情形：

• CLI 输出、帮助文案、文档变化
• 纯内存逻辑或运行时行为调整（不影响落盘数据）

并且文档特别强调：升号前必须先问用户，不要悄悄地 bump。

总结：codex-auth 版本演进速查

一次版本升级，用户几乎无感——这正是 v2 到 v4 三次演进始终坚持的设计目标：迁移对使用者完全透明，数据永远可回滚。

【免费下载链接】codex-authA CLI tool to switch and manage Codex accounts项目地址: https://gitcode.com/gh_mirrors/co/codex-auth