中继参数（Railway + Vercel）

本文档涵盖 AIS/OpenSky 中继路径使用的所有环境变量：

Railway 中继进程：scripts/ais-relay.cjs
仅供桌面产品使用的 OpenSky 中继：api/opensky.js（不属于公共 API 产品）
Vercel 中继代理端点（旧版）：api/ais-snapshot.js、api/polymarket.js、api/rss-proxy.js

第二项中的旧版代理端点正逐步被淘汰，以改用 sebuf proto-first 方式。OpenSky 路由仅是受限的桌面产品传输层，不是公共集成接口。有关当前推荐的模式，请参阅添加端点。

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

中继相邻功能开关

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

OpenSky 上游认证

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

OpenSky 缓存/基数控制

变量	设置位置	默认值	必填	用途
`OPENSKY_CACHE_MAX_ENTRIES`	Railway	`128`	否	内存中保留的最大正向缓存键数。
`OPENSKY_NEGATIVE_CACHE_MAX_ENTRIES`	Railway	`256`	否	内存中保留的最大负向缓存键（`429/5xx`）数。
`OPENSKY_BBOX_QUANT_STEP`	Railway	`0.01`	否	用于 bbox 缓存键复用的坐标量化步长。`0` 禁用量化。

AIS 管道调优

变量	设置位置	默认值	必填	用途
`AIS_SNAPSHOT_INTERVAL_MS`	Railway	`5000`（最小 `2000`）	否	重建快照负载的间隔。
`AIS_UPSTREAM_QUEUE_HIGH_WATER`	Railway	`4000`（最小 `500`）	否	队列达到此值时暂停上游 socket。
`AIS_UPSTREAM_QUEUE_LOW_WATER`	Railway	`1000`（限制低于 HIGH_WATER）	否	队列降至低于此值时恢复上游 socket。
`AIS_UPSTREAM_QUEUE_HARD_CAP`	Railway	`8000`（必须 `> HIGH_WATER`）	否	丢弃传入上游消息前的最大队列大小。
`AIS_UPSTREAM_DRAIN_BATCH`	Railway	`250`（最小 `1`）	否	每周期排出的最大消息数。
`AIS_UPSTREAM_DRAIN_BUDGET_MS`	Railway	`20`（最小 `2`）	否	每个排出周期的最大 CPU 时间预算。

速率限制 / 日志 / 指标

变量	设置位置	默认值	必填	用途
`RELAY_RATE_LIMIT_WINDOW_MS`	Railway	`60000`	否	全局速率限制窗口。
`RELAY_RATE_LIMIT_MAX`	Railway	`1200`	否	每个 IP 每窗口的默认最大请求数。
`RELAY_OPENSKY_RATE_LIMIT_MAX`	Railway	`600`	否	OpenSky 路由每个 IP 每窗口的最大请求数。
`RELAY_RSS_RATE_LIMIT_MAX`	Railway	`300`	否	RSS 路由每个 IP 每窗口的最大请求数。
`RELAY_LOG_THROTTLE_MS`	Railway	`10000`	否	每个键重复日志事件之间的最小间隔。
`RELAY_METRICS_WINDOW_SECONDS`	Railway	`60`（最小 `10`）	否	`/metrics` 使用的滚动窗口。

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

这些仅用于生产环境检测，通常由平台/运行时注入。

变量	设置方	用途
`NODE_ENV`	运行时/平台	用于检测生产模式。
`RAILWAY_ENVIRONMENT`	Railway	用于检测生产中继环境。
`RAILWAY_PROJECT_ID`	Railway	用于检测生产中继环境。
`RAILWAY_STATIC_URL`	Railway	用于检测生产中继环境。

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。

入门

使用

平台与功能

情报与分析

工作流

地图图层

金融

面板 — AI 与 PRO

面板 — 数据与追踪

面板 — 目录

桌面应用

MCP 与集成

HTTP API

开发者指南

公司

法律

中继参数（Railway + Vercel）

1) 最低生产环境配置

Railway（中继）

Vercel（代理 + 服务器函数）

2) 完整参数参考

核心中继/认证

中继相邻功能开关

OpenSky 上游认证

OpenSky 缓存/基数控制

AIS 管道调优

速率限制 / 日志 / 指标

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

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

4) 如何验证配置

​1) 最低生产环境配置

​Railway（中继）

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

​2) 完整参数参考

​核心中继/认证

​中继相邻功能开关

​OpenSky 上游认证

​OpenSky 缓存/基数控制

​AIS 管道调优

​速率限制 / 日志 / 指标

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

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

​4) 如何验证配置

1) 最低生产环境配置

Railway（中继）

Vercel（代理 + 服务器函数）

2) 完整参数参考

核心中继/认证

中继相邻功能开关

OpenSky 上游认证

OpenSky 缓存/基数控制

AIS 管道调优

速率限制 / 日志 / 指标

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

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

4) 如何验证配置