环境变量参考

本文档详细说明 Claude Code Hub 支持的所有环境变量，帮助您正确配置系统以满足不同部署场景的需求。

概述

Claude Code Hub 使用环境变量进行配置，支持以下几类配置：

• 必需变量：系统运行所必须的配置
• 数据库配置：PostgreSQL 连接和迁移设置
• Redis 配置：缓存、限流和 Session 管理
• 安全配置：Cookie 策略和认证设置
• API Key 安全配置：Vacuum Filter 和鉴权缓存
• 熔断器配置：故障保护和智能探测
• 端点探测配置：端点健康检查和动态间隔
• Langfuse 可观测性：LLM 请求追踪和分析
• 高级配置：调试、性能、超时和实验性功能

必需变量

ADMIN_TOKEN

管理员登录令牌，用于访问后台管理界面。

生成安全令牌的方法：

# Linux/macOS
openssl rand -hex 32

# 或使用 Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

配置示例：

ADMIN_TOKEN=a1b2c3d4e5f6789012345678901234567890abcdef

DSN

PostgreSQL 数据库连接字符串。

格式：

postgres://用户名:密码@主机:端口/数据库名

配置示例：

# 本地开发
DSN=postgres://postgres:password@localhost:5432/claude_code_hub

# Docker Compose（容器内自动配置，通常无需手动设置）
DSN=postgresql://postgres:postgres@postgres:5432/claude_code_hub

# 远程数据库
DSN=postgres://myuser:mypassword@db.example.com:5432/claude_code_hub

数据库配置

DB_USER

PostgreSQL 数据库用户名，仅在 Docker Compose 部署时使用。

DB_PASSWORD

PostgreSQL 数据库密码。

DB_NAME

PostgreSQL 数据库名称。

AUTO_MIGRATE

控制应用启动时是否自动执行数据库迁移。

使用建议：

• 开发环境：建议设为 true，方便快速迭代
• 生产环境：首次部署后建议设为 false，手动控制迁移时机

Redis 配置

REDIS_URL

Redis 连接地址。

支持的协议：

配置示例：

# 本地 Redis
REDIS_URL=redis://localhost:6379

# Docker Compose
REDIS_URL=redis://redis:6379

# 带密码认证
REDIS_URL=redis://:password@localhost:6379

# Upstash (TLS)
REDIS_URL=rediss://default:your-password@your-endpoint.upstash.io:6379

ENABLE_RATE_LIMIT

是否启用限流功能。

功能范围：

• RPM（每分钟请求数）限制
• 金额限制（5 小时/周/月）
• Session 并发限制
• 供应商并发限制

Session 配置

SESSION_TTL

Session 过期时间，控制 Session 与供应商的绑定关系缓存时长。

影响范围：

• Session 粘性（同一会话路由到同一供应商）
• 供应商缓存命中率优化
• 活跃 Session 监控数据保留时间

配置建议：

STORE_SESSION_MESSAGES

会话消息存储模式。控制请求/响应中 message 内容的存储方式（v0.5.1 行为变更）。

• false（默认）：存储请求/响应体但对 message 内容脱敏，显示为 [REDACTED]
• true：原样存储 message 内容

STORE_SESSION_RESPONSE_BODY

是否在 Redis 中存储会话响应体（SSE/JSON）。用于调试和问题定位。

• true（默认）：存储响应体到 Redis 临时缓存
• false：不存储响应体

SHORT_CONTEXT_THRESHOLD

短上下文阈值，用于并发任务检测。当消息数量小于等于此值时，触发短上下文并发检测逻辑。

ENABLE_SHORT_CONTEXT_DETECTION

是否启用短上下文并发检测。当检测到短上下文（消息数 <= SHORT_CONTEXT_THRESHOLD）且存在并发请求时， 系统会强制创建新 Session，避免并发短任务错误复用同一供应商。

应用配置

APP_PORT

应用对外暴露的端口号。

APP_URL

应用的完整访问地址，用于 OpenAPI 文档生成等场景。

配置示例：

# HTTPS 域名
APP_URL=https://your-domain.com

# IP 地址访问
APP_URL=http://192.168.1.100:23000

# 本地开发（通常留空自动检测）
APP_URL=

影响范围：

• OpenAPI 文档中的 servers 配置
• API 文档的基础 URL 显示

API_TEST_TIMEOUT_MS

供应商 API 连接测试的超时时间。

配置建议：

安全配置

ENABLE_SECURE_COOKIES

控制是否强制 HTTPS Cookie（设置 cookie 的 secure 属性）。

API Key 安全配置

ENABLE_API_KEY_VACUUM_FILTER

启用 API Key 真空过滤器（Vacuum Filter），在访问数据库前对无效 API Key 进行负向短路，降低数据库压力、抵御暴力破解。

ENABLE_API_KEY_REDIS_CACHE

是否启用 API Key Redis 缓存。需要 ENABLE_RATE_LIMIT=true 且配置 REDIS_URL 才会生效；否则自动回落到数据库查询。

API_KEY_AUTH_CACHE_TTL_SECONDS

API Key 鉴权缓存 TTL。缓存链路为 Vacuum Filter -> Redis -> DB。

熔断器配置

ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS

控制网络错误是否计入熔断器失败计数。

使用场景：

ENABLE_SMART_PROBING

是否启用智能探测功能。当熔断器处于 OPEN 状态时，定期探测供应商以实现更快恢复。

工作原理：

1. 定期检查处于 OPEN 状态的熔断器
2. 使用轻量级测试请求探测供应商
3. 探测成功则提前将熔断器转为 HALF_OPEN 状态

PROBE_INTERVAL_MS

智能探测的周期间隔。仅在 ENABLE_SMART_PROBING=true 时生效。

PROBE_TIMEOUT_MS

单次探测请求的超时时间。仅在 ENABLE_SMART_PROBING=true 时生效。

ENABLE_ENDPOINT_CIRCUIT_BREAKER

控制是否启用端点级别的熔断器。

端点探测配置

端点探测始终启用，定期检查所有启用的端点并刷新端点选择排名。

ENDPOINT_PROBE_INTERVAL_MS

端点探测基础间隔。系统使用动态间隔规则：

1. 超时覆盖（10 秒）：端点上次探测超时且未恢复时
2. 单端点供应商（10 分钟）：供应商仅有 1 个启用端点时
3. 基础间隔：其他端点使用此值

ENDPOINT_PROBE_TIMEOUT_MS

单次端点探测超时时间。

ENDPOINT_PROBE_METHOD

端点探测方式。TCP 模式（默认）仅检测连接，不发送 HTTP 请求，不产生访问日志。

ENDPOINT_PROBE_CONCURRENCY

端点探测并发数。

ENDPOINT_PROBE_LOG_RETENTION_DAYS

探测日志保留天数。自动清理任务每 24 小时运行，删除过期记录。

Langfuse 可观测性

以下变量控制 Langfuse LLM 可观测性集成，自 v0.6.0 起可用。

LANGFUSE_PUBLIC_KEY

Langfuse 项目公钥，以 pk-lf- 开头。与 LANGFUSE_SECRET_KEY 同时配置后自动启用追踪。

LANGFUSE_SECRET_KEY

Langfuse 项目密钥，以 sk-lf- 开头。

LANGFUSE_BASE_URL

Langfuse 服务器地址。使用 Langfuse Cloud 时无需修改，自托管实例需指向你的服务地址。

LANGFUSE_SAMPLE_RATE

追踪采样率。0.0 表示不采样，1.0 表示全量采样。高并发场景建议降低采样率以控制 Langfuse 存储成本。

LANGFUSE_DEBUG

是否启用 Langfuse SDK 调试日志。排查 Langfuse 集成问题时可临时开启。

高级配置

ENABLE_PROVIDER_CACHE

启用供应商进程级缓存（30s TTL + Redis Pub/Sub 跨实例即时失效），提升供应商查询性能。禁用后每次请求直接查询数据库。

MESSAGE_REQUEST_WRITE_MODE

请求日志（message_request）写入模式。async 为异步批量写入（降低 DB 写放大和连接占用），sync 为同步写入（兼容旧行为，但高并发下会增加请求尾部阻塞）。

DB_POOL_MAX

PostgreSQL 每个应用进程的连接池上限。K8s 多副本部署时需按副本数分摊。

MAX_RETRY_ATTEMPTS_DEFAULT

单供应商最大尝试次数（含首次调用）。

LOG_LEVEL

日志输出级别，从高到低依次为：fatal > error > warn > info > debug > trace。

级别详细说明：

默认值逻辑：

1. 优先使用环境变量 LOG_LEVEL 的值
2. 如果未设置 LOG_LEVEL，检查 DEBUG_MODE 是否为 true（向后兼容）
3. 如果都未设置，根据运行环境决定：
   • 开发环境（NODE_ENV !== 'production'）：debug
   • 生产环境：info

DEBUG_MODE

向后兼容的调试模式开关。设置为 true 时等同于 LOG_LEVEL=debug。

TZ

系统时区设置，影响日志时间戳和时间相关功能。

常用时区：

TZ=Asia/Shanghai      # 北京时间 (UTC+8)
TZ=America/New_York   # 美东时间
TZ=Europe/London      # 伦敦时间
TZ=UTC                # 协调世界时

Fetch 超时配置

以下变量控制上游请求的各阶段超时时间：

这些配置适用于系统向上游供应商发起的所有请求。

完整配置示例

开发环境

# 必需配置
ADMIN_TOKEN=dev-token-for-local-testing

# 数据库（本地 PostgreSQL）
DSN=postgres://postgres:postgres@localhost:5432/claude_code_hub
AUTO_MIGRATE=true

# Redis（本地）
REDIS_URL=redis://localhost:6379
ENABLE_RATE_LIMIT=true

# 应用
APP_PORT=23000
ENABLE_SECURE_COOKIES=false  # 开发环境允许 HTTP

# 调试
LOG_LEVEL=debug

生产环境（Docker Compose）

# 必需配置（务必修改！）
ADMIN_TOKEN=your-secure-random-token-here

# 数据库配置（Docker Compose 自动构建 DSN）
DB_USER=postgres
DB_PASSWORD=your-strong-password-here
DB_NAME=claude_code_hub
AUTO_MIGRATE=false  # 生产环境手动控制迁移

# Redis
REDIS_URL=redis://redis:6379
ENABLE_RATE_LIMIT=true

# Session
SESSION_TTL=300
STORE_SESSION_MESSAGES=false

# 应用
APP_PORT=23000
APP_URL=https://your-domain.com
ENABLE_SECURE_COOKIES=true

# 熔断器
ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS=false
ENABLE_SMART_PROBING=true
PROBE_INTERVAL_MS=30000
PROBE_TIMEOUT_MS=5000
ENABLE_ENDPOINT_CIRCUIT_BREAKER=false

# API Key 安全
ENABLE_API_KEY_VACUUM_FILTER=true
ENABLE_API_KEY_REDIS_CACHE=true
API_KEY_AUTH_CACHE_TTL_SECONDS=60

# 日志
LOG_LEVEL=info
TZ=Asia/Shanghai

# Langfuse 可观测性（可选）
# LANGFUSE_PUBLIC_KEY=pk-lf-your-public-key
# LANGFUSE_SECRET_KEY=sk-lf-your-secret-key
# LANGFUSE_BASE_URL=https://cloud.langfuse.com
# LANGFUSE_SAMPLE_RATE=1.0

内网部署（HTTP 访问）

# 必需配置
ADMIN_TOKEN=your-secure-random-token-here

# 数据库
DSN=postgres://user:password@db-server:5432/claude_code_hub

# Redis
REDIS_URL=redis://redis-server:6379

# 安全配置（内网 HTTP 访问）
ENABLE_SECURE_COOKIES=false  # 允许 HTTP Cookie

# 应用
APP_PORT=23000
APP_URL=http://192.168.1.100:23000

环境变量验证

系统启动时会通过 Zod schema 验证环境变量。如果配置无效，会输出明确的错误信息。

验证规则定义在 src/lib/config/env.schema.ts 中，主要包括：

• 类型验证（字符串、数字、布尔值）
• 必需字段检查
• 默认值应用
• URL 格式验证
• 枚举值验证