chenxin
5da1efe921
- 新增 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 引用
108 lines
6.1 KiB
Markdown
108 lines
6.1 KiB
Markdown
# 系统架构
|
||
|
||
## 1. 逻辑架构
|
||
|
||
完整 1.0 由多端客户端、统一 API、领域模块、Agent/Plugin Runtime、媒体与实时处理、生态与交易模块以及隔离执行边界组成。逻辑边界是强约束，物理部署可按规模合并或拆分。
|
||
|
||
```mermaid
|
||
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：全文、向量和社区索引。
|
||
|
||
```mermaid
|
||
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](../decisions/README.md#adr-024关系主库统一-postgresql不设-sqlite-档)）；正式云与社区/交易部署按完整 1.0 能力启用 Redis、对象存储和异步 Worker。向量库、图数据库与独立 Go 网关按量化规模选择，不因技术清单强制引入。灵台引擎默认进程内嵌入；满足独立扩缩容、故障域或资源隔离标准时可启用 `hunjing-lingtai-server` 独立服务形态（见[灵台引擎架构](lingtai-engine.md)）。
|
||
|
||
## 4. 客户端边界
|
||
|
||
- Web：完整社区、市场、创作、对话和管理体验。
|
||
- Tauri Desktop：Web 能力加本地文件、屏幕、相机、麦克风、系统通知和沙箱桥接。
|
||
- Tauri Mobile：iOS/Android 的相机、麦克风、文件、位置、通知和 Avatar 运行。
|
||
- 客户端权限由平台权限和 Hunjing `device_grant` 双重约束。
|
||
- 客户端不保存平台 Provider 密钥；离线缓存按用户和设备加密。
|
||
|
||
## 5. 数据与信任边界
|
||
|
||
1. 每次资源访问验证数据域、Workspace、角色、内容可见性和交易主体。
|
||
2. Provider Header deny-by-default，仅 Adapter 白名单透传。
|
||
3. 插件贡献能力；Core 决定加载、权限、审批、数据和审计。
|
||
4. 未可信插件不进入主进程；没有可用隔离后端时拒绝执行。
|
||
5. 支付 Provider Webhook 先验签和幂等，再写不可变账务记录。
|
||
6. 社区公开内容、协作私有内容、角色私密数据和诊断数据使用不同访问策略。
|
||
7. 设备采集默认关闭，逐能力展示状态并可即时撤回。
|
||
8. 市场许可不自动授予插件执行权限、角色私密数据或设备能力。
|
||
|
||
## 6. 可靠性目标
|
||
|
||
1.0 目标值：核心文字相伴官方云 SLO 99.9%；权威数据 RPO 不高于 5 分钟、RTO 不高于 1 小时，以恢复演练而非配置声明证明；媒体与可重建索引可采用更宽目标但不阻塞权威恢复。SLI 口径、窗口与排除规则在发布门前定义并验证（见[发布门](../product/complete-1.0-scope.md#44-可靠性门)）。
|
||
|
||
## 7. 服务拆分标准
|
||
|
||
模块只有满足独立扩缩容、故障域、数据/密钥边界、团队发布节奏或量化瓶颈时才拆服务。拆分保持端口、事件和账务契约；不因语言偏好拆分。
|