新闻详情

新闻详情

首页 / 资讯中心 / 详情

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

发布时间:2026/10/1 15:31:04来源:尧图网络
codex-auth的registry.json是如何版本演进的:Schema v2到v4迁移完整指南
codex-auth的registry.json是如何版本演进的Schema v2到v4迁移完整指南【免费下载链接】codex-authA CLI tool to switch and manage Codex accounts项目地址: https://gitcode.com/gh_mirrors/co/codex-authcodex-auth是一个用来切换和管理多个 Codex 账号的命令行工具而它的核心数据都存放在~/.codex/accounts/registry.json这个文件里。这篇指南带你完整看懂registry.json从 Schema v2 到 v4 的版本演进每个版本改了什么、codex-auth 是如何在启动时自动完成迁移的以及迁移过程中数据如何被备份保护。registry.jsoncodex-auth 账号管理的核心存储codex-auth 把每个 Codex 账号的身份信息 本地状态集中记录在一个 JSON 文件里路径固定为~/.codex/accounts/registry.json路径的构造逻辑见 registryPath而写入时采用的是先备份、再原子替换的安全流程实现位于 saveRegistry。理解版本演进前先分清两个容易混淆的概念官方定义见 docs/schema-migration.md概念含义app_versioncodex-auth 的 CLI 发布版本如 v0.3.0schema_versionregistry.json文件的格式版本只和迁移有关current_schema_version 4、min_supported_schema_version 2两个常量定义在 src/registry/common.zig。Schema 演进时间线v2 → v3 → v4 一图看懂版本账号身份标识关键特性v2version字段邮箱email最原始的形态按邮箱做 key用active_email记录当前激活账号v3schema_version字段account_key记录键引入chatgpt_account_id/chatgpt_user_id双标识active_account_key取代active_email新增每账号last_local_rollout遗留顶层api块被忽略v4当前格式同 v3顶层新增interval_secondsLive 刷新间隔和previous_active_account_key支持codex-auth -一键切回上个账号套餐命名收敛为最终产品名三个版本之间最大的质变发生在 v2 → v3账号身份从邮箱换成了平台侧的account_key。这是因为同一个邮箱在 ChatGPT 侧可能对应多个账号上下文而 v3 起每个账号都带有独立的 chatgpt_account_id 与 chatgpt_user_id快照文件也随之从按邮箱命名改为按 account_key 命名。自动迁移如何工作升级一次直达 v4很多工具要求用户逐级安装中间版本codex-auth 不需要。它的迁移策略是规则见 docs/schema-migration.md 的Upgrade Behavior章节加载即检测每次命令运行都会读取registry.jsondetectSchemaVersion 会优先读schema_version字段兼容旧文件里的version字段甚至能识别没有任何版本字段但有active_email的 v2 老文件检测到旧版本就直接升到位v2 和 v3 文件都会一次性改写为最终的 v4 格式用户无需安装任何中间版本的 codex-auth只向前兼容不向下猜测如果文件里的schema_version比当前版本更大比如被未来版本写成了 5codex-auth 会报UnsupportedRegistryVersion并拒绝写入防止覆盖未来格式的数据。 这里有个容易忽略的细节即使是schema_version 4的文件如果还残留旧字段如旧的全局last_attributed_rollout形状、auto_switch块、live.interval_seconds加载时也会被规范化重写一次。判断逻辑在 currentLayoutNeedsRewrite。以 v2 老文件为例迁移时 loadLegacyRegistryV2 会遍历每个按邮箱存储的旧账号从磁盘快照文件中读出真实的account_key与chatgpt_*标识再把旧快照文件复制为按新 key 命名的新文件——账号数据在这个过程中被完整保留。v4 相比 v3 的四个关键变化Live 刷新间隔上移从嵌套的live.interval_seconds变为顶层interval_seconds旧的auto_switch配置块在重写时直接省略后台自动切换功能已在 v0.3.0 移除新增previous_active_account_key支撑codex-auth -/switch -切回上一个账号能力设计文档见 docs/brainstorm/2026-05-31-previous-account-switch-design.md套餐语义收敛为产品名遗留的team统一改为business旧business改为enterprise账号级last_usage.plan_type同样适用。解析入口是 parseStoredPlanType可以明显看到它对schema_version 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 文件加载后落盘为 v4plan 值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 版本演进速查问题答案registry.json 在哪~/.codex/accounts/registry.json当前 schema 版本v4最低支持 v2需要手动迁移吗不需要加载时自动升级直达 v4有备份吗每次改写前生成registry.json.bak.*保留最近 5 份遇到更新版本的文件拒绝读写报UnsupportedRegistryVersion损坏了怎么救手动codex-auth import --purge重建一次版本升级用户几乎无感——这正是 v2 到 v4 三次演进始终坚持的设计目标迁移对使用者完全透明数据永远可回滚。【免费下载链接】codex-authA CLI tool to switch and manage Codex accounts项目地址: https://gitcode.com/gh_mirrors/co/codex-auth创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

BiliTools 项目全景:基于 Tauri  TypeScript  Rust 的轻量哔哩哔哩工具箱解析 2026/10/1 17:02:17

BiliTools 项目全景:基于 Tauri TypeScript Rust 的轻量哔哩哔哩工具箱解析

桌面应用音视频 【免费下载链接】BiliTools 本项目已停止维护。 项目地址: https://gitcode.com/GitHub_Trending/bilit/BiliTools 点击查看 免费下载 导读:本文以 BiliTools 文档站首页 docs/index.md 为核心骨架,系统拆解这个“简约 &…

阅读更多 →
WorkBuddy 光伏方案入门:别只看装机容量,把阴影、负载与回本假设讲明白 2026/10/1 17:02:10

WorkBuddy 光伏方案入门:别只看装机容量,把阴影、负载与回本假设讲明白

WorkBuddy 光伏方案入门:别只看装机容量,把阴影、负载与回本假设讲明白 [!NOTE] 用屋顶面积乘组件功率就得出收益,是常见的过度简化。方案至少要区分资源、朝向、遮挡、系统损耗、负载和电价情景。 本课不会用“AI 一键完成”制造错觉,而是把 WorkBuddy、Python 3.11、pand…

阅读更多 →
UE5地编必会:烘焙光照原理与Lumen差异及实操指南 2026/10/1 17:02:10

UE5地编必会:烘焙光照原理与Lumen差异及实操指南

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

阅读更多 →
前端精读:深入 JavaScript 事件循环(Event Loop)与异步编程原理 2026/10/1 17:02:10

前端精读:深入 JavaScript 事件循环(Event Loop)与异步编程原理

文档技术博客教程 【免费下载链接】weekly 前端精读周刊。帮你理解最前沿、实用的技术。 项目地址: https://gitcode.com/GitHub_Trending/we/weekly 点击查看 免费下载 事件循环(Event Loop)是 JavaScript 运行机制的核心"内科"&…

阅读更多 →
自治数据平台实战:自动化运维与性能调优的架构设计 2026/10/1 17:02:10

自治数据平台实战:自动化运维与性能调优的架构设计

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

阅读更多 →
图片像素、分辨率与文件体积怎么算?一文厘清概念与实战 2026/10/1 17:02:09

图片像素、分辨率与文件体积怎么算?一文厘清概念与实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉