weichen
13fd7b3a55
Details (original message): Document the dual-tier storage, multitenancy, and scaling delivery (proposal, implementation record, test report, usage guide)
4.3 KiB
4.3 KiB
提案：双档存储、多租户与规模化（2026-09-30）
状态：accepted（实施已完成，见实施记录）。 前置：系统骨架设计与计划（D5/D16 双档存储预留）。
1. 背景与决策
产品方向确认为多租户、多用户、高并发（用户确认，2026-09-30）。骨架期"单用户本地部署"假设据此修订： 多租户为既定主线，嵌入式单二进制仍为默认档与最高部署约束（非容器化不变）。
对既有设计的影响：
- §2.2 非目标中"多租户/计费/注册远期不做"修订为"多租户已立项（本提案）；计费/注册仍远期"。
- D5/D16 的 PostgreSQL 可选档转正为多用户主机档路线；SQLite 嵌入式档保持默认。
- 7.2 远期表中"向量 RAG 管线"前移至本期交付。
2. 决策（D17–D24）
| # | 决策 | 理由 |
|---|---|---|
| D17 | 租户模型：user 即 owner；API key（ask_ 前缀，库存 SHA-256 摘要，明文仅创建时返回一次）认证；嵌入式档默认关闭认证（回环单用户），PG 档默认开启（--auth auto/on/off） |
最小可审计的 API-first 租户身份；不引入注册/计费 |
| D18 | 租户列 owner 冗余落位（projects/conversations/runs/artifacts/knowledge/hitl_cards/profiles/settings），跨租户访问一律 NotFound（不泄露存在性）；知识 owner='' 为共享 |
现在零成本落位；后补需全量回填且易漏 |
| D19 | 存储双档：默认 SQLite（单二进制不变）；--dsn 显式切换 PostgreSQL 档（原生安装，非容器）；方言差异收敛在 store 包 dialect；查询统一 ? 书写、PG 重绑 $n |
D16 落地；业务层零感知 |
| D20 | schema 版本化迁移：schema_migrations 版本表 + 双方言 up/down + 基线 v1=旧形态（既有部署与新建库同路径演进）；回滚为运维入口（多租户数据折回限制在 down 注释标明） |
骨架期"CREATE IF NOT EXISTS"不可演进；补齐设计 446 的回滚要求 |
| D21 | 一致性加固：消息 seq 单语句分配 + UNIQUE(conversation_id,seq) 约束兜底重试；设置合并/读改写走事务 + 会话咨询锁（PG）/单写连接（SQLite）；HITL resolve 原子条件更新；工件写临时文件+rename 且删行先行 |
数据可靠性标准（同号并发、CAS、跨租户拒绝） |
| D22 | 事件写放大治理：高频增量（delta/progress）批处理（150ms/64 条冲盘），seq 改为会话内连续并在落盘事务内分配；立即事件（终态/HITL/工具）落盘后发布；优雅停机冲净缓冲 | 每 delta 一次 fsync 不可扩展；SSE 游标/重放语义不变 |
| D23 | 向量 RAG：Chunker/EmbeddingProvider/VectorIndex/Reranker/Retriever 契约（Core）；段落感知分块（默认 800/重叠 120）→ 全文入库 →（配置 embedding 时）向量入库；检索 = 向量+全文 RRF 融合（k=60）→（配置 rerank 时）重排；向量双档同构 BLOB+进程内余弦，pgvector+HNSW 为 PG 档优化路径 | 设计 4.12 前移；未配置自动退化为纯全文（默认行为不变） |
| D24 | 多实例地基：工件对象存储抽象（本地目录档；共享卷=改路径）；PG 档事件扇出 NOTIFY/LISTEN（agent_events，载荷 `会话 |
末seq，按 seq 取回，SSE 去重容忍双投）；租户限流固定窗口（进程内档默认，设置 runtime.redisAddr` 切原生 Redis 共享档）；多实例部署契约 = 会话亲和路由（run 归属实例内存执行） |
3. 边界与不做
- 不引入容器：开发验证使用本机原生 PostgreSQL/Redis 实例（多实例由 initdb/端口区分）。
- 不做注册/计费/密码登录（远期）；不做跨实例 run 迁移（依赖会话亲和）。
- pgvector 列级索引（HNSW）未启用：BLOB+余弦扫描面向 ≤ 数万块/实例，规模到此再优化（换实现不动契约）。
- SSE 认证用
?key=兜底（EventSource 无法带 header）；密钥经 URL 属于已知权衡，网关侧可剥离日志。
4. 验收与证据
见测试报告 2026-09-30（双档全量、真实约束/并发/越权负例、原生 Redis/PG 集成、单二进制构建）。