配置方式与关键参数

Sub2API 可以从默认值、YAML 和环境变量读取配置。管理后台还有一部分数据库运行时设置。

如果你不确定某个值最终保存在环境变量、PostgreSQL、Redis 还是进程内存，先读启动、配置与事实来源。特别注意：ADMIN_PASSWORD 仅用于首次创建管理员，不会持续覆盖数据库密码。

配置优先级

环境变量
   ↓ 覆盖
config.yaml
   ↓ 覆盖
程序内置默认值

环境变量名称由配置路径转换：点号改为下划线并大写。

gateway.max_body_size            → GATEWAY_MAX_BODY_SIZE
database.max_open_conns          → DATABASE_MAX_OPEN_CONNS
security.url_allowlist.enabled   → SECURITY_URL_ALLOWLIST_ENABLED

配置文件搜索

不同安装方式常见位置：

安装方式	配置位置
Docker	/app/data/config.yaml，宿主机挂载 ./data
systemd 二进制	/etc/sub2api/config.yaml
源码	当前工作目录、./data 或显式环境变量

Docker 的 .env 不是应用直接读取的 YAML，而是 Compose 用来替换变量并传进容器。

服务器

server:
  host: 127.0.0.1
  port: 8080
  mode: release
  frontend_url: https://api.example.com
  trusted_proxies:
    - 127.0.0.1/32
  max_request_body_size: 268435456

• frontend_url 用于邮件和外部链接，应为最终 HTTPS 地址。
• 同机反向代理建议 host 使用 127.0.0.1；Docker 端口映射场景容器内部仍监听 0.0.0.0。
• trusted proxies 只包含实际代理，不要使用 0.0.0.0/0。

运行模式

RUN_MODE=standard

simple 会跳过计费和余额检查，只适合可信内部环境。公开部署必须使用 standard。

PostgreSQL

database:
  host: postgres
  port: 5432
  user: sub2api
  password: change-me
  dbname: sub2api
  sslmode: disable
  max_open_conns: 100
  max_idle_conns: 25
  conn_max_lifetime_minutes: 30
  conn_max_idle_time_minutes: 5

跨主机或托管数据库使用 require、verify-ca 或 verify-full，并根据服务商配置 CA。不要在公网使用 disable。

Redis

redis:
  host: redis
  port: 6379
  password: change-me
  db: 0
  dial_timeout_seconds: 5
  read_timeout_seconds: 3
  write_timeout_seconds: 3
  pool_size: 256
  min_idle_conns: 16
  enable_tls: false

同一个 Redis 实例给多个环境使用时，优先使用独立实例或不同 Redis DB/前缀；不要让 staging 的 cleanup 和生产 key 冲突。

JWT 与 TOTP

jwt:
  secret: <固定随机值>
  access_token_expire_minutes: 60
  refresh_token_expire_days: 30
  refresh_window_minutes: 2

totp:
  encryption_key: <64位十六进制字符串>

• JWT secret 变化会让现有会话失效。
• TOTP key 变化会使已保存的 TOTP secret 无法解密。
• 多实例必须完全一致。

URL 安全

security:
  url_allowlist:
    enabled: true
    upstream_hosts:
      - api.openai.com
      - api.anthropic.com
      - generativelanguage.googleapis.com
      - cloudcode-pa.googleapis.com
    pricing_hosts:
      - raw.githubusercontent.com
    crs_hosts: []
    allow_private_hosts: false
    allow_insecure_http: false

使用自定义上游或 Azure OpenAI 时，把真实 hostname 加入 allowlist。不要为了一个地址临时关闭整个验证。

Gateway 基础参数

参数	作用	调整风险
response_header_timeout	等待通用上游响应头	太短会误杀排队请求
openai_response_header_timeout	OpenAI/Codex 单独超时	0 表示不额外限制
max_body_size	模型请求体上限	太大增加内存风险
upstream_response_read_max_bytes	非流式响应读取上限	太小截断大响应
connection_pool_isolation	proxy/account/account_proxy	隔离越细资源越多
max_account_switches	最大 failover 次数	太大放大错误流量
stream_data_interval_timeout	流数据空闲超时	要与代理协调
stream_keepalive_interval	keepalive 间隔	太频繁增加流量

OpenAI WebSocket

关键开关：

gateway:
  openai_ws:
    enabled: true
    force_http: false
    oauth_enabled: true
    apikey_enabled: true
    max_conns_per_account: 128

如果生产遇到 WS 协议或代理兼容问题，force_http 是紧急回滚开关。调优连接数前先检查文件描述符、账号并发和上游限制。

用量 worker

gateway:
  usage_record:
    worker_count: 128
    queue_size: 16384
    task_timeout_seconds: 5
    overflow_policy: sync
    auto_scale_enabled: true

小数据库可以降低 worker，避免瞬时写入过大。drop 会允许计费任务丢弃，不适合默认生产财务口径。

日志

容器推荐 JSON stdout，同时按需要写滚动文件：

LOG_LEVEL=info
LOG_FORMAT=json
LOG_OUTPUT_TO_STDOUT=true
LOG_OUTPUT_TO_FILE=true
LOG_ROTATION_MAX_SIZE_MB=100
LOG_ROTATION_MAX_BACKUPS=10
LOG_ROTATION_MAX_AGE_DAYS=7

Debug 可能包含更多请求上下文，不能长期在公网高流量环境开启。

配置变更流程

1. 备份当前 .env/YAML。
2. 在测试环境验证解析和启动。
3. 使用 docker compose config 检查 Compose 替换结果。
4. 一次只修改一类参数。
5. 滚动重启应用。
6. 验证健康、登录、普通请求、流式请求和计费。
7. 观察错误率与队列至少一个业务周期。

管理后台 Settings 写入 PostgreSQL，和 YAML/环境变量不是同一层。多实例下，部分运行时缓存和 Registry 需要逐副本确认生效；不要仅凭保存成功判断所有实例已应用新配置。

配置全集以仓库 deploy/config.example.yaml 和 deploy/.env.example 为准。