魂镜系统总架构

本文同时说明当前过渡拓扑与目标架构。目标职责不表示能力已落地；当前实现和迁移差距必须由能力矩阵单独确认。

1. 架构目标

魂镜以人物连续性、用户主权、区域驻留、可审计行动和可恢复运行为首要约束。目标形态由四个清晰解耦的服务组成；轻量部署可以关闭高风险能力，但不得把职责混回其他服务。

2. 当前过渡拓扑

当前代码尚未完成四服务物理拆分：

Python 灵台仍直接承载模型 Provider 配置、Endpoint 池和路由实现；这是待迁移的现状，不是目标边界；
现有 Go 网关是玄关（MCP Gateway），负责 MCP 服务和工具管理，不是目标神识模型网关；前端 /api/gateway/* 代理指向玄关；
当前应用 Compose 未部署独立 Go 神识；依赖该能力的条目在能力矩阵中必须标为未实现或过渡实现；
Rust 乾坤与 Next.js 琉璃镜已经有独立工程，但其生产安全与发布证据仍以能力矩阵为准。

过渡期新增模型接入仍应封装在 Python ai_provider 边界内，不向领域模块扩散 Provider SDK。迁移到 Go 神识前必须先确定模型请求/流式响应、鉴权、BYOK 密钥归属、用量、错误、回滚和并存期限；不得把现有玄关直接改名后冒充神识。

3. 目标四服务

服务	技术	核心职责	明确边界
灵台	Python	人物身份与认知业务、镜树运行、九枢编排、记忆与关系状态、司命裁决、百工注册	不承担通用模型协议网关；不直接执行不可信代码
神识	Go	Provider/Endpoint 接入、能力槽位、协议转换、路由、流式、BYOK、配额与成本	不拥有人物人格、记忆、关系或身份状态；参考 aiway 架构与功能，但不 Fork、不复制源码、不作为运行依赖
乾坤	Rust	隔离执行、设备安全、本地安全控制与硬急停边界	不决定人物目标，不保存可独立成长的人物副本
琉璃镜	TypeScript / Next.js	全部 Web 界面、响应式交互、治理与可解释呈现	不保存平台密钥，不绕过灵台和司命直连高风险能力

flowchart LR
    U[执镜者与互动者] --> W[琉璃镜<br/>Next.js Web]
    W --> L[灵台<br/>Python 生命与认知业务]
    L --> G[神识<br/>Go 模型网关]
    G --> P[模型 Provider / BYOK Endpoint]
    L --> K[乾坤<br/>Rust 隔离执行与设备安全]
    K --> E[工具、设备与本地执行环境]
    L --> D[(区域内权威数据)]
    L --> A[(事件审计与行动账)]

4. 区域云

官方云面向全球开放，但能力按地区分级。每个镜域在创建或迁移时绑定一个固定数据区域：权威数据、密钥、对象、索引和备份均在该区域驻留，不因流量路由、故障转移或用户旅行自动跨区漂移。

架构须支持多区域；1.0 只在少量已验证区域实际运营。实际首发区域、运营主体、隐私控制者、支付税务和正式法律文本属于发布决策门，本文不指定。

flowchart TB
    R[全球入口与地区能力判定]
    R --> RegionAEntry[区域 A 入口]
    R --> RegionBEntry[区域 B 入口]
    R --> N[后续已验证区域]
    subgraph RegionA[镜域固定驻留区域 A]
      RegionAEntry --> A1[四服务实例]
      A1 --> A2[(权威数据、密钥、对象、索引、备份)]
    end
    subgraph RegionB[镜域固定驻留区域 B]
      RegionBEntry --> B1[四服务实例]
      B1 --> B2[(权威数据、密钥、对象、索引、备份)]
    end
    A2 -.仅经正式迁移协议.-> B2

5. 数据总架构

关系数据库是当前状态事实源。
关键事件、治理裁决与外部行动形成不可缺失的审计链。
状态变更与事件通过同一事务或 Outbox 一致提交，避免“状态已变但事件缺失”。
轻量自托管采用 SQLite、可选 Chroma/向量层、本地对象存储和内存协调。
标准服务采用 PostgreSQL、pgvector、S3/MinIO 与 Redis；Milvus 和图库只在真实规模需要时引入。
可重建索引不是权威事实源；任何恢复均须从权威数据重建并校验。

6. 可靠性总架构

核心文字相伴官方云 1.0 的目标 SLO 为 99.9%。权威人物数据目标 RPO ≤ 5 分钟、RTO ≤ 1 小时；媒体和可重建索引可以采用更宽目标，但不得阻碍权威状态恢复。

可靠性手段包括：健康检查、超时与限流、模型端点故障切换、幂等、事务/Outbox、可验证备份、恢复演练、区域内高可用，以及对降级能力的显式说明。跨区域灾备不得突破镜域固定驻留约束；若需要跨区迁移，必须走正式身份与数据迁移协议。

7. 部署档位

档位	目标	基础设施
本地开发	单机开发与测试，不可用于生产	SQLite、本地对象、内存协调；允许宿主端口和示例凭证
轻量单机	私人闭环、低运维、自托管	SQLite、本地对象、内存协调，可选本地向量层
标准服务器	稳定多人/多人物服务	PostgreSQL、pgvector、S3/MinIO、Redis
官方区域云	区域驻留、可运营、满足发布门	四服务区域化部署、区域内高可用、备份与灾备体系

自托管以 Docker Compose 为主、源码开发为辅，遥测默认关闭。部署档位改变基础设施规模，不改变四服务的逻辑职责或禁域。change-me、无认证管理端口、宿主机全量端口暴露和 STORAGE_PROVIDER=local 只允许本地开发；标准服务器和官方云必须在启动/发布检查中拒绝这些配置。

5.7 KiB Raw Permalink Blame History Unescape Escape