主题
02 - 总体架构：分层设计与全链路数据流
一句话：QwenPaw 的存储是硬编码本地形态，sqlite3 与 ZIP 备份直写文件系统，所以企业化选择“不改源码”，用 PostgreSQL 做权威注册表、用同步器把 PVC 里的备份与 SQLite 里的审计往外搬；代价是数据主权被切成两半——会话与记忆的真值永远留在实例卷里，控制面只持有归档和增量副本，卷一旦丢失就退化为 24 小时前的备份。
一、关键架构决策：QwenPaw 保持单机形态
QwenPaw 的存储和数据库实现是硬编码本地形态：
| 维度 | QwenPaw 实际实现 | 企业化对策 |
|---|---|---|
| 数据库 | sqlite3 直接调用（20+ 文件），无 ORM，无抽象层 | 不改 QwenPaw 内部。SQLite 随 PVC 持久化，控制面用独立 PostgreSQL |
| 备份存储 | 本地 ZIP 文件（/app/working.backups/） | 控制面外部同步：定时将 PVC 中的备份 ZIP 转存到 MinIO/OSS |
| 工作区 | 本地文件系统（/app/working/） | PVC 持久化，Pod 重建后自动恢复 |
| 聊天数据 | JSON 文件（chats.json） | 随 PVC 保留 |
| 会话历史 | SQLite 文件（history.db） | 随 PVC 保留 |
核心原则：企业化改造不动 QwenPaw 源码。QwenPaw 实例保持"单机单用户"的原始形态，所有多租户、生命周期、安全审计等企业级能力由外部控制面提供。
二、架构分层
三、QwenPaw 实例内部结构（原生，不改造）
关键事实：
| 数据 | 存储位置 | 格式 | 企业化对策 |
|---|---|---|---|
| 实例注册表 | control.db（SQLite） | SQLite 表 | 控制面维护独立 PostgreSQL 注册表，与 SQLite 互补 |
| 凭据/Vault | control.db（SQLite） | Fernet 加密字段 | 控制面维护独立 Vault（PostgreSQL + Fernet） |
| 会话历史 | history.db（SQLite） | SQLite 表 | 随 PVC 持久化，Pod 重建后自动恢复 |
| 聊天数据 | chats.json | JSON 文件 | 随 PVC 持久化 |
| 备份归档 | working.backups/*.zip | ZIP 文件 | 控制面定时同步到 MinIO |
| 执行产物 | working/workspaces/*/projects/ | 本地文件 | 控制面按需取回到 MinIO |
| 审计日志 | audit.db（SQLite） | SQLite 表 | 控制面采集到独立 PostgreSQL 审计表 |
四、控制面与实例的数据关系
数据主权划分：
| 数据 | 权威源 | 说明 |
|---|---|---|
| 实例注册表（状态/绑定） | 控制面 PostgreSQL | QwenPaw 内部 SQLite 也有注册表，但控制面是权威 |
| 凭据（RT/密钥） | 控制面 Vault（PostgreSQL + Fernet） | QwenPaw 内部 SQLite 也有凭据表，控制面是权威 |
| 会话/记忆 | 实例 SQLite（history.db） | 随 PVC 持久化，控制面不直接读写 |
| 备份文件 | 实例本地 ZIP → 控制面同步到 MinIO | 实例创建备份，控制面负责归档 |
| 审计日志 | 控制面 PostgreSQL | 从实例 SQLite audit.db 定期采集 |
| 任务状态 | 控制面 PostgreSQL | 控制面下发任务时记录 |
五、核心数据流
5.1 员工对话流（主路径）
5.2 备份归档流（控制面外部同步）
同步方式选择：
| 方式 | 说明 | 适用场景 |
|---|---|---|
| K8s exec + kubectl cp | 控制面通过 K8s API 进入 Pod 拷贝文件 | 标准方式，无需额外配置 |
| 共享存储（NFS/CephFS） | PVC 同时挂载到同步器 Pod | 大规模场景，避免 exec 开销 |
| 实例主动上传 | 实例内增加 sidecar 容器，主动推送到 MinIO | 需要修改实例 Pod 配置 |
推荐：MVP 阶段用 kubectl cp，大规模后迁移到共享存储。
5.3 审计采集流
5.4 实例生命周期流
关键点：QwenPaw 实例恢复后，SQLite 数据库和文件系统自动回到暂存前状态——因为数据一直在 PVC 中，Pod 重建只是重新挂载同一块存储。不需要调用 QwenPaw 的 restore API（除非 PVC 也丢了，需要从 MinIO 归档恢复）。
六、两条通道的边界
| 维度 | 用户通道 | 平台通道 |
|---|---|---|
| 流量来源 | 员工（Web/IM/定时任务） | 产品控制面 |
| 入口 | Higress 网关 | K8s 内网直连 |
| 认证 | SSO JWT → ext_authz → RT 注入 | 控制面持有 RT |
| 可达端点 | QwenPaw 原生 API | QwenPaw 原生 API（全部） |
| 实例感知 | 实例只看到 RT 请求 | 实例只看到 RT 请求 |
实例无感：QwenPaw 实例不区分流量来自哪个通道。RT 校验通过 = 合法请求。通道差异完全在网关/控制面层处理。
七、组件间信任关系
八、K8s Namespace 隔离
九、容量规划
| 指标 | 数值 | 说明 |
|---|---|---|
| 单实例资源（基础） | 0.5 CPU / 1GB 内存 | QwenPaw 原生运行时 |
| 单实例资源（含 ACP） | 2 CPU / 4GB 内存 | 含 opencode 等执行体 |
| 单实例存储 | 10Gi data + 1Gi secrets + 5Gi backups | PVC 配额 |
| 单节点承载 | 30 实例 / 8C16G 节点 | 预留 40% 给系统 Pod |
| 控制面资源 | 2 CPU / 4GB 内存 × 3 副本 | FastAPI + 后台任务 |
| PostgreSQL | 4 CPU / 16GB 内存 × 3（主从） | 控制面数据 |
| Redis | 2 CPU / 4GB 内存 × 3（Sentinel） | 缓存 + 限流 |
1000 员工规模估算：
| 资源 | 估算 |
|---|---|
| 实例节点 | 35-40 节点（8C16G） |
| 控制面节点 | 3 节点（4C8G） |
| 数据库节点 | 3 节点（8C32G） |
| 总存储 | ~16Ti SSD（实例 PVC）+ ~5Ti HDD（MinIO 归档） |