跳到主要内容

数据库设计

后端选择​

环境后端
本地开发（默认）SQLite（零配置）
生产（设置 DATABASE_URL）PostgreSQL

选择逻辑在 memex.core.task_manager._database_backend()：DATABASE_URL 存在且 scheme 为 postgres/postgresql 时走 PG，否则回退 SQLite。

职责边界​

数据库（权威状态）：books · wiki_repositories · jobs · job_queue · job_events · job_steps · token_usage · settings · wiki_state · wiki_runtime · api_tokens

文件系统（证据层）：wiki 页面、review jsonl、preview 产物、butler 行为日志

长期目标：文件作为证据层，数据库作为运行态权威层。

核心表​

jobs​

记录 Wiki 构建任务主状态，是控制面任务列表、调度与恢复的入口。

关键字段：id · wiki_slug · target_dir · lang · status · phase · error · owner_username · started_at · completed_at

token_usage​

每个 job phase 的 token 数、cost、duration，用于成本分析和运行时 dashboard。

job_steps / job_events​

  • job_steps：结构化步骤日志，用于前端阶段详情和失败复盘
  • job_events：流式事件（review、log），用于 SSE 回放和结构化审计

wiki_state​

每个 wiki 的聚合状态缓存：egg_done · birth_done · grow_done · corpus_chars · page_count · wiki_chars，用于 overview 和 grow 预估。

wiki_runtime​

保存 serve/butler 运行态，用于 preview 状态恢复和 runtime 管理。

api_tokens​

Bearer token 的 hash 与角色信息（admin/user）。

建表规范（PostgreSQL）​

  • 主键：运行表用 BIGINT GENERATED BY DEFAULT AS IDENTITY；天然唯一键表用业务键（如 settings.key）
  • 审计字段：所有表必须有 created_at / updated_at（TIMESTAMPTZ NOT NULL DEFAULT now()）
  • 更新时间：所有表绑定 memex_set_updated_at() 触发器
  • JSON 字段：结构化扩展字段用 JSONB（job_events.event_data、wiki_runtime.butler_state 等）
  • 外键：日志/队列/租约类随 job 删除（ON DELETE CASCADE）；指纹表用 ON DELETE SET NULL
  • 索引：围绕调度、列表页、事件回放建组合索引，避免只建单列索引

SQLite / PostgreSQL 差异处理​

已处理：ON CONFLICT 方言 · RETURNING id · PG JSONB 参数包装 · 日期统计分支 · 进程级共享 Engine（QueuePool，默认 5+5）

连接池实测效果：16 线程并发仅占 3 个连接（旧代码 16 个），彻底解决生产 "FATAL: too many clients" 问题。