sub2api/deploy/config.example.yaml

# Sub2API Configuration File
# Sub2API 配置文件
#
# Copy this file to /etc/sub2api/config.yaml and modify as needed
# 复制此文件到 /etc/sub2api/config.yaml 并根据需要修改
#
# Documentation / 文档: https://github.com/Wei-Shaw/sub2api

# =============================================================================
# Server Configuration
# 服务器配置
# =============================================================================
server:
  # Bind address (0.0.0.0 for all interfaces)
  # 绑定地址（0.0.0.0 表示监听所有网络接口）
  host: "0.0.0.0"
  # Port to listen on
  # 监听端口
  port: 8080
  # Mode: "debug" for development, "release" for production
  # 运行模式："debug" 用于开发，"release" 用于生产环境
  mode: "release"
  # Return Server-Timing for authenticated requests made by the Admin web UI
  # 为管理端 Web 页面发出的已认证请求返回 Server-Timing
  enable_server_timing: false
  # Frontend base URL used to generate external links in emails (e.g. password reset)
  # 用于生成邮件中的外部链接（例如：重置密码链接）的前端基础地址
  # Example: "https://example.com"
  frontend_url: ""
  # Maximum time to receive complete request headers. Does not limit response streams.
  # 完整读取请求头的最大时间；不限制响应流持续时间。
  read_header_timeout: 10
  # Request header limit in bytes (64 KiB); also bounds the HTTP/2 header list.
  # 请求头上限（字节，默认 64 KiB）；同时约束 HTTP/2 header list。
  max_header_bytes: 65536
  # Keep-alive idle timeout in seconds.
  # Keep-Alive 空闲连接超时（秒）。
  idle_timeout: 120
  # Trusted proxies used when security.trust_forwarded_ip_for_api_key_acl is false.
  # List only the exact proxy addresses that connect directly to Sub2API.
  # Set [] explicitly to disable forwarded-IP trust in high-security mode.
  # security.trust_forwarded_ip_for_api_key_acl=false 时使用的可信代理。
  # 只填写直接连接 Sub2API 的精确代理地址；显式设置 [] 可在高安全模式下
  # 禁用转发 IP 信任。
  trusted_proxies:
    - 127.0.0.1/32
    - ::1/128
  # Global max request body size in bytes (default: 256MB)
  # 全局最大请求体大小（字节，默认 256MB）
  # Applies to all requests, especially important for h2c first request memory protection
  # 适用于所有请求，对 h2c 第一请求的内存保护尤为重要
  max_request_body_size: 268435456
  # HTTP/2 Cleartext (h2c) configuration
  # HTTP/2 Cleartext (h2c) 配置
  h2c:
    # Enable HTTP/2 Cleartext for client connections
    # 启用 HTTP/2 Cleartext 客户端连接
    enabled: true
    # Max concurrent streams per connection
    # 每个连接的最大并发流数量
    max_concurrent_streams: 50
    # Idle timeout for connections (seconds)
    # 连接空闲超时时间（秒）
    idle_timeout: 75
    # Max frame size in bytes (default: 1MB)
    # 最大帧大小（字节，默认 1MB）
    max_read_frame_size: 1048576
    # Max upload buffer per connection in bytes (default: 2MB)
    # 每个连接的最大上传缓冲区（字节，默认 2MB）
    max_upload_buffer_per_connection: 2097152
    # Max upload buffer per stream in bytes (default: 512KB)
    # 每个流的最大上传缓冲区（字节，默认 512KB）
    max_upload_buffer_per_stream: 524288

# =============================================================================
# WebAuthn / Passkey Configuration
# WebAuthn / Passkey 配置
# =============================================================================
# Passkeys require HTTPS in production. The RP ID is the domain only (no scheme
# or port), while RP origins are exact browser origins.
# Passkey 在生产环境要求 HTTPS。RP ID 只填写域名（不含协议和端口），RP origins
# 填写浏览器访问使用的完整 Origin。
webauthn:
  enabled: false
  rp_display_name: "Sub2API"
  # Example / 示例: "sub2api.example.com"
  rp_id: ""
  # Example / 示例: ["https://sub2api.example.com"]
  rp_origins: []

# =============================================================================
# Run Mode Configuration
# 运行模式配置
# =============================================================================
# Run mode: "standard" (default) or "simple" (for internal use)
# 运行模式："standard"（默认）或 "simple"（内部使用）
# - standard: Full SaaS features with billing/balance checks
# - standard: 完整 SaaS 功能，包含计费和余额校验
# - simple: Hides SaaS features and skips billing/balance checks
# - simple: 隐藏 SaaS 功能，跳过计费和余额校验
run_mode: "standard"

# =============================================================================
# CORS Configuration
# 跨域资源共享 (CORS) 配置
# =============================================================================
cors:
  # Allowed origins list. Leave empty to disable cross-origin requests.
  # 允许的来源列表。留空则禁用跨域请求。
  allowed_origins: []
  # Allow credentials (cookies/authorization headers). Cannot be used with "*".
  # 允许携带凭证（cookies/授权头）。不能与 "*" 通配符同时使用。
  allow_credentials: true

# =============================================================================
# Security Configuration
# 安全配置
# =============================================================================
security:
  # Legacy compatibility switch. When true, raw forwarded headers take over
  # server.trusted_proxies. Set false to enforce the trusted proxy chain above.
  # 旧版兼容开关。开启时原始转发头会接管 server.trusted_proxies；关闭后严格
  # 使用上方配置的可信代理链。示例配置采用高安全模式。
  trust_forwarded_ip_for_api_key_acl: false
  # Optional client-IP headers for third-party CDNs, checked in list order before
  # CF-Connecting-IP, X-Real-IP, and X-Forwarded-For. Valid only while the legacy
  # compatibility switch above is true; maximum 16 unique HTTP header names.
  # 第三方 CDN 的可选客户端 IP 请求头，按列表顺序优先于内置请求头解析。
  # 仅在上方旧版兼容开关为 true 时生效；最多配置 16 个不重复的合法 HTTP 头名。
  # Environment / 环境变量: SECURITY_FORWARDED_CLIENT_IP_HEADERS=True-Client-IP,X-CDN-Client-IP
  forwarded_client_ip_headers: []
  # Example / 示例:
  # forwarded_client_ip_headers:
  #   - "True-Client-IP"
  #   - "X-CDN-Client-IP"
  url_allowlist:
    # Enable URL allowlist validation (disable to skip all URL checks)
    # 启用 URL 白名单验证（禁用则跳过所有 URL 检查）
    enabled: false
    # Allowed upstream hosts for API proxying
    # 允许代理的上游 API 主机列表
    upstream_hosts:
      - "api.openai.com"
      - "api.anthropic.com"
      - "api.kimi.com"
      - "api.moonshot.ai"
      - "api.moonshot.cn"
      - "open.bigmodel.cn"
      - "api.minimaxi.com"
      - "generativelanguage.googleapis.com"
      - "cloudcode-pa.googleapis.com"
      - "*.openai.azure.com"
    # Allowed hosts for pricing data download
    # 允许下载定价数据的主机列表
    pricing_hosts:
      - "raw.githubusercontent.com"
    # Allowed hosts for CRS sync (required when using CRS sync)
    # 允许 CRS 同步的主机列表（使用 CRS 同步功能时必须配置）
    crs_hosts: []
    # Allow localhost/private IPs for upstream/pricing/CRS (use only in trusted networks)
    # 允许本地/私有 IP 地址用于上游/定价/CRS（仅在可信网络中使用）
    allow_private_hosts: true
    # Allow http:// URLs when allowlist is disabled (default: true; set to false to require https)
    # 白名单禁用时是否允许 http:// URL（默认: true，设为 false 则仅允许 https）
    allow_insecure_http: true
  response_headers:
    # Enable configurable response header filtering (default: true)
    # 启用可配置的响应头过滤（默认启用，过滤上游敏感响应头）
    enabled: true
    # Extra allowed response headers from upstream
    # 额外允许的上游响应头
    additional_allowed: []
    # Force-remove response headers from upstream
    # 强制移除的上游响应头
    force_remove: []
  csp:
    # Enable Content-Security-Policy header
    # 启用内容安全策略 (CSP) 响应头
    enabled: true
    # Default CSP policy (override if you host assets on other domains)
    # 默认 CSP 策略（如果静态资源托管在其他域名，请自行覆盖）
    # Note: __CSP_NONCE__ will be replaced with 'nonce-xxx' at request time for inline script security
    # 注意：__CSP_NONCE__ 会在请求时被替换为 'nonce-xxx'，用于内联脚本安全
    policy: "default-src 'self'; worker-src 'self' blob:; script-src 'self' __CSP_NONCE__ https://challenges.cloudflare.com https://*.alicdn.com https://static.cloudflareinsights.com https://turing.captcha.qcloud.com https://turing.captcha.gtimg.com https://ca.turing.captcha.qcloud.com https://global.turing.captcha.gtimg.com https://www.tycaptcha.com https://cloudcache.tencentcs.com https://*.stripe.com https://static.airwallex.com https://checkout.airwallex.com https://static-demo.airwallex.com https://checkout-demo.airwallex.com; style-src 'self' 'unsafe-inline' https://*.captcha.gtimg.com https://fonts.googleapis.com https://*.alicdn.com https://static.airwallex.com https://checkout.airwallex.com https://static-demo.airwallex.com https://checkout-demo.airwallex.com; img-src 'self' data: blob: https:; font-src 'self' data: https://fonts.gstatic.com; connect-src 'self' https://turing.captcha.qcloud.com https://www.tycaptcha.com https://rce.tencentrio.com https:; frame-src 'self' https://challenges.cloudflare.com https://turing.captcha.qcloud.com https://ca.turing.captcha.qcloud.com https://www.tycaptcha.com https://*.stripe.com https://checkout.airwallex.com https://checkout-demo.airwallex.com; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"
  proxy_probe:
    # Allow skipping TLS verification for proxy probe (debug only)
    # 允许代理探测时跳过 TLS 证书验证（仅用于调试）
    insecure_skip_verify: false
    # Optional ordered probe targets. Leave empty to use the built-in ip-api/ipify fallback.
    # parser supports: ip-api, ipify, chatgpt-trace
    # 可选的有序探测目标。留空时使用内置 ip-api/ipify 回退。
    # parser 支持：ip-api、ipify、chatgpt-trace
    urls: []
    # urls:
    #   - url: "https://chatgpt.com/cdn-cgi/trace"
    #     parser: "chatgpt-trace"
    #   - url: "https://api64.ipify.org?format=json"
    #     parser: "ipify"
  proxy_fallback:
    # Allow auxiliary services (update check, pricing data) to fallback to direct
    # connection when proxy initialization fails. Does NOT affect AI gateway connections.
    # 辅助服务（更新检查、定价数据拉取）代理初始化失败时是否允许回退直连。
    # 不影响 AI 账号网关连接。默认 false：fail-fast 防止 IP 泄露。
    allow_direct_on_error: false

# =============================================================================
# Gateway Configuration
# 网关配置
# =============================================================================
gateway:
  # Timeout for waiting upstream response headers (seconds)
  # 等待上游响应头超时时间（秒）
  response_header_timeout: 600
  # OpenAI/Codex upstream response header timeout (seconds, 0=disabled)
  # OpenAI/Codex 等待上游响应头超时时间（秒，0=禁用本地响应头超时）
  openai_response_header_timeout: 0
  # Grok text Responses first-byte timeout (seconds, 0=disabled; default 120)
  # Grok 文本 Responses 首字节超时时间（秒，0=禁用；默认 120）
  grok_response_header_timeout: 120
  # Native OpenAI HTTP Responses first semantic output timeout (seconds, 0=disabled)
  # Includes response-header wait; does not apply to passthrough or WebSocket transports.
  # A timed-out request may already have incurred upstream usage; account failover can therefore duplicate upstream billing.
  # 超时请求可能已产生上游用量；切换账号重试可能导致上游重复计费。
  # Pre-output attempt staging is capped at 8 MiB; overflow fails over without exposing partial SSE data.
  # 首次输出前的单次尝试暂存上限为 8 MiB；溢出时切号且不暴露不完整 SSE 数据。
  openai_first_output_timeout_seconds: 0
  # Optional high/xhigh/max override (seconds, 0=use the standard timeout)
  openai_high_effort_first_output_timeout_seconds: 0
  # Max request body size in bytes (default: 256MB)
  # 请求体最大字节数（默认 256MB）
  max_body_size: 268435456
  # Pure-text endpoint body limit (embeddings and alpha/search), default 32 MiB.
  # 纯文本端点请求体上限（embeddings、alpha/search），默认 32 MiB。
  text_max_body_size: 33554432
  # Max bytes to read for non-stream upstream responses (default: 8MB)
  # 非流式上游响应体读取上限（默认 8MB）
  upstream_response_read_max_bytes: 8388608
  # Max bytes to read for upstream model-list responses (default: 8MB)
  # 上游模型列表响应体读取上限（默认 8MB）
  models_list_read_max_bytes: 8388608
  # Max bytes to read for proxy probe responses (default: 1MB)
  # 代理探测响应体读取上限（默认 1MB）
  proxy_probe_response_read_max_bytes: 1048576
  # Enable Gemini upstream response header debug logs (default: false)
  # 是否开启 Gemini 上游响应头调试日志（默认 false）
  gemini_debug_response_headers: false
  # Connection pool isolation strategy:
  # 连接池隔离策略：
  # - proxy: Isolate by proxy, same proxy shares connection pool (suitable for few proxies, many accounts)
  # - proxy: 按代理隔离，同一代理共享连接池（适合代理少、账户多）
  # - account: Isolate by account, same account shares connection pool (suitable for few accounts, strict isolation)
  # - account: 按账户隔离，同一账户共享连接池（适合账户少、需严格隔离）
  # - account_proxy: Isolate by account+proxy combination (default, finest granularity)
  # - account_proxy: 按账户+代理组合隔离（默认，最细粒度）
  connection_pool_isolation: "account_proxy"
  # Force Codex CLI mode: treat all /openai/v1/responses requests as Codex CLI.
  # 强制按 Codex CLI 处理 /openai/v1/responses 请求（用于网关未透传/改写 User-Agent 的兜底）。
  #
  # 注意：开启后会影响所有客户端的行为（不仅限于 VS Code / Codex CLI），请谨慎开启。
  force_codex_cli: false
  # Stop rewriting load-shed Codex originators to the official CLI identity.
  # 关闭「把落在上游降载桶的 Codex originator 改写为官方 CLI 身份（codex_cli_rs）」。
  #
  # 上游 /backend-api/codex 按 originator 分桶调度容量：命中降载桶的请求即使 HTTP 200，
  # 也会立刻推 server_is_overloaded 错误事件，网关据此判定瞬时上游故障并冷却账号，
  # 对外表现为 Codex 账号频繁过载不可用。归一化只替换身份段，保留版本/OS/架构/终端指纹，
  # 改写后 originator 与 User-Agent 首段仍然配套。
  #
  # 默认 false（即归一化开启）；仅当上游调整分桶、使归一化反而落入降载桶时才置 true。
  disable_codex_originator_normalization: false
  # Enable Codex image-generation bridge injection for /openai/v1/responses.
  # 是否为 Codex /responses 请求自动注入 image_generation 工具与桥接指令。
  #
  # Default false keeps text-only Codex requests text-only. Explicit client-provided
  # image_generation tools are still forwarded when the group allows image generation.
  # 默认 false：保持纯文本 Codex 请求不被改写；客户端显式提供 image_generation tool 时，
  # 仍会在分组允许图片生成的情况下正常转发。
  codex_image_generation_bridge_enabled: false
  # Optional: template file used to build the final top-level Codex `instructions`.
  # 可选：用于构建最终 Codex 顶层 `instructions` 的模板文件路径。
  #
  # This is applied on the `/v1/messages -> Responses/Codex` conversion path,
  # after Claude `system` has already been normalized into Codex `instructions`.
  # 该模板作用于 `/v1/messages -> Responses/Codex` 转换链路，且发生在 Claude `system`
  # 已经被归一化为 Codex `instructions` 之后。
  #
  # The template can reference:
  # 模板可引用：
  # - {{ .ExistingInstructions }} : converted client instructions/system
  # - {{ .OriginalModel }}        : original requested model
  # - {{ .NormalizedModel }}      : normalized routing model
  # - {{ .BillingModel }}         : billing model
  # - {{ .UpstreamModel }}        : final upstream model
  #
  # If you want to preserve client system prompts, keep {{ .ExistingInstructions }}
  # somewhere in the template. If omitted, the template output fully replaces it.
  # 如需保留客户端 system 提示词，请在模板中显式包含 {{ .ExistingInstructions }}。
  # 若省略，则模板输出会完全覆盖它。
  #
  # Docker users can mount a host file to /app/data/codex-instructions.md.tmpl
  # and point this field there.
  # Docker 用户可将宿主机文件挂载到 /app/data/codex-instructions.md.tmpl，
  # 然后把本字段指向该路径。
  forced_codex_instructions_template_file: ""
  # OpenAI 透传模式是否放行客户端超时头（如 x-stainless-timeout）
  # 默认 false：过滤超时头，降低上游提前断流风险。
  openai_passthrough_allow_timeout_headers: false
  # Model used for OpenAI /responses/compact upstream requests (default: gpt-5.4).
  # OpenAI /responses/compact 上游模型（默认 gpt-5.4）。
  # Use this to avoid compact failures when newer models are not yet supported by the compact endpoint.
  # 当 compact 端点暂未支持更新模型时，可通过这里降级规避失败。
  openai_compact_model: "gpt-5.4"
  # ChatGPT Frameless Live 单会话硬上限（秒）。
  live:
    max_session_duration_seconds: 3600
  # OpenAI Responses WebSocket 配置（默认开启，可按需回滚到 HTTP）
  openai_ws:
    # 新版 WS mode 路由（默认关闭）。关闭时忽略账号级 WS mode（包括 http_bridge），保持 legacy ctx_pool 行为。
    # 环境变量：GATEWAY_OPENAI_WS_MODE_ROUTER_V2_ENABLED=true
    mode_router_v2_enabled: false
    # ingress 默认模式：off|ctx_pool|passthrough|http_bridge（仅 mode_router_v2_enabled=true 生效；关闭时账号级 WS mode 被忽略）
    # 兼容旧值：shared/dedicated 会按 ctx_pool 处理。
    ingress_mode_default: ctx_pool
    # 完整读取并解压首条客户端消息的总超时（秒）；大请求或慢链路可调高到 120-300。
    client_first_message_timeout_seconds: 30
    # Close a client WebSocket that stays idle between completed turns (seconds). Set 0 to disable.
    ingress_inter_turn_idle_timeout_seconds: 300
    # Limit live client WebSocket ingress sessions per API key across all instances. Set 0 to disable.
    max_ingress_connections_per_api_key: 64
    # 全局总开关，默认 true；关闭时所有请求保持原有 HTTP/SSE 路由
    enabled: true
    # 按账号类型细分开关
    oauth_enabled: true
    apikey_enabled: true
    # 全局强制 OpenAI Responses 上游使用 HTTP/SSE，不使用 WebSocket（紧急回滚开关）。
    # 此开关不强制 HTTP/1.1；HTTP/2 由 gateway.openai_http2 单独控制。
    force_http: false
    # 允许在 WSv2 下按策略恢复 store=true（默认 false）
    allow_store_recovery: false
    # ingress 模式收到 previous_response_not_found 时，自动去掉 previous_response_id 重试一次（默认 true）
    ingress_previous_response_recovery_enabled: true
    # store=false 且无可复用会话连接时的策略：
    # strict=强制新建连接（隔离优先），adaptive=仅在高风险失败后强制新建，off=尽量复用（性能优先）
    store_disabled_conn_mode: strict
    # store=false 且无可复用会话连接时，是否强制新建连接（默认 true，优先会话隔离）
    # 兼容旧配置：仅在 store_disabled_conn_mode 未配置时生效
    store_disabled_force_new_conn: true
    # 是否启用 WSv2 generate=false 预热（默认 false）
    prewarm_generate_enabled: false
    # 协议 feature 开关，v2 优先于 v1
    responses_websockets: false
    responses_websockets_v2: true
    # 连接池参数（按账号池化复用）
    max_conns_per_account: 128
    min_idle_per_account: 4
    max_idle_per_account: 12
    # 是否按账号并发动态计算连接池上限：
    # effective_max_conns = min(max_conns_per_account, ceil(account.concurrency * factor))
    dynamic_max_conns_by_account_concurrency_enabled: true
    # 按账号类型分别设置系数（OAuth / API Key）
    oauth_max_conns_factor: 1.0
    apikey_max_conns_factor: 1.0
    dial_timeout_seconds: 10
    read_timeout_seconds: 900
    write_timeout_seconds: 120
    pool_target_utilization: 0.7
    queue_limit_per_conn: 64
    # 流式写出批量 flush 参数
    event_flush_batch_size: 1
    event_flush_interval_ms: 10
    # 预热触发冷却（毫秒）
    prewarm_cooldown_ms: 300
    # WS 回退到 HTTP 后的冷却时间（秒），用于避免 WS/HTTP 来回抖动；0 表示关闭冷却
    fallback_cooldown_seconds: 30
    # WS 重试退避参数（毫秒）
    retry_backoff_initial_ms: 120
    retry_backoff_max_ms: 2000
    # 抖动比例（0-1）
    retry_jitter_ratio: 0.2
    # 单次请求 WS 重试总预算（毫秒）；建议设置为有限值，避免重试拉高 TTFT 长尾
    retry_total_budget_ms: 5000
    # payload_schema 日志采样率（0-1）；降低热路径日志放大
    payload_log_sample_rate: 0.2
    # 调度与粘连参数
    lb_top_k: 7
    sticky_session_ttl_seconds: 3600
    # 会话哈希迁移兼容开关：新 key 未命中时回退读取旧 SHA-256 key
    session_hash_read_old_fallback: true
    # 会话哈希迁移兼容开关：写入时双写旧 SHA-256 key（短 TTL）
    session_hash_dual_write_old: true
    # context 元数据迁移兼容开关：保留旧 ctxkey.* 读取/注入桥接
    metadata_bridge_enabled: true
    sticky_response_id_ttl_seconds: 3600
    # 兼容旧键：当 sticky_response_id_ttl_seconds 缺失时回退该值
    sticky_previous_response_ttl_seconds: 3600
    scheduler_score_weights:
      priority: 1.0
      load: 1.0
      queue: 0.7
      error_rate: 0.8
      ttft: 0.5
      # use-it-or-lose-it：倾向「会话窗口最早重置」的账号，剩余重置时间越短得分越高。
      # 0 表示关闭（默认，不改变原有行为）；调大可让即将重置的账号被优先用尽。
      reset: 0.0
      # 倾向 7d 剩余额度更健康的账号；0 表示关闭（默认，不改变原有行为），小流量灰度可设为 0.3。
      quota_headroom: 0.0
      # 倾向上游声明倍率更低的账号；0 表示关闭（默认），建议启用时从 1.5 开始。
      upstream_cost: 0.0
  # OpenAI 高级调度器补充配置
  openai_scheduler:
    # 是否允许 session_hash sticky 在账号健康度恶化时临时逃逸；false 可一键回退旧行为
    sticky_escape_enabled: true
    # TTFT EWMA 超过该阈值（毫秒）时跳过 sticky，默认 15s，避免轻微抖动就逃逸
    sticky_escape_ttft_ms: 15000
    # 错误率 EWMA 超过该阈值时跳过 sticky，默认 0.5，仅在明显降级时触发
    sticky_escape_error_rate: 0.5
  # OpenAI HTTP upstream protocol strategy.
  # OpenAI HTTP 上游协议策略（默认 HTTP/2；代理明确不兼容时可临时回退 HTTP/1.1）。
  openai_http2:
    enabled: true
    allow_proxy_fallback_to_http1: true
    fallback_error_threshold: 2
    fallback_window_seconds: 60
    fallback_ttl_seconds: 600
  # OpenAI Responses SSE 代理断流熔断；按 proxy_id 跨账号隔离，仅影响下一次调度。
  # 隔离是偏好而非硬闸：当全部候选账号都在被隔离代理下时自动放行（fail-open），
  # 不会因熔断而返回"无可用账号"。3 秒内的并发断流合并为一次失败事件。
  openai_proxy_stream_circuit:
    disabled: false
    failure_threshold: 2
    window_seconds: 60
    ttl_seconds: 600
  # Grok free-tier local soft gate (scheduler filter only; admin QueryQuota/import probe bypasses it).
  # Enabled by default because free detection requires an explicit subscription_tier/plan_type of "free".
  # Stats/query failures fail open so DB issues do not block all Grok traffic.
  grok:
    # Email/password OAuth is off by default and hidden in the admin UI.
    # Setting true enables POST /admin/grok/oauth/password (password → SSO → Build OAuth).
    # Prefer SSO cookie, browser OAuth, or refresh_token re-auth in production.
    password_auth_enabled: false
    free_quota_soft_gate_enabled: true
    free_quota_token_limit: 500000
    free_quota_soft_gate_percent: 95
    free_quota_window_hours: 24
    # Stats cache for free-tier soft gate. Hot path never waits on DB: misses
    # fail open and refresh in the background. Prefer >= 60s in production.
    free_quota_stats_cache_seconds: 60
  # HTTP upstream connection pool settings (HTTP/2 + multi-proxy scenario defaults)
  # HTTP 上游连接池配置（HTTP/2 + 多代理场景默认值）
  # Max idle connections across all hosts
  # 所有主机的最大空闲连接数
  max_idle_conns: 2560
  # Max idle connections per host
  # 每个主机的最大空闲连接数
  max_idle_conns_per_host: 120
  # Max connections per host
  # 每个主机的最大连接数
  max_conns_per_host: 1024
  # Idle connection timeout (seconds)
  # 空闲连接超时时间（秒）
  idle_conn_timeout_seconds: 90
  # Upstream client cache settings
  # 上游连接池客户端缓存配置
  # max_upstream_clients: Max cached clients, evicts least recently used when exceeded
  # max_upstream_clients: 最大缓存客户端数量，超出后淘汰最久未使用的
  max_upstream_clients: 5000
  # client_idle_ttl_seconds: Client idle reclaim threshold (seconds), reclaimed when idle and no active requests
  # client_idle_ttl_seconds: 客户端空闲回收阈值（秒），超时且无活跃请求时回收
  client_idle_ttl_seconds: 900
  # Concurrency slot expiration time (minutes)
  # 并发槽位过期时间（分钟）
  concurrency_slot_ttl_minutes: 30
  # Stream data interval timeout (seconds), 0=disable
  # 流数据间隔超时（秒），0=禁用
  stream_data_interval_timeout: 180
  # Stream keepalive interval (seconds), 0=disable
  # 流式 keepalive 间隔（秒），0=禁用
  stream_keepalive_interval: 10
  # Image stream data interval timeout (seconds), 0=disable; independent from ordinary text streams
  # 图片流数据间隔超时（秒），0=禁用；独立于普通文本流式
  image_stream_data_interval_timeout: 900
  # Image stream keepalive interval (seconds), 0=disable; independent from ordinary text streams
  # 图片流式 keepalive 间隔（秒），0=禁用；独立于普通文本流式
  image_stream_keepalive_interval: 10
  # Non-streaming Images JSON keepalive interval (seconds), 0=disable; commits HTTP 200 after the first heartbeat
  # 图片非流式 JSON keepalive 间隔（秒），0=禁用；首个心跳后 HTTP 状态会固化为 200
  image_nonstream_keepalive_interval: 0
  # Image generation independent concurrency limiter (process-local, default disabled)
  # 图片生成独立并发限制（进程级，默认关闭；多实例总上限约为实例数×该值）
  image_concurrency:
    # Enable image-only concurrency protection; false keeps existing behavior unchanged
    # 是否启用图片独立并发保护；false 保持现有行为不变
    enabled: false
    # Max concurrent image generation requests in this process, 0=unlimited
    # 当前进程允许同时处理的图片生成请求数，0=不限制
    max_concurrent_requests: 0
    # Overflow mode when the image concurrency limit is full: reject/wait
    # 图片并发满时的处理方式：reject=立即拒绝，wait=等待槽位
    overflow_mode: "reject"
    # Wait timeout for overflow_mode=wait (seconds), 0=do not wait
    # wait 模式等待图片并发槽位的超时时间（秒），0=不等待
    wait_timeout_seconds: 30
    # Max image requests waiting in this process when overflow_mode=wait, 0=unlimited
    # wait 模式当前进程允许排队等待的图片请求数，0=不限制
    max_waiting_requests: 100
  # SSE max line size in bytes (default: 40MB)
  # SSE 单行最大字节数（默认 40MB）
  max_line_size: 41943040
  # Log upstream error response body summary (safe/truncated; does not log request content)
  # 记录上游错误响应体摘要（安全/截断；不记录请求内容）
  log_upstream_error_body: true
  # Max bytes to log from upstream error body
  # 记录上游错误响应体的最大字节数
  log_upstream_error_body_max_bytes: 2048
  # Auto inject anthropic-beta header for API-key accounts when needed (default: off)
  # 需要时自动为 API-key 账户注入 anthropic-beta 头（默认：关闭）
  inject_beta_for_apikey: false
  # Allow failover on selected 400 errors (default: off)
  # 允许在特定 400 错误时进行故障转移（默认：关闭）
  failover_on_400: false
  # Scheduling configuration
  # 调度配置
  scheduling:
    # Sticky session max waiting queue size
    # 粘性会话最大排队长度
    sticky_session_max_waiting: 3
    # Sticky session wait timeout (duration)
    # 粘性会话等待超时（时间段）
    sticky_session_wait_timeout: 120s
    # Fallback wait timeout (duration)
    # 兜底排队等待超时（时间段）
    fallback_wait_timeout: 30s
    # Fallback max waiting queue size
    # 兜底最大排队长度
    fallback_max_waiting: 100
    # Prefer the account whose session window resets soonest (use-it-or-lose-it).
    # 负载感知选择时优先用尽「会话窗口最早重置」的账号；false 保持
    # 原有「优先级 → 负载率 → LRU」行为（默认）。
    prefer_soonest_reset: false
    # Enable batch load calculation for scheduling
    # 启用调度批量负载计算
    load_batch_enabled: true
    # Tiny in-process TTL for batch load reads in milliseconds (0 disables)
    # 调度批量负载读取的进程内短缓存 TTL（毫秒，0 表示禁用）
    load_batch_cache_ttl_ms: 200
    # Slot cleanup interval (duration)
    # 并发槽位清理周期（时间段）
    slot_cleanup_interval: 30s
    # 是否允许受控回源到 DB（默认 true，保持现有行为）
    db_fallback_enabled: true
    # 受控回源超时（秒），0 表示不额外收紧超时
    db_fallback_timeout_seconds: 0
    # 受控回源限流（实例级 QPS），0 表示不限制
    db_fallback_max_qps: 0
    # outbox 轮询周期（秒）
    outbox_poll_interval_seconds: 1
    # outbox 滞后告警阈值（秒）
    outbox_lag_warn_seconds: 5
    # outbox 触发强制重建阈值（秒）
    outbox_lag_rebuild_seconds: 10
    # outbox 连续滞后触发次数
    outbox_lag_rebuild_failures: 3
    # outbox 积压触发重建阈值（行数）
    outbox_backlog_rebuild_rows: 10000
    # 全量重建周期（秒），0 表示禁用
    full_rebuild_interval_seconds: 300
  # TLS fingerprint simulation / TLS 指纹伪装
  # Default profile "claude_cli_v2" simulates Node.js 20.x
  # 默认模板 "claude_cli_v2" 模拟 Node.js 20.x 指纹
  tls_fingerprint:
    enabled: true
    # profiles:
    #   profile_1:
    #     name: "Custom Profile 1"
    #   profile_2:
    #     name: "Custom Profile 2"

# =============================================================================
# Logging Configuration
# 日志配置
# =============================================================================
log:
  # Log level: debug/info/warn/error
  # 日志级别：debug/info/warn/error
  level: "info"
  # Log format: json/console
  # 日志格式：json/console
  format: "console"
  # Service name field written into each log line
  # 每条日志都会附带 service 字段
  service_name: "sub2api"
  # Environment field written into each log line
  # 每条日志都会附带 env 字段
  env: "production"
  # Include caller information
  # 是否输出调用方位置信息
  caller: true
  # Stacktrace threshold: none/error/fatal
  # 堆栈输出阈值：none/error/fatal
  stacktrace_level: "error"
  output:
    # Keep stdout/stderr output for container log collection
    # 保持标准输出用于容器日志采集
    to_stdout: true
    # Enable file output (default path auto-derived)
    # 启用文件输出（默认路径自动推导）
    to_file: true
    # Empty means:
    # - DATA_DIR set: {{DATA_DIR}}/logs/sub2api.log
    # - otherwise: /app/data/logs/sub2api.log
    # 留空时：
    # - 设置 DATA_DIR：{{DATA_DIR}}/logs/sub2api.log
    # - 否则：/app/data/logs/sub2api.log
    file_path: ""
  rotation:
    # Max file size before rotation (MB)
    # 单文件滚动阈值（MB）
    max_size_mb: 100
    # Number of rotated files to keep (0 means unlimited)
    # 保留历史文件数量（0 表示不限制）
    max_backups: 10
    # Number of days to keep old log files (0 means unlimited)
    # 历史日志保留天数（0 表示不限制）
    max_age_days: 7
    # Compress rotated files
    # 是否压缩历史日志
    compress: true
    # Use local time for timestamp in rotated filename
    # 滚动文件名时间戳使用本地时区
    local_time: true
  sampling:
    # Enable zap sampler (reduce high-frequency repetitive logs)
    # 启用 zap 采样（减少高频重复日志）
    enabled: false
    # Number of first entries per second to always log
    # 每秒无采样保留的前 N 条日志
    initial: 100
    # Thereafter keep 1 out of N entries per second
    # 之后每 N 条保留 1 条
    thereafter: 100

# Token refresh behavior
# token 刷新行为控制
token_refresh:
  # Candidate accounts loaded per cursor page (maximum 1000)
  # 每个游标分页加载的候选账号数量（最大 1000）
  candidate_page_size: 200
  # Maximum concurrent refresh attempts per provider (maximum 32)
  # 每个平台的最大并发刷新数（最大 32）
  provider_concurrency: 4
  # Per-provider refresh requests per second in each server process (maximum 100)
  # 每个服务进程中每个平台每秒允许的刷新请求数（最大 100）
  provider_qps: 2
  # Consecutive transient failures that contain a provider for the current cycle (maximum 100)
  # 当前周期内触发平台级熔断的连续临时失败次数（最大 100）
  provider_failure_threshold: 3
  # Timeout for one upstream refresh attempt, in seconds (maximum 300)
  # 单次上游刷新尝试的超时时间（秒，最大 300）
  attempt_timeout_seconds: 15
  # Total timeout for one background refresh cycle, in seconds (maximum 3600)
  # 单个后台刷新周期的总超时时间（秒，最大 3600）
  cycle_timeout_seconds: 240

# =============================================================================
# API Key Auth Cache Configuration
# API Key 认证缓存配置
# =============================================================================
api_key_auth_cache:
  # L1 cache size (entries), in-process LRU/TTL cache
  # L1 缓存容量（条目数），进程内 LRU/TTL 缓存
  l1_size: 65535
  # L1 cache TTL (seconds)
  # L1 缓存 TTL（秒）
  l1_ttl_seconds: 15
  # L2 cache TTL (seconds), stored in Redis
  # L2 缓存 TTL（秒），Redis 中存储
  l2_ttl_seconds: 300
  # Negative cache TTL (seconds)
  # 负缓存 TTL（秒）
  negative_ttl_seconds: 30
  # TTL jitter percent (0-100)
  # TTL 抖动百分比（0-100）
  jitter_percent: 10
  # Enable singleflight for cache misses
  # 缓存未命中时启用 singleflight 合并回源
  singleflight: true
  # Maximum concurrent database lookups for authentication cache misses
  # 认证缓存未命中时允许并发回源数据库的最大数量
  lookup_concurrency: 64
  # Process-local invalid-auth abuse protection. Counts only missing, malformed,
  # deprecated-query, and confirmed invalid credentials; valid requests and
  # Redis/DB failures do not consume the budget.
  # 本机无效鉴权防护：仅统计缺失、格式错误、废弃 query 及确认无效的凭据。
  invalid_abuse:
    enabled: true
    # Invalid attempts per trusted client IP (IPv6 grouped by /64) per window.
    # 每个可信客户端 IP（IPv6 按 /64 聚合）在窗口内允许的无效次数。
    threshold: 120
    window_seconds: 60
    block_seconds: 60
    # Maximum tracked client identities per process; memory remains bounded.
    # 每进程最多跟踪的客户端身份数量，确保内存有界。
    capacity: 16384

# =============================================================================
# Dashboard Cache Configuration
# 仪表盘缓存配置
# =============================================================================
dashboard_cache:
  # Enable dashboard cache
  # 启用仪表盘缓存
  enabled: true
  # Redis key prefix for multi-environment isolation
  # Redis key 前缀，用于多环境隔离
  key_prefix: "sub2api:"
  # Fresh TTL (seconds); within this window cached stats are considered fresh
  # 新鲜阈值（秒）；命中后处于该窗口视为新鲜数据
  stats_fresh_ttl_seconds: 15
  # Cache TTL (seconds) stored in Redis
  # Redis 缓存 TTL（秒）
  stats_ttl_seconds: 30
  # Async refresh timeout (seconds)
  # 异步刷新超时（秒）
  stats_refresh_timeout_seconds: 30

# =============================================================================
# Dashboard Aggregation Configuration
# 仪表盘预聚合配置（重启生效）
# =============================================================================
dashboard_aggregation:
  # Enable aggregation job
  # 启用聚合作业
  enabled: true
  # Refresh interval (seconds)
  # 刷新间隔（秒）
  interval_seconds: 60
  # Lookback window (seconds) for late-arriving data
  # 回看窗口（秒），处理迟到数据
  lookback_seconds: 120
  # Allow manual backfill
  # 允许手动回填
  backfill_enabled: false
  # Backfill max range (days)
  # 回填最大跨度（天）
  backfill_max_days: 31
  # Recompute recent N days on startup
  # 启动时重算最近 N 天
  recompute_days: 2
  # Retention windows (days)
  # 保留窗口（天）
  retention:
    # Raw usage_logs retention
    # 原始 usage_logs 保留天数
    usage_logs_days: 90
    # Hourly aggregation retention
    # 小时聚合保留天数
    hourly_days: 180
    # Daily aggregation retention
    # 日聚合保留天数
    daily_days: 730

# =============================================================================
# Usage Cleanup Task Configuration
# 使用记录清理任务配置（重启生效）
# =============================================================================
usage_cleanup:
  # Enable cleanup task worker
  # 启用清理任务执行器
  enabled: true
  # Max date range (days) per task
  # 单次任务最大时间跨度（天）
  max_range_days: 31
  # Batch delete size
  # 单批删除数量
  batch_size: 5000
  # Worker interval (seconds)
  # 执行器轮询间隔（秒）
  worker_interval_seconds: 10
  # Task execution timeout (seconds)
  # 单次任务最大执行时长（秒）
  task_timeout_seconds: 1800

# =============================================================================
# HTTP 写接口幂等配置
# Idempotency Configuration
# =============================================================================
idempotency:
  # Observe-only 模式：
  # true: 观察期，不带 Idempotency-Key 仍放行（但会记录）
  # false: 强制期，不带 Idempotency-Key 直接拒绝（仅对接入幂等保护的接口生效）
  observe_only: true
  # 关键写接口幂等记录 TTL（秒）
  default_ttl_seconds: 86400
  # 系统操作接口（update/rollback/restart）幂等记录 TTL（秒）
  system_operation_ttl_seconds: 3600
  # processing 锁超时（秒）
  processing_timeout_seconds: 30
  # 可重试失败退避窗口（秒）
  failed_retry_backoff_seconds: 5
  # 持久化响应体最大长度（字节）
  max_stored_response_len: 65536
  # 过期幂等记录清理周期（秒）
  cleanup_interval_seconds: 60
  # 每轮清理最大删除条数
  cleanup_batch_size: 500

# =============================================================================
# Concurrency Wait Configuration
# 并发等待配置
# =============================================================================
concurrency:
  # SSE ping interval during concurrency wait (seconds)
  # 并发等待期间的 SSE ping 间隔（秒）
  ping_interval: 10

# =============================================================================
# Database Configuration (PostgreSQL)
# 数据库配置 (PostgreSQL)
# =============================================================================
database:
  # Database host address
  # 数据库主机地址
  host: "localhost"
  # Database port
  # 数据库端口
  port: 5432
  # Database username
  # 数据库用户名
  user: "postgres"
  # Database password
  # 数据库密码
  password: "your_secure_password_here"
  # Database name
  # 数据库名称
  dbname: "sub2api"
  # SSL mode: disable, prefer, require, verify-ca, verify-full
  # SSL 模式：disable（禁用）, prefer（优先加密，默认）, require（要求）, verify-ca（验证CA）, verify-full（完全验证）
  # 默认值为 "prefer"，数据库支持 SSL 时自动使用加密连接，不支持时回退明文
  sslmode: "prefer"
  # Max open connections (高并发场景建议 256+，需配合 PostgreSQL max_connections 调整)
  # 最大打开连接数
  max_open_conns: 256
  # Max idle connections (建议为 max_open_conns 的 50%，减少频繁建连开销)
  # 最大空闲连接数
  max_idle_conns: 128
  # Connection max lifetime (minutes)
  # 连接最大存活时间（分钟）
  conn_max_lifetime_minutes: 30
  # Connection max idle time (minutes)
  # 空闲连接最大存活时间（分钟）
  conn_max_idle_time_minutes: 5

# =============================================================================
# Redis Configuration
# Redis 配置
# =============================================================================
redis:
  # Redis host address
  # Redis 主机地址
  host: "localhost"
  # Redis port
  # Redis 端口
  port: 6379
  # Redis ACL username (leave empty for default user)
  # Redis ACL 用户名（使用默认用户时留空）
  username: ""
  # Redis password (leave empty if no password is set)
  # Redis 密码（如果未设置密码则留空）
  password: ""
  # Database number (0-15)
  # 数据库编号（0-15）
  db: 0
  # Connection pool size (max concurrent connections)
  # 连接池大小（最大并发连接数）
  pool_size: 1024
  # Minimum number of idle connections (高并发场景建议 128+，保持足够热连接)
  # 最小空闲连接数
  min_idle_conns: 128
  # Enable TLS/SSL connection
  # 是否启用 TLS/SSL 连接
  enable_tls: false

# =============================================================================
# Ops Monitoring (Optional)
# 运维监控 (可选)
# =============================================================================
ops:
  # Enable ops monitoring features (background jobs and APIs)
  # 是否启用运维监控功能（后台任务和接口）
  # Set to false to hide ops menu in sidebar and disable all ops features
  # 设置为 false 可在左侧栏隐藏运维监控菜单并禁用所有运维监控功能
  # Other detailed settings (cleanup, aggregation, etc.) are configured in ops settings dialog
  # 其他详细设置（数据清理、预聚合等）在运维监控设置对话框中配置
  enabled: true

# =============================================================================
# JWT Configuration
# JWT 配置
# =============================================================================
jwt:
  # IMPORTANT: Change this to a random string in production!
  # 重要：生产环境中请更改为随机字符串！
  # Generate with / 生成命令: openssl rand -hex 32
  secret: "change-this-to-a-secure-random-string"
  # Token expiration time in hours (max 168)
  # 令牌过期时间（小时，最大 168）
  expire_hour: 24
  # Access Token 过期时间（分钟）
  # 优先级说明：
  # - >0: 按分钟生效（优先于 expire_hour）
  # - =0: 回退使用 expire_hour
  access_token_expire_minutes: 0

# =============================================================================
# TOTP (2FA) Configuration
# TOTP 双因素认证配置
# =============================================================================
totp:
  # IMPORTANT: Set a fixed encryption key for TOTP secrets.
  # 重要：设置固定的 TOTP 加密密钥。
  # If left empty, a random key will be generated on each startup, causing all
  # existing TOTP configurations to become invalid (users won't be able to
  # login with 2FA).
  # 如果留空，每次启动将生成随机密钥，导致现有的 TOTP 配置失效（用户无法使用
  # 双因素认证登录）。
  # Generate with / 生成命令: openssl rand -hex 32
  encryption_key: ""

# =============================================================================
# LinuxDo Connect OAuth Login (SSO)
# LinuxDo Connect OAuth 登录（用于 Sub2API 用户登录）
# =============================================================================
linuxdo_connect:
  enabled: false
  client_id: ""
  client_secret: ""
  authorize_url: "https://connect.linux.do/oauth2/authorize"
  token_url: "https://connect.linux.do/oauth2/token"
  userinfo_url: "https://connect.linux.do/api/user"
  scopes: "user"
  # 示例: "https://your-domain.com/api/v1/auth/oauth/linuxdo/callback"
  redirect_url: ""
  # 安全提示：
  # - 建议使用同源相对路径（以 / 开头），避免把 token 重定向到意外的第三方域名
  # - 该地址不应包含 #fragment（本实现使用 URL fragment 传递 access_token）
  frontend_redirect_url: "/auth/linuxdo/callback"
  token_auth_method: "client_secret_post" # client_secret_post | client_secret_basic | none
  # 注意：当 token_auth_method=none（public client）时，必须启用 PKCE
  use_pkce: true
  userinfo_email_path: ""
  userinfo_id_path: ""
  userinfo_username_path: ""

# =============================================================================
# Generic OIDC OAuth Login (SSO)
# 通用 OIDC OAuth 登录（用于 Sub2API 用户登录）
# =============================================================================
oidc_connect:
  enabled: false
  provider_name: "OIDC"
  client_id: ""
  client_secret: ""
  # 例如: "https://keycloak.example.com/realms/myrealm"
  issuer_url: ""
  # 可选: OIDC Discovery URL。为空时可手动填写 authorize/token/userinfo/jwks
  discovery_url: ""
  authorize_url: ""
  token_url: ""
  # 可选（仅补充 email/username，不用于 sub 可信绑定）
  userinfo_url: ""
  # validate_id_token=true 时必填
  jwks_url: ""
  scopes: "openid email profile"
  # 示例: "https://your-domain.com/api/v1/auth/oauth/oidc/callback"
  redirect_url: ""
  # 安全提示：
  # - 建议使用同源相对路径（以 / 开头），避免把 token 重定向到意外的第三方域名
  # - 该地址不应包含 #fragment（本实现使用 URL fragment 传递 access_token）
  frontend_redirect_url: "/auth/oidc/callback"
  token_auth_method: "client_secret_post" # client_secret_post | client_secret_basic | none
  # 注意：当 token_auth_method=none（public client）时，必须启用 PKCE
  use_pkce: false
  # 开启后强制校验 id_token 的签名和 claims（推荐）
  validate_id_token: true
  allowed_signing_algs: "RS256,ES256,PS256"
  # 允许的时钟偏移（秒）
  clock_skew_seconds: 120
  # 若 Provider 返回 email_verified=false，是否拒绝登录
  require_email_verified: false
  userinfo_email_path: ""
  userinfo_id_path: ""
  userinfo_username_path: ""

# =============================================================================
# Default Settings
# 默认设置
# =============================================================================
default:
  # Initial admin account (created on first run)
  # 初始管理员账户（首次运行时创建）
  admin_email: "admin@example.com"
  admin_password: "admin123"

  # Default settings for new users
  # 新用户默认设置
  # Max concurrent requests per user
  # 每用户最大并发请求数
  user_concurrency: 5
  # Initial balance for new users
  # 新用户初始余额
  user_balance: 0

  # API key settings
  # API 密钥设置
  # Prefix for generated API keys
  # 生成的 API 密钥前缀
  api_key_prefix: "sk-"

  # Rate multiplier (affects billing calculation)
  # 费率倍数（影响计费计算）
  rate_multiplier: 1.0

# =============================================================================
# Rate Limiting
# 速率限制
# =============================================================================
rate_limit:
  # Cooldown time (in minutes) when upstream returns 529 (overloaded)
  # 上游返回 529（过载）时的冷却时间（分钟）
  overload_cooldown_minutes: 10

# =============================================================================
# Local OAuth Transport Plugins (Optional)
# 本地 OAuth 出站传输插件（可选）
# =============================================================================
plugins:
  # Empty means {{DATA_DIR}}/plugins, or ./data/plugins when DATA_DIR is unset.
  # 留空时使用 {{DATA_DIR}}/plugins；未设置 DATA_DIR 时使用 ./data/plugins。
  data_dir: ""
  # Keep false in production. Enable only for local development packages you built yourself.
  # 生产环境应保持 false；仅调试自己构建的本地插件时临时开启。
  allow_unsigned: false
  # Additional Ed25519 public keys indexed by signature.json key_id.
  # OpenAI Transport's public key is built in; this map only adds third-party publishers.
  # 以 signature.json 中 key_id 为索引的额外 Ed25519 公钥。
  # OpenAI Transport 公钥已内置，此处只需添加第三方发布者。
  trusted_publishers: {}
  max_upload_bytes: 134217728
  max_uncompressed_bytes: 268435456
  start_timeout_seconds: 15

# =============================================================================
# Pricing Data Source (Optional)
# 定价数据源（可选）
# =============================================================================
pricing:
  # URL to fetch model pricing data (default: model-price-repo main branch)
  # 获取模型定价数据的 URL（默认：model-price-repo main 分支）
  remote_url: "https://raw.githubusercontent.com/Wei-Shaw/model-price-repo/refs/heads/main//model_prices_and_context_window.json"
  # Hash verification URL (optional)
  # 哈希校验 URL（可选）
  hash_url: "https://raw.githubusercontent.com/Wei-Shaw/model-price-repo/refs/heads/main//model_prices_and_context_window.sha256"
  # Local data directory for caching
  # 本地数据缓存目录
  data_dir: "./data"
  # Fallback pricing file: fills in models missing from the catalog. Edits are
  # detected by content hash at the next hash check and reloaded without restart.
  # 备用定价文件：只补目录缺失的模型。修改后在下一次哈希检查时按内容哈希自动重载，无需重启。
  fallback_file: "./resources/model-pricing/model_prices_and_context_window.json"
  # Override patch file (optional, highest priority): entries are shallow-merged
  # field-by-field over catalog/fallback data; a null field value removes that field.
  # Model names must match catalog keys exactly. Edits are detected by content hash
  # at the next hash check and reloaded without restart.
  # 覆盖补丁文件（可选，优先级最高）：条目按字段浅合并覆盖目录/回退数据，
  # 字段值为 null 表示删除该字段。模型名须与目录键完全一致。
  # 修改后在下一次哈希检查时按内容哈希自动重载，无需重启。
  # override_file: "./data/model_pricing_overrides.json"
  # Update interval in hours
  # 更新间隔（小时）
  update_interval_hours: 24
  # Hash check interval in minutes. Each check compares the remote catalog hash and
  # the local fallback/override file contents. Deleting a local file drops its
  # entries at the next check; a present but non-JSON file keeps the previous data
  # and is retried next check.
  # 哈希检查间隔（分钟）。每次检查同时比对远程目录哈希与本地 fallback/override 文件内容；
  # 删除本地文件会在下次检查时移除其条目，文件存在但不是 JSON 时保留旧数据、下次检查再试。
  hash_check_interval_minutes: 10

# =============================================================================
# Billing Configuration
# 计费配置
# =============================================================================
billing:
  circuit_breaker:
    # Enable circuit breaker for billing service
    # 启用计费服务熔断器
    enabled: true
    # Number of failures before opening circuit
    # 触发熔断的失败次数阈值
    failure_threshold: 5
    # Time to wait before attempting reset (seconds)
    # 熔断后重试等待时间（秒）
    reset_timeout_seconds: 30
    # Number of requests to allow in half-open state
    # 半开状态允许通过的请求数
    half_open_requests: 3
  # Conservative minimum balance required before forwarding balance-billed requests.
  # Set to 0 to only require balance > 0.
  # 余额计费请求转发前要求的保守最小余额；设为 0 则仅要求余额 > 0。
  minimum_balance_reserve: 0.000001
  # Cache TTL (seconds) for per-user × per-platform quota records
  # 用户 × 平台 quota 缓存 TTL（秒），默认 86400=1天，覆盖典型 daily 窗口
  user_platform_quota_cache_ttl_seconds: 86400

# =============================================================================
# Turnstile Configuration
# Turnstile 人机验证配置
# =============================================================================
turnstile:
  # Require Turnstile in release mode (when enabled, login/register will fail if not configured)
  # 在 release 模式下要求 Turnstile 验证（启用后，若未配置则登录/注册会失败）
  required: false

# =============================================================================
# Gemini OAuth (Required for Gemini accounts)
# Gemini OAuth 配置（Gemini 账户必需）
# =============================================================================
# Sub2API supports TWO Gemini OAuth modes:
# Sub2API 支持两种 Gemini OAuth 模式：
#
# 1. Code Assist OAuth (requires GCP project_id)
# 1. Code Assist OAuth（需要 GCP project_id）
#    - Uses: cloudcode-pa.googleapis.com (Code Assist API)
#    - 使用：cloudcode-pa.googleapis.com（Code Assist API）
#
# 2. AI Studio OAuth (no project_id needed)
# 2. AI Studio OAuth（不需要 project_id）
#    - Uses: generativelanguage.googleapis.com (AI Studio API)
#    - 使用：generativelanguage.googleapis.com（AI Studio API）
#
# Default: Uses Gemini CLI's public OAuth credentials (same as Google's official CLI tool)
# 默认：使用 Gemini CLI 的公开 OAuth 凭证（与 Google 官方 CLI 工具相同）
gemini:
  oauth:
    # OAuth 客户端配置说明：
    # 1) 留空 client_id/client_secret：使用 Gemini CLI 内置 OAuth Client（其 client_secret 需通过环境变量注入）
    #    - GEMINI_CLI_OAUTH_CLIENT_SECRET
    # 2) 同时设置 client_id/client_secret：使用你自建的 OAuth Client（推荐，权限更完整）
    #
    # 注意：client_id 与 client_secret 必须同时为空或同时非空。
    client_id: ""
    client_secret: ""
    # Optional scopes (space-separated). Leave empty to auto-select based on oauth_type.
    # 可选的权限范围（空格分隔）。留空则根据 oauth_type 自动选择。
    scopes: ""
  quota:
    # Optional: local quota simulation for Gemini Code Assist (local billing).
    # 可选：Gemini Code Assist 本地配额模拟（本地计费）。
    # These values are used for UI progress + precheck scheduling, not official Google quotas.
    # 这些值用于 UI 进度显示和预检调度，并非 Google 官方配额。
    tiers:
      LEGACY:
        # Pro model requests per day
        # Pro 模型每日请求数
        pro_rpd: 50
        # Flash model requests per day
        # Flash 模型每日请求数
        flash_rpd: 1500
        # Cooldown time (minutes) after hitting quota
        # 达到配额后的冷却时间（分钟）
        cooldown_minutes: 30
      PRO:
        # Pro model requests per day
        # Pro 模型每日请求数
        pro_rpd: 1500
        # Flash model requests per day
        # Flash 模型每日请求数
        flash_rpd: 4000
        # Cooldown time (minutes) after hitting quota
        # 达到配额后的冷却时间（分钟）
        cooldown_minutes: 5
      ULTRA:
        # Pro model requests per day
        # Pro 模型每日请求数
        pro_rpd: 2000
        # Flash model requests per day (0 = unlimited)
        # Flash 模型每日请求数（0 = 无限制）
        flash_rpd: 0
        # Cooldown time (minutes) after hitting quota
        # 达到配额后的冷却时间（分钟）
        cooldown_minutes: 5

# =============================================================================
# Update Configuration (在线更新配置)
# =============================================================================
update:
  # Proxy URL for accessing GitHub (used for online updates and pricing data)
  # 用于访问 GitHub 的代理地址（用于在线更新和定价数据获取）
  # Supports: http, https, socks5, socks5h
  # Examples:
  #   - HTTP proxy: "http://127.0.0.1:7890"
  #   - SOCKS5 proxy: "socks5://127.0.0.1:1080"
  #   - With authentication: "http://user:pass@proxy.example.com:8080"
  # Leave empty for direct connection (recommended for overseas servers)
  # 留空表示直连（适用于海外服务器）
  proxy_url: ""

# =============================================================================
# Image Storage (异步图片任务结果对象存储)
# =============================================================================
# 长耗时生图套 Cloudflare 会 524 超时，异步图片任务接口（/v1/images/generations/async
# 等）先返回 task_id，再由客户端轮询 /v1/images/tasks/{task_id} 获取结果。
#
# 这里配置一个 S3 兼容对象存储（AWS S3 / Cloudflare R2 / 阿里云 OSS / MinIO 等），
# 任务完成后把生成的图片上传到对象存储，只在 Redis 存一个短链接，避免 gpt-image-1 等
# 返回的大 base64 结果把 Redis 撑爆。
#
# enabled 同时是异步图片任务功能的总开关：为 false 或凭证未配全时，异步生图接口
# 整体返回 404、不创建任务、不写 Redis。
#
# 换其它厂商对象存储：只要它兼容 S3 API 即可直接用；如需完全自定义，实现
# service.ImageStorage 接口（Save(ctx, key, contentType, data) -> url）即可。
image_storage:
  enabled: false
  # S3 兼容端点。AWS 官方可留空；R2 形如 https://<account_id>.r2.cloudflarestorage.com
  endpoint: ""
  # 区域。Cloudflare R2 用 "auto"
  region: "auto"
  bucket: ""
  access_key_id: ""
  secret_access_key: ""
  # 对象 key 前缀
  prefix: "images/"
  # MinIO / 需要路径风格（path-style）访问的桶设为 true
  force_path_style: false
  # 若填写公开桶 / CDN 域名，则返回 public_base_url/key 永久直链；
  # 留空则返回带过期时间的 presigned 临时链接
  public_base_url: ""
  # public_base_url 为空时，presigned 链接的有效时长（小时）
  presign_expiry_hours: 24
  # 当上游返回的是图片 url 时，下载该图片再转存的字节上限（默认 32MB）
  max_download_bytes: 33554432