worldmonitor v2.11.4 配置参数详解
系统梳理 worldmonitor v2.11.4 自托管全部配置面：.env 282 变量 37 分区、compose 四服务注入表、LLM 与 11 项数据源 key、19 个 VITE 构建开关、seeders 参数与 9 个实测排障问题。
worldmonitor v2.11.4 配置参数详解
目标：系统梳理 worldmonitor v2.11.4 自托管部署的全部配置面——
.env变量体系（282 个变量、37 个官方分区）、docker-compose.yml四服务的环境变量注入表、AI/LLM 与数据源 key、前端构建开关与种子脚本运行参数，并给出 9 个实测排障问题。本文基于 v2.11.4 快照（main 分支 commitd8ba38d，2026-10-24）源码与官方文档撰写，配置行为均在按 《worldmonitor v2.11.4 Docker Compose 部署指南》 部署的实测栈上验证，查询日期 2026-10-25。
一、环境信息
- 组件版本：worldmonitor v2.11.4（2026-10-24 发布）
- 配置载体实测环境：Docker Engine 29.9.2（Compose v5.6.1）、Alpine 3.24.3、部署目录
/opt/worldmonitor/ - 配置文件清单（实测）：
cd /opt/worldmonitor && ls -la .env .env.example docker-compose.yml 2>/dev/null | awk '{print $NF, $5}'
实测输出：
.env 477
.env.example 27036
docker-compose.yml 6985
- 官方
.env.example规模（实测统计）：282 个变量、37 个分区；其中 Docker Compose 必填 4 个（无默认值，缺失拒绝启动），其余全部可选、留空即功能关闭 - 参数溯源：本文所有参数名与默认值直接取自仓库
.env.example、docker-compose.yml、Dockerfile、scripts/run-seeders.sh与docker/render-nginx-realip.mjs源码（v2.11.4 快照），非转述二手文档
二、配置体系与优先级
2.1 三层配置载体
| 载体 | 生效方式 | 适用场景 |
|---|---|---|
.env（仓库根，gitignore） | compose 插值 + seeders 脚本读取 | 日常配置主入口 |
docker-compose.override.yml（可选） | compose 自动叠加到主文件 | 按 key 分组注入 API key，不污染主文件 |
Docker secrets（可选，secrets/ 目录一 key 一文件） | 主文件注释段预留，取消注释启用 | 不想让 key 出现在 docker inspect 输出 |
两个实测确认的关键边界：
.env不会进入镜像构建：.dockerignore第 20 行排除.env*，前端构建读不到它——VITE_*前端开关属构建期变量，需在构建环境注入（见第七章）；.env改动需up -d重建才生效：compose 只在up -d时重新插值并重建服务，restart不会重读环境变量（见 FAQ Q2）。
2.2 必填四密钥（无默认值）
.env.example「Self-hosted Redis (Docker Compose only)」分区原文明确：
# REQUIRED when running via docker-compose.yml. Both containers fail to start
# if either variable is unset (no shipped defaults — see #3804).
# Generate fresh values: openssl rand -hex 32
#
# REDIS_PASSWORD → Redis AUTH password (--requirepass)
# REDIS_TOKEN → Upstash-compatible REST proxy bearer token (SRH_TOKEN)
加上 compose 中同样带 :? 强制校验的 RELAY_SHARED_SECRET 与 WM_SESSION_SECRET，共四个必填项。wm-local-token 旧默认值已因安全问题 #3804 移除——从旧克隆升级必须补齐，否则启动即报 required variable ... is missing a value（实测报错全文见部署指南 4.1 节）。
三、核心运行参数（docker-compose.yml 注入表）
以下为 docker-compose.yml 向四服务注入的全部环境变量（实测逐行提取，默认值与强制校验原样保留）：
3.1 worldmonitor（主服务：nginx + Node API）
| 变量 | compose 取值 | 说明 |
|---|---|---|
| 端口映射 | ${WM_PORT:-3000}:8080 | 宿主端口由 WM_PORT 控制，服务内固定 8080 |
UPSTASH_REDIS_REST_URL | http://redis-rest:80（固定） | 应用经 REST 代理访问 Redis |
UPSTASH_REDIS_REST_TOKEN | ${REDIS_TOKEN:?...}（必填） | 代理 Bearer 令牌 |
WM_SESSION_SECRET | ${WM_SESSION_SECRET:?...}（必填） | 匿名浏览器会话签名 |
LOCAL_API_PORT | 46123（固定） | 栈内 Node API 监听端口 |
LOCAL_API_MODE | docker（固定） | Docker 自托管模式：无 Clerk/Convex 权益后端，/api/local- 管理路由一律 403 |
LOCAL_API_CLOUD_FALLBACK | false（固定） | 关闭云端回退 |
WM_TRUSTED_PROXY_CIDRS | ${WM_TRUSTED_PROXY_CIDRS:-} | 前置反代时声明可信代理网段，详见 3.5 |
WS_RELAY_URL | http://ais-relay:3004（固定） | 应用连 AIS 中继 |
RELAY_SHARED_SECRET | ${RELAY_SHARED_SECRET:?...}（必填） | 中继鉴权 |
WORLDMONITOR_VALID_KEYS | ${WORLDMONITOR_VALID_KEYS:-} | 自托管 MCP/REST 接受的 operator key（X-WorldMonitor-Key 头），多个逗号分隔 |
WORLDMONITOR_RELAY_KEY | ${WORLDMONITOR_RELAY_KEY:-} | relay 侧调用的服务间 key |
LLM_API_URL / LLM_API_KEY / LLM_MODEL / OPENROUTER_API_KEY | 留空默认 | LLM 提供方，见第四章 |
AISSTREAM_API_KEY FINNHUB_API_KEY EIA_API_KEY FRED_API_KEY ACLED_EMAIL ACLED_PASSWORD ACLED_ACCESS_TOKEN NASA_FIRMS_API_KEY CLOUDFLARE_API_TOKEN AVIATIONSTACK_API TRAVELPAYOUTS_API_TOKEN | 留空默认 | 数据源 key，见第五章 |
3.2 ais-relay（AIS/航空中继）
| 变量 | compose 取值 | 说明 |
|---|---|---|
RELAY_SHARED_SECRET | ${RELAY_SHARED_SECRET:?...}（必填） | 与主服务共享 |
AISSTREAM_API_KEY / FINNHUB_API_KEY | 留空默认 | 中继侧自行拉流 |
MARKET_YAHOO_REFRESH_INTERVAL_MS | 默认 900000（15 分钟） | Yahoo 行情刷新间隔 |
UPSTASH_REDIS_REST_URL / ..._TOKEN | 同上（必填） | 中继写缓存 |
UPSTASH_ALLOW_INSECURE_HTTP | true（固定） | 允许走纯 HTTP 代理（默认仅 https，自托管代理是 http） |
UCDP_ACCESS_TOKEN / TYPESAFE_API_KEY / TYPESAFE_BASE_URL | 留空默认 | 冲突数据与 Jev 分类影子评估 |
API_BASE_URL | 默认 http://worldmonitor:8080 | 中继读 classify 种子（compose 原注释：勿对 worldmonitor 加 depends_on，靠瞬时重试过启动竞态） |
PORT | 3004（固定） | 中继监听端口 |
3.3 redis 与 redis-rest
| 服务 | 参数 | 值 | 说明 |
|---|---|---|---|
| redis | 启动命令 | --requirepass "${REDIS_PASSWORD:?...}" --maxmemory 256mb --maxmemory-policy allkeys-lru | 密码必填；缓存上限 256MB LRU 淘汰；数据卷 redis-data |
| redis-rest | SRH_TOKEN | ${REDIS_TOKEN:?...}（必填） | 代理 Bearer 令牌 |
| redis-rest | SRH_MAX_BODY_BYTES | 默认 16MB | 单请求体上限 |
| redis-rest | mem_limit | 512m | 源码注释实测：代理整体缓冲请求体，64 个并发 16MB POST 可达约 933MB RSS，限 512m 留约 7 倍余量 |
| redis-rest | 端口 | 127.0.0.1:8079:80 | 仅回环暴露，宿主侧 seeders 用 |
3.4 调度与自愈
三个自建服务均 restart: unless-stopped；主服务 depends_on redis-rest 与 ais-relay（started 条件）。服务器重启后全栈自动拉起。
3.5 WM_TRUSTED_PROXY_CIDRS（前置反代必配）
该变量由镜像内的 docker/render-nginx-realip.mjs 在启动时消费并渲染 nginx realip 配置，源码校验逻辑（实测提取）：每个值必须是合法 IP 或 CIDR，非法值直接报错退出：
Invalid IP or CIDR in WM_TRUSTED_PROXY_CIDRS: ["bad-cidr"]
SELF_HOSTING.md 要求：把 nginx 置于反代后时设为反代网段（如 172.16.0.0/12 或 10.0.0.0/8），nginx 据此信任 X-Forwarded-For，保证限流按真实客户端 IP 计数；直接对外访问时保持留空（设错会误信任伪造头）。另注意 nginx 仅信任请求头中的 X-Real-IP，不信任 X-Forwarded-For 链。
四、AI 与 LLM 参数
4.1 云端 LLM（OpenRouter）
OPENROUTER_API_KEY=
- 未配置时「世界简报 / Latest Brief / Daily Market Brief」等 LLM 面板隐藏，其余功能不受影响；
- 免费档限 50 次请求/天（
openrouter/free-tier模型）。
4.2 自托管 LLM（任意 OpenAI 兼容端点）
.env.example「Self-Hosted LLM (Docker — any OpenAI-compatible endpoint)」分区原文：
# Point to your own LLM server (Ollama, vLLM, llama.cpp, etc.)
# Used for intelligence assessments in the correlation engine.
LLM_API_URL=
LLM_API_KEY=
LLM_MODEL=
# Alternative: Ollama-specific URL (used if LLM_API_URL is not set)
OLLAMA_API_URL=
OLLAMA_MODEL=
配置要点（SELF_HOSTING.md「Self-Hosted LLM」节 + 官方 Getting Started）：
LLM_API_URL指向完整 chat completions 端点，Ollama 示例：http://your-host:11434/v1/chat/completions；LLM_MODEL如qwen3:8b；LLM_API_URL未设时回退读OLLAMA_API_URL（可只填http://your-host:11434）；- 容器内解析不了主机名时，在 override 中加
extra_hosts: ["your-host:192.168.1.100"]； - Docker 模式下
GET /api/intelligence/v1/get-country-intel-brief接受匿名会话，但每日每 IP 限 50 次直连 LLM 调用（nginx 以$remote_addr打X-Real-IP，换头/换会话无法重置）。
4.3 预测流水线模型分工（可选）
.env.example 还提供按用途细分模型（留空统一回退 OPENROUTER_API_KEY + 默认模型）：
FORECAST_LLM_MODEL_OPENROUTER=
FORECAST_LLM_COMBINED_MODEL_OPENROUTER=
FORECAST_LLM_CRITICAL_MODEL_OPENROUTER=
FORECAST_LLM_MARKET_IMPLICATIONS_MODEL_OPENROUTER=
官方注释示例：FORECAST_LLM_COMBINED_MODEL_OPENROUTER=google/gemini-2.5-pro、FORECAST_LLM_CRITICAL_MODEL_OPENROUTER=anthropic/claude-3.5-haiku——即「综合用强模型、关键判断用快模型」的成本分层玩法。
4.4 托管版专用（自托管不适用，如实标注）
.env.example「Pro MCP (plan 2026-05-10-001)」分区的 MCP_PRO_GRANT_HMAC_SECRET、MCP_INTERNAL_HMAC_SECRET 服务于官方托管站的 Pro 用户 OAuth 授权桥接（apex 与 api 域双端 HMAC 校验），自托管 Docker 模式不使用这两个变量——自托管 MCP 认证走 WORLDMONITOR_VALID_KEYS（见 3.1）。
五、数据源 API Key 参数
5.1 免 key 数据源（零配置可用）
.env.example「Public Data Sources (no keys required)」分区列出三个免认证源：UNHCR（联合国难民署，CC BY 4.0）、Open-Meteo（气象，基于 Copernicus ERA5）、WorldPop（人口栅格）。叠加地震/自然事件/预测市场/加密货币等公共源，构成免 key 层——实测本机栈在未配任何 key 时核心面板即可用（GET / HTTP 200，sidecar-health ok）。
5.2 compose 直通的数据源 key（11 项）
见 3.1 表末行。各 key 的来源与解锁能力（来源：SELF_HOSTING.md「Environment Variables」表与 .env.example 注释，实测变量名一致）：
| 变量 | 获取途径 | 解锁能力 |
|---|---|---|
FINNHUB_API_KEY | finnhub.io（免费档） | 股票行情主源 + 符号搜索 |
AISSTREAM_API_KEY | aisstream.io（免费） | 实时船舶 AIS（app 与 ais-relay 都要给） |
EIA_API_KEY | eia.gov/opendata（免费） | 石油分析 |
FRED_API_KEY | fred.stlouisfed.org（免费） | 美联储经济数据 |
ACLED_EMAIL / ACLED_PASSWORD | acleddata.com（研究者免费） | 冲突与抗议事件，自动 OAuth 刷新，优先于静态 token |
ACLED_ACCESS_TOKEN | 同上（legacy） | 静态令牌，24 小时过期需手工轮换 |
UCDP_ACCESS_TOKEN | ucdp.uu.se | 乌普萨拉冲突数据（2025 起需 token，注入 ais-relay） |
NASA_FIRMS_API_KEY | firms.modaps.eosdis.nasa.gov（免费） | 卫星火点（seed-fire-detections 必需） |
CLOUDFLARE_API_TOKEN | dash.cloudflare.com（需 Radar 权限，付费） | 断网监测 |
AVIATIONSTACK_API | aviationstack.com | 航空数据补充 |
TRAVELPAYOUTS_API_TOKEN | travelpayouts.com | 旅行/航班价格数据 |
5.3 ACLED 凭据的安全权衡（官方原文要点）
.env.example 冲突数据分区明确说明：推荐 email+password 方式（token 每 24 小时过期，服务端自动换新）；凭据明文存于 .env.local 是「自托管仪表盘可接受的权衡」——文件被 gitignore、ACLED 账号只读免费、手工每 24 小时轮换不现实；介意明文者改用 ACLED_ACCESS_TOKEN 并接受每日手工刷新。
5.4 扩展分区（按需启用）
.env.example 在 741 行之后还有 14 个扩展分区：Market & Financial / Energy / Economic & Trade / Climate / Cyber Threat Intelligence / Web Scraping & Search / External datasets (Supabase·R2) / OAuth (Discord·Slack) / Web Push (VAPID) / Auth·anti-abuse / internal keys / Intelligence Brief pipeline / notification relay tuning / Seed & forecast feature flags。官方总原则（分区头原文）：「Everything below is optional. Each key unlocks one feature, seed, or integration; the dashboard runs without them」——每个 key 只解锁一个功能，缺了就优雅降级。全集见仓库 .env.example（1297 行）。
六、前端 VITE_ 开关（构建期变量）
.env.example「Site Configuration」分区与各功能分区共定义 19 个 VITE_* 开关（实测全量提取）：
VITE_CLERK_PUBLISHABLE_KEY VITE_CLOUD_PREFS_ENABLED VITE_CONVEX_URL
VITE_DIGEST_CRON_ENABLED VITE_DODO_ENVIRONMENT VITE_ENABLE_AIS
VITE_ENABLE_CYBER_LAYER VITE_FOLLOW_COUNTRIES_ENABLED
VITE_MAP_INTERACTION_MODE VITE_PMTILES_URL VITE_PMTILES_URL_PUBLIC
VITE_QUIET_HOURS_BATCH_ENABLED VITE_RELAY_GATES_READY VITE_RSS_DIRECT_TO_RELAY
VITE_SENTRY_DSN VITE_TELEGRAM_BOT_USERNAME VITE_VARIANT
VITE_WS_API_URL VITE_WS_RELAY_URL
自托管相关的高频项：
| 变量 | 默认 | 说明 |
|---|---|---|
VITE_VARIANT | full | 站点变体：full（worldmonitor.app）或 tech（tech.worldmonitor.app） |
VITE_WS_API_URL | 空 | 浏览器 /api/* 重定向目标；留空 = 同域 API（本地安装默认）；官方托管填 https://api.worldmonitor.app |
VITE_MAP_INTERACTION_MODE | 3d | 地图交互：3d 允许俯仰/旋转，flat 锁 2D |
VITE_PMTILES_URL / VITE_PMTILES_URL_PUBLIC | 空（用免费 OpenFreeMap 瓦片） | 自托管 PMTiles 瓦片（Cloudflare R2 或任意 HTTP 服务）；_PUBLIC 供无 CORS 反代后的 Tauri 桌面端直连 |
VITE_SENTRY_DSN | 空（禁用） | 客户端错误上报 |
VITE_ENABLE_AIS / VITE_ENABLE_CYBER_LAYER | — | 船舶 AIS 层 / 网络威胁层显示开关 |
⚠️ 生效边界（实测确认）：
VITE_*是 Vite 构建期变量，Docker Compose 的运行环境变量不会传给已构建的前端；.dockerignore又排除了.env*。因此 Compose 栈内前端按代码内置默认值构建——要改VITE_VARIANT、VITE_PMTILES_URL等，需在镜像构建环境注入（构建时导出变量或改用静态导出流程npm run build:pro && npx vite build），然后docker compose build重建。VITE_WS_API_URL留空的「同域 API」正是 Compose 单端口形态的推荐值，无需改动。
七、seeders 与脚本运行参数
7.1 run-seeders.sh（种子灌数主脚本）
实测源码要点（scripts/run-seeders.sh）：
| 参数 | 默认 | 说明 |
|---|---|---|
SEED_TIMEOUT | 1800 秒 | 单脚本墙钟上限，超时 timeout -k 30 强杀并打印 TIMEOUT (killed after Nss)；设 0 关闭上限 |
UPSTASH_REDIS_REST_URL | http://localhost:8079 | 脚本默认打宿主回环的 REST 代理（与 compose 的 127.0.0.1:8079 对应） |
UPSTASH_REDIS_REST_TOKEN / REDIS_TOKEN | — | 脚本从 .env 读取；REDIS_TOKEN 优先级更高（源码注释：This script targets the LOCAL Docker REST proxy, so REDIS_TOKEN always wins） |
| 其余 API key | — | 脚本同样从 .env 读取各 seeder 专属 key（如 NASA_FIRMS） |
生产建议（SELF_HOSTING.md 示例）：cron 定时补数 */30 * * * * cd /opt/worldmonitor && ./scripts/run-seeders.sh；脚本自带 SEED_TIMEOUT 截断，不会因单个上游挂死拖死整轮。
7.2 其他脚本侧变量（.env.example 实测定位）
OPENSKY_CLIENT_ID/OPENSKY_CLIENT_SECRET（358-359 行）：军航追踪 OAuth 客户端（经中继消费）；WM_MCP_ENDPOINT/WM_MCP_BEARER（1119-1120 行）：脚本与集成侧指向 MCP 服务端的端点与 Bearer；SEED_FALLBACK_DISPLACEMENT/SEED_FALLBACK_NOTAMESH（1079-1080 行）：流离失所与 NOTAM 种子的回退开关。
八、常见配置问题（FAQ）
Q1：docker compose up -d 报 required variable ... is missing a value？
四个必填密钥缺一。.env 补齐 openssl rand -hex 32 生成的 RELAY_SHARED_SECRET/REDIS_PASSWORD/REDIS_TOKEN/WM_SESSION_SECRET 后重建。实测报错与解法详见部署指南 4.1 节。
Q2：改了 .env 里的 key，面板还是空？
compose 只在 up -d 时重新插值，restart 不重读环境。执行 docker compose -p <项目名> up -d（会按需 Recreate）后再看；同时确认对应 seeder 重跑过（key 只是解锁抓取，缓存仍要种子脚本去填）。
Q3：设了 WM_TRUSTED_PROXY_CIDRS 后栈起不来？
该值由 docker/render-nginx-realip.mjs 校验，非法 CIDR 直接报 Invalid IP or CIDR in WM_TRUSTED_PROXY_CIDRS: [...] 退出。逐项检查 /24、/12 等掩码写法；直连形态请清空该变量。
Q4：ACLED 面板一直 401？
ACLED token 每 24 小时过期。推荐 ACLED_EMAIL + ACLED_PASSWORD 自动刷新；用 ACLED_ACCESS_TOKEN 静态令牌则需每日手工换新。注意 compose 会把 ACLED_EMAIL/ACLED_PASSWORD/ACLED_ACCESS_TOKEN 三个都注入主服务（见 3.1），改后需 up -d 重建。
Q5：LLM 简报面板不出现？
依次检查：LLM_API_URL 是否完整到 /v1/chat/completions；或只配 OLLAMA_API_URL（LLM_API_URL 优先）；OpenRouter 免费档 50 次/天额度是否耗尽（次日重置）。主机名容器内解析不了时在 override 加 extra_hosts。配置正确后面板自动出现，无需改前端开关。
Q6：改 VITE_VARIANT / VITE_PMTILES_URL 没生效？
VITE_* 是构建期变量且 .dockerignore 排除 .env*，运行时注入无效。在构建环境注入后 docker compose build 重建，或走静态导出自托管路径。见第六章生效边界。
Q7：redis-rest 偶发 413 或内存飙高？
单请求体上限 SRH_MAX_BODY_BYTES 默认 16MB，代理整体缓冲请求体（源码实测注释：64 并发 16MB POST 约 933MB RSS），容器 mem_limit: 512m 兜底。确需放大请求体时同步上调内存上限，并评估并发量。
Q8：seeders 大量 FAIL / TIMEOUT？
FAIL = 优雅降级（无 key 或上游不可达，不中断后续脚本）；TIMEOUT (killed after 1800s) = 单脚本超时被强杀。按需补 key 重跑；调试卡死脚本可临时 SEED_TIMEOUT=60 ./scripts/run-seeders.sh 快速暴露。
Q9：/api/local-... 全部 403？
LOCAL_API_MODE=docker 的设计行为：自托管模式无权益后端，管理路由一律拒绝，sidecar 令牌不授予管理员权限。运维改动一律走 .env/override + up -d 重建（详见部署指南 FAQ Q5）。
九、参考链接
- 环境变量全集（本文主要依据，1297 行 / 282 变量 / 37 分区）：https://github.com/koala73/worldmonitor/blob/main/.env.example
- docker-compose.yml（四服务注入表与安全注释原文）：https://github.com/koala73/worldmonitor/blob/main/docker-compose.yml
- 自托管指南（必填密钥、LLM 接线、cron 示例）：https://github.com/koala73/worldmonitor/blob/main/SELF_HOSTING.md
- 可信代理渲染器源码：https://github.com/koala73/worldmonitor/blob/main/docker/render-nginx-realip.mjs
- 种子脚本（SEED_TIMEOUT 机制）：https://github.com/koala73/worldmonitor/blob/main/scripts/run-seeders.sh
- 项目仓库与当前版本：https://github.com/koala73/worldmonitor （v2.11.4，查询日期 2026-10-25）
- 本专栏前置阅读：《worldmonitor v2.11.4 Docker Compose 部署指南》