读 Octop 源码(2):三层存储,和一个 2100 行的迁移器

文章目录

读源码有个顺序问题:先读哪块?

我原来的顺序是先读运行时(第 5 篇),结果一路都在猜 repos 是什么。这篇回头补地基。

infra/db/ 8,854 行,是后端第五大模块。但读完发现它的结构比预想的清楚——难的不是设计,是兼容。

版本锚点:本文基于 octop v1.0.2(commit dd9dce4)。infra/db/ 8,854 行,其中 migrate.py 一个文件 2,110 行,占 24%。

环境准备

这次要同时看清"代码怎么写"和"库里实际长什么样"。

第一步,看控制面有多大。 我一直以为"多用户 Agent 平台"的控制面会很重:

cd ~/WorkBuddy/Claw/octop

sqlite3 .home/.octop/octop.db "select count(*) from sqlite_master where type='table';"   # 33
sqlite3 .home/.octop/octop.db "select count(*) from sqlite_master where type='index';"  # 71
ls -lh .home/.octop/octop.db                                                            # 472K

33 张表、71 个索引、472K。 这个体积小得让人意外——它只存元数据,不存任何对话内容。

第二步,找另外两层在哪。 这一步是关键:

find .home/.octop -name "*.sqlite*" -exec ls -lh {} \; | awk '{print $5, $9}'

跑出来是这样:

1.8M   .home/.octop/agents/aaaaa/.octop/memory.sqlite-wal
32K    .home/.octop/agents/aaaaa/.octop/memory.sqlite-shm
488K   .home/.octop/agents/aaaaa/.octop/memory.sqlite
1.8M   .home/.octop/agents/C4XMFK/.octop/memory.sqlite-wal
...

每个 Agent 各自有独立的数据库文件,而且 WAL 比主库还大。 这一眼就说明:控制面之外还有两套存储,且写入很频繁。

第三步,读 ADR。 docs/adr/002-database-backends.md 开头有一句加粗的话:「Three storage layers (do not conflate)」——三层存储,不要混为一谈。这篇 ADR 比代码更该先读。

流程

一、官方自己划的三层

ADR 002 画得很清楚:

Layer 1 — Octop control plane
  users / agents / channels / cron / settings / secrets
  → SQLite 文件  或  PostgreSQL(psycopg3 连接池 1–8)
  → 首次运行由 setup 向导决定;仅在 user_count == 0 时支持热重绑

Layer 2 — Harness checkpoints
  默认:{workspace}/checkpoints.sqlite
  memory 用 postgres 时:复用 Memory / PostgresSaver

Layer 3 — Agent memory(octop-memory)
  SQLite 控制面时:{workspace}/memory.sqlite
  PostgreSQL 控制面时:同 DSN,独立 schema agent_<id>
  → 不合并进控制面迁移

三层的分工值得逐条说。

Layer 1 是"这个系统有什么":有哪些用户、哪些 Agent、哪些通道、定时任务、密钥。33 张表全在这层。

Layer 2 是"每个 Agent 干过什么":LangGraph 的 checkpoint,一轮对话的中间状态、工具调用的参数和结果。这是可回放、可中断(HITL)的基础。

Layer 3 是"每个 Agent 记住了什么":长期记忆、向量索引、记忆片段。由 octop-memory 这个独立库管,连表结构都不归 Octop 管。

ADR 那句「→ 不合并进控制面迁移」很关键:记忆的 DDL 属于 octop-memory,Octop 的 migrate.py 一行都不碰。 这就是第 1 篇说的"复杂度被切成独立轮子"在存储层的体现。

顺带说一个实测发现:每个 Agent 的 memory.sqlite 主库 384–488K,WAL 文件 1.8M。 WAL 比主库大近四倍,说明写入远多于读取,且 checkpoint 回写不及时。

这其实和第 5 篇讲的 reclaim 是同一类问题的两面:一个是主库的 freelist 膨胀(删了数据不缩小文件),一个是 WAL 无限增长。SQLite 在"高频写入 + 长期运行"下的文件膨胀,是这类自托管项目绕不过去的运维负担。

二、控制面只有 33 张表,但装得很整齐

infra/db/repos/ 28 个文件,对应 25 个 repo 类。它们全部塞进一个 dataclass:

@dataclass(frozen=True)
class RepoBundle:
    db: DatabasePool

    user_repo: UserRepo
    user_policy_repo: UserPolicyRepo
    invite_repo: InviteRepo
    agent_repo: AgentRepo
    ...
    sso_repo: SsoRepo

    @classmethod
    def from_pool(cls, db: DatabasePool) -> RepoBundle:
        return cls(db=db, user_repo=UserRepo(db), user_policy_repo=UserPolicyRepo(db), ...)

25 个 repo,一个 db,全在构造函数里手写。 没有自动发现、没有依赖注入框架,就是老老实实列一遍。

外面再包一层 SharedServices:

@dataclass(frozen=True)
class SharedServices:
    paths: PathLayout
    config: OctopConfig
    repos: RepoBundle

到这儿都很干净。但紧接着是 25 个转发 property:

@property
def user_repo(self) -> UserRepo:
    return self.repos.user_repo

每一个 repo 都写了一遍。这是明显的重构痕迹:SharedServices 原本是扁平的(25 个字段直接挂在上面),后来被收进 repos 这一层,为了不破坏几百处 services.agent_repo 的调用,加了一层 property 转发。

这类代码在长期项目里到处都是,它不算优雅,但它是"能持续重构"的代价。 反过来说,如果一开始就没做这个收拢,SharedServices 会一直是个 25 字段的大杂烩。

第 1 篇讲过 app_runtime 只有 8 个字段——那个边界之所以干净,是因为有一层 SharedServices 替它吸收了这 25 个 repo。

三、双后端的本质:把 PostgreSQL 伪装成 SQLite

pool.py 只有 176 行,是整个双后端策略的全部实现。核心三个垫片。

垫片一:占位符改写。

def qmark_to_pyformat(sql: str) -> str:
    """Rewrite ``?`` placeholders to psycopg ``%s`` (no string-literal awareness)."""
    return sql.replace("?", "%s")

一行。注释里那句 “no string-literal awareness”(不识别字符串字面量)是老实交代:如果 SQL 里有个 'what?' 这样的字符串,? 会被误替换成 %s。

这意味着上层写 SQL 时不能随便用 ? 字符。这是个隐式约束,没有类型检查帮你,只能靠约定和测试。

垫片二:行对象兼容。

class _CompatRow(Mapping[str, Any]):
    """Row that supports both ``row["col"]`` and ``row[0]`` like sqlite3.Row."""

    def __getitem__(self, key: str | int) -> Any:
        if isinstance(key, int):
            return self._values[key]
        return self._map[key]

sqlite3.Row 同时支持下标和键名,psycopg 的 dict_row 只支持键名。为了 25 个 repo 不用区分后端,手写一个两者都支持的 Row。

垫片三:连接代理。

class _PgConnectionProxy:
    """Expose sqlite-like ``execute`` / ``executescript`` on a psycopg connection."""

    def execute(self, sql: str, params: Any = None) -> Any:
        return self._conn.execute(qmark_to_pyformat(sql), params)

    def __getattr__(self, name: str) -> Any:
        return getattr(self._conn, name)

__getattr__ 兜底把所有其它属性透传,只拦截 execute。

ADR 里把这件事说得很直接:「Repos keep ? placeholders; PostgresPool rewrites to %s at the boundary.」

评价:这是很务实的做法,省掉了 25 个 repo 各写两套 SQL。但它有个天花板——SQL 方言差异不可能靠三个垫片抹平。

比如 ON CONFLICT 两边语法接近但不是全部一致,RETURNING 的用法不同,日期函数完全不同(strftime vs to_char),AUTOINCREMENT vs SERIAL/GENERATED。这些只能靠 if db.dialect == "postgresql" 在具体 repo 里分支。

我 grep 了一下,migrate.py 里 db.dialect == "postgresql" 出现 20 处。所以"伪装"只覆盖了 80%,剩下 20% 的分支散在各处。

而且 ADR 自己列了一条硬限制:

Single active Octop writer; no multi-instance write promise.

单写者,不承诺多实例写。 换 PostgreSQL 的理由是"合规 / 状态外置",不是"水平扩展"。这和 ADR 001 的"只能垂直扩容"是一致的——两个 ADR 互相咬合。

四、SqlitePool 其实不是池

名字叫 Pool,实现是单连接 + 一把 RLock:

class SqlitePool:
    """Single shared SQLite connection guarded by an RLock."""

    def __init__(self, path: Path):
        self._conn = sqlite3.connect(str(self.path), check_same_thread=False, isolation_level=None)
        self._conn.row_factory = sqlite3.Row
        self._conn.execute("PRAGMA foreign_keys = ON")
        self._conn.execute("PRAGMA journal_mode = WAL")
        self._lock = threading.RLock()
        if first_create and os.name == "posix":
            os.chmod(self.path, 0o600)

五个细节各有原因:

  • check_same_thread=False + RLock:跨线程用同一个连接,靠锁串行化。SQLite 连接默认不能跨线程,这是绕过的标准姿势。
  • isolation_level=None:关掉 Python 的自动事务管理,改成手写 BEGIN/COMMIT。
  • PRAGMA foreign_keys = ON:SQLite 的外键约束默认是关的,不显式打开,所有 REFERENCES 都是装饰。
  • journal_mode = WAL:读写不互斥,适合"一写多读"。
  • chmod 0o600:首次创建时收紧权限。这个敏感库里有 JWT 密钥和各家 API Key。

为什么只有一个连接?因为 ADR 001 定了单进程、单写者。多连接在 SQLite 上只会带来锁竞争,不如串行化。

然后是全文最值得抄的一段注释:

@contextmanager
def transaction(self) -> Iterator[sqlite3.Connection]:
    with self._lock:
        # BEGIN IMMEDIATE, not a deferred BEGIN. A transaction that reads first and writes
        # later only takes the write lock at that first write, so another connection — a
        # second worker process (``octop run --workers N``), or a CLI run against a running
        # server — can commit in between. SQLite then rejects our write with
        # SQLITE_BUSY_SNAPSHOT ("database is locked") *immediately*; the 5s busy timeout
        # cannot wait that out. Taking the write lock up front makes the competing writer
        # wait instead of aborting us.
        self._conn.execute("BEGIN IMMEDIATE")
        try:
            yield self._conn
            self._conn.execute("COMMIT")
        except Exception:
            self._conn.execute("ROLLBACK")
            raise

把这段话翻译清楚,因为它是 SQLite 并发写的一个经典坑:

默认的 BEGIN 是 deferred 的——事务开始时只拿读锁,等到第一次写才升级成写锁。如果两个连接都"先读后写",两边都拿到读锁,然后都要升级,SQLite 会把后升级的那个直接拒掉(SQLITE_BUSY_SNAPSHOT),而且这个拒绝是立即的,busy_timeout 等不了。

结果就是:你以为配了 5 秒超时能等到,实际上直接报错。

BEGIN IMMEDIATE 一开始就拿写锁,后来的连接会在入口排队等,而不是进来之后被打死。

这个坑的触发条件很具体:多进程。 octop run --workers N,或者"服务在跑着、同时用 CLI 操作同一个库"。单进程单连接时永远不会遇到,所以很容易在开发阶段漏掉,上线开多 worker 才炸。

五、migrate.py 为什么 2,110 行

这是本篇最重的一块。先看规模:

ls src/octop/infra/db/migrations/*.sql | wc -l      # 42
ls src/octop/infra/db/migrations/*.pg.sql | wc -l   # 21

21 组迁移,每组两份:NNN_*.sql 给 SQLite,NNN_*.pg.sql 给 PostgreSQL。

按正常想象,迁移器应该就是"读出文件、按顺序执行、更新版本号",一两百行足够。多出来的 1,900 行全是兼容。

原因一:SQLite 不支持大部分 ALTER TABLE。

不能删列、不能改列类型、不能加约束。想在一张已有数据的表上"去掉一个字段",唯一办法是:建新表 → 拷数据 → 删旧表 → 改名。所以每个 schema 变更都有一套手写的"探测-重建"逻辑。

举个例子,_apply_sqlite_migration 里版本 5 的实现:

if version == 5:
    if _table_exists(db, "agents"):
        _ensure_column(db, "agents", "is_shared", "INTEGER NOT NULL DEFAULT 0")
        with db.connect() as conn:
            conn.execute(
                "CREATE INDEX IF NOT EXISTS idx_agents_shared "
                "ON agents(is_shared) WHERE is_shared = 1"
            )
    _ensure_published_experts_schema(db)
    _ensure_sso_oidc_schema(db)
    _ensure_knowledge_bases_schema(db)
    with db.connect() as conn:
        conn.execute("UPDATE _schema_version SET version = ?", (version,))
    return

注意它没有执行 005_*.sql——SQLite 的迁移是用 Python 重写的。所以同一个迁移实际要维护三份:

文件/位置用途
NNN_*.sqlSQLite 的声明式定义(新库初始化 / 参考)
NNN_*.pg.sqlPostgreSQL 实际执行
migrate.py 里的 if version == N: 分支SQLite 实际执行

_apply_sqlite_migration 的 docstring 把 v2 到 v18 每个版本干了什么全列了一遍——这三十来行注释就是整个项目的 schema 演进史,比任何设计文档都有用:

Version 2  cron_jobs.mcp_servers、技能包
Version 3  重写遗留的硬截断 thread 标题
Version 4  threads 的 composer 三列(model_ref / reasoning_mode / reasoning_effort)
Version 5  共享专家、发布模板、OIDC SSO、知识库
Version 6  users.permissions
Version 7  profile 列、thread artifacts、整数主键 + 公开字符串 id、文档目录、删 knowledge_base_members
Version 8  带缓存的 usage 分桶与调用计数
Version 9  一次性邀请码
Version 10 dashboard 的 thread-message 投影
Version 11 cron 任务显示名
Version 12 只增不改的轨迹事件账本
Version 13 多实例与共享连接器
Version 14 用户级命名策略行
Version 15 可插拔 SSO provider kind、多身份表
Version 16 agents.kind(团队主机可被列出)
Version 17 threads 的 conversation_mode 与 pending_plan_path
Version 18 user_role 模板

从 v1 到 v18 只用了三四个月(ADR 002 日期 2026-07-20,现在 10 月)。这个迭代速度解释了为什么迁移器会长成这样:每次都要快速上线、又不能让早期用户升不上去。

原因二:版本号不可信。

run_migrations() 在按版本号跑完之后,还有一段无条件执行的收尾:

_reconcile_pre_squash_schema_version(db)
_ensure_knowledge_bases_schema(db)
_ensure_skill_packages_schema(db)
_ensure_published_experts_schema(db)
_ensure_usage_cache_schema(db)
_ensure_user_invites_schema(db)
_ensure_thread_message_projection_schema(db)
_ensure_cron_jobs_schema(db)
_ensure_trajectory_events_schema(db)
_ensure_connectors_v13_schema(db)
_ensure_user_policy_schema(db)
_ensure_agent_teams_schema(db)
_ensure_thread_conversation_mode_schema(db)
_ensure_agent_profile_columns(db)
_ensure_sso_provider_kind_schema(db)
_ensure_user_role_schema(db)
_ensure_bridge_connections_schema(db)
_grant_default_nav_permissions(db)
_grant_personalization_tab_permissions(db)

16 个 _ensure_*,外加两个 _grant_*,每次启动都跑一遍,不看版本号。

因为版本号可能是错的。用户的库可能来自:旧版本手动升上来的、从备份恢复的、跨版本跳的、被 squash 过的(注释里的 _reconcile_pre_squash_schema_version 就是处理这个)。这些情况下"版本号说 21,实际 schema 是 14"很常见。

所以策略变成:不信任状态标记,每次启动把实际 schema 对一遍账。 这是"声明式幂等"的胜利——每个 _ensure_* 都是"如果缺就补,如果对就不动"。

代价也直接:每次启动要做几十次 PRAGMA table_info / information_schema.columns 查询,还要在 SQLite 和 PostgreSQL 各维护一份判定。2110 行里大概 60% 是这些 _ensure_* 的 if-else。

这和第 5 篇那个味道是一样的:boot() 里"超时了但已注册就当成功",_ensure_* 里"版本号说对了我还是再查一遍"。同一个团队,面对"状态不可信"给出了同一个答案:查实际状态,别信记录。

顺带一个纪律:_discover() 发现重复版本号时直接抛错,错误信息写明了正确做法:

raise RuntimeError(
    f"Duplicate migration version {version:03d}: {prior.name} and {path.name}. "
    "Fold unreleased schema into a single NNN_*.sql / NNN_*.pg.sql pair."
)

「未发布的 schema 改动要折叠进现有文件」——不这么做,迁移文件会随开发进度线性膨胀,而用户其实只需要最终态。

六、三层存储各有一个坑

最后把三层各自的边界记一下。

坑一:控制面换后端,没有迁移工具。

ADR 002 最后一行:

Greenfield only — no SQLite→PG data migrator.

只支持全新部署。 你已经用 SQLite 跑了一年,想换成 PostgreSQL?没有内置工具,得自己导。

这条写得很诚实,但也很容易被忽略——用户看到"支持 PostgreSQL"就以为能无缝切换,实际上是从零开始。

坑二:checkpoints.sqlite 在 workspace 里,不在控制面。

这意味着:备份控制面不等于备份对话。 第 1 篇讲过 backup create 会打包 DB + workspace + 配置,那是因为三层存储分散在不同位置,单备一个库没用。

也意味着:删 Agent 的时候要记得清 workspace,否则会留下孤儿 checkpoint。第 5 篇那个 _abort_incomplete_create() 回滚就是在防这个。

坑三:memory 换 PostgreSQL 时用独立 schema。

memory 用 postgres 时:同 DSN,独立 schema agent_<id>

不是独立库,是同一个库里按 Agent 分 schema。这样做的原因大概是连接池复用——但 schema 数量会随 Agent 数量线性增长,几百个 Agent 就是几百个 schema。这算不算问题,取决于 PostgreSQL 的 schema 管理能力,我没深究。

总结

数据层四句话:

  1. 存储是三层,不是一层。 控制面(33 张表 / 472K)、harness 检查点(每个 workspace 一份)、Agent 记忆(每个 workspace 一份,DDL 归 octop-memory 管)。ADR 原话「不要混为一谈」,因为备份、迁移、删除要分别处理。
  2. 双后端的实现是"把 PostgreSQL 伪装成 SQLite"。 三个垫片:?→%s(不识别字符串字面量)、_CompatRow(下标和键名都支持)、_PgConnectionProxy(透传一切只拦 execute)。只覆盖 80%,剩下 20% 靠 if db.dialect == "postgresql" 分散在仓库各处。
  3. SqlitePool 是单连接加一把 RLock,不是池。 最值钱的是那段 BEGIN IMMEDIATE 注释——默认 BEGIN 是先读后写升级锁,多进程下会被 SQLite 用 SQLITE_BUSY_SNAPSHOT 立即拒掉,busy_timeout 等不了。这个坑只在多进程下出现,单进程开发时永远碰不到。
  4. migrate.py 2100 行的 60% 是「不信任版本号」的代价。 21 组迁移要写三份(SQLite 声明式 / PG 文件 / Python 分支),外加 17 个每次启动都跑的 _ensure_*_schema() 对账函数。

顺带记一个实测:每个 Agent 的 memory.sqlite 主库 384–488K,WAL 文件 1.8M。WAL 比主库大四倍,说明高频写入下 SQLite 的文件膨胀是这类项目绕不过去的运维负担——和第 5 篇的 reclaim(压 freelist)是同一类问题的两面。

下一篇按编号写 配置与首次引导:config.py(633 行)、PathLayout、setup 向导,以及第 1 篇那个"启动了一半"的分叉到底怎么收尾。

参考链接

  • 仓库:https://github.com/TencentCloud/Octop(MIT)
  • 本文主读文件:
    • src/octop/infra/db/pool.py(176 行)
    • src/octop/infra/db/services.py(217 行)
    • src/octop/infra/db/migrate.py(2,110 行)
    • src/octop/infra/db/migrations/(21 组 × 2 份)
  • 架构决策:docs/adr/002-database-backends.md(三层存储、单写者、greenfield-only)
  • 前一篇:(1)先摊开地图