FreeLLMAPI 模型目录同步源码解读Ed25519 签名校验与增量应用全流程【免费下载链接】freellmapi7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapiFreeLLMAPI 是一个免费 LLM API 网关34 家免费提供商、635 个免费模型端点全部收敛到一个/v1端点之后。它的本地模型目录需要与官方发布的目录保持同步——模型目录同步是否可信、是否安全直接决定路由器的行为。本文带你走读 catalog-sync.ts 的完整链路固定公钥签名校验、版本地板拦截、以及绝不覆盖用户数据的增量应用规则。一、同步解决什么问题本地二进制里打包了一份基线模型目录SQLite 迁移脚本但上游模型一直在变动新模型上架、旧模型退役、限速调整。如果每台本地实例都靠发版更新目录速度太慢如果放任外部 JSON 直接写库被劫持的 CDN 就能往你的路由器里注入恶意模型。所以整套机制只有两个目标可信只接受官方亲笔签名的目录文件无副作用应用时绝不覆盖、删除用户自己创建或修改过的数据。二、源码入口一个服务文件管到底整个同步逻辑集中在 server/src/services/catalog-sync.ts在服务启动后被挂载启动入口server/src/index.ts 在服务就绪回调里调用startCatalogSync(scheduler)手动触发server/src/routes/premium.ts 提供立即检查更新接口测试覆盖catalog-sync.test.ts 用 40 多个用例钉死了行为契约。调度本身非常朴素就是一个可注入的定时器接口scheduler.ts 里的every周期轮询和after延迟一次。三、签名校验把公钥钉死在源码里1. 固定公钥Key Pinning源码里直接硬编码了一把 Ed25519公钥catalog-sync.ts 的PINNED_CATALOG_PUBKEY。对应的私钥只在官方目录主机上生成、从未离开。这意味着即使 CDN 被攻破、中间人拿到证书也无法伪造目录——因为签名验不过就整份丢弃。自部署用户如果运行自己的目录服务可以通过环境变量覆盖公钥。2. 验签覆盖收到的原始字节syncCatalogcatalog-sync.ts的核心几步请求{baseUrl}/v1/latest带上 20 秒超时Premium 用户附带 Bearer 许可证密钥拿到 live 层目录免费用户拿到每月快照若本地已应用过某版本会追加since版本号参数服务端无变化时直接返回304客户端立即结束up_to_date从响应头读取x-catalog-signature缺失直接报错用crypto.verify对res.arrayBuffer()的原始字节逐字节验签catalog-sync.ts失败即抛出discarding response整份响应作废验签通过后先做结构校验isCatalogcatalog-sync.ts逐字段检查类型一份格式畸形的目录连数据库都进不去。验签在解析 JSON 之前完成——先确认是官方发的再考虑内容是什么顺序不可颠倒。3. 版本地板旧快照永远不能回滚MIN_CATALOG_VERSION 2026.06.07catalog-sync.ts。每合并一次模型相关的数据库迁移就把它顶到当天日期。于是免费用户拿到的每月快照如果比新装版本自带的基线还旧同步动作直接返回skipped_older等下一轮——打包的迁移基线永远是本地目录的下限旧快照绝无可能把新迁移加进来的模型删掉。四、增量应用一个事务内的五条铁律验证通过且版本前进后applyCatalogcatalog-sync.ts在单个数据库事务内完成全部写入任何一步失败整体回滚。它与用户数据的交战规则写在源码注释里可以总结成五条#规则源码位置1元数据名称、评级、限速、上下文窗口跟随目录除非用户有本地覆盖applyModelOverridescatalog-sync.ts2目录标记enabledfalse强制禁用上游已死但目录的enabledtrue不会重新启用用户手动关掉的模型catalog-sync.ts3sourceuser的行自定义提供商、声明式配置、管理端添加永不更新、永不删除、永不收编platform:model_id冲突时用户行获胜目录条目直接跳过catalog-sync.ts4用户在面板里删掉的目录模型通过墓碑表tombstone保持删除状态而上游 410 退役的模型只禁用不删除一旦目录仍列着它且启用就恢复退役model-state.ts5从目录中消失的模型按迁移同款顺序删除先删fallback_config再删models遵守外键序catalog-sync.ts几个值得细看的工程细节清理候选只认sourcecatalog删除路径用来源列做精确判定替代了旧版靠size_label文案猜用户的脆弱启发式catalog-sync.ts。分模态快照互不干扰图像/音频走media_models表嵌入、语音转写、文生视频各有独立快照键老版本目录省略这些键时对应行一律保持原样——注释里明确警告把过滤条件放宽一个字符就会在第一次同步时误删全部视频模型行catalog-sync.ts。quirks模型怪癖知识库是纯内容全量替换删表重建catalog-sync.ts。不变量修复应用结束后补齐缺失的fallback_config行、确保每个模型都进了 profile与迁移脚本维持同一条不变量。五、调度节奏与离线自愈startCatalogSynccatalog-sync.ts的启动序列立即执行reapplyCachedCatalog()每次启动时迁移脚本都会重跑基线INSERT OR IGNORE会把目录删掉的模型插回来而启动时的网络同步大概率 304 不会重新应用——所以从本地缓存里已验签的目录 JSON同步重放一次让目录保持权威且完全离线可用延迟10 秒后首次网络同步给数据库留出喘息时间此后每12 小时轮询一次Premium 层 2–3 天刷新 live 目录免费层每月快照。两个优雅的设计验签后才缓存缓存行里存的是验签通过后的原始字节。注释一针见血——能篡改这个缓存的人本来就能直接篡改models表缓存没有引入新的信任面catalog-sync.ts。force 参数许可证密钥激活/移除后层级可能变化但版本号不变此时用syncCatalog(true)跳过since短路premium.ts升级几秒内生效而不是等下一个 12 小时周期。六、测试矩阵把安全变成可断言的事实catalog-sync.test.ts 的 40 用例几乎与源码规则一一对应用户删除的模型跨同步保持删除、自定义提供商模型绝不被触碰、畸形videoModels元数据导致整份载荷被拒、旧缓存低于基线版本时拒绝重放、旧目录省略可选键时不删任何视频行……再配合调度器行为测试 catalog-sync-scheduler.test.ts签名、版本、应用三层防线全部有回归保护。七、文件路径速查模块路径同步核心验签 应用 缓存重放server/src/services/catalog-sync.ts墓碑 / 退役 / 本地覆盖server/src/services/model-state.ts定时调度接口server/src/lib/scheduler.ts启动挂载点server/src/index.ts手动同步 / 许可证激活server/src/routes/premium.ts目录导出脚本发布侧单一事实源server/src/scripts/export-catalog.ts行为测试server/src/tests/services/catalog-sync.test.ts总结FreeLLMAPI 的模型目录同步机制可以用三句话概括先验签再解析——Ed25519 固定公钥对原始字节验签被篡改的响应整份丢弃旧版本进不来——版本地板保证任何快照都无法回滚本地基线用户数据不可侵犯——增量应用在单事务内执行来源列、墓碑表和覆盖机制层层设卡让自我更新与用户主权互不干扰。这也是本地 LLM 网关在免发版更新模型目录时一个值得抄作业的完整范式。【免费下载链接】freellmapi7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FreeLLMAPI 模型目录同步源码解读：Ed25519 签名校验与增量应用全流程
FreeLLMAPI 模型目录同步源码解读Ed25519 签名校验与增量应用全流程【免费下载链接】freellmapi7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapiFreeLLMAPI 是一个免费 LLM API 网关34 家免费提供商、635 个免费模型端点全部收敛到一个/v1端点之后。它的本地模型目录需要与官方发布的目录保持同步——模型目录同步是否可信、是否安全直接决定路由器的行为。本文带你走读 catalog-sync.ts 的完整链路固定公钥签名校验、版本地板拦截、以及绝不覆盖用户数据的增量应用规则。一、同步解决什么问题本地二进制里打包了一份基线模型目录SQLite 迁移脚本但上游模型一直在变动新模型上架、旧模型退役、限速调整。如果每台本地实例都靠发版更新目录速度太慢如果放任外部 JSON 直接写库被劫持的 CDN 就能往你的路由器里注入恶意模型。所以整套机制只有两个目标可信只接受官方亲笔签名的目录文件无副作用应用时绝不覆盖、删除用户自己创建或修改过的数据。二、源码入口一个服务文件管到底整个同步逻辑集中在 server/src/services/catalog-sync.ts在服务启动后被挂载启动入口server/src/index.ts 在服务就绪回调里调用startCatalogSync(scheduler)手动触发server/src/routes/premium.ts 提供立即检查更新接口测试覆盖catalog-sync.test.ts 用 40 多个用例钉死了行为契约。调度本身非常朴素就是一个可注入的定时器接口scheduler.ts 里的every周期轮询和after延迟一次。三、签名校验把公钥钉死在源码里1. 固定公钥Key Pinning源码里直接硬编码了一把 Ed25519公钥catalog-sync.ts 的PINNED_CATALOG_PUBKEY。对应的私钥只在官方目录主机上生成、从未离开。这意味着即使 CDN 被攻破、中间人拿到证书也无法伪造目录——因为签名验不过就整份丢弃。自部署用户如果运行自己的目录服务可以通过环境变量覆盖公钥。2. 验签覆盖收到的原始字节syncCatalogcatalog-sync.ts的核心几步请求{baseUrl}/v1/latest带上 20 秒超时Premium 用户附带 Bearer 许可证密钥拿到 live 层目录免费用户拿到每月快照若本地已应用过某版本会追加since版本号参数服务端无变化时直接返回304客户端立即结束up_to_date从响应头读取x-catalog-signature缺失直接报错用crypto.verify对res.arrayBuffer()的原始字节逐字节验签catalog-sync.ts失败即抛出discarding response整份响应作废验签通过后先做结构校验isCatalogcatalog-sync.ts逐字段检查类型一份格式畸形的目录连数据库都进不去。验签在解析 JSON 之前完成——先确认是官方发的再考虑内容是什么顺序不可颠倒。3. 版本地板旧快照永远不能回滚MIN_CATALOG_VERSION 2026.06.07catalog-sync.ts。每合并一次模型相关的数据库迁移就把它顶到当天日期。于是免费用户拿到的每月快照如果比新装版本自带的基线还旧同步动作直接返回skipped_older等下一轮——打包的迁移基线永远是本地目录的下限旧快照绝无可能把新迁移加进来的模型删掉。四、增量应用一个事务内的五条铁律验证通过且版本前进后applyCatalogcatalog-sync.ts在单个数据库事务内完成全部写入任何一步失败整体回滚。它与用户数据的交战规则写在源码注释里可以总结成五条#规则源码位置1元数据名称、评级、限速、上下文窗口跟随目录除非用户有本地覆盖applyModelOverridescatalog-sync.ts2目录标记enabledfalse强制禁用上游已死但目录的enabledtrue不会重新启用用户手动关掉的模型catalog-sync.ts3sourceuser的行自定义提供商、声明式配置、管理端添加永不更新、永不删除、永不收编platform:model_id冲突时用户行获胜目录条目直接跳过catalog-sync.ts4用户在面板里删掉的目录模型通过墓碑表tombstone保持删除状态而上游 410 退役的模型只禁用不删除一旦目录仍列着它且启用就恢复退役model-state.ts5从目录中消失的模型按迁移同款顺序删除先删fallback_config再删models遵守外键序catalog-sync.ts几个值得细看的工程细节清理候选只认sourcecatalog删除路径用来源列做精确判定替代了旧版靠size_label文案猜用户的脆弱启发式catalog-sync.ts。分模态快照互不干扰图像/音频走media_models表嵌入、语音转写、文生视频各有独立快照键老版本目录省略这些键时对应行一律保持原样——注释里明确警告把过滤条件放宽一个字符就会在第一次同步时误删全部视频模型行catalog-sync.ts。quirks模型怪癖知识库是纯内容全量替换删表重建catalog-sync.ts。不变量修复应用结束后补齐缺失的fallback_config行、确保每个模型都进了 profile与迁移脚本维持同一条不变量。五、调度节奏与离线自愈startCatalogSynccatalog-sync.ts的启动序列立即执行reapplyCachedCatalog()每次启动时迁移脚本都会重跑基线INSERT OR IGNORE会把目录删掉的模型插回来而启动时的网络同步大概率 304 不会重新应用——所以从本地缓存里已验签的目录 JSON同步重放一次让目录保持权威且完全离线可用延迟10 秒后首次网络同步给数据库留出喘息时间此后每12 小时轮询一次Premium 层 2–3 天刷新 live 目录免费层每月快照。两个优雅的设计验签后才缓存缓存行里存的是验签通过后的原始字节。注释一针见血——能篡改这个缓存的人本来就能直接篡改models表缓存没有引入新的信任面catalog-sync.ts。force 参数许可证密钥激活/移除后层级可能变化但版本号不变此时用syncCatalog(true)跳过since短路premium.ts升级几秒内生效而不是等下一个 12 小时周期。六、测试矩阵把安全变成可断言的事实catalog-sync.test.ts 的 40 用例几乎与源码规则一一对应用户删除的模型跨同步保持删除、自定义提供商模型绝不被触碰、畸形videoModels元数据导致整份载荷被拒、旧缓存低于基线版本时拒绝重放、旧目录省略可选键时不删任何视频行……再配合调度器行为测试 catalog-sync-scheduler.test.ts签名、版本、应用三层防线全部有回归保护。七、文件路径速查模块路径同步核心验签 应用 缓存重放server/src/services/catalog-sync.ts墓碑 / 退役 / 本地覆盖server/src/services/model-state.ts定时调度接口server/src/lib/scheduler.ts启动挂载点server/src/index.ts手动同步 / 许可证激活server/src/routes/premium.ts目录导出脚本发布侧单一事实源server/src/scripts/export-catalog.ts行为测试server/src/tests/services/catalog-sync.test.ts总结FreeLLMAPI 的模型目录同步机制可以用三句话概括先验签再解析——Ed25519 固定公钥对原始字节验签被篡改的响应整份丢弃旧版本进不来——版本地板保证任何快照都无法回滚本地基线用户数据不可侵犯——增量应用在单事务内执行来源列、墓碑表和覆盖机制层层设卡让自我更新与用户主权互不干扰。这也是本地 LLM 网关在免发版更新模型目录时一个值得抄作业的完整范式。【免费下载链接】freellmapi7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考