opral/lix · 上手攻略

仓库：opral/lix
链接：https://github.com/opral/lix
分类：开发者工具 · 版本控制 · 数据基础设施
作者：Tom
更新：2026-08-27

是什么

Lix 是一个面向现代应用的通用版本控制系统——它同时版本化管理普通文件（像 Git）、应用数据库表（像传统 DB migration）、评论和审核记录（像 CMS），并在这些维度上支持分支、Diff、Merge 和回滚。

核心定位：文件 + SQL 数据库 + 版本控制，三位一体。任何格式的文件、任何应用数据、任何变更历史，都在一个 ACID OLTP 数据库中统一版本化管理。LLM Agent 和人类用户操作的是普通文件和应用表，Lix 在底层自动记录每次变更的作者、时间戳和内容差异。

当前 SDK 状态：JavaScript/TypeScript（@lix-js/sdk）稳定，Rust 支持在 Beta，Python 和 Go 支持在规划中（见 GitHub issues）。

解决什么问题

传统工具的三大割裂

工具	文件	SQL 数据	版本历史
Git	✅	❌	✅（但只是文本 Diff）
PostgreSQL/SQLite	❌	✅	❌（除非借助外部工具）
CMS / 协作工具	✅	✅	❌（各自独立）

结果：同一个变更涉及文件 + 数据库行 + 业务状态，需要在三个系统间手动维护一致性。

Lix 的答案

所有变更都在同一个 OLTP 数据库中记录，Diff 精确到行/列/单元格级别，而非字节级别的文本 Diff。分支、Merge、回滚同时覆盖文件内容和数据库行，且保证 ACID 事务一致性。

典型问题 Lix 解决： - LLM Agent 改了一个配置又改了一个数据库字段，如何一起回滚？ - 每次部署需要同时迁移 schema 和 seed data，如何保证幂等？ - 不同客户的配置/数据需要隔离分支，如何复用同一套基础设施？

快速安装

环境要求

Node.js 18+（JavaScript SDK）
Rust 1.70+（Rust SDK）
服务器模式可选：Python 3.10+ 或直接用 lixray.com 托管

JavaScript SDK（最常用）

npm install @lix-js/sdk @lix-js/storage-filesystem

本地文件系统存储（开箱即用）

import { openLix } from "@lix-js/sdk";
import { FilesystemStorage } from "@lix-js/storage-filesystem";

const lix = await openLix({
  storage: new FilesystemStorage({ path: "./repository" }),
});

// 写入文件
await lix.execute(
  "INSERT INTO lix_file (path, content) VALUES ($1, $2)",
  ["/notes/status.txt", new TextEncoder().encode("ready")]
);

// 查询历史
const changes = await lix.execute(`
  SELECT created_at, account_id, schema_key, row_pk, snapshot_content
  FROM lix_change
  ORDER BY created_at DESC
`);

连接到远程服务器

const lix = await openLix({
  server: {
    mode: "remote",
    url: "https://example.com/repositories/acme",
  },
});

自托管 Lix 服务器

参考文档：/docs/hosting.md（需 Python 3.10+ 服务端）

托管方案：LixRay

不想自建服务器？用 https://lixray.com，三分钟创建仓库，无需自己运维。

核心概念

插件：文件格式 → SQL 行

Lix 的插件系统将文件格式映射为可版本化的 SQL 行：

文本文件 → lix_file 表（path, content）
业务数据 → 自定义表（products, orders 等）
审核记录 → lix_review / lix_comment 表

插件让你用 SQL 查询文件的版本历史，而不只是看文本 Diff。

存储后端

存储方式	说明
`FilesystemStorage`	本地文件系统，适合开发和小规模
`BrowserOPFSStorage`	浏览器 OPFS，适合纯前端应用
`S3Storage`	S3 兼容对象存储，适合生产大规模部署
远程服务器	通过 LixRay 或自建服务器访问

变更粒度

传统 Git	Lix
文本 Diff（按行）	精确到 clause / cell / row
文件是原子单位	行/列变更可独立分支和回滚
Binary 文件不可比对	文件内容可映射为行后比对

权限系统（即将到来）

计划支持：按文件、按分组的细粒度权限，且权限本身也版本化（permissions are coming）。

典型适用场景

场景	说明
每个客户一个仓库（SaaS）	每个客户的数据用独立 Lix 仓库，天然隔离；权限管理在规划中
LLM Agent 文件同步	Agent 和应用操作同一目录，Lix 记录所有变更，UI 展示 Diff 供人工审核
应用内建版本控制	CRM/CMS 的记录变更历史、审核流、评论，直接是 Lix 表，无需另外开发审计日志
配置 + 数据的联合回滚	配置文件和数据库默认值同步版本化，一个命令同时回滚
实时协作	多个人/Agent 同时操作同一仓库，变更实时同步（通过服务器模式）

场景示例：多租户 SaaS

// 每个客户一个仓库
const lix = await openLix({
  server: {
    mode: "remote",
    url: `https://lixray.com/@acme/customer-${customer.id}`,
  },
});

// Agent 自动写入自动化脚本
await lix.execute(
  "INSERT INTO lix_file (path, content) VALUES ($1, $2)",
  ["/automations/booking.ts", code]
);

// UI 直接展示 Diff，客户点 Accept 或 Undo

场景示例：Git + 数据库联合版本化

// 普通应用写操作（同时更新文件和表）
await lix.execute("UPDATE orders SET status = 'shipped' WHERE id = 1002");

// 历史、追责、撤销都是 SQL 查询
const history = await lix.execute(`
  SELECT created_at, account_id, schema_key, row_pk, snapshot_content
  FROM lix_change
  WHERE schema_key = 'orders' AND row_pk = 1002
  ORDER BY created_at DESC
`);

坑与注意

Python/Go SDK 尚未完成：当前 Python SDK 在 GitHub issue #373，Go SDK 在 #370。如果只打算用这两种语言，目前无法使用，需等待正式 release。
权限系统未上线：README 明确说"permissions (soon)"。如果需要细粒度权限控制（不同用户访问不同文件/行），目前 Lix 还无法满足，需要等待后续版本。
生产部署成熟度：Lix 整体项目仍处于活跃开发阶段（v0.x），API 和存储格式可能存在破坏性变更；不建议在核心业务未做充分测试前用于生产关键路径。
自建服务器复杂度：Lix 服务器模式需要自行维护（参考 docs/hosting.md），涉及数据库迁移、存储配置等；相比直接用 LixRay 托管，有更高的运维门槛。
Git 兼容性：Lix 不是 Git 的替代品——它版本化管理的是文件和行，不是 Git 的分支模型。如果需要 Git 工作流（如 Pull Request、代码审查），Lix 不提供这些功能。
大型二进制文件：虽然支持普通文件和二进制内容，但大文件（GB 级别）的存储性能和 S3 成本需要评估；建议结合 Git LFS 或对象存储分层策略。
Plugin 开发门槛：若需要自定义文件格式映射，需要了解 Lix 的插件 API，目前文档有限，可能需要参考源码。

与同类对比

维度	Lix	Git	Dolt	PlanetScale	SQLite
文件版本化	✅	✅	✅	✅	❌
SQL 数据版本化	✅	❌	✅	✅	❌
分支/Merge（数据）	✅	✅	✅	❌	❌
行级/列级 Diff	✅（插件）	❌	❌	❌	❌
细粒度回滚	✅	❌	✅	❌	❌
实时协作	✅（服务器）	❌	❌	❌	❌
多租户隔离	✅（仓库级）	❌	❌	✅	❌
权限系统	规划中	✅	❌	✅	❌
SDK 成熟度	JS 稳定 / Rust Beta	N/A	Go/Python 稳定	MySQL 兼容	稳定
许可证	MIT	GPL	Apache	商业	公共领域

核心差异：Dolt 是 Git for SQL Data（数据可像代码一样 clone/fork/push/pull），Lix 进一步扩展到任意文件 + 任意业务数据 + 实时协作，且有 Plugin 架构支持细粒度 Diff。

一句话推荐结论

如果你正在构建需要"每个客户独立数据空间 + LLM Agent 自动操作 + 人工审核 Diff"的 SaaS 产品，Lix 是目前唯一同时具备文件/数据联合版本化、细粒度变更追踪和实时协作的开源基础设施——尤其是 JavaScript/TypeScript 生态的项目，可以从今天开始集成 @lix-js/sdk。