跳到主要内容

数据库设计

后端选择​

环境后端
本地开发 / minimalPostgreSQL
内网 / 生产PostgreSQL

DATABASE_URL 必须存在并使用 postgres/postgresql scheme，否则 Service 拒绝启动。 SQLite 不再是平台运行后端；迁移期仅由测试套件通过显式开关启用临时 adapter。 memex batch/status 的独立本地跟踪库不属于平台数据库。

职责边界​

数据库（权威状态）：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。 已处理：RETURNING id · PG JSONB 参数包装 · 日期统计 · 进程级共享 Engine（QueuePool，默认 5+5）。

当 PostgreSQL 集成测试成为 CI 必跑项后，将删除测试 adapter 和剩余 SQLite 平台 schema。

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