网络摄像头图层

​

数据源：Windy Webcams API v3

​

API 提供的内容

​

免费层限制

• 图像令牌 URL 在 10 分钟后过期
• 边界框查询每次请求上限为 10,000 条结果（播种器使用自适应象限分割来规避此限制）
• 适用速率限制（播种器使用顺序区域抓取）

​

API 密钥配置

• 播种器 优雅退出，提示 “WINDY_API_KEY not set, skipping webcam seed”
• 图像处理器 返回 { error: 'unavailable' }，工具提示显示 “Preview unavailable”
• 地图图层 仍会根据缓存的地理数据渲染标记（如果先前已播种），但图像预览不可用

​

架构

Seed (periodic):
  Windy API → seed-webcams.mjs → Redis (geo index + metadata hash)

Runtime:
  Browser map viewport → listWebcams RPC → Redis geo search → clustered response
  User clicks marker → getWebcamImage RPC → Windy API (cached 5 min) → tooltip with preview
  User pins webcam → localStorage → PinnedWebcamsPanel (2x2 iframe grid)

​

服务端聚类

​

缓存

​

预期延迟行为

1. 地图视口切换 → listWebcams RPC → 服务器执行 Redis 地理搜索，构建聚类响应，并缓存。后续相同视口会立即从 Redis 缓存返回（24h TTL）。
2. 首次点击网络摄像头标记 → getWebcamImage RPC → 服务器调用 Windy API（到外部服务的网络往返），服务器端缓存响应 5 分钟。客户端也会缓存 9 分钟 — 因此在 9 分钟内重新点击同一网络摄像头是即时的，无需服务器调用。
3. 固定网络摄像头 → 播放器 iframe 从 Windy 的 CDN 加载（嵌入页面的又一次外部往返）。我们不缓存此项 — 由浏览器处理 iframe 缓存。

​

Redis 数据是临时的

​

无自动重新播种（已知缺口）

• 从主机运行 scripts/seed-webcams.mjs
• 运行 scripts/run-seeders.sh（运行包括网络摄像头在内的所有播种器）
• Railway cron（推荐）：将 seed-webcams.mjs 作为 Railway cron 服务每 12-18 小时调度一次，以领先于 24 小时 TTL 过期

​

固定网络摄像头面板

​

功能

• 2x2 iframe 网格：同时可见四个活动的网络摄像头播放器
• 开关切换：网络摄像头可在活动（在网格中显示）和非活动（仅在列表中）之间切换
• 溢出列表：当固定超过 4 个网络摄像头时，网格下方会出现一个可滚动列表，用于管理所有固定项
• 从任何渲染器固定：固定按钮出现在所有三种地图渲染器（SVG、Globe、DeckGL）的网络摄像头工具提示中
• 持久化：固定的网络摄像头通过 localStorage 在页面刷新后保留
• 自定义事件：当固定项从任何来源发生变化时，面板会响应式更新

​

存储

webcamId, title, lat, lng, category, country, playerUrl, active (boolean), pinnedAt (timestamp)

​

当前限制

​

非实时视频

• “播放器”是近期快照的延时回放，而非实时流
• 无法通过 Windy API 筛选实时流摄像头
• 实时态势感知仅限于最近采集的图像（在工具提示预览中可见）

​

免费层不存在实时视频 API

​

其他限制

• 免费层署名：Windy 在使用免费 API 层时要求署名
• 图像令牌过期：来自 Windy 的预览图像 URL 约 10 分钟后过期；对于过期的工具提示需要重新抓取
• 播种覆盖范围：播种器将每个区域边界框的摄像头上限设为 10K；自适应象限分割可缓解此问题，但非常密集的区域可能仍会遗漏摄像头
• 无状态筛选：非活动/离线摄像头可能以预览损坏的形式出现在地图上
• iframe 沙箱：播放器 iframe 使用 allow-scripts allow-same-origin allow-popups 沙箱策略

​

未来阶段

​

第 2 阶段：US DOT 511 州 API

​

第 3 阶段：OpenWebcamDB