星海图志 · Sky Monitor
从你头顶的这片夜空出发，一直走到可观测宇宙的边界。
一个位置感知的观星项目：FastAPI 星图后端计算“此时此地能看到什么”，
three.js 前端把它画成一张跨越 16 个数量级的交互星图，以及一片真实的今晚星空。
在线体验 sky.eunoia.top · 今晚星空 · 尺度巡游 · 开发者手册 · Swagger · 服务监控台
演示录屏（2 倍速）。高清版：docs/media/demo.mp4
效果展示
三维宇宙图谱
左侧的尺度阶梯可以一键飞往各个尺度，从太阳系、恒星邻域、银河系、本星系群，一直到可观测宇宙。恒星采用 HYG 星表中约 10.9 万颗星的真实三维位置，亮度按镜头所在位置实时计算。
今晚星空
仿照 Star Walk 的观测者视角，按你所在的位置和时间呈现真实天空。
- 真实的星光：
- 大小和眩光：按星等等级决定。零等星和负等星带光晕和十字芒。
- 颜色：按色指数着色。亮星颜色饱和，暗星偏灰白，和人眼看到的一致。
- 闪烁：每颗星有自己的节奏，越靠近地平线越强。低空的亮星会出现彩色闪烁，比如冬夜低空的天狼星。
- 大气消光：地平线附近的星光会变暗。
- 黄道：
- ±8° 的黄道带，配十二宫和二十四节气。
- 太阳所在的宫和节气会高亮。
- 太阳的信息卡给出黄经、当前节气和下一个节气的日期。
- 二十八宿：
- 朱砂色星官连线，宿界画在过距星的赤经圈上。
- 显示四象名称：东方苍龙、北方玄武、西方白虎、南方朱雀。
- 月亮的信息卡显示“月宿”，太阳的信息卡显示“日躔”。
- 交互：
- 拖拽环顾，滚轮或双指缩放。
- 时间胶囊可以前后拨动，也可以加速播放。
- 手机上可以开启陀螺仪，直接对准天空。
- 信息卡给出高度、方位、升起/中天/落下时间，还可以一键跳回三维图谱。
- 今晚推荐：直接来自本仓库的
/sky/chart 接口；后端不可达时自动改用本地计算。
- 中英双语：默认英文，右上角一键切换中文（也可用
?lang=zh / ?lang=en），选择会被记住。
- 服务目录：首页“Services / 服务”菜单直达开发者手册、服务监控台、Swagger、ReDoc、OpenAPI 和健康检查。
架构
https://sky.eunoia.top (nginx，同域)
┌──────────────────────┴──────────────────────┐
/, /tonight, /tour, /assets, /data /sky/*, /docs, /wiki, /health ...
│ │
atlas/ (Vite + TypeScript + three.js) app/ (FastAPI + Skyfield)
三维宇宙图谱 · 今晚星空 星表查询 · 星图投影 · 推理语料
└──────────── POST /sky/chart ────────────────┘
| 目录 | 内容 |
|---|
atlas/ | 前端星图，详见 atlas/README.md |
app/ | FastAPI 入口、天文计算、SQLite 星表查询、深空天体、推理语料 |
data/ | 可提交的中文观测语料 |
scripts/ | 下载 HYG 星表和 DE421 星历，构建 SQLite 星表和城市索引 |
site/wiki/ | 开发者手册（/wiki，含 API 参数、示例、灵珠接入、架构、部署和在线试用；/wiki/api 跳转到其 API 部分）和服务监控台（/wiki/health），共用 wiki.css，与星图同一配色 |
deploy/ | systemd 和 nginx 示例（含前端路由） |
docs/media/ | README 用的截图和录屏 |
tests/ | 后端单元测试 |
快速开始
后端
推荐 Python 3.10 或更高版本。
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python scripts/download_hyg.py # HYG 恒星星表
python scripts/build_catalog_db.py # 构建 SQLite 星表
python scripts/download_ephemeris.py # JPL DE421 星历
python scripts/build_city_index.py # 手册“在线试用”用的城市坐标索引（可选）
uvicorn app.main:app --host 0.0.0.0 --port 8000
启动后可以打开：http://127.0.0.1:8000/health、http://127.0.0.1:8000/docs、http://127.0.0.1:8000/sky/chart?latitude=31.4591&longitude=121.1298&total_limit=8
前端
cd atlas
npm install
npm run dev # http://localhost:5173 ，/sky-api 代理到线上后端
npm run build # 产物在 atlas/dist/
前端在 atlas/public/data/ 中自带烘焙好的星表，可以直接运行。用 npm run data 可以从后端下载的 HYG CSV 重新生成。
后端 API
功能概览：
- 根据 GPS 坐标和时间计算地平坐标系下的高度角和方位角，默认返回地平线以上（≥ 0°）的目标，最多 100 个（
total_limit 可到 300）。
- 恒星来自 HYG Database；深空天体为完整梅西耶目录 M1–M110 加 5 个著名 NGC/Melotte 目标；太阳、月亮和七大行星用 Skyfield + JPL DE421 计算，含星等。
- 先按
star_max_mag、deep_sky_max_mag、min_altitude_deg 筛选，再按亮度统一排序后截取，各类别没有固定数量。
category 取值：star、deep_sky、planet、sun、moon（日月的 object_type 分别为 sun、moon），完整说明见开发者手册。/sky/chart 返回 chart_x、chart_y、chart_radius，前端可以直接绘制极坐标星图。可以用 time_utc 指定观测时间。reasoning_context 提供中文观测建议和目标解释，便于 LLM 工具调用。- OpenAPI 的
servers 可以通过环境变量配置，适合接入灵珠等只接受 HTTPS 域名的工具平台。
健康检查
curl "https://sky.eunoia.top/health"
# {"status": "ok", "version": "0.4.0", "catalog_db_exists": true}
生成星图
curl "https://sky.eunoia.top/sky/chart?latitude=31.4591&longitude=121.1298&total_limit=8"
curl -X POST "https://sky.eunoia.top/sky/chart" \
-H "Content-Type: application/json" \
-d '{
"latitude": 31.4591,
"longitude": 121.1298,
"min_altitude_deg": 0,
"star_max_mag": 3,
"deep_sky_max_mag": 9,
"total_limit": 100
}'
关键返回结构：
{
"sky_chart": {
"observer": { "lat": 31.4591, "lon": 121.1298 },
"time_utc": "2026-05-17T03:00:00Z",
"coordinate_system": { "chart_projection": "polar_azimuthal_horizon" },
"counts": { "star": 69, "deep_sky": 28, "planet": 2, "moon": 1 },
"objects": [
{
"category": "star",
"display_name": "南河三",
"azimuth_deg": 242.65,
"altitude_deg": 44.83,
"magnitude": 0.4,
"chart_x": -0.4965,
"chart_y": -0.2567,
"chart_radius": 0.5019
}
],
"reasoning_context": {
"corpus_version": "0.1.0",
"summary": "当前位置纬度 31.4591、经度 121.1298，本次筛选得到 8 个适合星图展示的目标。",
"bullets": [],
"object_insights": []
}
}
}
其他接口
curl "https://sky.eunoia.top/reasoning/corpus" # 生成 reasoning_context 用的中文观测语料
curl "https://sky.eunoia.top/catalog/stats"
curl "https://sky.eunoia.top/stars/bright?limit=20"
curl "https://sky.eunoia.top/stars/search?name=Sirius"
灵珠平台接入
推荐导入 OpenAPI：https://sky.eunoia.top/openapi.json。工具主动作建议选 GET /sky/chart，参数只需要传 latitude 和 longitude（Query，number），其他筛选参数用后端默认值。
环境变量
复制 .env.example 作为参考：
| 变量 | 默认值 | 说明 |
|---|
SKY_CATALOG_DB | data/catalog.db | SQLite 星表路径 |
SKY_PUBLIC_BASE_URL | https://sky.eunoia.top | OpenAPI servers[0].url |
部署
# 后端：FastAPI 绑定 127.0.0.1:8000，由 systemd 托管
sudo cp deploy/lingzhuback.service /etc/systemd/system/lingzhuback.service
sudo systemctl daemon-reload
sudo systemctl enable --now lingzhuback
# 前端：构建后发布到 nginx 静态目录
cd atlas && npm run build
sudo mkdir -p /var/www/sky-atlas && sudo cp -r dist /var/www/sky-atlas/site
# nginx：星图为首页，其余路径反向代理到后端
sudo cp deploy/nginx.example.conf /etc/nginx/sites-available/sky-monitor-api
sudo ln -s /etc/nginx/sites-available/sky-monitor-api /etc/nginx/sites-enabled/sky-monitor-api
sudo nginx -t && sudo systemctl reload nginx
线上部署建议：
- 使用 HTTPS 域名访问，不要暴露“裸 IP + 端口”。
- 设置
SKY_PUBLIC_BASE_URL 为你的域名。
- 前后端同域部署时，前端直接请求
/sky/chart，不需要配置 CORS。
测试
pytest -q # 后端：请求模型、星表构建与查询、推理语料
cd atlas && npm run build # 前端：TypeScript 类型检查 + 构建
数据与许可证
代码采用 MIT License。第三方数据遵循各自的许可：
| 数据 | 许可 | 仓库中的形式 |
|---|
| HYG Database v3 | CC BY-SA 2.5 | 后端原始 CSV 不提交（脚本下载）；前端提交烘焙后的 atlas/public/data/stars.bin、named.json |
| JPL DE421 | 公有领域 | 不提交，脚本下载 |
| d3-celestial 星座 / 中国星官数据 | BSD-3-Clause | atlas/public/data/constellations.json、mansions.json，附 CONSTELLATIONS-LICENSE.txt |
| GeoNames cities1000 | CC BY 4.0 | 不提交，脚本生成 |
| OpenNGC（梅西耶目录坐标核对与取值） | CC BY-SA 4.0 | 坐标写入 app/deep_sky.py |
