GitLab

Cherry-picked from release/custom-0.1.106: a9117600

shaw authored Mar 27, 2026 and 陈曦 committed Mar 29, 2026

新增功能：
- 新增 TLS 指纹 Profile CRUD 管理（Ent schema + 迁移 + Admin API + 前端管理界面）
- 支持账号绑定数据库中的自定义 TLS Profile，或随机选择（profile_id=-1）
- HTTPUpstream.DoWithTLS 接口从 bool 改为 *tlsfingerprint.Profile，支持按账号指定 Profile
- AccountUsageService 注入 TLSFingerprintProfileService，统一 usage 场景与网关的 Profile 解析逻辑

代码优化：
- 删除已被 TLSFingerprintProfileService 完全取代的 registry.go 死代码（418 行）
- 提取 3 个 dialer 的重复 TLS 握手逻辑为 performTLSHandshake() 共用函数
- 修复 GetTLSFingerprintProfileID 缺少 json.Number 处理的 bug
- gateway_service.Forward 中 ResolveTLSProfile 从重试循环内重复调用改为预解析局部变量
- 删除冗余的 buildClientHelloSpec() 单行 wrapper 和 int64(e.ID) 无效转换
- tls_fingerprint_profile_cache.go 日志从 log.Printf 改为 slog 结构化日志
- dialer_capture_test.go 添加 //go:build integration 标签，防止 CI 失败
- 去重 TestProfileExpectation 类型至共享 test_types_test.go
- 修复 9 个测试文件缺少 tlsfingerprint import 的编译错误
- 修复 error_policy_integration_test.go 中 handleError 回调签名被错误替换的问题

新增功能：
- 新增 TLS 指纹 Profile CRUD 管理（Ent schema + 迁移 + Admin API + 前端管理界面）
- 支持账号绑定数据库中的自定义 TLS Profile，或随机选择（profile_id=-1）
- HTTPUpstream.DoWithTLS 接口从 bool 改为 *tlsfingerprint.Profile，支持按账号指定 Profile
- AccountUsageService 注入 TLSFingerprintProfileService，统一 usage 场景与网关的 Profile 解析逻辑

代码优化：
- 删除已被 TLSFingerprintProfileService 完全取代的 registry.go 死代码（418 行）
- 提取 3 个 dialer 的重复 TLS 握手逻辑为 performTLSHandshake() 共用函数
- 修复 GetTLSFingerprintProfileID 缺少 json.Number 处理的 bug
- gateway_service.Forward 中 ResolveTLSProfile 从重试循环内重复调用改为预解析局部变量
- 删除冗余的 buildClientHelloSpec() 单行 wrapper 和 int64(e.ID) 无效转换
- tls_fingerprint_profile_cache.go 日志从 log.Printf 改为 slog 结构化日志
- dialer_capture_test.go 添加 //go:build integration 标签，防止 CI 失败
- 去重 TestProfileExpectation 类型至共享 test_types_test.go
- 修复 9 个测试文件缺少 tlsfingerprint import 的编译错误
- 修复 error_policy_integration_test.go 中 handleError 回调签名被错误替换的问题

## Problem

When a proxy is unreachable, token refresh retries up to 4 times with
30s timeout each, causing requests to hang for ~2 minutes before
failing with a generic 502 error. The failed account is not marked,
so subsequent requests keep hitting it.

## Changes

### Proxy connection fast-fail
- Set TCP dial timeout to 5s and TLS handshake timeout to 5s on
  antigravity client, so proxy connectivity issues fail within 5s
  instead of 30s
- Reduce overall HTTP client timeout from 30s to 10s
- Export `IsConnectionError` for service-layer use
- Detect proxy connection errors in `RefreshToken` and return
  immediately with "proxy unavailable" error (no retries)

### Token refresh temp-unschedulable
- Add 8s context timeout for token refresh on request path
- Mark account as temp-unschedulable for 10min when refresh fails
  (both background `TokenRefreshService` and request-path
  `GetAccessToken`)
- Sync temp-unschedulable state to Redis cache for immediate
  scheduler effect
- Inject `TempUnschedCache` into `AntigravityTokenProvider`

### Account failover
- Return `UpstreamFailoverError` on `GetAccessToken` failure in
  `Forward`/`ForwardGemini` to trigger handler-level account switch
  instead of returning 502 directly

### Proxy probe alignment
- Apply same 5s dial/TLS timeout to shared `httpclient` pool
- Reduce proxy probe timeout from 30s to 10s

复用 GroupCapacityService，在 admin 分组列表中添加容量列，
显示每个分组的实时并发/会话/RPM 使用量和上限。
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Introduce OAuthRefreshAPI as the single entry point for all OAuth token
refresh operations, eliminating the race condition where background
refresh and inline refresh could simultaneously use the same
refresh_token (fixes #1035).

Key changes:
- Add OAuthRefreshExecutor interface extending TokenRefresher with CacheKey
- Add OAuthRefreshAPI.RefreshIfNeeded with lock → DB re-read → double-check flow
- Add ProviderRefreshPolicy / BackgroundRefreshPolicy strategy types
- Simplify all 4 TokenProviders to delegate to OAuthRefreshAPI
- Rewrite TokenRefreshService.refreshWithRetry to use unified API path
- Add MergeCredentials and BuildClaudeAccountCredentials helpers
- Add 40 unit tests covering all new and modified code paths

1. S3 凭证加密存储：使用 SecretEncryptor (AES-256-GCM) 加密 SecretAccessKey，
   防止备份文件中泄露 S3 凭证，兼容旧的未加密数据
2. 修复 saveRecord 竞态条件：添加 recordsMu 互斥锁保护 records 的 load/save
3. 恢复操作增加服务端验证：handler 层要求重新输入管理员密码，通过 bcrypt
   校验，前端弹出密码输入框
4. pg_dump/psql/S3 操作抽象为接口：定义 DBDumper 和 BackupObjectStore 接口，
   实现放入 repository 层，遵循项目依赖注入架构规范
5. 改为流式处理避免大数据库 OOM：备份时 pg_dump stdout -> gzip -> io.Pipe ->
   S3 upload；恢复时 S3 download -> gzip reader -> psql stdin，不再全量加载
6. loadRecords 区分"无数据"和"数据损坏"场景：JSON 解析失败返回明确错误
7. 添加 18 个核心逻辑单元测试：覆盖加密、并发、流式备份/恢复、错误处理等
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

新增管理员专属的数据库备份与恢复功能：
- 全量 PostgreSQL 备份（pg_dump），gzip 压缩后上传到 S3 兼容存储
- 支持手动备份和 cron 定时备份
- 支持从备份恢复（psql --single-transaction）
- 备份文件自动过期清理（默认 14 天）
- 前端完整管理页面（S3 配置、定时配置、备份列表、恢复/下载/删除）
- 内置 Cloudflare R2 配置教程弹窗
- Dockerfile 从 postgres 镜像多阶段复制 pg_dump/psql，确保版本一致
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

When the service restarts, concurrency slots from the old process
remain in Redis, causing phantom occupancy. On startup, scan all
concurrency sorted sets and remove members with non-current process
prefix, then clear orphaned wait queue counters.

Uses Go-side SCAN to discover keys (compatible with Redis client
prefix hooks in tests), then passes them to a Lua script for
atomic member-level cleanup.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- 为定时测试计划增加 auto_recover 配置，补齐前后端类型、接口、仓储与数据库迁移
- 在定时测试成功后自动恢复账号 error、rate-limit 等可恢复运行时状态
- 新增 /admin/accounts/:id/recover-state 接口，合并原有重置状态与清限流操作
- 更新账号管理菜单与定时测试面板，补充自动恢复开关、说明提示和状态展示
- 补充账号恢复、限流清理与仓储同步相关测试

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

将 redis leader lock 逻辑从 service 层抽取为 LeaderLocker 接口，
实现移至 repository 层，消除 service 层对 redis 的直接依赖。
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

每个测试计划绑定一个账号和一个模型，按 cron 表达式定期执行测试，
保存历史结果并在前端账号管理页面中提供完整的增删改查和结果查看功能。

主要变更：
- 新增 scheduled_test_plans / scheduled_test_results 两张表及迁移
- 后端 service 层：CRUD 服务 + 后台 cron runner（每分钟扫描到期计划并发执行）
- RunTestBackground 方法通过 httptest 在内存中执行账号测试并解析 SSE 输出
- Redis leader lock + pg_try_advisory_lock 双重保障多实例部署只执行一次
- REST API：5 个管理端点（计划 CRUD + 结果查询）
- 前端 ScheduledTestsPanel 组件：计划管理、启用开关、内联编辑、结果展开查看
- 中英文 i18n 支持
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

新增 UMQ (User Message Queue) 双模式支持:
- serialize: 账号级分布式串行锁 + RPM 自适应延迟（严格限流）
- throttle: 仅 RPM 自适应前置延迟，不阻塞并发（软性限速）

后端:
- config: 新增 Mode 字段，保留 Enabled 向后兼容
- service: 新增 UserMessageQueueService（Lua 锁/延迟算法/清理 worker）
- repository: 新增 UserMsgQueueCache（Redis Lua acquire/release/force-release）
- handler: 新增 UserMsgQueueHelper（SSE ping + 等待循环 + throttle）
- gateway: 按 mode 分支集成 serialize/throttle 逻辑
- lint: 修复 gofmt rewrite rules、errcheck 类型断言、staticcheck QF1012

前端:
- 三态选择器 UI（关闭/软性限速/串行队列）替代 toggle 开关
- BulkEdit 支持 null 语义（不修改）
- i18n 中英文文案

通过 6 轮专家评审（42 次 review）、golangci-lint、单元测试、集成测试。

OAuth 账号收到 401 时，原逻辑同时设置 expires_at=now() 和 SetError()，
但刷新服务只查询 status=active 的账号，导致 error 状态的账号永远无法
被刷新服务拾取，expires_at=now() 实际上是死代码。

修复:
- OAuth 401 使用 SetTempUnschedulable 替代 SetError，保持 status=active
- 新增 oauth_401_cooldown_minutes 配置项（默认 10 分钟）
- 刷新成功后同步清除 DB 和 Redis 中的临时不可调度状态
- 不可重试错误检查(invalid_grant 等)从 Antigravity 推广到所有平台
- 可重试错误耗尽后不再标记 error，下个刷新周期继续重试

恢复流程:
OAuth 401 → temp_unschedulable + expires_at=now → 刷新服务拾取
  → 成功: 清除 temp_unschedulable → 自动恢复
  → invalid_grant: SetError → 永久禁用
  → 网络错误: 仅记日志 → 下周期重试

- add default subscriptions to admin settings

- auto-assign subscriptions on register and admin user creation

- add validation/tests and align settings UI with subscription selector patterns

使用 go-sora2api v1.1.0 SDK 替代原有 ~2000 行自建 HTTP/PoW/TLS 指纹代码，
SDK 提供高并发性能优化（实例级 rand、PoW 缓冲区复用、context.Context 支持）。

- 新增 SoraSDKClient 适配器实现 SoraClient 接口
- 精简 sora_client.go 为仅保留接口和类型定义
- 更新 Wire 绑定使用 SoraSDKClient
- 删除 SoraDirectClient、sora_curl_cffi_sidecar、sora_request_guard 等旧代码
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- 新增 UsageRecordWorkerPool，支持有界队列、溢出降级策略与自动扩缩容
- 将 Gateway/OpenAI/Sora/Gemini 使用量记录改为提交到统一任务池执行
- 增加 usage_record 配置默认值与校验规则，并补充配置与任务提交相关测试
- 注入并托管 worker 池生命周期，服务退出时统一 StopAndWait
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- 新增并接通 Sora 专用 OAuth 接口与 ST/RT 换取能力
- 完成前端 Sora 授权、RT/ST 手动导入与账号创建流程
- 强化 Sora token 恢复、转发日志与网关路由隔离行为
- 补充后端服务层与路由层相关测试覆盖
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

支持管理员配置上游错误如何返回给客户端：
- 新增 ErrorPassthroughRule 数据模型和 Ent Schema
- 实现规则的 CRUD API（/admin/error-passthrough-rules）
- 支持按错误码、关键词匹配，支持 any/all 匹配模式
- 支持按平台过滤（anthropic/openai/gemini/antigravity）
- 支持透传或自定义响应状态码和错误消息
- 实现两级缓存（Redis + 本地内存）和多实例同步
- 集成到 gateway_handler 的错误处理流程
- 新增前端管理界面组件
- 新增单元测试覆盖核心匹配逻辑

优化：
- 移除 refreshLocalCache 中的冗余排序（数据库已排序）
- 后端 Validate() 增加匹配条件非空校验

Token 刷新成功后，调度器缓存中的 Account 对象仍包含旧的 credentials，
导致在 Outbox 异步更新之前（最多 1 秒窗口）请求使用过期 token，
返回 403 错误（OAuth token has been revoked）。

修复方案：在 token 刷新成功后同步更新调度器缓存，确保调度获取的
Account 对象立即包含最新的 access_token 和 _token_version。

此修复覆盖所有 OAuth 平台：OpenAI、Claude、Gemini、Antigravity。

实现直连 Sora 客户端、媒体落地与清理策略\n更新网关与前端配置以支持 Sora 平台\n补齐单元测试与契约测试，新增 curl 测试脚本\n\n测试: go test ./... -tags=unit

新增 Sora 网关路由、账号调度与同步服务\n补充媒体代理与签名 URL、模型列表动态拉取\n完善计费配置、前端支持与相关测试

Implements announcements end-to-end (admin CRUD + read status, user list + mark read) with OR-of-AND targeting. Also breaks the ent<->service import cycle by moving schema-facing constants/targeting into a new domain package.

- 新增 sora_accounts 表与 accounts.extra GIN 索引\n- OpenAI OAuth 支持同时创建 Sora 账号并同步配置\n- Token 刷新同步关联 Sora 账号凭证与扩展表\n- 增加 Sora 账号连通性测试与前端开关文案

新增功能：
- 新增 Sora 账号管理和 OAuth 认证
- 新增 Sora 视频/图片生成 API 网关
- 新增 Sora 任务调度和缓存机制
- 新增 Sora 使用统计和计费支持
- 前端增加 Sora 平台配置界面

安全修复（代码审核）：
- [SEC-001] 限制媒体下载响应体大小（图片 20MB、视频 200MB），防止 DoS 攻击
- [SEC-002] 限制 SDK API 响应大小（1MB），防止内存耗尽
- [SEC-003] 修复 SSRF 风险，添加 URL 验证并强制使用代理配置

BUG 修复（代码审核）：
- [BUG-001] 修复 for 循环内 defer 累积导致的资源泄漏
- [BUG-002] 修复图片并发槽位获取失败时已持有锁未释放的永久泄漏

性能优化（代码审核）：
- [PERF-001] 添加 Sentinel Token 缓存（3 分钟有效期），减少 PoW 计算开销

技术细节：
- 使用 io.LimitReader 限制所有外部输入的大小
- 添加 urlvalidator 验证防止 SSRF 攻击
- 使用 sync.Map 实现线程安全的包级缓存
- 优化并发槽位管理，添加 releaseAll 模式防止泄漏

影响范围：
- 后端：新增 Sora 相关数据模型、服务、网关和管理接口
- 前端：新增 Sora 平台配置、账号管理和监控界面
- 配置：新增 Sora 相关配置项和环境变量
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

新增功能：
- 支持 Google Authenticator 等应用进行 TOTP 二次验证
- 用户可在个人设置中启用/禁用 2FA
- 登录时支持 TOTP 验证流程
- 管理后台可全局开关 TOTP 功能

安全增强：
- TOTP 密钥使用 AES-256-GCM 加密存储
- 添加 TOTP_ENCRYPTION_KEY 配置项，必须手动配置才能启用功能
- 防止服务重启导致加密密钥变更使用户无法登录
- 验证失败次数限制，防止暴力破解

配置说明：
- Docker 部署：在 .env 中设置 TOTP_ENCRYPTION_KEY
- 非 Docker 部署：在 config.yaml 中设置 totp.encryption_key
- 生成密钥命令：openssl rand -hex 32

- 新增 SubscriptionExpiryService 定时任务，每分钟更新过期订阅状态
- 订阅列表支持服务端排序（按过期时间、状态、创建时间）
- 实时显示正确的过期状态，无需等待定时任务
- 允许对已过期订阅进行续期操作
- DataTable 组件支持 serverSideSort 模式

- 分页接口 page_size 最大限制从 100 改为 1000
- 通过 Redis Pub/Sub 实现跨实例认证缓存失效
- 允许订阅类型分组编辑计费倍率
- 账号计费倍率支持 3 位小数

- NewTimingWheelService 改为返回 error，避免 panic

- ProvideTimingWheelService 透传 error 并更新 wire 生成代码

- 补充定时任务调度/取消/周期任务相关单元测试

新增 OpenAI/Claude TokenProvider 与缓存键生成
扩展 OAuth 缓存失效覆盖更多平台
统一 OAuth 缓存前缀与依赖注入