0 Fork 0

Files

T

chenxin 5da1efe921 📝 docs: 统一 PostgreSQL 主库并固化索引命名约定

- 新增 ADR-024：服务端关系主库统一 PostgreSQL，不设 SQLite 档（pgvector 与中文全文无法在 SQLite 承载，双档必然残缺或第二实现）；端侧离线缓存不受约束
- AGENTS.md：权威事实源与部署句更新；8.6 固化 pk_/uk_/idx_/fk_ 索引命名约定
- system-architecture、data-architecture、memory-and-knowledge、roadmap WP-01、handoff（决策 29）同步清理 SQLite 引用

2026-09-09 21:14:10 +08:00

6.1 KiB

Raw Permalink Blame History

系统架构

1. 逻辑架构

完整 1.0 由多端客户端、统一 API、领域模块、Agent/Plugin Runtime、媒体与实时处理、生态与交易模块以及隔离执行边界组成。逻辑边界是强约束，物理部署可按规模合并或拆分。

flowchart LR
  subgraph Clients
    WEB[Web]
    DESK[Tauri Desktop]
    MOB[Tauri Mobile]
  end

  WEB & DESK & MOB --> EDGE[API and Realtime Edge]
  EDGE --> CORE[Core Application]
  CORE --> AGENT[Agent Runtime]
  CORE --> SOCIAL[Community and Collaboration]
  CORE --> MARKET[Marketplace and Ledger]
  CORE --> MEDIA[Media and Avatar Runtime]
  AGENT --> PLUGIN[Plugin Runtime]
  PLUGIN --> MODELS[Model Providers]
  PLUGIN --> TOOLS[Tools and MCP]
  CORE --> DATA[(Primary Data)]
  MEDIA --> OBJECTS[(Media Objects)]
  AGENT --> SANDBOX[Sandbox Workers]

2. 模块职责

模块	职责	禁止承担
Identity & Domain	登录、用户、设备、数据域、会话	角色人格和模型路由
Character	角色、设定版本、关系、谱系、导入导出	Provider 凭据和交易账
Conversation	多模态消息、分支、引用、流式和压缩	决定长期记忆写入
Memory & Knowledge	候选、版本、召回、纠正、删除、索引	覆盖角色基线
Agent Runtime	Agent/Run/Turn、计划、并行、暂停、取消、验收	绕过 Policy 执行工具
Model Gateway	Provider、逻辑模型、路由、流式、usage、成本	角色和社区业务
Plugin Runtime	Manifest、生命周期、Snapshot、Registry、SDK	身份根策略和交易账
Tool & Sandbox	Schema、审批、幂等、隔离执行、结果净化	自行扩大能力范围
Media Pipeline	ASR/TTS、图像、Live2D、3D 资产处理	授予设备采集权限
Avatar Runtime	Live2D/3D 渲染、动作、表情、场景同步	修改权威角色数据
Device Capability	文件、相机、麦克风、屏幕、位置和设备授权	后台常开采集
Community	社交图、内容、互动、搜索、推荐、治理	支付结算和私密记忆
Collaboration	Workspace、RBAC、邀请、评审、版本、协同	跨 Workspace 隐式共享
Marketplace	商品、许可、交付和版本可售性	直接改写支付账
Payment & Ledger	订单、支付、退款、分成、余额、结算、对账	浮点金额和可变历史账
Policy & Moderation	工具、插件、设备、内容、交易和年龄策略	执行业务副作用
Observability	Trace、Run 诊断、审计、成本、支持包	普通接口泄露敏感正文

3. 物理部署原则

开发期可在模块化单体中合并多数业务模块，但以下边界必须独立：

Sandbox Worker：执行不可信代码；
Media Worker：处理重型媒体任务；
Realtime Gateway：SSE/WebSocket/语音会话；
Payment Webhook Consumer：验签、幂等和账务入账；
Object Storage：媒体和市场交付物；
Search/Index Worker：全文、向量和社区索引。

flowchart TD
  C[Clients] --> E[Edge and Realtime]
  E --> A[Application API]
  A --> DB[(PostgreSQL)]
  A --> R[(Redis)]
  A --> S3[(S3-compatible Storage)]
  A --> W[Job Workers]
  W --> SB[Sandbox Pool]
  W --> GPU[Media or GPU Workers]
  W --> IDX[Search and Vector Index]
  A --> PAY[Payment Providers]
  PAY --> WH[Webhook Consumer]
  WH --> DB

PersonalDomain 创建或迁移时绑定一个固定数据区域：权威数据、密钥、对象、索引和备份在该区域驻留，不因流量路由、故障转移或用户旅行自动跨区漂移；跨区只能走正式迁移协议。跨区模型处理按地区规则、数据敏感度和用户授权单独治理，且必须经用户明确披露与授权；高敏数据（含私箧）可完全禁止跨区模型处理。

自托管遥测默认关闭。关系主库在开发、测试与自托管中统一 PostgreSQL（ADR-024）；正式云与社区/交易部署按完整 1.0 能力启用 Redis、对象存储和异步 Worker。向量库、图数据库与独立 Go 网关按量化规模选择，不因技术清单强制引入。灵台引擎默认进程内嵌入；满足独立扩缩容、故障域或资源隔离标准时可启用 hunjing-lingtai-server 独立服务形态（见灵台引擎架构）。

4. 客户端边界

Web：完整社区、市场、创作、对话和管理体验。
Tauri Desktop：Web 能力加本地文件、屏幕、相机、麦克风、系统通知和沙箱桥接。
Tauri Mobile：iOS/Android 的相机、麦克风、文件、位置、通知和 Avatar 运行。
客户端权限由平台权限和 Hunjing device_grant 双重约束。
客户端不保存平台 Provider 密钥；离线缓存按用户和设备加密。

5. 数据与信任边界

每次资源访问验证数据域、Workspace、角色、内容可见性和交易主体。
Provider Header deny-by-default，仅 Adapter 白名单透传。
插件贡献能力；Core 决定加载、权限、审批、数据和审计。
未可信插件不进入主进程；没有可用隔离后端时拒绝执行。
支付 Provider Webhook 先验签和幂等，再写不可变账务记录。
社区公开内容、协作私有内容、角色私密数据和诊断数据使用不同访问策略。
设备采集默认关闭，逐能力展示状态并可即时撤回。
市场许可不自动授予插件执行权限、角色私密数据或设备能力。

6. 可靠性目标

1.0 目标值：核心文字相伴官方云 SLO 99.9%；权威数据 RPO 不高于 5 分钟、RTO 不高于 1 小时，以恢复演练而非配置声明证明；媒体与可重建索引可采用更宽目标但不阻塞权威恢复。SLI 口径、窗口与排除规则在发布门前定义并验证（见发布门）。

7. 服务拆分标准

模块只有满足独立扩缩容、故障域、数据/密钥边界、团队发布节奏或量化瓶颈时才拆服务。拆分保持端口、事件和账务契约；不因语言偏好拆分。

6.1 KiB Raw Permalink Blame History Unescape Escape