跳转到主要内容
本文档涵盖 AIS/OpenSky 中继路径使用的所有环境变量：
  • Railway 中继进程：scripts/ais-relay.cjs
  • Vercel 中继代理端点（旧版）：api/opensky.js、api/ais-snapshot.js、api/polymarket.js、api/rss-proxy.js
上述 api/*.js edge function 端点是旧版模式，正逐步被淘汰，以改用 sebuf proto-first 方式。有关当前推荐的模式，请参阅添加端点。
  • 服务器中继调用方：server/worldmonitor/* 处理器
  • src/services/* 中的可选浏览器本地回退调用方

​
1) 最低生产环境配置

在启用严格的中继认证之前设置这些变量。

​
Railway（中继）

变量必填示例说明
AISSTREAM_API_KEY是ais_...用于 AIS 上游 WebSocket 数据流。
RELAY_SHARED_SECRET是wm_relay_prod_...必须与 Vercel 的值完全匹配。
RELAY_AUTH_HEADER推荐x-relay-key如果从默认值更改，必须与 Vercel 匹配。

​
Vercel（代理 + 服务器函数）

变量必填示例说明
WS_RELAY_URL是https://<railway-app>.up.railway.app服务器端代理调用使用的 HTTPS 中继基础 URL。
RELAY_SHARED_SECRET是wm_relay_prod_...必须与 Railway 的值完全匹配。
RELAY_AUTH_HEADER推荐x-relay-key用于转发中继密钥的标头名称。

​
2) 完整参数参考

​
核心中继/认证

变量设置位置默认值必填用途
AISSTREAM_API_KEYRailway无是AIS 上游数据源的认证。
VITE_AISSTREAM_API_KEY仅本地开发无否在缺少 AISSTREAM_API_KEY 时的本地回退。不建议用于生产环境。
PORTRailway/本地3004否中继进程的 HTTP 服务器监听端口。
WS_RELAY_URLVercel + 服务器处理器无是（针对中继支持的功能）Vercel/服务器用于访问 Railway 中继的基础 URL。
VITE_WS_RELAY_URL浏览器（本地开发）无否仅在开发环境中用于直接浏览器调用的 localhost 回退路径。
RELAY_SHARED_SECRETRailway + Vercel + 自托管空是（始终）非公开中继路由的共享密钥。没有此密钥中继将拒绝启动，除非 I_UNDERSTAND_THIS_DISABLES_AUTH=true。
RELAY_AUTH_HEADERRailway + Vercelx-relay-key否（但建议显式设置）携带中继密钥的标头名称。
I_UNDERSTAND_THIS_DISABLES_AUTHRailway / 自托管false否仅用于开发的逃生通道。如果为 true，中继在没有共享密钥的情况下启动，在启动时和每 5 分钟记录一条醒目的 [SECURITY] 日志，并接受非公开路由上的所有请求。切勿在生产环境中设置。
ALLOW_UNAUTHENTICATED_RELAYRailway / 自托管false否I_UNDERSTAND_THIS_DISABLES_AUTH 的已弃用别名。为向后兼容仍然接受；使用此名称时中继会记录一条 [DEPRECATED] 警告。
ALLOW_VERCEL_PREVIEW_ORIGINSRailwayfalse否如果为 true，允许在中继 CORS 检查中使用 *.vercel.app 来源。

​
中继相邻功能开关

变量设置位置默认值必填用途
VITE_ENABLE_AIS浏览器/客户端构建 env启用（除非为 false）否AIS UI/轮询的客户端功能开关。
LOCAL_API_MODE本地/服务器运行时无否如果包含 sidecar，一些服务器处理器会绕过中继并直接调用 OpenSky。
WINGBITS_API_KEYVercel/服务器无否服务器处理器使用的军用数据增强/回退源；中继核心不需要。

​
OpenSky 上游认证

变量设置位置默认值必填用途
OPENSKY_CLIENT_IDRailway无否（推荐）用于提高 OpenSky 可靠性/速率限制的 OAuth 客户端 ID。
OPENSKY_CLIENT_SECRETRailway无否（推荐）与客户端 ID 配对的 OAuth 客户端密钥。

​
OpenSky 缓存/基数控制

变量设置位置默认值必填用途
OPENSKY_CACHE_MAX_ENTRIESRailway128否内存中保留的最大正向缓存键数。
OPENSKY_NEGATIVE_CACHE_MAX_ENTRIESRailway256否内存中保留的最大负向缓存键（429/5xx）数。
OPENSKY_BBOX_QUANT_STEPRailway0.01否用于 bbox 缓存键复用的坐标量化步长。0 禁用量化。

​
AIS 管道调优

变量设置位置默认值必填用途
AIS_SNAPSHOT_INTERVAL_MSRailway5000（最小 2000）否重建快照负载的间隔。
AIS_UPSTREAM_QUEUE_HIGH_WATERRailway4000（最小 500）否队列达到此值时暂停上游 socket。
AIS_UPSTREAM_QUEUE_LOW_WATERRailway1000（限制低于 HIGH_WATER）否队列降至低于此值时恢复上游 socket。
AIS_UPSTREAM_QUEUE_HARD_CAPRailway8000（必须 > HIGH_WATER）否丢弃传入上游消息前的最大队列大小。
AIS_UPSTREAM_DRAIN_BATCHRailway250（最小 1）否每周期排出的最大消息数。
AIS_UPSTREAM_DRAIN_BUDGET_MSRailway20（最小 2）否每个排出周期的最大 CPU 时间预算。

​
速率限制 / 日志 / 指标

变量设置位置默认值必填用途
RELAY_RATE_LIMIT_WINDOW_MSRailway60000否全局速率限制窗口。
RELAY_RATE_LIMIT_MAXRailway1200否每个 IP 每窗口的默认最大请求数。
RELAY_OPENSKY_RATE_LIMIT_MAXRailway600否OpenSky 路由每个 IP 每窗口的最大请求数。
RELAY_RSS_RATE_LIMIT_MAXRailway300否RSS 路由每个 IP 每窗口的最大请求数。
RELAY_LOG_THROTTLE_MSRailway10000否每个键重复日志事件之间的最小间隔。
RELAY_METRICS_WINDOW_SECONDSRailway60（最小 10）否/metrics 使用的滚动窗口。

​
平台管理变量（请勿手动设置）

这些仅用于生产环境检测，通常由平台/运行时注入。
变量设置方用途
NODE_ENV运行时/平台用于检测生产模式。
RAILWAY_ENVIRONMENTRailway用于检测生产中继环境。
RAILWAY_PROJECT_IDRailway用于检测生产中继环境。
RAILWAY_STATIC_URLRailway用于检测生产中继环境。

​
3) 推荐起始值（高流量基线）

这些是繁忙中继的安全起始点： 
# Auth + routing — RELAY_SHARED_SECRET is REQUIRED (the relay exits at startup
# without it unless I_UNDERSTAND_THIS_DISABLES_AUTH=true is set).
RELAY_SHARED_SECRET=<strong-random-secret>   # openssl rand -hex 32
RELAY_AUTH_HEADER=x-relay-key
WS_RELAY_URL=https://<your-railway-relay>.up.railway.app
# I_UNDERSTAND_THIS_DISABLES_AUTH=false   # dev-only override; do NOT set in prod

# OpenSky cache/cardinality
OPENSKY_CACHE_MAX_ENTRIES=256
OPENSKY_NEGATIVE_CACHE_MAX_ENTRIES=512
OPENSKY_BBOX_QUANT_STEP=0.01

# AIS pipeline
AIS_SNAPSHOT_INTERVAL_MS=3000
AIS_UPSTREAM_QUEUE_HIGH_WATER=5000
AIS_UPSTREAM_QUEUE_LOW_WATER=1500
AIS_UPSTREAM_QUEUE_HARD_CAP=10000
AIS_UPSTREAM_DRAIN_BATCH=300
AIS_UPSTREAM_DRAIN_BUDGET_MS=20

# Rate limits + metrics
RELAY_RATE_LIMIT_WINDOW_MS=60000
RELAY_RATE_LIMIT_MAX=1200
RELAY_OPENSKY_RATE_LIMIT_MAX=600
RELAY_RSS_RATE_LIMIT_MAX=300
RELAY_LOG_THROTTLE_MS=10000
RELAY_METRICS_WINDOW_SECONDS=60

​
4) 如何验证配置

健康检查： 
curl -sS https://<relay>/health
指标（需要中继认证）： 
curl -sS https://<relay>/metrics \
  -H "x-relay-key: $RELAY_SHARED_SECRET"
或： 
curl -sS https://<relay>/metrics \
  -H "Authorization: Bearer $RELAY_SHARED_SECRET"
预期检查项：
  • auth.enabled 在 /health 中为 true（操作员可见的规范标志 —— 仅当配置了共享密钥且未启用 I_UNDERSTAND_THIS_DISABLES_AUTH 绕过时才为 true）。auth.sharedSecretEnabled 为向后兼容而保留。
  • /metrics.opensky.hitRatio 在负载下保持稳定且处于高位。
  • /metrics.ais.dropsPerSec 在正常运行时保持为 0。
  • /metrics.ais.queueMax 远低于 AIS_UPSTREAM_QUEUE_HARD_CAP。