NASA Astronomy Picture of the Day Mirror

APOD Server

一个带缓存、可观测性和容错能力的 NASA APOD 镜像服务。它为 APOD 元数据和图片提供稳定 API、缓存加速、限流、健康探针和 Prometheus/Grafana 观测能力。

请求今日 APOD 查看今日图片健康检查

核心特性

多级缓存

内存缓存 + Redis 持久缓存，并使用 singleflight 合并同 key 并发请求，降低上游压力。

图片落盘缓存

图片本地缓存，支持热数据保留、冷数据按时间和容量清理。

可观测性

结构化日志、Trace ID、Prometheus 指标和 Grafana 仪表盘。

API 优化

Gzip、ETag、Cache-Control、限流、健康检查和优雅关闭。

安全默认值

Bearer Token 认证、常量时间密钥比较、metrics 独立密钥、生产默认关闭匿名 DEMO_KEY。

容错抓取

NASA API 与网页解析兜底，定时预抓取每日 APOD。

主要接口

`GET /v1/apod`

返回 APOD 元数据。支持 ?date=YYYY-MM-DD。

`GET /v1/apod/image`

当 APOD 是图片时返回 302，跳转到本地静态图片。

`GET /static/apod/YYYY-MM-DD.jpg`

公开图片直链，只返回本地已缓存图片，不触发上游抓取。

`GET /metrics`

Prometheus 指标端点，生产环境使用独立 Bearer Token。

`GET /healthz`

进程健康检查。

`GET /readyz`

文件系统、Redis 等依赖就绪检查。

请求示例

curl 'https://api.lyqgzbl.com/v1/apod'
curl 'https://api.lyqgzbl.com/v1/apod?date=2026-04-01'
curl -I 'https://api.lyqgzbl.com/v1/apod/image'
curl 'https://api.lyqgzbl.com/healthz'

响应摘要

/v1/apod 返回标题、日期、说明、媒体类型、图片缓存 URL 和原始高清 URL。
/v1/apod/image 对图片 APOD 返回 302 Found。
非法日期返回 400；认证失败返回 401；上游失败返回 502。
图片和静态缓存使用 Cache-Control: public, max-age=86400。

部署与配置

API_AUTH_KEY=your_app_api_key \
METRICS_AUTH_KEY=your_metrics_api_key \
GF_SECURITY_ADMIN_PASSWORD=your_grafana_password \
NASA_API_KEY=your_nasa_api_key \
docker compose up -d

关键环境变量

NASA_API_KEY: NASA API Key，避免 DEMO_KEY 配额瓶颈。
API_AUTH_KEY: 业务 API 访问密钥。
METRICS_AUTH_KEY: metrics 独立认证密钥。
REDIS_ADDR: Redis 地址。
TRUSTED_PROXIES: 可信反向代理 IP/CIDR。

缓存与观测

缓存策略

今日数据默认内存 TTL 3 小时、Redis TTL 48 小时；历史数据 Redis TTL 30 天；图片最近 7 天视为热数据。