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:

enabled: false

rp_display_name: "Sub2API"

# Example / 示例: "sub2api.example.com"

rp_id: ""

# Example / 示例: ["https://sub2api.example.com"]

rp_origins: []

run_mode: "standard"

simple_mode:

# 仅控制简易模式启动时补齐默认分组；false 不删除已有分组，不改变运行时自动绑定或管理员并发设置。

# 环境变量：SIMPLE_MODE_AUTO_CREATE_DEFAULT_GROUPS

auto_create_default_groups: true

simple_mode_key_rate_limit_enabled: false

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:

# 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:

# 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.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 端点暂未支持更新模型时，可通过这里降级规避失败。

openai_compact_model: "gpt-5.5"

# ChatGPT OAuth x-codex-turn-state ticket: harvest a 292-length header via a

# dedicated HTTP(S)/SOCKS proxy, store it for ttl_seconds (default 3600), then inject

# it on residential-IP production requests. Off by default.

# ChatGPT OAuth 门票：用独立 HTTP(S)/SOCKS 代理打到 292 长度的 x-codex-turn-state，默认缓存 1 小时，

# 再在住宅 IP 业务请求中覆盖该头。默认关闭。

# Env: GATEWAY_OPENAI_CODEX_TICKET_ENABLED=true

# GATEWAY_OPENAI_CODEX_TICKET_HARVEST_PROXY_URL=socks5h://user:pass@host:port

# Admin UI 开关（系统设置 → 网关 → Codex 设置 → 292 打票）可覆盖 enabled，无需重启。

# Off: do not harvest or inject. On: harvest in the background and inject on production requests.

# The harvest proxy should rotate egress IPs itself (fresh CONNECT per request).

# Credential shadow accounts retain their existing forwarding policy and are not ticket-gated.

openai_codex_ticket:

# Disabled by default. Enable manually in admin settings when needed.

enabled: false

target_length: 292

ttl_seconds: 3600

refresh_before_seconds: 600

# 后台「系统设置 → 网关 → Codex 设置」可覆盖此值，无需重启。

# 后台值的读取缓存为 5 秒，下个探测周期使用新代理；代理服务商自行负责轮换 IP。

harvest_proxy_url: ""

harvest_probe_interval_seconds: 6

harvest_attempt_timeout_seconds: 25

# Missing tickets are allowed by default. Explicit global/account policies still apply.

fail_closed: false

models:

- gpt-6-astra

- gpt-5.6-sol

# 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: 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"

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:

# 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:

# 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_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:

# 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:

# 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:

# 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

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:

# SSE ping interval during concurrency wait (seconds)

# 并发等待期间的 SSE ping 间隔（秒）

ping_interval: 10

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:

# 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:

# 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:

# 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:

# 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:

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）