# 魂镜系统总架构

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

## 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 界面、响应式交互、治理与可解释呈现 | 不保存平台密钥，不绕过灵台和司命直连高风险能力 |

```mermaid
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 只在少量已验证区域实际运营。实际首发区域、运营主体、隐私控制者、支付税务和正式法律文本属于发布决策门，本文不指定。

```mermaid
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` 只允许本地开发；标准服务器和官方云必须在启动/发布检查中拒绝这些配置。