feat(spark-shadow): OpenAI Spark 链接型影子账号

背景:gpt-5.3-codex-spark 使用独立于 codex 全局(5h/7d)的配额窗口(数据源是
/wham/usage 响应体的 codex_bengalfox,而非 codex 全局用的 x-codex-* 响应头),且
只能挂在已完成 OAuth 授权的 OpenAI 账号下复用其登录态,不能作为独立账号单独接入。
为此新增“链接型影子账号”(spark shadow account):影子账号本身不持有任何凭据,
通过 parent_account_id 指向母账号,凭据/token/代理透传自母账号并共享母账号的刷新
周期,仅在配额维度(quota_dimension=spark)和用量窗口上与母账号完全独立调度、互不
连坐。

实现:
- 数据模型:migration 154(+154a)给 accounts 表加 parent_account_id /
  quota_dimension 列 + 4 条约束(维度合法 / parent⟺非 global 维度一致 / 禁自指 /
  FK)+ 2 个 CONCURRENTLY 索引(母账号索引 + 每母账号至多一个影子的唯一索引)。
- 创建:POST /api/v1/admin/accounts/:id/shadow(CreateShadow)—— 一母一影(唯一
  索引兜底并发竞态),继承母账号 proxy/分组/并发/优先级(显式传参可覆盖),默认
  model_mapping 恒等映射到 spark(拒绝非 spark 模型),母账号必须是真实的 OpenAI
  OAuth 账号(非影子)。
- 凭据透传:resolveCredentialAccount 把影子解析回母账号,GetAccessToken / 请求头
  / WS 三条路径统一走此函数;影子自身 Credentials 恒为空(仅允许写 model_mapping),
  凭据写入的汇聚点 persistAccountCredentials 对影子早返 no-op,防止误写。
- 调度:parentHealthyForShadow 只看母账号是否仍是 OpenAI OAuth + 凭据/传输是否
  可用(active、token 未过期、未处于 401/刷新失败/传输故障导致的临时不可调度冷却),
  刻意不看母账号的 global 限流窗口——两条 429 道互不连坐。
- 用量:影子的 codex_5h/7d 走 OpenAIQuotaService.QueryUsage(/wham/usage 的
  codex_bengalfox),与母账号走的 WSv2 探测(/responses 头)完全独立的数据源、
  刷新节流与 staleness 判定。
- 备份:ExportData 显式排除影子账号(影子不持凭据,通用凭据型导入强制
  credentials 非空、无法表达父子链接),按 skipped_shadows 计数提示前端。
- 前端:账号操作菜单新增“创建 Spark 影子”入口,影子行展示回填的母账号信息
  (邮箱 / plan / 隐私模式 / 订阅到期 / chatgpt_account_id),批量操作自动跳过
  影子账号。

说明:migrations 目录用完整文件名(而非纯数字前缀)标识迁移,故本次新增的
154_account_spark_shadow.sql / 154a_..._notx.sql 与已有的
154_add_ops_system_logs_api_key_id.sql 按序号共存,与目录里 145/151 已有的
先例一致。

测试:新增约 20 个测试文件,覆盖 handler(CreateShadow 校验 / 母账号信息回填)、
repository(影子 round-trip / 一母一影唯一索引 / 迁移 schema)、service(凭据
透传三路径 / 调度母健康门 / 用量窗口来源与刷新节流 / CRS 母账号不变量 / 各类
早返与 fail-closed 场景)及前端组件(账号列表 / 操作菜单 / 用量重置)。

验证(镜像 CI;golangci-lint 首次全量分析耗时过长被跳过,其余全部实测):
- gofmt -l:干净
- go build ./... / go vet ./...:通过
- go test ./... -count=1:全绿(全部包 ok,含 internal/service、
  internal/repository、migrations)
- go test -tags integration ./internal/repository/... ./internal/service/...
  (真实 Postgres,testcontainers):全绿,含迁移幂等性
  (TestMigrationsRunner_IsIdempotent_AndSchemaIsUpToDate)与影子相关全部用例
- pnpm lint:check / pnpm typecheck / pnpm build(真实 vite 构建)/
  pnpm vitest run:全绿(124 文件 760 用例)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
DaydreamCodingandClaude Sonnet 5 authored and QTom committed 2026-07-01 12:21:45 +08:00
1 parent 5f62625ae6
commit bdf7ead157
95 files changed
+6388 -179

No files matched your search

@@ -132,6 +132,11 @@ func (r *accountRepository) Create(ctx context.Context, account *service.Account
builder.SetSessionWindowStatus(account.SessionWindowStatus)
}
builder.SetQuotaDimension(dbaccount.QuotaDimension(account.QuotaDimensionOrDefault()))
if account.ParentAccountID != nil {
builder.SetParentAccountID(*account.ParentAccountID)
}
created, err := builder.Save(ctx)
if err != nil {
return translatePersistenceError(err, service.ErrAccountNotFound, nil)
@@ -265,7 +270,11 @@ func (r *accountRepository) GetByCRSAccountID(ctx context.Context, crsAccountID
}
// 使用 sqljson.ValueEQ 生成 JSON 路径过滤,避免手写 SQL 片段导致语法兼容问题。
// 排除 spark 影子账号(parent_account_id 非空):影子不持凭据,绝不能被 CRS 当作普通账号
// 更新而覆盖 type/credentials/proxy。即便影子 Extra 被误写入 crs_account_id 也不会命中
// (外审第7轮 P1)。
m, err := r.client.Account.Query().
Where(dbaccount.ParentAccountIDIsNil()).
Where(func(s *entsql.Selector) {
s.Where(sqljson.ValueEQ(dbaccount.FieldExtra, crsAccountID, sqljson.Path("crs_account_id")))
}).
@@ -288,10 +297,13 @@ func (r *accountRepository) GetByCRSAccountID(ctx context.Context, crsAccountID
}
func (r *accountRepository) ListCRSAccountIDs(ctx context.Context) (map[string]int64, error) {
// parent_account_id IS NULL 排除 spark 影子账号:影子不是 CRS 账号,绝不能进 CRS 同步映射
// (否则会被当普通账号更新而覆盖 type/credentials/proxy)(外审第7轮 P1)。
rows, err := r.sql.QueryContext(ctx, `
SELECT id, extra->>'crs_account_id'
FROM accounts
WHERE deleted_at IS NULL
AND parent_account_id IS NULL
AND extra->>'crs_account_id' IS NOT NULL
AND extra->>'crs_account_id' != ''
`)
@@ -396,6 +408,9 @@ func (r *accountRepository) Update(ctx context.Context, account *service.Account
builder.ClearNotes()
}
builder.SetQuotaDimension(dbaccount.QuotaDimension(account.QuotaDimensionOrDefault()))
builder.SetNillableParentAccountID(account.ParentAccountID)
updated, err := builder.Save(ctx)
if err != nil {
return translatePersistenceError(err, service.ErrAccountNotFound, nil)
@@ -1930,6 +1945,8 @@ func accountEntityToService(m *dbent.Account) *service.Account {
SessionWindowStart: m.SessionWindowStart,
SessionWindowEnd: m.SessionWindowEnd,
SessionWindowStatus: derefString(m.SessionWindowStatus),
ParentAccountID: m.ParentAccountID,
QuotaDimension: string(m.QuotaDimension),
}
}
@@ -2222,3 +2239,21 @@ func (r *accountRepository) RevertProxyFallback(ctx context.Context, accountID i
}
return nil
}
// ListShadowsByParent 返回指定父账号的影子账号;当前实现仅查 quota_dimension='spark'(唯一预设)。
// 同时过滤 parent_account_id 和 quota_dimension='spark',防止未来其它 linked 维度被误伤。
// ⚠️ 新增影子维度时:须更新此函数(或新增维度专用列举),并检查所有调用点(级联删除/一母一影校验/type 守卫),否则会静默漏掉新维度。
// 软删除行由 SoftDeleteMixin 拦截器自动排除,无需手写 deleted_at IS NULL。
func (r *accountRepository) ListShadowsByParent(ctx context.Context, parentID int64) ([]*service.Account, error) {
rows, err := r.client.Account.Query().
Where(dbaccount.ParentAccountIDEQ(parentID), dbaccount.QuotaDimensionEQ(dbaccount.QuotaDimensionSpark)).
All(ctx)
if err != nil {
return nil, err
}
out := make([]*service.Account, 0, len(rows))
for _, m := range rows {
out = append(out, accountEntityToService(m))
}
return out, nil
}
@@ -1031,6 +1031,45 @@ func (s *AccountRepoSuite) TestGetByCRSAccountID_EmptyString() {
s.Require().Nil(got)
}
// TestGetByCRSAccountID_ExcludesSparkShadow 验证外审第7轮 P1:即便 spark 影子的 Extra 被误写入
// crs_account_id,CRS 查询也绝不能命中影子(否则会被当普通账号更新而覆盖 type/credentials/proxy)。
func (s *AccountRepoSuite) TestGetByCRSAccountID_ExcludesSparkShadow() {
crsID := "crs-shadow-only-99"
parent := mustCreateAccount(s.T(), s.client, &service.Account{
Name: "crs-mother", Platform: service.PlatformOpenAI, Type: service.AccountTypeOAuth,
})
mustCreateAccount(s.T(), s.client, &service.Account{
Name: "crs-shadow", Platform: service.PlatformOpenAI, Type: service.AccountTypeOAuth,
ParentAccountID: &parent.ID,
QuotaDimension: service.QuotaDimensionSpark,
Extra: map[string]any{"crs_account_id": crsID},
})
got, err := s.repo.GetByCRSAccountID(s.ctx, crsID)
s.Require().NoError(err)
s.Require().Nil(got, "spark 影子即便带 crs_account_id 也不应被 CRS 命中")
}
// TestListCRSAccountIDs_ExcludesSparkShadow 验证外审第7轮 P1:影子的 crs_account_id 不应进入
// CRS 同步映射(否则后续 CRS 同步会把影子当普通账号更新)。
func (s *AccountRepoSuite) TestListCRSAccountIDs_ExcludesSparkShadow() {
parent := mustCreateAccount(s.T(), s.client, &service.Account{
Name: "crs-list-mother", Platform: service.PlatformOpenAI, Type: service.AccountTypeOAuth,
})
shadowCRSID := "crs-list-shadow-77"
mustCreateAccount(s.T(), s.client, &service.Account{
Name: "crs-list-shadow", Platform: service.PlatformOpenAI, Type: service.AccountTypeOAuth,
ParentAccountID: &parent.ID,
QuotaDimension: service.QuotaDimensionSpark,
Extra: map[string]any{"crs_account_id": shadowCRSID},
})
ids, err := s.repo.ListCRSAccountIDs(s.ctx)
s.Require().NoError(err)
_, ok := ids[shadowCRSID]
s.Require().False(ok, "影子的 crs_account_id 不应进入 CRS 映射")
}
// --- BulkUpdate ---
func (s *AccountRepoSuite) TestBulkUpdate() {
@@ -0,0 +1,136 @@
//go:build integration
package repository
import (
"context"
"testing"
"github.com/Wei-Shaw/sub2api/internal/service"
)
func TestAccountRepoSparkShadowRoundTrip(t *testing.T) {
ctx := context.Background()
tx := testEntTx(t)
repo := newAccountRepositoryWithSQL(tx.Client(), tx, nil)
parent := &service.Account{
Name: "parent",
Platform: service.PlatformOpenAI,
Type: service.AccountTypeOAuth,
Status: service.StatusActive,
}
if err := repo.Create(ctx, parent); err != nil {
t.Fatalf("create parent: %v", err)
}
pid := parent.ID
shadow := &service.Account{
Name: "shadow",
Platform: service.PlatformOpenAI,
Type: service.AccountTypeOAuth,
Status: service.StatusActive,
ParentAccountID: &pid,
QuotaDimension: service.QuotaDimensionSpark,
}
if err := repo.Create(ctx, shadow); err != nil {
t.Fatalf("create shadow: %v", err)
}
got, err := repo.GetByID(ctx, shadow.ID)
if err != nil {
t.Fatalf("get: %v", err)
}
if got.ParentAccountID == nil || *got.ParentAccountID != pid {
t.Fatalf("ParentAccountID round-trip: %v", got.ParentAccountID)
}
if got.QuotaDimension != service.QuotaDimensionSpark {
t.Fatalf("QuotaDimension: %q", got.QuotaDimension)
}
}
func TestListShadowsByParent(t *testing.T) {
// Schema enforces at most one spark shadow per parent (uq_accounts_spark_shadow_per_parent).
// Test strategy: create 2 parents each with 1 spark shadow + 1 unrelated account;
// assert ListShadowsByParent(parent1.ID) returns exactly 1 (filtering by both
// parent_account_id and quota_dimension='spark', excluding parent2's shadow and unrelated).
ctx := context.Background()
tx := testEntTx(t)
repo := newAccountRepositoryWithSQL(tx.Client(), tx, nil)
// Create parent1 and its spark shadow
parent1 := &service.Account{
Name: "list-parent1",
Platform: service.PlatformOpenAI,
Type: service.AccountTypeOAuth,
Status: service.StatusActive,
}
if err := repo.Create(ctx, parent1); err != nil {
t.Fatalf("create parent1: %v", err)
}
pid1 := parent1.ID
shadow1 := &service.Account{
Name: "shadow1",
Platform: service.PlatformOpenAI,
Type: service.AccountTypeOAuth,
Status: service.StatusActive,
ParentAccountID: &pid1,
QuotaDimension: service.QuotaDimensionSpark,
}
if err := repo.Create(ctx, shadow1); err != nil {
t.Fatalf("create shadow1: %v", err)
}
// Create parent2 and its spark shadow (must NOT appear in parent1's list)
parent2 := &service.Account{
Name: "list-parent2",
Platform: service.PlatformOpenAI,
Type: service.AccountTypeOAuth,
Status: service.StatusActive,
}
if err := repo.Create(ctx, parent2); err != nil {
t.Fatalf("create parent2: %v", err)
}
pid2 := parent2.ID
shadow2 := &service.Account{
Name: "shadow2",
Platform: service.PlatformOpenAI,
Type: service.AccountTypeOAuth,
Status: service.StatusActive,
ParentAccountID: &pid2,
QuotaDimension: service.QuotaDimensionSpark,
}
if err := repo.Create(ctx, shadow2); err != nil {
t.Fatalf("create shadow2: %v", err)
}
// Create 1 unrelated normal account (no parent, global dimension)
unrelated := &service.Account{
Name: "unrelated",
Platform: service.PlatformOpenAI,
Type: service.AccountTypeOAuth,
Status: service.StatusActive,
}
if err := repo.Create(ctx, unrelated); err != nil {
t.Fatalf("create unrelated: %v", err)
}
// Assert ListShadowsByParent returns exactly 1 for parent1
got, err := repo.ListShadowsByParent(ctx, pid1)
if err != nil {
t.Fatalf("ListShadowsByParent: %v", err)
}
if len(got) != 1 {
t.Fatalf("expected 1 spark shadow for parent1, got %d", len(got))
}
acc := got[0]
if acc.ParentAccountID == nil || *acc.ParentAccountID != pid1 {
t.Errorf("unexpected ParentAccountID: %v", acc.ParentAccountID)
}
if acc.QuotaDimension != service.QuotaDimensionSpark {
t.Errorf("unexpected QuotaDimension: %q", acc.QuotaDimension)
}
if acc.ID != shadow1.ID {
t.Errorf("expected shadow1.ID=%d, got %d", shadow1.ID, acc.ID)
}
}
@@ -8,6 +8,7 @@ import (
"time"
dbent "github.com/Wei-Shaw/sub2api/ent"
dbaccount "github.com/Wei-Shaw/sub2api/ent/account"
"github.com/Wei-Shaw/sub2api/internal/service"
"github.com/stretchr/testify/require"
)
@@ -233,6 +234,12 @@ func mustCreateAccount(t *testing.T, client *dbent.Client, a *service.Account) *
if !a.UpdatedAt.IsZero() {
create.SetUpdatedAt(a.UpdatedAt)
}
if a.ParentAccountID != nil {
create.SetParentAccountID(*a.ParentAccountID)
}
if a.QuotaDimension != "" {
create.SetQuotaDimension(dbaccount.QuotaDimension(a.QuotaDimension))
}
created, err := create.Save(ctx)
require.NoError(t, err, "create account")
@@ -449,6 +449,8 @@ func buildSchedulerMetadataAccount(account service.Account) service.Account {
SessionWindowStart: account.SessionWindowStart,
SessionWindowEnd: account.SessionWindowEnd,
SessionWindowStatus: account.SessionWindowStatus,
ParentAccountID: account.ParentAccountID,
QuotaDimension: account.QuotaDimension,
AccountGroups: filterSchedulerAccountGroups(account.AccountGroups),
GroupIDs: filterSchedulerGroupIDs(account.GroupIDs, account.AccountGroups),
Credentials: filterSchedulerCredentials(account.Credentials),
@@ -516,7 +518,7 @@ func filterSchedulerCredentials(credentials map[string]any) map[string]any {
if len(credentials) == 0 {
return nil
}
keys := []string{"model_mapping", "api_key", "project_id", "oauth_type"}
keys := []string{"model_mapping", "compact_model_mapping", "api_key", "project_id", "oauth_type"}
filtered := make(map[string]any)
for _, key := range keys {
if value, ok := credentials[key]; ok && value != nil {
@@ -134,3 +134,32 @@ func TestBuildSchedulerMetadataAccount_KeepsModelRateLimits(t *testing.T) {
require.Contains(t, limits, "antigravity:gemini")
require.Nil(t, got.Extra["unused_large_field"])
}
func TestBuildSchedulerMetadataAccount_KeepsSparkShadowRoutingIdentity(t *testing.T) {
parentID := int64(100)
account := service.Account{
ID: 200,
Platform: service.PlatformOpenAI,
Type: service.AccountTypeOAuth,
ParentAccountID: &parentID,
QuotaDimension: service.QuotaDimensionSpark,
Credentials: map[string]any{
"model_mapping": map[string]any{
"gpt-5.3-codex-spark": "gpt-5.3-codex-spark",
},
"compact_model_mapping": map[string]any{
"gpt-5.4": "gpt-5.4-openai-compact",
},
"access_token": "drop-me",
},
}
got := buildSchedulerMetadataAccount(account)
require.NotNil(t, got.ParentAccountID)
require.Equal(t, parentID, *got.ParentAccountID)
require.Equal(t, service.QuotaDimensionSpark, got.QuotaDimension)
require.Equal(t, map[string]any{"gpt-5.3-codex-spark": "gpt-5.3-codex-spark"}, got.Credentials["model_mapping"])
require.Equal(t, map[string]any{"gpt-5.4": "gpt-5.4-openai-compact"}, got.Credentials["compact_model_mapping"])
require.Nil(t, got.Credentials["access_token"])
}