> ## Documentation Index > Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # 桌面应用 > World Monitor Tauri 桌面应用架构深度详解：涵盖 Rust sidecar 进程管理、系统密钥链安全存储、云端 API 回退策略、离线缓存机制、自动更新流程，以及 Windows、macOS、Linux 的多平台构建、代码签名与公证发布流水线的完整实现细节。 ## 概览 ### 桌面应用（Tauri） * **原生桌面应用**，支持 macOS、Windows 和 Linux —— 打包完整的仪表盘，并附带一个本地 Node.js sidecar，在本地运行全部 60+ 个 API 处理器 * **OS 钥匙串集成** —— API 密钥存储在系统凭据管理器中（macOS Keychain、Windows Credential Manager），绝不以明文文件形式存储 * **Token 鉴权的 sidecar** —— 一个唯一的会话 token 防止其他本地进程访问 localhost 上的 sidecar。每次启动时通过随机化哈希生成 * **云端回退** —— 当本地 API 处理器失败或缺失时，请求会透明地回退到云端部署（worldmonitor.app），并剥离 Origin 头 * **设置窗口** —— 专用配置 UI（Cmd+,），包含三个标签页：**LLMs**（Ollama 端点、模型选择、Groq、OpenRouter）、**API Keys**（12+ 个数据源凭据，逐键校验）以及 **Debug & Logs**（流量日志、详细模式、日志文件）。每个标签页运行独立的校验流水线 —— 在 LLMs 标签页保存不会阻塞 API Keys 的校验 * **自动模型发现** —— 当你在 LLMs 标签页设置 Ollama 或 LM Studio 的端点 URL 时，设置面板会立即查询其可用模型（先尝试 Ollama 原生 `/api/tags`，再尝试 OpenAI 兼容的 `/v1/models`），并填充下拉菜单。Embedding 模型会被过滤掉。如果发现失败，会显示一个手动文本输入作为回退 * **跨窗口密钥同步** —— 主仪表盘和设置窗口运行在独立的 webview 中，具有独立的 JS 上下文。在 Settings 中保存密钥时会写入 OS 钥匙串并广播一个 `localStorage` 变更事件。主窗口监听此事件并热重载所有密钥，无需重启应用 * **合并式钥匙串保险库** —— 所有密钥作为一个 JSON blob 存储在单个钥匙串条目（`secrets-vault`）中，而非每个密钥一个条目。这将每次应用启动时的 macOS Keychain 授权提示从 20+ 次减少到正好 1 次。一次性迁移会读取现有任何单独条目，合并它们，并清理旧格式 * **详细调试模式** —— 切换流量日志，状态在重启后保持。查看最近 200 个请求，包含时序、状态码和错误详情 * **DevTools 切换** —— Cmd+Alt+I 打开嵌入式 web 检查器进行调试 * **自动更新检查器** —— 每 6 小时轮询云端 API 检查新版本。显示非侵入式更新徽章，附带直接下载链接，并支持按版本忽略。具备变体感知能力 —— Tech Monitor 桌面应用会链接到正确的 Tech Monitor 发布资产 ## 多平台架构 全部六个变体运行在三个相互协作的平台上： ``` ┌─────────────────────────────────────┐ │ Vercel (Edge) │ │ 60+ edge functions · static SPA │ │ Proto gateway (24 typed services) │ │ CORS allowlist · Redis cache │ │ AI pipeline · market analytics │ │ CDN caching (s-maxage) · PWA host │ └──────────┬─────────────┬────────────┘ │ │ fallback │ ▼ │ ┌───────────────────────────────────┐ │ │ Tauri Desktop (Rust + Node) │ │ │ OS keychain · Token-auth sidecar │ │ │ 60+ local API handlers · br/gzip │ │ │ Cloud fallback · Traffic logging │ │ └───────────────────────────────────┘ │ │ https:// (server-side) │ wss:// (client-side) ▼ ┌──────────────────────────────────────────┐ │ Railway (Relay Server) │ │ AIS WebSocket · OpenSky OAuth2 │ │ Telegram MTProto (26 OSINT channels) │ │ OREF rocket alerts (residential proxy) │ │ Polymarket proxy (queue backpressure) │ │ ICAO NOTAM · RSS proxy · gzip all resp │ └──────────────────────────────────────────┘ ``` **为什么需要两个平台？** 一些上游 API（OpenSky Network、CNN RSS、UN News、CISA、IAEA）会主动屏蔽来自 Vercel IP 段的请求，还有一些需要持久连接或 edge function 不支持的协议。Railway 中继服务器作为备用源站，负责处理： * **AIS 船舶追踪** —— 维护到 AISStream.io 的持久 WebSocket 连接，并将其多路复用到所有已连接的浏览器客户端，避免触发每用户连接限制 * **OpenSky 航空器数据** —— 通过 OAuth2 client credentials 流程进行认证（Vercel IP 在没有 auth token 时会被 OpenSky 返回 403） * **Telegram 情报** —— 一个 GramJS MTProto 客户端以 60 秒为周期轮询 26 个 OSINT 频道，具备逐频道超时和 FLOOD\_WAIT 处理 * **OREF 火箭警报** —— 通过 `curl` 经住宅代理轮询以色列后方司令部警报系统（Akamai WAF 会屏蔽数据中心的 TLS 指纹） * **Polymarket 代理** —— 从 Gamma API 拉取，带有并发上游限流（最多 3 个同时请求，队列背压阈值为 20）、在途请求去重，以及 10 分钟缓存，以防止来自 11 个并行标签查询的踩踏 * **ICAO NOTAM 代理** —— 通过中继路由 MENA 机场的 NOTAM 关闭查询，绕过 ICAO API 上对 Vercel IP 的限制 * **GDELT 正面事件** —— 一个 15 分钟的 cron 任务拉取三个主题化的 GDELT GEO API 查询（突破/可再生能源、保护/人道、志愿/慈善），按事件名去重，校验坐标，按类别分类，并以 45 分钟 TTL 写入 Redis。这取代了直接调用 Vercel Edge Function 的方式 —— 后者因 GDELT 约 31 秒的顺序响应时间超过 25 秒的 edge 超时，在 99.9% 的调用中失败。已注册 bootstrap 水合，使 Happy 变体在首次渲染时即有数据 * **RSS feeds** —— 代理来自屏蔽 Vercel IP 的域名的 feeds，并带有独立的域名白名单以保证安全。支持条件 GET（ETag/If-Modified-Since）以减少未变更 feeds 的带宽消耗 Vercel edge function 通过 `WS_RELAY_URL`（服务端，HTTPS）连接到 Railway，而浏览器客户端通过 `VITE_WS_RELAY_URL`（客户端，WSS）连接。这种分离使中继 URL 可按部署配置，而不会把服务端配置泄露给浏览器。 当客户端接受且负载超过 1KB 时，所有 Railway 中继响应都会进行 gzip 压缩（zlib `gzipSync`），可减少 JSON 与 XML 响应约 80% 的出口流量。桌面本地 sidecar 现在优先使用 Brotli（`br`），对于大于 1KB 的负载回退到 gzip，自动设置 `Content-Encoding` 与 `Vary: Accept-Encoding`。 ## 桌面应用架构 Tauri 桌面应用将仪表盘封装在一个原生窗口中（macOS、Windows、Linux），并附带一个本地 Node.js sidecar，运行全部 API 处理器而无需依赖云端： ``` ┌─────────────────────────────────────────────────┐ │ Tauri (Rust) │ │ Window management · Consolidated keychain vault│ │ Token generation · Log management · Menu bar │ │ Polymarket native TLS bridge │ └─────────────────────┬───────────────────────────┘ │ spawn + env vars ▼ ┌─────────────────────────────────────────────────┐ │ Node.js Sidecar (dynamic port) │ │ 60+ API handlers · Local RSS proxy │ │ Brotli/Gzip compression · Cloud fallback │ │ Traffic logging · Verbose debug mode │ └─────────────────────┬───────────────────────────┘ │ fetch (on local failure) ▼ ┌─────────────────────────────────────────────────┐ │ Cloud (worldmonitor.app) │ │ Transparent fallback when local handlers fail │ └─────────────────────────────────────────────────┘ ``` ## 密钥管理 API 密钥存储在操作系统的凭据管理器中（macOS Keychain、Windows Credential Manager）—— 绝不以明文配置文件形式存储。所有密钥都合并到钥匙串中的单个 JSON 保险库条目里，因此无论配置了多少密钥，应用启动都只需要一次 OS 授权提示。 sidecar 启动时，会读取保险库、解析，并作为环境变量注入。空值或仅含空白字符的值会被跳过。密钥也可以在运行时更新而无需重启 sidecar：在 Settings 窗口保存密钥会触发一次 `POST /api/local-env-update` 调用，热补丁 `process.env`，使处理器立即取到新值。 **校验流水线** —— 当你在 Settings 中输入凭据时，应用会针对实际的提供商 API 进行校验（Groq → `/openai/v1/models`，Ollama → `/api/tags`，FRED → GDP 测试查询，NASA FIRMS → 火灾数据拉取等）。网络错误（超时、DNS 失败、主机不可达）被视为软通过 —— 密钥会被保存并附带"无法验证"提示，而不会阻塞。只有来自提供商的明确 401/403 响应才会将密钥标记为无效。这防止了临时网络问题把用户锁在自己的凭据之外。 **智能重新校验** —— 保存设置时，校验流水线会跳过自上次成功校验以来未修改的密钥。这避免了当用户只改动一个密钥但已有 15 个已配置且校验通过的密钥时，对提供商 API 产生不必要的往返请求。只有新输入或修改过的密钥才会触发校验请求。 **桌面端特有要求** —— 一些功能在桌面端需要的凭据比 Web 端更少。例如，Web 端的 AIS 船舶追踪同时需要中继 URL 和 API 密钥，但桌面 sidecar 在内部处理中继连接，因此只需要 API 密钥。设置面板会根据检测到的平台调整其必填字段显示。 ### 桌面运行时配置 Schema World Monitor 桌面端使用一个运行时配置 schema，具备按功能切换的开关与密钥支撑的凭据。 ### 密钥 桌面保险库 schema（Rust `SUPPORTED_SECRET_KEYS`）支持以下 25 个密钥： * `GROQ_API_KEY` * `OPENROUTER_API_KEY` * `FRED_API_KEY` * `EIA_API_KEY` * `FINNHUB_API_KEY` * `CLOUDFLARE_API_TOKEN` * `ACLED_ACCESS_TOKEN` * `URLHAUS_AUTH_KEY` * `OTX_API_KEY` * `ABUSEIPDB_API_KEY` * `NASA_FIRMS_API_KEY` * `WINGBITS_API_KEY` * `WS_RELAY_URL` * `VITE_WS_RELAY_URL` * `VITE_OPENSKY_RELAY_URL` * `OPENSKY_CLIENT_ID` * `OPENSKY_CLIENT_SECRET` * `AISSTREAM_API_KEY` * `OLLAMA_API_URL` * `OLLAMA_MODEL` * `WORLDMONITOR_API_KEY` —— 控制云端回退访问（最少 16 字符） * `WTO_API_KEY` * `AVIATIONSTACK_API` * `ICAO_API_KEY` * `UCDP_ACCESS_TOKEN` ### 功能 schema 每个功能包含： * `id`：稳定的功能标识符。 * `requiredSecrets`：必须存在且有效的密钥列表。 * `enabled`：来自运行时设置面板的用户切换状态。 * `available`：计算值（`enabled && requiredSecrets valid`）。 * `fallback`：面向用户的降级行为描述。 ### 桌面密钥存储 桌面构建通过 Tauri 命令绑定将密钥持久化到 OS 凭据存储中，底层为 Rust `keyring` 条目（`world-monitor` 服务命名空间）。 前端**不会以明文文件形式存储**密钥。 ### 降级行为 若所需密钥缺失/被禁用： * 摘要：Groq/OpenRouter 被禁用，回退到浏览器模型。 * FRED / EIA / Finnhub：经济、石油分析和股票数据返回空状态。 * Cloudflare / ACLED：中断/冲突返回空状态。 * 网络威胁 feeds（URLhaus、OTX、AbuseIPDB）：网络威胁图层返回空状态。 * NASA FIRMS：卫星火灾检测返回空状态。 * Wingbits：航班增强被禁用，仅保留基于启发式的航班分类。 * AIS / OpenSky 中继：实时追踪功能被干净地禁用。 * World Monitor API 密钥：云端回退被阻塞；桌面端仅以本地模式运行。 ## Sidecar ### Sidecar 鉴权 每次应用启动时，通过随机化哈希状态（Rust 标准库的 `RandomState`）生成一个唯一的 32 字符十六进制 token。该 token 会： 1. 作为 `LOCAL_API_TOKEN` 注入 sidecar 2. 前端通过 `get_local_api_token` Tauri 命令获取（在首次 API 请求时懒加载） 3. 作为 `Authorization: Bearer ` 附加到每个本地请求 `/api/service-status` 健康检查端点免除 token 校验，以支持监控工具。 ### 动态端口分配 sidecar 默认使用端口 46123，但会优雅地处理 `EADDRINUSE` —— 如果端口被占用（另一个 World Monitor 实例，或任何其他进程），sidecar 会绑定到端口 0 并让 OS 分配一个可用的临时端口。实际绑定的端口会写入一个端口文件（日志目录中的 `sidecar.port`），Rust 宿主在启动时轮询该文件（100 毫秒间隔，5 秒超时）。前端在运行时通过 `get_local_api_port` IPC 命令发现端口，`runtime.ts` 中的 `getApiBaseUrl()` 是规范的访问器 —— 禁止在前端代码中硬编码端口 46123。CSP 的 `connect-src` 指令使用 `http://127.0.0.1:*` 以适配任意端口。 ### 本地 RSS 代理 sidecar 内置了一个 RSS 代理处理器，直接从源域名拉取新闻 feeds，完全绕过云端 RSS 代理。这意味着桌面应用可以加载全部 500+ 个 RSS feeds 而无需任何云端依赖 —— Vercel edge 代理使用的相同域名白名单会在本地强制执行。结合本地 API 处理器，这使桌面应用能够作为一个完全自包含的情报聚合平台运行。 ### Sidecar 弹性 sidecar 采用多种弹性模式，以在上游 API 降级时维持数据可用性： * **出错时返回旧数据** —— 当上游 API 返回 5xx 错误或超时时，sidecar 从其内存缓存中提供最后一次成功响应，而非传播失败。面板会显示旧数据并附带可视的"重试中"指示器，而不是变空白 * **负缓存** —— 上游失败后，sidecar 会记录一个 5 分钟的负缓存条目，以防止立即重新命中同一故障端点。冷却期间的后续请求会立即收到旧响应 * **错峰请求** —— 具有严格速率限制的 API（Yahoo Finance）使用顺序请求批处理，请求间延迟 150 毫秒，而非 `Promise.all`。这会把 10 个并发请求（会触发 HTTP 429）转换为一个保持在速率限制之下的错峰序列 * **在途请求去重** —— 对同一资源的并发请求（例如多个面板轮询同一端点）被合并为单次上游拉取。第一个请求创建一个 Promise 存储在在途映射中；所有并发请求都等待该单个 Promise * **面板重试指示器** —— 当面板的数据拉取失败并重试时，Panel 基类会显示一个非侵入式的"Retrying..."指示器，让用户理解仪表盘正在自我修复而非已损坏 ## 云端回退 当本地 API 处理器缺失、抛出错误或返回 5xx 状态时，sidecar 会透明地将请求代理到云端部署。失败的端点会被标记为 `cloudPreferred` —— 后续请求会跳过本地处理器并直接访问云端，直到 sidecar 重启。代理前会剥离 Origin 和 Referer 头，以维持服务端到服务端的对等。 ## 可观测性 * **流量日志** —— 最近 200 个请求的环形缓冲区，包含方法、路径、状态和耗时（毫秒），可通过 `GET /api/local-traffic-log` 访问 * **详细模式** —— 通过 `POST /api/local-debug-toggle` 切换，在 `verbose-mode.json` 中跨 sidecar 重启持久化 * **双日志文件** —— `desktop.log` 捕获 Rust 端事件（启动、密钥注入计数、菜单操作），而 `local-api.log` 捕获 Node.js 的 stdout/stderr * **强制 IPv4 拉取** —— sidecar 补丁 `globalThis.fetch` 以对所有出站请求强制使用 IPv4。政府 API（NASA FIRMS、EIA、FRED）发布 AAAA DNS 记录，但其 IPv6 端点经常超时。该补丁使用 `node:https` 并设置 `family: 4` 以绕过 Happy Eyeballs，避免级联的 ETIMEDOUT 失败 * **DevTools** —— `Cmd+Alt+I` 切换嵌入式 web 检查器 ## 自动更新 桌面应用通过轮询 `worldmonitor.app/api/version` 检查新版本 —— 启动时一次（延迟 5 秒），之后每 6 小时一次。当检测到较新版本时（semver 比较），会出现一个非侵入式的更新徽章，附带指向 GitHub Release 页面的直接链接。 更新提示可按版本忽略 —— 忽略 v2.5.0 不会抑制 v2.6.0 的通知。更新器具备变体感知能力：Tech Monitor 桌面构建会链接到 Tech Monitor 的发布资产，而非 full 变体。 `/api/version` 端点会读取最新的 GitHub Release 标签并将结果缓存 1 小时，因此版本检查不会在每次请求时都命中 GitHub API。