# 插件闭环实施规划（2026-05-28）

日期：2026-05-28

## 目标

把插件后续演进从“概念设计”推进到“可执行实施”，明确：

- 当前数据库是什么
- 后续继续沿用什么存储结构
- 每个功能域怎样形成闭环
- 智能路由的日志必须落在哪里
- 哪些运行态适合放 Redis，哪些必须写插件数据库

这份文档是对以下文档的进一步细化：

- [PLUGIN_REQUIREMENTS_OVERVIEW_2026-05-28.md](/home/long/project/sub2api-cn-relay-manager/docs/PLUGIN_REQUIREMENTS_OVERVIEW_2026-05-28.md:1)
- [PLUGIN_ROUTE_STICKY_DESIGN.md](/home/long/project/sub2api-cn-relay-manager/docs/PLUGIN_ROUTE_STICKY_DESIGN.md:1)

## 一、当前数据库结论

### 当前插件用的是什么数据库

当前插件主数据库是 **SQLite**。

直接证据：

- 配置项：
  - [internal/config/config.go](/home/long/project/sub2api-cn-relay-manager/internal/config/config.go:12)
  - 环境变量 `SUB2API_CRM_SQLITE_DSN`
- 默认配置：
  - [.env.example](/home/long/project/sub2api-cn-relay-manager/.env.example:2)
  - `SUB2API_CRM_SQLITE_DSN=file:/data/sub2api-cn-relay-manager.db?_foreign_keys=on&_busy_timeout=5000`
- 打开数据库与迁移入口：
  - [internal/store/sqlite/db.go](/home/long/project/sub2api-cn-relay-manager/internal/store/sqlite/db.go:35)

### 当前 SQLite 里已经在存什么

当前 SQLite 已经承载：

- host 注册信息
- pack/provider 元数据
- provider drafts
- import batches / import items
- managed resources
- probe results
- access closures
- reconcile runs

相关表来自：

- [0001_init.sql](/home/long/project/sub2api-cn-relay-manager/internal/store/migrations/0001_init.sql:1)
- [0002_operational_runtime.sql](/home/long/project/sub2api-cn-relay-manager/internal/store/migrations/0002_operational_runtime.sql:1)
- 后续 migrations `0003` 到 `0009*`

### 当前数据库特性边界

SQLite 目前是合理选择，原因是：

- 项目当前是单实例控制面为主
- 状态库规模仍然偏中小
- 现有 repo / migration / integration test 全围绕 SQLite 建设

但要明确一个实现事实：

- [internal/store/sqlite/db.go](/home/long/project/sub2api-cn-relay-manager/internal/store/sqlite/db.go:42)
  已经把连接池限制为单 writer 友好模式：
  - `SetMaxOpenConns(1)`
  - `SetMaxIdleConns(1)`

这意味着：

- SQLite 很适合当前控制面状态持久化
- 但智能路由日志不能无限制高频同步写库，否则会放大写锁争用

所以后续方案应当是：

- **SQLite 继续作为插件主状态库**
- **Redis 作为智能路由运行态缓存**
- **智能路由日志按结构化事件写回 SQLite**

---

## 二、后续存储策略

## 总体原则

### 1. SQLite：保存“真相状态”

放 SQLite 的必须是：

- 配置真相
- 可审计真相
- 需要查询/回放/后台管理的结构化记录

### 2. Redis：保存“短期运行态”

放 Redis 的应该是：

- sticky route
- route cooldown
- 短期失败计数
- 热路由选择缓存

### 3. 智能路由日志：必须最终落 SQLite

用户已经明确要求：

- **智能路由日志要存在插件中**

所以要求不能只停留在 Redis，也不能只打 stdout。

正确做法是：

- 请求热路径上先写结构化内存事件/异步队列
- 由后台 writer 批量落 SQLite
- 关键失败场景允许同步兜底落一条简版事件

---

## 三、目标架构

建议后续插件内部形成三层存储：

```text
SQLite
  - 配置真相
  - 业务真相
  - 路由日志

Redis
  - sticky route
  - cooldown
  - short-lived routing cache

In-memory
  - 单请求上下文
  - 异步日志缓冲队列
```

## SQLite 负责

- `logical_groups`
- `logical_group_routes`
- `logical_group_models`
- `route_shadow_groups`
- `route_decision_logs`
- `route_failover_events`
- `route_sticky_audit`
- `provider account inventory` 扩展表

## Redis 负责

- 当前 route sticky
- route 失败计数
- route cooldown
- 可选的 user-model route cache

---

## 四、功能闭环规划

下面按功能域写成闭环，不再只列功能点。

## 4.1 增加模型闭环

### 目标闭环

运营在管理页完成一次“新增模型”后，应形成：

1. provider manifest 被创建或更新
2. 模型被纳入某个 `logical_group`
3. 至少一条 route 被配置好
4. route 对应的 shadow group 被定义好
5. 后续可直接导入供应商帐号

### 当前已有能力

- provider drafts
- publish to pack repo
- 同模型冲突校验

### 待补技术细节

新增模型不应只产生 provider 文件，还应额外落地以下数据：

#### 新表：`logical_groups`

```sql
CREATE TABLE logical_groups (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    logical_group_id TEXT NOT NULL UNIQUE,
    display_name TEXT NOT NULL,
    status TEXT NOT NULL,
    description TEXT NOT NULL DEFAULT '',
    route_policy TEXT NOT NULL DEFAULT 'priority',
    sticky_mode TEXT NOT NULL DEFAULT 'conversation_preferred',
    conversation_ttl_seconds INTEGER NOT NULL DEFAULT 7200,
    user_model_ttl_seconds INTEGER NOT NULL DEFAULT 1800,
    failover_threshold INTEGER NOT NULL DEFAULT 2,
    cooldown_seconds INTEGER NOT NULL DEFAULT 600,
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```

#### 新表：`logical_group_models`

```sql
CREATE TABLE logical_group_models (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    logical_group_id TEXT NOT NULL,
    public_model TEXT NOT NULL,
    status TEXT NOT NULL DEFAULT 'active',
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (logical_group_id, public_model)
);
```

### 闭环接口

建议新增：

- `POST /api/logical-groups`
- `POST /api/logical-groups/{group_id}/models`
- `GET /api/logical-groups`
- `GET /api/logical-groups/{group_id}`

### 验收标准

- 新增模型后，不只是 pack 文件变了
- 插件库里也能看到：
  - 该模型属于哪个 logical group
  - 哪些 route 支持它

---

## 4.2 维护逻辑分组闭环

### 目标闭环

运营维护一个逻辑分组时，应能完成：

1. 新建逻辑分组
2. 绑定公开模型集合
3. 绑定多条 route
4. 每条 route 绑定 shadow group
5. 管理页可查看该逻辑分组当前真实承载结构

### 新表：`logical_group_routes`

```sql
CREATE TABLE logical_group_routes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    route_id TEXT NOT NULL UNIQUE,
    logical_group_id TEXT NOT NULL,
    name TEXT NOT NULL,
    status TEXT NOT NULL,
    priority INTEGER NOT NULL,
    weight INTEGER NOT NULL DEFAULT 100,
    shadow_group_id TEXT NOT NULL,
    shadow_host_id TEXT NOT NULL,
    upstream_base_url_hint TEXT NOT NULL DEFAULT '',
    cooldown_until TEXT NOT NULL DEFAULT '',
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```

### 新表：`logical_group_route_models`

```sql
CREATE TABLE logical_group_route_models (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    route_id TEXT NOT NULL,
    public_model TEXT NOT NULL,
    shadow_model TEXT NOT NULL DEFAULT '',
    status TEXT NOT NULL DEFAULT 'active',
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (route_id, public_model)
);
```

### 闭环接口

- `POST /api/logical-groups/{group_id}/routes`
- `PUT /api/logical-groups/{group_id}/routes/{route_id}`
- `GET /api/logical-groups/{group_id}/routes`
- `POST /api/logical-groups/{group_id}/routes/{route_id}/models`

### 验收标准

- 打开某个 logical group 时，可以完整看到：
  - 公开模型
  - route 列表
  - 每条 route 对应的 shadow group
  - route 当前状态

---

## 4.3 智能路由闭环

这是新增需求后的核心实现。

### 目标闭环

一次用户请求进入插件后，应形成完整闭环：

1. 识别 logical group
2. 识别 public model
3. 计算 sticky key
4. 选择 route
5. 记录 route decision log
6. 转发到对应 shadow group
7. 收到结果后更新 sticky / fail count / cooldown
8. 记录最终路由结果日志

### 运行态存储

#### Redis key：sticky

```text
lg:{logical_group_id}:m:{public_model}:conv:{conversation_id}
lg:{logical_group_id}:m:{public_model}:sess:{session_id}
lg:{logical_group_id}:m:{public_model}:user:{user_id}
```

#### Redis key：route failure

```text
routefail:{route_id}
```

#### Redis key：route cooldown

```text
routecool:{route_id}
```

### 路由日志必须写入 SQLite

#### 新表：`route_decision_logs`

```sql
CREATE TABLE route_decision_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    request_id TEXT NOT NULL,
    logical_group_id TEXT NOT NULL,
    public_model TEXT NOT NULL,
    user_key TEXT NOT NULL DEFAULT '',
    conversation_key TEXT NOT NULL DEFAULT '',
    sticky_key TEXT NOT NULL DEFAULT '',
    sticky_key_type TEXT NOT NULL DEFAULT '',
    sticky_hit INTEGER NOT NULL DEFAULT 0,
    selected_route_id TEXT NOT NULL,
    selected_shadow_group_id TEXT NOT NULL,
    fallback_used INTEGER NOT NULL DEFAULT 0,
    error_class TEXT NOT NULL DEFAULT '',
    upstream_status INTEGER NOT NULL DEFAULT 0,
    latency_ms INTEGER NOT NULL DEFAULT 0,
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```

#### 新表：`route_failover_events`

```sql
CREATE TABLE route_failover_events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    request_id TEXT NOT NULL,
    logical_group_id TEXT NOT NULL,
    public_model TEXT NOT NULL,
    from_route_id TEXT NOT NULL,
    to_route_id TEXT NOT NULL,
    reason TEXT NOT NULL,
    failure_count INTEGER NOT NULL DEFAULT 0,
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```

#### 新表：`route_sticky_audit`

```sql
CREATE TABLE route_sticky_audit (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    sticky_key TEXT NOT NULL,
    sticky_key_type TEXT NOT NULL,
    logical_group_id TEXT NOT NULL,
    public_model TEXT NOT NULL,
    route_id TEXT NOT NULL,
    action TEXT NOT NULL,
    expires_at TEXT NOT NULL DEFAULT '',
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```

### 为什么日志必须进 SQLite

因为后续必须支持：

- 查询“这次为什么走了 codex2api 而不是 asxs”
- 查询某个 logical group 最近 24h 的 route 命中情况
- 查询 fallback 是否频繁发生
- 查询 sticky 命中率

这些都必须靠结构化插件日志完成，宿主侧日志无法替代。

### 日志写入策略

SQLite 是单 writer，不能每个请求把大量日志同步直写。

建议：

1. 路由热路径先产出 `RouteDecisionEvent`
2. 写入内存 channel/buffer
3. 后台 writer 每 100ms 或每 100 条批量写 SQLite
4. 如果 writer 满了：
   - 保底同步写一条精简版失败记录
   - 或至少 stderr 告警

### 路由服务接口建议

建议新增：

- `RouteResolver`
- `StickyStore`
- `RouteDecisionLogger`

```go
type RouteResolver interface {
    Resolve(ctx context.Context, req RouteRequest) (RouteDecision, error)
}

type StickyStore interface {
    Get(ctx context.Context, key string) (StickyBinding, bool, error)
    Set(ctx context.Context, key string, binding StickyBinding, ttl time.Duration) error
    Delete(ctx context.Context, key string) error
}

type RouteDecisionLogger interface {
    Append(ctx context.Context, event RouteDecisionEvent) error
}
```

### 验收标准

- 同一会话优先命中同一路 route
- retryable 失败时能 fallback
- fallback 有日志
- sticky 命中有日志
- 所有路由决策都能在插件库里查询到

---

## 4.4 供应商帐号导入与停启用闭环

### 目标闭环

管理员对供应商帐号做一次操作后，应形成：

1. 预检
2. 导入或复用
3. 绑定到 provider / route / shadow group
4. 记录帐号库存状态
5. 后续可以启用/停用/下线

### 当前问题

当前更像“导入任务系统”，还不是“帐号资产系统”。

### 建议新增表：`provider_accounts`

```sql
CREATE TABLE provider_accounts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    host_id TEXT NOT NULL,
    provider_id TEXT NOT NULL,
    route_id TEXT NOT NULL DEFAULT '',
    shadow_group_id TEXT NOT NULL DEFAULT '',
    host_account_id TEXT NOT NULL,
    key_fingerprint TEXT NOT NULL,
    account_name TEXT NOT NULL DEFAULT '',
    account_status TEXT NOT NULL,
    last_probe_status TEXT NOT NULL DEFAULT '',
    last_probe_at TEXT NOT NULL DEFAULT '',
    disabled_reason TEXT NOT NULL DEFAULT '',
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (host_id, host_account_id)
);
```

### 闭环接口

- `GET /api/provider-accounts`
- `POST /api/provider-accounts/{id}/disable`
- `POST /api/provider-accounts/{id}/enable`
- `POST /api/provider-accounts/{id}/retire`

### 验收标准

- 能看到帐号库存
- 能看到帐号属于哪个 route / shadow group
- 能手动停启用
- 状态变化有日志可追

---

## 4.5 普通用户前端闭环

### 目标闭环

普通用户看到的是逻辑分组，而不是宿主真实 group。

一次用户进入 portal 后，应形成：

1. 看到逻辑分组列表
2. 看到该分组可用模型
3. 申请/使用的 key 对应逻辑分组
4. 后端实际路由到某个 shadow group
5. 用户无需感知宿主真实 group 名称

### 当前现实

当前 `/portal/` 已存在，但仍偏宿主分组视角。

### 待做接口

建议新增面向 portal 的聚合 API：

- `GET /api/portal/logical-groups`
- `GET /api/portal/logical-groups/{group_id}`
- `GET /api/portal/logical-groups/{group_id}/models`

### 验收标准

- 用户前端不再直接暴露 `gpt-shared__asxs` 这种 shadow group
- 只看到 `GPT Shared`
- 用户使用体验上是一个产品，不是多个宿主组装件

---

## 五、实施顺序

为了保证每步都闭环，建议按下面顺序推进。

## Phase 1：数据模型闭环

目标：

- 先让插件库知道什么是 `logical_group / route / shadow_group`

范围：

- SQLite migrations
- sqlite repos
- 基础 CRUD API

输出：

- 逻辑分组配置可持久化
- route 配置可持久化
- 每个闭环功能完成后，必须提交、推送、部署到 `remote43`，并完成服务器验证后再更新执行板

## Phase 2：智能路由最小闭环

目标：

- 让请求真正能按 logical group -> route -> shadow group 跑起来

范围：

- Redis sticky
- route resolver
- route forwarding
- SQLite route logs

输出：

- `asxs + codex2api` 单 logical group 跑通

## Phase 3：帐号资产闭环

目标：

- 把“导入任务”升级成“帐号资产管理”

范围：

- provider_accounts 视图
- enable/disable/retire
- route / shadow group 归属展示

输出：

- 能运维帐号池

## Phase 4：普通用户产品闭环

目标：

- 用户前端彻底切换到逻辑分组视角

范围：

- portal 聚合 API
- portal 前端改造

输出：

- 用户只看到逻辑分组

---

## 六、技术决策总结

### 当前数据库

- **SQLite**

### 后续主状态库

- **继续使用 SQLite**

### 智能路由运行态

- **Redis**

### 智能路由日志

- **必须最终落 SQLite**

### 为什么不是一开始就换 PostgreSQL

当前不建议立刻切 PostgreSQL，原因是：

- 现有 repo、migration、integration test 都围绕 SQLite
- 当前主要瓶颈不是查询能力，而是产品结构未闭环
- 先把闭环跑通比先换库更重要

但要保留一个现实判断：

- 如果后续 route 日志量显著升高
- 或多实例控制面出现
- 或需要复杂聚合分析

那时再评估：

- SQLite -> PostgreSQL
- Redis 保持不变

## 一句话结论

当前插件数据库是 **SQLite**；后续仍建议以 **SQLite 作为主状态库**，并以 **Redis 承载智能路由运行态缓存**。  
同时，**智能路由日志必须结构化写回插件 SQLite**，不能只停留在 Redis 或 stdout。  
后续真正的闭环实施顺序应当是：

1. 先补 `logical_group / route / shadow_group` 数据模型  
2. 再做前置智能路由最小闭环  
3. 再做供应商帐号资产管理  
4. 最后把普通用户前端切到逻辑分组视角