deploy/config.example.yaml
Rama main · réplica de lectura del repositorio original.
# 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"
simple_mode:
# 仅控制简易模式启动时补齐默认分组；false 不删除已有分组，不改变运行时自动绑定或管理员并发设置。
# 环境变量：SIMPLE_MODE_AUTO_CREATE_DEFAULT_GROUPS
auto_create_default_groups: true
# Enforce API-key 5h/1d/7d spending windows in simple mode; other billing stays disabled.
simple_mode_key_rate_limit_enabled: false
# =============================================================================
# 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
# =============================================================================
# MCP OAuth Configuration / MCP OAuth 配置
# =============================================================================
mcp:
# Canonical public MCP endpoint, e.g. https://example.com/api/v1/mcp.
# 固定的 MCP 对外地址，例如 https://example.com/api/v1/mcp。
# Leave empty to keep the management MCP and its OAuth endpoints disabled (default).
# 留空则关闭 MCP 及其 OAuth 接口（默认），不会回落到前端地址或请求中的 Host。
# HTTPS is required except localhost/loopback development; site-root /api/v1/mcp path, no trailing slash.
# 除 localhost/回环 IP 开发环境外必须使用 HTTPS；路径固定为站点根下的 /api/v1/mcp，末尾不加斜杠。
# Environment / 环境变量: MCP_PUBLIC_URL
public_url: ""
# =============================================================================
# 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"
- "opencode.ai"
- "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:
# Minimum max_output_tokens when converting Chat Completions or Anthropic requests to Responses (minimum 16, default 128)
# Chat Completions 或 Anthropic 请求转换为 Responses 时的最小 max_output_tokens（最小 16，默认 128）
min_output_tokens: 128
# 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
# Opt out of the fixed 10-minute account cooldown for persistent OpenAI transport failures (DNS/proxy/network).
# Env: GATEWAY_DISABLE_OPENAI_TRANSPORT_ERROR_COOLDOWN=true; default false retains protection.
# Errors/Ops and bounded request failover remain; HTTP 401/403/429, quota/model limits,
# stream timeouts and token-refresh cooldowns are unchanged. Existing cooldowns and admin pauses are not cleared.
# With shared egress still broken, later requests retry it: this does not repair DNS/proxies or guarantee faster models.
disable_openai_transport_error_cooldown: false
# 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
# Per-instance ingress allocation budget. Unreferenced intermediates are released after each phase.
# Final bodies (and still-referenced preread buffers) remain charged until the handler returns.
# Include all concurrent long-lived requests and upload/decode workspace; see EDGE_SECURITY.md.
# Unset (default): 1/4 of the memory limit (min of RAM, cgroup limit, GOMEMLIMIT), at least 1 GiB.
# 实例级请求体分配预算；超出返回 503 + Retry-After，0 禁用。
# 不配置时自动取内存上限（物理内存/cgroup 限额/GOMEMLIMIT 的最小值）的 1/4，最低 1GiB；显式配置后不再自适应。
# request_body_memory_budget_bytes: 1073741824
# Individual socket read/write idle deadlines, not the entire SSE lifetime; 0 disables.
# 上传单次读取、下游单次写入/flush 超时（秒），不会限制正常长流的总时长；0 禁用。
request_body_read_timeout_seconds: 120
downstream_write_timeout_seconds: 120
# 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
# Maximum TTL (seconds) a Gemini explicit context cache may be created or extended to (default: 86400)
# Gemini 显式上下文缓存单次可设置的最长有效期（秒，默认 86400）；存储费在创建/延长请求中一次性收取
gemini_cached_content_max_ttl_seconds: 86400
# 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.5).
# OpenAI /responses/compact 上游模型（默认 gpt-5.5）。
# Use this to avoid compact failures when newer models are not yet supported by the compact endpoint.
# 当 compact 端点暂未支持更新模型时，可通过这里降级规避失败。
# GPT-5.5 is API-only after its ChatGPT Codex retirement; subscription
# requests skip this retired fallback and keep their selected model.
openai_compact_model: "gpt-5.5"
# 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))
# 旧版及 mode_router_v2 的 ctx_pool 共用此开关和下方类型系数；关闭后使用 max_conns_per_account。
# mode_router_v2 下并发数 <= 0 的账号仍不可调度。
dynamic_max_conns_by_account_concurrency_enabled: true
# 按账号类型分别设置系数（OAuth / API Key）。
# ctx_pool 接入下每个客户端会话在整个生命周期（轮次之间也不释放）持有一条上游连接，
# 该上限限制的是同时持有连接的会话数，在飞请求数另由账号并发限制；
# 系数 1.0 会让存活会话数一到并发数，新会话就收到 1013 upstream websocket is busy。
# 空闲连接数另受 max_idle_per_account 裁剪。
oauth_max_conns_factor: 5.0
apikey_max_conns_factor: 5.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: 500 MiB, including large inline 4K images)
# SSE 单行最大字节数（默认 500 MiB，兼容含大尺寸 4K 图片的响应）
max_line_size: 524288000
# Queue byte budget. One larger line may be transferred alone, bounded by max_line_size.
# 队列按字节限流；超过预算的单行只能独占传递，仍受 max_line_size 硬上限约束。
sse_queue_max_bytes: 8388608
# Accumulated event byte limit (0 inherits max_line_size) and nonempty line limit.
# 事件累计字节上限（0 继承单行上限）与行数上限；持续短行也不能无界积累。
sse_event_max_bytes: 0
sse_event_max_lines: 4096
# 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
# =============================================================================
# API Key Creation Limits
# 用户创建 API Key 的防滥用限制（0 表示不限制）
# =============================================================================
api_key_create:
# Maximum non-deleted API keys per user
# 单个用户同时存在（未删除）的 API Key 上限
max_active_per_user: 200
# Maximum API key creations per user per hour (custom and generated keys).
# Deleting a key does not refund the count, which blocks delete/recreate loops.
# 单个用户每小时可创建的 API Key 次数（自定义与自动生成均计入）；删除 Key 不返还次数，阻断删建循环
max_per_user_per_hour: 60
# =============================================================================
# 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 表示删除该字段。模型名须与目录键完全一致。
# 修改后在下一次哈希检查时按内容哈希自动重载，无需重启。
# Gemini explicit context caching storage price (USD per token per hour) comes
# from the field cache_storage_cost_per_token_per_hour here, e.g.
# {"gemini-3.8-flash": {"cache_storage_cost_per_token_per_hour": 0.0000005}};
# without it, built-in official prices apply (released models first, then the
# Pro / Flash series rate). Models with no price at all reject POST /v1beta/cachedContents.
# Gemini 显式缓存存储单价（每 token 每小时，USD）优先取这里的 cache_storage_cost_per_token_per_hour 字段，
# 未配置时使用内置官方价（先按已发布型号，再按 Pro / Flash 系列兜底）；两者都没有的模型拒绝创建缓存。
# 目录中不存在的模型条目还须同时提供 input_cost_per_token / output_cost_per_token。
# 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
# In-flight balance reservation (Redis): at admission, estimate per-request cost
# (input estimate + output price x max_tokens) and atomically require
# cached_balance - in-flight reservations >= estimate. Released when the request ends.
# The first in-flight request of a user is always admitted (same as before).
# Fails open when the estimate cannot be computed or Redis is unavailable.
# 余额模式在途预留：准入时估算单请求费用，要求 缓存余额 - 在途预留合计 >= 估算；
# 用户无在途请求时始终放行（与旧行为一致）；估算失败/Redis 不可用时 fail-open。
inflight_reservation:
enabled: true
# Reservation TTL. Renewed every ttl/3 while the request is running; after the
# handler returns it is held (not renewed) until the async billing task has
# deducted the cached balance, so a stuck billing task frees it after at most one TTL.
# 预留 TTL（秒）。请求进行中每 ttl/3 续期；请求结束后不再续期，保持到异步计费
# 扣减余额缓存后释放，计费任务卡死时最多一个 TTL 后自动失效
ttl_seconds: 900
# Output tokens assumed when the request has no max_tokens
# 请求未携带 max_tokens 时假定的输出 token 数
default_max_tokens: 8192
# Cap for estimated output / input tokens
# 估算输出 / 输入 token 上限
max_output_tokens: 128000
max_input_tokens: 200000
# Cap for a single reservation in USD (0 = no cap)
# 单请求预留金额上限（USD，0 为不设上限）
max_reservation_usd: 0
# When a request cannot be priced (no base / group / channel pricing for the
# billing model), reject it instead of admitting it without reservation.
# 无法为请求定价（计费模型无基础/分组/渠道定价）时拒绝请求；默认 false 为放行不预留（节流告警日志）
fail_closed_on_unpriced: false
# =============================================================================
# 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