release: bump version to 0.61.0

docs/CHANGELOG.md

@@ -8,6 +8,22 @@ This project follows the repository versioning rule:
 - `improvement` -> `+0.0.1`（bugfix + 小功能混合）
 - `bugfix` -> `+0.0.1`
 
+## [0.61.0] — 2026-05-18
+
+Released: 2026-05-18
+
+### Highlights
+- 新增 Earth 图层 Redis 读穿缓存、防击穿锁、stale 兜底和 payload budget，降低演示前重图层与船只 snapshot 对后端内存的冲击。
+- 保持前端原 API 不变，为海缆、登陆点、卫星、算力中心、BGP、summary 和船只 snapshot 增加透明缓存 header 可观测性。
+- 新增 super admin Earth 图层缓存状态与清理接口，并在采集写入后按 source 主动失效相关缓存。
+
+### Added / Fixed / Improved
+- 新增 `earth:layer:v1:*` 缓存命名空间、fresh/stale 双 key、Redis 故障 bypass 和 OOM 防护诊断。
+- 船只 snapshot 使用短 TTL、bbox 量化和响应预算，避免重复视窗请求和超大 payload 触发后端 OOM。
+- 补充 Earth layer cache 计划文档与后端测试，覆盖 hit、refresh、stale、bypass、锁竞争、cache header 和运维清理。
+
+---
+
 ## [0.60.0] — 2026-05-17
 
 Released: 2026-05-17

docs/plans/earth-layer-redis-cache-oom-guard-plan.md

@@ -0,0 +1,71 @@
+# Earth 图层 Redis 缓存与 OOM 防护完整计划
+
+## Summary
+
+目标不是单纯“加缓存”，而是把 Earth 图层读路径改成可控、可观测、可降级的缓存架构，避免演示前高并发、重图层、船只数据膨胀再次把后端打到 OOM 无限重启。
+
+前端继续请求原 API，response body 保持兼容。后端新增 Redis 读穿缓存、防击穿锁、stale 兜底、payload budget、主动失效、观测 header 和日志。
+
+更新架构图：
+
+```mermaid
+flowchart TD
+  Earth["Earth 前端<br/>原 API 不变"] --> API["FastAPI Visualization / Layers APIs"]
+
+  API --> Guard["Request Guard<br/>limit clamp / bbox required / payload budget"]
+  Guard --> Cache["Layer Cache Adapter<br/>key / TTL / lock / stale"]
+  Cache -->|fresh hit| Redis["Redis<br/>earth:layer:v1:*<br/>fresh + stale payloads"]
+  Cache -->|miss or refresh| Builder["Layer Builders<br/>DB query + GeoJSON conversion"]
+  Builder --> DB["PostgreSQL / Timescale<br/>authoritative data"]
+  Builder --> Budget["Response Budget Check<br/>feature cap / byte cap / diagnostics"]
+  Budget --> Cache
+  Cache --> API
+  API --> Earth
+
+  Collectors["Collectors / Data writes"] --> DB
+  Collectors --> Invalidate["Source-scoped invalidation"]
+  Invalidate --> Redis
+
+  Cache --> Metrics["Structured logs / headers<br/>hit miss stale bypass refresh<br/>bytes features duration"]
+```
+
+## Implementation Changes
+
+- Add an Earth layer cache adapter that owns Redis keys, TTLs, stale fallback, single-flight locks, JSON serialization, response headers, and graceful Redis bypass.
+- Use `earth:layer:v1:{layer}:{params}` for fresh cache, `earth:layer:v1:{layer}:{params}:stale` for stale fallback, and `earth:layer:lock:v1:{hash}` for rebuild locks.
+- Cache policy:
+  - `cables`, `landing-points`: fresh `6h`, stale `24h`
+  - `satellites`: fresh `15m`, stale `2h`
+  - `compute-centers`: fresh `10m`, stale `1h`
+  - `bgp-collectors`, `bgp-anomalies`, `bgp-incidents`, `geo/summary`: fresh `30-60s`, stale `10m`
+  - `vessels snapshot`: fresh `5s`, stale `30s`, with bbox rounded to `0.1` degrees and key including `zoom/type/limit/since_minutes`
+- Prevent cache stampedes with `SET NX EX` locks. The lock holder refreshes; other requests prefer stale, wait briefly, then fall back to the guarded DB path.
+- Enforce payload budgets on every cached layer: maximum features, maximum serialized bytes, and diagnostics when truncation happens.
+- Keep vessel snapshot viewport-first: require bbox, clamp low-zoom limits, never build an unbounded all-vessel GeoJSON for Earth startup.
+- Add cache observability headers: `X-Planet-Cache`, `X-Planet-Cache-Features`, `X-Planet-Cache-Bytes`, and development-only `X-Planet-Cache-Key`.
+- Add super-admin system endpoints for Earth layer cache status and clearing.
+
+## Public Interfaces
+
+- Frontend request URLs stay unchanged.
+- Response bodies stay compatible.
+- New optional response headers report cache state.
+- New system endpoints:
+  - `GET /api/v1/system/cache/earth-layers`
+  - `DELETE /api/v1/system/cache/earth-layers`
+- Redis key contract: `earth:layer:v1:*`. Existing news keys remain `earth_news:target_location:*`.
+
+## Test Plan
+
+- Unit-test key generation, bbox rounding, payload budget truncation, Redis miss/hit, stale fallback, Redis bypass, and single-flight lock behavior.
+- API-test repeated requests for cache headers, super-admin cache status/clear endpoints, and vessel snapshot bbox/limit safeguards.
+- Regression-test existing layer guard behavior and vessel type forwarding.
+- Verify Redis outage does not break Earth API responses.
+- Verify large vessel requests return bounded payload diagnostics instead of exhausting memory.
+
+## Assumptions
+
+- PostgreSQL remains the authoritative data source; Redis is disposable read-through cache.
+- First phase does not change frontend rendering. If Three.js rendering becomes the bottleneck, that is a separate frontend performance task.
+- When safety conflicts with completeness, vessel responses prefer bounded/truncated data plus diagnostics over risking backend OOM.
+- GeoJSON schema changes should bump the Redis key version from `v1` to `v2`.

docs/version-history.md

@@ -16,12 +16,13 @@
 ## Current Version
 
 - `main` 当前主线历史推导到：`0.16.5`
-- `dev` 当前开发分支历史推导到：`0.60.0`
+- `dev` 当前开发分支历史推导到：`0.61.0`
 
 ## Timeline
 
 | Version | Type | Branch | Commit | Summary |
 | --- | --- | --- | --- | --- |
+| `0.61.0` | feature | `dev` | `pending` | Earth 图层新增 Redis 读穿缓存、防击穿、stale 兜底、payload budget、缓存状态/清理接口和采集后主动失效，降低船只与重图层演示 OOM 风险 |
 | `0.60.0` | feature | `dev` | `pending` | Earth 内容/国界运行体验、新闻中文摘要展示、AI Provider 纯净边界和提示词运维配置落地，并补充 Agent Runtime 与 Earth LLM 指令计划 |
 | `0.59.0` | feature | `dev` | `pending` | Earth 国界迁移为静态资产并恢复低精 fallback，新增工具栏高精构建进度、后台 Earth 内容/采集管理拆分、AI task prompt 管理和新闻锚点队列补丁链路 |
 | `0.58.0` | feature | `dev` | `pending` | Earth 高精度国界切换到 PMTiles/MVT 和标准源采集器，移除旧低精度兜底，修复远距地表 z-fighting 雪花/黑块，并补齐新闻目标地点队列与文档 |