Skip to content

feat(gemini): 支持显式上下文缓存,并完善 Vertex 与第三方 API Key 账号 - #8006

Merged
Wei-Shaw merged 15 commits into
Wei-Shaw:mainfrom
feeeei:feat/gemini-explicit-cache
Oct 13, 2026
Merged

Wei-Shaw merged 15 commits into
Wei-Shaw:mainfrom
feeeei:feat/gemini-explicit-cache

Conversation

@feeeei

@feeeei feeeei commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

概述

为 Gemini 平台新增显式上下文缓存(/v1beta/cachedContents),并完善 Vertex 与第三方 API Key 账号的相关支持。改动按职责拆成 9 个提交,可以逐个审阅。

改动

显式上下文缓存

  • 新增 /v1beta/cachedContents 的创建、列表、查询、续期与删除接口,支持官方 AI Studio API Key、Vertex Service Account,以及开启「上游支持显式缓存」的自定义地址 API Key 账号
  • 缓存 ID 由网关分配,并记录创建它的 API Key 与持有账号;引用缓存的请求固定发往持有账号
  • 计费:缓存 token 按输入价收取,存储费按有效期预收,续期按增量收取;扣费前校验余额与额度;存储费同时计入账号成本
  • 引用不存在或已过期的缓存时统一返回 403,不再因此停用账号或换号

Vertex

  • Google 已将 Vertex AI 更名为 Agent Platform,界面显示名同步改为 Agent Platform (Vertex)
  • Gemini 平台的 Vertex 账号支持 API Key 认证
  • Vertex Service Account 账号支持同步上游模型列表

第三方 API Key

  • 非官方 Base URL 的 Gemini API Key 账号以及 Vertex 账号,不再套用 AI Studio 的等级与模拟配额;第三方上游的 429 不再按每日配额冷却到太平洋时间午夜
  • 适配 AI Studio 新的 AQ. 格式 Key:更新表单提示,日志与渠道监控脱敏覆盖新格式

其他

  • Gemini 原生路由中由网关产生的错误,在运维监控里按错误类型归类,不再一律记为平台错误
  • 同步上游模型失败时显示后端返回的具体原因

部署说明

  • 新增迁移 243_gemini_cached_contents.sql
  • 新增配置 gateway.gemini_cached_content_max_ttl_seconds(缓存有效期上限,默认 86400 秒)
  • 存储单价读取定价覆盖文件的 cache_storage_cost_per_token_per_hour 字段,未配置存储价的模型不能创建缓存

测试

  • 后端与前端补充了单元测试,每个提交单独通过 go test -tags=unit ./...、vue-tsc 与 vitest run
  • 使用真实 AI Studio 账号端到端验证缓存的创建、引用、续期、删除与计费;Vertex 账号验证了创建、引用与删除

效果图

image image

feeeei added 10 commits October 10, 2026 23:36
上游对不存在、已过期、已删除或不属于当前项目的 cachedContent 一律返回
403 "CachedContent not found (or permission denied)"。原生转发路径在错误
策略之前识别该响应,原样返回客户端,不标记账号错误、不临时停调度、
不重试、不换号;其余 403 处理不变。
新增 /v1beta/cachedContents 的创建、列表、查询、更新有效期与删除接口。
参与账号:官方地址的 AI Studio API Key 账号、Vertex service account 账号,
以及开启"上游支持显式缓存"的自定义地址 API Key 账号。

- 网关自发缓存 ID,绑定上游资源名、持有账号与创建它的 API Key
  (迁移 243 gemini_cached_contents);list/get 只读本地记录
- 引用缓存的 generateContent / streamGenerateContent / countTokens
  改写为上游资源名,只发往持有缓存的账号,不参与会话粘性、不换号;
  拒绝重复键与 snake_case 写法;在持有账号上重试耗尽后,
  上游 429 / 5xx 原样透传,401 / 403 映射为 502
- 计费:创建时一次性收取缓存 token 输入费与整个有效期的存储费;
  延长按库中实际推进的时长收费,纯存储费不算一次请求;缩短与删除不退费
- 存储单价随计费模型取价,来自定价覆盖文件字段
  cache_storage_cost_per_token_per_hour,未配置的模型拒绝创建;
  存储费同时计入账号统计成本,渠道按 token 重算成本时叠加且不重复计入
- 扣费前校验:创建在上游建成后按确定金额校验余额 / 订阅额度 /
  API Key 额度并登记不封顶的在途预留,不足时删除上游缓存、只收输入费;
  延长在调用上游前按增量时长校验
- 有效期上限 gateway.gemini_cached_content_max_ttl_seconds,默认 86400,
  有效期向上取整到秒;创建请求保留数字原文、兼容 snake_case 元数据字段
- 上游调用与落库同客户端连接脱钩;2xx 不可用响应不换号并删除已建缓存
- 缓存不存在:AI Studio 的 403、Vertex 生成请求的 400 与缓存资源接口的
  404 统一识别;原生转发(含流式)不重试、不换号、不改账号状态,
  向客户端返回标准 403,不暴露上游缓存资源 ID,上游原始错误登记到 ops;
  PATCH 遇上游 404 移除本地记录并返回 403,DELETE 视为成功
- 自建网关上游:账号开关 explicit_cache_upstream,缓存接口发往账号自身
  base_url;可选 explicit_cache_upstream_max_ttl_seconds 对齐上游 TTL 上限,
  显式 TTL 超限时创建跳过该账号(全部超限返回 400),未显式时按上限创建,
  PATCH 取本站与账号上限的较小值;绑定缓存的请求在网关账号上收到
  429 / 5xx 时不重试、不限流该账号;前端创建 / 编辑账号弹窗新增开关与上限输入框
- 用量与 ops 端点统计:带缓存 ID 的路径归一化为 /v1beta/cachedContents,
  缓存操作的上游端点记为 /v1beta/cachedContents
Google 格式错误体没有 type 字段,ops 一律记为 api_error,客户端参数错误、
引用不存在的缓存等都被归为平台内部错误。

- googleError 写出时按状态码向 ops 登记错误类型:400/413 invalid_request_error、
  401 authentication_error、403 permission_error、404 not_found_error,
  429 与 5xx 不登记
- 计费、并发与风控拦截沿用 Claude / OpenAI 格式错误的类型与错误码,归类口径一致
- 存储价未配置、显式缓存未启用改用 googlePlatformError,仍按平台错误统计;
  错误透传规则改写的上游错误不登记本地类型
- 上游返回的缓存不存在标记为请求级失败:按客户端请求错误分类,
  上游原始错误保留为明细但不参与上游归因
Google 已将 Vertex AI 更名为 Gemini Enterprise Agent Platform。
账号类型按钮、平台徽章、Vertex 相关提示、配额文档链接与批量生图报错文案
统一显示为 Agent Platform (Vertex);创建账号弹窗的 Vertex 按钮改用 i18n 文案。
- Gemini 平台的 Vertex 账号新增 API Key 认证(credentials.auth_mode=apikey),
  不填 Project ID 走全局端点,填写后走项目级端点,Key 通过 x-goog-api-key 传递;
  Anthropic 平台的 Vertex 账号仍只支持 Service Account JSON
- 转发(Claude 兼容 / 原生 / Chat Completions)与测试连接统一走
  buildVertexGeminiAccountURL / setVertexGeminiAuth
- API Key 账号不参与显式缓存(Vertex 缓存接口不接受 API Key)与批量生图
- 创建弹窗新增认证方式选择;编辑弹窗支持轮换 Key 与修改 Project ID,
  Key 留空表示保留
- 按 base_url 判定上游:非官方地址的 Gemini API Key 账号视为第三方上游
- 第三方上游与 Vertex 不返回本地模拟配额,隐藏等级与配额说明;
  账号列表中第三方上游按普通 Key 账号展示今日统计与额度进度条,
  Vertex 显示 vertex 徽章与今日统计
- 第三方上游的 429 只认显式重试时长,否则走全局 429 兜底冷却,
  不按每日配额冷却到 PST 午夜
- 创建账号:第三方 Base URL 不显示 AI Studio 等级选项,也不写入 tier_id;
  API 密钥卡片标题与说明不再限定 AI Studio,免费层说明只在官方 Base URL 下显示;
  OAuth 等级回退下拉只在 OAuth 表单显示
- AI Studio 新建 Key 为 AQ.Ab 前缀的 auth key:logredact.RedactText 与
  渠道监控 sanitizeErrorMessage 增加 AQ.Ab 规则,长度按 40 位以上放宽以覆盖格式变体
- 创建 / 编辑账号的 Key 占位符改为 AQ.Ab...,提示文案说明新旧两种前缀
  与第三方上游 Key
- Gemini 平台 Service Account 账号改用 v1beta1 publishers/google/models
  分页拉取模型(pageSize 300,最多 20 页),按账号默认区域选端点;
  只保留 publishers/google/models/gemini-* 条目,排除区域端点里的
  Gemma、Veo、AutoML 等模型花园条目
- 凭据缺失或 location 非法返回配置错误(400),且不发起 token 交换;
  API Key 认证的 Vertex 账号返回不支持
- 翻页途中的 404/405 不再触发配置模型回退
- 模型列表的请求、读体与状态码检查抽成 readUpstreamModelsResponse
  供各平台共用
- apiClient 拒绝的是普通对象而非 Error,原写法 instanceof Error 恒为假,
  错误提示被替换成通用文案"同步上游模型失败:同步上游模型失败"
- 白名单选择器与 Antigravity 同步按钮改用 extractApiErrorMessage 取消息
- 绑定缓存的请求与缓存管理接口收到 429 / 5xx 时,只有上游网关账号的响应原样回写
  (UpstreamFailoverError.BoundUpstreamPassthrough / GeminiCachedContentUpstreamError.UpstreamGateway),
  官方账号仍走错误透传规则与通用映射,不向客户端暴露配额明细
- 记录新增 channel_usage(迁移 244)保存创建时的渠道计费口径,PATCH 延长按同一口径预检、报价与记账
- 创建 / 延长费用行的 request_id 改为固定前缀 gcache:{create|patch}:{id},不被客户端或网关请求 id 覆盖,
  按缓存 ID 即可检索一个缓存的全部费用行
- 调度快照凭据投影补齐 base_url / auth_mode / 上游显式缓存声明,显式缓存候选过滤一次算全,
  不再逐个选号后剔除
- 新增 Gemini 显式缓存存储单价表(Standard 档,USD / token / 小时):
  Pro 全系 $4.50、Flash 与 Flash-Lite 全系 $1.00;3.6 / 3.7 / 3.8 Flash
  为优惠价 $0.50(有效期至 2026-12-31,2027-01-01 起恢复 $1.00),
  AI Studio 与 Vertex 统一按优惠价计
- 型号表未命中的 Gemini 模型按系列兜底:Pro 取 $4.50,Flash / Flash-Lite
  取标准价 $1.00;Flash-Lite 变体不落到同版本 Flash 的优惠价
- 取值优先级:价格表(override_file 等)配置值 > 内置型号价 > 内置系列价;
  两者都没有的模型仍拒绝创建缓存
- 内置兜底价与本地价格表快照的 gemini-3.6-flash 改为 $0.75 输入 / $3.75 输出 /
  $0.075 缓存读取(Priority 档 $1.35 / $6.75 / $0.135),有效期至 2026-12-31,
  2027-01-01 起恢复 $1.50 / $7.50 / $0.15,与 3.7 / 3.8 Flash 及远程价格目录一致
Gemini 分组对外提供 AI Studio 兼容协议,分组内账号不一定是 AI Studio。
分组只剩 Vertex 服务账号时,GET /v1beta/models 与 /v1beta/models/{model}
选中服务账号后报 502 unsupported account type: service_account。

- SelectAccountForAIStudioEndpoints 改名 SelectAccountForModelsEndpoints,
  Vertex 账号排在所有 AI Studio 兼容账号之后参与选号
- ForwardAIStudioGET 拆为 ForwardListModels / ForwardGetModel,按账号类型分流:
  AI Studio 兼容账号原样转发;Vertex 服务账号读取 Google 发布方模型列表并
  转换为 AI Studio 格式,模型详情在该模型所用区域的列表中查找;Vertex API Key
  账号返回内置列表
- Vertex 发布方模型分页读取抽成 listVertexGeminiPublisherModels,与后台
  同步上游模型共用
- 模型接口响应体上限改用 gateway.models_list_read_max_bytes,超出时报错
@Wei-Shaw

Copy link
Copy Markdown
Owner

复核当前 head daebb7a80c720763a01e5cef8799c030aed0b058,现有关键 CI 均通过;下面 3 项可在隔离 worktree 复现,建议修复后再合并。

  1. [P1] 同一缓存并发 PATCH,迟到的旧响应会覆盖最新 TTL。 上游调用与本地写回、数据库无条件更新。A 把同一上游资源设为 2 小时、上游已提交但延迟返回;B 随后设为 24 小时并先完成落库/计费;A 的旧响应最后写回 2 小时。反例确认两个请求均 200,最终上游与本地到期时间相差约 22 小时。之后 Resolve 会提前拒绝已付费缓存。SQL 行锁只串行化本地 UPDATE,不能保证上游提交顺序与响应到达顺序一致。建议为同一缓存建立覆盖上游变更、本地写回和计费的跨实例串行化/版本恢复机制;仅取最大到期时间会破坏合法缩短 TTL 的语义。

  2. [P1] 新增固定金额续期仍可并发越过 API Key 总额度。 Key 检查 只读已结算用量;固定金额预留入口 后续仅做 用户余额预留。两个不同缓存、每笔约 $103.5、Key 剩余 $110、用户余额 $1000,开启 billing.inflight_reservation.enabled 后,两笔均在任何入账前到达上游,余额预留峰值 $207,两次 PATCH 最终均 200。对照将用户余额降为 $110,第二笔被正确拦截,说明余额预留有效但没有占用 Key 额度。这里实证的是准入和上游副作用,不是真实数据库双扣。订阅同样只读额度且 直接跳过预留;单独 helper 测试也确认日剩余 $110 时两次 $103.5 均放行。建议对确定金额按 Key/订阅维度原子预留,成功交接计费、失败释放。一般生成请求的事后计费并发窗口本就存在;本项限定本 PR 新增、事先已知全部费用的缓存操作。

  3. [P2] 上游续期成功后落库失败,没有可恢复的本地状态。 错误分支 直接返回 500,不登记待恢复操作、不补偿上游,也不提交存储计费。已有 TestGeminiCachedContentsPatch_PersistFailureDoesNotCharge 本身验证了一次上游 PATCH、500 和零用量记录;追加测试确认数据库恢复后的 GET 仍成功返回旧到期时间,未查询上游修复。若没有后续成功 PATCH,网关按旧时间失效,上游仍持续存储。这是新增持久资源的状态缺口,不是把既有通用异步计费可靠性问题归给本 PR。建议先持久化操作意图,失败后幂等对账/恢复状态与费用,或明确可安全执行的补偿。

复现命令(在当前 head 的 backend 目录,将下方测试保存为 internal/handler/audit_8006_recheck_test.go;复用 PR 已有夹具):

go test -tags=unit ./internal/handler -run 'TestAudit8006OutOfOrder|TestRecheck8006|TestGeminiCachedContentsPatch_PersistFailureDoesNotCharge' -v -count=1

实际结果:TTL 一致性断言失败(约 22 小时差);Key 额度断言失败(2 > 1,预留峰值 207);余额对照通过(上游仅 1 次);订阅预留断言失败(第二次错误为 nil);持久化失败/GET 旧状态测试通过。余额对照通过证明余额预留有效;持久化相关测试“通过”表示成功复现旧状态仍可读,不表示恢复机制已存在。测试未请求真实 Google 服务、未运行真实 PostgreSQL;mock 只控制上游响应时序和存储接口,未替换生产 handler/报价/准入逻辑。

可直接运行的复现测试
//go:build unit

package handler

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"strings"
	"testing"
	"time"

	"github.com/Wei-Shaw/sub2api/internal/config"
	"github.com/Wei-Shaw/sub2api/internal/service"
	"github.com/gin-gonic/gin"
	"github.com/stretchr/testify/require"
)

type audit8006Upstream struct {
	service.HTTPUpstream
	t                *testing.T
	calls            int
	expire           time.Time
	afterFirstCommit func()
}

func (u *audit8006Upstream) Do(req *http.Request, _ string, _ int64, _ int) (*http.Response, error) {
	u.calls++
	require.Equal(u.t, "/v1beta/cachedContents/up1", req.URL.Path)
	var payload map[string]string
	require.NoError(u.t, json.NewDecoder(req.Body).Decode(&payload))
	expectedTTL := "7200s"
	if u.calls == 2 {
		expectedTTL = "86400s"
	}
	require.Equal(u.t, expectedTTL, payload["ttl"])
	// 模拟上游先提交第一个 PATCH,但其响应延后到第二个 PATCH 已完成本地落库。
	expiry := time.Now().Add(2 * time.Hour)
	if u.calls == 2 {
		expiry = time.Now().Add(24 * time.Hour)
	}
	u.expire = expiry
	if u.calls == 1 {
		u.afterFirstCommit()
	}
	body := fmt.Sprintf(`{"name":"cachedContents/up1","expireTime":%q}`, expiry.UTC().Format(time.RFC3339Nano))
	return &http.Response{StatusCode: 200, Header: http.Header{}, Body: io.NopCloser(strings.NewReader(body))}, nil
}

func TestAudit8006OutOfOrderRenewalMustPreserveUpstreamExpiration(t *testing.T) {
	env := newCachedBillingEnv(t, 1000, 900)
	env.seed(time.Now().Add(time.Hour))
	upstream := &audit8006Upstream{t: t}
	cfg := &config.Config{}
	compat := service.NewGeminiMessagesCompatService(&cachedBillingAccountRepo{accounts: env.accounts}, nil, nil, nil, nil, nil, upstream, nil, cfg)
	env.h.geminiCachedContentService = service.NewGeminiCachedContentService(env.repo, compat, cfg)
	upstream.afterFirstCommit = func() { require.Equal(t, http.StatusOK, env.patch().Code) }
	rec := env.serve(http.MethodPatch, "/v1beta/cachedContents/abc?updateMask=ttl", `{"ttl":"7200s"}`, gin.Params{{Key: "cacheID", Value: "abc"}}, env.h.GeminiCachedContentsPatch)
	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
	require.WithinDuration(t, upstream.expire, env.repo.records["abc"].ExpireTime, time.Second, "两个成功 PATCH 后,本地到期时间必须与上游一致")
}

// 仅补齐本反例会调用的缓存接口;记录余额预留确实启用。
type recheck8006Cache struct {
	service.BillingCache
	balance      float64
	reserved     map[string]float64
	maxReserved  float64
	reserveCalls int
}

func (c *recheck8006Cache) GetUserBalance(context.Context, int64) (float64, error) {
	return c.balance, nil
}
func (c *recheck8006Cache) GetSubscriptionCache(context.Context, int64, int64) (*service.SubscriptionCacheData, error) {
	return &service.SubscriptionCacheData{Status: service.SubscriptionStatusActive, ExpiresAt: time.Now().Add(time.Hour)}, nil
}
func (c *recheck8006Cache) ReserveInflightBalance(_ context.Context, _ int64, id string, amount, balance float64, _ time.Duration) (bool, float64, error) {
	c.reserveCalls++
	sum := 0.0
	for _, v := range c.reserved {
		sum += v
	}
	if sum > 0 && balance-sum < amount {
		return false, sum, nil
	}
	c.reserved[id] = amount
	if sum+amount > c.maxReserved {
		c.maxReserved = sum + amount
	}
	return true, sum, nil
}
func (c *recheck8006Cache) ReleaseInflightBalance(_ context.Context, _ int64, id string) error {
	delete(c.reserved, id)
	return nil
}
func recheck8006EnableReservations(t *testing.T, env *cachedBillingEnv, balance float64) *recheck8006Cache {
	t.Helper()
	cache := &recheck8006Cache{balance: balance, reserved: map[string]float64{}}
	cfg := &config.Config{}
	cfg.Billing.InflightReservation.Enabled = true
	bcs := service.NewBillingCacheService(cache, nil, nil, nil, nil, nil, cfg, nil)
	t.Cleanup(bcs.Stop)
	env.h.billingCacheService = bcs
	require.True(t, bcs.InflightReservationEnabled())
	return cache
}
func TestRecheck8006KeyQuotaWithReservations(t *testing.T) {
	for _, tc := range []struct {
		name           string
		balance, quota float64
		want           int
	}{
		{"key_quota", 1000, 110, 1},
		{"balance_control", 110, 0, 1},
	} {
		t.Run(tc.name, func(t *testing.T) {
			env := newCachedBillingEnv(t, tc.balance, 900)
			env.seed(time.Now().Add(time.Hour))
			env.apiKey.Quota = tc.quota
			cache := recheck8006EnableReservations(t, env, tc.balance)
			second := *env.repo.records["abc"]
			second.ID = 101
			second.PublicID = "def"
			second.UpstreamName = "cachedContents/up2"
			env.repo.records["def"] = &second
			beforeSettlement := 0
			env.upstream.beforePost = func(n int) {
				// 此钩子在任何上游响应返回之前执行;此时两请求尚未触发计费。
				require.Empty(t, env.usage.totals())
				beforeSettlement = n
				if n == 1 {
					rec := env.serve(http.MethodPatch, "/v1beta/cachedContents/def?updateMask=ttl", `{"ttl":"86400s"}`, gin.Params{{Key: "cacheID", Value: "def"}}, env.h.GeminiCachedContentsPatch)
					if tc.name == "key_quota" {
						require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
					} else {
						require.NotEqual(t, http.StatusOK, rec.Code)
					}
				}
			}
			require.Equal(t, http.StatusOK, env.patch().Code)
			require.Equal(t, 2, cache.reserveCalls, "两个请求均实际调用了余额原子预留")
			t.Logf("未入账时已到达上游=%d,余额预留峰值=%.2f,reserve调用=%d", beforeSettlement, cache.maxReserved, cache.reserveCalls)
			require.LessOrEqual(t, beforeSettlement, tc.want, "固定费用每笔约103.5,剩余Key额度110不应同时放行两笔")
		})
	}
}
func TestRecheck8006SubscriptionChargeReservation(t *testing.T) {
	env := newCachedBillingEnv(t, 1000, 900)
	cache := recheck8006EnableReservations(t, env, 1000)
	limit := 110.0
	env.group.SubscriptionType = service.SubscriptionTypeSubscription
	env.group.DailyLimitUSD = &limit
	sub := &service.UserSubscription{ID: 1, UserID: env.apiKey.UserID, GroupID: env.group.ID, Status: service.SubscriptionStatusActive, ExpiresAt: time.Now().Add(time.Hour)}
	var secondErr error
	for i := 0; i < 2; i++ {
		env.serve(http.MethodPatch, "/", `{}`, nil, func(c *gin.Context) {
			done, err := env.h.reserveGeminiCachedContentCharge(c, env.apiKey, sub, 103.5)
			if done != nil {
				t.Cleanup(done)
			}
			if i == 0 {
				require.NoError(t, err)
			} else {
				secondErr = err
			}
		})
	}
	t.Logf("订阅剩余110,两次103.5固定金额准入;余额预留调用=%d,第二次错误=%v", cache.reserveCalls, secondErr)
	require.Error(t, secondErr, "第一笔仍未结算时应占用订阅剩余额度")
}
func TestRecheck8006PersistFailureLeavesStaleReadableState(t *testing.T) {
	env := newCachedBillingEnv(t, 1000, 900)
	old := time.Now().Add(time.Hour)
	env.seed(old)
	env.repo.failUpdate = true
	require.Equal(t, http.StatusInternalServerError, env.patch().Code)
	require.Equal(t, 1, env.upstream.methodCalls(http.MethodPatch))
	require.Equal(t, old, env.repo.records["abc"].ExpireTime)
	require.Empty(t, env.usage.totals())
	require.Zero(t, env.upstream.methodCalls(http.MethodDelete))
	env.repo.failUpdate = false
	require.Equal(t, http.StatusOK, env.serve(http.MethodGet, "/v1beta/cachedContents/abc", "", gin.Params{{Key: "cacheID", Value: "abc"}}, env.h.GeminiCachedContentsGet).Code)
	require.Equal(t, old, env.repo.records["abc"].ExpireTime)
	require.Equal(t, 1, env.upstream.methodCalls(http.MethodPatch), "Get未触发任何上游状态恢复")
}

同一缓存的并发 PATCH 可能以与上游提交不同的顺序写回本地到期时间;
确定金额的存储费只预留用户余额,并发续期可越过 API Key 总额度与订阅额度;
上游已修改而本地写回失败时没有可恢复的状态。

- 新增迁移 245:缓存记录增加修改意图(mutation_token / mutation_lease_until)。
  PATCH 在调用上游前登记意图并取得 2 分钟租约,条件为没有进行中的修改且到期时间
  未变;上游修改、本地写回与计费均由持有者完成,并发的修改返回 409 ABORTED
- 上游结果未知、本地写回失败或进程退出时修改意图保留且不计费;租约过期后由下一次
  修改或后台每分钟的恢复流程把上游有效期回滚到修改前的到期时间(已到期则删除上游
  缓存与本地记录)。上游明确拒绝或请求未发出时直接清除意图
- 修改 / 删除上游缓存的单次调用超时改为 30 秒;请求发出前的失败包装为
  ErrGeminiCachedContentRequestNotSent
- CheckChargeAffordable 与 ReserveInflightCharge 合并为 ReserveFixedCharge:在途预留
  新增订阅、API Key 两个维度(Redis billing:inflight_scope:*),先登记本笔预留再读取
  库中权威用量(Key quota_used 与限速窗口、订阅日 / 周 / 月用量)叠加同维度在途合计
  校验;预留随计费任务交接,落库后释放
- GetRateLimitData 一并读取 quota_used
@Wei-Shaw

Copy link
Copy Markdown
Owner

复核最新 head 26b31a83e4190a3b38bce112fc597defbfb9515b:上轮并发 PATCH、Key/订阅额度预留及正常失败恢复路径已补齐,定向测试通过。新增恢复机制还有一个 [P2] 暂时关闭上游显式缓存能力会误清尚未完成的补偿意图,建议合并前处理。

触发场景:自建网关账号 explicit_cache_upstream=true;上游 PATCH 延长成功,但本地 CommitMutation 失败,意图正确保留。租约到期后,管理员临时关闭该账号的显式缓存能力,此时后台恢复流程:

  1. BoundAccount 第 877 行 因账号不再支持缓存而返回 (nil, nil)。
  2. rollbackUpstream 第 842 行 未执行上游回滚,却返回 (false, nil)。
  3. recoverStaleMutation 第 835 行 将其视作成功,调用 ReleaseMutation 清除唯一补偿标记。重新开启能力后,后台已查不到这笔待恢复操作。

本次在隔离 worktree 重跑的结果:

关闭能力时:恢复计数=1,错误=nil,累计上游 PATCH=1,意图保留=false
重新启用后:恢复计数=0,错误=nil,累计上游 PATCH=1,意图保留=false
保护断言失败:未回滚上游前不能因临时关闭能力丢弃恢复意图

累计 PATCH 为 1 表示只有最初续期,没有任何补偿请求。影响是本地仍按旧有效期失效,上游却可能持续存储;重新启用能力也无法再自动补偿。

建议将“当前无法取得支持缓存的账号”作为可重试恢复失败,保留意图;只有确认上游回滚/删除完成后才清除。已用外部 overlay 仅将 account == nil 改为返回非 nil 错误作因果对照:关闭能力时意图保留,重新启用并待租约过期后发出第二次 PATCH,恢复完成再清除意图,完整测试通过。该对照未修改 PR 分支。

下面测试可单独保存为 backend/internal/handler/audit_8006_recovery_test.go,复用本 PR 已有夹具,从 backend 运行:

go test -tags=unit ./internal/handler -run '^TestAudit8006RecoveryDisabledCapabilityKeepsIntent$' -count=1 -v
可复制的关闭能力、重新启用恢复回归测试
//go:build unit

package handler

import (
	"context"
	"net/http"
	"testing"
	"time"

	"github.com/Wei-Shaw/sub2api/internal/service"
	"github.com/stretchr/testify/require"
)

func TestAudit8006RecoveryDisabledCapabilityKeepsIntent(t *testing.T) {
	env := newCachedBillingEnv(t, 1000, 900)
	env.accounts[900].Credentials["base_url"] = "https://gw.example.com"
	env.accounts[900].Credentials[service.GeminiExplicitCacheUpstreamCredentialKey] = true
	env.seed(time.Now().Add(time.Hour))
	env.repo.failCommit = true
	require.Equal(t, http.StatusInternalServerError, env.patch().Code)
	require.True(t, env.repo.pendingMutation(100))
	require.Equal(t, 1, env.upstream.methodCalls(http.MethodPatch))
	env.repo.failCommit = false
	env.repo.expireLease(100)
	env.accounts[900].Credentials[service.GeminiExplicitCacheUpstreamCredentialKey] = false
	recovered, err := env.h.geminiCachedContentService.RecoverStaleMutations(context.Background())
	pending := env.repo.pendingMutation(100)
	t.Logf("关闭能力时:恢复计数=%d 错误=%v PATCH次数=%d 意图保留=%v", recovered, err, env.upstream.methodCalls(http.MethodPatch), pending)
	env.accounts[900].Credentials[service.GeminiExplicitCacheUpstreamCredentialKey] = true
	// 仅对仍保留的意图推进租约,避免测试替生产代码重新创建已丢失的意图。
	if pending {
		env.repo.expireLease(100)
	}
	recoveredAgain, errAgain := env.h.geminiCachedContentService.RecoverStaleMutations(context.Background())
	t.Logf("重新启用后:恢复计数=%d 错误=%v PATCH次数=%d 意图保留=%v", recoveredAgain, errAgain, env.upstream.methodCalls(http.MethodPatch), env.repo.pendingMutation(100))
	require.True(t, pending, "未回滚上游前不能因临时关闭能力丢弃恢复意图")
	require.Zero(t, recovered)
	require.Error(t, err)
	require.NoError(t, errAgain)
	require.Equal(t, 1, recoveredAgain)
	require.Equal(t, 2, env.upstream.methodCalls(http.MethodPatch))
	require.False(t, env.repo.pendingMutation(100))
}

验证使用本 PR 的 HTTP/仓储夹具模拟上游成功、本地提交失败及租约过期,执行生产 handler 和恢复逻辑;未请求真实 Google/网关服务或运行 PostgreSQL。

后台回滚在持有账号返回 nil 时把修改意图当作已回滚清除:账号临时关闭显式缓存能力后
意图丢失,重新开启也无法补偿。

- boundAccount 区分两种情形:账号已删除返回 nil,账号存在但不支持显式缓存返回
  errGeminiCachedContentAccountUnsupported;BoundAccount 对外行为不变
- 账号暂不支持缓存时不改动上游、保留意图,租约过期后重试(期间同一缓存的修改返回 409);
  账号已删除时没有凭据可回滚上游,软删本地记录
- 修改前到期时间加上单次最长有效期与 1 小时容忍都已过去时上游缓存必已自行过期:
  账号不支持缓存或上游回滚持续失败的意图不再重试,直接作废本地记录
- 测试夹具 GetForOwner 过滤已软删记录
@Wei-Shaw
Wei-Shaw merged commit 53c21fe into Wei-Shaw:main Oct 13, 2026
9 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 13, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants