@git-stunts/git-cas

中文文档
7.2.0发布于 2026/11/07Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 9132

内容地址存储由 Git 对象数据库支持, 可选加密和可插件编码器

中文使用文档
文档目录9 节
  1. 为什么?
  2. 快速启动
  3. 1. CLI的使用
  4. 2. TUI 锁舱
  5. 3. 图书馆入侵
  6. 能力地图
  7. 安全快照
  8. 运行时间支持
  9. 文档

盖克

现代开源系统仍然依靠集中式基础设施来分配二进制文物,即使其源代码完全分散. 这就造成了一种脆弱的依赖:如果托管端被阻断、退化或被取出,关键文物就变得无法使用或无法核实.

git-cas 通过让文物发行继承 Git 现有的复制模型来解决这个问题, 允许二进制存储、核实和运输到 Git 能够运行的任何地方, 包括镜像网络、 受限环境, 或完全脱机.

git-cas git 对象数据库支持的工业级内容可处理存储引擎。 它的"安全第一"姿态明确恢复了边界,定界元数据读取,认证了加密,遗留的策略拒绝了默认. 存储的内容被块化,被去重复,并且可选择加密——将高真实度资产和对安全敏感的文件直接保存在您的仓库历史中.

git-cas 设计对象为要求数学确定性的建筑师和需要稳定地储存文物的操作员。 它从简单的二进制 blob 管理到多接收信封加密的金库,其中包含密钥旋转,隐私-模式 swashing,以及任何大小的资产的默克勒式的列表.

npm version License

git-cas demo

为什么?

不同于传统的LFS将文件移动到外部服务器, git-cas 将 Git 对象数据库作为一等存储子库处理.

  • 默认复制: 内容自定义块 (CDC) 有 Buzhash 滚动散列, 识别文件和版本的重复模式, 最小化寄存器增长 .
  • 密码学信任:每个块都根据SHA-256文摘加以核实。 可选 AES-256-GCM 加密多收信封支持可确保隐私休息 framed 绑定每个框架的 AAD , 防止交叉的blob 互换 .
  • GC-安全舱: 命名资产通过稳定的参考索引编制(refs/cas/vault),有乐观的通币,使Git垃圾收集无法回收被引用的blobs.
  • 可变的根集:缓存和衍生状态树可停靠在 refs/cas/rootsets/* 既能活后,又能收集, 而不保留所有前辈的金库历史.
  • 管理缓存集: 应用程序可以在下面存储控件 refs/cas/caches/* 带有 TTL 、 输入和逻辑字节限制, 大致为 LRU 驱逐、永久保留证据、有限度的检查、修理和 范围化的购置,使选定的一代在使用期间能够达到. 缓存指数和对象可达性仍然是基本责任.
  • 过期安全重放集: 安全敏感标记可以生活在 refs/cas/expiring/* 带有原子加成(如果),仅摘要元数据,以及 仅限过期释放。 活性标记没有去除、修理、容量或LRU 路径可以缩短其接受窗口.
  • 不透明应用程序处理: 应用阶段资产,不可变页, 和通过经验证的手柄确定结构的捆绑,然后保留 或以生成范围的证据发布,而不是管理 Git 物体、树木或有效载荷.
  • 边界基特进程重用: 不可移动对象元数据和树读取再利用 键入适配器后面的 Git 会话 。 关于会话能力适配器,流线 blob 读取在固定的 10 MiB 上限上下,使用一个有限制的会话读取; 更大的有效载荷保留了真正的一发一发流道。 明确 封闭的页面、资产和订购的分批管道 写作. workspace.batch() 可以组成依赖性资产、页面和捆绑 在一个私人持久性范围内的波浪,或者保持其结合,或者 在一个精确的决赛下 明确选定一组新上演的终端根 生成而不改变内容特性.
  • 密钥生命周期:信封加密将DEK与KEK分离. 在整个金库中旋转密码句, 不重新加密数据 。 隐私模式 HMAC-hashes sults names 防止元数据发现.
  • 运行时间调整:单核支持Node.js 22+,Bun,和德诺通过严格的六边形端口架构,并带有运行时特有的加密适配器.

快速启动

现有v5用户应改为: 更新(md) 运行 npm run upgrade 在恢复旧的加密金库条目之前使用干燥运行模式. 已公布的v7.0.0发布将公共计划依赖性更改为Zod 4. 升级前,请阅读 移徙指导 财务报告和审定财务报表 发布注释。此释放需要 已出版 Plumbing 3.3.3. 释放和登记证据 记录其出版物.

发布 v7.1.0 添加 持久保留数字 : 申请生效前的硬记录片段承认、证据和 受限收复/检查. 见 发布注释 财务报告和审定财务报表 出版物和新的登记处-消费者证据。 。 。 . 已签名的标签、 npm githead 和成功的发布工作流程都同意 18f87dd。 。 。 .

V7.2.0发布候选路径压缩预留索引,所以分类账 更新时会写到log16(记录)树而不是 64. 指数为7.1.0 读取和更新,但7.1.0拒绝7.2.0的索引 发布注释 财务报告和审定财务报表 169号。 。 。 .

已发布 v6.5.12 发布约束对象-元数据请求如此根集,目标超过1000个(SHA-256为936个),在Plumbing的猫文件请求限制范围内验证. 招生仍拒绝在出版前丢失和不匹配的目标;见 v 6.5.12 释放说明。 。 。 .

1. CLI的使用

初始化一个金库并存储您的第一笔资产 .

git init
git-cas vault init
git-cas store data.bin --slug assets/v1 --tree
git-cas restore --slug assets/v1 --out data-restored.bin

2. TUI 锁舱

通过阅读器第一交互式仪表板导航您存储的资产 .

git-cas vault dashboard

被设定的驾驶舱将Explorer, Atlas, 和业务在一个共享的会话中保存. 使用 / 搜索资产, Ctrl+P 用于命令调色板, ? 键盘 帮助, F2 用于会话设置,以及 q 为了确认出口 非交互式 引用保留简单的分页列表.

3. 图书馆入侵

将管理的blob存储直接整合到您的 TypeScript 或 JavaScript 应用程序中 .

import { createReadStream } from 'node:fs';
import ContentAddressableStore from '@git-stunts/git-cas';

const cas = await ContentAddressableStore.open({ cwd: '.' });
const staged = await cas.assets.put({
  source: createReadStream('./asset.bin'),
  slug: 'app/asset',
  filename: 'asset.bin',
});
const retained = await cas.retention.retain({
  handle: staged.handle,
  root: { ref: 'refs/cas/rootsets/my-app', name: 'app/asset' },
  policy: 'pinned',
});
await cas.close();

staged.handle 是一个内容定位符,而不是持久的承诺。 回来的 留下的目击证人 准确的 Git 生成和树缘 可到达的资产. close() 只释放本地资源; 永不删除 对象、更新参考或更改保留.

能力地图

README是前门. 详细力学在指南集中直播:

需求从这里开始
生产性图书馆和CLI工作流程开发者指南
恢复记忆行为流回矩阵
加密方案选择加密模式
疾控中心内部、默克勒清单、KDF政策和调试高级指南
港口、适配器和协作器边界建筑
资产、页数、捆绑、保留和出版应用程序存储
多步骤组成期间的临时保留工作空间范围
为缓存和衍生状态保留GC根设置
管理 TTL 和容量缓存缓存集
在消耗缓存时进行范围保护缓存获取
持久重放只释放过期标记过期集
仓库可到达性和git-cas使用证据仓库诊断
v5 到 v6 迁移升级

核心能力:

  • 内容处理后存储:块由SHA-256文摘和 完整验证读取.
  • 复制: 固定块和内容定义块(CDC)支持 可预见或可抗转向的块边界.
  • 加密: AES-256-GCM 有经过认证的元数据. whole 财务报告和审定财务报表 framed 使用新的随机 96- 位非 ; convergent 生成每圆键 和非ces 确定从平版内容散列来保存 相去相减.
  • 默认索引: 名下资产 refs/cas/vault 所以,Git垃圾 收藏不回收引用的块 .
  • 保留根集: 当前缓存条目在呼叫者拥有下运行 refs/cas/rootsets/* 参考者。 条目在存在时可以获取,并且是旧的 设定的世代不能作为承诺历史保留.
  • 管理缓存生命周期数字 : caches.open() 拥有不可改变的缓存索引, 比较和扫描替换、过期、能力迁移、保留 证人 诊断 修复 阅读不写入访问元数据; 调用者选择合并访问更新 touch()。 。 。 .
  • 范围化缓存购置数字 : cache.acquire() 只执行一个引用 查找和解析锁定呼叫者选中的缓存生成 明确的生命. release() 检查和检查 清理使废弃的购置可视和可回收.
  • 过期安全重放生命周期数字 : expiringSets.open() 解剖保留 仅通过它们宣布的窗口重放摘要标记 . contains() 实值 仅读,以及 sweep() 只能释放过期的标记.
  • 应用程序存储数字 : assets, (中文(简体) ), pages, (中文(简体) ), bundles, (中文(简体) ), retention,以及 publications 编曲串流 CAS 写作, 结构化 具体化,明确限定的资产/页数/批发, 直接参考或完全验证成员读取,可达到根, 比较和洗涤 和不可改变的生命周期证据.
  • 工作空间范围数字 : workspaces.open() 镜像应用程序写入 在一个可更新的临时 RootSet 后方,支持一代限 资产/页数/批次加上复合依赖资产/页数/批次 精确地说,新设计的终端 - 根选择, 返回时,必须先锁定每个公开结果,并首先促进目的地, 并揭露了限定年龄、过期、逻辑内容和直接根基诊断 与不透明清理 pagination.
  • 信封收件人: 多接收键包和收件人旋转 避免重新加密数据blobs.
  • 业务诊断数字 : cas.diagnostics.doctor() 流库 物体/残余证据、被锚定物、孤儿和挥发性物体的分类、, 并汇总工作空间、缓存获取、缓存Set、RootSet、, 过期的Set, 和没有变异的 Vault 用途 Git. 这个 git-cas doctor 国 际 继续验证金库的健康.

安全快照

V6 行默认为安全第一:

  • restoreFile() 需求 baseDirectory 并拒绝输出出逃出路径 这个.
  • 明显和次明显blob 默认为 10 MiB maxBlobSize 保险 限制.
  • 遗留加密方案标识符 LEGACY_SCHEME 移徙 指导.
  • KDF 参数、盐类、框架大小、还原缓冲和货币 政策范围.
  • 接收者的试解密和金库核查员检查经常使用 比较.

完全硬化的桌子,见 高级指南:安全硬化摘要。 。 。 .

运行时间支持

运行时间版本加密后端状态
节点.js22岁以上node:crypto初级-全流支持
阿宝最新node:crypto 比较通过 Docker 测试
德诺最新网络加密 API通过Docker测试; whole 解密为有界缓冲

所有三个运行时间都通过CI测试,每次推. 六边形结构将运行时间差异隔离在 CryptoPort 边界,所以域核心是运行时不可知的.

文档

  • 指南:生产路径,库/CLI使用,金库工作流程,以及特征覆盖图.
  • 高级指南:疾病控制中心内部、直接服务合同、安全限制、业务工具编制和业绩基线.
  • 建筑: 权威的系统映射——花相,域相,口相,和适应器相.
  • 扩展:自定义适配器合同和扩展点核对表.
  • 储存/备用管道: 维护字节存储、恢复、树刊行和金库边界的状态机器.
  • 默认内部: 用于金库持久性、缓存、编码器、隐私索引、密钥校验和重试策略的维护者地图.
  • 警卫:威胁模型,信任边界,以及加密的内部.
  • API探员: 用于CI/CD自动化的JSONL代理协议.
  • 工作流程: Repo 工作学说,循环,和无变化.
  • 捐款, (中文(简体) ), 行为守则,以及 支助项目参与和帮助路径.
  • v6.0.0 释放注释:主要发布摘要,升级调用行动,并发布说明.
  • v6.1.0 发布注释: 根位保留, 医生/修理和GC-政策指导.
  • v6.2.0 释放注释: 不透明应用程序 存储、管理缓存和回放生命周期、保留证据,以及 仓库诊断.
  • v6.3.0 释放注释:生命安全, 仅有参考的缓存获取,并附有明确的释放和医生证据.
  • v6.4.0 发布注释: 范围 临时多对象可达性、晋升和清理工作空间.
  • v6.5.0 释放注释: 直接捆绑 参考文献、元数据不可改变的再利用以及更正的货币结算.
  • v 6.5.1 释放说明: 不可更改的边界页 重用零命令的热读器.
  • v 6.5.2 释放注释页:1 对象会话、范围化的分页和决定性资源关闭.
  • v6.5.3 释放注释: 一致再利用 持久性 Git 对象会话横跨相容的不可移动写入 .
  • v 6.5.4 释放注释: 排序的分页 在一个精确的中转工作空间生成中保留.
  • v 6.5.5 发布注释:自成一体 身份,指在未配置的赤裸地储存库中.
  • v 6.5.6 释放注释: Bijou 7主办 驾驶舱所有权和确定性核对冲突分类.
  • v 6.5.7 释放说明: 固执 在大有效载荷保持流畅的同时,小流体读取的会话.
  • v 6.5.8 发布注释: 受约束的应用程序 写出波浪、一代工作空间批次,以及可重复使用的批次.
  • v 6.5.9 释放说明: 依赖化合物 写出在一个精确的中转工作空间生成中保留的波.
  • v6.5.10 发布注释: 复合资产, 页面,并用精确的选定终端根来捆绑录入.
  • 升级: v5~v6的移民指南.
  • 更改日志: 版本历史与迁移注释.

以最终目标建造 飞行室

版本与发布记录

@git-stunts/git-cas 共发布 35 个版本,首次发布于 2026/02/07;过去 12 个月发布了 35 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
7.2.0latest2026/11/079 天前
7.1.02026/11/0313 天前
7.0.02026/11/0214 天前
6.5.122026/10/2027 天前
6.5.112026/10/021 个月前
6.5.102026/08/252 个月前

关于 @git-stunts/git-cas 的常见问题

@git-stunts/git-cas 是什么?

内容地址存储由 Git 对象数据库支持, 可选加密和可插件编码器

如何安装 @git-stunts/git-cas?

在项目目录运行 npm install @git-stunts/git-cas,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 git-cas,可以用 npx git-cas 直接运行。

@git-stunts/git-cas 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@git-stunts/git-cas 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@git-stunts/git-cas 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@git-stunts/git-cas 可以商用吗?

@git-stunts/git-cas 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@git-stunts/git-cas 的下载量有多少?

根据 npm 官方下载统计,@git-stunts/git-cas 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,132 次,日均约 304 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@git-stunts/git-cas 还在维护吗?

最新版本 7.2.0 发布于 2026/11/07(9 天前);至今共发布 35 个版本,其中过去 12 个月发布了 35 个;首次发布于 2026/02/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。