Compare commits

...
7 Commits
Author SHA1 Message Date
rayd1o dd176a6ae6 release: bump version to 0.57.0
ci / backend (push) Has been cancelled
ci / frontend (push) Has been cancelled
release / images (push) Has been cancelled
ci / delivery (push) Has been cancelled
2026-05-14 01:02:17 +08:00
linkong f14ff6ec0f release: bump version to 0.56.0
ci / backend (push) Has been cancelled
ci / frontend (push) Has been cancelled
ci / delivery (push) Has been cancelled
release / images (push) Has been cancelled
2026-05-13 18:21:03 +08:00
linkong 39854b9983 release: bump version to 0.55.0
ci / backend (push) Has been cancelled
ci / frontend (push) Has been cancelled
ci / delivery (push) Has been cancelled
release / images (push) Has been cancelled
2026-05-13 15:31:29 +08:00
linkong 3b4347c87d release: bump version to 0.54.0
ci / backend (push) Has been cancelled
ci / frontend (push) Has been cancelled
ci / delivery (push) Has been cancelled
release / images (push) Has been cancelled
2026-05-13 14:26:47 +08:00
rayd1o d9efd98d26 release: bump version to 0.53.0
ci / backend (push) Has been cancelled
ci / frontend (push) Has been cancelled
ci / delivery (push) Has been cancelled
release / images (push) Has been cancelled
2026-05-13 08:05:43 +08:00
linkong b87cb310fd release: bump version to 0.52.0 2026-05-12 17:15:02 +08:00
linkong b15d097b9c default user 2026-05-12 09:20:13 +08:00
138 changed files with 10398 additions and 3174 deletions

No files matched your search

+10
View File
@@ -46,6 +46,16 @@ rg -n "class |def |function |export |router|@router|interface |type " <path>
- Keep filenames lowercase and hyphenated.
- Apply the repository-specific rules file before writing.
#### Document Audience Routing (Planet)
In this repository, classify the action's performer before picking a target file:
- Browser/UI end user → `docs/technical/{zh,en}/manual.md` or `quickstart.md`.
- Shell / Docker / log paths / `planet.sh` / SMTP fallbacks / port forwarding → `docs/technical/{zh,en}/ops-runbook.md` (or an existing `ops-*.md`).
- Second-party developers → existing `*-context.md` / `backend-*.md` / `earth-*.md` files.
Never put shell commands, log paths, or Docker operations into `manual.md` / `quickstart.md`. Never put UI button labels or screenshots into `ops-*.md`. When the same action has both a UI and a CLI path, write each in its own home and cross-link them with one sentence.
For ambiguous or large documentation changes, briefly state the intended doc plan before editing. For clear small changes, proceed directly.
### Step 3 — Write
+5
View File
@@ -2,9 +2,14 @@
!pyproject.toml
!uv.lock
!VERSION
!backend/
!backend/**
!aiprovider/
!aiprovider/**
backend/.env
backend/.env.*
aiprovider/.env
aiprovider/.env.*
!aiprovider/.env.example
+64
View File
@@ -0,0 +1,64 @@
name: ci
on:
push:
branches:
- dev
- main
pull_request:
env:
REGISTRY: gitea.rclaw.top
IMAGE_NAMESPACE: linkong/planet
jobs:
backend:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
run: curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Sync Python dependencies
run: ~/.local/bin/uv sync --group dev
- name: Run backend smoke tests
working-directory: backend
run: PYTHONPATH=. "$GITHUB_WORKSPACE/.venv/bin/python" -m pytest -s tests/test_api.py tests/test_realtime_sources.py -q
frontend:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Bun
run: curl -fsSL https://bun.sh/install | bash
- name: Build frontend
working-directory: frontend
run: |
~/.bun/bin/bun install --frozen-lockfile
~/.bun/bin/bun run build
delivery:
runs-on: ubuntu-latest
needs:
- backend
- frontend
steps:
- uses: actions/checkout@v4
- name: Install Helm
run: |
mkdir -p "$HOME/.local/bin"
curl -fsSL https://get.helm.sh/helm-v3.15.4-linux-amd64.tar.gz -o /tmp/helm.tar.gz
tar -xzf /tmp/helm.tar.gz -C /tmp
mv /tmp/linux-amd64/helm "$HOME/.local/bin/helm"
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Docker build smoke
run: |
docker build -t "$REGISTRY/$IMAGE_NAMESPACE/frontend:${GITHUB_SHA}" ./frontend
docker build -t "$REGISTRY/$IMAGE_NAMESPACE/backend:${GITHUB_SHA}" -f backend/Dockerfile .
docker build -t "$REGISTRY/$IMAGE_NAMESPACE/aiprovider:${GITHUB_SHA}" -f aiprovider/Dockerfile .
- name: Helm template smoke
run: |
helm lint deploy/helm/planet
helm template planet-staging deploy/helm/planet \
--namespace planet-staging \
-f deploy/helm/planet/values.single-node.yaml \
--set image.tag="${GITHUB_SHA}" >/tmp/planet-rendered.yaml
+67
View File
@@ -0,0 +1,67 @@
name: deploy-staging
on:
workflow_dispatch:
push:
branches:
- main
env:
REGISTRY: gitea.rclaw.top
IMAGE_NAMESPACE: linkong/planet
RELEASE_NAME: planet-staging
NAMESPACE: planet-staging
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install deploy tools
run: |
mkdir -p "$HOME/.local/bin"
curl -fsSL https://get.helm.sh/helm-v3.15.4-linux-amd64.tar.gz -o /tmp/helm.tar.gz
tar -xzf /tmp/helm.tar.gz -C /tmp
mv /tmp/linux-amd64/helm "$HOME/.local/bin/helm"
curl -fsSL https://dl.k8s.io/release/v1.30.5/bin/linux/amd64/kubectl -o /tmp/kubectl
install -m 0755 /tmp/kubectl "$HOME/.local/bin/kubectl"
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Configure kubeconfig
run: |
mkdir -p "$HOME/.kube"
printf "%s" "${{ secrets.KUBE_CONFIG_STAGING }}" | base64 -d > "$HOME/.kube/config"
chmod 600 "$HOME/.kube/config"
- name: Deploy Helm release
run: |
kubectl create namespace "$NAMESPACE" --dry-run=client -o yaml | kubectl apply -f -
helm upgrade --install "$RELEASE_NAME" deploy/helm/planet \
--namespace "$NAMESPACE" \
-f deploy/helm/planet/values.single-node.yaml \
--set global.imageRegistry="$REGISTRY" \
--set global.imageNamespace="$IMAGE_NAMESPACE" \
--set image.tag="${GITHUB_SHA}"
- name: Wait for rollout
run: |
kubectl rollout status deployment/planet-frontend -n "$NAMESPACE" --timeout=180s
kubectl rollout status deployment/planet-backend -n "$NAMESPACE" --timeout=180s
kubectl rollout status deployment/planet-aiprovider -n "$NAMESPACE" --timeout=180s
- name: Smoke test services
run: |
kubectl run planet-smoke-${GITHUB_RUN_NUMBER} \
--rm -i --restart=Never \
--namespace "$NAMESPACE" \
--image=curlimages/curl:8.11.1 \
--command -- sh -c '
set -eu
curl -fsS http://planet-frontend:3000/ >/dev/null
curl -fsS http://planet-frontend:3000/health >/dev/null
curl -fsS http://planet-frontend:3000/api/health >/dev/null
curl -fsS http://planet-backend:8000/health >/dev/null
curl -fsS http://planet-aiprovider:8010/health >/dev/null
'
- name: Collect diagnostics on failure
if: failure()
run: |
kubectl get all -n "$NAMESPACE" -o wide || true
kubectl describe pods -n "$NAMESPACE" || true
kubectl logs -n "$NAMESPACE" -l app.kubernetes.io/instance="$RELEASE_NAME" --all-containers --tail=200 || true
+58
View File
@@ -0,0 +1,58 @@
name: release
on:
push:
branches:
- main
tags:
- "v*"
workflow_dispatch:
env:
REGISTRY: gitea.rclaw.top
IMAGE_NAMESPACE: linkong/planet
jobs:
images:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Resolve image tags
id: meta
run: |
echo "sha_tag=${GITHUB_SHA}" >> "$GITHUB_OUTPUT"
if printf "%s" "${GITHUB_REF}" | grep -q '^refs/tags/v'; then
echo "release_tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
else
echo "release_tag=" >> "$GITHUB_OUTPUT"
fi
- name: Login to registry
run: echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login "$REGISTRY" -u "${{ secrets.REGISTRY_USER }}" --password-stdin
- name: Build and push images
run: |
for service in frontend backend aiprovider; do
case "$service" in
frontend)
dockerfile="./frontend/Dockerfile"
context="./frontend"
;;
backend)
dockerfile="backend/Dockerfile"
context="."
;;
aiprovider)
dockerfile="aiprovider/Dockerfile"
context="."
;;
esac
image="$REGISTRY/$IMAGE_NAMESPACE/$service:${{ steps.meta.outputs.sha_tag }}"
docker build -t "$image" -f "$dockerfile" "$context"
docker push "$image"
if [ -n "${{ steps.meta.outputs.release_tag }}" ]; then
release_image="$REGISTRY/$IMAGE_NAMESPACE/$service:${{ steps.meta.outputs.release_tag }}"
docker tag "$image" "$release_image"
docker push "$release_image"
fi
done
+8 -22
View File
@@ -275,38 +275,24 @@ curl http://localhost:8000/health
在常见的 WSL2 开发环境下,Windows 通常可以直接通过 `localhost` 访问 WSL 中的服务。
### 4. 如果需要让局域网设备访问,再做 Windows 端口转发
### 4. 如果需要让局域网设备访问,使用临时 Windows relay
注意:下面的命令必须在“以管理员身份运行”的 PowerShell 中执行。
`./planet.sh start --allow-lan` 在 WSL 下会优先使用临时 Windows relay:WSL 和 Windows 本机 `localhost` 仍使用 `3000` / `8000`,局域网设备访问 Windows 局域网 IP 的 `3000` / `8000` 时由 relay 转发。relay 由脚本启动和停止;如果 WSL 目标端口断开,relay 会自动退出并释放 Windows 局域网监听端口。
先把 Windows 对外网卡上的 `3000` / `8000` 转发到 Windows 本机 `127.0.0.1`:
如果以前手动配置过持久 `portproxy`,脚本会在启动前检测 `3000` / `8000` 残留规则,并请求管理员 PowerShell 自动删除。若自动请求被取消,可以手动清理,避免 `iphlpsvc` 继续占用 `3000` / `8000`:
```powershell
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
```
再放行 Windows 防火墙:
脚本会检测 Windows 防火墙是否已放行 `3000` / `8000`。如果缺少规则,会触发一次 Windows UAC 管理员 PowerShell 请求来自动创建。若自动请求被取消,也可以手动执行:
```powershell
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
检查转发规则是否生效:
```powershell
netsh interface portproxy show all
```
预期能看到:
- `0.0.0.0:3000 -> 127.0.0.1:3000`
- `0.0.0.0:8000 -> 127.0.0.1:8000`
### 5. 查 Windows 局域网 IP,并让其他设备访问
在 Windows PowerShell 中执行:
@@ -329,7 +315,7 @@ ipconfig
### 6. 常见现象与判断
- WSL 中 `curl localhost:3000` 能通,但 Windows 访问 `WSL 的局域网 IP:3000` 不通:这是正常现象之一,优先验证 Windows 的 `localhost:3000`
- Windows `localhost:3000` 能通,但局域网设备访问 `Windows 局域网 IP:3000` 不通:通常缺少 `portproxy` 或防火墙放行
- Windows `localhost:3000` 能通,但局域网设备访问 `Windows 局域网 IP:3000` 不通:通常是 Windows 防火墙、网络配置或旧 `portproxy` 残留
- `whoami /groups` 中 `S-1-5-32-544` 显示 `deny only`:说明当前 PowerShell 不是提权管理员窗口
### 7. 本项目一次性验证顺序
@@ -340,8 +326,8 @@ ipconfig
2. WSL 中执行 `curl http://localhost:8000/health`
3. Windows 中执行 `curl http://localhost:3000`
4. Windows 中执行 `curl http://localhost:8000/health`
5. 管理员 PowerShell 配置 `portproxy` 和防火墙
6. 用手机或其他电脑访问 `http://<Windows局域网IP>:3000/earth`
5. 按脚本提示完成 Windows 防火墙 UAC 请求;如果曾手动配置过 `portproxy`,先清理旧规则
6. 用手机或其他电脑访问 Windows 对外端口,例如 `http://<Windows局域网IP>:3000/earth`
## 启动容错参数
@@ -365,7 +351,7 @@ DATABASE_RETRY_INTERVAL=10 \
- `AI_PROVIDER_START_MAX_RETRIES` / `AI_PROVIDER_RETRY_INTERVAL`: 控制 `aiprovider` 的构建/启动与容器重启自愈,默认 `3` 次、`5` 秒
- `BACKEND_MAX_RETRIES`: 控制后端进程启动重试次数,默认 `3`
- `FRONTEND_MAX_RETRIES`: 控制前端 dev server 启动重试次数,默认 `3`
- `BACKEND_HEALTH_CHECK_ATTEMPTS` / `BACKEND_HEALTH_CHECK_INTERVAL`: 控制后端 HTTP 健康检查等待次数与间隔,默认 `10` 次、`2` 秒
- `BACKEND_HEALTH_CHECK_ATTEMPTS` / `BACKEND_HEALTH_CHECK_INTERVAL`: 控制后端 HTTP 健康检查等待次数与间隔,默认 `60` 次、`2` 秒
- `FRONTEND_HEALTH_CHECK_ATTEMPTS` / `FRONTEND_HEALTH_CHECK_INTERVAL`: 控制前端 HTTP 可访问检查等待次数与间隔,默认 `10` 次、`2` 秒
- `AI_PROVIDER_HEALTH_CHECK_ATTEMPTS` / `AI_PROVIDER_HEALTH_CHECK_INTERVAL`: 控制 `aiprovider` HTTP 健康检查等待次数与间隔,默认 `10` 次、`2` 秒
+69 -43
View File
@@ -1,45 +1,71 @@
# TODO
- [x] 把 BGP 观测站和异常点的 `hover/click` 手感再磨细一点
- [x] 开始做 BGP 异常和海缆/区域的关联展示
- [x] 做 Earth 侧的 `BGP activity layer`,让低 incident 密度时地图仍然有持续可感知的观测存在感
- [x] 给 Earth BGP 补三层状态表达:`平稳观测态 / 局部波动态 / 事件活跃态`
- [x] 把“当前无活跃事件”改造成“观测网络仍在运行、当前未发现聚合级事件”的状态表达
- [x] 做 collector / region 近 15 分钟 activity score 聚合接口或动态聚合逻辑
- [x] 把 Earth 的 BGP incident 改成 `紧凑事件核 + 向外扩张环形 pulse`,替换当前大面积 glow
- [x] 为 BGP incident 建立符号系统:按事件类型用不同 marker,而不是都用同一种亮点
- [x] 把 incident 地理定位从 `collector-centric` 改成 `prefix-centric`,优先使用 `prefix_geography`,其次 `prefix_scope`,再次 ASN 区域,最后才回退到观测区域质心
- [x] 新增 `prefix_geography` 数据层,不再把 `prefix_scope` 当成 prefix 地理归属本身
- [x] 接入 `IPtoASN / IPtoCountry` 作为 prefix-centric geography 的主数据源
- [x] 接入 `OpenGeoFeed` 作为 prefix geography 的高质量覆盖/override 数据源
- [x] 把 RIR delegated 设计成 prefix geography 的 fallback,而不是主来源
- [ ] 为 `aiprovider` 建立 `provider -> api adapter -> compat policy` 的配置中心,优先落成 `json` 或 `yaml` 文件,运行时按 `provider/model` 读取兼容设置,而不是把专项兼容继续散落在 Python 分支里
- [ ] 为市面上主流 AI 服务补专项兼容配置并固化到配置文件中,至少覆盖 `OpenAI / Anthropic / MiniMax / Ollama / Moonshot / DeepSeek / Qwen / GLM / Gemini / OpenRouter / vLLM / LM Studio / One API`
- [ ] 在兼容配置中补齐可声明项:`api adapter`、`base_url pattern`、`auth header`、`thinking default`、`reasoning block mapping`、`stream path`、`tool-call capability`、`multimodal capability`、`provider-specific request patch`
- [ ] 接入 `inetnum` / `inet6num` whois 作为比 RIR 更细粒度的后备层
- [x] 在 activity layer 之后继续补 `route leak` 和 `path instability / flap` detector
- [ ] 对 [frontend/public/earth/js/bgp.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp.js) 做按职责拆分的小重构,拆成 data / markers / overlays / animation,降低后续维护复杂度
- [ ] 可选优化(非必做):将 BGP incident/collector 标点改为 HTML marker(参考 worldmonitor 的 `htmlElementsData` 思路),实现近乎固定屏幕尺寸与更高密度可点击性
- [ ] 保持 Earth 当前这批纯个人偏好设置继续走本地持久化:`旋转模式`、HUD 面板显示/隐藏、`地形透明度` 暂不升级到后端系统设置,避免把设备级偏好过早做成全局配置
- [ ] 如果后续明确需要“账号级同步 Earth 偏好”,再单独设计 `Earth user preferences`:优先按用户维度而不是全局系统设置保存,并规划 `localStorage -> backend` 的平滑迁移策略
- [ ] 为 Planet / Earth 补一个可用的日志查看系统:先明确前后端/AI Provider/采集任务的日志入口、最近日志聚合、筛选与 tail 能力,再决定是先做脚本级统一入口还是控制台内置日志面板
- [ ] 重写控制台 UI,逐步抛弃 Ant Design,建立自有组件体系,并统一采用 `tabler.io` / Tabler Icons 作为控制台主图标库
- [ ] 把 Earth 态势新闻源从 [earth_news.py](/home/ray/dev/linkong/planet/backend/app/services/earth_news.py) 的硬编码列表抽成可配置目录,优先保持当前“实时聚合”链路不变,只先解决新闻源不可配置的问题
- [ ] 为 Earth 态势新闻设计后续采集器化方案:明确新闻数据模型、去重策略、区域映射、过期清理和 Earth/AI 复用方式,再决定何时把新闻从实时抓取升级成正式 collector
- [ ] AIS v3.1:修复船只聚合完整性,`/geo/vessels` 合并 raw observation 聚合结果与 legacy `vessel_position + vessel_static` 最新结果,确保 BarentsWatch-only 船只不会因为 AISStream 子集存在而消失,并增加 raw/legacy/final unique MMSI 诊断统计
- [ ] AIS v3.2:把 AISStream 从收满 `max_messages` 后结束的批采集改成长连接 streaming service,持续写入 raw observations,通过内部 `/ws` 的 `vessels` channel 推送新船、位置和航向增量,Earth 前端按 MMSI upsert marker
- [ ] AIS v3.3:修正 AISStream 采集页面状态语义,使用 connecting/streaming/reconnecting/stopped 与 indeterminate 状态,展示运行时长、消息数、unique MMSI、message rate、最近消息和错误,不再用一次性 REST 进度条表示长连接
- [ ] AIS v3.4:修复船只身份字段和名称聚合,MMSI/IMO/callsign 按字符串显示且不带千分位符;查询并列出所有仍以 MMSI 号码或 `MMSI <number>` 作为船名的记录,标注来源、最近观测、message types 和缺失原因,并把这批 fallback-name 船只纳入名称聚合修复集合
- [ ] Earth Live Sync:建立统一态势实时同步链路,新增 `earth_summary` WS channel,任意采集器成功后广播轻量 summary invalidation,前端收到后重新拉 `/api/v1/visualization/geo/summary` 并更新 HUD;同时为 BGP 增加 `bgp` WS channel,使 BGP incidents/anomalies/collectors 在不刷新页面时也能 upsert 图层;卫星采集完成后触发 summary 刷新,必要时按 TLE 版本重新 hydrate 卫星数据
- [ ] AIS v4:开放船只多源聚合策略配置,支持 source priority、字段级规则、freshness 窗口和高级保护开关;保存时校验未知字段、非法模式和危险动态字段锁定,并在聚合接口返回命中的配置版本
- [ ] AIS v5:实现船舶资料 enrichment 与冲突治理,按 `mmsi + imo + name + callsign` 异步补充船型细分、AIS 大类、旗国、尺寸、建造年份、运营方和图片缓存;详情面板展示缓存资料和字段来源,不在实时 AIS 请求链路现场抓第三方页面
- [ ] 为 Earth 地球表面增加一层与基础纹理对齐的材质/纹理 overlay,并在同层叠加国界轮廓参考线;要求国界线与底图稳定对齐,且 hover 到国家轮廓时能高亮当前国家,便于校准地表和增强交互
- [ ] 把 Earth 新闻接入通用巡航队列:按新闻发生地和时间排序生成巡航目标,巡航聚焦到新闻事件时显示对应新闻卡片,并保持实现边界为“通用巡航层 + 新闻业务适配层”,不要再把新闻逻辑直接耦合回 `main.js` 状态机
- [ ] 为未知位置的算力中心建立分层坐标补全链路:优先 `精确坐标 > 站点/园区命中 > 城市 > 州/省 > 国家内主要算力城市 > 国家质心`,并把每次回退的 `confidence / reason / precision` 明确写进统一 GeoJSON
- [ ] 为算力中心补一份可维护的本地位置注册表,例如 `canonical_name / aliases / operator / country / region / city / lat / lon / confidence / source_note`,避免把地点知识长期硬编码在 `visualization.py`
- [ ] 增强 `epoch_ai_gpu` 和相关算力采集器的源页面解析:即使公开 API 不给坐标,也继续尝试从详情页、HTML、内嵌 JSON、schema.org、OpenGraph、脚本变量和 PDF/新闻稿链接里抽地点线索
- [ ] 为未知位置算力中心增加外部富化策略评估:可选接入公开知识源或搜索兜底,只抓“站点名/园区名/城市名”级别线索,不直接抓经纬度结论,并把结果作为候选证据而不是真值
- [ ] 为算力中心建立 `operator / cluster name / facility alias` 归一化层,先解决 `xAI / Colossus / Memphis`、`OpenAI / Stargate`、`CoreWeave`、`Lambda`、`Crusoe` 这类同一对象多种写法导致的地点匹配失败
- [ ] 为估算位置增加更细的视觉和产品表达:除了问号角标,还要支持 tooltip/详情中的“估算依据”“精度级别”“最后核验时间”,并允许在设置中单独开关“仅看精确位置”
- [ ] 为国家级估算点设计更合理的落点策略:优先落在“该国主要算力/数据中心城市候选集”而不是几何质心,必要时同国多节点做稳定散列分配,避免大量节点堆在荒漠或海上
- [ ] 为未知位置算力中心建立人工校验工作流:支持导出待核验清单、记录人工确认结果,并把人工确认反哺到位置注册表,逐步减少问号点比例
This file is the active backlog only. Completed history belongs in `docs/CHANGELOG.md`; detailed designs belong in `docs/plans/`.
## Earth
- [ ] High-precision country boundaries: implement the source-faithful static vector tile pipeline described in [Earth High Precision Boundary Tiles Plan](/home/ray/dev/linkong/planet/docs/plans/earth-high-precision-boundary-tiles-plan.md). Highest zoom must preserve trusted source geometry instead of smoothing or hand-drawing borders.
- [ ] Earth boundary data: acquire or generate auditable China POV geometry for Zangnan, Aksai Chin, Taiwan/Penghu, Diaoyu Dao and affiliated islands, Chiwei Yu, South China Sea islands, and the official dashed maritime claim line before implementing visual changes.
- [ ] Presentation controller ownership: replace the singleton card fallback in [presentation-controller.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/presentation-controller.js) with a presentation/card token check before BGP/News migrate onto the shared controller, so connectors only attach to their owning card.
- [ ] BGP frontend maintainability: split [bgp.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp.js) by responsibility into data loading, marker rendering, overlays, and animation once the current interaction behavior is stable.
- [ ] Optional BGP marker experiment: evaluate HTML markers for BGP incident/collector points if WebGL marker density or fixed screen-size clickability becomes a real blocker.
- [ ] Earth news cruise: connect Earth news to the generic cruise queue via a news adapter rather than coupling news-specific sequencing into `main.js`.
## Compute Centers And Location
- [ ] Unknown compute-center locations: continue reducing unresolved records through the shared location pipeline, with confidence, precision, reason, and verification date preserved in GeoJSON/details.
- [ ] Compute-center registry: keep expanding the local canonical location registry with `canonical_name`, aliases, operator, country/region/city, coordinates, confidence, and source notes.
- [ ] Compute-center enrichment: improve source-page parsing for Epoch AI and related collectors by extracting location clues from detail pages, embedded JSON, schema.org, OpenGraph, script variables, PDFs, and press releases.
- [ ] Compute-center identity normalization: normalize operator / cluster / facility aliases such as `xAI / Colossus / Memphis`, `OpenAI / Stargate`, `CoreWeave`, `Lambda`, and `Crusoe`.
- [ ] Compute-center manual review: add an export/review/import workflow for unresolved or estimated locations and feed confirmed results back into the registry.
## AIS / Vessels
- [ ] AIS aggregation strategy v4: expose source priority, field-level merge rules, freshness windows, and protected dynamic-field rules in configuration, with validation and strategy version returned by vessel APIs.
- [ ] AIS vessel enrichment v5: add asynchronous vessel profile enrichment for ship type detail, AIS class, flag, dimensions, build year, operator, and cached media. Do not fetch third-party pages in the realtime AIS request path.
- [ ] AIS identity cleanup: continue identifying vessels whose display name is only `MMSI <number>` and backfill names from AISStream static messages, BarentsWatch static fields, or enrichment cache.
## AI Provider And Agents
- [ ] AI provider compatibility center: move provider/model compatibility rules into a JSON/YAML config read by runtime, instead of continuing to scatter provider-specific branches through Python code.
- [ ] Provider compatibility coverage: add explicit config for OpenAI, Anthropic, MiniMax, Ollama, Moonshot, DeepSeek, Qwen, GLM, Gemini, OpenRouter, vLLM, LM Studio, and One API.
- [ ] Compatibility schema: cover adapter type, base URL pattern, auth header, thinking/reasoning defaults, stream path, tool-call capability, multimodal capability, and provider-specific request patches.
- [ ] BGP geography fallback: evaluate `inetnum` / `inet6num` whois as a finer fallback layer after `prefix_geography`, `OpenGeoFeed`, and RIR delegated data.
## Platform
- [ ] Earth preferences scope: keep current device-local Earth preferences in `localStorage`; only design backend user preferences if account-level synchronization becomes a real product requirement.
- [ ] System logs: finish a usable Planet log viewing flow that covers backend, frontend, AI Provider, and collector/task logs, with filtering and tailing.
- [ ] Console UI modernization: gradually replace Ant Design with Planet-owned components and a consistent Tabler Icons based icon system.
- [ ] Earth live sync: design a unified realtime invalidation path for summary/BGP/satellite updates if polling and current WebSocket channels become insufficient.
## Archive
Archived items stay here so old context is not lost. Completed items remain checked; obsolete, invalid, or superseded items stay unchecked and include the reason.
### Completed
- [x] Refined BGP observer and anomaly `hover/click` feel.
- [x] Added BGP anomaly relationship display with cables / regions.
- [x] Added the Earth BGP activity layer so the map still feels alive when incident density is low.
- [x] Added BGP state expression for stable observation, local fluctuation, and active incident states.
- [x] Reframed "no active incident" as "observation network is running; no aggregate incident detected".
- [x] Added collector / region recent activity scoring.
- [x] Replaced oversized BGP incident glow with compact incident core plus outward pulse rings.
- [x] Added BGP incident symbol types instead of using one generic bright marker.
- [x] Switched BGP incident geography from collector-centric to prefix-centric priority.
- [x] Added `prefix_geography` as a separate data layer instead of treating `prefix_scope` as prefix geography.
- [x] Added IPtoASN / IPtoCountry as the main prefix-centric geography source.
- [x] Added OpenGeoFeed as a high-quality prefix geography override source.
- [x] Made RIR delegated data a prefix geography fallback rather than the primary source.
- [x] Added route leak and path instability / flap detectors after the activity layer work.
### Obsolete Or Superseded
- [ ] AIS v3.1 old `/geo/vessels` full-merge requirement. Superseded by `/api/v1/vessels/snapshot`, controlled legacy fallback, and diagnostics in the AIS aggregation plan.
- [ ] AIS v3.2 old framing of AISStream as a batch collector that needed conversion. Superseded by the implemented long-lived AISStream collector and realtime stream UI.
- [ ] AIS v3.3 old one-shot REST progress semantics for AISStream. Superseded by realtime stream status handling.
- [ ] AIS v3.4 broad identity cleanup wording. Folded into the active AIS identity cleanup and v5 enrichment tasks.
- [ ] Earth surface material overlay for boundary calibration. Superseded by the high-precision boundary tile plan; future work must use source-faithful boundary/coastline data rather than overlay calibration against the coarse base map.
- [ ] Hardcoded Earth news source extraction as a standalone task. Superseded by the broader Earth news source configuration and collector plans.
- [ ] Country-level compute-center fallback placement as a standalone task. Superseded by the shared location pipeline and registry/manual-review backlog.
+1 -1
View File
@@ -1 +1 @@
0.51.1
0.57.0
+4 -1
View File
@@ -27,4 +27,7 @@ COPY aiprovider /app/aiprovider
EXPOSE 8010
CMD ["uv", "run", "--frozen", "--no-dev", "--project", "/app", "python", "-m", "uvicorn", "aiprovider.main:app", "--host", "0.0.0.0", "--port", "8010", "--reload"]
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD curl -fsS http://127.0.0.1:8010/health >/dev/null || exit 1
CMD ["uv", "run", "--frozen", "--no-dev", "--project", "/app", "python", "-m", "uvicorn", "aiprovider.main:app", "--host", "0.0.0.0", "--port", "8010"]
+5 -1
View File
@@ -12,6 +12,7 @@ ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV UV_COMPILE_BYTECODE=1
ENV UV_LINK_MODE=copy
ENV PYTHONPATH=/app/backend
RUN apt-get update && apt-get install -y --no-install-recommends \
curl \
@@ -25,4 +26,7 @@ COPY VERSION /app/VERSION
EXPOSE 8000
CMD ["uv", "run", "--frozen", "--no-dev", "--project", "/app", "python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD curl -fsS http://127.0.0.1:8000/health >/dev/null || exit 1
CMD ["uv", "run", "--frozen", "--no-dev", "--project", "/app", "python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+8 -1
View File
@@ -8,14 +8,17 @@ from app.api.v1 import (
docs,
tasks,
dashboard,
websocket,
alerts,
settings,
collected_data,
data_products,
layers,
visualization,
vessel_aggregation,
vessels,
bgp,
news,
realtime_sources,
system_control,
tv,
)
@@ -36,12 +39,16 @@ api_router.include_router(dashboard.router, prefix="/dashboard", tags=["dashboar
api_router.include_router(alerts.router, prefix="/alerts", tags=["alerts"])
api_router.include_router(settings.router, prefix="/settings", tags=["settings"])
api_router.include_router(system_control.router, prefix="/system", tags=["system"])
api_router.include_router(data_products.router, prefix="/data-products", tags=["data-products"])
api_router.include_router(layers.router, prefix="/layers", tags=["layers"])
api_router.include_router(visualization.router, prefix="/visualization", tags=["visualization"])
api_router.include_router(
vessel_aggregation.router,
prefix="/vessel-aggregation",
tags=["vessel-aggregation"],
)
api_router.include_router(vessels.router, prefix="/vessels", tags=["vessels"])
api_router.include_router(bgp.router, prefix="/bgp", tags=["bgp"])
api_router.include_router(tv.router, prefix="/tv", tags=["tv"])
api_router.include_router(news.router, prefix="/news", tags=["news"])
api_router.include_router(realtime_sources.router, prefix="/realtime-sources", tags=["realtime-sources"])
+246 -23
View File
@@ -1,26 +1,85 @@
from datetime import timedelta
from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import text
from app.core.config import settings
from app.core.logging import get_logger
from app.core.security import (
create_access_token,
create_refresh_token,
blacklist_token,
get_current_user,
get_password_hash,
verify_password,
)
from app.db.session import get_db
from app.models.user import User
from app.schemas.token import Token
from app.schemas.user import UserCreate, UserResponse
from app.schemas.user import (
ForgotPasswordRequest,
ResendCodeRequest,
ResetPasswordRequest,
UserRegister,
UserResponse,
VerifyEmailRequest,
)
from app.services import otp
from app.services.email import (
EmailError,
EmailNotConfiguredError,
send_verification_email,
)
logger = get_logger(__name__)
router = APIRouter()
def _token_response(user: User) -> dict:
access_token = create_access_token(data={"sub": user.id})
refresh = create_refresh_token(data={"sub": user.id})
expires_in = (
settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60
if settings.ACCESS_TOKEN_EXPIRE_MINUTES > 0
else None
)
return {
"access_token": access_token,
"token_type": "bearer",
"expires_in": expires_in,
"refresh_token": refresh,
"user": {
"id": user.id,
"username": user.username,
"role": user.role,
"gatekeeper_groups": user.gatekeeper_groups or [],
},
}
async def _load_user_by_email(db: AsyncSession, email: str) -> User | None:
result = await db.execute(
text(
"SELECT id, username, email, password_hash, role, is_active, gatekeeper_groups, email_verified "
"FROM users WHERE email = :email"
),
{"email": email},
)
row = result.fetchone()
if row is None:
return None
user = User()
user.id = row[0]
user.username = row[1]
user.email = row[2]
user.password_hash = row[3]
user.role = row[4]
user.is_active = row[5]
user.gatekeeper_groups = row[6] or []
user.email_verified = bool(row[7])
return user
@router.post("/login", response_model=Token)
async def login(
form_data: OAuth2PasswordRequestForm = Depends(),
@@ -28,7 +87,8 @@ async def login(
):
result = await db.execute(
text(
"SELECT id, username, email, password_hash, role, is_active, gatekeeper_groups FROM users WHERE username = :username"
"SELECT id, username, email, password_hash, role, is_active, gatekeeper_groups, email_verified "
"FROM users WHERE username = :username"
),
{"username": form_data.username},
)
@@ -47,6 +107,7 @@ async def login(
user.role = row[4]
user.is_active = row[5]
user.gatekeeper_groups = row[6] or []
user.email_verified = bool(row[7])
if not verify_password(form_data.password, user.password_hash):
raise HTTPException(
@@ -58,25 +119,13 @@ async def login(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="User is inactive",
)
if not user.email_verified:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail={"code": "EMAIL_NOT_VERIFIED", "email": user.email},
)
access_token = create_access_token(data={"sub": user.id})
refresh_token = create_refresh_token(data={"sub": user.id})
expires_in = None
if settings.ACCESS_TOKEN_EXPIRE_MINUTES > 0:
expires_in = settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60
return {
"access_token": access_token,
"token_type": "bearer",
"expires_in": expires_in,
"user": {
"id": user.id,
"username": user.username,
"role": user.role,
"gatekeeper_groups": user.gatekeeper_groups or [],
},
}
return _token_response(user)
@router.post("/refresh", response_model=Token)
@@ -116,5 +165,179 @@ async def get_me(current_user: User = Depends(get_current_user)):
"role": current_user.role,
"gatekeeper_groups": current_user.gatekeeper_groups or [],
"is_active": current_user.is_active,
"email_verified": getattr(current_user, "email_verified", True),
"created_at": current_user.created_at,
}
async def _send_code_or_raise(db: AsyncSession, email: str, code: str, purpose: str) -> None:
try:
await send_verification_email(db, to=email, code=code, purpose=purpose)
except EmailNotConfiguredError as exc:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail={"code": exc.code, "message": str(exc)},
) from exc
except EmailError as exc:
logger.warning_event(
"SMTP send failed",
event="auth.email.send_failed",
context={"email": email, "purpose": purpose, "error": str(exc)},
)
raise HTTPException(
status_code=status.HTTP_502_BAD_GATEWAY,
detail={"code": exc.code, "message": str(exc)},
) from exc
@router.post("/register", status_code=status.HTTP_201_CREATED)
async def register(payload: UserRegister, db: AsyncSession = Depends(get_db)):
existing = await db.execute(
text("SELECT id, email_verified FROM users WHERE username = :u OR email = :e"),
{"u": payload.username, "e": payload.email},
)
row = existing.fetchone()
if row is not None:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail={"code": "USER_ALREADY_EXISTS", "message": "Username or email already in use"},
)
user = User(
username=payload.username,
email=payload.email,
password_hash=get_password_hash(payload.password),
role="viewer",
is_active=True,
email_verified=False,
)
db.add(user)
await db.commit()
try:
code = otp.issue_code(payload.email, "register")
except otp.OtpResendRateLimited as exc:
raise HTTPException(
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail={"code": exc.code, "retry_after_seconds": exc.retry_after_seconds},
) from exc
await _send_code_or_raise(db, payload.email, code, "register")
return {"status": "pending_verification", "email": payload.email}
@router.post("/verify-email", response_model=Token)
async def verify_email(payload: VerifyEmailRequest, db: AsyncSession = Depends(get_db)):
user = await _load_user_by_email(db, payload.email)
if user is None:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail={"code": "USER_NOT_FOUND"},
)
try:
otp.verify_code(payload.email, "register", payload.code)
except otp.OtpExpired as exc:
raise HTTPException(
status_code=status.HTTP_410_GONE,
detail={"code": exc.code, "message": str(exc)},
) from exc
except otp.OtpAttemptsExceeded as exc:
raise HTTPException(
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail={"code": exc.code, "message": str(exc)},
) from exc
except otp.OtpInvalid as exc:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail={"code": exc.code, "message": str(exc)},
) from exc
await db.execute(
text("UPDATE users SET email_verified = TRUE WHERE id = :id"),
{"id": user.id},
)
await db.commit()
user.email_verified = True
return _token_response(user)
@router.post("/resend-code")
async def resend_code(payload: ResendCodeRequest, db: AsyncSession = Depends(get_db)):
user = await _load_user_by_email(db, payload.email)
if user is None:
# Avoid email enumeration; pretend success.
return {"status": "ok"}
if payload.purpose == "register" and user.email_verified:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail={"code": "ALREADY_VERIFIED"},
)
try:
code = otp.issue_code(payload.email, payload.purpose)
except otp.OtpResendRateLimited as exc:
raise HTTPException(
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail={"code": exc.code, "retry_after_seconds": exc.retry_after_seconds},
) from exc
await _send_code_or_raise(db, payload.email, code, payload.purpose)
return {"status": "ok"}
@router.post("/forgot-password")
async def forgot_password(payload: ForgotPasswordRequest, db: AsyncSession = Depends(get_db)):
user = await _load_user_by_email(db, payload.email)
if user is None:
# Don't leak whether an email is registered.
return {"status": "ok"}
try:
code = otp.issue_code(payload.email, "reset_password")
except otp.OtpResendRateLimited:
# Silently accept; the user can retry after the cooldown.
return {"status": "ok"}
try:
await send_verification_email(db, to=payload.email, code=code, purpose="reset_password")
except EmailNotConfiguredError as exc:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail={"code": exc.code, "message": str(exc)},
) from exc
except EmailError as exc:
logger.warning_event(
"SMTP send failed",
event="auth.email.send_failed",
context={"email": payload.email, "purpose": "reset_password", "error": str(exc)},
)
return {"status": "ok"}
@router.post("/reset-password")
async def reset_password(payload: ResetPasswordRequest, db: AsyncSession = Depends(get_db)):
user = await _load_user_by_email(db, payload.email)
if user is None:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail={"code": "OTP_INVALID"},
)
try:
otp.verify_code(payload.email, "reset_password", payload.code)
except otp.OtpExpired as exc:
raise HTTPException(
status_code=status.HTTP_410_GONE,
detail={"code": exc.code, "message": str(exc)},
) from exc
except otp.OtpAttemptsExceeded as exc:
raise HTTPException(
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail={"code": exc.code, "message": str(exc)},
) from exc
except otp.OtpInvalid as exc:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail={"code": exc.code, "message": str(exc)},
) from exc
await db.execute(
text("UPDATE users SET password_hash = :p, email_verified = TRUE WHERE id = :id"),
{"p": get_password_hash(payload.new_password), "id": user.id},
)
await db.commit()
return {"status": "ok"}
+98
View File
@@ -0,0 +1,98 @@
from datetime import UTC, datetime
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.v1.visualization import get_visualization_geo_summary
from app.core.time import to_iso8601_utc
from app.db.session import get_db
router = APIRouter()
PRODUCT_DEFINITIONS: dict[str, dict] = {
"vessels": {
"name": "船只",
"sources": ["aisstream_vessels", "barentswatch_vessels"],
"primary_stat_key": "vessel_count",
"stat_keys": ["vessel_count", "vessel_raw_unique_mmsi", "vessel_legacy_unique_mmsi"],
},
"cables": {
"name": "海底光缆",
"sources": [
"arcgis_cables",
"arcgis_landing_points",
"arcgis_cable_landing_relation",
"telegeography_cables",
"telegeography_landing",
"telegeography_systems",
"fao_landing_points",
],
"primary_stat_key": "cable_count",
"stat_keys": ["cable_count", "landing_point_count"],
},
"satellites": {
"name": "卫星",
"sources": ["celestrak_tle", "spacetrack_tle"],
"primary_stat_key": "satellite_count",
"stat_keys": ["satellite_count"],
},
"bgp": {
"name": "BGP",
"sources": [
"ris_live_bgp",
"bgpstream_bgp",
"iptoasn_prefix_geo",
"opengeofeed_prefix_geo",
"nro_delegated_prefix_geo",
],
"primary_stat_key": "bgp_event_count",
"stat_keys": ["bgp_event_count", "bgp_incident_count", "bgp_anomaly_count", "bgp_collector_count"],
},
"compute": {
"name": "算力",
"sources": ["top500", "epoch_ai_gpu"],
"primary_stat_key": "compute_center_count",
"stat_keys": ["compute_center_count", "supercomputer_count", "gpu_cluster_count"],
},
}
def _build_product_status(product_id: str, summary: dict) -> dict:
definition = PRODUCT_DEFINITIONS[product_id]
stats = summary.get("stats", {})
product_stats = {key: stats.get(key, 0) for key in definition["stat_keys"]}
total_count = int(product_stats.get(definition["primary_stat_key"]) or 0)
return {
"product_id": product_id,
"name": definition["name"],
"sources": definition["sources"],
"generated_at": summary.get("generated_at") or to_iso8601_utc(datetime.now(UTC)),
"total_count": total_count,
"stats": product_stats,
"build_state": "ready",
"stats_scope": "global",
"stats_freshness": "cached_or_indexed",
}
@router.get("")
async def list_data_products(db: AsyncSession = Depends(get_db)):
summary = await get_visualization_geo_summary(db)
return {
"generated_at": summary.get("generated_at"),
"data": [
_build_product_status(product_id, summary)
for product_id in PRODUCT_DEFINITIONS
],
}
@router.get("/{product_id}/status")
async def get_data_product_status(
product_id: str,
db: AsyncSession = Depends(get_db),
):
if product_id not in PRODUCT_DEFINITIONS:
raise HTTPException(status_code=404, detail="Unknown data product")
summary = await get_visualization_geo_summary(db)
return _build_product_status(product_id, summary)
+321 -103
View File
@@ -3,7 +3,8 @@ from datetime import datetime, timedelta, timezone
from typing import Optional
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy import func, select, text
from pydantic import BaseModel, Field
from sqlalchemy import func, or_, select, text
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.time import to_iso8601_utc
@@ -17,6 +18,8 @@ from app.models.datasource import DataSource
from app.models.datasource_config import DataSourceConfig
from app.models.task import CollectionTask
from app.models.user import User
from app.models.vessel import AISRawObservation
from app.services.vessel_ais_aggregation import VESSEL_AIS_SCHEMA
from app.services.scheduler import (
cancel_running_collector_now,
get_latest_task_id_for_datasource,
@@ -27,6 +30,29 @@ from app.services.scheduler import (
router = APIRouter()
STALE_RUNNING_TASK_TIMEOUT_MINUTES = 90
PRODUCT_SOURCE_KEYWORDS: tuple[tuple[str, tuple[str, ...]], ...] = (
("vessels", ("vessel", "ais")),
("cables", ("cable", "landing", "telegeography", "arcgis", "fao")),
("satellites", ("tle", "satellite", "spacetrack", "celestrak")),
("bgp", ("bgp", "asn", "prefix_geo", "opengeofeed", "nro")),
("compute", ("top500", "gpu", "supercomputer", "compute")),
("ai", ("huggingface", "epoch_ai")),
("media", ("news", "tv", "live_stream")),
)
class DatasourceBatchTriggerRequest(BaseModel):
source_ids: list[int] = Field(default_factory=list)
force: bool = False
module: Optional[str] = None
product: Optional[str] = None
is_active: Optional[bool] = None
priority: Optional[str] = None
run_status: Optional[str] = None
collected: Optional[bool] = None
credential_status: Optional[str] = None
q: Optional[str] = None
def format_frequency_label(minutes: int) -> str:
if minutes % 1440 == 0:
@@ -47,6 +73,20 @@ def datasource_metadata(source: str) -> dict:
}
def datasource_product_key(datasource: DataSource) -> str:
haystack = " ".join(
[
datasource.source or "",
datasource.name or "",
datasource.collector_class or "",
]
).lower()
for product, keywords in PRODUCT_SOURCE_KEYWORDS:
if any(keyword in haystack for keyword in keywords):
return product
return "other"
def is_due_for_collection(datasource: DataSource, now: datetime) -> bool:
if datasource.last_run_at is None:
return True
@@ -110,6 +150,41 @@ async def _load_latest_task_ids(
return {datasource_id: task_id for datasource_id, task_id in result.all()}
async def _load_collected_record_counts(
db: AsyncSession,
sources: list[str],
) -> dict[str, int]:
if not sources:
return {}
result = await db.execute(
select(CollectedData.source, func.count(CollectedData.id))
.where(CollectedData.source.in_(sources))
.where(CollectedData.is_current.is_(True))
.group_by(CollectedData.source)
)
counts = {source: int(count or 0) for source, count in result.all()}
vessel_sources = [
source
for source in sources
if datasource_metadata(source)["credential_provider"] in {"aisstream", "barentswatch"}
or "vessel" in source
or "ais" in source
]
if vessel_sources:
raw_result = await db.execute(
select(AISRawObservation.source, func.count(AISRawObservation.id))
.where(AISRawObservation.target_schema == VESSEL_AIS_SCHEMA)
.where(AISRawObservation.source.in_(vessel_sources))
.group_by(AISRawObservation.source)
)
for source, count in raw_result.all():
counts[source] = max(counts.get(source, 0), int(count or 0))
return counts
async def _load_datasource_endpoint_overrides(
db: AsyncSession,
sources: list[str],
@@ -161,6 +236,192 @@ async def _load_datasource_list_context(
return running_tasks, endpoint_overrides
def _apply_datasource_query_filters(
query,
*,
module: Optional[str] = None,
is_active: Optional[bool] = None,
priority: Optional[str] = None,
run_status: Optional[str] = None,
q: Optional[str] = None,
) -> object:
if module:
query = query.where(DataSource.module == module)
if is_active is not None:
query = query.where(DataSource.is_active == is_active)
if priority:
query = query.where(DataSource.priority == priority)
if run_status and run_status not in {"running", "collected", "uncollected"}:
if run_status == "not_run":
query = query.where(DataSource.last_status.is_(None))
else:
query = query.where(DataSource.last_status == run_status)
if q:
like_value = f"%{q.strip()}%"
query = query.where(
or_(
DataSource.name.ilike(like_value),
DataSource.source.ilike(like_value),
DataSource.collector_class.ilike(like_value),
)
)
return query
def _filter_datasources_in_memory(
datasources: list[DataSource],
*,
running_tasks: dict[int, CollectionTask],
record_counts: dict[str, int],
product: Optional[str] = None,
run_status: Optional[str] = None,
collected: Optional[bool] = None,
credential_status: Optional[str] = None,
) -> list[DataSource]:
filtered: list[DataSource] = []
for datasource in datasources:
record_count = record_counts.get(datasource.source, 0)
if product and datasource_product_key(datasource) != product:
continue
if collected is not None and (record_count > 0) != collected:
continue
if credential_status:
metadata = datasource_metadata(datasource.source)
if metadata["credential_status"] != credential_status:
continue
if run_status == "running" and datasource.id not in running_tasks:
continue
if run_status == "collected" and record_count <= 0:
continue
if run_status == "uncollected" and record_count > 0:
continue
filtered.append(datasource)
return filtered
async def _trigger_datasource_batch(
db: AsyncSession,
datasources: list[DataSource],
*,
force: bool,
) -> dict:
if not datasources:
return {
"status": "noop",
"message": "No matching data sources to trigger",
"force": force,
"triggered": [],
"skipped": [],
"failed": [],
}
previous_task_ids: dict[int, Optional[int]] = {}
triggered_sources: list[dict] = []
skipped_sources: list[dict] = []
failed_sources: list[dict] = []
now = datetime.now(timezone.utc)
running_tasks = await _load_latest_running_tasks(
db,
[datasource.id for datasource in datasources],
)
for datasource in datasources:
if not datasource.is_active:
skipped_sources.append(
{
"id": datasource.id,
"source": datasource.source,
"name": datasource.name,
"reason": "disabled",
}
)
continue
running_task = running_tasks.get(datasource.id)
if running_task is not None:
if not force:
skipped_sources.append(
{
"id": datasource.id,
"source": datasource.source,
"name": datasource.name,
"reason": "already_running",
"task_id": running_task.id,
}
)
continue
cancelled = await cancel_running_collector_now(datasource.source)
if not cancelled:
await rollback_orphaned_running_task(db, datasource, running_task)
if not force and not is_due_for_collection(datasource, now):
skipped_sources.append(
{
"id": datasource.id,
"source": datasource.source,
"name": datasource.name,
"reason": "within_frequency_window",
"last_run_at": to_iso8601_utc(datasource.last_run_at),
"next_run_at": to_iso8601_utc(
datasource.last_run_at + timedelta(minutes=datasource.frequency_minutes)
),
}
)
continue
previous_task_ids[datasource.id] = None
success = run_collector_now(datasource.source)
if not success:
failed_sources.append(
{
"id": datasource.id,
"source": datasource.source,
"name": datasource.name,
"reason": "trigger_failed",
}
)
continue
triggered_sources.append(
{
"id": datasource.id,
"source": datasource.source,
"name": datasource.name,
"task_id": None,
}
)
latest_task_ids = await _load_latest_task_ids(
db,
[datasource.id for datasource in datasources],
)
for datasource_id in previous_task_ids:
previous_task_ids[datasource_id] = latest_task_ids.get(datasource_id)
for _ in range(20):
await asyncio.sleep(0.1)
pending = [item for item in triggered_sources if item["task_id"] is None]
if not pending:
break
latest_task_ids = await _load_latest_task_ids(
db,
[item["id"] for item in pending],
)
for item in pending:
task_id = latest_task_ids.get(item["id"])
if task_id is not None and task_id != previous_task_ids.get(item["id"]):
item["task_id"] = task_id
return {
"status": "triggered" if triggered_sources else "partial",
"message": f"Triggered {len(triggered_sources)} data sources",
"force": force,
"triggered": triggered_sources,
"skipped": skipped_sources,
"failed": failed_sources,
}
async def get_datasource_record(db: AsyncSession, source_id: str) -> Optional[DataSource]:
datasource = None
try:
@@ -355,16 +616,23 @@ async def list_datasources(
module: Optional[str] = None,
is_active: Optional[bool] = None,
priority: Optional[str] = None,
product: Optional[str] = None,
run_status: Optional[str] = None,
collected: Optional[bool] = None,
credential_status: Optional[str] = None,
q: Optional[str] = None,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
query = select(DataSource).order_by(DataSource.module, DataSource.id)
if module:
query = query.where(DataSource.module == module)
if is_active is not None:
query = query.where(DataSource.is_active == is_active)
if priority:
query = query.where(DataSource.priority == priority)
query = _apply_datasource_query_filters(
query,
module=module,
is_active=is_active,
priority=priority,
run_status=run_status,
q=q,
)
result = await db.execute(query)
datasources = result.scalars().all()
@@ -372,11 +640,22 @@ async def list_datasources(
collector_list = []
config = get_data_sources_config()
running_tasks, endpoint_overrides = await _load_datasource_list_context(db, datasources)
record_counts = await _load_collected_record_counts(db, [datasource.source for datasource in datasources])
datasources = _filter_datasources_in_memory(
datasources,
running_tasks=running_tasks,
record_counts=record_counts,
product=product,
run_status=run_status,
collected=collected,
credential_status=credential_status,
)
for datasource in datasources:
running_task = running_tasks.get(datasource.id)
endpoint = endpoint_overrides.get(datasource.source) or config.get_yaml_url(datasource.source)
last_run_at = datasource.last_run_at
last_status = datasource.last_status
collected_records = record_counts.get(datasource.source, 0)
collector_list.append(
{
@@ -384,6 +663,7 @@ async def list_datasources(
"source": datasource.source,
"name": datasource.name,
**datasource_metadata(datasource.source),
"product": datasource_product_key(datasource),
"module": datasource.module,
"priority": datasource.priority,
"frequency": format_frequency_label(datasource.frequency_minutes),
@@ -405,6 +685,8 @@ async def list_datasources(
"phase_unit": running_task.phase_unit if running_task else None,
"records_processed": running_task.records_processed if running_task else None,
"total_records": running_task.total_records if running_task else None,
"collected_records": collected_records,
"has_collected_data": collected_records > 0,
}
)
@@ -419,110 +701,46 @@ async def trigger_all_datasources(
):
result = await db.execute(
select(DataSource)
.where(DataSource.is_active == True)
.where(DataSource.is_active.is_(True))
.order_by(DataSource.module, DataSource.id)
)
datasources = result.scalars().all()
return await _trigger_datasource_batch(db, datasources, force=force)
if not datasources:
return {
"status": "noop",
"message": "No active data sources to trigger",
"triggered": [],
"skipped": [],
"failed": [],
}
previous_task_ids: dict[int, Optional[int]] = {}
triggered_sources: list[dict] = []
skipped_sources: list[dict] = []
failed_sources: list[dict] = []
now = datetime.now(timezone.utc)
running_tasks = await _load_latest_running_tasks(
db,
[datasource.id for datasource in datasources],
)
for datasource in datasources:
running_task = running_tasks.get(datasource.id)
if running_task is not None:
skipped_sources.append(
{
"id": datasource.id,
"source": datasource.source,
"name": datasource.name,
"reason": "already_running",
"task_id": running_task.id,
}
)
continue
if not force and not is_due_for_collection(datasource, now):
skipped_sources.append(
{
"id": datasource.id,
"source": datasource.source,
"name": datasource.name,
"reason": "within_frequency_window",
"last_run_at": to_iso8601_utc(datasource.last_run_at),
"next_run_at": to_iso8601_utc(
datasource.last_run_at + timedelta(minutes=datasource.frequency_minutes)
),
}
)
continue
previous_task_ids[datasource.id] = None
success = run_collector_now(datasource.source)
if not success:
failed_sources.append(
{
"id": datasource.id,
"source": datasource.source,
"name": datasource.name,
"reason": "trigger_failed",
}
)
continue
triggered_sources.append(
{
"id": datasource.id,
"source": datasource.source,
"name": datasource.name,
"task_id": None,
}
@router.post("/trigger-batch")
async def trigger_datasource_batch(
payload: DatasourceBatchTriggerRequest,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
query = select(DataSource).order_by(DataSource.module, DataSource.id)
if payload.source_ids:
query = query.where(DataSource.id.in_(payload.source_ids))
else:
query = _apply_datasource_query_filters(
query,
module=payload.module,
is_active=payload.is_active,
priority=payload.priority,
run_status=payload.run_status,
q=payload.q,
)
latest_task_ids = await _load_latest_task_ids(
db,
[datasource.id for datasource in datasources],
result = await db.execute(query)
datasources = result.scalars().all()
running_tasks, _ = await _load_datasource_list_context(db, datasources)
record_counts = await _load_collected_record_counts(db, [datasource.source for datasource in datasources])
datasources = _filter_datasources_in_memory(
datasources,
running_tasks=running_tasks,
record_counts=record_counts,
product=None if payload.source_ids else payload.product,
run_status=None if payload.source_ids else payload.run_status,
collected=None if payload.source_ids else payload.collected,
credential_status=None if payload.source_ids else payload.credential_status,
)
for datasource_id in previous_task_ids:
previous_task_ids[datasource_id] = latest_task_ids.get(datasource_id)
for _ in range(20):
await asyncio.sleep(0.1)
pending = [item for item in triggered_sources if item["task_id"] is None]
if not pending:
break
latest_task_ids = await _load_latest_task_ids(
db,
[item["id"] for item in pending],
)
for item in pending:
task_id = latest_task_ids.get(item["id"])
if task_id is not None and task_id != previous_task_ids.get(item["id"]):
item["task_id"] = task_id
return {
"status": "triggered" if triggered_sources else "partial",
"message": f"Triggered {len(triggered_sources)} data sources",
"force": force,
"triggered": triggered_sources,
"skipped": skipped_sources,
"failed": failed_sources,
}
return await _trigger_datasource_batch(db, datasources, force=payload.force)
@router.get("/{source_id}")
+229
View File
@@ -0,0 +1,229 @@
from typing import Any, Optional
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.v1.visualization import (
_parse_bbox,
get_bgp_anomalies_geojson,
get_bgp_collectors_geojson,
get_bgp_incidents_geojson,
get_cables_geojson,
get_landing_points_geojson,
get_satellites_geojson,
)
from app.api.v1.vessels import build_vessel_snapshot_response
from app.db.session import get_db
router = APIRouter()
DEFAULT_LAYER_LIMIT = 1000
MAX_LAYER_LIMIT = 5000
LOW_ZOOM_FEATURE_LIMIT = 500
def _clamp_limit(limit: int, zoom: int) -> tuple[int, bool]:
clamped = min(max(limit, 1), MAX_LAYER_LIMIT)
if zoom <= 3:
return min(clamped, LOW_ZOOM_FEATURE_LIMIT), clamped != limit or clamped > LOW_ZOOM_FEATURE_LIMIT
return clamped, clamped != limit
def _coordinate_in_bbox(coord: Any, bbox: tuple[float, float, float, float]) -> bool:
if not isinstance(coord, (list, tuple)) or len(coord) < 2:
return False
try:
lon = float(coord[0])
lat = float(coord[1])
except (TypeError, ValueError):
return False
lon_min, lat_min, lon_max, lat_max = bbox
return lon_min <= lon <= lon_max and lat_min <= lat <= lat_max
def _geometry_intersects_bbox(geometry: dict, bbox: tuple[float, float, float, float]) -> bool:
coordinates = geometry.get("coordinates")
geometry_type = geometry.get("type")
if geometry_type == "Point":
return _coordinate_in_bbox(coordinates, bbox)
if geometry_type in {"LineString", "MultiPoint"}:
return any(_coordinate_in_bbox(coord, bbox) for coord in coordinates or [])
if geometry_type in {"Polygon", "MultiLineString"}:
return any(
_coordinate_in_bbox(coord, bbox)
for line in coordinates or []
for coord in line
)
if geometry_type == "MultiPolygon":
return any(
_coordinate_in_bbox(coord, bbox)
for polygon in coordinates or []
for line in polygon
for coord in line
)
return False
def _guard_geojson_layer(
geojson: dict,
*,
bbox: tuple[float, float, float, float],
zoom: int,
limit: int,
) -> dict:
bounded_limit, limit_clamped = _clamp_limit(limit, zoom)
features = [
feature
for feature in geojson.get("features", [])
if _geometry_intersects_bbox(feature.get("geometry") or {}, bbox)
]
visible_count = len(features)
returned_features = features[:bounded_limit]
return {
**geojson,
"features": returned_features,
"visible_count": visible_count,
"returned_count": len(returned_features),
"diagnostics": {
"bbox_limited": True,
"limit": bounded_limit,
"limit_clamped": limit_clamped,
"truncated": visible_count > len(returned_features),
"degraded": zoom <= 3 or visible_count > len(returned_features),
"stats_scope": "viewport",
},
}
def _parse_layer_bbox(bbox: str) -> tuple[float, float, float, float]:
parsed = _parse_bbox(bbox)
if parsed is None:
raise HTTPException(status_code=400, detail="bbox is required")
return parsed
@router.get("/vessels/snapshot")
async def get_vessel_layer_snapshot(
bbox: str = Query(..., description="lon_min,lat_min,lon_max,lat_max"),
zoom: int = Query(..., ge=1, le=20),
limit: int = Query(DEFAULT_LAYER_LIMIT, ge=1),
vessel_type: Optional[str] = Query(None, alias="type"),
since_minutes: int = Query(60, ge=1, le=1440),
db: AsyncSession = Depends(get_db),
):
parsed_bbox = _parse_layer_bbox(bbox)
return await build_vessel_snapshot_response(
db,
bbox=parsed_bbox,
zoom=zoom,
limit=limit,
type_filter=vessel_type,
since_minutes=since_minutes,
)
@router.get("/cables")
async def get_cable_layer(
bbox: str = Query(..., description="lon_min,lat_min,lon_max,lat_max"),
zoom: int = Query(..., ge=1, le=20),
limit: int = Query(DEFAULT_LAYER_LIMIT, ge=1),
db: AsyncSession = Depends(get_db),
):
return _guard_geojson_layer(
await get_cables_geojson(db),
bbox=_parse_layer_bbox(bbox),
zoom=zoom,
limit=limit,
)
@router.get("/landing-points")
async def get_landing_point_layer(
bbox: str = Query(..., description="lon_min,lat_min,lon_max,lat_max"),
zoom: int = Query(..., ge=1, le=20),
limit: int = Query(DEFAULT_LAYER_LIMIT, ge=1),
db: AsyncSession = Depends(get_db),
):
return _guard_geojson_layer(
await get_landing_points_geojson(db),
bbox=_parse_layer_bbox(bbox),
zoom=zoom,
limit=limit,
)
@router.get("/satellites")
async def get_satellite_layer(
bbox: str = Query(..., description="lon_min,lat_min,lon_max,lat_max"),
zoom: int = Query(..., ge=1, le=20),
limit: int = Query(DEFAULT_LAYER_LIMIT, ge=1),
db: AsyncSession = Depends(get_db),
):
bounded_limit, _ = _clamp_limit(limit, zoom)
return _guard_geojson_layer(
await get_satellites_geojson(limit=bounded_limit, db=db),
bbox=_parse_layer_bbox(bbox),
zoom=zoom,
limit=limit,
)
@router.get("/bgp/anomalies")
async def get_bgp_anomaly_layer(
bbox: str = Query(..., description="lon_min,lat_min,lon_max,lat_max"),
zoom: int = Query(..., ge=1, le=20),
limit: int = Query(DEFAULT_LAYER_LIMIT, ge=1),
severity: Optional[str] = Query(None),
status: Optional[str] = Query("active"),
db: AsyncSession = Depends(get_db),
):
bounded_limit, _ = _clamp_limit(limit, zoom)
return _guard_geojson_layer(
await get_bgp_anomalies_geojson(
severity=severity,
status=status,
limit=bounded_limit,
db=db,
),
bbox=_parse_layer_bbox(bbox),
zoom=zoom,
limit=limit,
)
@router.get("/bgp/incidents")
async def get_bgp_incident_layer(
bbox: str = Query(..., description="lon_min,lat_min,lon_max,lat_max"),
zoom: int = Query(..., ge=1, le=20),
limit: int = Query(DEFAULT_LAYER_LIMIT, ge=1),
severity: Optional[str] = Query(None),
status: Optional[str] = Query("active"),
db: AsyncSession = Depends(get_db),
):
bounded_limit, _ = _clamp_limit(limit, zoom)
return _guard_geojson_layer(
await get_bgp_incidents_geojson(
severity=severity,
status=status,
limit=min(bounded_limit, 500),
db=db,
),
bbox=_parse_layer_bbox(bbox),
zoom=zoom,
limit=limit,
)
@router.get("/bgp/collectors")
async def get_bgp_collector_layer(
bbox: str = Query(..., description="lon_min,lat_min,lon_max,lat_max"),
zoom: int = Query(..., ge=1, le=20),
limit: int = Query(DEFAULT_LAYER_LIMIT, ge=1),
db: AsyncSession = Depends(get_db),
):
return _guard_geojson_layer(
await get_bgp_collectors_geojson(db),
bbox=_parse_layer_bbox(bbox),
zoom=zoom,
limit=limit,
)
+280
View File
@@ -0,0 +1,280 @@
"""Realtime datasource operations and runtime statistics."""
from datetime import UTC, datetime, timedelta
import os
from typing import Any
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy import distinct, func, select
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.data_sources import get_data_sources_config
from app.core.security import get_current_user
from app.core.time import to_iso8601_utc
from app.db.session import get_db
from app.models.datasource import DataSource
from app.models.datasource_config import DataSourceConfig
from app.models.user import User
from app.models.vessel import AISRawObservation, AISSourceHealth
from app.services.custom_datasource_runtime import (
get_custom_stream_status,
start_custom_stream,
stop_custom_stream,
)
from app.services.scheduler import (
cancel_running_collector_now,
is_collector_running,
run_collector_now,
)
from app.services.vessel_ais_aggregation import VESSEL_AIS_SCHEMA, update_ais_source_health
router = APIRouter()
BUILTIN_REALTIME_SOURCES = {"aisstream_vessels"}
REALTIME_SOURCE_TYPES = {"websocket", "ws"}
def _is_realtime_config(config: DataSourceConfig) -> bool:
return str(config.source_type or "").lower() in REALTIME_SOURCE_TYPES
def _safe_config_dict(value: Any) -> dict[str, Any]:
return value if isinstance(value, dict) else {}
def _credential_configured(config: DataSourceConfig | None) -> bool:
if config is not None:
auth_config = _safe_config_dict(config.auth_config)
config_payload = _safe_config_dict(config.config)
if auth_config.get("api_key") or config_payload.get("api_key"):
return True
return bool(os.getenv("AISSTREAM_API_KEY"))
async def _load_realtime_stats(db: AsyncSession, source: str) -> dict[str, Any]:
now = datetime.now(UTC)
observed_24h = now - timedelta(hours=24)
observed_1h = now - timedelta(hours=1)
payload_mmsi = AISRawObservation.entity_key
result = await db.execute(
select(
func.count(AISRawObservation.id).label("total_observations"),
func.count(AISRawObservation.id)
.filter(AISRawObservation.observed_at >= observed_24h)
.label("observations_24h"),
func.count(AISRawObservation.id)
.filter(AISRawObservation.observed_at >= observed_1h)
.label("observations_1h"),
func.count(distinct(payload_mmsi)).label("unique_mmsi_total"),
func.count(distinct(payload_mmsi))
.filter(AISRawObservation.observed_at >= observed_24h)
.label("unique_mmsi_24h"),
func.max(AISRawObservation.observed_at).label("latest_observed_at"),
func.max(AISRawObservation.collected_at).label("latest_collected_at"),
)
.where(AISRawObservation.target_schema == VESSEL_AIS_SCHEMA)
.where(AISRawObservation.source == source)
)
row = result.mappings().one()
return {
"total_observations": int(row["total_observations"] or 0),
"observations_24h": int(row["observations_24h"] or 0),
"observations_1h": int(row["observations_1h"] or 0),
"unique_mmsi_total": int(row["unique_mmsi_total"] or 0),
"unique_mmsi_24h": int(row["unique_mmsi_24h"] or 0),
"latest_observed_at": to_iso8601_utc(row["latest_observed_at"]),
"latest_collected_at": to_iso8601_utc(row["latest_collected_at"]),
}
def _runtime_status_for_builtin(source: str) -> dict[str, Any]:
running = is_collector_running(source)
return {
"running": running,
"done": False,
"runtime": "collector",
}
def _runtime_status_for_custom(config_id: int) -> dict[str, Any]:
status = get_custom_stream_status(config_id)
return {
"running": bool(status.get("running")),
"done": bool(status.get("done")),
"runtime": "custom_stream",
}
async def _serialize_builtin_aisstream(
db: AsyncSession,
datasource: DataSource,
config: DataSourceConfig | None,
) -> dict[str, Any]:
health = await db.get(AISSourceHealth, datasource.source)
config_payload = _safe_config_dict(config.config if config else {})
endpoint = (
(config.endpoint if config else None)
or get_data_sources_config().get_yaml_url(datasource.source)
)
return {
"source": datasource.source,
"name": datasource.name,
"display_name": "AISStream 实时船舶",
"kind": "builtin",
"source_type": "websocket",
"endpoint": endpoint,
"is_active": bool(datasource.is_active),
"credential_configured": _credential_configured(config),
"message_types": config_payload.get("message_types") or ["PositionReport", "ShipStaticData"],
"bounding_boxes": config_payload.get("bounding_boxes") or [[[-90, -180], [90, 180]]],
"config": config_payload,
"runtime": _runtime_status_for_builtin(datasource.source),
"health": health.to_dict() if health else None,
"stats": await _load_realtime_stats(db, datasource.source),
}
async def _serialize_custom_stream(
db: AsyncSession,
config: DataSourceConfig,
) -> dict[str, Any]:
health = await db.get(AISSourceHealth, config.name)
config_payload = _safe_config_dict(config.config)
return {
"source": config.name,
"name": config.name,
"display_name": config.description or config.name,
"kind": "custom",
"config_id": config.id,
"source_type": config.source_type,
"endpoint": config.endpoint,
"is_active": bool(config.is_active),
"credential_configured": config.auth_type == "none" or bool(_safe_config_dict(config.auth_config)),
"message_types": config_payload.get("message_types") or [],
"bounding_boxes": config_payload.get("bounding_boxes") or [],
"config": config_payload,
"runtime": _runtime_status_for_custom(config.id),
"health": health.to_dict() if health else None,
"stats": await _load_realtime_stats(db, config.name),
}
async def _load_builtin_aisstream(db: AsyncSession) -> tuple[DataSource | None, DataSourceConfig | None]:
result = await db.execute(select(DataSource).where(DataSource.source == "aisstream_vessels"))
datasource = result.scalar_one_or_none()
config_result = await db.execute(
select(DataSourceConfig)
.where(DataSourceConfig.name == "aisstream_vessels")
.where(DataSourceConfig.is_active.is_(True))
.order_by(DataSourceConfig.id.desc())
.limit(1)
)
return datasource, config_result.scalar_one_or_none()
async def _load_custom_realtime_config(db: AsyncSession, source: str) -> DataSourceConfig | None:
result = await db.execute(
select(DataSourceConfig)
.where(DataSourceConfig.name == source)
.order_by(DataSourceConfig.id.desc())
.limit(1)
)
config = result.scalar_one_or_none()
return config if config is not None and _is_realtime_config(config) else None
@router.get("")
async def list_realtime_sources(
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
sources: list[dict[str, Any]] = []
datasource, builtin_config = await _load_builtin_aisstream(db)
if datasource is not None:
sources.append(await _serialize_builtin_aisstream(db, datasource, builtin_config))
custom_result = await db.execute(
select(DataSourceConfig)
.where(func.lower(DataSourceConfig.source_type).in_(REALTIME_SOURCE_TYPES))
.order_by(DataSourceConfig.name)
)
for config in custom_result.scalars().all():
if config.name in BUILTIN_REALTIME_SOURCES:
continue
sources.append(await _serialize_custom_stream(db, config))
return {"total": len(sources), "data": sources}
async def _ensure_builtin_startable(db: AsyncSession) -> DataSourceConfig | None:
datasource, config = await _load_builtin_aisstream(db)
if datasource is None:
raise HTTPException(status_code=404, detail="Realtime source not found")
if not datasource.is_active:
raise HTTPException(status_code=400, detail="Realtime source is disabled")
if not _credential_configured(config):
raise HTTPException(status_code=400, detail="AISStream API key is not configured")
return config
@router.post("/{source}/start")
async def start_realtime_source(
source: str,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
if source == "aisstream_vessels":
await _ensure_builtin_startable(db)
if is_collector_running(source):
return {"status": "already_running", "source": source, "runtime": _runtime_status_for_builtin(source)}
if not run_collector_now(source):
raise HTTPException(status_code=409, detail="Realtime source could not be started")
return {"status": "started", "source": source, "runtime": _runtime_status_for_builtin(source)}
config = await _load_custom_realtime_config(db, source)
if config is None:
raise HTTPException(status_code=404, detail="Realtime source not found")
if not config.is_active:
raise HTTPException(status_code=400, detail="Realtime source is disabled")
started = start_custom_stream(config.id)
return {
"status": "started" if started else "already_running",
"source": source,
"runtime": _runtime_status_for_custom(config.id),
}
@router.post("/{source}/stop")
async def stop_realtime_source(
source: str,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
if source == "aisstream_vessels":
stopped = await cancel_running_collector_now(source)
await update_ais_source_health(db, source=source, connection_state="disconnected", last_error=None)
await db.commit()
return {"status": "stopped" if stopped else "not_running", "source": source, "runtime": _runtime_status_for_builtin(source)}
config = await _load_custom_realtime_config(db, source)
if config is None:
raise HTTPException(status_code=404, detail="Realtime source not found")
stopped = await stop_custom_stream(config.id)
await update_ais_source_health(db, source=source, connection_state="disconnected", last_error=None)
await db.commit()
return {
"status": "stopped" if stopped else "not_running",
"source": source,
"runtime": _runtime_status_for_custom(config.id),
}
@router.post("/{source}/restart")
async def restart_realtime_source(
source: str,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
await stop_realtime_source(source, current_user=current_user, db=db)
return await start_realtime_source(source, current_user=current_user, db=db)
+230 -2
View File
@@ -81,6 +81,17 @@ DEFAULT_SETTINGS = {
"password_policy": "medium",
},
"tv": DEFAULT_TV_SETTINGS,
"smtp": {
"host": "",
"port": 587,
"username": "",
"password": "",
"from_address": "",
"from_name": "Planet",
"use_tls": False,
"use_starttls": True,
"timeout_seconds": 20,
},
"external_integrations": {
"ai_provider": {
"service_url": "",
@@ -95,6 +106,17 @@ DEFAULT_SETTINGS = {
"default_provider": "tavily",
"providers": {},
},
"ocr": {
"enabled": False,
"provider": "paddleocr",
"base_url": "",
"api_key": "",
"model": "",
"languages": ["zh", "en"],
"timeout_seconds": 30,
"max_file_size_mb": 20,
"output_format": "markdown",
},
},
}
@@ -153,6 +175,24 @@ class TVSettingsUpdate(BaseModel):
sources: list[TVStreamSourceUpdate] = Field(default_factory=list)
class SMTPSettingsUpdate(BaseModel):
host: str = Field(default="", max_length=255)
port: int = Field(default=587, ge=1, le=65535)
username: str = Field(default="", max_length=255)
password: Optional[str] = None
clear_password: bool = False
from_address: str = Field(default="", max_length=255)
from_name: str = Field(default="Planet", max_length=120)
use_tls: bool = False
use_starttls: bool = True
timeout_seconds: int = Field(default=20, ge=3, le=300)
class SMTPTestRequest(BaseModel):
to: EmailStr
settings: Optional[SMTPSettingsUpdate] = None
class AIProviderIntegrationUpdate(BaseModel):
service_url: str = ""
service_token: Optional[str] = None
@@ -198,10 +238,23 @@ class WebSearchIntegrationUpdate(BaseModel):
scrape_formats: list[str] = Field(default_factory=lambda: ["markdown"])
class OCRIntegrationUpdate(BaseModel):
enabled: bool = False
provider: str = Field(default="paddleocr", max_length=80)
base_url: str = Field(default="", max_length=500)
api_key: Optional[str] = None
model: str = Field(default="", max_length=200)
languages: list[str] = Field(default_factory=lambda: ["zh", "en"])
timeout_seconds: int = Field(default=30, ge=3, le=300)
max_file_size_mb: int = Field(default=20, ge=1, le=200)
output_format: str = Field(default="markdown", pattern="^(markdown|text|json)$")
class ExternalIntegrationsUpdate(BaseModel):
ai_provider: AIProviderIntegrationUpdate
barentswatch: BarentsWatchIntegrationUpdate
web_search: WebSearchIntegrationUpdate | None = None
ocr: OCRIntegrationUpdate | None = None
def merge_with_defaults(category: str, payload: Optional[dict]) -> dict:
@@ -649,6 +702,59 @@ def _runtime_config_from_web_search_payload(web_search_payload: dict) -> WebSear
)
def _normalize_ocr_payload(ocr_payload: dict | None) -> dict:
raw = dict(ocr_payload or {})
languages = raw.get("languages")
if not isinstance(languages, list) or not languages:
languages = ["zh", "en"]
return {
"enabled": bool(raw.get("enabled", False)),
"provider": str(raw.get("provider") or "paddleocr").strip().lower() or "paddleocr",
"base_url": str(raw.get("base_url") or "").strip(),
"api_key": str(raw.get("api_key") or "").strip(),
"model": str(raw.get("model") or "").strip(),
"languages": [str(item).strip() for item in languages if str(item).strip()],
"timeout_seconds": int(raw.get("timeout_seconds") or 30),
"max_file_size_mb": int(raw.get("max_file_size_mb") or 20),
"output_format": str(raw.get("output_format") or "markdown").strip() or "markdown",
}
def _resolve_ocr_api_key(ocr_config: dict) -> tuple[str, str]:
saved_key = ocr_config.get("api_key") or ""
if saved_key:
return str(saved_key), "runtime"
return _resolve_web_search_env_secret("OCR_API_KEY")
def _build_ocr_payload(
current_payload: dict,
update: OCRIntegrationUpdate | None,
) -> dict:
current_ocr = _normalize_ocr_payload(current_payload.get("ocr") or {})
if update is None:
return current_ocr
current_key, current_key_source = _resolve_ocr_api_key(current_ocr)
current_key_preview = _mask_secret(current_key, current_key_source)["preview"]
ocr_payload = {
"enabled": update.enabled,
"provider": update.provider.strip().lower() or current_ocr.get("provider") or "paddleocr",
"base_url": update.base_url.strip(),
"model": update.model.strip(),
"languages": [item.strip() for item in update.languages if item.strip()] or ["zh", "en"],
"timeout_seconds": update.timeout_seconds,
"max_file_size_mb": update.max_file_size_mb,
"output_format": update.output_format.strip() or "markdown",
}
if not _is_secret_placeholder(update.api_key, current_key_preview):
ocr_payload["api_key"] = str(update.api_key).strip()
elif current_ocr.get("api_key"):
ocr_payload["api_key"] = current_ocr.get("api_key") or ""
else:
ocr_payload["api_key"] = ""
return ocr_payload
async def get_runtime_web_search_config(db: AsyncSession) -> WebSearchConfig:
runtime_record = await get_setting_record(db, "external_integrations")
payload = merge_with_defaults(
@@ -684,6 +790,7 @@ async def serialize_external_integrations(db: AsyncSession) -> dict:
)
normalized_ai = _normalize_ai_provider_payload(raw_payload.get("ai_provider") or {})
normalized_web_search = _normalize_web_search_payload(raw_payload.get("web_search") or {})
normalized_ocr = _normalize_ocr_payload(raw_payload.get("ocr") or {})
default_provider = normalized_ai["default_provider"]
providers_payload: dict[str, dict] = {}
for provider in sorted({
@@ -731,6 +838,7 @@ async def serialize_external_integrations(db: AsyncSession) -> dict:
web_search_providers_payload.get(normalized_web_search["default_provider"])
or _web_search_provider_defaults(normalized_web_search["default_provider"])
)
ocr_api_key, ocr_api_key_source = _resolve_ocr_api_key(normalized_ocr)
barentswatch_record = await get_barentswatch_config_record(db)
barentswatch_auth = barentswatch_record.auth_config if barentswatch_record else {}
barentswatch_auth = barentswatch_auth or {}
@@ -782,6 +890,18 @@ async def serialize_external_integrations(db: AsyncSession) -> dict:
"scrape_formats": display_web_search_config.get("scrape_formats") or ["markdown"],
"source": "runtime" if runtime_setting else "env",
},
"ocr": {
"enabled": normalized_ocr["enabled"],
"provider": normalized_ocr["provider"],
"base_url": normalized_ocr["base_url"],
"api_key": _mask_secret(ocr_api_key, ocr_api_key_source),
"model": normalized_ocr["model"],
"languages": normalized_ocr["languages"],
"timeout_seconds": normalized_ocr["timeout_seconds"],
"max_file_size_mb": normalized_ocr["max_file_size_mb"],
"output_format": normalized_ocr["output_format"],
"source": "runtime" if normalized_ocr.get("api_key") else (ocr_api_key_source or "default"),
},
}
@@ -792,11 +912,12 @@ async def save_external_integrations_payload(
current_payload = await get_setting_payload(db, "external_integrations")
ai_payload = _build_ai_provider_payload(current_payload, update.ai_provider)
web_search_payload = _build_web_search_payload(current_payload, update.web_search)
ocr_payload = _build_ocr_payload(current_payload, update.ocr)
await save_setting_payload(
db,
"external_integrations",
{"ai_provider": ai_payload, "web_search": web_search_payload},
{"ai_provider": ai_payload, "web_search": web_search_payload, "ocr": ocr_payload},
)
default_endpoint = get_data_sources_config().get_yaml_url("barentswatch_vessels")
@@ -919,6 +1040,97 @@ async def update_security_settings(
return {"status": "updated", "security": payload}
def _serialize_smtp_payload(payload: dict) -> dict:
password = str(payload.get("password") or "")
return {
"host": payload.get("host") or "",
"port": int(payload.get("port") or 587),
"username": payload.get("username") or "",
"password": _mask_secret(password, "runtime" if password else ""),
"from_address": payload.get("from_address") or "",
"from_name": payload.get("from_name") or "Planet",
"use_tls": bool(payload.get("use_tls", False)),
"use_starttls": bool(payload.get("use_starttls", True)),
"timeout_seconds": int(payload.get("timeout_seconds") or 20),
"configured": bool(payload.get("host") and payload.get("from_address")),
}
def _build_smtp_payload(current_payload: dict, update: SMTPSettingsUpdate) -> dict:
current_password = str(current_payload.get("password") or "")
current_preview = _mask_secret(current_password, "runtime" if current_password else "")["preview"]
if update.clear_password:
password = ""
elif _is_secret_placeholder(update.password, current_preview):
password = current_password
else:
password = str(update.password).strip()
return {
"host": update.host.strip(),
"port": update.port,
"username": update.username.strip(),
"password": password,
"from_address": update.from_address.strip(),
"from_name": update.from_name.strip() or "Planet",
"use_tls": update.use_tls,
"use_starttls": update.use_starttls,
"timeout_seconds": update.timeout_seconds,
}
@router.get("/smtp")
async def get_smtp_settings(
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
return {"smtp": _serialize_smtp_payload(await get_setting_payload(db, "smtp"))}
@router.put("/smtp")
async def update_smtp_settings(
payload: SMTPSettingsUpdate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
if current_user.role not in ("admin", "super_admin"):
raise HTTPException(status_code=403, detail="Only administrators can change SMTP settings")
current = await get_setting_payload(db, "smtp")
merged = _build_smtp_payload(current, payload)
saved = await save_setting_payload(db, "smtp", merged)
return {"status": "updated", "smtp": _serialize_smtp_payload(saved)}
@router.post("/smtp/test")
async def test_smtp_settings(
payload: SMTPTestRequest,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
if current_user.role not in ("admin", "super_admin"):
raise HTTPException(status_code=403, detail="Only administrators can test SMTP settings")
from app.services.email import EmailError, send_email
current = await get_setting_payload(db, "smtp")
config = _build_smtp_payload(current, payload.settings) if payload.settings else current
if not config.get("host") or not config.get("from_address"):
raise HTTPException(
status_code=400,
detail="Host and from_address are required to send a test email",
)
try:
await send_email(
db,
to=payload.to,
subject="Planet SMTP test",
text_body="This is a test email from Planet SMTP settings.",
html_body="<p>This is a test email from Planet SMTP settings.</p>",
config=config,
)
except EmailError as exc:
return {"success": False, "message": str(exc), "code": exc.code}
return {"success": True, "message": "Test email sent"}
@router.get("/tv")
async def get_tv_settings(
current_user: User = Depends(get_current_user),
@@ -1033,10 +1245,11 @@ async def connect_ai_provider_integration(
)
)
current_web_search = _normalize_web_search_payload(current_payload.get("web_search") or {})
current_ocr = _normalize_ocr_payload(current_payload.get("ocr") or {})
await save_setting_payload(
db,
"external_integrations",
{"ai_provider": draft_ai_payload, "web_search": current_web_search},
{"ai_provider": draft_ai_payload, "web_search": current_web_search, "ocr": current_ocr},
)
return {
"success": True,
@@ -1110,6 +1323,21 @@ async def reveal_web_search_secrets(
}
@router.get("/integrations/ocr/secrets")
async def reveal_ocr_secrets(
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
):
current_payload = await get_setting_payload(db, "external_integrations")
ocr_payload = _normalize_ocr_payload(current_payload.get("ocr") or {})
api_key, api_key_source = _resolve_ocr_api_key(ocr_payload)
return {
"provider": ocr_payload["provider"],
"api_key": api_key,
"api_key_source": api_key_source,
}
@router.post("/integrations/web-search/connect")
async def connect_web_search_integration(
payload: WebSearchIntegrationUpdate,
+39
View File
@@ -0,0 +1,39 @@
"""Bounded vessel snapshot APIs for viewport-first consumers."""
from typing import Optional
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.v1.visualization import _parse_bbox, build_vessel_snapshot_response
from app.db.session import get_db
from app.services.vessel_ais_aggregation import MAX_SNAPSHOT_LIMIT
router = APIRouter()
@router.get("/snapshot")
async def get_vessel_snapshot(
bbox: Optional[str] = Query(None, description="Viewport bbox as lon_min,lat_min,lon_max,lat_max"),
zoom: int = Query(..., ge=1, le=20, description="Current map zoom level"),
type: Optional[str] = Query(
None,
description="Comma-separated vessel types: cargo,tanker,passenger,fishing,military,other",
),
limit: int = Query(1000, ge=1, le=MAX_SNAPSHOT_LIMIT),
since_minutes: int = Query(60, ge=1, le=1440),
db: AsyncSession = Depends(get_db),
):
if not bbox:
raise HTTPException(status_code=400, detail="bbox is required")
parsed_bbox = _parse_bbox(bbox)
if parsed_bbox is None:
raise HTTPException(status_code=400, detail="bbox is required")
return await build_vessel_snapshot_response(
db,
bbox=parsed_bbox,
zoom=zoom,
type_filter=type,
limit=limit,
since_minutes=since_minutes,
)
+147 -73
View File
@@ -51,8 +51,10 @@ from app.services.vessel_ais_aggregation import (
get_aggregated_vessel,
get_aggregated_vessel_track,
get_aggregated_vessels,
get_aggregated_vessels_snapshot,
get_vessel_conflict_records,
get_vessel_raw_observations,
MAX_SNAPSHOT_LIMIT,
)
from app.core.logging import get_logger
@@ -66,6 +68,7 @@ TERRAIN_TILE_BATCH_MAX_ITEMS = 128
TERRAIN_TILE_BATCH_CONCURRENCY = 16
_terrain_tile_cache: OrderedDict[tuple[int, int, int], tuple[bytes, str, dict[str, str]]] = OrderedDict()
VESSEL_NAME_FALLBACK_PATTERN = re.compile(r"^mmsi\s*\d+$", re.IGNORECASE)
VESSEL_SNAPSHOT_LEGACY_FALLBACK_ENABLED = True
class TerrariumTileRequest(BaseModel):
@@ -939,6 +942,39 @@ def _merge_vessel_features(
}
async def _load_legacy_vessel_snapshot_features(
db: AsyncSession,
*,
bbox: tuple[float, float, float, float] | None,
limit: int,
) -> list[dict[str, Any]]:
latest_positions = select(
VesselPosition.mmsi.label("mmsi"),
func.max(VesselPosition.received_at).label("received_at"),
)
if bbox is not None:
lon_min, lat_min, lon_max, lat_max = bbox
latest_positions = latest_positions.where(VesselPosition.lon >= lon_min)
latest_positions = latest_positions.where(VesselPosition.lon <= lon_max)
latest_positions = latest_positions.where(VesselPosition.lat >= lat_min)
latest_positions = latest_positions.where(VesselPosition.lat <= lat_max)
latest_positions = latest_positions.group_by(VesselPosition.mmsi).subquery()
result = await db.execute(
select(VesselPosition, VesselStatic)
.join(
latest_positions,
(VesselPosition.mmsi == latest_positions.c.mmsi)
& (VesselPosition.received_at == latest_positions.c.received_at),
)
.outerjoin(VesselStatic, VesselStatic.mmsi == VesselPosition.mmsi)
.order_by(VesselPosition.received_at.desc())
.limit(limit)
)
legacy_geojson = convert_vessels_to_geojson(list(result.all()))
return legacy_geojson.get("features", [])[:limit]
def _build_vessel_stats(features: List[dict[str, Any]]) -> dict[str, Any]:
by_type: dict[str, int] = {}
underway = 0
@@ -960,6 +996,52 @@ def _build_vessel_stats(features: List[dict[str, Any]]) -> dict[str, Any]:
}
def _safe_vessel_limit(value: int | None, *, default: int = 1000) -> int:
if value is None or value <= 0:
return default
return min(value, MAX_SNAPSHOT_LIMIT)
async def build_vessel_snapshot_response(
db: AsyncSession,
*,
bbox: tuple[float, float, float, float] | None,
zoom: int | None,
type_filter: str | None,
limit: int | None,
since_minutes: int = 60,
) -> dict[str, Any]:
requested_types = _requested_vessel_types(type_filter)
safe_limit = _safe_vessel_limit(limit)
safe_since_minutes = min(max(int(since_minutes or 60), 1), 1440)
observed_since = datetime.now(UTC) - timedelta(minutes=safe_since_minutes)
features, diagnostics = await _load_raw_vessel_snapshot_features(
db,
bbox=bbox,
limit=safe_limit,
observed_since=observed_since,
)
features = _filter_vessel_features(
features,
bbox=bbox,
requested_types=requested_types,
)[:safe_limit]
return {
"type": "FeatureCollection",
"features": features,
"count": len(features),
"stats": _build_vessel_stats(features),
"diagnostics": {
**diagnostics,
"filtered_count": len(features),
"bbox_applied": bbox is not None,
"zoom": zoom,
"limit": safe_limit,
"since_minutes": safe_since_minutes,
},
}
def convert_bgp_anomalies_to_geojson(
records: List[BGPAnomaly],
geography_hints: Optional[Dict[str, Dict[str, Any]]] = None,
@@ -2025,83 +2107,68 @@ async def _load_compute_center_record(db: AsyncSession, source_id: str) -> Colle
return result.scalars().first()
@router.get("/geo/vessels")
async def get_vessels_geojson(
bbox: Optional[str] = Query(
None,
description="Viewport bbox as lon_min,lat_min,lon_max,lat_max",
),
type: Optional[str] = Query(
None,
description="Comma-separated vessel types: cargo,tanker,passenger,fishing,military,other",
),
limit: Optional[int] = Query(
None,
ge=0,
description="Maximum vessel features to return. Omit or pass 0 for no limit.",
),
db: AsyncSession = Depends(get_db),
):
"""Return latest vessel positions as GeoJSON points."""
parsed_bbox = _parse_bbox(bbox)
requested_types = _requested_vessel_types(type)
merged_features, diagnostics = await _load_merged_vessel_features(db)
features = _filter_vessel_features(
merged_features,
bbox=parsed_bbox,
requested_types=requested_types,
)
if limit and limit > 0:
features = features[:limit]
return {
"type": "FeatureCollection",
"features": features,
"count": len(features),
"stats": _build_vessel_stats(features),
"diagnostics": {
**diagnostics,
"filtered_count": len(features),
},
}
async def _load_merged_vessel_features(db: AsyncSession) -> tuple[list[dict[str, Any]], dict[str, Any]]:
aggregated_vessels = await get_aggregated_vessels(db)
async def _load_raw_vessel_snapshot_features(
db: AsyncSession,
*,
bbox: tuple[float, float, float, float] | None,
limit: int,
observed_since: datetime,
) -> tuple[list[dict[str, Any]], dict[str, Any]]:
if bbox is None:
aggregated_vessels = await get_aggregated_vessels(
db,
limit=limit,
observed_since=observed_since,
)
else:
aggregated_vessels = await get_aggregated_vessels_snapshot(
db,
bbox=bbox,
limit=limit,
observed_since=observed_since,
)
raw_geojson = convert_aggregated_vessels_to_geojson(aggregated_vessels)
latest_times = (
select(
VesselPosition.mmsi.label("mmsi"),
func.max(VesselPosition.received_at).label("received_at"),
raw_features = raw_geojson.get("features", [])
features = raw_features
legacy_features: list[dict[str, Any]] = []
legacy_fallback_used = False
if not raw_features and VESSEL_SNAPSHOT_LEGACY_FALLBACK_ENABLED:
legacy_features = await _load_legacy_vessel_snapshot_features(
db,
bbox=bbox,
limit=limit,
)
.group_by(VesselPosition.mmsi)
.subquery()
)
stmt = (
select(VesselPosition, VesselStatic)
.join(
latest_times,
(VesselPosition.mmsi == latest_times.c.mmsi)
& (VesselPosition.received_at == latest_times.c.received_at),
)
.outerjoin(VesselStatic, VesselStatic.mmsi == VesselPosition.mmsi)
.order_by(VesselPosition.received_at.desc())
)
features, _merge_diagnostics = _merge_vessel_features(raw_features, legacy_features)
legacy_fallback_used = bool(legacy_features)
result = await db.execute(stmt)
rows = list(result.all())
legacy_geojson = convert_vessels_to_geojson(rows)
merged_features, diagnostics = _merge_vessel_features(
raw_geojson.get("features", []),
legacy_geojson.get("features", []),
)
return merged_features, {
**diagnostics,
"raw_feature_count": len(raw_geojson.get("features", [])),
"legacy_feature_count": len(legacy_geojson.get("features", [])),
return features, {
"raw_feature_count": len(raw_features),
"raw_unique_mmsi": len(
{
key
for key in (_feature_mmsi_key(feature) for feature in raw_features)
if key is not None
}
),
"legacy_feature_count": len(legacy_features),
"legacy_backfilled_mmsi": len(
{
key
for key in (_feature_mmsi_key(feature) for feature in legacy_features)
if key is not None
}
),
"legacy_fallback_enabled": VESSEL_SNAPSHOT_LEGACY_FALLBACK_ENABLED,
"legacy_fallback_used": legacy_fallback_used,
"final_unique_mmsi": len(
{
key
for key in (_feature_mmsi_key(feature) for feature in features)
if key is not None
}
),
}
@router.get("/vessels/custom-supplements")
async def get_vessel_custom_supplements(db: AsyncSession = Depends(get_db)):
"""Group custom vessel_ais sources by their declared merge target for diagnostics."""
@@ -2426,7 +2493,12 @@ async def get_visualization_geo_summary(db: AsyncSession = Depends(get_db)):
select(func.count(func.distinct(VesselPosition.mmsi)))
)
legacy_unique_mmsi = int(legacy_unique_result.scalar() or 0)
vessel_count = max(raw_unique_mmsi, legacy_unique_mmsi)
legacy_fallback_active = (
VESSEL_SNAPSHOT_LEGACY_FALLBACK_ENABLED
and raw_unique_mmsi == 0
and legacy_unique_mmsi > 0
)
vessel_count = legacy_unique_mmsi if legacy_fallback_active else raw_unique_mmsi
aisstream_health = await db.get(AISSourceHealth, "aisstream_vessels")
return {
@@ -2437,6 +2509,8 @@ async def get_visualization_geo_summary(db: AsyncSession = Depends(get_db)):
"satellite_count": satellite_count,
"compute_center_count": compute_center_count,
"vessel_count": vessel_count,
"vessel_count_source": "legacy_fallback" if legacy_fallback_active else "raw_recent",
"vessel_legacy_fallback_enabled": VESSEL_SNAPSHOT_LEGACY_FALLBACK_ENABLED,
"vessel_raw_unique_mmsi": raw_unique_mmsi,
"vessel_raw_unique_window_hours": raw_unique_window_hours,
"vessel_legacy_unique_mmsi": legacy_unique_mmsi,
+32 -3
View File
@@ -1,7 +1,6 @@
"""WebSocket API endpoints"""
import asyncio
import json
from datetime import UTC, datetime
from typing import Optional
@@ -95,14 +94,44 @@ async def websocket_endpoint(
}
)
elif data.get("type") == "subscribe":
channels = data.get("data", {}).get("channels", [])
payload_data = data.get("data", {})
if not isinstance(payload_data, dict):
payload_data = {}
channels = payload_data.get("channels", [])
if isinstance(channels, str):
channels = [channels]
elif not isinstance(channels, list):
channels = []
channel = payload_data.get("channel")
if channel and channel not in channels:
channels = [*channels, channel]
if is_anonymous:
channels = [channel for channel in channels if channel in supported_channels]
vessel_subscription = None
if "vessels" in channels and "bbox" in payload_data:
try:
vessel_subscription = manager.subscribe_vessels(websocket, payload_data)
except ValueError as exc:
await websocket.send_json(
{
"type": "subscription_error",
"data": {"channel": "vessels", "detail": str(exc)},
}
)
continue
channels = [channel for channel in channels if channel != "vessels"]
manager.subscribe(websocket, channels)
await websocket.send_json(
{
"type": "subscription_confirmed",
"data": {"action": "subscribe", "channels": channels},
"data": {
"action": "subscribe",
"channels": [
*channels,
*(["vessels"] if vessel_subscription else []),
],
"vessels": vessel_subscription,
},
}
)
elif data.get("type") == "unsubscribe":
+60 -1
View File
@@ -2,7 +2,7 @@
import asyncio
from datetime import UTC, datetime
from typing import Dict, Any, Optional
from typing import Dict, Any
from app.core.time import to_iso8601_utc
from app.core.websocket.manager import manager
@@ -15,6 +15,8 @@ class DataBroadcaster:
def __init__(self):
self.running = False
self.tasks: Dict[str, asyncio.Task] = {}
self._pending_vessel_updates: Dict[str, Dict[str, Any]] = {}
self._vessel_flush_interval = 1.0
async def get_dashboard_stats(self) -> Dict[str, Any]:
"""Get dashboard statistics"""
@@ -68,6 +70,9 @@ class DataBroadcaster:
async def broadcast_custom(self, channel: str, data: Dict[str, Any]):
"""Broadcast custom data to a specific channel"""
if channel == "vessels":
self.enqueue_vessel_update(data)
return
await manager.broadcast(
{
"type": "data_frame",
@@ -78,6 +83,58 @@ class DataBroadcaster:
channel=channel,
)
def enqueue_vessel_update(self, data: Dict[str, Any]):
vessels = data.get("vessels") if isinstance(data, dict) else None
if not isinstance(vessels, list):
return
source = data.get("source")
action = data.get("action") or "upsert"
created = data.get("created")
for vessel in vessels:
if not isinstance(vessel, dict):
continue
mmsi = vessel.get("mmsi")
if mmsi in (None, ""):
continue
self._pending_vessel_updates[str(mmsi)] = {
**vessel,
"_source": source,
"_action": action,
"_created": created,
}
async def flush_vessel_updates(self):
if not self._pending_vessel_updates:
return
pending = self._pending_vessel_updates
self._pending_vessel_updates = {}
vessels = []
for item in pending.values():
vessel = dict(item)
source = vessel.pop("_source", None)
action = vessel.pop("_action", "upsert")
created = vessel.pop("_created", None)
vessel["source"] = source
vessel["action"] = action
vessel["created"] = created
vessels.append(vessel)
await manager.broadcast_vessels(
{
"action": "upsert",
"source": "mixed",
"created": None,
"vessels": vessels,
}
)
async def broadcast_vessels_periodically(self):
while self.running:
try:
await self.flush_vessel_updates()
except Exception:
pass
await asyncio.sleep(self._vessel_flush_interval)
async def broadcast_datasource_task_update(self, data: Dict[str, Any]):
"""Broadcast datasource task progress updates to connected clients."""
await manager.broadcast(
@@ -95,6 +152,7 @@ class DataBroadcaster:
if not self.running:
self.running = True
self.tasks["dashboard"] = asyncio.create_task(self.broadcast_stats(5))
self.tasks["vessels"] = asyncio.create_task(self.broadcast_vessels_periodically())
def stop(self):
"""Stop all broadcasters"""
@@ -102,6 +160,7 @@ class DataBroadcaster:
for task in self.tasks.values():
task.cancel()
self.tasks.clear()
self._pending_vessel_updates.clear()
broadcaster = DataBroadcaster()
+104 -1
View File
@@ -1,11 +1,16 @@
"""WebSocket Connection Manager"""
from typing import Dict, Set, Optional
from datetime import UTC, datetime
from typing import Any, Dict, Set, Optional
from fastapi import WebSocket
import redis.asyncio as redis
from app.core.config import settings
MAX_VESSEL_SUBSCRIPTION_LIMIT = 5000
MAX_VESSEL_WS_MESSAGE_ITEMS = 1000
MAX_VESSEL_BBOX_AREA = 2500.0
class ConnectionManager:
"""Manages WebSocket connections"""
@@ -14,6 +19,7 @@ class ConnectionManager:
self.active_connections: Dict[str, Set[WebSocket]] = {} # user_id -> connections
self.channel_subscriptions: Dict[str, Set[WebSocket]] = {}
self.websocket_channels: Dict[WebSocket, Set[str]] = {}
self.vessel_subscriptions: Dict[WebSocket, dict[str, Any]] = {}
self.redis_client: Optional[redis.Redis] = None
async def connect(self, websocket: WebSocket, user_id: str):
@@ -72,6 +78,50 @@ class ConnectionManager:
channels = list(self.websocket_channels.get(websocket, set()))
if channels:
self.unsubscribe(websocket, channels)
self.vessel_subscriptions.pop(websocket, None)
def subscribe_vessels(self, websocket: WebSocket, config: dict[str, Any]) -> dict[str, Any]:
subscription = self._normalize_vessel_subscription(config)
self.channel_subscriptions.setdefault("vessels", set()).add(websocket)
self.websocket_channels.setdefault(websocket, set()).add("vessels")
self.vessel_subscriptions[websocket] = subscription
return subscription
def _normalize_vessel_subscription(self, config: dict[str, Any]) -> dict[str, Any]:
bbox = config.get("bbox")
if not isinstance(bbox, (list, tuple)) or len(bbox) != 4:
raise ValueError("vessels subscription requires bbox=[lon_min,lat_min,lon_max,lat_max]")
try:
lon_min, lat_min, lon_max, lat_max = [float(value) for value in bbox]
except (TypeError, ValueError) as exc:
raise ValueError("bbox values must be numbers") from exc
if lat_min > lat_max:
lat_min, lat_max = lat_max, lat_min
if lon_min > lon_max:
lon_min, lon_max = lon_max, lon_min
if not (-180 <= lon_min <= 180 and -180 <= lon_max <= 180):
raise ValueError("bbox longitude values must be between -180 and 180")
if not (-90 <= lat_min <= 90 and -90 <= lat_max <= 90):
raise ValueError("bbox latitude values must be between -90 and 90")
if (lon_max - lon_min) * (lat_max - lat_min) > MAX_VESSEL_BBOX_AREA:
raise ValueError("bbox is too large; zoom in or request a smaller viewport")
zoom = int(config.get("zoom") or 1)
if zoom < 1 or zoom > 20:
raise ValueError("zoom must be between 1 and 20")
limit = min(max(int(config.get("limit") or 1000), 1), MAX_VESSEL_SUBSCRIPTION_LIMIT)
vessel_types = {
str(item).strip().lower()
for item in str(config.get("type") or "").split(",")
if str(item).strip()
}
return {
"bbox": (lon_min, lat_min, lon_max, lat_max),
"zoom": zoom,
"limit": limit,
"type": vessel_types,
"last_sent_at": None,
}
async def send_personal_message(self, message: dict, user_id: str):
if user_id in self.active_connections:
@@ -92,6 +142,58 @@ class ConnectionManager:
except Exception:
self.unsubscribe_all(connection)
async def broadcast_vessels(self, data: dict[str, Any]):
vessels = data.get("vessels") if isinstance(data, dict) else None
if not isinstance(vessels, list) or not vessels:
return
for connection, subscription in list(self.vessel_subscriptions.items()):
matched = [
vessel
for vessel in vessels
if self._vessel_matches_subscription(vessel, subscription)
][: min(subscription["limit"], MAX_VESSEL_WS_MESSAGE_ITEMS)]
if not matched:
continue
subscription["last_sent_at"] = datetime.now(UTC)
message = {
"type": "data_frame",
"channel": "vessels",
"timestamp": subscription["last_sent_at"].isoformat(),
"payload": {
**data,
"vessels": matched,
"subscription": {
"bbox": list(subscription["bbox"]),
"zoom": subscription["zoom"],
"limit": subscription["limit"],
},
},
}
try:
await connection.send_json(message)
except Exception:
self.unsubscribe_all(connection)
def _vessel_matches_subscription(
self,
vessel: dict[str, Any],
subscription: dict[str, Any],
) -> bool:
try:
lon = float(vessel.get("lon"))
lat = float(vessel.get("lat"))
except (TypeError, ValueError):
return False
lon_min, lat_min, lon_max, lat_max = subscription["bbox"]
if not (lon_min <= lon <= lon_max and lat_min <= lat <= lat_max):
return False
requested_types = subscription.get("type") or set()
if not requested_types:
return True
type_name = str(vessel.get("vessel_type_name") or "").lower()
return any(requested_type in type_name for requested_type in requested_types)
async def close_all(self):
for user_id in self.active_connections:
for connection in self.active_connections[user_id]:
@@ -99,6 +201,7 @@ class ConnectionManager:
self.active_connections.clear()
self.channel_subscriptions.clear()
self.websocket_channels.clear()
self.vessel_subscriptions.clear()
manager = ConnectionManager()
+70 -14
View File
@@ -72,25 +72,44 @@ async def seed_default_datasources(session: AsyncSession):
await session.commit()
DEFAULT_LOGIN_USERS = (
{
"username": "admin",
"email": "admin@planet.local",
"password": "admin123",
"role": "super_admin",
},
{
"username": "linkong",
"email": "linkong@planet.local",
"password": "12345678",
"role": "super_admin",
},
)
async def ensure_default_admin_user(session: AsyncSession):
from app.core.security import get_password_hash
from app.models.user import User
result = await session.execute(
text("SELECT id FROM users WHERE username = 'admin'")
)
if result.fetchone():
return
for default_user in DEFAULT_LOGIN_USERS:
result = await session.execute(
text("SELECT id FROM users WHERE username = :username"),
{"username": default_user["username"]},
)
if result.fetchone():
continue
session.add(
User(
username="admin",
email="admin@planet.local",
password_hash=get_password_hash("admin123"),
role="super_admin",
is_active=True,
session.add(
User(
username=default_user["username"],
email=default_user["email"],
password_hash=get_password_hash(default_user["password"]),
role=default_user["role"],
is_active=True,
email_verified=True,
)
)
)
await session.commit()
@@ -130,14 +149,31 @@ async def init_db():
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
users_email_verified_existed = (
await conn.execute(
text(
"""
SELECT 1
FROM information_schema.columns
WHERE table_name = 'users' AND column_name = 'email_verified'
"""
)
)
).fetchone() is not None
await conn.execute(
text(
"""
ALTER TABLE users
ADD COLUMN IF NOT EXISTS gatekeeper_groups JSONB DEFAULT '[]'::jsonb
ADD COLUMN IF NOT EXISTS gatekeeper_groups JSONB DEFAULT '[]'::jsonb,
ADD COLUMN IF NOT EXISTS email_verified BOOLEAN NOT NULL DEFAULT FALSE,
ADD COLUMN IF NOT EXISTS pending_email VARCHAR(255)
"""
)
)
if not users_email_verified_existed:
await conn.execute(
text("UPDATE users SET email_verified = TRUE WHERE email_verified = FALSE")
)
await conn.execute(
text(
"""
@@ -198,6 +234,26 @@ async def init_db():
"""
)
)
await conn.execute(
text(
"""
CREATE INDEX IF NOT EXISTS idx_ais_raw_schema_observed_desc
ON ais_raw_observations (target_schema, observed_at DESC)
"""
)
)
await conn.execute(
text(
"""
CREATE INDEX IF NOT EXISTS idx_ais_raw_payload_lon_lat
ON ais_raw_observations (
((normalized_payload->>'lon')::double precision),
((normalized_payload->>'lat')::double precision)
)
WHERE target_schema = 'vessel_ais'
"""
)
)
await conn.execute(
text(
"""
+2
View File
@@ -14,6 +14,8 @@ class User(Base):
role = Column(String(20), default="viewer")
gatekeeper_groups = Column(JSON, default=list)
is_active = Column(Boolean, default=True)
email_verified = Column(Boolean, default=False, nullable=False)
pending_email = Column(String(255), nullable=True)
last_login_at = Column(DateTime(timezone=True))
created_at = Column(DateTime(timezone=True), server_default=func.now())
updated_at = Column(
+27
View File
@@ -39,7 +39,34 @@ class UserResponse(UserBase):
role: str
gatekeeper_groups: list[str] = Field(default_factory=list)
is_active: bool
email_verified: bool = False
created_at: datetime
class Config:
from_attributes = True
class UserRegister(BaseModel):
username: str = Field(..., min_length=3, max_length=50)
email: EmailStr
password: str = Field(..., min_length=8, max_length=128)
class VerifyEmailRequest(BaseModel):
email: EmailStr
code: str = Field(..., min_length=6, max_length=6)
class ResendCodeRequest(BaseModel):
email: EmailStr
purpose: str = Field(default="register", pattern="^(register|verify_email|reset_password)$")
class ForgotPasswordRequest(BaseModel):
email: EmailStr
class ResetPasswordRequest(BaseModel):
email: EmailStr
code: str = Field(..., min_length=6, max_length=6)
new_password: str = Field(..., min_length=8, max_length=128)
+1 -1
View File
@@ -138,7 +138,7 @@ class AISStreamCollector(BaseCollector):
try:
import websockets
except ImportError as exc:
except ImportError:
return {"status": "failed", "error": "Python package 'websockets' is required for AISStream"}
start_time = datetime.now(UTC)
+1
View File
@@ -53,6 +53,7 @@ DOCS_METADATA: tuple[DocsMetadata, ...] = (
DocsMetadata("backend-datasources-api-performance.md", "backend-datasources-api-performance", "docs_developer", "Backend", 33, "数据源 API 性能", "Datasource API Performance"),
DocsMetadata("location-pipeline-development.md", "location-pipeline-development", "docs_developer", "Backend", 34, "通用位置估算管线开发说明", "Shared Location Resolution Pipeline Development Guide"),
DocsMetadata("agents-aiprovider.md", "agents-aiprovider", "docs_developer", "Agents", 40, "AI Provider 指南", "AI Provider Guide"),
DocsMetadata("ops-runbook.md", "ops-runbook", "docs_admin", "Ops", 49, "Planet 运维手册", "Planet Ops Runbook"),
DocsMetadata("ops-docker-compose-buildx-upgrade.md", "ops-docker-compose-buildx-upgrade", "docs_admin", "Ops", 50, "Docker + Compose + Buildx 升级", "Docker + Compose + Buildx Upgrade"),
DocsMetadata("ops-planet-sh-startup.md", "ops-planet-sh-startup", "docs_admin", "Ops", 51, "planet.sh 启动机制", "planet.sh Startup"),
)
+123
View File
@@ -0,0 +1,123 @@
"""SMTP-backed email sender.
Generic primitive used by registration/verification today, reusable for alert
digests and other notifications later. Configuration lives in the `smtp` row of
`system_settings` and is loaded once per send (small surface, no caching layer
yet to keep behavior obvious after settings changes).
"""
from __future__ import annotations
from email.message import EmailMessage
from typing import Literal, Optional
import aiosmtplib
from sqlalchemy.ext.asyncio import AsyncSession
OtpPurpose = Literal["register", "verify_email", "reset_password"]
class EmailError(Exception):
code: str = "EMAIL_ERROR"
class EmailNotConfiguredError(EmailError):
code = "EMAIL_PROVIDER_NOT_CONFIGURED"
class EmailSendError(EmailError):
code = "EMAIL_SEND_FAILED"
async def _load_smtp_config(db: AsyncSession) -> dict:
from app.api.v1.settings import get_setting_payload # local import avoids cycle
payload = await get_setting_payload(db, "smtp")
if not payload.get("host") or not payload.get("from_address"):
raise EmailNotConfiguredError("SMTP host/from_address not set")
return payload
async def send_email(
db: AsyncSession,
*,
to: str,
subject: str,
text_body: str,
html_body: Optional[str] = None,
config: Optional[dict] = None,
) -> None:
cfg = config or await _load_smtp_config(db)
message = EmailMessage()
from_name = (cfg.get("from_name") or "").strip()
from_address = cfg["from_address"]
message["From"] = f"{from_name} <{from_address}>" if from_name else from_address
message["To"] = to
message["Subject"] = subject
message.set_content(text_body)
if html_body:
message.add_alternative(html_body, subtype="html")
use_tls = bool(cfg.get("use_tls", True))
use_starttls = bool(cfg.get("use_starttls", False))
port = int(cfg.get("port") or (465 if use_tls else 587))
try:
await aiosmtplib.send(
message,
hostname=cfg["host"],
port=port,
username=cfg.get("username") or None,
password=cfg.get("password") or None,
use_tls=use_tls and not use_starttls,
start_tls=use_starttls,
timeout=int(cfg.get("timeout_seconds") or 20),
)
except aiosmtplib.SMTPException as exc:
raise EmailSendError(str(exc)) from exc
except OSError as exc:
raise EmailSendError(str(exc)) from exc
_SUBJECTS: dict[OtpPurpose, str] = {
"register": "Confirm your Planet account",
"verify_email": "Verify your Planet email",
"reset_password": "Reset your Planet password",
}
_HEADLINES: dict[OtpPurpose, str] = {
"register": "Welcome to Planet — confirm your email to activate your account.",
"verify_email": "Confirm your new email address to keep your Planet account active.",
"reset_password": "Use this code to set a new password for your Planet account.",
}
async def send_verification_email(
db: AsyncSession,
*,
to: str,
code: str,
purpose: OtpPurpose,
config: Optional[dict] = None,
) -> None:
subject = _SUBJECTS[purpose]
headline = _HEADLINES[purpose]
text_body = (
f"{headline}\n\n"
f"Your verification code: {code}\n"
"This code expires in 10 minutes. If you did not request it, ignore this email.\n"
)
html_body = (
f"<p>{headline}</p>"
f"<p style=\"font-size:24px;letter-spacing:4px;font-family:monospace\"><b>{code}</b></p>"
"<p>This code expires in 10 minutes. If you did not request it, ignore this email.</p>"
)
await send_email(
db,
to=to,
subject=subject,
text_body=text_body,
html_body=html_body,
config=config,
)
+100
View File
@@ -0,0 +1,100 @@
"""One-time verification codes backed by Redis.
Reusable primitive for register/verify-email/reset-password (and any future 2FA or
phone-number verification). Codes are bcrypt-hashed before storage so a Redis dump
does not leak active codes.
"""
from __future__ import annotations
import json
import secrets
from typing import Literal
import bcrypt
from app.core.security import redis_client
OtpPurpose = Literal["register", "verify_email", "reset_password"]
CODE_TTL_SECONDS = 600 # 10 minutes
RESEND_COOLDOWN_SECONDS = 60
MAX_ATTEMPTS = 5
CODE_LENGTH = 6
class OtpError(Exception):
code: str = "OTP_ERROR"
class OtpResendRateLimited(OtpError):
code = "OTP_RESEND_RATE_LIMITED"
def __init__(self, retry_after_seconds: int) -> None:
super().__init__(f"Resend allowed in {retry_after_seconds}s")
self.retry_after_seconds = retry_after_seconds
class OtpInvalid(OtpError):
code = "OTP_INVALID"
class OtpExpired(OtpError):
code = "OTP_EXPIRED"
class OtpAttemptsExceeded(OtpError):
code = "OTP_ATTEMPTS_EXCEEDED"
def _code_key(email: str, purpose: OtpPurpose) -> str:
return f"otp:{purpose}:{email.lower()}"
def _rate_key(email: str, purpose: OtpPurpose) -> str:
return f"otp_rate:{purpose}:{email.lower()}"
def _generate_code() -> str:
# secrets.randbelow gives uniform 0..10**CODE_LENGTH-1 without modulo bias
return f"{secrets.randbelow(10 ** CODE_LENGTH):0{CODE_LENGTH}d}"
def check_resend_allowed(email: str, purpose: OtpPurpose) -> None:
ttl = redis_client.ttl(_rate_key(email, purpose))
if ttl and ttl > 0:
raise OtpResendRateLimited(ttl)
def issue_code(email: str, purpose: OtpPurpose) -> str:
"""Generate a new code, persist its hash, and start the resend cooldown.
Caller is responsible for delivering the returned plaintext (e.g. via email).
Any pre-existing code for the same (purpose, email) is overwritten.
"""
check_resend_allowed(email, purpose)
code = _generate_code()
hashed = bcrypt.hashpw(code.encode(), bcrypt.gensalt()).decode()
payload = json.dumps({"hash": hashed, "attempts": 0})
redis_client.set(_code_key(email, purpose), payload, ex=CODE_TTL_SECONDS)
redis_client.set(_rate_key(email, purpose), "1", ex=RESEND_COOLDOWN_SECONDS)
return code
def verify_code(email: str, purpose: OtpPurpose, code: str) -> None:
"""Validate and consume a code. Raises subclasses of OtpError on failure."""
key = _code_key(email, purpose)
raw = redis_client.get(key)
if raw is None:
raise OtpExpired("Code expired or never issued")
record = json.loads(raw)
attempts = int(record.get("attempts", 0))
if attempts >= MAX_ATTEMPTS:
redis_client.delete(key)
raise OtpAttemptsExceeded("Too many invalid attempts")
if not bcrypt.checkpw(code.encode(), record["hash"].encode()):
record["attempts"] = attempts + 1
ttl = redis_client.ttl(key)
redis_client.set(key, json.dumps(record), ex=max(ttl, 1))
raise OtpInvalid("Incorrect code")
redis_client.delete(key)
+5
View File
@@ -374,6 +374,11 @@ def run_collector_now(collector_name: str) -> bool:
return False
def is_collector_running(collector_name: str) -> bool:
task = get_running_collector_task(collector_name)
return bool(task is not None and not task.done())
async def cancel_running_collector_now(collector_name: str) -> bool:
task = get_running_collector_task(collector_name)
if task is None or task.done():
@@ -6,6 +6,7 @@ import json
from typing import Any, Iterable
from sqlalchemy import select
from sqlalchemy import Float
from sqlalchemy.ext.asyncio import AsyncSession
from app.models.vessel import AISConflictRecord, AISRawObservation, AISSourceHealth
@@ -17,6 +18,10 @@ from app.services.vessel_types import normalize_vessel_type_name
VESSEL_AIS_SCHEMA = "vessel_ais"
DEFAULT_AGGREGATION_WINDOW_HOURS = 24
DEFAULT_SNAPSHOT_WINDOW_MINUTES = 60
MAX_SNAPSHOT_LIMIT = 5000
MAX_SNAPSHOT_CANDIDATE_MULTIPLIER = 20
MAX_SNAPSHOT_CANDIDATE_OBSERVATIONS = 100_000
BARENTSWATCH_DELIVERY_MODE = "polling"
BARENTSWATCH_TRANSPORT = "http"
AISSTREAM_DELIVERY_MODE = "realtime_stream"
@@ -564,6 +569,46 @@ async def get_aggregated_vessels(
return vessels
async def get_aggregated_vessels_snapshot(
db: AsyncSession,
*,
bbox: tuple[float, float, float, float],
limit: int = 1000,
observed_since: datetime | None = None,
) -> list[dict[str, Any]]:
"""Return a bounded viewport snapshot without loading the global AIS window."""
observed_since = observed_since or (
datetime.now(UTC) - timedelta(minutes=DEFAULT_SNAPSHOT_WINDOW_MINUTES)
)
safe_limit = min(max(int(limit or 1000), 1), MAX_SNAPSHOT_LIMIT)
candidate_limit = min(
max(safe_limit * MAX_SNAPSHOT_CANDIDATE_MULTIPLIER, safe_limit),
MAX_SNAPSHOT_CANDIDATE_OBSERVATIONS,
)
lon_min, lat_min, lon_max, lat_max = bbox
payload_lon = AISRawObservation.normalized_payload["lon"].as_string().cast(Float)
payload_lat = AISRawObservation.normalized_payload["lat"].as_string().cast(Float)
stmt = (
select(AISRawObservation)
.where(AISRawObservation.target_schema == VESSEL_AIS_SCHEMA)
.where(AISRawObservation.observed_at >= observed_since)
.where(payload_lon >= lon_min)
.where(payload_lon <= lon_max)
.where(payload_lat >= lat_min)
.where(payload_lat <= lat_max)
.order_by(AISRawObservation.observed_at.desc(), AISRawObservation.id.desc())
.limit(candidate_limit)
)
result = await db.execute(stmt)
if not hasattr(result, "scalars"):
return []
vessels = await aggregate_vessel_observations(db, result.scalars().all())
return vessels[:safe_limit]
async def get_aggregated_vessel(db: AsyncSession, mmsi: int) -> dict[str, Any] | None:
observations = await get_vessel_raw_observations(db, mmsi, limit=1000)
vessels = await aggregate_vessel_observations(db, observations)
+5 -4
View File
@@ -17,15 +17,16 @@ async def create_admin():
existing_user = result.scalar_one_or_none()
if existing_user:
print(f"用户 linkong 已存在,更新密码...")
existing_user.set_password("LK12345678")
print("用户 linkong 已存在,更新密码...")
existing_user.set_password("12345678")
existing_user.role = "super_admin"
existing_user.email = "linkong@planet.local"
else:
print("创建管理员用户...")
user = User(
username="linkong",
email="linkong@example.com",
password_hash=get_password_hash("LK12345678"),
email="linkong@planet.local",
password_hash=get_password_hash("12345678"),
role="super_admin",
is_active=True,
)
+43 -14
View File
@@ -6,29 +6,58 @@ import sys
sys.path.insert(0, ".")
from app.core.security import get_password_hash
from app.db.session import engine, async_session_factory
from app.db.session import async_session_factory
from app.models.user import User
DEFAULT_LOGIN_USERS = (
{
"username": "admin",
"email": "admin@planet.local",
"password": "admin123",
"role": "super_admin",
},
{
"username": "linkong",
"email": "linkong@planet.local",
"password": "12345678",
"role": "super_admin",
},
)
async def create_admin():
from sqlalchemy import text
async with async_session_factory() as session:
result = await session.execute(text("SELECT id FROM users WHERE username = 'admin'"))
if result.fetchone():
print("Admin user already exists")
created = []
for default_user in DEFAULT_LOGIN_USERS:
result = await session.execute(
text("SELECT id FROM users WHERE username = :username"),
{"username": default_user["username"]},
)
if result.fetchone():
continue
session.add(
User(
username=default_user["username"],
email=default_user["email"],
password_hash=get_password_hash(default_user["password"]),
role=default_user["role"],
is_active=True,
)
)
created.append(default_user)
await session.commit()
if not created:
print("Default login users already exist")
return
admin = User(
username="admin",
email="admin@planet.local",
password_hash=get_password_hash("admin123"),
role="super_admin",
is_active=True,
)
session.add(admin)
await session.commit()
print("Admin user created: admin / admin123")
for default_user in created:
print(
f"Default login user created: {default_user['username']} / {default_user['password']}"
)
if __name__ == "__main__":
+48 -17
View File
@@ -12,8 +12,20 @@ from sqlalchemy.orm import sessionmaker
import bcrypt
# Generate proper bcrypt hash
ADMIN_PASSWORD_HASH = bcrypt.hashpw("admin123".encode(), bcrypt.gensalt()).decode()
DEFAULT_LOGIN_USERS = (
{
"username": "admin",
"email": "admin@planet.local",
"password": "admin123",
"role": "super_admin",
},
{
"username": "linkong",
"email": "linkong@planet.local",
"password": "12345678",
"role": "super_admin",
},
)
async def create_admin():
@@ -22,23 +34,42 @@ async def create_admin():
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
async with async_session() as session:
result = await session.execute(
text("SELECT id FROM users WHERE username = 'admin'")
)
if result.fetchone():
print("Admin user already exists")
created = []
for default_user in DEFAULT_LOGIN_USERS:
result = await session.execute(
text("SELECT id FROM users WHERE username = :username"),
{"username": default_user["username"]},
)
if result.fetchone():
continue
password_hash = bcrypt.hashpw(
default_user["password"].encode(), bcrypt.gensalt()
).decode()
await session.execute(
text("""
INSERT INTO users (username, email, password_hash, role, is_active, created_at, updated_at)
VALUES (:username, :email, :password, :role, true, NOW(), NOW())
"""),
{
"username": default_user["username"],
"email": default_user["email"],
"password": password_hash,
"role": default_user["role"],
},
)
created.append((default_user, password_hash))
await session.commit()
if not created:
print("Default login users already exist")
return
await session.execute(
text("""
INSERT INTO users (username, email, password_hash, role, is_active, created_at, updated_at)
VALUES ('admin', 'admin@planet.local', :password, 'super_admin', true, NOW(), NOW())
"""),
{"password": ADMIN_PASSWORD_HASH},
)
await session.commit()
print(f"Admin user created: admin / admin123")
print(f"Hash: {ADMIN_PASSWORD_HASH}")
for default_user, password_hash in created:
print(
f"Default login user created: {default_user['username']} / {default_user['password']}"
)
print(f"Hash: {password_hash}")
if __name__ == "__main__":
+47 -11
View File
@@ -18,6 +18,17 @@ from app.schemas.ai import (
)
class _FakeRedisClient:
def sismember(self, *_args, **_kwargs):
return False
@pytest.fixture(autouse=True)
def fake_token_blacklist(monkeypatch):
"""Keep API auth tests independent from an external Redis service."""
monkeypatch.setattr("app.core.security.redis_client", _FakeRedisClient())
@pytest.fixture
def auth_headers():
"""Create authentication headers"""
@@ -62,20 +73,43 @@ async def test_dashboard_stats_without_auth():
@pytest.mark.asyncio
async def test_dashboard_stats_with_auth(auth_headers):
"""Test dashboard stats with authentication"""
with patch("app.api.v1.dashboard.cache.get", return_value=None):
with patch("app.api.v1.dashboard.cache.set", return_value=True):
with patch("app.db.session.get_db") as mock_get_db:
mock_session = AsyncMock()
mock_result = AsyncMock()
mock_result.scalar.return_value = 0
mock_result.fetchall.return_value = []
mock_session.execute.return_value = mock_result
class _StatsResult:
def __init__(self, row):
self._row = row
async def mock_db_context():
yield mock_session
def one(self):
return self._row
mock_get_db.return_value = mock_db_context()
class _FakeStatsSession:
def __init__(self):
self._rows = [
type("DatasourceStats", (), {"custom_count": 0, "custom_active": 0})(),
type("TaskStats", (), {"tasks_today": 0, "success_tasks": 0})(),
type(
"AlertStats",
(),
{"critical_alerts": 0, "warning_alerts": 0, "info_alerts": 0},
)(),
]
async def execute(self, _query):
return _StatsResult(self._rows.pop(0))
def override_get_current_user():
return User(id=1, username="testuser", email="test@example.com", role="admin", is_active=True)
async def override_get_db():
yield _FakeStatsSession()
app.dependency_overrides.update(
{
__import__("app.core.security", fromlist=["get_current_user"]).get_current_user: override_get_current_user,
get_db: override_get_db,
}
)
try:
with patch("app.api.v1.dashboard.cache.get", return_value=None):
with patch("app.api.v1.dashboard.cache.set", return_value=True):
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as client:
response = await client.get(
@@ -85,6 +119,8 @@ async def test_dashboard_stats_with_auth(auth_headers):
assert response.status_code == 200
data = response.json()
assert "total_datasources" in data
finally:
app.dependency_overrides.clear()
@pytest.mark.asyncio
+86
View File
@@ -0,0 +1,86 @@
from datetime import datetime, timedelta, timezone
import pytest
from app.api.v1 import datasources as datasources_api
from app.models.datasource import DataSource
def make_datasource(
datasource_id: int,
source: str,
*,
name: str | None = None,
module: str = "L4",
is_active: bool = True,
last_status: str | None = None,
last_run_at: datetime | None = None,
frequency_minutes: int = 60,
) -> DataSource:
return DataSource(
id=datasource_id,
name=name or source,
source=source,
module=module,
priority="P1",
frequency_minutes=frequency_minutes,
collector_class=source,
is_active=is_active,
last_status=last_status,
last_run_at=last_run_at,
)
def test_datasource_product_key_groups_domain_specific_sources():
assert datasources_api.datasource_product_key(make_datasource(1, "aisstream_vessels")) == "vessels"
assert datasources_api.datasource_product_key(make_datasource(2, "telegeography_cables")) == "cables"
assert datasources_api.datasource_product_key(make_datasource(3, "celestrak_tle")) == "satellites"
assert datasources_api.datasource_product_key(make_datasource(4, "ris_live_bgp")) == "bgp"
def test_filter_datasources_by_product_status_and_collected_state():
vessels = make_datasource(1, "aisstream_vessels", last_status="success")
cables = make_datasource(2, "telegeography_cables", last_status="failed")
filtered = datasources_api._filter_datasources_in_memory(
[vessels, cables],
running_tasks={},
record_counts={"aisstream_vessels": 12, "telegeography_cables": 0},
product="vessels",
run_status="success",
collected=True,
)
assert filtered == [vessels]
@pytest.mark.asyncio
async def test_trigger_datasource_batch_skips_disabled_and_frequency_window(monkeypatch):
now = datetime.now(timezone.utc)
disabled = make_datasource(1, "aisstream_vessels", is_active=False)
not_due = make_datasource(2, "telegeography_cables", last_run_at=now, frequency_minutes=120)
due = make_datasource(3, "ris_live_bgp", last_run_at=now - timedelta(hours=2))
triggered_sources: list[str] = []
async def fake_running_tasks(_db, _ids):
return {}
async def fake_latest_task_ids(_db, _ids):
return {}
monkeypatch.setattr(datasources_api, "_load_latest_running_tasks", fake_running_tasks)
monkeypatch.setattr(datasources_api, "_load_latest_task_ids", fake_latest_task_ids)
monkeypatch.setattr(
datasources_api,
"run_collector_now",
lambda source: triggered_sources.append(source) or True,
)
result = await datasources_api._trigger_datasource_batch(
object(),
[disabled, not_due, due],
force=False,
)
assert [item["source"] for item in result["triggered"]] == ["ris_live_bgp"]
assert {item["reason"] for item in result["skipped"]} == {"disabled", "within_frequency_window"}
assert triggered_sources == ["ris_live_bgp"]
+70
View File
@@ -0,0 +1,70 @@
from fastapi import HTTPException
import pytest
from app.api.v1 import layers
def test_layer_guard_requires_bbox():
try:
layers._parse_layer_bbox("")
except HTTPException as exc:
assert exc.status_code == 400
else:
raise AssertionError("Expected missing bbox to fail")
def test_layer_guard_filters_bbox_and_clamps_low_zoom_limit():
geojson = {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [121.0, 31.0]},
"properties": {"id": "inside"},
},
{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [10.0, 10.0]},
"properties": {"id": "outside"},
},
],
}
result = layers._guard_geojson_layer(
geojson,
bbox=(120.0, 30.0, 122.0, 32.0),
zoom=2,
limit=6000,
)
assert result["returned_count"] == 1
assert result["visible_count"] == 1
assert result["features"][0]["properties"]["id"] == "inside"
assert result["diagnostics"]["limit"] == layers.LOW_ZOOM_FEATURE_LIMIT
assert result["diagnostics"]["limit_clamped"] is True
assert result["diagnostics"]["degraded"] is True
@pytest.mark.asyncio
async def test_vessel_layer_snapshot_passes_type_filter(monkeypatch):
captured = {}
async def fake_build_vessel_snapshot_response(db, **kwargs):
captured.update(kwargs)
return {"type": "FeatureCollection", "features": []}
monkeypatch.setattr(layers, "build_vessel_snapshot_response", fake_build_vessel_snapshot_response)
result = await layers.get_vessel_layer_snapshot(
bbox="10,59,11,60",
zoom=12,
limit=1000,
vessel_type="cargo",
since_minutes=30,
db=object(),
)
assert result["features"] == []
assert captured["bbox"] == (10.0, 59.0, 11.0, 60.0)
assert captured["type_filter"] == "cargo"
assert "vessel_type" not in captured
+106
View File
@@ -0,0 +1,106 @@
"""Unit tests for app.services.otp using an in-memory Redis fake."""
from __future__ import annotations
import time
from typing import Any
import pytest
from app.services import otp
class FakeRedis:
"""Minimal subset of redis-py used by services.otp."""
def __init__(self) -> None:
self._store: dict[str, tuple[Any, float | None]] = {}
def _expired(self, key: str) -> bool:
item = self._store.get(key)
if item is None:
return True
_, expires = item
if expires is not None and expires <= time.time():
self._store.pop(key, None)
return True
return False
def set(self, key: str, value: Any, ex: int | None = None) -> None:
expires = time.time() + ex if ex else None
self._store[key] = (value, expires)
def get(self, key: str) -> Any:
if self._expired(key):
return None
return self._store[key][0]
def ttl(self, key: str) -> int:
if self._expired(key):
return -2
_, expires = self._store[key]
if expires is None:
return -1
return max(int(expires - time.time()), 0)
def delete(self, key: str) -> None:
self._store.pop(key, None)
@pytest.fixture
def fake_redis(monkeypatch):
fake = FakeRedis()
monkeypatch.setattr(otp, "redis_client", fake)
return fake
def test_issue_code_returns_six_digits(fake_redis):
code = otp.issue_code("alice@example.com", "register")
assert len(code) == 6
assert code.isdigit()
def test_verify_code_succeeds_and_consumes(fake_redis):
code = otp.issue_code("alice@example.com", "register")
otp.verify_code("alice@example.com", "register", code)
with pytest.raises(otp.OtpExpired):
otp.verify_code("alice@example.com", "register", code)
def test_verify_code_rejects_wrong_code(fake_redis):
otp.issue_code("alice@example.com", "register")
with pytest.raises(otp.OtpInvalid):
otp.verify_code("alice@example.com", "register", "000000")
def test_verify_code_locks_after_max_attempts(fake_redis):
code = otp.issue_code("alice@example.com", "register")
for _ in range(otp.MAX_ATTEMPTS):
with pytest.raises(otp.OtpInvalid):
otp.verify_code("alice@example.com", "register", "000000")
# After max attempts the next call should raise OtpAttemptsExceeded and clear the code.
with pytest.raises(otp.OtpAttemptsExceeded):
otp.verify_code("alice@example.com", "register", code)
with pytest.raises(otp.OtpExpired):
otp.verify_code("alice@example.com", "register", code)
def test_issue_code_enforces_resend_cooldown(fake_redis):
otp.issue_code("alice@example.com", "register")
with pytest.raises(otp.OtpResendRateLimited) as excinfo:
otp.issue_code("alice@example.com", "register")
assert excinfo.value.retry_after_seconds > 0
def test_issue_code_emails_are_case_insensitive(fake_redis):
code = otp.issue_code("Alice@Example.com", "register")
otp.verify_code("alice@example.com", "register", code)
def test_purposes_are_isolated(fake_redis):
register_code = otp.issue_code("alice@example.com", "register")
reset_code = otp.issue_code("alice@example.com", "reset_password")
assert register_code != reset_code
otp.verify_code("alice@example.com", "register", register_code)
# Reset code should still be valid after consuming the register code.
otp.verify_code("alice@example.com", "reset_password", reset_code)
+101
View File
@@ -0,0 +1,101 @@
from datetime import UTC, datetime
from unittest.mock import AsyncMock
import pytest
from fastapi import HTTPException
from app.api.v1 import realtime_sources
from app.models.datasource import DataSource
from app.models.datasource_config import DataSourceConfig
from app.models.vessel import AISSourceHealth
@pytest.mark.asyncio
async def test_serialize_builtin_aisstream_includes_health_config_and_stats(monkeypatch):
datasource = DataSource(
id=28,
name="AISStream Vessels",
source="aisstream_vessels",
module="L4",
priority="P1",
collector_class="aisstream_vessels",
is_active=True,
)
config = DataSourceConfig(
id=3,
name="aisstream_vessels",
source_type="websocket",
endpoint="wss://stream.aisstream.io/v0/stream",
auth_type="api_key",
auth_config={"api_key": "test-key"},
config={
"message_types": ["PositionReport"],
"bounding_boxes": [[[-10, 50], [35, 75]]],
},
is_active=True,
)
health = AISSourceHealth(
source="aisstream_vessels",
connection_state="connected",
last_seen_at=datetime(2026, 5, 13, 1, 0, tzinfo=UTC),
)
class _Session:
async def get(self, _model, key):
assert key == "aisstream_vessels"
return health
monkeypatch.setattr(
realtime_sources,
"_load_realtime_stats",
AsyncMock(
return_value={
"total_observations": 10,
"observations_24h": 4,
"observations_1h": 1,
"unique_mmsi_total": 8,
"unique_mmsi_24h": 3,
"latest_observed_at": "2026-05-13T01:00:00Z",
"latest_collected_at": "2026-05-13T01:00:01Z",
}
),
)
monkeypatch.setattr(realtime_sources, "is_collector_running", lambda source: False)
payload = await realtime_sources._serialize_builtin_aisstream(_Session(), datasource, config)
assert payload["source"] == "aisstream_vessels"
assert payload["kind"] == "builtin"
assert payload["credential_configured"] is True
assert payload["message_types"] == ["PositionReport"]
assert payload["runtime"]["running"] is False
assert payload["health"]["connection_state"] == "connected"
assert payload["stats"]["total_observations"] == 10
@pytest.mark.asyncio
async def test_start_builtin_realtime_source_rejects_disabled(monkeypatch):
datasource = DataSource(
id=28,
name="AISStream Vessels",
source="aisstream_vessels",
module="L4",
priority="P1",
collector_class="aisstream_vessels",
is_active=False,
)
monkeypatch.setattr(
realtime_sources,
"_load_builtin_aisstream",
AsyncMock(return_value=(datasource, None)),
)
with pytest.raises(HTTPException) as excinfo:
await realtime_sources.start_realtime_source(
"aisstream_vessels",
current_user=object(),
db=object(),
)
assert excinfo.value.status_code == 400
assert "disabled" in excinfo.value.detail
@@ -5,9 +5,12 @@ import pytest
from app.api.v1 import settings as settings_api
from app.api.v1.settings import (
AIProviderIntegrationUpdate,
OCRIntegrationUpdate,
_build_ai_provider_payload,
_build_ocr_payload,
_mask_secret,
_normalize_ai_provider_payload,
_normalize_ocr_payload,
_resolve_provider_api_key,
get_runtime_ai_provider_config,
)
@@ -130,6 +133,43 @@ def test_build_payload_keeps_saved_key_when_preview_submitted():
assert payload["providers"]["openai"]["api_key"] == "sk-old-secret"
def test_normalize_ocr_payload_adds_defaults():
payload = _normalize_ocr_payload({})
assert payload["enabled"] is False
assert payload["provider"] == "paddleocr"
assert payload["languages"] == ["zh", "en"]
assert payload["output_format"] == "markdown"
def test_build_ocr_payload_keeps_saved_key_when_preview_submitted():
current = {
"ocr": {
"enabled": True,
"provider": "custom",
"base_url": "http://localhost:8020",
"api_key": "ocr-old-secret",
}
}
update = OCRIntegrationUpdate(
enabled=True,
provider="custom",
base_url="http://localhost:8020",
api_key="**************",
model="ocr-model",
languages=["zh", "en"],
timeout_seconds=45,
max_file_size_mb=50,
output_format="json",
)
payload = _build_ocr_payload(current, update)
assert payload["api_key"] == "ocr-old-secret"
assert payload["model"] == "ocr-model"
assert payload["output_format"] == "json"
@pytest.mark.asyncio
async def test_runtime_config_uses_default_provider_specific_key(monkeypatch):
record = SimpleNamespace(
+86
View File
@@ -0,0 +1,86 @@
"""Unit tests for SMTP settings helpers in app.api.v1.settings."""
from app.api.v1.settings import (
SMTPSettingsUpdate,
_build_smtp_payload,
_serialize_smtp_payload,
)
def test_serialize_masks_password_and_reports_configured():
serialized = _serialize_smtp_payload(
{
"host": "smtp.example.com",
"port": 587,
"username": "noreply@example.com",
"password": "super-secret",
"from_address": "noreply@example.com",
"from_name": "Planet",
"use_tls": False,
"use_starttls": True,
"timeout_seconds": 20,
}
)
assert serialized["configured"] is True
assert serialized["password"]["configured"] is True
assert "secret" not in serialized["password"]["preview"]
def test_serialize_marks_unconfigured_when_host_missing():
serialized = _serialize_smtp_payload(
{
"host": "",
"port": 587,
"from_address": "",
}
)
assert serialized["configured"] is False
assert serialized["password"]["configured"] is False
def test_build_payload_preserves_password_when_placeholder_submitted():
current = {
"host": "smtp.example.com",
"port": 587,
"username": "noreply@example.com",
"password": "super-secret",
"from_address": "noreply@example.com",
"from_name": "Planet",
"use_tls": False,
"use_starttls": True,
"timeout_seconds": 20,
}
preview = _serialize_smtp_payload(current)["password"]["preview"]
update = SMTPSettingsUpdate(
host="smtp.example.com",
port=587,
username="noreply@example.com",
password=preview,
from_address="noreply@example.com",
)
merged = _build_smtp_payload(current, update)
assert merged["password"] == "super-secret"
def test_build_payload_replaces_password_when_new_value_submitted():
current = {"password": "old", "host": "", "port": 587, "from_address": ""}
update = SMTPSettingsUpdate(
host="smtp.example.com",
port=587,
password="new-secret",
from_address="noreply@example.com",
)
merged = _build_smtp_payload(current, update)
assert merged["password"] == "new-secret"
def test_build_payload_clears_password_when_requested():
current = {"password": "old"}
update = SMTPSettingsUpdate(
host="smtp.example.com",
port=587,
from_address="noreply@example.com",
clear_password=True,
)
merged = _build_smtp_payload(current, update)
assert merged["password"] == ""
+147 -57
View File
@@ -523,22 +523,114 @@ def test_convert_vessels_to_geojson_dedupes_mmsi_rows():
@pytest.mark.asyncio
async def test_vessels_geojson_endpoint_filters_type_and_bbox():
async def test_vessel_snapshot_filters_type_and_bbox(monkeypatch):
now = datetime(2026, 4, 28, 1, 0, tzinfo=timezone.utc)
rows = [
(
VesselPosition(mmsi=1, lat=59.9, lon=10.7, received_at=now),
VesselStatic(mmsi=1, name="Cargo Ship", vessel_type=70, vessel_type_name="Cargo"),
monkeypatch.setattr(
visualization,
"get_aggregated_vessels_snapshot",
AsyncMock(
return_value=[
{
"mmsi": 1,
"lat": 59.9,
"lon": 10.7,
"received_at": now,
"name": "Cargo Ship",
"vessel_type": 70,
"vessel_type_name": "Cargo",
},
{
"mmsi": 2,
"lat": 60.3,
"lon": 5.3,
"received_at": now - timedelta(minutes=1),
"name": "Passenger Ship",
"vessel_type": 60,
"vessel_type_name": "Passenger",
},
]
),
(
VesselPosition(mmsi=2, lat=60.3, lon=5.3, received_at=now - timedelta(minutes=1)),
VesselStatic(mmsi=2, name="Passenger Ship", vessel_type=60, vessel_type_name="Passenger"),
),
]
)
async def override_get_db():
yield object()
app.dependency_overrides[get_db] = override_get_db
transport = ASGITransport(app=app)
try:
async with AsyncClient(transport=transport, base_url="http://test") as client:
response = await client.get(
"/api/v1/vessels/snapshot",
params={"bbox": "0,50,20,70", "zoom": 12, "type": "cargo", "limit": 1000},
)
assert response.status_code == 200
data = response.json()
assert data["count"] == 1
assert data["features"][0]["properties"]["name"] == "Cargo Ship"
assert data["stats"]["by_type"]["Cargo"] == 1
finally:
app.dependency_overrides.clear()
@pytest.mark.asyncio
async def test_legacy_vessels_geojson_route_is_not_registered():
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as client:
response = await client.get("/api/v1/visualization/geo/vessels")
assert response.status_code == 404
@pytest.mark.asyncio
async def test_vessel_snapshot_requires_bbox():
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as client:
response = await client.get("/api/v1/vessels/snapshot", params={"zoom": 12})
assert response.status_code == 400
assert response.json()["detail"] == "bbox is required"
@pytest.mark.asyncio
async def test_vessel_snapshot_filters_bbox_and_caps_limit(monkeypatch):
now = datetime(2026, 4, 28, 1, 0, tzinfo=timezone.utc)
captured = {}
async def fake_get_aggregated_vessels_snapshot(db, *, bbox, limit, observed_since):
captured["bbox"] = bbox
captured["limit"] = limit
captured["observed_since"] = observed_since
return [
{
"mmsi": 1,
"lat": 59.9,
"lon": 10.7,
"received_at": now,
"name": "Cargo Ship",
"vessel_type": 70,
"vessel_type_name": "Cargo",
},
{
"mmsi": 2,
"lat": 60.3,
"lon": 5.3,
"received_at": now,
"name": "Passenger Ship",
"vessel_type": 60,
"vessel_type_name": "Passenger",
},
]
monkeypatch.setattr(
visualization,
"get_aggregated_vessels_snapshot",
fake_get_aggregated_vessels_snapshot,
)
class _Result:
def all(self):
return rows
return []
class _FakeSession:
async def execute(self, _query):
@@ -552,75 +644,73 @@ async def test_vessels_geojson_endpoint_filters_type_and_bbox():
try:
async with AsyncClient(transport=transport, base_url="http://test") as client:
response = await client.get(
"/api/v1/visualization/geo/vessels",
params={"bbox": "0,50,20,70", "type": "cargo", "limit": 0},
"/api/v1/vessels/snapshot",
params={
"bbox": "10,59,11,60",
"zoom": 12,
"type": "cargo",
"limit": 5000,
"since_minutes": 30,
},
)
assert response.status_code == 200
data = response.json()
assert data["count"] == 1
assert data["features"][0]["properties"]["name"] == "Cargo Ship"
assert data["stats"]["by_type"]["Cargo"] == 1
assert captured["bbox"] == (10.0, 59.0, 11.0, 60.0)
assert captured["limit"] == 5000
assert data["diagnostics"]["bbox_applied"] is True
assert data["diagnostics"]["legacy_feature_count"] == 0
assert data["diagnostics"]["legacy_backfilled_mmsi"] == 0
finally:
app.dependency_overrides.clear()
@pytest.mark.asyncio
async def test_vessels_geojson_merges_raw_and_legacy_sources(monkeypatch):
async def test_vessel_snapshot_uses_legacy_fallback_when_raw_window_is_empty(monkeypatch):
now = datetime(2026, 4, 28, 1, 0, tzinfo=timezone.utc)
monkeypatch.setattr(
visualization,
"get_aggregated_vessels",
"get_aggregated_vessels_snapshot",
AsyncMock(return_value=[]),
)
monkeypatch.setattr(
visualization,
"_load_legacy_vessel_snapshot_features",
AsyncMock(
return_value=[
{
"mmsi": 1,
"lat": 59.9,
"lon": 10.7,
"received_at": now,
"name": "AISSTREAM SHIP",
"vessel_type_name": "Cargo",
"source_summary": {"aisstream_vessels": {"message_types": ["PositionReport"]}},
"type": "Feature",
"id": 257123000,
"geometry": {"type": "Point", "coordinates": [10.73, 59.91]},
"properties": {
"mmsi": 257123000,
"name": "OSLO TRADER",
"vessel_type": 70,
"vessel_type_name": "Cargo",
"received_at": now.isoformat(),
},
}
]
),
)
rows = [
(
VesselPosition(mmsi=1, lat=60.0, lon=10.8, received_at=now),
VesselStatic(mmsi=1, name="LEGACY DUP", vessel_type_name="Cargo"),
),
(
VesselPosition(mmsi=2, lat=60.3, lon=5.3, received_at=now),
VesselStatic(mmsi=2, name="BARENTSWATCH ONLY", vessel_type_name="Passenger"),
),
]
class _Result:
def all(self):
return rows
result = await visualization.build_vessel_snapshot_response(
object(),
bbox=(10.0, 59.0, 11.0, 60.0),
zoom=12,
type_filter=None,
limit=1000,
since_minutes=60,
)
class _FakeSession:
async def execute(self, _query):
return _Result()
async def override_get_db():
yield _FakeSession()
app.dependency_overrides[get_db] = override_get_db
transport = ASGITransport(app=app)
try:
async with AsyncClient(transport=transport, base_url="http://test") as client:
response = await client.get("/api/v1/visualization/geo/vessels")
assert response.status_code == 200
data = response.json()
names = {feature["properties"]["mmsi"]: feature["properties"]["name"] for feature in data["features"]}
assert data["count"] == 2
assert names == {1: "AISSTREAM SHIP", 2: "BARENTSWATCH ONLY"}
assert data["diagnostics"]["legacy_backfilled_mmsi"] == 1
finally:
app.dependency_overrides.clear()
assert result["count"] == 1
assert result["features"][0]["properties"]["name"] == "OSLO TRADER"
assert result["diagnostics"]["raw_feature_count"] == 0
assert result["diagnostics"]["legacy_feature_count"] == 1
assert result["diagnostics"]["legacy_backfilled_mmsi"] == 1
assert result["diagnostics"]["legacy_fallback_used"] is True
@pytest.mark.asyncio
+92
View File
@@ -1,6 +1,8 @@
import pytest
import importlib
from app.core.websocket.manager import ConnectionManager
from app.core.websocket.broadcaster import DataBroadcaster
class FakeWebSocket:
@@ -44,3 +46,93 @@ async def test_disconnect_removes_channel_subscriptions():
assert socket.sent == []
assert "dashboard" not in manager.channel_subscriptions
@pytest.mark.asyncio
async def test_vessel_subscribers_receive_only_matching_bbox_updates():
manager = ConnectionManager()
oslo_socket = FakeWebSocket()
bergen_socket = FakeWebSocket()
await manager.connect(oslo_socket, "user-1")
await manager.connect(bergen_socket, "user-2")
manager.subscribe_vessels(
oslo_socket,
{"bbox": [10, 59, 11, 60], "zoom": 12, "limit": 1000},
)
manager.subscribe_vessels(
bergen_socket,
{"bbox": [5, 60, 6, 61], "zoom": 12, "limit": 1000},
)
await manager.broadcast_vessels(
{
"action": "upsert",
"vessels": [
{"mmsi": 1, "lat": 59.9, "lon": 10.7},
{"mmsi": 2, "lat": 60.3, "lon": 5.3},
],
}
)
assert oslo_socket.sent[0]["payload"]["vessels"] == [{"mmsi": 1, "lat": 59.9, "lon": 10.7}]
assert bergen_socket.sent[0]["payload"]["vessels"] == [{"mmsi": 2, "lat": 60.3, "lon": 5.3}]
@pytest.mark.asyncio
async def test_vessel_broadcast_removes_slow_connections():
manager = ConnectionManager()
class BrokenWebSocket(FakeWebSocket):
async def send_json(self, message):
raise RuntimeError("client is gone")
socket = BrokenWebSocket()
await manager.connect(socket, "user-1")
manager.subscribe_vessels(socket, {"bbox": [10, 59, 11, 60], "zoom": 12})
await manager.broadcast_vessels({"vessels": [{"mmsi": 1, "lat": 59.9, "lon": 10.7}]})
assert socket not in manager.vessel_subscriptions
def test_vessel_subscription_rejects_large_bbox():
manager = ConnectionManager()
with pytest.raises(ValueError, match="bbox is too large"):
manager.subscribe_vessels(FakeWebSocket(), {"bbox": [-180, -90, 180, 90], "zoom": 1})
@pytest.mark.asyncio
async def test_vessel_broadcaster_keeps_latest_update_per_mmsi(monkeypatch):
sent = []
async def fake_broadcast_vessels(payload):
sent.append(payload)
broadcaster_module = importlib.import_module("app.core.websocket.broadcaster")
monkeypatch.setattr(broadcaster_module.manager, "broadcast_vessels", fake_broadcast_vessels)
broadcaster = DataBroadcaster()
broadcaster.enqueue_vessel_update(
{
"source": "aisstream_vessels",
"vessels": [
{"mmsi": 1, "lat": 59.0, "lon": 10.0},
{"mmsi": 1, "lat": 59.1, "lon": 10.1},
],
}
)
await broadcaster.flush_vessel_updates()
assert len(sent) == 1
assert sent[0]["vessels"] == [
{
"mmsi": 1,
"lat": 59.1,
"lon": 10.1,
"source": "aisstream_vessels",
"action": "upsert",
"created": None,
}
]
+6
View File
@@ -0,0 +1,6 @@
apiVersion: v2
name: planet
description: Planet situational awareness platform
type: application
version: 0.1.0
appVersion: "0.52.0"
+33
View File
@@ -0,0 +1,33 @@
{{- define "planet.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
{{- end -}}
{{- define "planet.fullname" -}}
{{- if .Values.fullnameOverride -}}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
{{- else -}}
{{- $name := include "planet.name" . -}}
{{- if contains $name .Release.Name -}}
{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
{{- else -}}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
{{- end -}}
{{- end -}}
{{- end -}}
{{- define "planet.labels" -}}
app.kubernetes.io/name: {{ include "planet.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}
{{- end -}}
{{- define "planet.selectorLabels" -}}
app.kubernetes.io/name: {{ include "planet.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end -}}
{{- define "planet.image" -}}
{{- printf "%s/%s/%s:%s" .root.Values.global.imageRegistry .root.Values.global.imageNamespace .repository .root.Values.image.tag -}}
{{- end -}}
@@ -0,0 +1,66 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "planet.fullname" . }}-aiprovider
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: aiprovider
spec:
replicas: {{ .Values.aiprovider.replicaCount }}
selector:
matchLabels:
{{- include "planet.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: aiprovider
template:
metadata:
labels:
{{- include "planet.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: aiprovider
spec:
{{- with .Values.global.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: aiprovider
image: {{ include "planet.image" (dict "root" . "repository" .Values.aiprovider.image.repository) | quote }}
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: http
containerPort: 8010
envFrom:
- configMapRef:
name: {{ include "planet.fullname" . }}-config
- secretRef:
name: {{ include "planet.fullname" . }}-secrets
readinessProbe:
httpGet:
path: /health
port: http
initialDelaySeconds: 10
periodSeconds: 10
livenessProbe:
httpGet:
path: /health
port: http
initialDelaySeconds: 30
periodSeconds: 20
resources:
{{- toYaml .Values.aiprovider.resources | nindent 12 }}
---
apiVersion: v1
kind: Service
metadata:
name: {{ include "planet.fullname" . }}-aiprovider
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: aiprovider
spec:
type: ClusterIP
ports:
- name: http
port: {{ .Values.aiprovider.service.port }}
targetPort: http
selector:
{{- include "planet.selectorLabels" . | nindent 4 }}
app.kubernetes.io/component: aiprovider
+66
View File
@@ -0,0 +1,66 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "planet.fullname" . }}-backend
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: backend
spec:
replicas: {{ .Values.backend.replicaCount }}
selector:
matchLabels:
{{- include "planet.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: backend
template:
metadata:
labels:
{{- include "planet.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: backend
spec:
{{- with .Values.global.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: backend
image: {{ include "planet.image" (dict "root" . "repository" .Values.backend.image.repository) | quote }}
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: http
containerPort: 8000
envFrom:
- configMapRef:
name: {{ include "planet.fullname" . }}-config
- secretRef:
name: {{ include "planet.fullname" . }}-secrets
readinessProbe:
httpGet:
path: /health
port: http
initialDelaySeconds: 10
periodSeconds: 10
livenessProbe:
httpGet:
path: /health
port: http
initialDelaySeconds: 30
periodSeconds: 20
resources:
{{- toYaml .Values.backend.resources | nindent 12 }}
---
apiVersion: v1
kind: Service
metadata:
name: {{ include "planet.fullname" . }}-backend
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: backend
spec:
type: ClusterIP
ports:
- name: http
port: {{ .Values.backend.service.port }}
targetPort: http
selector:
{{- include "planet.selectorLabels" . | nindent 4 }}
app.kubernetes.io/component: backend
@@ -0,0 +1,27 @@
{{- $postgresHost := .Values.postgresql.external.host -}}
{{- if .Values.postgresql.internal.enabled -}}
{{- $postgresHost = printf "%s-postgresql" (include "planet.fullname" .) -}}
{{- end -}}
{{- $redisHost := .Values.redis.external.host -}}
{{- if .Values.redis.internal.enabled -}}
{{- $redisHost = printf "%s-redis" (include "planet.fullname" .) -}}
{{- end -}}
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ include "planet.fullname" . }}-config
labels:
{{- include "planet.labels" . | nindent 4 }}
data:
DATABASE_URL: "postgresql+asyncpg://{{ .Values.postgresql.external.username }}:{{ .Values.postgresql.external.password }}@{{ $postgresHost }}:{{ .Values.postgresql.external.port }}/{{ .Values.postgresql.external.database }}"
REDIS_SERVER: {{ $redisHost | quote }}
REDIS_PORT: {{ .Values.redis.external.port | quote }}
REDIS_DB: {{ .Values.redis.external.db | quote }}
AI_BASE_URL: "http://{{ include "planet.fullname" . }}-aiprovider:{{ .Values.aiprovider.service.port }}"
AI_PROVIDER_API: "http://{{ include "planet.fullname" . }}-aiprovider:{{ .Values.aiprovider.service.port }}"
{{- range $key, $value := .Values.backend.env }}
{{ $key }}: {{ $value | quote }}
{{- end }}
{{- range $key, $value := .Values.aiprovider.env }}
{{ $key }}: {{ $value | quote }}
{{- end }}
@@ -0,0 +1,61 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "planet.fullname" . }}-frontend
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: frontend
spec:
replicas: {{ .Values.frontend.replicaCount }}
selector:
matchLabels:
{{- include "planet.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: frontend
template:
metadata:
labels:
{{- include "planet.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: frontend
spec:
{{- with .Values.global.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: frontend
image: {{ include "planet.image" (dict "root" . "repository" .Values.frontend.image.repository) | quote }}
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: http
containerPort: 3000
readinessProbe:
httpGet:
path: /health
port: http
initialDelaySeconds: 5
periodSeconds: 10
livenessProbe:
httpGet:
path: /health
port: http
initialDelaySeconds: 20
periodSeconds: 20
resources:
{{- toYaml .Values.frontend.resources | nindent 12 }}
---
apiVersion: v1
kind: Service
metadata:
name: {{ include "planet.fullname" . }}-frontend
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: frontend
spec:
type: ClusterIP
ports:
- name: http
port: {{ .Values.frontend.service.port }}
targetPort: http
selector:
{{- include "planet.selectorLabels" . | nindent 4 }}
app.kubernetes.io/component: frontend
+29
View File
@@ -0,0 +1,29 @@
{{- if .Values.frontend.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: {{ include "planet.fullname" . }}
labels:
{{- include "planet.labels" . | nindent 4 }}
{{- with .Values.frontend.ingress.annotations }}
annotations:
{{- toYaml . | nindent 4 }}
{{- end }}
spec:
ingressClassName: {{ .Values.frontend.ingress.className | quote }}
{{- with .Values.frontend.ingress.tls }}
tls:
{{- toYaml . | nindent 4 }}
{{- end }}
rules:
- host: {{ .Values.frontend.ingress.host | quote }}
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: {{ include "planet.fullname" . }}-frontend
port:
name: http
{{- end }}
+14
View File
@@ -0,0 +1,14 @@
apiVersion: v1
kind: Secret
metadata:
name: {{ include "planet.fullname" . }}-secrets
labels:
{{- include "planet.labels" . | nindent 4 }}
type: Opaque
stringData:
{{- range $key, $value := .Values.backend.secretEnv }}
{{ $key }}: {{ $value | quote }}
{{- end }}
{{- range $key, $value := .Values.aiprovider.secretEnv }}
{{ $key }}: {{ $value | quote }}
{{- end }}
@@ -0,0 +1,116 @@
{{- if .Values.postgresql.internal.enabled }}
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: {{ include "planet.fullname" . }}-postgresql
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: postgresql
spec:
serviceName: {{ include "planet.fullname" . }}-postgresql
replicas: 1
selector:
matchLabels:
{{- include "planet.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: postgresql
template:
metadata:
labels:
{{- include "planet.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: postgresql
spec:
containers:
- name: postgresql
image: postgres:15
ports:
- name: postgres
containerPort: 5432
env:
- name: POSTGRES_USER
value: {{ .Values.postgresql.external.username | quote }}
- name: POSTGRES_PASSWORD
value: {{ .Values.postgresql.external.password | quote }}
- name: POSTGRES_DB
value: {{ .Values.postgresql.external.database | quote }}
readinessProbe:
exec:
command: ["pg_isready", "-U", {{ .Values.postgresql.external.username | quote }}]
initialDelaySeconds: 5
periodSeconds: 10
volumeMounts:
- name: data
mountPath: /var/lib/postgresql/data
volumeClaimTemplates:
- metadata:
name: data
spec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 8Gi
---
apiVersion: v1
kind: Service
metadata:
name: {{ include "planet.fullname" . }}-postgresql
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: postgresql
spec:
ports:
- name: postgres
port: 5432
targetPort: postgres
selector:
{{- include "planet.selectorLabels" . | nindent 4 }}
app.kubernetes.io/component: postgresql
{{- end }}
{{- if .Values.redis.internal.enabled }}
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "planet.fullname" . }}-redis
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: redis
spec:
replicas: 1
selector:
matchLabels:
{{- include "planet.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: redis
template:
metadata:
labels:
{{- include "planet.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: redis
spec:
containers:
- name: redis
image: redis:7-alpine
ports:
- name: redis
containerPort: 6379
readinessProbe:
exec:
command: ["redis-cli", "ping"]
initialDelaySeconds: 5
periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
name: {{ include "planet.fullname" . }}-redis
labels:
{{- include "planet.labels" . | nindent 4 }}
app.kubernetes.io/component: redis
spec:
ports:
- name: redis
port: 6379
targetPort: redis
selector:
{{- include "planet.selectorLabels" . | nindent 4 }}
app.kubernetes.io/component: redis
{{- end }}
@@ -0,0 +1,29 @@
global:
imageRegistry: gitea.rclaw.top
imageNamespace: linkong/planet
image:
tag: latest
frontend:
ingress:
enabled: true
host: planet.local
postgresql:
internal:
enabled: true
external:
host: planet-postgresql
port: 5432
database: planet_db
username: postgres
password: postgres
redis:
internal:
enabled: true
external:
host: planet-redis
port: 6379
db: 0
+73
View File
@@ -0,0 +1,73 @@
global:
imageRegistry: gitea.rclaw.top
imageNamespace: linkong/planet
imagePullSecrets: []
fullnameOverride: planet
image:
tag: latest
pullPolicy: IfNotPresent
frontend:
replicaCount: 1
image:
repository: frontend
service:
port: 3000
ingress:
enabled: true
className: nginx
host: planet.example.com
annotations: {}
tls: []
resources: {}
backend:
replicaCount: 1
image:
repository: backend
service:
port: 8000
env:
PROJECT_NAME: Planet
CORS_ORIGINS: '["*"]'
secretEnv:
SECRET_KEY: change-me
resources: {}
aiprovider:
replicaCount: 1
image:
repository: aiprovider
service:
port: 8010
env:
AI_PROVIDER: openai
AI_MODEL: gpt-4o-mini
secretEnv:
AI_API_KEY: ""
resources: {}
postgresql:
internal:
enabled: false
external:
host: postgres.example.com
port: 5432
database: planet_db
username: postgres
password: postgres
redis:
internal:
enabled: false
external:
host: redis.example.com
port: 6379
db: 0
smoke:
frontendPath: /
backendHealthPath: /health
aiProviderHealthPath: /health
+97
View File
@@ -8,6 +8,103 @@ This project follows the repository versioning rule:
- `improvement` -> `+0.0.1`(bugfix + 小功能混合)
- `bugfix` -> `+0.0.1`
## [0.57.0] — 2026-05-14
Released: 2026-05-14
### Highlights
- 新增 WSL `--allow-lan` 临时 Windows relay,保持本机 `localhost:3000` / `localhost:8000` 不变,同时用 Windows 局域网 IP 暴露相同端口。
- 启动脚本会检测旧 `netsh interface portproxy` 冲突并请求管理员 PowerShell 清理,避免 `svchost.exe / iphlpsvc` 持久占用 3000/8000。
- 修复 Vite CJS Node API deprecated warning,将前端配置迁移到 ESM,并让脚本按实际后端端口注入代理目标。
### Added / Fixed / Improved
- 新增 [scripts/windows-lan-relay.ps1](/home/ray/dev/linkong/planet/scripts/windows-lan-relay.ps1),在 Windows 侧启动随 WSL 服务健康状态自动退出的 TCP relay。
- `planet.sh --allow-lan` 仅在 WSL + PowerShell 可用时启用 Windows relay,并自动检查 Windows 防火墙规则;非 WSL 环境保持原有路径。
- 更新中英文 README、FAQ 和运维文档,说明旧 portproxy 清理、UAC 防火墙授权、同端口 localhost/LAN 访问和故障恢复方式。
---
## [0.56.0] — 2026-05-13
Released: 2026-05-13
### Highlights
- 修复 Earth 卫星 SGP4 坐标口径,当前点/短尾迹使用地固坐标,锁定预测轨道使用固定地球姿态下的闭合惯性轨道。
- 优化真实高度压缩显示上限,将高轨显示控制在地球半径外约四分之一,保持 GEO/MEO/LEO 分层同时避免轨迹过远。
- 统一 BGP 光晕与图标色调,并更新超算中心建筑图标和 Earth 新闻/HUD 面板体验。
### Added / Fixed / Improved
- 修正卫星详情卡近地点/远地点高度计算,避免把轨道半径误显示为离地高度。
- 调整 BGP event / collector halo 的浅色派生规则,使红色事件、橙色活跃观测站和蓝色 idle 观测站保持各自色相。
- 补充中英文用户手册、FAQ、Earth frontend context、render order、layer style reference 和相关计划文档。
---
## [0.55.0] — 2026-05-13
Released: 2026-05-13
### Highlights
- 新增 Earth 卫星真实高度显示开关,默认按 TLE/SGP4 真实轨道高度压缩分层,关闭后恢复旧版同层球面。
- 将卫星轨迹显示保留在设置面板,并让轨迹、预测轨道和锁定视觉跟随真实高度开关即时刷新。
- 修复 Earth 设置面板 switch 圆点垂直居中问题,并同步更新用户手册、FAQ 和 Earth 开发者文档。
### Added / Fixed / Improved
- 新增 `satelliteRealAltitudeEnabled` 本地偏好和真实高度压缩参数,保留 TLE 缺失/传播失败时的 fallback 固定高度。
- 更新卫星渲染高度、轨迹、预测轨道和设置持久化链路,避免同一轨迹混入两套高度模型。
- 补充中英文 manual、quickstart、FAQ、Earth frontend context、render order 和 layer style reference。
---
## [0.54.0] — 2026-05-13
Released: 2026-05-13
### Highlights
- 新增 Earth 轨迹显示设置,将卫星轨迹从图层列表迁移到桌面与移动设置面板,便于独立控制轨迹线显示。
- 优化卫星静止呼吸与低缩放圆点闪烁参数,让卫星态势视觉节奏更柔和、层次更清晰。
- 更新算力中心图标资产,统一 Earth 交互图标在高分辨率显示下的视觉规格。
### Added / Fixed / Improved
- 新增轨迹显示偏好持久化,并在卫星图层不可用时同步禁用轨迹设置入口。
- 调整卫星呼吸、透明度和 twinkle 参数,降低闪烁频率并增强可读性。
- 将轨迹控制状态同步到桌面设置、移动设置和图层卡片刷新流程。
---
## [0.53.0] — 2026-05-13
Released: 2026-05-13
### Highlights
- 新增正式交付基线:Gitea Actions CI、镜像发布、staging 自动部署,以及 Kubernetes Helm chart。
- 前端生产镜像改为 `vite build` 静态产物 + nginx 托管,后端与 AI Provider 镜像移除开发 reload 并加入容器健康检查。
- 明确 `planet.sh` 只作为开发启动入口,生产环境交给 Kubernetes Service、Ingress、readiness/liveness probe 和 rollout 管理。
### Added / Fixed / Improved
- 新增 frontend/backend/aiprovider 镜像 build smoke、Helm lint/template、staging rollout 与 HTTP smoke test 流水线。
- 新增 Helm values、single-node 演示依赖、ConfigMap/Secret 引用、ClusterIP 服务和 frontend Ingress。
- 更新运维文档与交付计划,保留 Vite 生产构建路线,不新增 Webpack 双构建链,Electron 暂不进入主线。
- 继续收口启动脚本风险:状态目录、健康检查端口默认值、PID 校验、端口诊断和开发环境跨平台边界说明。
---
## [0.52.0] — 2026-05-12
Released: 2026-05-12
### Highlights
- 新增邮箱验证码注册/找回密码链路、SMTP 设置面板和连接测试组件,补齐公开账号自助入口。
- 重构 AIS 船只实时链路:新增受控船只 snapshot、WebSocket vessels 订阅、AISStream 长连接状态与节流广播。
- 新增数据产品统计接口、受控 `/layers/*` 图层接口骨架,以及数据源产品域筛选和批量采集。
### Added / Fixed / Improved
- 新增 `/api/v1/data-products`、`/api/v1/layers/*` 和 `/api/v1/datasources/trigger-batch`,拆分全量统计与地图渲染数据。
- 将 Earth 船只层迁移到 `/api/v1/vessels/snapshot`,并修正 vessels WebSocket 订阅 payload。
- 更新中英文手册、采集器文档、运维手册和计划状态,覆盖注册、SMTP、AISStream、数据产品和图层保护流程。
---
## [0.51.1] — 2026-05-11
Released: 2026-05-11
+10
View File
@@ -2,6 +2,16 @@
This file contains Planet-specific documentation coverage rules. Documentation skills and agents should read this file before deciding which docs to update. Keep tool-specific workflow in skills; keep product and repository rules here.
## Audience Routing (mandatory)
Before deciding scope, classify the change by who performs the action:
- **Browser/UI end user** (login, account settings, configuring collectors or AI via UI, using Earth/Console pages): update `docs/technical/{zh,en}/manual.md` and `quickstart.md` only. Never put shell commands, log file paths, `planet.sh`, Docker operations, or `netsh portproxy` rules into these files.
- **Operations / deployment / on-call** (`planet.sh`, log paths, SMTP fallbacks like `createuser`, LAN/portproxy, env-var tuning, troubleshooting order, Bun build conventions): update `docs/technical/{zh,en}/ops-runbook.md` (or an existing `ops-*.md`). Never put UI button labels or screenshots into these files.
- **Second-party developers** (component context, render order, internal pipelines): update the existing `*-context.md` / `backend-*.md` / `earth-*.md` files.
If the same action has both a UI and a CLI path (e.g. user creation), describe the UI path in `manual.md` and the CLI path in `ops-runbook.md`, and cross-link them with a single sentence each.
## Scope Rules
- User-visible workflow changes must update `docs/technical/zh/manual.md` and usually `docs/technical/zh/quickstart.md`.
+1 -1
View File
@@ -19,7 +19,7 @@
- [earth-mobile-drawer-ui-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-mobile-drawer-ui-plan.md)
- [earth-compute-center-bgp-style-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-compute-center-bgp-style-plan.md)
- [earth-renderer-architecture-separation-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-renderer-architecture-separation-plan.md)
- [earth-country-boundary-overlay-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-country-boundary-overlay-plan.md)
- [Earth 高精度国界静态瓦片计划](/home/ray/dev/linkong/planet/docs/plans/earth-high-precision-boundary-tiles-plan.md)
- [earth-predicted-orbit-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-predicted-orbit-plan.md)
- [earth-webgl-instancing-satellites-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-webgl-instancing-satellites-plan.md)
- [earth-real-terrain-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-real-terrain-plan.md)
@@ -0,0 +1,146 @@
# 数据产品流水线、数据源批量运维与抗击穿图层接口计划
## Summary
前端展示分两类数据:
- **图层数据**:按 viewport、bbox、zoom、limit 返回,可降级、截断、缓存,用来保护服务器。
- **聚合面板统计**:必须是全量统计,不受当前 viewport 限制,但不能实时扫全表;通过产品状态表或预计算统计提供。
也就是说:地图上低 zoom 可以只画摘要或局部数据,但面板里的“总船只数、总海缆数、BGP 活跃事件数、卫星数”等应该代表全局数据产品状态。
## Implementation Status
- 已新增 `POST /api/v1/datasources/trigger-batch`,支持按选中 `source_ids` 或筛选条件批量触发,并返回 `triggered/skipped/failed`。
- 已改造 `/datasources` 页面,支持产品域、层级、启用状态、最近执行状态、是否已有数据和关键词筛选,并支持复选框批量采集。
- 已新增 `/api/v1/data-products` 和 `/api/v1/data-products/{product_id}/status`,聚合面板可以读取全量/全局统计口径。
- 已新增 `/api/v1/layers/*` 受控图层接口骨架,要求 `bbox/zoom/limit`,响应包含 `visible_count/returned_count/diagnostics`。
- 非船只图层当前先复用已有 GeoJSON 转换再做保护层;下一步应把 cables/BGP/satellites 的 bbox 过滤继续下推到各自产品查询,避免转换前仍加载过多候选。
## Key Changes
- 新增数据产品状态/统计层:
- 每个产品维护全量统计:总实体数、活跃数、最近更新时间、使用源、缺失源、冲突数、构建状态。
- 统计在采集成功或产品投影完成后更新,不在用户打开页面时临时全表聚合。
- 前端聚合面板统一读取产品统计接口,而不是从图层返回量推断总数。
- 新增接口:
- `GET /api/v1/data-products`
- `GET /api/v1/data-products/{product_id}/status`
- `GET /api/v1/layers/{product}/...`
- `POST /api/v1/datasources/trigger-batch`
- `/layers/*` 只负责可视化数据:
- 支持 bbox、zoom、limit、since。
- 可以返回 `degraded`、`truncated`、`cache_hit`。
- 返回 `visible_count` 和 `returned_count`,但不作为全量统计来源。
- `/data-products/*/status` 负责全量统计:
- 返回 `total_count`、`active_count`、`source_counts`、`last_built_at`、`health`。
- 数据来自预计算状态或轻量索引统计。
- 即使图层降级,统计也保持全量口径。
## Product Processing
- 船只:
- 图层:bbox snapshot + WS 聚合流,受限返回。
- 统计:全量唯一 MMSI、最近窗口活跃 MMSI、AISStream/BarentsWatch/source counts。
- 海缆:
- 图层:viewport 内 cable segments/landing points,低 zoom 可简化路线。
- 统计:全量 cable count、landing point count、relation count、graph 构建状态。
- 处理:专用 cable graph assembler,区分路线源、登陆点源、关系源、补充源,不使用统一字段融合函数。
- BGP:
- 图层:active incidents/anomalies/collectors,按窗口和 limit 返回。
- 统计:全量活跃事件、最近 24h/7d 事件数、collector 数、incident/anomaly 分布。
- 处理:专用事件流水线,区分 observation、anomaly、incident、geo hint、infrastructure inference。
- 卫星:
- 图层:可见卫星或受控 limit。
- 统计:全量卫星数、最新 TLE epoch、源覆盖情况。
- 处理:按 NORAD id 生成轨道快照,TLE epoch 最新优先。
## Data Source Page
- 增加筛选:
- 产品类型、启用/禁用、最近成功/失败/运行中/未执行、已采集/未采集、凭证状态、文本搜索。
- 增加复选框批量操作:
- 批量启用、禁用、采集、强制采集。
- 一键采集改为:采集全部启用源、采集筛选结果、采集选中源。
- 后端 batch 逻辑:
- 禁用源 skipped。
- 运行中源按 force 处理。
- 单个失败不影响其他源。
- 返回 `triggered`、`skipped`、`failed`,并包含每个 source 的原因和 task_id。
## Protection Rules
- 所有 `/layers/*` 接口必须有保护层:
- limit clamp。
- bbox/zoom 校验。
- 低 zoom 降级。
- 短 TTL 缓存。
- 慢查询超时。
- diagnostics 返回降级原因。
- 全量统计不走图层查询:
- 不允许为了面板统计在请求时 `.all()` 全量加载。
- 统计由采集/投影任务异步更新。
- 统计缺失时返回 `unknown` 或 `stale`,不触发重型实时计算。
- 缓存失效规则:
- 采集成功后失效对应产品缓存。
- 海缆 graph cache 在路线、登陆点或关系源成功采集后失效。
- BGP incident/anomaly 生成后失效 BGP layer cache。
- 船只实时流使用短 TTL 或 viewport 级缓存,不清全局缓存。
- 接口观测:
- 记录每个 layer endpoint 的耗时、返回数量、是否降级、是否缓存命中、limit 是否被 clamp。
- 对高频 viewport 请求增加简单 per-IP 或 per-user rate limit。
## Frontend UX
- 数据源页:
- 顶部统计可作为快捷筛选入口:全部、启用、禁用、运行中、失败、未采集。
- 表格左侧增加复选框。
- 工具栏显示“已选择 N 个”,并提供批量按钮。
- 筛选结果和选中结果分清楚,避免误触发全部源。
- 批量采集完成后弹出摘要:触发、跳过、失败数量,可展开查看原因。
- 设置/配置页:
- “采集器设置”改为“数据产品配置”。
- 产品内按源角色分组展示,而不是简单列出 collector。
- 海缆显示路线源、登陆点源、关系源、补充源。
- BGP 显示实时观测源、历史回填源、地理 hint 源、检测输出。
- 船只显示实时 AIS、轮询 AIS、自定义补充源。
- Earth 图层交互:
- 聚合面板统计读取 `/data-products/*/status`,保持全量口径。
- 图层面板展示当前图层是否降级、截断、缓存命中。
- 对象详情展示来源证据:
- 船只:字段来源、冲突。
- 海缆:路线源、登陆点源、关系源。
- BGP:事件证据、分组依据、地理推断依据。
- 产品 degraded 时仍显示可用部分,并提示缺失源角色。
## Test Plan
- 图层接口:
- 大 limit 被 clamp。
- 低 zoom 降级。
- 大数据集不全量内存过滤。
- diagnostics 正确说明截断、缓存、降级。
- 全量统计:
- 面板统计不受 bbox 影响。
- 图层返回 1000 条时,产品统计仍显示全量总数。
- 统计陈旧时返回 `stale=true` 和 `last_built_at`。
- 采集成功后对应产品统计刷新。
- 数据源批量:
- 筛选、选中、批量采集行为正确。
- skipped/failed/triggered 分组正确。
- 禁用源在 batch 中被 skipped。
- 运行中源按 force 参数处理。
- batch 单源失败不阻断整体。
- 产品处理:
- 海缆缺 relation 时产品状态 degraded,但 cable layer 可用。
- BGP observation 不直接变成前端 marker,必须经过 anomaly/incident 投影。
- 船只 bbox snapshot 和 WS 节流继续有效。
- 卫星列表不返回无限轨道点。
## Assumptions
- 前端聚合面板以后只读 `/data-products/*/status`。
- 地图图层只读 `/layers/*`。
- 统计可以短暂 stale,但不能因实时全量统计击穿服务器。
- 保留现有 collector,不为了重构而删除 BarentsWatch 或其他源。
- 当前开发阶段允许前端从旧 `/visualization/geo/*` 迁移到 `/layers/*`。
@@ -13,7 +13,7 @@
| 采集时是否调用 LLM | 不调用;采集链路必须确定性、可审计、可复现 |
| 自定义数据如何进入 Earth | 必须映射到已支持的目标 schema,或先进入通用数据沉淀 |
| 外部凭证放置位置 | Settings / 外部集成统一管理 provider token;DataSources 引用 provider profile |
| TimescaleDB | 放入 TODO;高频时序数据稳定后再评估迁移 |
| TimescaleDB | 高频时序数据稳定后再评估迁移 |
---
@@ -57,7 +57,7 @@ flowchart LR
| schema | 用途 | Earth 可视化 |
|-------|------|-------------|
| `vessel_ais` | 船只 AIS 位置、航速、航向、MMSI 等 | 进入船舶图层 |
| `geo_points` | 通用点位数据,包含经纬度、名称、类型、时间 | 进入通用 geo layer(TODO) |
| `geo_points` | 通用点位数据,包含经纬度、名称、类型、时间 | 未来进入通用 geo layer |
| `news_events` | 新闻/事件类数据,带时间、地点、摘要、来源 | 复用新闻/事件链路 |
| `compute_centers` | 算力中心、机房、数据中心数据 | 复用算力中心图层 |
| `generic_records` | 未知结构化数据沉淀 | 不直接展示 |
@@ -294,7 +294,7 @@ PostgreSQL 可以承载当前规模的采集、关系查询、JSONB 沉淀和基
- 查询模式还没稳定。
- 需要快速迭代 schema 与 mapping。
### TODO:TimescaleDB
### TimescaleDB 后续评估
以下条件满足后,再评估 TimescaleDB:
@@ -324,7 +324,7 @@ PostgreSQL 可以承载当前规模的采集、关系查询、JSONB 沉淀和基
- Settings 中保存 provider credentials。
- API 返回配置时必须 mask secret。
- LLM prompt 只能包含脱敏 sample 和 schema 说明。
- 后续 TODO:引入字段级加密或 KMS。
- 后续可引入字段级加密或 KMS。
### Mapping 治理
+116
View File
@@ -0,0 +1,116 @@
# 文档受众分层重构计划
**状态**:待实施
**创建日期**:2026-05-12
**核心目标**:把 `docs/technical/{zh,en}/manual.md` 拆成"纯客户视角"的使用手册,把 `planet.sh`、日志、LAN、故障排查这类运维内容迁到独立 `ops-runbook.md`,并把分层规则写进 `documentation-coverage-rules.md` 和 `.claude/commands/docs.md`,让以后写文档时自动按受众归档。
## 背景
当前 `manual.md` 把客户实际使用和开发/运维操作混在一份文档里:开头 200 多行讲的是 `planet.sh start/stop/restart/log/health/createuser/--allow-lan`、AI Provider 镜像构建、`netsh portproxy` 和故障排查顺序,后面才进入 Earth、控制台、AI、Docs 这些客户真正会用到的功能。
客户读到一半会被 shell 命令吓住,开发者想找运维细节又要在大段 UI 操作里翻。`documentation-coverage-rules.md` 现在也没有受众分层规则,未来文档继续混着写。
本计划假定客户已经能拿到账号登录使用 — 注册/验证流程本身见 [用户公开注册与邮箱验证计划](/home/ray/dev/linkong/planet/docs/plans/user-registration-email-verification-plan.md)。
## 新的文档地形
| 文档 | 受众 | Gatekeeper 组 | 范围 |
| --- | --- | --- | --- |
| `manual.md` (zh+en) | 纯客户/最终用户 | `public` | 注册、登录、账户、设置 UI、collector 配置、AI 配置、Console 页面、Earth、Docs 浏览 |
| `quickstart.md` (zh+en) | 纯客户 | `public` | "我刚拿到 Planet 怎么开始用" — 打开 URL → 注册 → 验证 → 登录 → 第一次配置 |
| `ops-runbook.md` (zh+en, **新增**) | 运维/部署人员 | `docs_admin` | `planet.sh` 完整命令、健康检查、日志位置、LAN/portproxy、故障排查顺序、createuser CLI、Bun 构建约定 |
| `ops-planet-sh-startup.md` (已存在) | 运维 | `docs_admin` | 启动性能、AI Provider 镜像、`PLANET_LOAD_ZSHRC_ENV` 深度调优 — 保持不动 |
| 现有 `*-context.md` / `backend-*.md` | 二次开发者 | `docs_developer` | 保持现状 |
`backend-system-service-control.md` 偏后端服务控制原理,**不**和 `ops-runbook.md` 重复 — runbook 讲"运维要敲什么命令",service-control 讲"后端怎么实现服务管控"。
## manual.md 重写后的章节顺序(客户旅程)
1. **欢迎与入口** — Planet 是什么、几个入口(Earth 公开 / Console 需登录 / Docs / API)
2. **注册账户** — 打开 `/login` → 点"注册" → 填用户名/邮箱/密码 → 收邮件 → 输入 6 位验证码 → 登录
3. **登录与找回密码** — 登录页、忘记密码流程
4. **账户设置** — 修改密码、修改邮箱(需重新验证)、查看权限组、登出
5. **Console 总览** — 左侧菜单结构、各路由用途
6. **配置数据采集器** — `/settings?tab=collector_credentials`:选择 collector、连接测试、保存凭证;BarentsWatch / AISStream 两个典型例子
7. **配置 AI 凭证** — `/ai?tab=providers`:默认 provider、模型、Base URL、API Key、本地代理;工具 tab(WebSearch、OCR)
8. **系统设置** — `/settings` 其他子 tab(系统设置、电视直播源、SMTP 邮件)
9. **用户管理(管理员)** — `/users`:创建、删除、改角色、Gatekeeper 权限组
10. **数据探索** — `/datasources`、`/data`、`/bgp`、`/alerts/*`
11. **AI 测试台** — `/ai?tab=playground`
12. **Earth 公开页面** — 现 manual.md 的 Earth 章节原样保留(图层、图例、搜索、位置候选、设置、视角、动捕、巡航、移动端)
13. **Docs 文档站** — 当前 Docs 章节保留(权限组说明)
不再出现:`planet.sh`、`./planet.sh log`、`netsh portproxy`、`source ~/.zshrc && bun run build`、"故障排查顺序"、"开发命令约定"。
## quickstart.md 重写
当前 quickstart 假设读者会自己 `git clone` 然后 `./planet.sh start`,这是给开发者看的。改为:
- 打开管理员给你的 URL
- 注册账号 + 邮箱验证
- 登录后第一次做什么(建议先到 `/settings?tab=collector_credentials` 配一个 collector,再到 `/ai` 配模型)
- 看 Earth
部署/开发的 quickstart 内容并入 `ops-runbook.md` 的"首次部署"小节,**不**再单独出 `ops-quickstart.md`,避免新增维护点。
## ops-runbook.md 内容大纲
抽自现 manual.md,重新组织:
1. 首次启动 — `./planet.sh start`、默认账号(`admin/admin123`、`linkong/12345678`,引用 `b15d097b` 引入的 `DEFAULT_LOGIN_USERS`)
2. 启停与按模块重启 — `start/stop/restart` 及 `-b -f -a -d`
3. 健康检查 — `./planet.sh health`
4. 日志 — `./planet.sh log` 及 `-f -b -a`,日志文件路径
5. 创建用户(CLI 兜底)— `./planet.sh createuser`;说明这是公开注册不可用(SMTP 未配置)时的兜底
6. 局域网/WSL 访问 — `--allow-lan`、`netsh portproxy`、防火墙
7. AI Provider 环境变量与构建 — `aiprovider/.env`、`~/.zshrc`、`PLANET_LOAD_ZSHRC_ENV`
8. 故障排查顺序 — 现 manual 末尾那段,原样搬来
9. 开发命令约定 — Bun、`bun run build`、为什么不用 npm
## documentation-coverage-rules.md 增量
在现有"覆盖清单"末尾新增一段:
> **受众分层(强制)**
>
> - 客户/最终用户能在浏览器里完成的操作 → 只写到 `manual.md` / `quickstart.md`
> - 需要 SSH/shell/Docker/`planet.sh`/日志文件路径/端口转发 → 只写到 `ops-runbook.md`(或现有 `ops-*.md`),**禁止**出现在 manual/quickstart
> - 同一动作两种入口(如"创建用户"既能 UI 也能 CLI)→ UI 路径写 manual.md,CLI 路径写 ops-runbook.md,互相用一句话相互引用
> - 新增客户可见 UI 流 → 同时更新 `manual.md` zh+en 与 `docs-content.ts`
> - 新增 ops 命令或脚本 → 只更新 `ops-runbook.md` zh+en
## .claude/commands/docs.md 增量
在 "Step 2 — Decide Scope" 后插一段:
> **Document Audience Routing (Planet)**
>
> 在 Planet 仓库内,写文档前先判断动作的执行者:
>
> - 浏览器 UI 用户 → `docs/technical/{zh,en}/manual.md` / `quickstart.md`
> - shell/容器/运维 → `docs/technical/{zh,en}/ops-runbook.md` 或现有 `ops-*.md`
> - 二次开发者 → 现有 `*-context.md` / `backend-*.md`
>
> 永远不要把 shell 命令、日志路径、Docker 操作写进 manual/quickstart;永远不要把 UI 截图/按钮路径写进 ops-*。
## 关键文件清单
- `docs/technical/zh/manual.md` & `en/manual.md` — 重写
- `docs/technical/zh/quickstart.md` & `en/quickstart.md` — 重写
- `docs/technical/zh/ops-runbook.md` & `en/ops-runbook.md` *(新)*
- `docs/documentation-coverage-rules.md` — 加受众分层段
- `.claude/commands/docs.md` — 加 Document Audience Routing 段
- `frontend/src/pages/Docs/docs-content.ts` — 注册 `ops-runbook` 到 `DOCS_METADATA`(`docs_admin` 组)
## 依赖
manual.md 的"注册账户"和"登录与找回密码"两章需要前后端注册/验证流程已经落地,否则文档会描述不存在的功能。注册功能本身见 [用户公开注册与邮箱验证计划](/home/ray/dev/linkong/planet/docs/plans/user-registration-email-verification-plan.md)。建议先实现注册再重写 manual,避免文档与代码错位。
## 验证
- `rg -n 'planet\.sh' docs/technical/zh/manual.md docs/technical/en/manual.md docs/technical/zh/quickstart.md docs/technical/en/quickstart.md` 应该为空
- `rg -n '注册账户|register|邮箱验证' docs/technical/zh/manual.md docs/technical/en/manual.md` 应该有命中
- `rg -n 'planet\.sh' docs/technical/zh/ops-runbook.md docs/technical/en/ops-runbook.md` 应该有命中
- `frontend/src/pages/Docs/docs-content.ts` 中 `ops-runbook` 出现且分组为 `docs_admin`
- zh/en manual 章节标题对齐(按 `documentation-coverage-rules.md` 现有要求)
- Docs 站点访问:未登录看 manual/quickstart 正常;非 `docs_admin` 用户看不到 `ops-runbook`;`admin` 能看到
@@ -0,0 +1,132 @@
# Earth High Precision Boundary Tiles Plan
## Status
Planning revised after visual review. The previous hand-authored China claim-line / point-buffer approach is rejected and must not be implemented.
Implemented separately:
- 地表 hover 三模式已实现。
Still planned:
- 权威 China POV 数据包。
- OSM / coastline 高精度离线构建。
- 版本化静态矢量瓦片输出。
- 前端 bbox/tile/LRU 高精度加载器。
## Summary
Earth 国界线目标从“明显提升”升级为 **最高精度档按真实地图源一比一还原**:
- 高缩放时不能使用当前 `countries-admin0.min.geojson` 这种低精度简化线。
- 最高 tile zoom 必须忠实保留选定权威矢量源的原始折点,不做视觉平滑,不做人工凭感觉补线。
- 藏南、阿克赛钦等争议陆地直接作为中国国家面的一部分表达;hover 只显示普通 `中国 / CHN`,不显示特殊区域名。
- 九段线 / 十段线必须来自官方标准地图口径或经地理配准校核后的权威矢量数据;不能手工目测画线,不能把马来西亚、菲律宾等周边陆地或近岸底盘划入中国面。
方案仍采用 **离线构建 + 静态矢量瓦片**。低缩放加载简化 base line;高缩放按当前视野 bbox 加载高精度 boundary tiles。第一版不使用 Redis,依靠 Nginx 静态服务、浏览器 HTTP cache 和前端 LRU。
## Data Source and Policy
- 基础陆地国界使用 OSM `boundary=administrative` + `admin_level=2`,并补充高精度 coastline,避免只靠粗糙国家面导致海岸线缺失。
- China POV 覆盖数据必须独立成包,构建时优先级高于 OSM 原始归属:
- 藏南 union 到中国面,同时从印度面 subtract。
- 阿克赛钦 union 到中国面,同时从相关邻接面 subtract。
- 台湾、澎湖、钓鱼岛及附属岛屿、赤尾屿、东沙、西沙、中沙、南沙等作为中国国家面/岛礁面的一部分进入 hover index。
- 岛礁很小时可有最小可交互面,但 tooltip 仍是 `中国 / CHN`,不展示“某特殊区域归属”标签。
- 九段线 / 十段线是独立 maritime claim line 图层:
- 只渲染 dashed line,不参与国家陆地面。
- 不用于吞并周边国家陆地或近岸水域。
- 坐标必须来自官方标准地图、权威矢量数据,或从官方示意图配准后人工复核,不接受手工猜测坐标。
- 必须保留 OSM 数据归因:`© OpenStreetMap contributors, ODbL`。
## Precision Requirements
- 最高精度档的验收口径是 **source-faithful**,不是“看起来更细”:
- 对高精度源线,最高 zoom tile 不允许 Douglas-Peucker 简化。
- 坐标量化精度至少保留到 `1e-5` 度级别,构建时不得把经纬度粗暴四舍五入到低精度。
- 球面渲染只允许 densify 长边来贴合地球曲率;不允许 CatmullRom、Bezier 或任何会改变边界走向的平滑。
- 海岸/边界红框类区域必须与源地图折线逐点对齐;若有偏差,只能追溯并替换数据源,不能靠渲染平滑掩盖。
- 低缩放允许简化,但必须有误差预算:
- base line 只服务远景识别。
- 中 zoom tile 可简化到屏幕误差低于 `0.5px`。
- 最高 zoom tile 使用无简化或近零误差版本。
## Implementation Plan
### 1. Data pipeline
新增边界构建脚本,使用 `/home/ray/.local/bin/uv` 运行:
1. 读取 OSM PBF 或预处理后的 admin-0 边界 / coastline GeoJSON。
2. 读取 China POV override package。
3. 使用可靠几何库做 union / difference / validity repair,禁止手写 polygon overlay。
4. 生成中国国家面时直接合并藏南、阿克赛钦和相关岛礁;从相邻国家面扣除同一区域。
5. 单独读取官方口径九段线 / 十段线矢量,生成 claim-line tiles。
6. 输出:
- 低精度 global base line。
- 无简化 high-precision hover polygon index。
- 高精度静态瓦片:`frontend/public/earth/data/boundaries/v1/{z}/{x}/{y}.geojson`。
- 海上断续线瓦片:`frontend/public/earth/data/boundaries/v1/china-claims/{z}/{x}/{y}.geojson`。
- manifest,记录数据源、覆盖规则版本、构建时间、简化误差和 attribution。
### 2. Tile levels and size budget
- Earth zoom `< 1.6`:只显示 global base line 和低精度 claim line。
- Earth zoom `1.6-2.8`:加载 tile zoom `4-5`。
- Earth zoom `2.8-4.0`:加载 tile zoom `6-7`。
- Earth zoom `> 4.0`:加载 tile zoom `8-10`,使用最高精度无简化折线。
- 单 tile gzip 目标 `20-80KB`,但最高精度档优先保证几何真实性;若超限,优先提高 tile zoom 或拆 tile,而不是简化真实线。
### 3. Frontend loading model
`country-boundaries.js` 拆成 base layer、tile layer 和 China claim layer:
- 首屏加载 base line + hover index,不阻塞 Earth 初始化。
- 高缩放时根据 camera 可见范围计算经纬 bbox,再转换为 Web Mercator tile keys。
- bbox 由屏幕中心、四角和边中点 raycast 得到,并扩张 `10-20%` 作为预取范围。
- 处理反经线,必要时拆成两个 bbox。
- 视野变化请求 debounce `150-250ms`。
- 拖拽/惯性旋转中不每帧请求;缩放档或 tile key 集合没变时不刷新。
- 加载当前视野 tile,并预取一圈邻接 tile。
- base line 在高精度 tile 到达后降低 opacity,避免双线。
### 4. Caching and memory control
- 前端维护 `tileCache`、`inFlightTiles` 和 LRU 使用顺序。
- tile cache 上限建议 `120-180` 个 tile;超过后释放最旧 tile 的 `BufferGeometry`。
- Nginx 为 `/earth/data/boundaries/` 设置长缓存:
- `Cache-Control: public, max-age=31536000, immutable`
- gzip 包含 JSON。
- tile URL 包含版本目录,例如 `v1`;数据更新时改版本目录破浏览器缓存。
- 第一版不使用 Redis。只有改成动态裁剪 API、多 POV 同 URL、或压测证明静态服务成为瓶颈时再考虑 Redis。
## Acceptance Criteria
1. 最高 zoom 的海岸线和国界线与选定源地图逐点一致,不再只是“明显提升”。
2. 红框类海岸/边界细节在最高 zoom 下不能出现肉眼可见的低精度折线、直线切边或圆滑失真。
3. 藏南、阿克赛钦 hover 命中普通 `中国 / CHN`;印度或其他邻接国家不再包含这些区域。
4. 钓鱼岛、赤尾屿、南海诸岛代表点 hover 命中普通 `中国 / CHN`。
5. 九段线 / 十段线位置与权威来源一致,不压入马来西亚、菲律宾等周边陆地或错误包围近岸底盘。
6. 首屏不加载全球超高精度整包。
7. 高缩放只请求当前视野附近 tile,快速旋转不会出现请求风暴。
8. 回到已访问区域命中前端 cache 或浏览器 cache。
9. 国界图层开关、hover 高亮、移动端中心国家高亮、悬停提示三模式保持可用。
## Verification
- 构建阶段:
- 几何 validity check 全通过。
- China POV 代表点测试全部返回 `CHN`。
- 相邻国家代表点不得被 China override 误吞。
- 最高 zoom tile 抽样与源数据做坐标级 diff,确认未简化。
- 前端阶段:
- 在 `frontend` 运行 `/home/ray/.bun/bin/bun run build`。
- 浏览器 DevTools 验证低缩放无高精度 tile 请求,高缩放请求数量受控,重复视野走 cache。
- 用截图中的红框区域、南海断续线、藏南、钓鱼岛、赤尾屿、南海诸岛做手动视觉验收。
## Sources and Assumptions
- 产品默认采用中国标准地图/公开地图合规口径;若后续支持多 POV,必须通过版本化数据目录隔离,不能让同一 URL 返回不同政治口径。
- 当前仓库没有足够权威和足够精细的 China POV / 九段线矢量源,因此不能直接凭现有低精度 GeoJSON 完成“一比一还原”。
- 实施前必须先引入或生成可审计的高精度源数据包;没有源数据时,只能实现加载框架,不能伪造边界。
+1 -1
View File
@@ -273,7 +273,7 @@ hover / locked 使用少量 overlay:
- 算力中心保留现有业务 icon,但接入统一 hover / locked / glow。(已完成)
- 登陆点曾接入同一套 `Points` 渲染,但 pin 类 SVG 在地球边缘会被深度测试裁切;当前保留专用 `THREE.Sprite`,并使用 canvas 生成黄色扁平球,贴到海缆层级。
- TODO:登陆点暂不迁移到完整 Interactable。后续若要统一交互接口,优先考虑 Sprite-backed adapter,只对齐 `getMarkers()`、`getPointerIntersections()`、`setMarkerState()`、`updateVisualState()` 等外观协议,不强行复用 `THREE.Points`、atlas 和跨图层避让。
- 登陆点暂不迁移到完整 Interactable。后续若要统一交互接口,优先考虑 Sprite-backed adapter,只对齐 `getMarkers()`、`getPointerIntersections()`、`setMarkerState()`、`updateVisualState()` 等外观协议,不强行复用 `THREE.Points`、atlas 和跨图层避让。
- 检查图例、搜索和 info-card 是否只依赖业务 payload,而不是依赖渲染对象类型。
### Phase 4:形成 Earth 图标层规范
+105
View File
@@ -0,0 +1,105 @@
# Earth Surface Hover Info Plan
Status: Implemented.
## Goal
为 Earth 桌面和 compact 鼠标地表 hover 增加可配置的提示内容,让用户可以选择只看国家信息、只看位置数据,或同时查看国家和经纬海拔。
当前地表 hover 已经具备两类信息:
- 命中国家时显示国家、ISO、大洲,并高亮国界。
- 未命中国家时显示纬度、经度、海拔。
新方案把这两类信息合并成一个清晰的设置项:`悬停提示`。
## User-facing behavior
设置项放在桌面设置和移动端设置的 `视图` 区,使用分段控件:
- `国家`:陆地命中国家时显示国家名、ISO、大洲;太平洋等海洋区域不显示地表 tooltip。
- `位置`:陆地和海洋都显示纬度、经度、海拔;不触发国家 tooltip 和国家边界 hover 高亮。
- `完整`:陆地命中国家时显示国家信息和纬度、经度、海拔;海洋区域显示纬度、经度、海拔。
默认值为 `完整`,因为它保留现有国家识别价值,同时满足 hover 时查看经纬海拔的需求。
海洋在 `国家` 模式下保持沉默,而不是显示大洋名称。原因是当前项目没有海域/大洋边界数据源;用经纬度粗判太平洋、大西洋等范围容易产生误导。如果用户需要海洋位置,使用 `位置` 或 `完整`。
## Implementation plan
### Settings state
在 `frontend/public/earth/js/constants.js` 增加:
```js
export const SURFACE_HOVER_INFO_MODES = {
COUNTRY: "country",
POSITION: "position",
FULL: "full",
};
export const DEFAULT_SURFACE_HOVER_INFO_MODE =
SURFACE_HOVER_INFO_MODES.FULL;
```
在 `frontend/public/earth/js/controls.js`:
- 将 `EARTH_SETTINGS_VERSION` 从 `10` 升到 `11`。
- 在 shared settings 中新增 `surfaceHoverInfoMode`。
- 新增导出:
- `getSurfaceHoverInfoMode()`
- `setSurfaceHoverInfoMode(mode, { persist, suppressStatus })`
- normalize 时只接受 `country | position | full`,否则回退到 `full`。
- reset settings 后恢复为 `full`。
### Settings UI
在桌面设置 `视图` 区和移动端设置 `视图` 区加入同一组按钮:
```html
<button data-surface-hover-info-mode="country">国家</button>
<button data-surface-hover-info-mode="position">位置</button>
<button data-surface-hover-info-mode="full">完整</button>
```
控件同步规则沿用现有卫星显示风格和巡航模块的模式:
- 当前模式按钮添加 `is-active`。
- 当前模式按钮设置 `aria-pressed="true"`。
- 切换后保存到 Earth settings localStorage。
### Hover tooltip logic
在 `frontend/public/earth/js/main.js` 的地表 hover 分支中读取 `getSurfaceHoverInfoMode()`,统一构造 tooltip。
行为规则:
- 如果没有命中地球:清除国家 hover 并隐藏 tooltip。
- `position`:
- 调用 `clearCountryBoundaryHover()`。
- 显示 `纬度 / 经度 / 海拔`。
- `country`:
- 仅当国界图层开启并命中国家时显示国家 tooltip 和国界 hover。
- 海洋、国界图层关闭、未加载国界数据时隐藏地表 tooltip。
- `full`:
- 国界图层开启且命中国家时显示国家信息加位置信息。
- 未命中国家或国界图层关闭时显示位置信息。
海拔继续使用 `sampleElevationAt(lat, lon)`。暂无采样时显示 `—`,不因 hover 主动加载地形瓦片。
## Acceptance criteria
1. `完整` 模式下,hover 陆地显示国家信息和经纬海拔,hover 海洋显示经纬海拔。
2. `国家` 模式下,hover 陆地显示国家信息,hover 太平洋等海洋不显示地表 tooltip。
3. `位置` 模式下,hover 陆地和海洋都显示经纬海拔,国家边界不高亮。
4. 关闭国界图层后,`完整` 模式回退为只显示位置。
5. 船只、BGP、算力中心、海缆等对象 hover tooltip 优先级不变。
6. 移动端中心国家高亮不受这个鼠标 hover 设置影响。
7. 设置刷新后保持,重置后恢复为 `完整`。
## Verification
- 在 `frontend` 下运行 `/home/ray/.bun/bin/bun run build`。
- 手动验证三种模式的陆地和海洋 hover 行为。
- 验证设置持久化和重置。
- 验证对象 hover 仍优先于地表 hover。
@@ -176,10 +176,12 @@ freshness:
## 聚合接口
状态更新:开发期已直接切换到新船只快照接口。旧 `/api/v1/visualization/geo/vessels` 路由已移除;新的 Earth 船只首屏应调用 `/api/v1/vessels/snapshot`,实时更新走 `/ws` 的 `vessels` 订阅。
现有展示接口应逐步改为消费聚合服务,而不是自己直接拼 `VesselPosition + VesselStatic`。
```text
GET /api/v1/visualization/geo/vessels
GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/visualization/vessels/{mmsi}
GET /api/v1/visualization/vessels/{mmsi}/track
GET /api/v1/visualization/vessels/{mmsi}/conflicts
@@ -317,7 +319,7 @@ VesselFinder 等服务里的船只图片不属于 AIS 实时数据本身。图
目标是让展示接口开始消费聚合结果,但前端形状保持兼容。
1. 实现 AIS 聚合服务,先兼容读取现有表,再逐步切换到原始观测层。
2. 将 `/geo/vessels` 和 `/vessels/{mmsi}` 改为走聚合服务。
2. 将船只列表迁移到 `/api/v1/vessels/snapshot`,并让 `/vessels/{mmsi}` 走聚合服务。
3. 将 `/vessels/{mmsi}/track` 改为走轨迹聚合逻辑。
4. 返回 `field_sources`、`selected_reasons`、`quality_flags`、`conflict_count`。
5. 加入 freshness fallback 和异常位置保护。
@@ -342,13 +344,13 @@ VesselFinder 等服务里的船只图片不属于 AIS 实时数据本身。图
3. 聚合结果返回 `source_summary`,展示每艘船的来源、观测数量、最新观测时间、传输模式和消息类型。
4. 保留 `field_sources` 和 `selected_reasons`,用于解释动态字段来自实时流、静态字段来自可用非空来源。
5. 船名标准化会读取 AISStream `MetaData.ShipName`;船型展示会从 `vessel_type_name` 和 AIS 数字 `vessel_type` 共同归一化,保证 marker 颜色、详情卡、hover 和搜索结果一致。
6. `/geo/vessels` 不再默认限制 5000 艘;不传 `limit` 或传 `limit=0` 表示全量返回,前端默认也不再二次裁剪到 5000。
6. 当前实现已转向 `/api/v1/vessels/snapshot`:必须带 bbox / zoom,默认 `limit=1000`,最大 `limit=5000`,不再支持旧 `/geo/vessels` 全量返回。
### v3.1 — 聚合完整性修复(v4 前置)
### v3.1 — 聚合完整性修复(已被受控 fallback 取代)
目标是先保证“所有已采集到的船都能显示”,BarentsWatch 不因为接入 AISStream 而被 raw observation 聚合结果遮蔽。
原目标是先保证“所有已采集到的船都能显示”,BarentsWatch 不因为接入 AISStream 而被 raw observation 聚合结果遮蔽。当前实现已经移除旧 `/geo/vessels` 路由,船只入口统一为 `/api/v1/vessels/snapshot`。snapshot 优先读取 `ais_raw_observations` 聚合结果;当当前 raw 窗口为空时,才受控回退到 `vessel_position + vessel_static` 最新点,并通过 `diagnostics.legacy_fallback_used` 标记。
当前风险是 `/geo/vessels` 只要 raw observation 聚合返回非空,就直接使用 raw 聚合结果,不再补读兼容层 `vessel_position + vessel_static`。如果 raw observation 中只存在 AISStream 的几百艘船,或 BarentsWatch 历史数据没有完整回填到 raw 层,最终 Earth 就会只显示 AISStream 子集。
因此以下旧 `/geo/vessels` 全量 merge 要求作废,保留在文档中只作为历史决策记录:
1. `/geo/vessels` 必须合并 raw observation 聚合结果和 legacy latest position 结果。
2. raw 与 legacy 同一 MMSI 同时存在时只显示一艘,优先使用 raw 聚合结果及其 `field_sources` / `selected_reasons`。
@@ -416,7 +418,7 @@ REST collector 的自然状态是 `fetch -> transform -> save -> progress 0..100
- `freshness.realtime_stream_seconds` / `polling_seconds` 必须为非负整数;
- `mode=locked` 必须带非空 `locked_source`。
4. 聚合服务 `vessel_ais_aggregation.py` 在 `_select_position_observation` 中按 `freshness` 把过期实时流降级到 stale 候选;在 `_select_static_field` 中按 `field_rules.mode = source_priority / locked / newest / non_empty` 选源。
5. 聚合输出每条 vessel 携带 `aggregation_strategy_version`,并在 `/geo/vessels` GeoJSON properties + `/vessels/{mmsi}` 详情中暴露。
5. 聚合输出每条 vessel 携带 `aggregation_strategy_version`,并在 `/api/v1/vessels/snapshot` GeoJSON properties + `/vessels/{mmsi}` 详情中暴露。
6. API:
- `GET /api/v1/vessel-aggregation/strategy`
- `PUT /api/v1/vessel-aggregation/strategy`(校验失败 400)
@@ -460,8 +462,8 @@ REST collector 的自然状态是 `fetch -> transform -> save -> progress 0..100
- 明显异常位置不会进入默认展示轨迹,并会留下 `quality_flags`。
- 同一时间窗口内多来源相近轨迹点只展示一个点。
- AISStream 重连或回放导致的重复消息不会重复进入聚合结果。
- raw observation 聚合结果和 legacy latest position 结果会按 MMSI 合并,BarentsWatch-only 船只不会因为 AISStream 子集存在而消失。
- 不传 `limit` 或传 `limit=0` 时,`/geo/vessels` 全量返回合并后的船只集合。
- `/api/v1/vessels/snapshot` 优先读取 AIS raw observation 聚合结果;当当前 raw 窗口为空时,允许受控 fallback 到 legacy latest position。
- `/api/v1/visualization/geo/vessels` 路由已移除,客户端必须迁移到新 snapshot API。
- AISStream 长连接收到新船、位置变化和航向变化后,会通过内部 `/ws` 的 `vessels` channel 推送增量。
- AISStream streaming 状态不会显示成固定百分比完成进度条,也不会在收到一批消息后误报采集完成。
- `mmsi`、`imo`、`callsign` 等身份编号在前端不显示千分位符。
@@ -216,7 +216,7 @@ hover、locked、dimmed 可通过更新少量 instance attribute 实现,不再
### 1. 请求视口范围
前端请求 `/api/v1/visualization/geo/vessels` 时带上当前视口 `bbox`,减少无关船只。
前端请求 `/api/v1/vessels/snapshot` 时必须带上当前视口 `bbox`、`zoom` 和受控 `limit`,减少无关船只。旧 `/api/v1/visualization/geo/vessels` 路由已移除。
### 2. 后端排序策略
+15 -21
View File
@@ -1,14 +1,14 @@
# 实时船只监控系统 — 实施计划
**状态**:规划中
**状态**:历史计划;实时 AIS 与聚合接口已由 [AIS 多源采集、冲突记录与聚合接口计划](/home/ray/dev/linkong/planet/docs/plans/earth-vessel-ais-aggregation-plan.md) 接管
**创建日期**:2026-04-27
**优先数据源**:BarentsWatch AIS(免费但需要 OAuth client credentials)→ AISHub / MarineTraffic(TODO,付费)
**优先数据源**:BarentsWatch AIS(免费但需要 OAuth client credentials)→ AISStream realtime;AISHub / MarineTraffic 保留为付费备选
## 已确认决策
| 项目 | 决策 |
|-----|------|
| 数据源 | BarentsWatch 先行;AISHub / MarineTraffic TODO |
| 数据源 | BarentsWatch 先行;AISStream realtime 已成为全球实时补充;AISHub / MarineTraffic 保留为付费备选 |
| 船只规模 | BarentsWatch 阶段全部显示;全球数据接入后按需加船型过滤(默认 Cargo + Tanker + Passenger) |
| 更新频率 | 准实时:前端 5 分钟轮询,后端 Collector 每分钟拉取写库 |
| 历史轨迹 | 保留(`vessel_position` 表保留 24h,后期按需扩展) |
@@ -23,9 +23,9 @@
| 来源类型 | 典型服务 | 覆盖范围 | 成本 | 状态 |
|---------|---------|---------|------|------|
| **BarentsWatch AIS API** | live.ais.barentswatch.no | 挪威海域实时 | 免费,需要 AIS API client credentials | **当前使用** |
| **AISHub** | aishub.net | 全球实时 | 免费/小额 | TODO:付费接入 |
| **MarineTraffic API** | marinetraffic.com | 全球实时 | $50–$500/月 | TODO:评估 tier |
| **VesselFinder API** | vesselfinder.com | 全球实时 | $50–$300/月 | TODO:备选 |
| **AISHub** | aishub.net | 全球实时 | 免费/小额 | 付费备选 |
| **MarineTraffic API** | marinetraffic.com | 全球实时 | $50–$500/月 | 待评估 tier |
| **VesselFinder API** | vesselfinder.com | 全球实时 | $50–$300/月 | 备选 |
| **自建 SDR 接收** | RTL-SDR + AIS-catcher | 仅本地 30–50km | 硬件 $30 | 不考虑 |
| **NOAA 历史数据** | Marine Cadastre | 美国近海历史 | 免费 | 可用于冷启动 |
@@ -36,16 +36,9 @@
- 字段:mmsi, lat, lon, sog, cog, heading, nav_status, name, vessel_type, flag
- 刷新频率:数据约 30–60s 更新一次,可随意轮询
### TODO:多源 AIS 与实时流接入
### 多源 AIS 与实时流接入历史
- [ ] 接入 AISStream WebSocket 采集器,作为 BarentsWatch 覆盖不足的实时补充
- [ ] 将 BarentsWatch、AISStream、自定义 `vessel_ais` 映射源统一写入原始观测层
- [ ] 通过聚合接口做去重、字段合并、冲突记录和默认来源选择
- [ ] 开放字段级聚合策略配置,让用户决定不同字段优先信任哪个来源
- [ ] 评估 AISHub 订阅(全球覆盖,约 $30/月),接入全球实时流
- [ ] 评估 MarineTraffic API tier,对比 AISHub 数据质量与成本
- [ ] 实现多数据源适配器,通过 `datasource_config` 切换
- [ ] 真实高频 AIS 稳定接入后,评估将 `vessel_position` 迁移为 TimescaleDB hypertable(保留 Postgres 原生分区作为备选)
AISStream WebSocket collector、`/api/v1/vessels/snapshot` 和 `/ws` vessels channel 已在后续计划中落地。仍有价值的后续项集中维护在根目录 [TODO](/home/ray/dev/linkong/planet/TODO.md) 的 AIS / Vessels 小节。
多源 AIS 的详细设计见 [AIS 多源采集、冲突记录与聚合接口计划](/home/ray/dev/linkong/planet/docs/plans/earth-vessel-ais-aggregation-plan.md)。
@@ -120,11 +113,12 @@ CREATE UNIQUE INDEX ON vessel_latest(mmsi);
#### 1.3 API 端点
```
GET /api/v1/visualization/geo/vessels
?bbox=lon_min,lat_min,lon_max,lat_max # 视口裁剪
```http
GET /api/v1/vessels/snapshot
?bbox=lon_min,lat_min,lon_max,lat_max # 必填,视口裁剪
?zoom=12 # 必填,当前缩放
?type=cargo,tanker,passenger # 船型过滤
?limit=0 # 可选;不传或 0 表示不裁剪数量
?limit=1000 # 默认 1000,最大 5000
→ GeoJSON FeatureCollection(Point)
GET /api/v1/visualization/vessels/{mmsi} # 单船详情
@@ -163,7 +157,7 @@ GeoJSON Feature 格式:
- 后端 BarentsWatch collector 继续以 HTTP polling 方式采集
- AISStream 等实时源以独立 WebSocket collector 写入原始观测层
- 展示接口从聚合服务读取当前船只视图,而不是由单个 collector 决定最终展示值
- 前端默认不再给 `/geo/vessels` 传 `limit=5000`,`VESSEL_CONFIG.maxRenderedMarkers = 0` 表示不做前端数量裁剪;后续如性能不足再引入显式 LOD 上限
- 旧 `/api/v1/visualization/geo/vessels` 路由已移除,前端必须使用受控 snapshot 接口。
- marker 颜色、详情卡、hover 和搜索结果必须共享 `vessel_type_display` 船型归一化结果,避免 AIS 数字类型码已驱动颜色但卡片仍显示 `Other`
- 前端是否升级为 WebSocket delta push 是独立优化,不影响后端采集器可以使用 WebSocket 接上游实时源
@@ -251,7 +245,7 @@ IMO 9811000
### Phase 4 — 性能与生产化(2–3 天)
- `vessel_position` 按天分区,7 天自动清理
- TODO:真实数据量达到百万级/日后,将 `vessel_position` 升级为 TimescaleDB hypertable,配置 retention policy 与压缩策略
- 真实数据量达到百万级/日后,再评估是否将船只时序数据升级为 TimescaleDB hypertable,并配置 retention policy 与压缩策略
- GeoJSON endpoint 用 Redis 缓存 15s
- 若需 bbox 精确查询,引入 PostGIS `geography` + `ST_DWithin`
- InstancedMesh + frustum culling,目标 5 万船只 60fps
@@ -0,0 +1,55 @@
# Planet 正式交付与 CI/CD 稳定化计划
## Summary
- CI/CD 平台采用 Gitea Actions,由自托管 `act_runner` 执行。
- 正式交付目标采用 Kubernetes,端口、健康检查、重启和滚动发布交给 Service、Ingress、readiness/liveness probe。
- Vite 继续保留,但只作为开发服务器和生产构建工具;生产运行 nginx 托管 `vite build` 产物。
- 不新增 Webpack 双构建链。Electron 仅在离线桌面交付成为明确目标后再评估。
## Key Changes
- 生产镜像:
- frontend 多阶段构建,`bun install` + `bun run build`,最终 nginx 托管 `dist`。
- backend/aiprovider 移除 `--reload`,加入容器健康检查。
- 镜像标签使用 `<registry>/<namespace>/<service>:<git-sha>`,发布 tag 额外推 `vX.Y.Z`。
- Kubernetes:
- 新增 Helm chart:`deploy/helm/planet`。
- frontend 暴露 Ingress;backend/aiprovider 默认 ClusterIP。
- PostgreSQL/Redis 默认外部依赖,`values.single-node.yaml` 提供演示/测试内置依赖。
- Gitea Actions:
- `ci.yaml`:后端测试、前端构建、Docker build smoke、Helm render。
- `release.yaml`:构建并推送三类镜像。
- `deploy-staging.yaml`:部署 staging、等待 rollout、执行 smoke tests。
- 开发脚本边界:
- `planet.sh` 保留为本地开发便利脚本。
- CI/CD 与正式部署不调用 `planet.sh start`。
## Vite / Webpack / Electron Decision
中肯结论:不要因为“企业生产环境”这件事去做 Webpack 版本;继续用 Vite,但把“开发服务器”和“生产构建/部署”分清楚。Electron 也不要现在做,除非正式版目标明确是离线桌面软件。
Vite 可以用于生产构建。生产环境运行的是 `vite build` 产出的静态资源,不是 Vite dev server。当前项目已经使用 React + Vite + Bun、`import.meta.env`、`public/earth` 静态资产路径和大量 Three.js/ES module 资源引用。维护 Webpack 双构建链会显著增加路径、资源、环境变量和回归测试成本。
如果未来客户环境确实要求更接近 Webpack 生态,优先做 Rsbuild/Rspack 技术 spike,而不是直接维护 Webpack 并行构建。Electron 适合离线运行、本地硬件/文件访问、系统托盘、自动更新和安装包分发;但 Planet 目前还包含 backend、database、Redis、AI Provider、Motion Agent 等服务编排,桌面壳不能解决正式交付的核心问题。
## Test Plan
- CI gates:
- `uv sync --group dev`
- `uv run pytest backend/tests/test_api.py backend/tests/test_realtime_sources.py -q`
- `cd frontend && bun install --frozen-lockfile && bun run build`
- Docker build frontend/backend/aiprovider
- `helm lint deploy/helm/planet`
- `helm template planet-staging deploy/helm/planet -f deploy/helm/planet/values.single-node.yaml`
- Staging deployment:
- `helm upgrade --install planet-staging deploy/helm/planet --namespace planet-staging`
- 等待 frontend/backend/aiprovider rollout。
- smoke test frontend `/`、frontend `/health`、backend `/health`、aiprovider `/health`。
## Acceptance Criteria
- main/dev 提交能通过 CI。
- 发布 workflow 能生成可追踪镜像。
- staging 可从零部署并完成滚动升级。
- 正式部署不依赖本机端口清理,也不运行 Vite dev server。
@@ -0,0 +1,155 @@
# 用户公开注册与邮箱验证计划
**状态**:待实施
**创建日期**:2026-05-12
**核心目标**:给 Planet 增加公开注册流程 + 邮箱验证码 + 忘记密码,让客户无需管理员介入就能开通账号;同时把 SMTP 邮件作为可复用基础服务接入 `/settings`。
## 背景
当前认证只暴露 `/auth/login`、`/auth/refresh`、`/auth/logout`、`/auth/me`(`backend/app/api/v1/auth.py`),账号只能由 `super_admin` 在 `/users` 后台创建。User 模型 `backend/app/models/user.py` 没有 `email_verified` 字段,仓库也没有任何 SMTP/邮件发送基础设施。
客户旅程想从"打开浏览器→注册→验证→登录"开始走(见 [文档受众分层重构计划](/home/ray/dev/linkong/planet/docs/plans/docs-audience-split-plan.md)),就必须先把这条链路在代码里跑通。
注册策略(已确认):
- 开放公开注册,任何人可在 `/register` 自助开通
- 默认角色 `viewer`
- 邮箱验证后立即可登录(无需管理员审批)
- 验证仅走 SMTP 邮件,6 位数字码,10 分钟 TTL
## 数据模型
`backend/app/models/user.py` 加两列:
```python
email_verified = Column(Boolean, default=False, nullable=False)
pending_email = Column(String(255), nullable=True) # 改邮箱时临时落地待验证地址
```
迁移路径:仓库目前没看到 alembic 目录,沿用 `backend/app/db/session.py` 的初始化风格在启动时跑 `ALTER TABLE users ADD COLUMN IF NOT EXISTS ...`。先确认是否存在 alembic,若有则正规迁移。
不另建 `verification_codes` 表 — OTP 走 **Redis**(系统已有 Redis,token blacklist 也走 Redis):
```
key: otp:{purpose}:{email} purpose ∈ {register, verify_email, reset_password}
value: { code_hash: bcrypt, attempts: int, issued_at: ts }
TTL: 600 秒
```
`{purpose}:{email}` 同时配一个限流键 `otp_rate:{purpose}:{email}`,TTL 60 秒,用于"60 秒内禁止重发"。
## 服务拆分
按项目 `services/` 单职责风格拆两个:
**`backend/app/services/otp.py`**(通用 OTP 原语,未来 2FA / 手机号验证可直接复用):
```python
async def issue_code(email: str, purpose: OtpPurpose) -> str # 生成 6 位、写 Redis、返回明码(调用方负责送达)
async def verify_code(email: str, purpose: OtpPurpose, code: str) -> bool # 校验并消耗
async def check_resend_allowed(email: str, purpose: OtpPurpose) -> None # 抛 RateLimited 异常
```
- 6 位数字,密码学随机
- Redis 存 `bcrypt(code)`,不存明码
- 校验失败计数 ≥ 5 直接失效该 key
- 重发触发即失效旧 code
**`backend/app/services/email.py`**(通用 SMTP 发送,告警/摘要等后续可复用):
```python
async def send_email(to: str, subject: str, html: str, text: str | None = None) -> None
async def send_verification_email(to: str, code: str, purpose: OtpPurpose) -> None # 模板封装
```
- 用 `aiosmtplib` 异步发送
- 从 `system_settings` 的 `smtp` 命名空间读配置(host/port/username/password/from/use_tls)
- 未配置抛 `EmailNotConfiguredError`
- 模板用简单 HTML + 纯文本双段,按 `purpose` 切换文案
编排("签码 → 发邮件")在 `api/v1/auth.py` 端点里调两个服务,不在 service 内互相调用,保持单测可单独 mock。
## 后端端点
新增到 `backend/app/api/v1/auth.py`:
| 端点 | 入参 | 行为 |
| --- | --- | --- |
| `POST /auth/register` | `username, email, password` | 用户名/邮箱查重 → 写 User `is_active=True, email_verified=False, role="viewer"` → 调 `otp.issue_code(email, "register")` → 调 `email.send_verification_email` |
| `POST /auth/verify-email` | `email, code` | `otp.verify_code` → 置 `email_verified=True` → 直接返回 access/refresh token |
| `POST /auth/resend-code` | `email, purpose` | `check_resend_allowed` → `issue_code` → `send_verification_email` |
| `POST /auth/forgot-password` | `email` | 即便邮箱不存在也返回 200(防枚举);存在则签 `reset_password` 码并发邮件 |
| `POST /auth/reset-password` | `email, code, new_password` | `verify_code(..., "reset_password")` → `user.set_password(new_password)` |
`/auth/login` 改造:邮箱未验证用户登录返回 `403 { code: "EMAIL_NOT_VERIFIED", email }`,前端拿到后跳验证页。
## SMTP 设置
复用 `backend/app/api/v1/settings.py` 现有 setting store,新增 `smtp` 命名空间:
- `smtp_host`、`smtp_port`、`smtp_username`、`smtp_password`、`smtp_from`、`smtp_from_name`、`smtp_use_tls`
- 密码走与 collector 凭证相同的加密路径(看 `backend/app/services/` 是否已有 `credentials_encryption` 之类工具,若有直接复用)
- `POST /settings/smtp/test` — 用当前未保存的入参试发一封到指定地址,不落库
未配置 SMTP 时 `/auth/register` 应返回明确错误 `503 { code: "EMAIL_PROVIDER_NOT_CONFIGURED" }`,提示管理员先去 `/settings` 配 SMTP 或用 `./planet.sh createuser` 兜底。
## 前端
**新页面**:
- `frontend/src/pages/Register/Register.tsx` — 两步表单:(1) 用户名/邮箱/密码 (2) 6 位验证码;60s 重发冷却;验证成功写 token,自动跳 `/admin`
- `frontend/src/pages/VerifyEmail/VerifyEmail.tsx` — 给登录拦截 `EMAIL_NOT_VERIFIED` 时落地的页,仅"输码 + 重发"
- `frontend/src/pages/ForgotPassword/ForgotPassword.tsx` — 两步:(1) 输邮箱 (2) 输码 + 新密码
**改动**:
- `frontend/src/pages/Login/Login.tsx` — 表单下加"注册账号"、"忘记密码"链接;接 `EMAIL_NOT_VERIFIED` 跳 `/verify-email`
- `frontend/src/pages/Settings/Settings.tsx` — 新增 SMTP 子 tab(host/port/username/password/from/TLS + 测试发送按钮),用工作区里新建的 `frontend/src/components/ConnectionTestInput/` 做连通测试输入
- 路由表(`frontend/src/App.tsx` 或 `frontend/src/router/*`)— 加 `/register`、`/forgot-password`、`/verify-email`
## 关键文件清单
后端:
- `backend/app/models/user.py` — 加字段
- `backend/app/schemas/user.py` — 新增 `UserRegister`、`VerifyCode`、`ResetPasswordRequest` schema
- `backend/app/api/v1/auth.py` — 新端点 + 登录校验
- `backend/app/services/otp.py` *(新)*
- `backend/app/services/email.py` *(新)*
- `backend/app/api/v1/settings.py` — SMTP 命名空间 + 测试发送
- `backend/app/core/config.py` — SMTP 默认值/特性开关
- `backend/app/db/session.py` — DDL 兜底(若无 alembic)
前端:
- `frontend/src/pages/Register/Register.tsx` *(新)*
- `frontend/src/pages/VerifyEmail/VerifyEmail.tsx` *(新)*
- `frontend/src/pages/ForgotPassword/ForgotPassword.tsx` *(新)*
- `frontend/src/pages/Login/Login.tsx`
- `frontend/src/pages/Settings/Settings.tsx`
- 路由文件
## 实施顺序
1. 后端:User 模型字段 + DDL 兜底
2. 后端:`services/otp.py`(先纯单测跑通)
3. 后端:`services/email.py`(用 MailHog 本地试发)
4. 后端:`/auth/register` + `/auth/verify-email` + `/auth/resend-code` + 登录拦截
5. 后端:`/auth/forgot-password` + `/auth/reset-password`
6. 后端:`/settings/smtp` 命名空间 + 测试发送
7. 前端:`Settings.tsx` 加 SMTP 子 tab
8. 前端:Register / VerifyEmail / ForgotPassword 页 + Login 入口
文档同步在 [文档受众分层重构计划](/home/ray/dev/linkong/planet/docs/plans/docs-audience-split-plan.md) 落地。
## 验证
- **后端单测**(仿 `backend/tests/test_settings_ai_provider.py`):
- 注册端点用户名/邮箱查重
- OTP 过期、错码计数、重发限流
- 邮箱未验证用户登录返回 `EMAIL_NOT_VERIFIED`
- SMTP 未配置时注册端点返回 `EMAIL_PROVIDER_NOT_CONFIGURED`
- 忘记密码对不存在邮箱仍返回 200
- **后端集测**:本机起 MailHog 或 Mailtrap,把 SMTP 指到上面,跑 register → 收码 → verify → login 一遍
- **前端**:`source ~/.zshrc && bun run build`;启 dev server 走 `/register` → `/verify-email` → `/admin` 全流程,再试 `/forgot-password`
- **手测**:新邮箱注册 → 收码 → 输错 → 重发 → 输对 → 登录 → 改密码 → 用新密码再登;管理员在 `/settings` 改 SMTP → 测试发送
+56 -4
View File
@@ -299,6 +299,17 @@ State semantics:
AISStream connectivity validation reads the saved collector configuration, environment variables, and `AISSTREAM_API_KEY` in `~/.zshrc` through `datasource_connectivity.py`. For actual collection, the most reliable path is saving the API key in `Settings -> Collector Settings -> AISStream Vessels`; if the key only lives in `~/.zshrc`, confirm that the backend process inherited it.
The console manages AISStream from `/datasources -> Realtime Streams`, not from the normal finite collection progress bar. The realtime stream API aggregates runtime state, health, configuration preview, and raw observation counters:
```http
GET /api/v1/realtime-sources
POST /api/v1/realtime-sources/{source}/start
POST /api/v1/realtime-sources/{source}/stop
POST /api/v1/realtime-sources/{source}/restart
```
`aisstream_vessels` and custom `source_type=websocket` sources appear in that API. They do not participate in one-click collection percentages; the UI interprets them as long-lived services with message counters, lag, last success, and last error.
### AIS Raw Observations And Aggregation
AIS observations do not directly replace final vessel records. They are first saved as raw observations:
@@ -309,17 +320,50 @@ AIS observations do not directly replace final vessel records. They are first sa
- Dynamic fields such as position, speed, and course are selected by freshness and source priority.
- Static fields prefer non-empty values; conflicting candidates are recorded for detail and diagnostics views.
Earth still reads vessel data from:
Earth vessel rendering now consumes the bounded snapshot endpoint and realtime delta channel:
```http
GET /api/v1/visualization/geo/vessels
GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/visualization/vessels/{mmsi}
GET /api/v1/visualization/vessels/{mmsi}/track
GET /api/v1/visualization/vessels/{mmsi}/conflicts
GET /api/v1/visualization/vessels/aggregation/diagnostics
```
`/geo/vessels` merges raw observation aggregation with the legacy BarentsWatch latest-position tables so adding AISStream does not hide historical BarentsWatch-only vessels.
`/api/v1/vessels/snapshot` requires `bbox` and `zoom`, defaults to `limit=1000`, and caps `limit` at `5000`. It prefers aggregated `ais_raw_observations`; when the current raw window is empty, it can fall back to the latest legacy `vessel_position` / `vessel_static` rows and marks that path with `diagnostics.legacy_fallback_used`. The old `/api/v1/visualization/geo/vessels` route has been removed.
Realtime deltas are sent through the `/ws` `vessels` channel. Clients must subscribe with the current viewport:
```json
{
"type": "subscribe",
"data": {
"channel": "vessels",
"bbox": [120.8, 30.7, 122.1, 31.8],
"zoom": 12,
"limit": 1000
}
}
```
The backend stores lightweight subscription filters per connection and only sends vessel updates that match the subscriber bbox. Collector broadcasts enter a 1-second throttle queue; within each flush window, only the latest update per MMSI is retained.
### Layer APIs And Global Stats
Earth is moving to two API families:
```http
GET /api/v1/data-products
GET /api/v1/data-products/{product_id}/status
GET /api/v1/layers/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/cables?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/landing-points?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/satellites?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/bgp/anomalies?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/bgp/incidents?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/bgp/collectors?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
```
`/api/v1/data-products/*` is for aggregate panels and keeps a global statistics scope independent of the map bbox. `/api/v1/layers/*` is for map rendering, requires `bbox` and `zoom`, defaults to `limit=1000`, and caps `limit` at `5000`; low zoom falls back to a smaller response cap and reports `degraded`, `truncated`, `limit_clamped`, and `stats_scope=viewport` in `diagnostics`. Non-vessel layers currently reuse the existing GeoJSON converters before the guard layer; future product-specific queries can push bbox filtering deeper.
## X. Collector Settings And Connectivity Validation
@@ -390,4 +434,12 @@ curl -X POST http://localhost:8000/api/v1/datasources/1/trigger \
-H "Authorization: Bearer <token>"
```
Batch collection uses:
```http
POST /api/v1/datasources/trigger-batch
```
The request body may pass `source_ids` for selected rows. Without `source_ids`, the backend filters by `product`, `module`, `is_active`, `run_status`, `collected`, `credential_status`, and `q`. The endpoint skips disabled sources, sources already running without `force`, and sources still inside their frequency window, then returns `triggered`, `skipped`, and `failed` groups.
**Core file**: `backend/app/api/v1/datasources.py`
@@ -288,6 +288,16 @@ Normalization:
Connectivity validation reads saved configuration, environment variables, and `AISSTREAM_API_KEY` from `~/.zshrc`. For actual collection, prefer saving the API key in collector settings. If the key only lives in `~/.zshrc`, confirm that the backend process inherited it; otherwise validation may pass while the collector runtime cannot read the key.
Connectivity validation and actual collection are separate actions. A banner such as `AISStream credentials configured, WebSocket endpoint format valid` only means the saved settings can be used for a connection attempt; runtime status may still be `disconnected`. Global AIS data is written locally only while `aisstream_vessels` is `streaming` / `connected` and its realtime stream counters plus `last_seen_at` keep advancing. Start, stop, reconnect, health, and counters are exposed through `/datasources -> Realtime Streams` and `/api/v1/realtime-sources`; AISStream is not counted in normal one-click collection progress.
The new vessel list entry point is no longer the legacy `/api/v1/visualization/geo/vessels` route. Earth initial state should call:
```http
GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
```
That endpoint prefers local aggregated `ais_raw_observations`; when the current raw window is empty, it can fall back to the latest legacy `vessel_position` / `vessel_static` rows and exposes that through `diagnostics.legacy_fallback_used`. Realtime updates use the `/ws` `vessels` channel; subscriptions must include `bbox`, `zoom`, and `limit`. The server filters updates per connection and merges collector broadcasts every second, keeping only the latest position per MMSI.
## Custom REST / WebSocket Mapping Runtime
Files:
+1
View File
@@ -157,6 +157,7 @@ Current design:
- symbol-driven event cores
- outward ring pulses
- reduced diffuse glow compared with older Earth builds
- event region halos, collector coverage halos, and radar pulses derive a lighter tint from their own icon color instead of using a fixed teal; red high-severity events, orange active collectors, and blue idle collectors keep their hue family while broad halos stay softer than the icon
5. The right-side stats now show:
- BGP events
- collector count
+12 -2
View File
@@ -152,7 +152,11 @@ The `earth:compute-center-location-saved` reconciliation pipeline is deliberatel
### AIS Vessel Layer
The vessel layer fetches `/api/v1/visualization/geo/vessels` and renders the aggregated AIS GeoJSON through `createInteractableLayer()`. By default it does not send a `limit` parameter, and `VESSEL_CONFIG.maxRenderedMarkers = 0` means the frontend does not clip the result to 5000 vessels. A positive `options.limit` or positive `maxRenderedMarkers` can still be used as an explicit temporary cap.
The vessel layer now uses `/api/v1/vessels/snapshot` for the initial viewport snapshot and the `/ws` `vessels` channel for realtime deltas. Snapshot requests must include `bbox`, `zoom`, and a bounded `limit`; the backend defaults to `limit=1000` and caps it at `5000`. WebSocket subscriptions must include the same viewport fields so the server can filter updates per connection.
The legacy `/api/v1/visualization/geo/vessels` route has been removed. Frontend code should fetch a snapshot for the current viewport when the layer opens, then subscribe to `vessels` deltas. After map pan or zoom, reload the snapshot and send a fresh vessels subscription. The backend only falls back to legacy `vessel_position` / `vessel_static` rows when the current raw window is empty; frontend code can detect that state through `diagnostics.legacy_fallback_used`.
The new layer API family is `/api/v1/layers/*`, which separates map rendering payloads from aggregate panel statistics. Layer requests must include `bbox`, `zoom`, and a bounded `limit`; responses include `visible_count`, `returned_count`, and `diagnostics`, where `degraded`, `truncated`, and `limit_clamped` are the frontend signals for fallback UI. Right-side aggregate panels should not sum the layer response. They should read `/api/v1/data-products` or `/api/v1/data-products/{product_id}/status`, because those statistics stay global and do not change with the viewport.
Vessel color and vessel type text must use the same normalized classification. `vessels.js` derives `type` from both `vessel_type_name` and the AIS numeric `vessel_type` code; that `type` drives marker color. It also derives `vessel_type_display`, which `main.js` uses for the info card, hover summary, and search result subtitle. Do not make the info card read only the raw `vessel_type_name`, because AISStream can provide a numeric type while the raw name is still `Other`.
@@ -201,7 +205,13 @@ Terrain should not block startup when it is not the restored visible layer. Afte
Earth settings are stored in `localStorage`. The key is typically a namespaced string defined in `constants.js`. `controls.js` handles read, write, and reset.
Settings that affect visual layers (terrain opacity, day/night mode, satellite display style, etc.) are read during initialization and applied immediately.
Settings that affect visual layers and surface interaction (terrain opacity, day/night mode, satellite display style, satellite idle breathing, real satellite altitude, track display, hover tooltip mode, etc.) are read during initialization and applied immediately.
The surface hover tooltip preference is persisted by `controls.js` as `shared.surfaceHoverInfoMode`, while `main.js` composes the actual tooltip in the globe-surface hover branch. `Country` shows country details only when a country polygon is hit and stays silent over ocean; `Position` shows latitude, longitude, and sampled terrain elevation and clears country-boundary hover; `Full` shows country + position on land and position over ocean.
The real satellite altitude preference is persisted by `controls.js`, while the rendering state lives in `satellites.js`. When enabled, the real radius from SGP4 is compressed logarithmically into the current Earth visual radius range. When disabled, satellite dots, trails, and predicted orbits all return to the legacy same-sphere display. Toggling this setting must refresh satellite positions and clear trail buffers so a trail never mixes both height models. `maxRealAltitudeOffset = 25` is a visual cap tuned for the current camera and `earthRadius = 100`: GEO / MEO remain clearly higher than LEO, but the highest orbits stay within about 25% beyond the globe radius so selection targets, red trails, and the globe do not feel disconnected.
SGP4 propagation returns an inertial-frame position, so it must not be drawn directly as Earth-fixed longitude / latitude. `satellites.js` uses `gstime` to convert ECI/TEME positions to ECF, then maps that result into the same Three.js axes as `latLonToVector3()`. Satellite dots and short trails use Earth-fixed coordinates for each sample time, representing the object's current position relative to the globe surface. The locked predicted orbit uses the `gstime` from the lock moment for the whole future orbit, projecting the inertial orbit plane onto the current globe pose; that keeps the line closed and keeps the visual orbit inclination aligned with the details card. Fallback predicted orbits must also use a real RAAN + inclination orbital-plane formula, not treat inclination as a constant latitude.
## Current Terrain Pipeline
@@ -160,10 +160,13 @@ The land/ocean base is an Earth base-map asset and preloads at startup; the "Bor
| Name | Variable | Current Value | Location / Notes |
| --- | --- | --- | --- |
| Satellite display radius offset | `SATELLITE_CONFIG.displayAltitudeOffset` | `8` | Satellite point position |
| Satellite fallback radius offset | `SATELLITE_CONFIG.fallbackAltitudeOffset` | `8` | Legacy same-sphere position when real altitude is disabled or TLE propagation fails |
| Satellite altitude compression scale | `SATELLITE_CONFIG.altitudeCompressionKm` | `1200` | TLE/SGP4 altitude compression; larger values soften high-orbit separation |
| Satellite real-altitude cap | `SATELLITE_CONFIG.maxDisplayAltitudeKm` | `40000` | Altitude clamp for the compressed display mapping, covering GEO-range altitude |
| Satellite real-altitude display offset range | `minRealAltitudeOffset / maxRealAltitudeOffset` | `4 / 25` | Compressed offset added to `CONFIG.earthRadius`; `25` is about one quarter of the current globe radius `100`, keeping high-orbit separation visible without pushing GEO/MEO trails too far away |
| Satellite dot base pixel size | `SATELLITE_CONFIG.dotBaseSize` | `2.8` | Point shader size |
| Satellite backdrop dot scale | `SATELLITE_CONFIG.dotBackdropScale` | `1.28` | Backdrop dot size |
| Satellite dot opacity range | `dotOpacityMin / dotOpacityMax` | `0.7 / 1.0` | Breathing animation |
| Satellite dot opacity range | `dotOpacityMin / dotOpacityMax` | `0.42 / 1.0` | Breathing animation |
| Satellite dot breathing speed | `SATELLITE_CONFIG.dotBreathingSpeed` | `0.12` | Dot opacity animation |
| Satellite backdrop renderOrder | inline | `5` | `satelliteBackdropPoints.renderOrder` |
| Satellite dot renderOrder | inline | `6` | `satellitePoints.renderOrder` |
@@ -230,7 +233,9 @@ AIS vessel markers use batched `THREE.Points`, not one `THREE.Sprite` per vessel
| Medium color | `BGP_CONFIG.severityColors.medium` | `0xffd166` | Medium-severity event |
| Low color | `BGP_CONFIG.severityColors.low` | `0x4dabf7` | Low-severity event |
| Collector base color | `BGP_CONFIG.collectorColor` | `0x6db7ff` | Default collector color |
| Region color | `BGP_CONFIG.regionColor` | `0x2dd4bf` | Region overlay |
| BGP halo neutral tint | `BGP_CONFIG.halo.tintNeutralColor` | `0xffffff` | Broad halos derive from the matching event / collector icon color and blend toward this neutral, keeping the same hue family without becoming identical |
| BGP halo icon-color blend | `BGP_CONFIG.halo.tintBlend` | `0.72` | Higher values stay closer to the icon color; currently used by event region halos, collector coverage halos, and collector radar pulse |
| Region color | `BGP_CONFIG.regionColor` | `0x2dd4bf` | Legacy region baseline; broad BGP halos now prefer colors derived from the event or collector icon |
## Celestial and Starfield
@@ -6,8 +6,8 @@ Note: the layer control panel order and the registration / startup load order ar
| Order type | Current sequence | Notes |
| --- | --- | --- |
| Control panel order | Cables → Trails → Satellites → Compute Centers → BGP → Terrain → HD Texture → Cloud Layer → Border Lines → Grid | Controlled by `displayOrder`, sorted by operational relevance. |
| Registration / startup load order | Grid → Border Lines / Land-Ocean Base → HD Texture → Cloud Layer → Cables → Compute Centers → BGP → Satellites | Controlled by registration order and `startupPriority`, sorted surface-to-sky; the startup queue reads persisted layer visibility first, skips normal layers explicitly saved as hidden, and HD Texture does not download the texture when disabled; Border Lines are the exception: the land-ocean base always preloads, while the persisted state only controls interactive border lines and hover; Trails and Terrain are dependency/optional display layers and do not participate in normal startup data loading. |
| Control panel order | Cables → Satellites → Compute Centers → Vessels → BGP → Terrain → HD Texture → Cloud Layer → Border Lines → Grid | Controlled by `displayOrder`, sorted by operational relevance; satellite trails moved to Settings and are no longer a layer-list item. |
| Registration / startup load order | Grid → Border Lines / Land-Ocean Base → HD Texture → Cloud Layer → Cables → Compute Centers → Vessels → BGP → Satellites | Controlled by registration order and `startupPriority`, sorted surface-to-sky; the startup queue reads persisted layer visibility first, skips normal layers explicitly saved as hidden, and HD Texture does not download the texture when disabled; Border Lines are the exception: the land-ocean base always preloads, while the persisted state only controls interactive border lines and hover; Trails and Terrain are dependency/optional display layers and do not participate in normal startup data loading. |
## Surface Layer Stack
@@ -29,9 +29,9 @@ Note: the layer control panel order and the registration / startup load order ar
| 3 | Satellite footprint fill / Iridium coverage ring | `satellites.js`, `iridium-footprint-adapter.js` | `GROUND_FOOTPRINT_RENDER_ORDER` | depth-tested; Iridium adapter fill / ring use the same renderOrder | Footprint above land / texture / terrain and country borders, below compute centers and satellites. |
| 3-5 | BGP markers and overlays | `bgp.js` | Each marker's own renderOrder | BGP picking path | Preserves existing BGP visual level. |
| 4.5 | Compute centers | `compute-centers.js` | `COMPUTE_CENTER_RENDER_ORDER` | Compute center picking path | Surface facilities, below satellites. |
| 5 | Satellite background dot | `satellites.js` | Fixed renderOrder | Screen-space satellite picking | Below satellite dots. |
| 6 | Satellite dots | `satellites.js` | Fixed renderOrder | Screen-space satellite picking | Satellite dots above footprints and compute centers. |
| 12+ | Satellite locked ring, halo, predicted orbit | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` and offsets | Satellite overlay path | Used for selected/locked satellite emphasis. |
| 5 | Satellite background dot | `satellites.js` | Fixed renderOrder; by default TLE/SGP4 altitude is compressed to `CONFIG.earthRadius + 4..25`; with real altitude disabled or propagation failed, uses `fallbackAltitudeOffset = 8` | Screen-space satellite picking | Below satellite dots. |
| 6 | Satellite dots | `satellites.js` | Same compressed / fallback height as satellite backdrop dots | Screen-space satellite picking | Satellite dots above footprints and compute centers. |
| 12+ | Satellite locked ring, halo, predicted orbit | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` and offsets; predicted orbit follows the same real-altitude toggle and fixes the lock-time globe pose to draw a closed inertial orbit; returns to same-sphere mode when real altitude is disabled | Satellite overlay path | Used for selected/locked satellite emphasis. |
| 98-100 | Sun / moon halo and sprite | `celestial.js` | Fixed renderOrder | Celestial picking disabled | Foreground celestial sprites. |
## Toggle Behavior
@@ -43,6 +43,7 @@ Note: the layer control panel order and the registration / startup load order ar
| Terrain on | Displayed above HD texture, but below country border hover, footprints, satellites, and other emphasis layers. |
| Cloud layer | Only controls cloud mesh visibility. |
| Border Lines off | Hides only interactive border lines and hover, clearing hover state; the land/ocean base fill remains as the Earth base map. |
| Real Satellite Altitude off | Satellite dots, trails, and predicted orbits use the legacy same-sphere height; satellites with missing TLE data or failed propagation also use this fallback height. |
## Interaction Rules
+17 -6
View File
@@ -55,12 +55,12 @@ tasklist /svc /fi "PID eq 4700"
For temporary troubleshooting, you can stop IP Helper from Administrator PowerShell:
```powershell
Stop-Service iphlpsvc
Stop-Service iphlpsvc -Force
```
This may affect networking, proxying, or forwarding features. Do not disable it long-term unless you know why it is safe. If the Windows forwarding rule must stay, use a different Planet backend port.
This may affect networking, proxying, or forwarding features. Do not disable it long-term unless you know why it is safe. New `--allow-lan` runs a temporary Windows relay for `3000` / `8000`, so persistent portproxy is no longer required.
If the script prints `failed-stop-service` or `failed-stop-process`, the current shell does not have permission to clear the Windows listener. Startup stops immediately instead of launching the backend into the same port conflict.
If the script prints `failed-stop-service`, `failed-stop-process`, or Vite reports `Port 3000 is already in use` followed by `Windows listener ... services=iphlpsvc`, an old Windows listener still owns the port. Startup stops immediately and prints the recovery order: use Administrator PowerShell to inspect `netsh interface portproxy show all`, delete the matching `listenport` rule, confirm the PID and services with `netstat` / `tasklist` if no portproxy rule exists, and temporarily run `Stop-Service iphlpsvc -Force` when appropriate. After old rules are gone, rerun `./planet.sh restart --allow-lan`; the script starts temporary relays while LAN devices still use `3000` / `8000`.
### Which startup flags change default ports?
@@ -110,15 +110,18 @@ The flag must be written as `--allow-lan`. `allowlan` or `--allowlan` is not rec
If `ss -ltnp` shows the frontend listening on `0.0.0.0:3000`, but `Test-NetConnection <Windows LAN IP> -Port 3000` still fails from Windows PowerShell, the problem is usually Windows-side forwarding or firewall policy rather than Vite or `.zshrc`.
For traditional WSL NAT networking, configure portproxy and firewall from Administrator PowerShell:
For traditional WSL NAT networking, `./planet.sh start --allow-lan` starts temporary Windows relays so Windows still exposes `3000` / `8000`. Before startup, the script checks for stale `portproxy` rules and requests Administrator PowerShell to delete them. It also checks Windows Firewall and, when inbound allow rules for `3000` / `8000` are missing, triggers a UAC Administrator PowerShell request to create them. If the automatic request is canceled, clean up manually:
```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
LAN devices should use the Windows external port, for example `http://<Windows LAN IP>:3000/earth`.
If `wslinfo --networking-mode` prints `mirrored`, also check Hyper-V firewall. Even when ordinary Windows Firewall rules exist, Hyper-V firewall can still block external devices from reaching WSL. From Administrator PowerShell, allow the required ports:
```powershell
@@ -321,6 +324,14 @@ Collecting and saving are two separate actions. Candidates can be previewed on E
Compute-center saves write to `compute_center_locations` and refresh the layer. Records with no candidate stay in the unresolved list; Planet does not fabricate a location from a country center or hard-coded hint.
### Why are satellites no longer on one sphere?
Earth enables "Real Satellite Altitude" by default. Satellite positions still come from TLE/SGP4, but altitude is compressed for display: LEO satellites stay close to the globe, while higher-orbit satellites render farther out without leaving the normal view. The maximum display offset is `25`, about one quarter of the current globe radius; this is a readability compromise that separates GEO / MEO / LEO without drawing real kilometers to scale. This setting also affects satellite trails and the predicted orbit shown after locking a satellite.
Turn off "Real Satellite Altitude" in Earth Settings to restore the legacy same-sphere satellite display. Satellites with missing TLE data or failed propagation still fall back to the legacy fixed height, so they do not disappear just because a real altitude cannot be computed.
Low-inclination high-orbit satellites should stay near the equator or a fixed longitude band, not form a near north-south ring. Earth converts the SGP4 inertial position to Earth-fixed coordinates for the current dot; the locked predicted orbit fixes the current globe pose and draws one inertial orbit, so it should close and preserve the correct inclination. If a future details card shows inclination near `0°` but the predicted orbit looks polar, check the ECI/TEME-to-ECF conversion and whether the predicted orbit accidentally uses per-sample `gstime`.
### Why does Motion Debug not show camera video?
With the Browser Camera source, the debug panel shows the local browser camera preview and draws the skeleton over it. If `Skeleton Only` is enabled, the video preview is hidden and the panel keeps only the dark canvas plus red/green skeleton.
@@ -163,7 +163,25 @@ Current constraints:
- Internal document links should be converted to `/docs/:slug` through `transformLink`
- Heading anchors are injected through `getHeadingId`, keeping route state outside the renderer
### 6. `TableActions`
### 6. `ConnectionTestInput`
File:
- [ConnectionTestInput.tsx](/home/ray/dev/linkong/planet/frontend/src/components/ConnectionTestInput/ConnectionTestInput.tsx)
Purpose:
- Console form fields that combine an endpoint/Base URL value with a connection check
- Connection-test entry points for AI Provider and WebSearch
- Future collector configuration fields should reuse it when the test action belongs inside the input
Current constraints:
- The input suffix shows a single plug/connector icon, not an adjacent text button
- Disabled integrations must grey out both the input and its connection-test action
- The component only combines the input and action; callers still own form state, loading, disabled state, and the request itself
### 7. `TableActions`
File:
@@ -205,10 +223,13 @@ File:
Responsibilities:
- `/ai` now owns LLM Provider, AI Tool configuration, and the testbench instead of nesting them under `/settings`
- The `模型供应商` tab manages default provider, model, base URL, provider key, local `aiprovider` proxy, and connection test
- The `工具` tab manages WebSearch provider, search key, base URL, timeout, result count, and advanced provider options
- The `模型供应商` tab manages default provider, model, base URL, provider key, local `aiprovider` proxy, and connection test; provider and model fields use editable comboboxes so users can manually enter new providers/models if the models.dev catalog stops updating
- The `工具` tab first selects a tool from a dropdown menu, then renders that tool's configuration; it currently includes WebSearch and OCR
- WebSearch configuration includes provider, search key, base URL, timeout, result count, and advanced provider options
- OCR configuration includes provider, Base URL, API key, model/engine, languages, timeout, file-size limit, and output format
- The `测试台` tab embeds the former Playground real session, preset prompts, and AI Provider status debugging
- The page reuses the Settings single-screen tabs, panel card, and internal scrolling style
- AI Provider and WebSearch connection tests use `ConnectionTestInput`, with the connector icon fixed at the end of the Base URL input; when WebSearch is disabled, every configuration field and the test entry point are greyed out except the switch
Legacy `/settings?tab=ai` should redirect to `/ai?tab=providers`.
Legacy `/playground` should redirect to `/ai?tab=playground`.
+247 -575
View File
@@ -1,666 +1,338 @@
# Planet Manual
This manual is for daily use, demos, development integration, and local operations. It covers four core entry points:
This manual is for Planet end users. Starting from the browser, it covers account registration, login, configuring collectors, configuring AI, using Earth and the console, and reading the docs site. Every action happens in a browser.
- `planet.sh`: local start, stop, restart, health check, and log access
- Earth: public 3D situational awareness page
- Console: admin backend (login required)
- Docs: backend Gatekeeper-controlled documentation; basic usage docs are public, while developer and operations docs require permission groups
For the shortest path to getting started, see [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md). For common troubleshooting, see the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md).
If you are responsible for deployment or on-call duty, read the [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md) instead — it covers shell commands, log paths, and CLI fallbacks for user creation.
## Entry Overview
After a default startup, the common URLs are:
| Name | URL | Login Required | Description |
| --- | --- | --- | --- |
| Earth | `http://localhost:3000/earth` | No | 3D globe, layers, BGP, satellites, cables, news situational awareness |
| Docs | `http://localhost:3000/docs` | Partly | Usage docs are public; developer, backend, and operations docs require Gatekeeper groups |
| FAQ | `http://localhost:3000/docs/faq` | No | Windows / WSL, ports, dependencies, motion capture, credentials, and permission troubleshooting |
| Console | `http://localhost:3000/admin` | Yes | Data, config, alerts, logs, and situational observation |
| AI | `http://localhost:3000/ai` | Yes | Model providers, AI tools, and testbench |
| Backend API Docs | `http://localhost:8000/docs` | Depends on endpoint | FastAPI / OpenAPI documentation |
| Earth | `http://<host>/earth` | No | Public 3D situational awareness page |
| Docs | `http://<host>/docs` | Partly | Public docs need no login; developer/ops docs need Gatekeeper groups |
| Register / Login / Forgot Password | `/register`, `/login`, `/forgot-password` | No | Self-serve account creation and recovery |
| Console | `http://<host>/admin` | Yes | Data, collectors, alerts, AI, users, settings |
| AI | `http://<host>/ai` | Yes | Model providers, tools, testbench |
| Backend API Docs | `http://<host>:8000/docs` | Depends | FastAPI / OpenAPI |
## planet.sh
URLs below use the local default `http://localhost:3000`. Replace the prefix with your deployment URL in production.
`planet.sh` is the main control script for local development and demos. Use it to manage services rather than manually starting frontend, backend, database, and AI Provider separately.
## Register an Account
### Start
1. Open `http://localhost:3000/login` and click "Register" under the form.
2. On `/register`, fill in:
- **Username**: 3–50 characters, used to log in
- **Email**: receives the verification code; editable later in account settings
- **Password**: at least 8 characters
3. After submission you are taken to the verify page. A 6-digit code is sent to your email. It expires in 10 minutes.
4. Enter the code and click "Verify and Sign In". On success the system stores a session and sends you to the console.
```bash
./planet.sh start
```
If no email arrives within 60 seconds:
Default behavior:
- Check spam, promotions, and any enterprise mail gateway
- The "Resend Code" button shows a 60-second countdown; you can resend after it ends
- After 5 wrong attempts the code is invalidated; you must resend a new one
- Starts PostgreSQL and Redis
- Starts AI Provider
- Starts the backend API
- Starts the frontend Vite dev server
- Outputs Earth, console, Playground, and backend API doc URLs
If you see "Email service not configured", the administrator has not yet set up SMTP. Ask the administrator to fill SMTP at `/settings -> SMTP Email`.
Specify custom ports:
The default role for a self-registered user is `viewer`, which can sign in and view public content. To see collector / user / settings pages, ask an `admin` or `super_admin` to promote your role at `/users`.
```bash
./planet.sh start -b 8001 -f 3001 -a 8101
```
## Sign In and Recover Password
Parameters:
### Sign In
| Flag | Meaning |
| --- | --- |
| `-b <port>` | Backend port |
| `-f <port>` | Frontend port |
| `-a <port>` | AI Provider port |
| `--allow-lan` | Enable LAN access |
| `--verbose` | Show more command output during execution |
Open `/login`, enter username and password. On success you are taken to `/admin`.
### AI Provider Environment and Builds
If you see "Email not verified", the page automatically redirects to `/verify-email` — follow the prompts to enter the code.
AI Provider runtime configuration can live in `aiprovider/.env` or in matching variables in `~/.zshrc`. `planet.sh` reads simple `export AI_...=...` / `AI_...=...` lines and passes them to the container at startup.
### Forgot Password
Changing model, API key, or base URL does not rebuild the image. Restart only AI Provider to pick up runtime configuration changes:
1. On `/login`, click "Forgot Password?", or open `/forgot-password` directly.
2. Enter your registered email and click "Send Code". The same confirmation is shown regardless of whether the email is registered (to avoid enumeration).
3. After receiving the code, enter it together with a new password (≥ 8 characters) and click "Reset Password".
4. The system sends you back to `/login` — sign in with the new password.
```bash
./planet.sh restart -a
```
## Account Settings
For complex shell expansion in `~/.zshrc`, opt in explicitly:
Click your username at the top-right of the console to open account settings:
```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```
- Change password: enter current password + new password
- Change email: the system sends a verification code to the new address; the change applies only after verification
- View Gatekeeper groups: lists current groups (`docs_user` / `docs_developer` / `docs_admin`)
- Log out: clears the current session
To ignore `~/.zshrc` during troubleshooting:
## Console Overview
```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```
The AI Provider Docker build context is intentionally limited to the files required by the service, and `uv sync` uses a BuildKit cache mount so dependency downloads are reused after the first build.
### Stop
```bash
./planet.sh stop
```
Stops:
- Backend
- AI Provider
- Frontend
- PostgreSQL
- Redis
### Restart
Full restart:
```bash
./planet.sh restart
```
Per-module restart:
```bash
./planet.sh restart -b
./planet.sh restart -f
./planet.sh restart -a
./planet.sh restart -d
```
| Flag | Effect |
| --- | --- |
| `-b` | Backend only |
| `-f` | Frontend only |
| `-a` | AI Provider only |
| `-d` | Database only |
Per-module restarts are preferred during development — they avoid interrupting unrelated services.
### Create User
```bash
./planet.sh createuser
```
Used to create a console login account before first use. The script interactively prompts for username, password, and role.
### Health Check
```bash
./planet.sh health
```
Checks:
- `planet_*` container status
- Backend `/health`
- AI Provider `/health`
- Frontend reachability
If something shows offline, check the corresponding logs first.
### Logs
Recent logs:
```bash
./planet.sh log
```
Follow logs:
```bash
./planet.sh log -f
./planet.sh log -b
./planet.sh log -a
```
| Flag | Log source |
| --- | --- |
| `-f` / `--frontend` | `/tmp/planet_frontend.log` |
| `-b` / `--backend` | `/tmp/planet_backend.log` |
| `-a` / `--ai-provider` | `planet_aiprovider` container logs |
### LAN Access
```bash
./planet.sh start --allow-lan
```
Useful for:
- Starting in WSL, accessing from Windows browser
- Demos on phone or tablet
- Another machine on the same LAN accessing the same dev instance
`--allow-lan` only makes the frontend and backend listen on `0.0.0.0`. When Planet runs in WSL, Windows can usually reach it through `localhost`, but access from a phone or another computer through `http://<Windows LAN IP>:3000` still depends on Windows port forwarding and firewall rules.
Use this order to diagnose:
```bash
# From WSL or the shell running Planet
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'
```
If this shows `0.0.0.0:3000` and `0.0.0.0:8000`, but the LAN IP still fails, configure Windows from an elevated PowerShell:
```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
## Earth
Earth is the public 3D situational awareness page, accessed at:
```text
http://localhost:3000/earth
```
It is a standalone frontend. The actual page lives at:
- `frontend/public/earth/index.html`
- `frontend/public/earth/js/`
- `frontend/public/earth/css/`
The React route `/earth` simply hosts it in an iframe.
### Main Uses
Earth is used to observe in a single globe view:
- BGP events, anomalies, and situational posture
- Satellites and orbital trails
- Submarine cables and landing points
- Compute centers
- AIS vessels
- Border lines, grid lines, HD texture, cloud layer, terrain
- Live news streams and situational news
- Search and focused object details
### Layer Control
The right-side layer panel toggles visualization layers on or off.
Common layers include:
- Grid lines
- Border lines
- HD texture
- Atmospheric cloud layer
- Submarine cables
- Compute centers
- BGP observation
- AIS vessels
- Satellites
- Orbital trails
- Terrain
Some layers have dependencies:
- Terrain requires HD texture
- Trails require Satellites
- When HD texture is off, the globe shows the base map and edge glow effect
### Legend
The lower-left legend follows the currently focused or enabled layer.
Current legend modes include:
- Cables
- Satellites
- Border lines
- Compute centers
- BGP
- AIS vessels
AIS vessel legend entries are grouped by vessel type: cargo, tanker, passenger, fishing, military, anchored/slow, and other. Triangle markers represent moving vessels; dots represent anchored or slow vessels.
### Search
Earth search finds current globe objects, such as:
- Submarine cables
- Landing points
- Satellites
- Compute centers
- BGP events
- BGP collectors
Search results can be used to quickly locate objects and open their details.
### Location Candidate Collection
Compute-center and BGP collector detail cards can collect candidate coordinates automatically. After clicking an object, use `自动采集坐标候选` or `重新自动采集坐标`; the backend ranks source coordinates, open organization lookups, and Nominatim online search results. If those regular sources return no candidates, the current default AI Provider is used once as an LLM factcheck fallback. Stored BGP collector locations are used as query context only and are not emitted as candidates.
Candidates can be previewed directly on Earth. Compute-center candidates can be saved into the `compute_center_locations` dimension table from the detail card, then the layer refreshes immediately. The notification badge on the compute-center layer row shows unresolved records that cannot be rendered; clicking it opens the queue, where users can collect individual candidates or use `一键采用` to save the highest-confidence candidate top-to-bottom. Records without candidates stay in the queue and are not replaced by country centroids or hard-coded hints. See [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md) for the full workflow.
### Settings
The settings panel contains:
- Rotation mode / cruise mode / motion mode
- Cruise modules: BGP, News, Compute Centers, Vessels, Cables, Satellites
- View settings: satellite display style, day/night mode, panel visibility
- Motion Debug Mode, Motion Input Source, skeleton-only debug view
- Globe default size
- Terrain opacity
- Reset settings
These settings are stored in browser local storage. They revert to defaults if you switch browsers or clear site data.
### View Controls
Earth supports mouse, touchpad, and touchscreen interaction.
Common controls:
| Action | Result |
| --- | --- |
| Left-button drag | Rotates the globe |
| One-finger drag | Rotates the globe on touch devices |
| Mouse wheel | Zooms the view in or out |
| Two-finger pinch | Zooms the view on touch devices |
| Zoom buttons | Adjust zoom in fixed steps |
| Click the zoom percent | Resets to the default zoom |
When zooming, the top capsule briefly shows the current zoom level, for example `Zoom 180%`. This indicates view zoom only, not data loading progress. Loading status takes priority and will not be interrupted by zoom feedback.
Drag sensitivity adjusts automatically based on the current zoom. Around the default view it keeps the normal rotation feel; when zoomed in, dragging becomes progressively finer for inspecting a region, vessel, satellite, or BGP event; when zoomed out, dragging is slightly faster for global browsing.
### Motion Capture Controls
Earth has a motion-capture control entry point for large-screen and future 3D displays. There are two realtime input sources: the default `Browser Camera` source uses webpage `getUserMedia` and recognizes gestures locally in the browser; the advanced `Motion Agent` source uses `camera/RTSP/HTTP -> local Agent -> local WebSocket -> Earth page`. Neither path sends camera frames or realtime gesture decisions to the cloud, and neither path reuses the news/RSS aggregation APIs.
It is disabled by default. Enable `Motion Debug Mode` in settings, open Earth with `?motion=1`, or set `planet-earth-motion-control-enabled=true` in browser local storage to start the selected source. The default source is `Browser Camera`; it requires HTTPS or localhost and a granted browser camera permission, but does not require installing an app. For dual cameras, USB indexes, phone/network camera streams, client integration, or edge devices, switch the setting to `Motion Agent`. The default Agent URL is `ws://127.0.0.1:8765/ws/gestures`; the `motionAgent` URL parameter can override it.
URL parameters can also force the source: `?motion=1&motionProvider=browser` uses the browser camera, `?motion=1&motionProvider=agent` uses Motion Agent, and providing `motionAgent=ws://...` automatically selects Motion Agent.
Current gesture semantics:
| Gesture event | Result |
| --- | --- |
| `rotate_left` | Rotates the globe left |
| `rotate_right` | Rotates the globe right |
| `rotate_up` | Rotates the globe upward |
| `rotate_down` | Rotates the globe downward |
| `zoom_in` | Zooms in |
| `zoom_out` | Zooms out |
| `focus_prev` / `focus_next` | Switches targets within the current motion layer |
| `layer_prev` / `layer_next` | Switches the motion candidate layer and cruises to the nearest target in that layer |
| `confirm` | Confirms the currently selected target; browser recognition currently keeps the two-hands-up confirm gesture disabled |
The settings panel also includes `Motion Debug Mode`, which opens the debug panel. With the Browser Camera source, the panel shows a local live preview and draws joints and bones over it. With the Motion Agent source, the Agent sends normalized skeleton events only and does not send raw video frames. The `Skeleton Only` switch hides the video preview and keeps the dark canvas plus skeleton; `Stop Matching Gestures` pauses gesture execution while preview and skeleton drawing can continue for debugging. Unmatched skeletons are red; once a gesture matches, the skeleton turns green and the matched gesture name is shown. Both this entry and the `Motion Input Source` control already carry Gatekeeper permission markers for future authorization control.
### Cruise Mode
Cruise mode makes Earth automatically cycle through focus targets.
Current cruise modules:
- BGP
- News
- Compute Centers
- Vessels
- Cables
- Satellites
Suitable for demos, monitoring displays, or unattended presentations.
### Mobile
Earth has a mobile drawer layout. On small screens:
- Layer controls open in a mobile drawer
- Search, settings, and details use mobile panels
- Main interactions remain centered on globe object clicks, search, and layer toggles
### Common Issues
#### Earth Won't Open
Check whether the frontend is online:
```bash
./planet.sh health
./planet.sh log -f
```
If the frontend port is not `3000`, use the actual port shown at startup.
#### Layer Has No Data
Check the backend and data sources:
```bash
./planet.sh health
./planet.sh log -b
```
Then open the console and check:
- `/datasources`
- `/data`
- `/bgp`
#### Satellites, BGP, or Cables Load Slowly
These layers may depend on backend APIs, external data sources, or first-run collection tasks. Wait for startup tasks to finish before checking logs and console data source status.
## Console
Console entry point:
```text
http://localhost:3000/admin
```
The console requires login. Create a user first if this is your first time:
```bash
./planet.sh createuser
```
### Page Structure
The console uses React + Ant Design, with a left-side menu organized by work domain.
Common pages:
The console at `http://localhost:3000/admin` is built with React + Ant Design. The left menu is organized by work domain.
| Page | Route | Purpose |
| --- | --- | --- |
| Dashboard | `/admin` | System overview |
| Earth | `/earth` | Opens the public Earth page |
| Data Sources | `/datasources` | View data sources and trigger collection |
| Collected Data | `/data` | View collected data |
| BGP Observation | `/bgp` | BGP situational data |
| Earth | `/earth` | Open the public Earth page |
| Datasources | `/datasources` | Source directory and collection triggers |
| Collected Data | `/data` | Data already ingested |
| BGP | `/bgp` | BGP situational view |
| System Alerts | `/alerts/system` | System-level alerts |
| BGP Alerts | `/alerts/bgp` | BGP-related alerts |
| Situational Alerts | `/alerts/situational` | Situational assessment alerts |
| AI | `/ai` | Model providers, WebSearch-style tools, and testbench |
| System Logs | `/logs` | View system logs (typically super admin only) |
| Users | `/users` | User management |
| Settings | `/settings` | System config and TV live stream sources |
| Situational Alerts | `/alerts/situational` | Situational analysis alerts |
| AI | `/ai` | Model providers, tools, testbench |
| Logs | `/logs` | Usually visible only to super admin |
| Users | `/users` | Create/delete users, change roles/groups |
| Settings | `/settings` | System, SMTP, TV, collectors |
### Data Sources
Menu items hide automatically when you lack permission. If a menu is missing, check your role and Gatekeeper groups.
`/datasources` shows collection sources and triggers collection. It is now a data source directory that lists built-in and custom sources in one table.
## Configure Data Collectors
Common operations:
`/settings?tab=collector_credentials` is the "Collector Settings" page. It manages connection configuration for every collector, not just credentials.
- View data source status
- Trigger collection
- View recent collection tasks
- Open the read-only detail drawer for endpoint, headers, runtime config, and built-in/custom source type
Steps:
If a category of objects is missing on Earth, start here to confirm the data source is available.
1. Pick a collector in the dropdown.
2. Inspect status tags:
- `No credentials` / `Credentials required`
- Owning module
- `Enabled` / `Disabled`
- `Unchecked` / `Reachable` / `Unreachable`
3. Click the plug icon next to the dropdown to run a health check. On success the status becomes `Reachable`.
4. Edit endpoint, headers, timeout, retries; click save.
The data source name opens an information drawer only. Endpoint, credentials, headers, and custom source configuration are maintained under `/settings` collector settings.
For free collectors without credentials, the health check hits the endpoint directly. For credential-bearing collectors it runs the credential flow. If credentials or endpoint changed since the last successful check, click connect again.
When collection tasks are running, the progress area shows a clickable `Collecting N` pill. Clicking it opens a modal with each running task's phase, progress, and processed count.
"Connected" means either: data was successfully collected with the current config, or the connect button passed validation with the current config.
### Collected Data
### BarentsWatch AIS Credentials
`/data` shows the collected data table.
Useful for diagnosing:
- Whether data has entered the system
- Whether data update times match expectations
- Whether a data source produced valid records
### BGP Observation
`/bgp` is the BGP-focused page.
It complements the BGP layer on Earth:
- Earth emphasizes spatial posture and visual focus
- The console BGP page emphasizes lists, status, details, and assessment
### Alerts
Alert entry points:
- `/alerts/system`
- `/alerts/bgp`
- `/alerts/situational`
Used to view system, network, and situational alerts.
### System Settings
`/settings` manages system-level configuration.
Current common uses:
- System settings
- TV live stream source configuration
- Collector settings
### AI
`/ai` manages the AI runtime chain and is now separate from system settings. Legacy `/playground` redirects to `/ai?tab=playground`.
It currently contains:
- `模型供应商`: default LLM provider, model, base URL, API key, local `aiprovider` proxy, and connection test
- `工具`: WebSearch provider, search API key, base URL, max results, timeout, and advanced provider options
- `测试台`: AI Provider status, preset prompts, and real analysis-chain debugging
Legacy `/settings?tab=ai` redirects to `/ai?tab=providers`.
Available configuration depends on the current user's role.
#### Collector Settings
`/settings?tab=collector_credentials` is currently displayed as Collector Settings. It manages connection settings for all collectors, not only credentials.
Use it to:
1. Select a collector from the dropdown.
2. Review tags such as `Requires credentials`, module, enabled state, and `Unchecked` / `Available` / `Unavailable`.
3. Click the plug icon next to the selector to run a health check.
4. Edit endpoint, request headers, timeout, and retry settings.
5. Save the collector settings.
Free collectors are checked by requesting their endpoint directly. Credentialed collectors use their credential provider. If endpoint or credential fingerprint changes after the last successful validation, the collector must be checked again.
The system treats a collector as connected when the current configuration has either collected data successfully or passed the manual connection check.
#### BarentsWatch AIS Credentials
`BarentsWatch AIS` is a credentialed built-in collector. Its credential card appears above the basic configuration card.
Configured fields:
`BarentsWatch AIS` is a credential-required built-in collector. Selecting it surfaces the credential section above the base configuration:
- `Client ID`
- `Client Secret`
- `Endpoint`
If a secret is already configured, the input shows a masked preview. Keeping that preview unchanged preserves the stored secret; entering a new value replaces it.
If a secret was saved previously, the input shows a masked preview. Saving while keeping the preview unchanged preserves the original secret; entering a new secret overwrites it.
BarentsWatch AIS credentials can be read from:
When the connection fails, the page opens a credential guide. You can:
1. Collector settings saved in the console.
2. Backend environment variables:
- `BARENTSWATCH_CLIENT_ID`
- `BARENTSWATCH_CLIENT_SECRET`
- historical spellings: `BARRENTSWATCH_CLIENT_ID`, `BARRENTSWATCH_CLIENT_SECRET`
3. matching `export` lines in `~/.zshrc`.
- View the default guide
- Click "Guide not helpful" to ask AI Provider to regenerate from the default prompt
- Click "Reset" to restore the default guide
If connection fails, the page opens the credential guide. The guide can be regenerated through AI Provider or reset to the default guide. The default guide points users to the official BarentsWatch tutorial and emphasizes selecting `AIS - API`, not the regular `BarentsWatch - API`.
The default guide follows the BarentsWatch official tutorial and reminds you to choose `AIS - API` for Live AIS.
### System Logs
### AISStream Realtime Vessels
`/logs` views system logs. If the menu item is not visible, the current user likely lacks the required role.
`AISStream Realtime Vessels` is the global AIS WebSocket collector. A passing connection test only confirms API key + endpoint format. Actual global vessel data requires the backend `aisstream_vessels` collector to stay connected and write to `ais_raw_observations`.
Common troubleshooting sequence:
Steps:
```bash
./planet.sh health
./planet.sh log
```
1. Open `/settings?tab=collector_credentials` and select `AISStream Realtime Vessels : aisstream_vessels`
2. Fill the AISStream API Key
3. Keep the default endpoint `wss://stream.aisstream.io/v0/stream`
4. Click the plug icon to test; confirm it reports `Reachable`
5. Save collector settings
6. Open the `Realtime Streams` tab on `/datasources` and find `AISStream Realtime Vessels`
7. Use `Start`, `Stop`, or `Reconnect` there. The normal `Collection Tasks` tab does not count AISStream in one-click collection or percentage progress
8. Watch the realtime stream panel:
- `streaming` / `connected` means the live stream is being consumed
- `total stored`, `last 24h`, `last 1h`, and `unique MMSI` show historical collection volume
- `disconnected` with a recent error means the upstream or network dropped; click `Reconnect`
Then open `/logs` for more structured runtime information.
## Configure AI Credentials
## Docs
`/ai?tab=providers` is the AI management entry. Two key sub-tabs:
Documentation site:
- `Model Providers`: default LLM provider, model, base URL, API key, local `aiprovider` proxy, connection test
- `Tools`: a dropdown for specific tools — currently WebSearch and OCR
```text
http://localhost:3000/docs
```
### Model Providers
Docs content is read through backend APIs by permission. The frontend no longer bundles all Markdown files directly. Source files still live in:
Providers and models accept presets or arbitrary custom IDs. Common fields:
```text
docs/technical/zh/ (Chinese)
docs/technical/en/ (English)
```
- Provider: e.g. `minimax`, `openai`, `anthropic`, `ollama`
- Protocol: `OpenAI Chat Completions` / `Anthropic Messages` / `Ollama Generate`
- Base URL: model API URL
- Default Model: e.g. `gpt-5.1`, `MiniMax-M2.7`
- API Key: stored on save; displayed masked afterwards
- Max Tokens, Anthropic Version: keep defaults if unsure
- Timeout / Retry: timeout and retry attempts
Anonymous visitors only see `public` docs such as the overview, quickstart, and manual. Logged-in users can see more technical docs when assigned Gatekeeper groups:
The plug icon at the end of the Base URL input runs a connection test. A passing test echoes the model's short reply.
- `docs_user`: user-operation docs.
- `docs_developer`: Earth, frontend, backend, collector, and AI Provider development docs.
- `docs_admin`: service control, operations, environment variable, and sensitive-operation docs.
### Tools
`admin` receives admin-doc access by default, and `super_admin` can read all Docs content. Gatekeeper groups are configured in the console Users page.
- **WebSearch**: provider, API key, base URL, max results, timeout, advanced provider parameters. While disabled, all fields except the enable switch are greyed out
- **OCR**: provider, base URL, API key, model/engine, recognition languages, timeout, max file size, output format
Docs supports:
The legacy link `/settings?tab=ai` redirects to `/ai?tab=providers`.
- Category navigation
- Markdown rendering
- Tables and code blocks
- In-document table of contents
- Search across currently visible docs
- Internal links between technical documents
## System Settings
When adding a new technical document, check:
`/settings` manages system-level configuration. Sub-tabs:
- Does it have a clear top-level heading
- Does it need to be added to backend Docs metadata for category and ordering
- Should it be classified as `public`, `docs_user`, `docs_developer`, or `docs_admin`
- **System Display**: name, refresh interval, retention, max concurrent tasks
- **Notifications**: alert email switch, recipient, critical/warning/daily summary
- **Security**: session timeout, max login attempts, password policy
- **SMTP Email**: outgoing email used by registration and password reset (visible to `admin` / `super_admin` only)
- **TV Livestream**: TV source management
- **AI / WebSearch / OCR**: see above
## Development Command Conventions
### SMTP Email Settings
Frontend commands must use Bun:
Public registration and verification codes depend on this section. An `admin` or `super_admin` opens `/settings -> SMTP Email` and fills:
```bash
cd frontend
bun install
bun run dev
bun run build
```
- SMTP host, port
- Username, password
- From address (required), from name
- STARTTLS (typical for port 587) or implicit TLS (port 465)
- Timeout in seconds
Do not use `npm run ...`. The project uses Bun in WSL / Windows mixed environments to avoid Node/npm path compatibility issues.
Save, then click "Send Test Email" and enter a recipient address to verify delivery. Once that works, regular users can self-register at `/register`.
Verify the frontend build:
Leaving the masked password preview unchanged keeps the original password. Enter a new value to replace it.
```bash
source ~/.zshrc && bun run build
```
## User Management (Admins)
## Troubleshooting Order
`/users` is `super_admin`-only for create/delete. The page supports:
When something goes wrong, follow this sequence:
- Listing users (username, email, role, active, email verified)
- Creating users (equivalent to public registration but skips email verification — administrator vouching)
- Changing roles: `viewer` / `operator` / `admin` / `super_admin`
- Editing Gatekeeper groups: `docs_user` / `docs_developer` / `docs_admin`, controlling which docs are visible
- Disabling / enabling accounts
1. Check service status:
To let a regular user read developer or operations docs, add `docs_developer` or `docs_admin` at `/users`.
```bash
./planet.sh health
```
## Data Exploration
2. Check recent logs:
- `/datasources`: source directory. The `Collection Tasks` tab is for one-shot, scheduled, and finite collectors; it can be filtered by product domain, layer/module, enabled state, last run status, whether collected records exist, and search text. Selecting rows triggers only those sources; with no selected rows, `Collect current filter` triggers the filtered scope. The `Realtime Streams` tab is for AISStream / WebSocket long connections and shows connection health, stored totals, time-window counters, and Start / Stop / Reconnect actions. Clicking a name opens an info drawer showing endpoint, headers, base config, and built-in flag; endpoint/credentials editing happens at `/settings -> Collector Settings`. The `Collecting N` tag under the overall progress can be clicked to expand the current collection task list
- `/data`: collected data table — used to verify "did data arrive", "is the freshness right", "does a source emit valid records"
- `/bgp`: BGP detail page with list + detail + analysis; complements the BGP layer on Earth
- `/alerts/system`, `/alerts/bgp`, `/alerts/situational`: system, BGP, and situational alerts
```bash
./planet.sh log
```
## AI Testbench
3. Check per-module logs:
`/ai?tab=playground` is for real-pipeline debugging:
```bash
./planet.sh log -f
./planet.sh log -b
./planet.sh log -a
```
- Pick the active provider
- Run preset requests or custom prompts
- Watch AI Provider status and response
4. Restart only the affected module:
The legacy link `/playground` redirects here.
```bash
./planet.sh restart -f
./planet.sh restart -b
./planet.sh restart -a
```
## Earth Public Page
5. If database or cache is abnormal, restart the database:
Earth at `http://localhost:3000/earth` is the public 3D situational page; no login required. The React route `/earth` wraps a standalone frontend (in `frontend/public/earth/`) via iframe.
```bash
./planet.sh restart -d
```
### Primary Uses
6. If still unrecovered, do a full restart:
A single globe view of: BGP events and observations, satellites and tracks, cables and landing points, compute centers, country boundaries / graticules / high-res tiles / clouds / terrain, news live streams and situational news, search and focus details.
```bash
./planet.sh restart
```
### Layer Control
The right-side layer panel toggles layers. Common layers: graticule, country boundaries, high-res tiles, atmospheric clouds, cables, compute centers, BGP, satellites, AIS vessels, terrain. Satellite tracks are no longer listed as a standalone layer; they are controlled from Settings.
Dependencies:
- Terrain depends on high-res tiles
- Tracks depend on satellites
- With high-res tiles disabled, the globe shows the base map with edge highlighting
### Legend
The bottom-left legend follows the focused or enabled layer. Covered: cables, satellites, country boundaries, compute centers, BGP, AIS vessels.
AIS vessel legend colors by type: cargo, tanker, passenger, fishing, military, moored/slow, other. Triangles indicate moving vessels; dots indicate moored or slow targets.
### Search
Search finds cables, landing points, satellites, compute centers, BGP events, BGP observers. Results jump to and focus the object.
### Coordinate Candidate Collection
Compute center and BGP observer detail cards support automatic coordinate-candidate collection. Click the object then use "Collect Coordinate Candidates" or "Re-collect Coordinates". The backend assembles candidates from source coordinates, public-org registry APIs, and online geocoders. When regular sources have no candidate, the current default AI Provider runs one LLM factcheck fallback. BGP observers' stored coordinates only fill query context; they are not returned as candidates.
Candidates preview on Earth directly. Saving a compute-center candidate writes to the `compute_center_locations` dimension table and refreshes the layer immediately. The notification badge at the top-left of the compute-center layer shows the unresolved count; clicking it opens the queue, supports single collection, or "Adopt All" to save the top-confidence candidates from top to bottom. Records without candidates stay in the queue rather than being faked to country centroids. See [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md).
### Settings
The settings panel covers: rotate / cruise / motion mode, cruise modules (BGP/news/compute centers/vessels/cables/satellites), view (satellite display style, hover tooltip, satellite idle breathing, real satellite altitude, track display, compact dots, day-night mode, panel toggles), motion debug mode / input source / skeleton-only, default globe size, terrain opacity, reset.
"Real Satellite Altitude" is enabled by default: satellite positions use a compressed display height based on TLE/SGP4 orbital altitude. LEO satellites remain close to the globe, while high-orbit satellites render farther out without leaving the normal view. The high-orbit display height is capped at about one quarter of the globe radius, so GEO / MEO objects remain visually separated from LEO without spreading trails and selection targets too far apart. Turning it off restores the legacy same-sphere satellite display. "Track Display" controls satellite trail visibility; trails are unavailable while the satellite layer is hidden.
"Hover Tooltip" controls the tooltip shown when the pointer hovers over the globe surface: `Country` shows country details only when land matches a country, and stays silent over oceans such as the Pacific; `Position` shows latitude, longitude, and elevation over land and ocean; `Full` is the default and shows country + position over land and position over ocean.
These settings live in browser local storage; switching browsers or clearing site data resets them.
### View Controls
| Action | Effect |
| --- | --- |
| Mouse drag | Rotate the globe |
| Single-finger drag | Touch rotate |
| Mouse wheel | Zoom in/out |
| Pinch | Touch zoom |
| Zoom button | Stepped zoom |
| Click zoom percentage | Reset to default zoom |
A small pill at the top briefly shows the current zoom while zooming. This is not a data loading indicator; if data is loading, the loading state takes precedence.
Drag sensitivity adjusts to zoom: near the default it is normal; zoomed in it is finer for targeted inspection; zoomed out it is slightly faster for global browsing.
### Motion Capture
Earth supports motion capture. Two live inputs:
- **Browser Camera** (default): uses `getUserMedia` in the page. No install needed but the page must run on HTTPS or localhost, and the user must grant camera permission
- **Motion Agent**: camera/RTSP/HTTP → local agent → local WebSocket → Earth. Used for dual cameras, USB index, phone/IP camera streams
Enable via the settings toggle "Motion Debug Mode", or with URL parameter `?motion=1`. Motion Agent defaults to `ws://127.0.0.1:8765/ws/gestures`; override with `motionAgent`. You can also pin the input with `?motion=1&motionProvider=browser` or `?motion=1&motionProvider=agent`.
Neither mode uploads camera frames or live gestures; neither reuses the news/RSS aggregation API.
Gesture semantics:
| Event | Effect |
| --- | --- |
| `rotate_left/right/up/down` | Rotate accordingly |
| `zoom_in/out` | Zoom |
| `focus_prev/next` | Cycle focusable targets within the current layer |
| `layer_prev/next` | Switch layer and pan to nearest target |
| `confirm` | Confirm the current selection |
In the debug panel: the browser camera input shows the live preview with skeleton overlay; Motion Agent sends only normalized skeleton events, never raw frames. "Skeleton Only" hides the video and keeps just the skeleton; "Stop Matching" pauses gesture firing while keeping preview and skeleton. Unmatched skeleton is red; matched turns green and shows the action name.
### Cruise Mode
Cruise mode auto-rotates focused targets. Current modules: BGP, news, compute centers, vessels, cables, satellites. Suitable for demos, control rooms, and unattended displays.
### Mobile
Mobile uses a drawer layout: layer control moves into a drawer; search/settings/details use mobile panels. Main interaction is still object tap, search, and layer toggles.
### Common Issues
- **Earth does not open**: confirm the frontend is online; if not on port `3000`, use the port printed by the startup log
- **Layers have no data**: open `/datasources` to check source status, collected-record state, and the latest run result; then `/data` or `/bgp` for records
- **Satellites / BGP / cables load slowly**: those layers depend on backend APIs and external data sources; the first load waits for startup tasks
- **Satellites are not all on one shell**: this is the default compressed real-altitude display. Disable "Real Satellite Altitude" in Settings to return to the legacy same-sphere view
## Docs Site
Docs at `http://localhost:3000/docs` are served by the backend with access control, not bundled into the frontend build.
Anonymous visitors see only `public` docs: README, Quickstart, Manual, FAQ, Earth Location Candidate Collection User Guide. Authenticated users with Gatekeeper groups see more:
- `docs_user`: end-user operational docs
- `docs_developer`: Earth, frontend, backend, collectors, AI Provider development docs
- `docs_admin`: service control, operations, environment variables, sensitive operations (including the Ops Runbook)
`admin` has `docs_admin` by default; `super_admin` has all docs permissions. Gatekeeper groups are managed at `/users`.
Docs supports: category navigation, Markdown rendering, tables and code blocks, in-doc table of contents, search across currently visible docs, internal links between technical docs.
## Related Docs
- [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md)
- [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
- [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
- [Earth Layer Style Reference](/home/ray/dev/linkong/planet/docs/technical/en/earth-layer-style-reference.md)
- [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md)
- [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md)
- [System Service Control](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
- [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
- [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md)
+60 -4
View File
@@ -22,10 +22,10 @@ image_exists AND stamp_non_empty AND fingerprint_match
### Fix
The stamp file moved to a persistent cache path:
The stamp file moved from a temporary location to a persistent cache path:
```bash
AI_PROVIDER_BUILD_STAMP_FILE="$HOME/.cache/planet/aiprovider_build.sha256"
AI_PROVIDER_BUILD_STAMP_FILE="${XDG_CACHE_HOME:-$HOME/.cache}/planet/aiprovider_build.sha256"
```
Writing the stamp creates the directory first:
@@ -92,7 +92,7 @@ COPY aiprovider /app/aiprovider
### Runtime Configuration
Before starting AI Provider, `planet.sh` generates a temporary env-file and passes it to Compose or the manual `docker run` fallback. Configuration priority:
Before starting AI Provider, `planet.sh` generates a current-user runtime env-file and passes it to Compose or the manual `docker run` fallback. The default path is `${XDG_STATE_HOME:-$HOME/.local/state}/planet/aiprovider_runtime.env`. Configuration priority:
1. `aiprovider/.env`
2. simple `export AI_...=...` or `AI_...=...` lines from `~/.zshrc`
@@ -177,7 +177,7 @@ Frontend startup now has an additional pre-start cleanup retry layer:
- `PORT_PRESTART_RETRIES`: defaults to 3 attempts.
- `PORT_PRESTART_RETRY_INTERVAL`: defaults to 2 seconds.
`kill_port_if_requested()` first cleans listener PIDs visible in the current environment. It only checks for Windows-side listeners when the script detects WSL, no local listener PID is visible, and the port still cannot bind. In that WSL-only path it tries to stop the owning Windows service or force-stop the owning process through PowerShell. If permissions are missing, or a system service such as `iphlpsvc` refuses to stop, the script prints the Windows listener details and stops startup immediately instead of launching the service into the same port error. Non-WSL environments do not run the Windows cleanup path. At that point, use Administrator PowerShell to clear the portproxy/service ownership, or choose another port.
`kill_port_if_requested()` first cleans listener PIDs visible in the current environment. It only checks for Windows-side listeners when the script detects WSL, no local listener PID is visible, and the port still cannot bind. In that WSL-only path it tries to stop the owning Windows service or force-stop the owning process through PowerShell. If permissions are missing, or a system service such as `iphlpsvc` refuses to stop, the script prints the Windows listener details and Administrator PowerShell recovery commands, then stops startup immediately instead of launching the service into the same port error. If the frontend Vite process only discovers `Port 3000 is already in use` after launch, the script prints the same Windows listener recovery commands. Non-WSL environments do not run the Windows cleanup path. On WSL, `--allow-lan` uses temporary Windows relays to expose `3000` / `8000`, so old persistent portproxy rules should be removed.
## Issue 4: `restart` Behavior
@@ -188,6 +188,62 @@ Before the stamp path fix:
After moving the stamp file, plain `restart` uses the same `stop + start` behavior and the same fingerprint check as `restart -b`.
## State Files, Logs, and Failed-Start Cleanup
`planet.sh` no longer writes PID files, logs, or runtime env-files to fixed `/tmp/planet_*` paths. The default state directory is:
```bash
${XDG_STATE_HOME:-$HOME/.local/state}/planet
```
At startup the script creates this directory and tries to set it to `700`. The current files include:
- `backend.pid` / `frontend.pid` / `motion_agent.pid`
- `backend.log` / `frontend.log` / `motion_agent.log`
- `aiprovider_build.log`
- `aiprovider_runtime.env`
- `ports.env`
PID writes validate that the PID is a positive integer, include a trailing newline, and try to set file mode `600`. PID reads ignore invalid content instead of passing it to `kill`.
After a successful `start`, the script records the ports in `ports.env`. Later `./planet.sh health` calls prefer the last started ports; if the state file is missing, health checks fall back to the defaults `8000`, `3000`, `8010`, and `8765`. This avoids checking default ports after starting with custom ports.
Startup now has light failed-start cleanup. If `start` exits before completing, the script only cleans local processes that this run already started: backend, frontend, and Motion Agent. It does not stop services after a successful start. AI Provider, PostgreSQL, and Redis keep their existing container lifecycle behavior.
## Health Checks and Hardening
HTTP readiness checks now use `curl -fsS --max-time`, so 4xx and 5xx responses are no longer treated as healthy.
Process termination now validates:
- signal names are limited to `TERM`, `KILL`, `INT`, and `HUP`;
- PIDs must be positive integers;
- process group IDs must be positive integers.
This prevents bad PID files or invalid signals from reaching `kill`.
Frontend and Motion Agent startup failures now call `print_port_listener_details()`, matching backend port diagnostics. The Windows-side listener and cleanup path still only runs when WSL is detected.
## Cross-Platform Notes
The script is currently Linux-first with WSL enhancements. Normal Linux runs do not execute the PowerShell path; WSL gets extra Windows listener, portproxy, and camera guidance.
To make this single script fully portable across Linux, macOS, and WSL, the remaining platform differences should be wrapped behind compatibility helpers:
- `stat --format`, `sort -V`, and `xargs -r` are GNU-style and are not fully compatible with default macOS BSD tools.
- `hostname -I`, `ss`, `fuser`, and `systemctl` are usually unavailable on macOS.
- `tac` may be missing on macOS; use `awk` or Python as a fallback.
- Docker Desktop on macOS does not use `systemctl` daemon diagnostics.
- Camera auto-detection relies on `/dev/video*` / `v4l2-ctl`, which is Linux-specific; macOS should use explicit camera URLs or a separate AVFoundation detector.
The recommended direction is a small platform compatibility layer for port listener detection, version comparison, file metadata, reverse tail, LAN IP discovery, and Docker daemon diagnostics, instead of scattering more platform branches throughout service startup logic.
## Production Delivery Boundary
`planet.sh` is a local development convenience script, not the production startup entrypoint. Production delivery should use Kubernetes `Deployment`, `Service`, `Ingress`, and readiness/liveness probes for ports, health checks, restarts, and rolling upgrades. This removes the need for a host script to reclaim local ports and avoids running the Vite dev server in production.
The production frontend shape is `vite build` static output served by nginx/Caddy or an equivalent HTTP server. Do not use `bun run dev` or `vite preview` in production. The project does not maintain a parallel Webpack build chain; if a future enterprise requirement needs closer Webpack-ecosystem compatibility, run an Rsbuild/Rspack spike first. Electron should only be evaluated when the official target becomes an offline desktop application.
## Optional Motion Agent Startup
`planet.sh` can now manage the local Motion Capture Agent. It is disabled by default so ordinary development machines do not fail startup when cameras, OpenCV, or MediaPipe are unavailable.
+246
View File
@@ -0,0 +1,246 @@
# Planet Ops Runbook
This runbook is for deployment, on-call, and maintenance engineers. End-user UI flows live in the [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md); this document only covers shell, Docker, logs, environment variables, and troubleshooting.
## First Startup
```bash
./planet.sh start
```
Default behavior:
- Starts PostgreSQL and Redis
- Starts AI Provider
- Starts the backend API
- Starts the frontend Vite dev server
- Prints Earth, console, Playground, and backend API doc URLs
First startup seeds two default accounts (see `DEFAULT_LOGIN_USERS` in `backend/app/db/session.py`):
| Username | Password | Role |
| --- | --- | --- |
| `admin` | `admin123` | `super_admin` |
| `linkong` | `12345678` | `super_admin` |
Both seed accounts are created with `email_verified = TRUE` and can log into the console immediately. Any other account must either go through the public registration flow described in the Manual, or be created via `./planet.sh createuser`.
Specify custom ports:
```bash
./planet.sh start -b 8001 -f 3001 -a 8101
```
| Flag | Meaning |
| --- | --- |
| `-b <port>` | Backend port |
| `-f <port>` | Frontend port |
| `-a <port>` | AI Provider port |
| `--allow-lan` | Enable LAN access |
| `--verbose` | Show extra command output |
## Stop and Per-Module Restart
Stop everything:
```bash
./planet.sh stop
```
Stops backend, AI Provider, frontend, PostgreSQL, Redis.
Per-module restart:
```bash
./planet.sh restart # full
./planet.sh restart -b # backend
./planet.sh restart -f # frontend
./planet.sh restart -a # AI Provider
./planet.sh restart -d # database
```
Per-module restart is preferred during development to avoid interrupting unrelated services.
## Health Check
```bash
./planet.sh health
```
Checks:
- `planet_*` container status
- Backend `/health`
- AI Provider `/health`
- Frontend reachability
If anything reports offline, check the corresponding logs first.
## Logs
Recent logs:
```bash
./planet.sh log
```
Follow:
```bash
./planet.sh log -f # frontend: /tmp/planet_frontend.log
./planet.sh log -b # backend: /tmp/planet_backend.log
./planet.sh log -a # AI Provider: planet_aiprovider container logs
```
## CLI User Creation
```bash
./planet.sh createuser
```
Interactively prompts for username, password, and role; writes the user with `email_verified = TRUE` directly.
Use when:
- SMTP is not yet configured but an admin account is needed now
- Pre-seeding internal test accounts
- Public registration is unavailable for any reason and a fallback is required
For ordinary user onboarding, configure SMTP at `/settings -> SMTP Email` first and let users self-register at `/register`.
## LAN / WSL Access
```bash
./planet.sh start --allow-lan
```
Useful for:
- Starting in WSL, accessing from Windows browser
- Demoing Earth from a phone or tablet
- Other LAN machines reaching the same dev instance
`--allow-lan` only makes the frontend and backend listen on `0.0.0.0`. When Planet runs in WSL, Windows can usually reach it through `localhost`, but other LAN machines reaching the Windows LAN IP still need Windows port forwarding and firewall rules.
Diagnose in this order:
```bash
# From the shell running Planet
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'
```
If WSL services are running but the LAN IP still fails, let `./planet.sh start --allow-lan` launch temporary Windows relays. The relays keep Windows exposed on `3000` / `8000` and exit automatically when the WSL target port goes away. The script checks stale `portproxy` rules and requests Administrator PowerShell to delete them, then checks Windows Firewall and triggers a UAC Administrator PowerShell request when inbound allow rules are missing. Manual fallback commands:
```powershell
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
LAN devices should use the Windows external port, for example `http://<Windows LAN IP>:3000/earth`.
## AI Provider Environment and Builds
AI Provider runtime configuration lives in two places:
| Location | Best for | Notes |
| --- | --- | --- |
| `aiprovider/.env` | Team-shared local defaults | Read by Docker Compose as `env_file` |
| `~/.zshrc` | Personal provider/model/key/proxy | `planet.sh` reads common `AI_*`, `SERVICE_*`, `PYTHON_IMAGE`, `UV_IMAGE` lines |
Recommended form:
```bash
export AI_PROVIDER=minimax
export AI_PROVIDER_API=anthropic-messages
export AI_BASE_URL=https://api.example.com/anthropic
export AI_API_KEY=sk-change-me
export AI_MODEL=MiniMax-M2.7
export AI_PROVIDER_SERVICE_TOKEN=change_me
```
By default `planet.sh` only statically parses simple `export KEY=value` lines from `~/.zshrc`. When complex shell expansion is required, opt in explicitly:
```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```
To ignore `~/.zshrc` entirely:
```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```
The AI Provider image only rebuilds when code, Dockerfile, Compose config, or Python dependencies change. After changing keys or base URL, restarting the container is enough:
```bash
./planet.sh restart -a
```
Diagnose slow builds:
| Symptom | Common cause | Fix |
| --- | --- | --- |
| Large `transferring context` | build context includes unrelated frontend / data files | `.dockerignore` ships only required files |
| `uv sync` is slow | first build or cold cache | wait for the first build; later runs reuse BuildKit cache |
| Old keys still in effect after edit | container not restarted | `./planet.sh restart -a` |
## SMTP Email (Required for Public Registration)
Public registration and email verification depend on SMTP. Administrators configure host, port, username, password, from-address, and TLS mode at `/settings -> SMTP Email` in the console, then use the "Send Test Email" button to verify. Settings are persisted in the `system_settings.smtp` row.
When SMTP is unset, `POST /api/v1/auth/register` returns `503 EMAIL_PROVIDER_NOT_CONFIGURED` and the frontend surfaces a clear error. The operational fallback is `./planet.sh createuser`.
One-time codes are stored in Redis under `otp:{purpose}:{email}` with a 600-second TTL. The key is invalidated after 5 invalid attempts. Resend cooldown is 60 seconds, enforced via `otp_rate:{purpose}:{email}`.
## Troubleshooting Order
```bash
./planet.sh health # 1. service state
./planet.sh log # 2. recent logs
./planet.sh log -f # 3. per-module logs
./planet.sh log -b
./planet.sh log -a
./planet.sh restart -f # 4. restart only the affected module
./planet.sh restart -b
./planet.sh restart -a
./planet.sh restart -d # 5. database / cache issues
./planet.sh restart # 6. full restart if still broken
```
## Development Command Conventions
Frontend must use Bun:
```bash
cd frontend
bun install
bun run dev
bun run build
```
Do not use `npm run ...`. In the WSL / Windows mixed environment Bun avoids Node/npm path inconsistencies.
Validate the frontend build:
```bash
source ~/.zshrc && bun run build
```
Backend dependencies are managed with uv:
```bash
uv sync
uv run pytest backend/tests/test_otp_service.py
```
## Related Docs
- [planet.sh Startup Mechanism](/home/ray/dev/linkong/planet/docs/technical/en/ops-planet-sh-startup.md)
- [System Service Control](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
- [Docker + Compose + Buildx Upgrade](/home/ray/dev/linkong/planet/docs/technical/en/ops-docker-compose-buildx-upgrade.md)
- [Data Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
+39 -209
View File
@@ -1,236 +1,66 @@
# Quickstart
This guide is for developers or demo operators starting Planet for the first time. The goal is to get services running via the shortest path and know which URLs to open.
This quickstart is for Planet end users who just received an access URL and need the shortest path from "open the browser" to "first useful configuration done". Every action happens in the browser.
If you run into port conflicts, Windows / WSL LAN access, `uv` / `bun`, camera, or Docs permission issues, start with the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md).
If you are responsible for deployment or operations, read the [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md) instead.
## Prerequisites
## 1. Open the URL
Recommended: run in a WSL / Linux shell.
Open the URL your administrator gave you, e.g. `http://planet.example.com`. A local demo is usually `http://localhost:3000`.
You need:
Entry points are split in two:
- Docker / Docker Compose available
- `uv` and `bun` accessible in the current shell
- Repository cloned locally
- Public: `/earth` (3D situational view), `/docs` (public documentation)
- Login required: `/admin` (console), `/ai` (AI), `/settings` (system configuration)
On a new machine, run the bootstrap script first:
## 2. Register
```bash
./scripts/bootstrap-dev.sh
```
1. Open `/login` and click "Register" under the form.
2. On `/register`, fill in username, email, password (≥ 8 characters).
3. After submission, check your inbox for a 6-digit verification code (valid for 10 minutes).
4. Enter the code on the verify page and click "Verify and Sign In". You are taken to the console automatically.
This script checks and syncs common dependencies, and generates if missing:
If the email does not arrive:
- `backend/.env`
- `aiprovider/.env`
- `frontend/.env.local`
- Check spam and your enterprise mail gateway
- The "Resend Code" button has a countdown; you can resend once it ends
- A "Email service not configured" message means your administrator has not yet set up SMTP — please ping them
Personal AI Provider configuration can also live in `~/.zshrc`. `planet.sh` reads simple `export AI_...=...` / `AI_...=...` lines and passes them to the AI Provider container. After changing model, key, or base URL, restart only AI Provider:
The default role is `viewer`: you can sign in but only see public pages. For collectors, user management, or system settings, ask the admin to promote your role or add Gatekeeper groups.
```bash
./planet.sh restart -a
```
## 3. First Sign-In Checklist
Collector credentials such as AISStream and BarentsWatch can also start in `~/.zshrc` for connectivity validation:
After landing on the `/admin` dashboard, here's a recommended walk-through:
```bash
export AISSTREAM_API_KEY="..."
export BARENTSWATCH_CLIENT_ID="..."
export BARENTSWATCH_CLIENT_SECRET="..."
```
1. `/settings?tab=collector_credentials`: pick a collector and click the plug icon to test connectivity. Free collectors (e.g. open BGP) usually work right away; credential-bearing ones like `AISStream` or `BarentsWatch` need an API key / client secret first
2. `/ai?tab=providers`: fill an LLM provider (e.g. `minimax` / `openai`), model, base URL, API key, and click the plug at the end of the base URL to test. WebSearch / OCR tools are optional
3. `/datasources` or `/data`: check whether collectors have produced data. Use `/datasources -> Collection Tasks` for finite collectors, and `/datasources -> Realtime Streams` for AISStream / WebSocket health and counters
4. `/alerts/system`: verify system alerts look right
5. `/users` (super_admin only): open accounts for teammates or adjust their groups
For actual collection, prefer saving credentials in `Settings -> Collector Settings`, especially for AISStream's long-lived WebSocket collector. That keeps connectivity validation, backend collection tasks, and Earth realtime vessel aggregation on the same configuration source.
## 4. Open Earth
## 1. Start Services
From the repository root:
```bash
./planet.sh start
```
After startup, the key URLs are:
| Entry | Default URL | Purpose |
| --- | --- | --- |
| Earth | `http://localhost:3000/earth` | Public 3D Earth visualization |
| Console | `http://localhost:3000/admin` | Admin console (login required) |
| Docs | `http://localhost:3000/docs` | Usage docs are public; developer and operations docs require Gatekeeper groups |
| AI | `http://localhost:3000/ai` | Model provider, tool, and testbench entry (login required) |
| Backend API Docs | `http://localhost:8000/docs` | FastAPI / OpenAPI interface docs |
If the default ports are taken, specify custom ports:
```bash
./planet.sh start -f 3001 -b 8001 -a 8101
```
If backend port `8000` is occupied by a Windows listener or an old portproxy rule, follow the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md) troubleshooting order.
## 2. Create a Login User
The console requires login. For first-time use:
```bash
./planet.sh createuser
```
Follow the prompts to enter username, password, and role.
To read developer or operations docs, log in as `super_admin` and assign Gatekeeper groups from the Users page. Use `docs_developer` for development docs and `docs_admin` for service-control and operations docs.
## 3. Open Earth
Visit:
```text
http://localhost:3000/earth
```
Earth is a public page — no login required.
Visit `/earth`. This is a public page — no login required.
Once in, verify:
- The globe renders correctly
- The right-side layer panel can toggle layers on/off
- Search can find cables, satellites, compute centers, BGP events
- Compute-center and BGP collector detail cards can collect and preview coordinate candidates; when regular sources have no candidate, the current default AI Provider runs one LLM factcheck fallback; the compute-center unresolved badge can open the queue and save candidates
- Mouse drag, wheel zoom, and zoom percent feedback work correctly
- Settings panel can switch rotate / cruise / motion mode, day/night mode, and satellite display style; Motion Debug Mode can show the local Browser Camera preview plus skeleton overlay
- The globe renders, and the right-side layer panel can toggle layers
- Search finds cables, satellites, compute centers, BGP events
- Compute-center and BGP collector detail cards can collect coordinate candidates and preview them on Earth
- Mouse drag, wheel zoom, and the zoom percentage indicator work
- The settings panel can switch rotate / cruise / motion modes; view settings can switch hover tooltip content, and satellite settings can toggle real-altitude layering and track display
## 4. Open the Console
## 5. Recover a Lost Password
Visit:
Open `/forgot-password`, enter your email, receive a code, then enter the code plus a new password. The same confirmation is shown for unknown emails (to avoid enumeration).
```text
http://localhost:3000/admin
```
## 6. Read the Docs
The console manages data sources, collected data, situational observation, alerts, system logs, and configuration.
First-time inspection checklist:
- `/datasources`: data source directory and collection triggers; endpoint, headers, and credentials are configured under `/settings` collector settings
- `/data`: collected data
- `/bgp`: BGP situational view
- `/ai`: AI page for model providers, WebSearch-style tools, and the testbench
- `/alerts/system`: system alerts
- `/settings`: system configuration
## 5. Check Service Health
```bash
./planet.sh health
```
This shows container status and checks:
- Backend
- AI Provider
- Frontend
## 6. View Logs
Recent logs:
```bash
./planet.sh log
```
Follow a specific service:
```bash
./planet.sh log -f
./planet.sh log -b
./planet.sh log -a
```
Flags:
- `-f`: frontend logs
- `-b`: backend logs
- `-a`: AI Provider logs
## 7. Common Restarts
Frontend only:
```bash
./planet.sh restart -f
```
Backend only:
```bash
./planet.sh restart -b
```
AI Provider only:
```bash
./planet.sh restart -a
```
Database only:
```bash
./planet.sh restart -d
```
Full restart:
```bash
./planet.sh restart
```
## 8. LAN Access
To allow a Windows browser, phone, or another device on the same network:
```bash
./planet.sh start --allow-lan
```
This makes the frontend and backend listen on a LAN-accessible address.
Note: `--allow-lan` only makes Planet listen on `0.0.0.0`; it does not automatically expose WSL services through the Windows LAN IP. A common pattern is:
- `localhost:3000` / `localhost:8000` works inside WSL
- `localhost:3000` / `localhost:8000` works on Windows
- `http://<Windows LAN IP>:3000` fails from a phone or another computer
That usually means Windows still needs port forwarding or firewall rules.
If access fails, check from the shell running Planet:
```bash
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'
```
If WSL is listening on `0.0.0.0:3000` and `0.0.0.0:8000` but the LAN IP still fails, configure Windows forwarding and firewall rules from an elevated PowerShell:
```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
## 9. Stop Services
```bash
./planet.sh stop
```
This shuts down the frontend, backend, AI Provider, PostgreSQL, and Redis.
`/docs` is the docs site. Without login you can read: this Quickstart, the Manual, the FAQ. Authenticated users with `docs_user` / `docs_developer` / `docs_admin` groups see additional technical documents.
## Next Steps
- Full usage guide: [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md)
- Console structure: [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
- Earth structure: [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
- Backend collectors: [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
- Full UI walkthrough: [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md)
- Troubleshooting and configuration questions: [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md)
- Detailed Earth coordinate candidate flow: [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md)
- Deployment / operations commands: [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md)
+56 -4
View File
@@ -326,6 +326,17 @@ AISStream 使用 `wss://stream.aisstream.io/v0/stream` WebSocket endpoint。默
AISStream 连接验证会通过 `datasource_connectivity.py` 读取保存的采集器配置、环境变量和 `~/.zshrc` 中的 `AISSTREAM_API_KEY`。正式采集时,最稳妥的方式是把 API Key 保存到“设置 -> 采集器设置 -> AISStream 实时船舶”;如果只放在 `~/.zshrc`,需要确认后端进程实际继承到了该环境变量。
控制台通过 `/datasources -> 实时流` 管理 AISStream,而不是把它放进普通有限采集任务的进度条。实时流 API 会聚合运行态、健康状态、配置摘要和 raw observation 计数:
```http
GET /api/v1/realtime-sources
POST /api/v1/realtime-sources/{source}/start
POST /api/v1/realtime-sources/{source}/stop
POST /api/v1/realtime-sources/{source}/restart
```
`aisstream_vessels` 和自定义 `source_type=websocket` 数据源会出现在该接口中。它们不参与一键采集百分比;前端按长连接服务展示消息计数、延迟、最近成功和最近错误。
### AIS 原始观测与聚合
AIS 观测写入后不会直接替换最终船只记录,而是先保存为 raw observation:
@@ -336,17 +347,50 @@ AIS 观测写入后不会直接替换最终船只记录,而是先保存为 raw
- 位置、速度、航向等动态字段会按 freshness 和来源优先级选择。
- 静态字段优先保留非空值;冲突候选会记录到详情接口,便于排查多源差异。
Earth 使用的接口仍是:
Earth 船只展示现在使用受控快照接口和实时增量通道:
```http
GET /api/v1/visualization/geo/vessels
GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/visualization/vessels/{mmsi}
GET /api/v1/visualization/vessels/{mmsi}/track
GET /api/v1/visualization/vessels/{mmsi}/conflicts
GET /api/v1/visualization/vessels/aggregation/diagnostics
```
`/geo/vessels` 会合并 raw observation 聚合结果和 legacy BarentsWatch latest position 结果,避免只接入 AISStream 后把历史 BarentsWatch 船只遮蔽掉。
`/api/v1/vessels/snapshot` 必须携带 `bbox` 和 `zoom`,默认 `limit=1000`,最大 `limit=5000`。它优先消费 `ais_raw_observations` 聚合结果;当当前 raw 窗口为空时,会受控回退到 legacy `vessel_position` / `vessel_static` 最新点,并在 `diagnostics.legacy_fallback_used` 中标明。旧 `/api/v1/visualization/geo/vessels` 路由已移除。
实时增量通过 `/ws` 的 `vessels` channel 推送。客户端订阅时必须带当前视口:
```json
{
"type": "subscribe",
"data": {
"channel": "vessels",
"bbox": [120.8, 30.7, 122.1, 31.8],
"zoom": 12,
"limit": 1000
}
}
```
后端按连接保存轻量订阅条件,只向 bbox 命中的连接发送船只更新。collector 广播会先进入 1 秒节流队列,同一 MMSI 在一个 flush 周期内只保留最新位置,避免高频实时流拖垮 WebSocket。
### 图层接口与全量统计分离
Earth 后续迁移到两类接口:
```http
GET /api/v1/data-products
GET /api/v1/data-products/{product_id}/status
GET /api/v1/layers/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/cables?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/landing-points?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/satellites?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/bgp/anomalies?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/bgp/incidents?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
GET /api/v1/layers/bgp/collectors?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
```
`/api/v1/data-products/*` 面向聚合面板,统计口径是全量/全局,不受地图 bbox 影响。`/api/v1/layers/*` 面向地图渲染,必须携带 `bbox` 和 `zoom`,默认 `limit=1000`,最大 `limit=5000`;低 zoom 会降级到更小的返回上限,并在 `diagnostics` 中暴露 `degraded`、`truncated`、`limit_clamped` 和 `stats_scope=viewport`。当前版本的非船只图层先复用已有 GeoJSON 转换再做保护层,后续可继续把 bbox 下推到各产品专用查询。
## 十、采集器设置与连接验证
@@ -418,4 +462,12 @@ curl -X POST http://localhost:8000/api/v1/datasources/1/trigger \
-H "Authorization: Bearer <token>"
```
批量采集使用:
```http
POST /api/v1/datasources/trigger-batch
```
请求体可以传 `source_ids` 精确触发选中项;如果不传 `source_ids`,后端按 `product`、`module`、`is_active`、`run_status`、`collected`、`credential_status` 和 `q` 过滤后触发。接口会跳过禁用源、正在运行且未 `force` 的源,以及未到频率窗口的源,并返回 `triggered`、`skipped`、`failed` 三组结果。
**核心文件**: `backend/app/api/v1/datasources.py`
@@ -290,6 +290,16 @@ AISStream 使用 WebSocket 实时流,采集器只写入 `ais_raw_observations`
连接验证会读取保存配置、环境变量和 `~/.zshrc` 中的 `AISSTREAM_API_KEY`。正式采集时,推荐把 API Key 保存到采集器设置;如果只写在 `~/.zshrc`,需要确认后端进程实际继承了该变量,否则连接验证可能可用但 collector 运行时拿不到 key。
连接验证和正式采集是两个不同动作。设置页出现 `AISStream 凭证已配置,WebSocket endpoint 格式有效` 只说明配置可以用于连接;运行状态仍可能是 `disconnected`。只有 `aisstream_vessels` 处于 `streaming` / `connected`,并且实时流计数、`last_seen_at` 持续更新时,全球 AIS 数据才会不断写入本地库。启动、停止、重连、健康状态和计数统一从 `/datasources -> 实时流` 和 `/api/v1/realtime-sources` 查看;AISStream 不再参与普通一键采集进度。
新版本不再使用 legacy `/api/v1/visualization/geo/vessels` 作为船只列表入口。Earth 初始状态应调用:
```http
GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
```
该接口优先查询本地 `ais_raw_observations` 聚合结果;当当前 raw 窗口为空时,会受控回退到 legacy `vessel_position` / `vessel_static` 最新点,并通过 `diagnostics.legacy_fallback_used` 暴露。实时更新走 `/ws` 的 `vessels` channel,订阅时必须提供 `bbox`、`zoom` 和 `limit`。服务端按连接过滤 bbox,并对 collector 广播做 1 秒合并,同一 MMSI 只推送最新位置。
## 自定义 REST / WebSocket 映射运行时
文件:
+1
View File
@@ -157,6 +157,7 @@ BGP 模块正在从一个只展示异常的演示功能,演进为分层观测
- 由符号驱动的事件核心
- 向外扩散的环形脉冲
- 相比旧版 Earth 更少的弥散 glow
- 事件区域 halo、collector coverage halo 和雷达 pulse 从各自图标色派生浅色调,而不是使用固定青绿色;红色高危事件、橙色活跃 collector 和蓝色 idle collector 保持各自色相一致,面状光晕则比图标更轻
7. 右侧统计现在显示:
- BGP events
- collector count
+16 -3
View File
@@ -286,8 +286,9 @@ AIS 船只图层入口:
船只图层当前负责:
- 请求 `/api/v1/visualization/geo/vessels`
- 将聚合后的 AIS GeoJSON 转为地球局部坐标 marker 数据;请求默认不传 `limit`,后端和前端都不再默认裁剪到 5000 艘
- 请求 `/api/v1/vessels/snapshot` 获取当前视口初始快照;请求必须携带 `bbox`、`zoom`,并传入受控 `limit`
- 通过 `/ws` 的 `vessels` channel 订阅后续增量;订阅 payload 同样必须携带当前视口 `bbox`、`zoom`、`limit`
- 将聚合后的 AIS GeoJSON 转为地球局部坐标 marker 数据;后端默认 `limit=1000`,最大 `limit=5000`
- 通过 `createInteractableLayer()` 注册 Interactable 图标层
- 用按航向分桶的 `THREE.Points` 批量渲染普通船只 marker
- 按船型映射颜色;`vessels.js` 会用 `vessel_type_name` 和 AIS `vessel_type` 数字共同归一化船型
@@ -310,6 +311,10 @@ AIS 船只图层入口:
AISStream 的 `PositionReport` 常带实时位置和 `MetaData.ShipName`,但船型通常来自低频 `ShipStaticData.Type`。后端会把 `MetaData.ShipName` 补进船名,并将类型码映射为 Cargo / Tanker / Passenger / Fishing / Military;仍缺失的船型需要等待静态 AIS 消息或后续船舶资料 enrichment,不能在前端凭颜色之外的信息臆造细分类。
旧 `/api/v1/visualization/geo/vessels` 路由已移除。前端打开船只图层时应先按当前视口拉一次 `/api/v1/vessels/snapshot`,再用 WebSocket 接收同一视口内的 upsert 增量;地图拖动或缩放后应重新拉取 snapshot 并重发 vessels 订阅。后端只在当前 raw 窗口为空时受控回退到 legacy `vessel_position` / `vessel_static`,前端可通过 `diagnostics.legacy_fallback_used` 识别该状态。
新的图层接口族是 `/api/v1/layers/*`,用于把地图渲染数据和聚合面板统计分开。地图层请求必须带 `bbox`、`zoom` 和受控 `limit`,响应会返回 `visible_count`、`returned_count` 和 `diagnostics`,其中 `degraded/truncated/limit_clamped` 用于前端提示降级。右侧聚合统计不要从图层响应累加,应读取 `/api/v1/data-products` 或 `/api/v1/data-products/{product_id}/status`,因为这些统计保持全量/全局口径,不随当前视口变化。
船只 hover / click 也不再对渲染对象做 `raycaster.intersectObjects()`。`main.js` 只负责传入当前 Earth、camera、pointer 和命中半径,实际命中计算由 `interactable.js` 的图标层接口完成:
1. 拖动地球或惯性旋转时跳过 hover picking。
@@ -414,11 +419,19 @@ Earth 设置面板当前由 [controls.js](/home/ray/dev/linkong/planet/frontend/
- 旋转模式
- 地球默认大小(作为重置视角、缩放重置和巡航视图的默认 zoom 真源)
- HUD 面板显示/隐藏
- 图层控制开关:`地形 / 卫星 / 轨迹 / 海缆 / BGP`
- 图层控制开关:`地形 / 卫星 / 海缆 / BGP`
- 卫星显示偏好:`卫星显示风格 / 卫星呼吸闪烁 / 真实卫星高度 / 轨迹显示`
- 地表 hover 提示偏好:`国家 / 位置 / 完整`
- 地形透明度
也就是说,Earth 设置不是一次性 UI 状态了,而是本地设备级偏好。后续如果再加入新的设置项,应优先接入同一条持久化链,而不是各自散着写 `localStorage`。
地表 hover 提示由 `controls.js` 持久化为 `shared.surfaceHoverInfoMode`,实际 tooltip 在 `main.js` 的地表 hover 分支组合。`国家` 模式只在命中国家时显示国家信息,海洋区域不显示地表 tooltip;`位置` 模式只显示纬度、经度和地形采样海拔,并清除国家边界 hover;`完整` 模式在陆地显示国家 + 位置,在海洋显示位置。
卫星真实高度开关由 `controls.js` 持久化,实际渲染状态在 `satellites.js`。开启时,SGP4 得到的真实半径会按对数压缩到当前 Earth 视觉半径范围;关闭时,卫星点、轨迹和预测轨道都回到旧版同层球面。切换时必须刷新卫星位置并清理轨迹缓存,避免同一条轨迹混入两个高度模型。`maxRealAltitudeOffset = 25` 是当前相机和 `earthRadius = 100` 下的视觉上限:它让 GEO / MEO 比 LEO 明显更高,但把最高轨道控制在地球半径外约 25%,避免选择点、红色轨迹和主体地球之间出现过大的空场。
SGP4 传播输出是惯性系位置,不能直接当成 Earth 的经纬度固定坐标使用。`satellites.js` 会用当前时间的 `gstime` 把 ECI/TEME 位置转换到 ECF,再映射到 `latLonToVector3()` 使用的 Three.js 坐标轴。卫星点和短尾迹使用随采样时间变化的地固坐标,表示相对当前地球表面的实际位置;锁定后的预测轨道线使用锁定时刻固定的 `gstime`,把未来一圈惯性轨道投到当前地球姿态上显示,因此会闭合,并且轨道面倾角应与详情卡一致。fallback 预测轨道也必须使用真正的 RAAN + inclination 轨道平面公式,不能把 inclination 当成恒定纬度。
## 当前地形链路
真实地形首次启用会慢,原因不只是一个:
@@ -166,10 +166,13 @@
| 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 |
| --- | --- | --- | --- |
| 卫星显示半径偏移 | `SATELLITE_CONFIG.displayAltitudeOffset` | `8` | 卫星点位置 |
| 卫星 fallback 半径偏移 | `SATELLITE_CONFIG.fallbackAltitudeOffset` | `8` | 关闭真实高度或 TLE 传播失败时的旧版同层球面位置 |
| 卫星真实高度压缩尺度 | `SATELLITE_CONFIG.altitudeCompressionKm` | `1200` | TLE/SGP4 高度压缩映射,数值越大高轨差异越温和 |
| 卫星真实高度上限 | `SATELLITE_CONFIG.maxDisplayAltitudeKm` | `40000` | 压缩映射的高度截断,覆盖 GEO 附近高度 |
| 卫星真实高度显示偏移范围 | `minRealAltitudeOffset / maxRealAltitudeOffset` | `4 / 25` | 压缩后映射到 `CONFIG.earthRadius + offset`;`25` 约为当前地球半径 `100` 的四分之一,用于保留高轨分层同时避免 GEO/MEO 轨迹离主体过远 |
| 卫星点基础像素大小 | `SATELLITE_CONFIG.dotBaseSize` | `2.8` | 点 shader size |
| 卫星背景点缩放 | `SATELLITE_CONFIG.dotBackdropScale` | `1.28` | 背景点大小 |
| 卫星点透明度范围 | `dotOpacityMin / dotOpacityMax` | `0.7 / 1.0` | 呼吸动画 |
| 卫星点透明度范围 | `dotOpacityMin / dotOpacityMax` | `0.42 / 1.0` | 呼吸动画 |
| 卫星点呼吸速度 | `SATELLITE_CONFIG.dotBreathingSpeed` | `0.12` | 点 opacity 动画 |
| 卫星背景点颜色 | inline | `0x0b1626` | backdrop point baseColor |
| 卫星背景点透明度 | inline | `0.42` | backdrop point opacity |
@@ -249,7 +252,9 @@ AIS 船只普通态使用批量 `THREE.Points`,不是逐船 `THREE.Sprite`。
| medium 颜色 | `BGP_CONFIG.severityColors.medium` | `0xffd166` | 中危事件 |
| low 颜色 | `BGP_CONFIG.severityColors.low` | `0x4dabf7` | 低危事件 |
| collector 基础色 | `BGP_CONFIG.collectorColor` | `0x6db7ff` | collector 默认色 |
| region 色 | `BGP_CONFIG.regionColor` | `0x2dd4bf` | 区域覆盖 |
| BGP 光晕浅色基准 | `BGP_CONFIG.halo.tintNeutralColor` | `0xffffff` | 面状 halo 先取对应事件/collector 图标色,再向该中性色混合,保持同色调但不完全同色 |
| BGP 光晕图标色混合比例 | `BGP_CONFIG.halo.tintBlend` | `0.72` | 值越高越接近图标色;当前用于事件区域 halo、collector coverage halo 和 collector radar pulse |
| region 色 | `BGP_CONFIG.regionColor` | `0x2dd4bf` | 区域覆盖旧基准;新的面状 BGP halo 优先从事件或 collector 图标色派生 |
| BGP ring 缩放 | `BGP_CONFIG.ring.scaleA / scaleB` | `2.5 / 3.4` | anomaly ring |
| BGP ring 透明度 | `BGP_CONFIG.ring.opacity` | `0.5` | anomaly ring |
| collector marker renderOrder | local `BGP_COLLECTOR_RENDER_ORDER` | `4.4` | 观测站主图标,与船只同层 |
@@ -7,7 +7,7 @@
| 顺序类型 | 当前顺序 | 说明 |
| --- | --- | --- |
| 控制面板顺序 | 海缆 → 轨迹 → 卫星 → 算力中心 → 船只 → BGP → 地形 → 高清材质 → 大气云图 → 国界线 → 经纬线 | 由 `displayOrder` 控制,按操作关注度排列。 |
| 控制面板顺序 | 海缆 → 卫星 → 算力中心 → 船只 → BGP → 地形 → 高清材质 → 大气云图 → 国界线 → 经纬线 | 由 `displayOrder` 控制,按操作关注度排列;卫星轨迹已迁到设置面板,不再作为图层列表项。 |
| 注册 / 启动加载顺序 | 经纬线 → 国界线 / 海陆基座 → 高清材质 → 大气云图 → 海缆 → 算力中心 → 船只 → BGP → 卫星 | 由注册顺序和 `startupPriority` 控制,按地表到天空排列;启动队列会先读取保存的图层可见状态,明确关闭的普通图层不预加载,高清材质关闭时不下载贴图;国界线图层例外,海陆基座始终预加载,保存状态只控制可交互国界线和 hover;轨迹和地形是依赖/可选显示层,不参与常规启动数据加载。 |
## 地表图层栈
@@ -32,9 +32,9 @@
| 4.3 | AIS 船只轨迹线 | `vessels.js` | `VESSEL_RENDER_ORDER - 0.1`;`CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset` | 跟随船只显隐,不单独参与拾取 | 选中船只后显示最近轨迹,低于船只 marker。 |
| 4.4 | AIS 船只 marker | `vessels.js`, `interactable.js` | `VESSEL_RENDER_ORDER`;业务高度为 `CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset`;普通 marker 为分桶 `THREE.Points`,hover / locked 为单点 `THREE.Points` overlay | `depthTest: true`;`main.js` 使用屏幕空间 picking,只取正面 marker;参与 Interactable 同坐标避让 | 航行船只用三角点纹理,停泊/低速用圆点;普通态无 glow,交互态叠加同尺寸 glow;低于算力中心 `4.5`。 |
| 4.5 | 算力中心 | `compute-centers.js`, `interactable.js` | 使用 `COMPUTE_CENTER_RENDER_ORDER` 并由 `Interactable` 绘制 | 通过 `Interactable` 屏幕空间 picking,参与同坐标避让 | 地表设施层,保持在卫星下方。登陆点已下沉到海缆层。 |
| 5 | 卫星背景点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 位于卫星点下方。 |
| 6 | 卫星点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
| 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 |
| 5 | 卫星背景点 | `satellites.js` | 固定 renderOrder;默认按 TLE/SGP4 真实高度压缩到 `CONFIG.earthRadius + 4..25`,关闭真实高度或传播失败时回退到 `fallbackAltitudeOffset = 8` | 屏幕空间卫星拾取 | 位于卫星点下方。 |
| 6 | 卫星点 | `satellites.js` | 与卫星背景点使用同一压缩高度 / fallback 高度 | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
| 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移;预测轨道使用同一真实高度开关,并固定锁定时刻的地球姿态来绘制闭合惯性轨道;关闭真实高度时回到同层球面 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 |
| 98-100 | 太阳 / 月亮 halo 和 sprite | `celestial.js` | 固定 renderOrder | 天体拾取禁用 | 前景天体 sprite。 |
## 开关联动
@@ -46,6 +46,7 @@
| 地形 on | 显示在高清材质之上,但低于国界 hover、footprint、卫星等强调层。 |
| 大气云图 | 只控制云图 mesh 显隐。 |
| 国界线 off | 只隐藏可交互国界线和 hover,高亮状态会清除;海陆基座填充仍作为 Earth 底图保留。 |
| 真实卫星高度 off | 卫星点、轨迹和预测轨道都使用旧版同层球面;缺失 TLE 或传播失败的卫星也使用同一 fallback 高度。 |
## 交互规则
+17 -6
View File
@@ -55,12 +55,12 @@ tasklist /svc /fi "PID eq 4700"
临时排障可以在管理员 PowerShell 中停止 IP Helper:
```powershell
Stop-Service iphlpsvc
Stop-Service iphlpsvc -Force
```
这可能影响部分网络、代理或转发能力。长期不推荐禁用该服务;如果必须保留 Windows 转发,改用不同后端端口更稳。
这可能影响部分网络、代理或转发能力。长期不推荐禁用该服务;新版本 `--allow-lan` 会用临时 Windows relay 暴露 `3000` / `8000`,不再需要保留持久 portproxy。
如果脚本输出 `failed-stop-service` 或 `failed-stop-process`,说明当前权限无法清理 Windows listener。脚本会停止启动,避免后端再次遇到同一端口冲突。
如果脚本输出 `failed-stop-service`、`failed-stop-process`,或 Vite 报 `Port 3000 is already in use` 后显示 `Windows listener ... services=iphlpsvc`,说明旧的 Windows listener 仍在占用端口。脚本会停止启动,并提示用管理员 PowerShell 检查 `netsh interface portproxy show all`,删除对应 `listenport` 规则;如果没有 portproxy 规则,再用 `netstat` / `tasklist` 确认服务,必要时临时 `Stop-Service iphlpsvc -Force`。清理旧规则后重新运行 `./planet.sh restart --allow-lan`,脚本会启动临时 relay,局域网仍访问 `3000` / `8000`。
### 默认端口冲突时应该改哪些参数?
@@ -112,15 +112,18 @@ curl http://localhost:8000/health
如果 `ss -ltnp` 显示前端已经监听 `0.0.0.0:3000`,但 Windows PowerShell 中 `Test-NetConnection <Windows局域网IP> -Port 3000` 仍失败,问题通常不在 Vite 或 `.zshrc`,而是在 Windows 侧转发或防火墙。
传统 WSL NAT 场景下,管理员 PowerShell 中配置 portproxy 和防火墙:
传统 WSL NAT 场景下,`./planet.sh start --allow-lan` 会启动临时 Windows relay,让 Windows 对外仍使用 `3000` / `8000`。脚本会在启动前检测并请求管理员 PowerShell 删除旧 `portproxy`,也会检测 Windows 防火墙规则;如果缺少 `3000` / `8000` 入站放行,会触发一次 UAC 管理员 PowerShell 请求来自动创建。若自动请求被取消,可以手动清理:
```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
局域网设备访问 Windows 对外端口,例如 `http://<Windows局域网IP>:3000/earth`。
如果 `wslinfo --networking-mode` 输出 `mirrored`,还需要检查 Hyper-V firewall。普通 Windows 防火墙规则存在时,Hyper-V firewall 仍可能拦截外部设备进入 WSL。管理员 PowerShell 中按端口放行:
```powershell
@@ -323,6 +326,14 @@ Docs 按 Gatekeeper 权限组控制可见性:
算力中心候选保存后会写入 `compute_center_locations`。没有可用候选的记录会保留在待定位列表中,系统不会用国家中心点或硬编码 hint 伪造位置。
### 为什么卫星看起来不在同一个球面上?
Earth 默认开启“真实卫星高度”。卫星位置仍来自 TLE/SGP4,但高度会经过压缩映射:低轨卫星靠近地球,高轨卫星更远,同时保持在当前视图可读范围内。最高显示偏移使用 `25`,约等于当前地球显示半径的四分之一;这是视觉上区分 GEO / MEO / LEO 和保持镜头可读性的折中,不是把真实公里数按比例直接画出来。这个设置也会影响卫星轨迹和锁定后的预测轨道。
如果需要旧版所有卫星位于同一显示球面的效果,在 Earth 设置里关闭“真实卫星高度”。缺失 TLE 或传播失败的卫星仍会回退到旧版固定高度,不会因为无法计算真实高度而消失。
低倾角高轨卫星应该沿赤道附近或固定经度附近分布,而不是绕出接近南北向的大圈。Earth 会先把 SGP4 的惯性系位置转换成地固坐标再绘制当前点;锁定后的预测轨道则固定当前地球姿态来画一圈惯性轨道,所以应该闭合并保留正确倾角。如果以后看到详情卡倾角接近 `0°`,但预测轨道像极轨一样竖着绕,优先检查 ECI/TEME 到 ECF 的转换和预测轨道是否错误使用了逐采样 `gstime`。
### 动捕调试面板为什么看不到摄像头画面?
如果输入源是 Browser Camera,调试面板会显示浏览器本机摄像头实时预览,并在画面上绘制骨架。如果勾选了 `只显示骨骼`,视频预览会被隐藏,只显示深色背景和红/绿骨架。
@@ -163,7 +163,25 @@
- 文档内部链接应通过 `transformLink` 转成 `/docs/:slug`
- 标题锚点由 `getHeadingId` 注入,避免渲染器自己理解路由状态
### 6. `TableActions`
### 6. `ConnectionTestInput`
文件:
- [ConnectionTestInput.tsx](/home/ray/dev/linkong/planet/frontend/src/components/ConnectionTestInput/ConnectionTestInput.tsx)
用途:
- Endpoint、Base URL 这类“输入值 + 连接验证”的控制台表单项
- AI Provider 和 WebSearch 的连接测试入口
- 后续采集器配置如果把连接测试放进输入框,也应复用它
当前约束:
- 输入框末端只显示一个插头/连接器图标,不再并排放“测试连接”文字按钮
- 禁用的集成能力必须同时置灰输入框和连接测试按钮
- 组件只负责输入框与测试入口组合,不保存业务状态;调用方仍负责表单值、loading、disabled 和连接请求
### 7. `TableActions`
文件:
@@ -205,10 +223,13 @@
职责:
- `/ai` 独立承载 LLM Provider、AI Tool 配置和测试台,不再放在 `/settings` 的系统配置 tabs 中
- `模型供应商` tab 管理默认 provider、模型、base URL、provider key、本地 `aiprovider` 代理和连接测试
- `工具` tab 管理 WebSearch provider、搜索 key、base URL、超时、结果数和高级 provider 参数
- `模型供应商` tab 管理默认 provider、模型、base URL、provider key、本地 `aiprovider` 代理和连接测试;provider 和模型输入使用可输入组合框,models.dev 目录停更时用户仍可手动填新 provider/model
- `工具` tab 先通过下拉菜单选择工具,再管理对应配置;当前包含 WebSearch 和 OCR
- WebSearch 配置包含 provider、搜索 key、base URL、超时、结果数和高级 provider 参数
- OCR 配置包含 provider、Base URL、API Key、模型/engine、语言、超时、文件大小上限和输出格式
- `测试台` tab 嵌入原 Playground 的真实会话、预设请求和 AI Provider 状态调试
- 页面复用 Settings 的单屏 tabs、panel card 和内部滚动样式
- AI Provider / WebSearch 的连接测试使用 `ConnectionTestInput`,连接器图标固定在 Base URL 输入框末端;WebSearch 未启用时,除开关外的配置项和测试入口都置灰
旧的 `/settings?tab=ai` 应跳转到 `/ai?tab=providers`。
旧的 `/playground` 应跳转到 `/ai?tab=playground`。
+241 -611
View File
@@ -1,543 +1,92 @@
# Planet 使用手册
这份手册面向日常使用、演示、开发联调和本地运维。它覆盖四个核心入口:
这份手册面向 Planet 的最终用户。从打开浏览器开始,覆盖注册账号、登录、配置数据采集器、配置 AI、使用 Earth 和控制台、阅读文档站。所有操作都在浏览器里完成。
- `planet.sh`:本地启动、停止、重启、健康检查和日志入口
- Earth:公开 3D 地球态势页面
- 控制台:登录后的管理后台
- Docs:后端 Gatekeeper 受控的文档站,基础使用文档公开,开发/运维文档按权限组开放
快速启动路径见 [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)。常见排障见 [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)。
如果你是负责部署或值班的运维,请改读 [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md),里面是 shell 命令、日志位置、SMTP 兜底创建用户等内容。
## 入口总览
默认启动后,常用地址如下:
| 名称 | 地址 | 是否需要登录 | 说明 |
| --- | --- | --- | --- |
| Earth | `http://localhost:3000/earth` | 否 | 3D 地球、图层、BGP、卫星、海缆、新闻态势 |
| Docs | `http://localhost:3000/docs` | 部分需要 | 使用手册公开;开发、后端、运维文档按 Gatekeeper 权限组开放 |
| FAQ | `http://localhost:3000/docs/faq` | 否 | Windows / WSL、端口、依赖、动捕、凭证和权限排障 |
| 控制台 | `http://localhost:3000/admin` | 是 | 数据、配置、告警、日志和专题观测 |
| AI | `http://localhost:3000/ai` | 是 | 模型供应商、AI 工具和测试台 |
| 后端 API 文档 | `http://localhost:8000/docs` | 视接口而定 | FastAPI / OpenAPI 文档 |
| Earth | `http://<域名>/earth` | 否 | 公开 3D 地球态势页面 |
| Docs | `http://<域名>/docs` | 部分需要 | 公共文档免登录,开发/运维文档按 Gatekeeper 权限组开放 |
| 注册 / 登录 / 找回密码 | `/register`、`/login`、`/forgot-password` | 否 | 自助开通和恢复账号 |
| 控制台 | `http://<域名>/admin` | 是 | 数据、采集器、告警、AI、用户、设置 |
| AI | `http://<域名>/ai` | 是 | 模型供应商、工具和测试台 |
| 后端 API 文档 | `http://<域名>:8000/docs` | 视接口而定 | FastAPI / OpenAPI |
## planet.sh
下面所有 URL 都基于本机演示的默认地址 `http://localhost:3000`,部署到正式环境时把前缀换成你们的访问域名即可。
`planet.sh` 是本地开发和演示的主控脚本。优先使用它管理服务,而不是手动分别启动前端、后端、数据库和 AI Provider。
## 注册账号
### 启动
1. 打开 `http://localhost:3000/login`,点击表单下方"注册账户"。
2. 在 `/register` 填写:
- **用户名**:3–50 位字符,登录时使用
- **邮箱**:用于接收验证码,可在账户设置中修改
- **密码**:至少 8 位
3. 提交后会跳到验证页,已将 6 位验证码发到你的邮箱。10 分钟内有效。
4. 输入验证码,点击"验证并登录"。验证通过后系统会自动写入登录态并跳到控制台。
```bash
./planet.sh start
```
如果 60 秒内没收到邮件:
默认行为:
- 检查垃圾邮件、订阅推广、企业邮件网关
- 验证页右下角的"重新发送验证码"会显示 60 秒倒计时,倒计时结束后可重发
- 连续输错 5 次后该验证码会失效,需要重发新码
- 启动 PostgreSQL 和 Redis
- 启动 AI Provider
- 启动后端 API
- 启动前端 Vite dev server
- 输出 Earth、控制台、Playground 和后端 API 文档入口
如果系统提示"邮件服务尚未配置",说明管理员还没填 SMTP,请联系管理员开通 SMTP 或在控制台 `/settings -> SMTP 邮件` 完成配置。
可指定端口:
默认注册角色为 `viewer`,可以登录控制台浏览公共内容。要看采集器、用户管理、系统设置等管理类页面,需要 `admin` 或 `super_admin` 在 `/users` 给你升角色。
```bash
./planet.sh start -b 8001 -f 3001 -a 8101
```
## 登录与找回密码
参数含义:
### 登录
| 参数 | 含义 |
| --- | --- |
| `-b <port>` | 后端端口 |
| `-f <port>` | 前端端口 |
| `-a <port>` | AI Provider 端口 |
| `--allow-lan` | 允许局域网访问 |
| `--verbose` | 在执行过程中显示更多命令输出 |
打开 `/login`,输入用户名和密码即可。登录成功后跳到 `/admin`。
### AI Provider 环境变量和构建
如果提示"邮箱未验证",页面会自动跳到 `/verify-email`,按提示输入验证码完成验证。
AI Provider 的运行期配置可以放在两处:
### 忘记密码
| 位置 | 适合内容 | 说明 |
| --- | --- | --- |
| `aiprovider/.env` | 团队约定的本地默认配置 | Docker Compose 会作为 `env_file` 读取 |
| `~/.zshrc` | 个人机器上的 provider、模型、密钥和代理变量 | `planet.sh` 启动时会读取常见的 `AI_*`、`SERVICE_*`、`PYTHON_IMAGE`、`UV_IMAGE`、代理变量 |
1. 在 `/login` 点击"忘记密码?",或直接打开 `/forgot-password`。
2. 输入注册邮箱,点击"发送验证码"。无论邮箱是否注册,页面都会显示同一句提示(避免账号枚举)。
3. 收到验证码后,在下一步填入验证码 + 新密码(至少 8 位),点击"重置密码"。
4. 系统会跳回 `/login`,用新密码登录即可。
推荐写法:
## 账户设置
```bash
export AI_PROVIDER=minimax
export AI_PROVIDER_API=anthropic-messages
export AI_BASE_URL=https://api.example.com/anthropic
export AI_API_KEY=sk-change-me
export AI_MODEL=MiniMax-M2.7
export AI_PROVIDER_SERVICE_TOKEN=change_me
```
控制台右上角点击你的用户名进入账户设置,可以:
默认情况下,`planet.sh` 只静态解析 `~/.zshrc` 中简单的 `export KEY=value` 或 `KEY=value` 行,避免 shell 主题、插件或交互初始化拖慢启动。如果变量依赖复杂 shell 展开,可以显式启用 source 模式:
- 修改密码:输入当前密码 + 新密码
- 修改邮箱:输入新邮箱后系统会发验证码到新地址,验证通过后才生效
- 查看权限组:列出你目前拥有的 Gatekeeper 权限组(`docs_user` / `docs_developer` / `docs_admin`)
- 登出:清除当前会话
```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```
## 控制台总览
如需完全忽略 `~/.zshrc`:
```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```
AI Provider 镜像只在代码、Dockerfile、Compose 配置或相关 Python 依赖变化时重建。修改 `aiprovider/.env` 或 `~/.zshrc` 中的模型、密钥、Base URL 不会触发镜像重建;重启 AI Provider 即可让容器读取新配置:
```bash
./planet.sh restart -a
```
构建较慢时,优先判断当前卡在哪一层:
| 现象 | 常见原因 | 处理方式 |
| --- | --- | --- |
| `transferring context` 很大 | Docker build context 包含前端资源、PDF、数据目录等无关文件 | 当前仓库通过 `.dockerignore` 只发送 AI Provider 必需文件 |
| `uv sync` 下载依赖较慢 | 首次构建或缓存为空,网络访问 Python 包较慢 | 等待首次构建完成;后续会复用 BuildKit 的 uv 下载缓存 |
| 改密钥后仍显示旧配置 | 容器尚未重启 | 执行 `./planet.sh restart -a` |
### 停止
```bash
./planet.sh stop
```
会停止:
- 后端
- AI Provider
- 前端
- PostgreSQL
- Redis
### 重启
全量重启:
```bash
./planet.sh restart
```
按模块重启:
```bash
./planet.sh restart -b
./planet.sh restart -f
./planet.sh restart -a
./planet.sh restart -d
```
| 参数 | 作用 |
| --- | --- |
| `-b` | 只重启后端 |
| `-f` | 只重启前端 |
| `-a` | 只重启 AI Provider |
| `-d` | 只重启数据库 |
按模块重启适合日常开发,能避免无关服务被打断。
### 创建用户
```bash
./planet.sh createuser
```
用于首次进入控制台前创建登录账号。脚本会交互式提示用户名、密码和角色。
### 健康检查
```bash
./planet.sh health
```
会检查:
- `planet_*` 容器状态
- 后端 `/health`
- AI Provider `/health`
- 前端页面可达性
如果某项显示 offline,优先查看对应日志。
### 日志
最近日志:
```bash
./planet.sh log
```
持续跟随日志:
```bash
./planet.sh log -f
./planet.sh log -b
./planet.sh log -a
```
| 参数 | 日志来源 |
| --- | --- |
| `-f` / `--frontend` | `/tmp/planet_frontend.log` |
| `-b` / `--backend` | `/tmp/planet_backend.log` |
| `-a` / `--ai-provider` | `planet_aiprovider` 容器日志 |
### 局域网访问
```bash
./planet.sh start --allow-lan
```
适合:
- WSL 中启动,Windows 浏览器访问
- 手机或平板演示 Earth
- 局域网其他机器访问同一个开发实例
`--allow-lan` 只负责让前端和后端监听 `0.0.0.0`。如果服务运行在 WSL 中,Windows 本机通常可以通过 `localhost` 访问,但手机或其他电脑访问 `http://<Windows局域网IP>:3000` 还依赖 Windows 端口转发和防火墙放行。
推荐按顺序判断:
```bash
# 在 WSL 或运行 Planet 的 shell 中
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'
```
如果这里能看到 `0.0.0.0:3000` 和 `0.0.0.0:8000`,但局域网 IP 访问失败,请在管理员 PowerShell 中配置:
```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
## Earth
Earth 是公开的 3D 态势页面,入口:
```text
http://localhost:3000/earth
```
它是独立前端,实际页面位于:
- `frontend/public/earth/index.html`
- `frontend/public/earth/js/`
- `frontend/public/earth/css/`
React 路由中的 `/earth` 只是用 iframe 承载它。
### 主要用途
Earth 用于在一个地球视图中观察:
- BGP 事件、异常和观测态势
- 卫星和轨迹
- 海缆与登陆点
- 算力中心
- 国界线、经纬线、高清材质、云图、地形
- 新闻直播和态势新闻
- 搜索和聚焦对象详情
### 图层控制
右侧图层面板用于打开或关闭可视图层。
常见图层包括:
- 经纬线
- 国界线
- 高清材质
- 大气云图
- 海缆
- 算力中心
- BGP 观测
- 卫星
- AIS 船只
- 轨迹
- 地形
部分图层存在依赖关系:
- 地形依赖高清材质
- 轨迹依赖卫星
- 高清材质关闭时,地球会显示基座地图和边缘识别效果
### 图例
左下角图例会跟随当前聚焦或启用的图层切换。
当前已覆盖:
- 海缆
- 卫星
- 国界线
- 算力中心
- BGP
- AIS 船只
AIS 船只图例按船型显示颜色:
- 货轮
- 油轮
- 客船
- 渔船
- 军舰
- 停泊/低速
- 其他船只
船只图例中的三角形对应地图上的航行船只标记,圆点对应停泊或低速状态。
### 搜索
Earth 搜索支持查找当前地球对象,例如:
- 海缆
- 登陆点
- 卫星
- 算力中心
- BGP 事件
- BGP 观测站
搜索结果可以用于快速定位对象,并打开对应详情。
### 位置候选采集
算力中心和 BGP 观测站详情卡支持自动采集坐标候选。点击对象后,使用详情卡中的 `自动采集坐标候选` 或 `重新自动采集坐标` 按钮,后端会从源坐标、开放组织注册 API 和在线地理编码中整理候选位置;这些常规来源没有候选时,会使用当前默认 AI Provider 做一次 LLM factcheck 兜底。BGP 观测站的已存储位置只用于补齐查询上下文,不会作为候选直接返回。
候选可以直接在 Earth 上预览。算力中心候选点击 `保存` 后会写入 `compute_center_locations` 维表,并立即刷新图层。算力中心图层左上角的通知气泡显示无法渲染的待定位数量;点击后可查看列表,单条采集候选,或用 `一键采用` 从上到下保存最高置信候选。没有可用候选的记录会留在列表中,不会被国家中心点或硬编码 hint 伪造位置。详细流程见 [Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)。
### 设置
设置面板包含:
- 旋转模式 / 巡航模式 / 动捕模式
- 巡航模块:BGP、新闻、算力中心、船只、海缆、卫星
- 视图设置:卫星显示风格、日夜模式、面板显示开关
- 动捕调试模式、动捕输入源、只显示骨骼
- 地球默认大小
- 地形透明度
- 重置设置
这些设置会保存在浏览器本地存储中。换浏览器或清理站点数据后会恢复默认值。
### 视角控制
Earth 支持鼠标、触控板和触屏操作。
常用控制方式:
| 操作 | 作用 |
| --- | --- |
| 鼠标左键拖动 | 旋转地球 |
| 手指单指拖动 | 在触屏设备上旋转地球 |
| 鼠标滚轮 | 放大或缩小视角 |
| 双指捏合 | 在触屏设备上放大或缩小视角 |
| 缩放按钮 | 按固定步长调整缩放 |
| 点击缩放百分比 | 重置到默认缩放 |
缩放时,顶部胶囊会短暂显示当前缩放比例,例如 `缩放 180%`。这个提示只表示当前视角缩放,不代表数据加载进度;如果页面正在加载数据,加载提示优先显示,缩放提示不会打断加载状态。
拖动灵敏度会根据当前缩放自动调整。默认视角附近保持常规旋转速度;放大后拖动会逐步变细,适合检查某个区域、船只、卫星或 BGP 事件;缩小后拖动会略快,方便快速浏览全球态势。
### 动作捕捉控制
Earth 预留了动作捕捉控制入口,面向大屏和未来 3D 展示。实时链路有两种输入源:默认的 `浏览器摄像头` 会直接用网页 `getUserMedia` 在本机浏览器识别;高级的 `Motion Agent` 会走 `摄像头/RTSP/HTTP -> 本地 Agent -> 本地 WebSocket -> Earth 页面`。两种模式都不会把摄像头帧或实时手势发到云端,也不会复用新闻/RSS 聚合接口。
默认不自动启用。打开设置里的 `动捕调试模式`,或用 `?motion=1` 打开 Earth 动捕连接后,系统会启动当前选择的输入源。输入源默认是 `浏览器摄像头`,无需安装应用,但页面必须运行在 HTTPS 或 localhost,且用户需要允许浏览器摄像头权限。需要双摄、USB index、手机/网络摄像头流或客户端/边缘设备时,可在设置中切到 `Motion Agent`。默认 Agent 地址是 `ws://127.0.0.1:8765/ws/gestures`,也可用 URL 参数 `motionAgent` 覆盖。
URL 参数也可以直接指定输入源:`?motion=1&motionProvider=browser` 使用浏览器摄像头;`?motion=1&motionProvider=agent` 使用 Motion Agent;传入 `motionAgent=ws://...` 时会自动选择 Motion Agent。
当前手势语义:
| 手势事件 | 作用 |
| --- | --- |
| `rotate_left` | 地球向左旋转 |
| `rotate_right` | 地球向右旋转 |
| `rotate_up` | 地球向上旋转 |
| `rotate_down` | 地球向下旋转 |
| `zoom_in` | 放大视角 |
| `zoom_out` | 缩小视角 |
| `focus_prev` / `focus_next` | 在当前动捕图层内切换可交互目标 |
| `layer_prev` / `layer_next` | 切换动捕候选图层,并巡航到新图层最近目标 |
| `confirm` | 确认当前已选目标;当前浏览器识别暂未启用双手上举确认 |
设置面板中的 `动捕调试模式` 会打开调试面板。浏览器摄像头输入源会在面板内显示本机实时预览,并在其上绘制关节点和连线;`Motion Agent` 输入源只发送归一化骨架事件,不发送原始视频帧。面板里的 `只显示骨骼` 会隐藏视频预览、只保留深色背景和骨架;`停止匹配动作` 会暂停手势触发,但摄像头预览和骨架绘制仍可继续用于调试。未匹配动作时骨架为红色,匹配后变绿并显示当前动作名称。该入口和 `动捕输入源` 控件都已预留 Gatekeeper 权限标记,后续可接入鉴权控制。
### 巡航模式
巡航模式会让 Earth 自动轮播聚焦目标。
当前巡航模块包括:
- BGP
- 新闻
- 算力中心
- 船只
- 海缆
- 卫星
适合演示、监控大屏或无人值守展示。
### 移动端
Earth 有移动端抽屉布局。小屏下:
- 图层控制进入移动抽屉
- 搜索、设置、详情会使用移动端面板
- 主要交互仍围绕地球对象点击、搜索和图层开关
### 常见问题
#### Earth 打不开
先检查前端是否在线:
```bash
./planet.sh health
./planet.sh log -f
```
如果前端端口不是 `3000`,使用启动时输出的实际端口。
#### 图层没有数据
检查后端和数据源:
```bash
./planet.sh health
./planet.sh log -b
```
然后进入控制台查看:
- `/datasources`
- `/data`
- `/bgp`
#### 卫星、BGP 或海缆加载慢
这些图层可能依赖后端接口、外部数据源或首次加载任务。先等待启动任务完成,再查看日志和控制台数据源状态。
## 控制台
控制台入口:
```text
http://localhost:3000/admin
```
控制台需要登录。首次使用先创建用户:
```bash
./planet.sh createuser
```
### 页面结构
控制台使用 React + Ant Design,左侧菜单按工作域组织。
常见入口:
控制台 `http://localhost:3000/admin` 使用 React + Ant Design,左侧菜单按工作域组织。
| 页面 | 路由 | 用途 |
| --- | --- | --- |
| 仪表盘 | `/admin` | 系统概览 |
| Earth | `/earth` | 打开公开 Earth 页面 |
| 数据源 | `/datasources` | 查看数据源和触发采集 |
| 采集数据 | `/data` | 查看采集后的数据 |
| BGP 观测 | `/bgp` | 查看 BGP 专题数据 |
| Earth | `/earth` | 跳到公开 Earth 页面 |
| 数据源 | `/datasources` | 数据源目录、触发采集 |
| 采集数据 | `/data` | 已落库的数据 |
| BGP 观测 | `/bgp` | BGP 专题观测 |
| 系统告警 | `/alerts/system` | 系统级告警 |
| BGP 告警 | `/alerts/bgp` | BGP 相关告警 |
| 态势告警 | `/alerts/situational` | 态势研判告警 |
| AI | `/ai` | 模型供应商、WebSearch 等工具和测试台 |
| 系统日志 | `/logs` | 查看系统日志,通常仅 super admin 可见 |
| 用户管理 | `/users` | 管理用户 |
| 系统配置 | `/settings` | 系统配置和电视直播源等设置 |
| AI | `/ai` | 模型供应商、工具、测试台 |
| 系统日志 | `/logs` | 通常仅 super admin 可见 |
| 用户管理 | `/users` | 创建/删除/改角色/调权限组 |
| 系统配置 | `/settings` | 系统、SMTP、TV、采集器设置 |
### 数据源
权限不足时菜单项会自动隐藏。如果发现某个菜单看不到,先确认自己的角色和 Gatekeeper 权限组。
`/datasources` 用于查看采集来源和触发采集。当前页面是“数据源目录”,会把内置数据源和自定义数据源放在同一张列表里展示。
## 配置数据采集器
常见操作:
`/settings?tab=collector_credentials` 是"采集器设置"页。这里统一维护所有采集器的连接配置,不仅是凭证。
- 查看数据源状态
- 触发采集
- 查看最近采集任务
- 打开详情抽屉查看 endpoint、请求头、基础配置和是否为内置数据源
如果 Earth 上某类对象缺失,通常先到这里确认数据源是否可用。
数据源列表中的名称点击后只打开信息抽屉,不再承担编辑入口。接口地址、凭证、请求头和自定义数据源配置统一到 `/settings` 的“采集器设置”里维护。
当有采集任务正在运行时,总体进度下方会出现 `采集中 N` 标签。这个标签和其他状态标签放在同一排,但带有可点击样式;点击后会弹出当前采集中任务列表,显示每个任务的阶段、进度和处理数量。
### 采集数据
`/data` 用于查看采集后的数据表。
适合排查:
- 数据是否已经进入系统
- 数据更新时间是否符合预期
- 某个数据源是否产出了有效记录
### BGP 观测
`/bgp` 是 BGP 专题页面。
它和 Earth 的 BGP 图层互补:
- Earth 强调空间态势和可视聚焦
- 控制台 BGP 页面强调列表、状态、详情和研判
### 告警
告警入口包括:
- `/alerts/system`
- `/alerts/bgp`
- `/alerts/situational`
用于查看系统、网络和态势相关告警。
### 系统配置
`/settings` 用于管理系统级配置。
当前常见用途包括:
- 系统设置
- 电视直播源配置
- 采集器设置
### AI
`/ai` 用于管理 AI 运行链路,已经从系统配置中独立出来。旧链接 `/playground` 会跳转到 `/ai?tab=playground`。
当前包含:
- `模型供应商`:默认 LLM provider、模型、Base URL、API Key、本地 `aiprovider` 代理和连接测试
- `工具`:WebSearch provider、搜索 API Key、Base URL、最大结果数、超时和高级 provider 参数
- `测试台`:AI Provider 状态、预设请求和真实分析链路调试
旧链接 `/settings?tab=ai` 会跳转到 `/ai?tab=providers`。
具体可用配置取决于当前登录用户权限。
#### 采集器设置
`/settings?tab=collector_credentials` 当前显示为“采集器设置”。这里统一维护所有采集器的连接配置,而不是只维护凭证。
使用方式:
操作步骤:
1. 在下拉框选择采集器。
2. 查看状态标签:
@@ -545,167 +94,248 @@ http://localhost:3000/admin
- 所属模块
- `启用` / `禁用`
- `未检查` / `可用` / `不可用`
3. 点击下拉框右侧的插头图标执行健康检查。
4. 如果检查通过,状态会变为 `可用`。
5. 修改 endpoint、请求头、超时或重试次数后保存。
3. 点击下拉框右侧的插头图标执行健康检查。检查通过状态变为 `可用`。
4. 修改 endpoint、请求头、超时、重试次数等,然后保存。
对于免费且不需要凭证的采集器,连接检查会直接请求对应 endpoint。对于需要凭证的采集器,连接检查会走对应凭证链路;如果凭证或 endpoint 相比上次验证成功时发生变化,需要重新点击连接。
对于免费且不需要凭证的采集器,连接检查直接打 endpoint;对于需要凭证的采集器走对应凭证链路。如果凭证或 endpoint 相比上次验证成功时发生变化,需要重新点击连接。
系统判断“已连接”的条件是:
系统判断"已连接"的条件:
- 当前配置已经成功采集过数据;或
- 当前配置已经点击过连接按钮并验证成功。
- 当前配置已经成功采集过数据,或
- 当前配置已经点击过连接按钮并验证成功
#### BarentsWatch AIS 凭证
### BarentsWatch AIS 凭证
`BarentsWatch AIS` 是需要凭证的内置采集器。选择该采集器后,凭证区域会显示在基础配置上方。
配置项:
`BarentsWatch AIS` 是需要凭证的内置采集器。选择该采集器后,凭证区域显示在基础配置上方:
- `Client ID`
- `Client Secret`
- `Endpoint`
如果已经配置过 secret,输入框会显示脱敏预览。保存时如果保持这个脱敏预览不变,系统会保留原 secret;只有输入新的 secret 才会替换。
BarentsWatch AIS 支持从以下位置读取凭证:
1. 控制台采集器设置中保存的凭证。
2. 后端环境变量:
- `BARENTSWATCH_CLIENT_ID`
- `BARENTSWATCH_CLIENT_SECRET`
- 兼容历史拼写:`BARRENTSWATCH_CLIENT_ID`、`BARRENTSWATCH_CLIENT_SECRET`
3. `~/.zshrc` 中的同名 `export`。
如果已配置过 secret,输入框会显示脱敏预览。保存时保持脱敏预览不变就会保留原 secret;只有输入新的 secret 才会替换。
如果连接失败,页面会弹出凭证获取教程。教程支持:
- 查看默认教程。
- 点击“教程不好用”让 AI Provider 根据默认 prompt 重新生成教程。
- 点击“重置”恢复默认教程。
- 查看默认教程
- 点击"教程不好用"让 AI Provider 用默认 prompt 重新生成
- 点击"重置"恢复默认教程
默认教程以 BarentsWatch 官方 tutorial 为准,并提醒 Live AIS 应选择 `AIS - API`,不是普通 `BarentsWatch - API`。
默认教程以 BarentsWatch 官方 tutorial 为准,并提醒 Live AIS 应选择 `AIS - API`。
### 系统日志
### AISStream 实时船舶
`/logs` 用于查看系统日志。若菜单中不可见,通常是当前用户角色没有权限。
`AISStream 实时船舶` 是全球 AIS WebSocket 采集器。连接测试通过只说明 API Key 和 endpoint 格式可用;真正的全球船只数据来自后台 `aisstream_vessels` collector 长连接运行并写入 `ais_raw_observations`。
排查问题时常用组合:
操作步骤:
```bash
./planet.sh health
./planet.sh log
```
1. `/settings?tab=collector_credentials` 选择 `AISStream 实时船舶 : aisstream_vessels`
2. 在 `AISStream 凭证` 填入 API Key
3. Endpoint 保持默认 `wss://stream.aisstream.io/v0/stream`
4. 点击插头图标进行连接测试,确认显示 `可用`
5. 保存采集器设置
6. 打开 `/datasources` 的 `实时流` tab,找到 `AISStream 实时船舶`
7. 点击 `启动`、`停止` 或 `重连` 管理长连接;这里不显示百分比进度
8. 在实时流卡片中观察:
- `connected` 表示正在接收实时流
- `累计入库`、`近 24h`、`近 1h` 和 `唯一 MMSI` 用于判断历史采集量
- 如果显示 `disconnected` 且有最近错误,可以点击 `重连`
再进入 `/logs` 查看更结构化的运行信息。
## 配置 AI 凭证
## Docs
`/ai?tab=providers` 是 AI 模型管理入口。包含两个核心子 tab:
文档站入口:
- `模型供应商`:默认 LLM provider、模型、Base URL、API Key、本地 `aiprovider` 代理和连接测试
- `工具`:通过下拉菜单选择具体工具,当前支持 WebSearch 和 OCR
```text
http://localhost:3000/docs
```
### 模型供应商
Docs 正文由后端 API 按权限读取,不再把全部 Markdown 直接打进前端构建产物。当前文档源文件仍位于:
provider 和模型既可选预设也可直接输入自定义 id/name。常用字段:
```text
docs/technical/zh/*.md
docs/technical/en/*.md
```
- Provider:例如 `minimax`、`openai`、`anthropic`、`ollama`
- 协议适配:`OpenAI Chat Completions` / `Anthropic Messages` / `Ollama Generate`
- Base URL:模型 API 地址
- 默认模型:例如 `gpt-5.1`、`MiniMax-M2.7`
- API Key:填入后保存;保存的 Key 在 UI 中显示为脱敏预览
- Max Tokens、Anthropic Version:可保持默认
- Timeout / Retry:超时和重试次数
未登录访客默认只能看到 `public` 文档,例如首页、快速开始和使用手册。登录用户如果被分配 Gatekeeper 权限组,可以看到更多技术文档:
Base URL 输入框尾端的插头图标会触发连接测试。测试通过会显示当前模型返回的简短回复。
- `docs_user`:用户操作类文档。
- `docs_developer`:Earth、前端、后端、采集器和 AI Provider 等开发文档。
- `docs_admin`:服务控制、运维、环境变量和敏感操作文档。
### 工具
`admin` 默认拥有管理文档权限,`super_admin` 拥有全部 Docs 权限。Gatekeeper 权限组在控制台“用户管理”中配置。
- **WebSearch**:provider、API Key、Base URL、最大结果数、超时、高级 provider 参数。未启用时除"启用"开关外其它配置项和连接测试都会置灰
- **OCR**:provider、Base URL、API Key、模型/engine、识别语言、超时、最大文件大小、输出格式
Docs 支持:
旧链接 `/settings?tab=ai` 会跳到 `/ai?tab=providers`。
- 分类导航
- Markdown 渲染
- 表格和代码块
- 文档内目录
- 对当前可见文档搜索
- technical 文档之间的内部链接跳转
## 系统设置
如果新增 technical 文档,应同步检查:
`/settings` 用于管理系统级配置,常用子 tab:
- 是否有清晰的一级标题
- 是否需要加入后端 Docs metadata 的人工分类和排序
- 应归入 `public`、`docs_user`、`docs_developer` 还是 `docs_admin`
- **系统显示**:系统名称、刷新间隔、数据保留天数、最大并发任务
- **通知策略**:告警邮件开关、收件邮箱、严重/警告/每日摘要通知
- **安全策略**:会话超时、最大登录尝试、密码策略
- **SMTP 邮件**:注册和找回密码所需的发件配置(仅 `admin` / `super_admin` 可见)
- **电视直播**:电视直播源管理
- **AI / WebSearch / OCR**:见上节
## 开发命令约定
### SMTP 邮件设置
前端命令必须使用 Bun:
公开注册和验证码功能依赖这一项。`admin` 或 `super_admin` 用户在 `/settings` 进入 `SMTP 邮件` 子 tab,填:
```bash
cd frontend
bun install
bun run dev
bun run build
```
- SMTP 主机、端口
- 账号、密码
- 发件地址(必填)、发件人名称
- STARTTLS(端口 587 常用) 或 隐式 TLS(端口 465)
- 超时秒数
不要使用 `npm run ...`。项目在 WSL / Windows 混合环境中优先依赖 Bun,避免 Node/npm 路径差异带来的兼容问题。
填完保存,再点"发送测试邮件"按钮,输入收件人地址试发一封。测试通过后即可让普通用户走 `/register` 自助注册。
验证前端构建:
如果保留密码字段中的脱敏预览不动,保存时不会覆盖原密码;要换密码就输入新值。
```bash
source ~/.zshrc && bun run build
```
## 用户管理(管理员)
## 故障排查顺序
`/users` 仅 `super_admin` 可创建/删除用户。该页支持:
遇到问题时,建议按这个顺序排查:
- 查看用户列表(用户名、邮箱、角色、是否激活、邮箱是否已验证)
- 创建用户:与公开注册等价,但跳过邮箱验证(管理员认账)
- 修改角色:`viewer` / `operator` / `admin` / `super_admin`
- 调整 Gatekeeper 权限组:`docs_user` / `docs_developer` / `docs_admin`,影响 Docs 站可见文档范围
- 禁用 / 启用账号
1. 看服务状态:
要让普通用户能看开发或运维文档,进 `/users` 给他加 `docs_developer` 或 `docs_admin`。
```bash
./planet.sh health
```
## 数据探索
2. 看最近日志:
- `/datasources`:数据源目录。`采集任务` tab 面向一次性/定时采集器,可以按产品域、层级、启用状态、最近执行状态、是否已有采集数据和关键词筛选;勾选多行后可批量采集选中项,未勾选时“一键采集”触发当前筛选范围。`实时流` tab 面向 AISStream / WebSocket 长连接,展示连接健康、累计入库、时间窗统计和启动 / 停止 / 重连操作。点击名称打开信息抽屉查看 endpoint、请求头、基础配置和是否内置;接口、凭证、请求头的编辑统一在 `/settings` 的"采集器设置"。总体进度下方的 `采集中 N` 标签可点击,展开当前采集任务列表
- `/data`:采集后数据表,适合排查"数据是否已经进入系统"、"更新时间是否符合预期"、"某个数据源是否产出有效记录"
- `/bgp`:BGP 专题页面,列表 + 详情 + 研判,与 Earth 的 BGP 图层互补
- `/alerts/system`、`/alerts/bgp`、`/alerts/situational`:系统、BGP、态势告警
```bash
./planet.sh log
```
## AI 测试台
3. 按模块查看日志:
`/ai?tab=playground` 用于真实分析链路调试。可以:
```bash
./planet.sh log -f
./planet.sh log -b
./planet.sh log -a
```
- 选择当前 provider
- 用预设请求或自定义 prompt 触发分析
- 观察 AI Provider 状态和返回内容
4. 只重启有问题的模块:
旧链接 `/playground` 会跳到这里。
```bash
./planet.sh restart -f
./planet.sh restart -b
./planet.sh restart -a
```
## Earth 公开页面
5. 如果数据库或缓存异常,再重启数据库:
Earth `http://localhost:3000/earth` 是公开 3D 态势页面,不需要登录。React 路由中的 `/earth` 用 iframe 承载独立前端(位于 `frontend/public/earth/`)。
```bash
./planet.sh restart -d
```
### 主要用途
6. 仍无法恢复时,执行全量重启:
在一个地球视图中观察:BGP 事件与观测态势、卫星和轨迹、海缆与登陆点、算力中心、国界线/经纬线/高清材质/云图/地形、新闻直播和态势新闻、搜索和聚焦对象详情。
```bash
./planet.sh restart
```
### 图层控制
右侧图层面板用于打开或关闭图层。常见图层:经纬线、国界线、高清材质、大气云图、海缆、算力中心、BGP 观测、卫星、AIS 船只、地形。卫星轨迹不再作为单独图层出现在图层列表中,改在设置面板里控制。
依赖关系:
- 地形依赖高清材质
- 轨迹依赖卫星
- 高清材质关闭时,地球显示基座地图和边缘识别效果
### 图例
左下角图例会跟随当前聚焦或启用的图层切换。已覆盖:海缆、卫星、国界线、算力中心、BGP、AIS 船只。
AIS 船只图例按船型显示颜色:货轮、油轮、客船、渔船、军舰、停泊/低速、其他船只。三角形对应航行船只标记,圆点对应停泊或低速状态。
### 搜索
支持查找海缆、登陆点、卫星、算力中心、BGP 事件、BGP 观测站。结果可快速定位并打开详情。
### 位置候选采集
算力中心和 BGP 观测站详情卡支持自动采集坐标候选。点击对象后用"自动采集坐标候选"或"重新自动采集坐标"按钮,后端会从源坐标、开放组织注册 API 和在线地理编码中整理候选;常规来源没有候选时使用当前默认 AI Provider 做 LLM factcheck 兜底。BGP 观测站的已存储位置只用于补齐查询上下文,不会作为候选直接返回。
候选可以直接在 Earth 预览。算力中心候选点击"保存"后写入 `compute_center_locations` 维表并刷新图层。算力中心图层左上角的通知气泡显示无法渲染的待定位数量;点击查看列表,单条采集候选,或用"一键采用"从上到下保存最高置信候选。没有可用候选的记录会留在列表中,不会被国家中心点或硬编码 hint 伪造位置。详细流程见 [Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)。
### 设置
设置面板包含:旋转模式 / 巡航模式 / 动捕模式、巡航模块(BGP/新闻/算力中心/船只/海缆/卫星)、视图设置(卫星显示风格、悬停提示、卫星呼吸闪烁、真实卫星高度、轨迹显示、低缩放圆点、日夜模式、面板显示开关)、动捕调试模式 / 输入源 / 只显示骨骼、地球默认大小、地形透明度、重置设置。
“真实卫星高度”默认开启:卫星会按 TLE/SGP4 算出的真实轨道高度做压缩分层显示,低轨仍靠近地球,高轨会更远但不会脱离当前视图。高轨显示高度会被压到地球半径外约四分之一以内,这样 GEO / MEO 仍能和 LEO 分层,但不会把视线、轨迹和选择操作拉得过散;关闭后恢复旧版所有卫星位于同一显示球面的效果。“轨迹显示”控制卫星轨迹线显隐,卫星图层关闭时轨迹也不可见。
“悬停提示”控制鼠标悬停地表时的 tooltip 内容:`国家` 只在陆地命中国家时显示国家信息,太平洋等海洋区域不弹出地表提示;`位置` 在陆地和海洋都显示纬度、经度和海拔;`完整` 是默认模式,陆地显示国家 + 位置,海洋显示位置。
这些设置保存在浏览器本地存储,换浏览器或清理站点数据后会恢复默认值。
### 视角控制
| 操作 | 作用 |
| --- | --- |
| 鼠标左键拖动 | 旋转地球 |
| 手指单指拖动 | 触屏旋转地球 |
| 鼠标滚轮 | 放大或缩小 |
| 双指捏合 | 触屏放大或缩小 |
| 缩放按钮 | 固定步长调整缩放 |
| 点击缩放百分比 | 重置到默认缩放 |
缩放时顶部胶囊会短暂显示当前缩放比例。这个提示不代表数据加载进度;如果页面正在加载数据,加载提示优先显示。
拖动灵敏度会根据当前缩放自动调整:默认视角附近保持常规旋转速度;放大后拖动会逐步变细,缩小后拖动会略快。
### 动作捕捉控制
Earth 预留了动作捕捉控制入口。实时链路两种输入源:
- **浏览器摄像头**(默认):直接用网页 `getUserMedia` 在本机浏览器识别;无需安装应用,但页面必须运行在 HTTPS 或 localhost,且需允许浏览器摄像头权限
- **Motion Agent**:摄像头/RTSP/HTTP → 本地 Agent → 本地 WebSocket → Earth 页面;用于双摄、USB index、手机/网络摄像头流
打开方式:设置中开启"动捕调试模式",或加 URL 参数 `?motion=1` 打开 Earth 动捕连接。Motion Agent 默认地址 `ws://127.0.0.1:8765/ws/gestures`,可用 `motionAgent` URL 参数覆盖。也可以直接 `?motion=1&motionProvider=browser` 或 `?motion=1&motionProvider=agent`。
两种模式都不会把摄像头帧或实时手势发到云端,也不会复用新闻/RSS 聚合接口。
手势语义:
| 手势事件 | 作用 |
| --- | --- |
| `rotate_left/right/up/down` | 地球向对应方向旋转 |
| `zoom_in/out` | 放大或缩小视角 |
| `focus_prev/next` | 在当前动捕图层内切换可交互目标 |
| `layer_prev/next` | 切换动捕候选图层并巡航到新图层最近目标 |
| `confirm` | 确认当前已选目标 |
调试面板中:浏览器摄像头输入会显示本机实时预览并绘制关节点和连线;Motion Agent 只发归一化骨架事件,不发原始帧。"只显示骨骼"会隐藏视频预览只保留骨架;"停止匹配动作"会暂停手势触发但保留预览和骨架。未匹配时骨架红色,匹配后变绿并显示动作名称。
### 巡航模式
巡航模式让 Earth 自动轮播聚焦目标。当前巡航模块:BGP、新闻、算力中心、船只、海缆、卫星。适合演示、监控大屏或无人值守。
### 移动端
移动端抽屉布局:图层控制进入移动抽屉,搜索、设置、详情使用移动端面板。主要交互仍围绕地球对象点击、搜索和图层开关。
### 常见问题
- **Earth 打不开**:先确认前端服务是否在线;如果端口不是 `3000`,使用启动输出的实际端口
- **图层没有数据**:进 `/datasources` 看数据源状态、是否已采集和最近执行结果,再到 `/data` 或 `/bgp` 看是否有记录
- **卫星 / BGP / 海缆加载慢**:这些图层依赖后端接口和外部数据源,首次加载需要等启动任务完成
- **卫星看起来不在同一层**:这是默认的真实高度压缩显示。想回到旧版同层球面,可在设置中关闭“真实卫星高度”
## Docs 文档站
文档站 `http://localhost:3000/docs` 由后端按权限读取,不再把全部 Markdown 直接打进前端构建产物。
未登录访客默认只能看到 `public` 文档:首页、快速开始、使用手册、常见问题、Earth 位置候选采集使用手册。登录用户被分配 Gatekeeper 权限组后可以看到更多技术文档:
- `docs_user`:用户操作类文档
- `docs_developer`:Earth、前端、后端、采集器和 AI Provider 等开发文档
- `docs_admin`:服务控制、运维、环境变量和敏感操作文档(包括运维手册)
`admin` 默认拥有 `docs_admin`,`super_admin` 拥有全部 Docs 权限。Gatekeeper 权限组在"用户管理"中配置。
Docs 支持分类导航、Markdown 渲染、表格和代码块、文档内目录、对当前可见文档搜索、technical 文档间内部链接跳转。
## 相关文档
- [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)
- [控制台前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
- [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
- [Earth 图层样式属性索引](/home/ray/dev/linkong/planet/docs/technical/zh/earth-layer-style-reference.md)
- [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)
- [Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)
- [系统服务控制](/home/ray/dev/linkong/planet/docs/technical/zh/backend-system-service-control.md)
- [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
- [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)
+60 -4
View File
@@ -22,10 +22,10 @@ image_exists AND stamp_non_empty AND fingerprint_match
### 修复
将戳文件路径从 `/tmp/` 改到持久路径:
将戳文件路径从临时目录改到持久缓存路径:
```bash
AI_PROVIDER_BUILD_STAMP_FILE="$HOME/.cache/planet/aiprovider_build.sha256"
AI_PROVIDER_BUILD_STAMP_FILE="${XDG_CACHE_HOME:-$HOME/.cache}/planet/aiprovider_build.sha256"
```
写入时确保目录存在:
@@ -94,7 +94,7 @@ COPY aiprovider /app/aiprovider
### 运行期配置来源
`planet.sh` 启动 AI Provider 前会生成临时 env-file,并把它传给 Compose 或手动 `docker run` fallback。配置优先来自:
`planet.sh` 启动 AI Provider 前会生成受当前用户保护的运行期 env-file,并把它传给 Compose 或手动 `docker run` fallback。默认路径位于 `${XDG_STATE_HOME:-$HOME/.local/state}/planet/aiprovider_runtime.env`。配置优先来自:
1. `aiprovider/.env`
2. `~/.zshrc` 中简单的 `export AI_...=...` 或 `AI_...=...` 行
@@ -155,7 +155,7 @@ wait_for_port_release() {
- `PORT_PRESTART_RETRIES`:默认 3 次。
- `PORT_PRESTART_RETRY_INTERVAL`:默认 2 秒。
`kill_port_if_requested()` 优先清理当前环境能找到的监听 PID;只有检测到当前运行在 WSL 且没有可杀 PID、但端口仍不可绑定时,才会检查 Windows 侧 listener,并尝试通过 PowerShell 停止对应服务或强制结束对应进程。若没有权限,或 `iphlpsvc` 这类系统服务拒绝停止,脚本会打印 Windows listener 详情并立即停止启动,不再继续拉起服务碰同一个端口错误。非 WSL 环境不会尝试 Windows 清理路径。此时需要用管理员 PowerShell 清理 portproxy/服务占用,或改用其他端口。
`kill_port_if_requested()` 优先清理当前环境能找到的监听 PID;只有检测到当前运行在 WSL 且没有可杀 PID、但端口仍不可绑定时,才会检查 Windows 侧 listener,并尝试通过 PowerShell 停止对应服务或强制结束对应进程。若没有权限,或 `iphlpsvc` 这类系统服务拒绝停止,脚本会打印 Windows listener 详情和管理员 PowerShell 处理命令,然后立即停止启动,不再继续拉起服务碰同一个端口错误。前端 Vite 启动后才发现 `Port 3000 is already in use` 时,也会打印同一套 Windows listener 处理命令。非 WSL 环境不会尝试 Windows 清理路径。`--allow-lan` 在 WSL 下会使用临时 Windows relay 暴露 `3000` / `8000`,所以旧的持久 portproxy 规则应清理掉。
## 问题三:端口检测用 Python
@@ -202,6 +202,62 @@ PY
修复戳文件路径后,无参 `restart` 同样使用 `stop + start`,fingerprint 检查正常生效,行为与 `restart -b` 完全一致。无需额外代码变更。
## 状态文件、日志与失败清理
`planet.sh` 不再把 PID、日志和运行期 env-file 写入固定 `/tmp/planet_*` 路径。默认状态目录为:
```bash
${XDG_STATE_HOME:-$HOME/.local/state}/planet
```
脚本启动时会创建该目录并尽量设置为 `700`。当前使用的文件包括:
- `backend.pid` / `frontend.pid` / `motion_agent.pid`
- `backend.log` / `frontend.log` / `motion_agent.log`
- `aiprovider_build.log`
- `aiprovider_runtime.env`
- `ports.env`
PID 文件写入前会校验 PID 为正整数,写入时带换行并尽量设置为 `600`。读取 PID 文件时,如果内容不是数字,脚本会忽略该文件,不会把垃圾内容传给 `kill`。
`start` 成功后会把本次端口写入 `ports.env`。后续执行 `./planet.sh health` 时,会优先检查上次启动端口;如果没有状态文件,则回退到默认端口 `8000`、`3000`、`8010`、`8765`。这避免了用自定义端口启动后,健康检查仍只看默认端口的问题。
启动过程有轻量失败清理:如果 `start` 中途失败,脚本只清理本轮已经拉起的本地进程(backend、frontend、Motion Agent),不会在正常启动完成后停止服务。AI Provider、PostgreSQL 和 Redis 容器仍按原有容器生命周期管理。
## 健康检查与安全加固
HTTP 健康检查统一使用 `curl -fsS --max-time`。因此 `/health` 返回 4xx/5xx 不再被视为在线。
进程终止路径现在会校验:
- signal 只允许 `TERM`、`KILL`、`INT`、`HUP`;
- PID 必须是正整数;
- 进程组 PGID 必须是正整数。
这可以避免坏 PID 文件或错误 signal 造成不可预期的 `kill` 行为。
前端和 Motion Agent 启动失败时,现在也会调用 `print_port_listener_details()`,输出与后端一致的端口监听诊断。WSL 下如果端口看起来被 Windows 侧占用,脚本仍只在检测到 WSL 时才调用 PowerShell 诊断或清理路径。
## 跨平台注意事项
当前脚本是 Linux-first,并带有 WSL 增强。普通 Linux 不会执行 WSL PowerShell 逻辑;WSL 下会额外提供 Windows listener、portproxy 和摄像头提示。
如果要把同一份脚本扩展为 Linux、macOS、WSL 三平台通用,还需要继续封装这些命令差异:
- `stat --format`、`sort -V`、`xargs -r` 是 GNU 风格,macOS 默认 BSD 工具不完全兼容。
- `hostname -I`、`ss`、`fuser`、`systemctl` 在 macOS 上通常不可用。
- `tac` 在 macOS 上不一定存在,可用 `awk` 或 Python 兜底。
- Docker Desktop on macOS 不适用 `systemctl` daemon 诊断。
- 摄像头自动发现依赖 `/dev/video*` / `v4l2-ctl`,这是 Linux 路线;macOS 应显式使用 camera URL 或另做 AVFoundation 检测。
维护方向是增加一个小的 platform compatibility 层,把端口监听检测、版本比较、文件元信息、反向 tail、LAN IP 获取和 Docker daemon 诊断集中处理,而不是在业务启动流程里继续散落平台判断。
## 正式交付边界
`planet.sh` 是本地开发便利脚本,不作为正式生产启动入口。正式交付应通过 Kubernetes 的 `Deployment`、`Service`、`Ingress`、readiness/liveness probe 管理端口、健康检查、重启和滚动发布。这样生产环境不需要脚本抢占宿主机端口,也不会依赖 Vite dev server。
前端生产形态是 `vite build` 生成静态资源,再由 nginx/Caddy 等 HTTP 服务器托管。不要在生产中使用 `bun run dev` 或 `vite preview`。当前不维护 Webpack 双构建链;如果未来需要评估更企业化的构建生态,优先做 Rsbuild/Rspack spike。Electron 仅在正式目标变成离线桌面软件时再单独评估。
## Motion Agent 可选启动
`planet.sh` 现在可以管理本地动作捕捉 Agent,但默认不会启动它,避免普通开发机因为没有摄像头、OpenCV 或 MediaPipe 而影响后端/前端启动。
+246
View File
@@ -0,0 +1,246 @@
# Planet 运维手册
这份手册面向部署、值班和二次开发的运维人员。客户面向的 UI 使用流程见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md),本手册只覆盖 shell、Docker、日志、环境变量和故障排查。
## 首次启动
```bash
./planet.sh start
```
默认行为:
- 启动 PostgreSQL 和 Redis
- 启动 AI Provider
- 启动后端 API
- 启动前端 Vite dev server
- 输出 Earth、控制台、Playground 和后端 API 文档入口
首次启动会自动写入两个默认账号(见 `backend/app/db/session.py` 的 `DEFAULT_LOGIN_USERS`):
| 用户名 | 密码 | 角色 |
| --- | --- | --- |
| `admin` | `admin123` | `super_admin` |
| `linkong` | `12345678` | `super_admin` |
两个默认账号 `email_verified` 为 `true`,可直接登录控制台。任何在该列表之外的账号都必须走公开注册 + 邮箱验证流程(见使用手册),或用 `./planet.sh createuser` 命令式创建。
可指定端口:
```bash
./planet.sh start -b 8001 -f 3001 -a 8101
```
| 参数 | 含义 |
| --- | --- |
| `-b <port>` | 后端端口 |
| `-f <port>` | 前端端口 |
| `-a <port>` | AI Provider 端口 |
| `--allow-lan` | 允许局域网访问 |
| `--verbose` | 显示更多命令输出 |
## 启停与按模块重启
停止全部:
```bash
./planet.sh stop
```
会停止后端、AI Provider、前端、PostgreSQL、Redis。
按模块重启:
```bash
./planet.sh restart # 全量
./planet.sh restart -b # 后端
./planet.sh restart -f # 前端
./planet.sh restart -a # AI Provider
./planet.sh restart -d # 数据库
```
按模块重启适合日常开发,能避免无关服务被打断。
## 健康检查
```bash
./planet.sh health
```
会检查:
- `planet_*` 容器状态
- 后端 `/health`
- AI Provider `/health`
- 前端页面可达性
如果某项显示 offline,优先看对应日志。
## 日志
最近日志:
```bash
./planet.sh log
```
持续跟随:
```bash
./planet.sh log -f # 前端: /tmp/planet_frontend.log
./planet.sh log -b # 后端: /tmp/planet_backend.log
./planet.sh log -a # AI Provider: planet_aiprovider 容器日志
```
## 命令式创建用户
```bash
./planet.sh createuser
```
交互式提示用户名、密码、角色,直接落库并标记 `email_verified = TRUE`。
适用场景:
- SMTP 还没配置好,但需要先发账号给一名管理员
- 想批量预置内部测试账号
- 公开注册流程因任何原因不可用,需要应急兜底
正式用户开通推荐走控制台 `/settings -> SMTP 邮件` 配好发件后,让用户在 `/register` 自助注册。
## 局域网 / WSL 访问
```bash
./planet.sh start --allow-lan
```
适用于:
- WSL 中启动,Windows 浏览器访问
- 手机或平板演示 Earth
- 局域网其他机器访问同一开发实例
`--allow-lan` 只负责让前端和后端监听 `0.0.0.0`。WSL 中运行时,Windows 本机一般可以通过 `localhost` 访问,但局域网其他机器访问 Windows 局域网 IP 时还需要 Windows 端口转发和防火墙放行。
建议按顺序排查:
```bash
# 在运行 Planet 的 shell 中
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'
```
如果看到 WSL 内部服务已经启动,但局域网 IP 仍访问失败,让 `./planet.sh start --allow-lan` 启动临时 Windows relay。relay 会让 Windows 对外继续使用 `3000` / `8000`,并在 WSL 目标端口断开后自动退出。脚本会检测并请求管理员 PowerShell 删除旧 `portproxy`,也会检测 Windows 防火墙规则;缺少入站放行时会触发一次 UAC 管理员 PowerShell 请求自动创建。手动兜底命令如下:
```powershell
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
局域网设备访问 Windows 对外端口,例如 `http://<Windows局域网IP>:3000/earth`。
## AI Provider 环境变量与构建
AI Provider 运行期配置可以放在两处:
| 位置 | 适合内容 | 说明 |
| --- | --- | --- |
| `aiprovider/.env` | 团队约定的本地默认配置 | Docker Compose 作为 `env_file` 读取 |
| `~/.zshrc` | 个人 provider、模型、密钥、代理 | `planet.sh` 启动时读取常见 `AI_*`、`SERVICE_*`、`PYTHON_IMAGE`、`UV_IMAGE` |
推荐写法:
```bash
export AI_PROVIDER=minimax
export AI_PROVIDER_API=anthropic-messages
export AI_BASE_URL=https://api.example.com/anthropic
export AI_API_KEY=sk-change-me
export AI_MODEL=MiniMax-M2.7
export AI_PROVIDER_SERVICE_TOKEN=change_me
```
`planet.sh` 默认只静态解析 `~/.zshrc` 中简单的 `export KEY=value` 或 `KEY=value` 行。需要复杂 shell 展开时显式启用:
```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```
完全忽略 `~/.zshrc`:
```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```
AI Provider 镜像只在代码、Dockerfile、Compose 配置或相关 Python 依赖变化时重建。修改密钥或 Base URL 后只需重启容器:
```bash
./planet.sh restart -a
```
构建较慢时按层排查:
| 现象 | 常见原因 | 处理方式 |
| --- | --- | --- |
| `transferring context` 很大 | build context 含前端资源等无关文件 | `.dockerignore` 只发送必需文件 |
| `uv sync` 下载较慢 | 首次构建或缓存为空 | 等待首次完成,后续复用 BuildKit 缓存 |
| 改密钥后仍是旧配置 | 容器未重启 | `./planet.sh restart -a` |
## SMTP 邮件(公开注册依赖)
公开注册和邮箱验证依赖 SMTP。管理员在控制台 `/settings -> SMTP 邮件` 子 tab 中填写主机、端口、账号、密码、发件地址、TLS 模式,然后用"发送测试邮件"按钮验证。配置同时写入 `system_settings.smtp` 表行。
未配置时 `POST /api/v1/auth/register` 返回 `503 EMAIL_PROVIDER_NOT_CONFIGURED`,前端的注册流程会给出明确提示。运维兜底方式是 `./planet.sh createuser`。
OTP 一次性验证码走 Redis,key 格式 `otp:{purpose}:{email}`,TTL 600 秒。错误尝试 5 次后该 key 失效;重发冷却 60 秒,由 `otp_rate:{purpose}:{email}` 控制。
## 故障排查顺序
```bash
./planet.sh health # 1. 看服务状态
./planet.sh log # 2. 看最近日志
./planet.sh log -f # 3. 按模块查看
./planet.sh log -b
./planet.sh log -a
./planet.sh restart -f # 4. 只重启有问题的模块
./planet.sh restart -b
./planet.sh restart -a
./planet.sh restart -d # 5. 数据库 / 缓存异常时
./planet.sh restart # 6. 仍无法恢复时全量重启
```
## 开发命令约定
前端必须使用 Bun:
```bash
cd frontend
bun install
bun run dev
bun run build
```
不要使用 `npm run ...`。项目在 WSL / Windows 混合环境优先依赖 Bun,避免 Node/npm 路径差异。
验证前端构建:
```bash
source ~/.zshrc && bun run build
```
后端依赖通过 uv 管理:
```bash
uv sync
uv run pytest backend/tests/test_otp_service.py
```
## 相关文档
- [planet.sh 启动机制](/home/ray/dev/linkong/planet/docs/technical/zh/ops-planet-sh-startup.md)
- [系统服务控制](/home/ray/dev/linkong/planet/docs/technical/zh/backend-system-service-control.md)
- [Docker + Compose + Buildx 升级](/home/ray/dev/linkong/planet/docs/technical/zh/ops-docker-compose-buildx-upgrade.md)
- [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
+39 -209
View File
@@ -1,236 +1,66 @@
# 快速开始
这份快速开始面向第一次启动 Planet 的开发者或演示操作者。目标是用最短路径把服务跑起来,并知道应该打开哪些入口。
这份快速开始面向 Planet 的最终用户:你拿到了管理员给的访问地址,要从打开浏览器到第一次完成配置之间的最短路径。所有操作都在浏览器里完成。
如果遇到端口占用、Windows / WSL 局域网访问、`uv` / `bun`、摄像头或 Docs 权限问题,先看 [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)。
如果你是负责部署或运维的同事,请改读 [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)。
## 前置条件
## 1. 打开访问地址
推荐在 WSL / Linux shell 中运行。
打开管理员给的 URL,例如 `http://planet.example.com`。本地演示一般是 `http://localhost:3000`。
需要具备:
入口分两类:
- Docker / Docker Compose 可用
- 当前 shell 能访问 `uv` 和 `bun`
- 仓库已 clone 到本机
- 公开页:`/earth`(3D 态势)、`/docs`(公共文档)
- 登录后:`/admin`(控制台)、`/ai`(AI)、`/settings`(系统配置)
如果是新机器,优先执行仓库自带初始化脚本:
## 2. 注册账号
```bash
./scripts/bootstrap-dev.sh
```
1. 打开 `/login`,点击表单下方"注册账户"。
2. 在 `/register` 填用户名、邮箱、密码(至少 8 位)。
3. 提交后,到邮箱查收 6 位验证码(10 分钟内有效)。
4. 在验证页输入验证码,点击"验证并登录",系统会自动跳到控制台。
这个脚本会检查并同步常用依赖,并在缺少时生成:
收不到邮件时:
- `backend/.env`
- `aiprovider/.env`
- `frontend/.env.local`
- 看一下垃圾邮件或企业邮件网关
- 验证页右下角的"重新发送验证码"会显示倒计时,结束后可以重发
- 提示"邮件服务尚未配置"时联系管理员开 SMTP
AI Provider 的个人配置也可以放在 `~/.zshrc`。`planet.sh` 会读取简单的 `export AI_...=...` 或 `AI_...=...` 行,并在启动 AI Provider 时传给容器。修改模型、密钥或 Base URL 后,通常只需要重启 AI Provider:
默认角色是 `viewer`,可登录但只能看公共内容。要看采集器、用户管理、系统设置,请联系管理员升级角色或加 Gatekeeper 权限组。
```bash
./planet.sh restart -a
```
## 3. 第一次登录
AISStream、BarentsWatch 等采集器凭证也可以先写在 `~/.zshrc` 里供连接验证读取,例如:
进入 `/admin` 仪表盘后,建议按这个顺序熟悉控制台:
```bash
export AISSTREAM_API_KEY="..."
export BARENTSWATCH_CLIENT_ID="..."
export BARENTSWATCH_CLIENT_SECRET="..."
```
1. `/settings?tab=collector_credentials`:选一个采集器,点插头图标做连接测试。免费 collector(开源 BGP 等)通常直接可用;像 `AISStream`、`BarentsWatch` 这类需要凭证的,需要先填 API Key/Client Secret
2. `/ai?tab=providers`:填一个 LLM provider(例如 `minimax` / `openai`)、模型名、Base URL、API Key,点 Base URL 末端的插头测试连接。WebSearch / OCR 工具可选
3. `/datasources` 或 `/data`:看采集器是否已经产出数据。有限采集器看 `/datasources -> 采集任务`,AISStream / WebSocket 长连接看 `/datasources -> 实时流` 的健康状态和计数
4. `/alerts/system`:看系统告警是否正常
5. `/users`(仅 `super_admin`):根据需要给同事开账号或调权限组
正式采集更推荐在控制台 `设置 -> 采集器设置` 保存凭证,尤其是 AISStream 这类长连接 WebSocket collector。这样连接验证、后端采集任务和 Earth 实时船只聚合会使用同一份配置。
## 4. 打开 Earth
## 1. 启动服务
访问 `/earth`,公开页面,不需要登录。
在仓库根目录执行:
进入后建议确认:
```bash
./planet.sh start
```
启动完成后,常用入口是:
| 入口 | 默认地址 | 用途 |
| --- | --- | --- |
| Earth | `http://localhost:3000/earth` | 公开 3D Earth 可视化页面 |
| 控制台 | `http://localhost:3000/admin` | 登录后的管理后台 |
| 文档站 | `http://localhost:3000/docs` | 使用手册公开;开发/运维文档按 Gatekeeper 权限组开放 |
| AI | `http://localhost:3000/ai` | 登录后的模型供应商、工具和测试台入口 |
| 后端 API 文档 | `http://localhost:8000/docs` | FastAPI / OpenAPI 接口文档 |
如果默认端口被占用,可以指定端口:
```bash
./planet.sh start -f 3001 -b 8001 -a 8101
```
后端 `8000` 被 Windows listener 或旧 portproxy 占用时,排查顺序见 [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)。
## 2. 创建登录用户
控制台需要登录。首次使用可以执行:
```bash
./planet.sh createuser
```
按提示输入用户名、密码和角色。
如果需要阅读开发或运维文档,用 `super_admin` 登录控制台后,在“用户管理”里给目标用户分配 Gatekeeper 权限组:`docs_developer` 用于开发文档,`docs_admin` 用于服务控制和运维文档。
## 3. 打开 Earth
访问:
```text
http://localhost:3000/earth
```
Earth 是公开页面,不需要登录。
进入后可以先确认:
- 地球正常显示
- 右侧图层控制可打开/关闭图层
- 地球正常显示,右侧图层面板可以打开/关闭
- 搜索可以查找海缆、卫星、算力中心、BGP 事件
- 算力中心和 BGP 观测站详情卡可以自动采集并预览坐标候选;常规来源无候选时会用当前默认 AI Provider 做 LLM factcheck 兜底;算力中心待定位气泡可以打开列表并保存候选
- 鼠标拖动、滚轮缩放和缩放百分比提示正常工作
- 设置面板可以切换旋转 / 巡航 / 动捕模式、日夜模式、卫星显示风格;动捕调试模式下浏览器摄像头可显示本机预览和骨架
- 算力中心和 BGP 观测站详情卡可以自动采集坐标候选,并能在 Earth 上预览
- 鼠标拖动、滚轮缩放、缩放百分比提示工作正常
- 设置面板的旋转 / 巡航 / 动捕模式可以切换;视图设置里可以切换悬停提示,卫星相关设置里可以打开或关闭真实高度分层和轨迹显示
## 4. 打开控制台
## 5. 找回密码
访问:
忘记密码时打开 `/forgot-password`,输入邮箱并接收验证码,再输入验证码 + 新密码即可。系统对未注册的邮箱也会返回同样的提示(防止账号枚举)。
```text
http://localhost:3000/admin
```
## 6. 看文档
控制台用于数据源、采集数据、专题观测、告警、系统日志和配置管理。
首次排查建议查看:
- `/datasources`:数据源目录和采集触发;接口、请求头和凭证配置在 `/settings` 的“采集器设置”
- `/data`:已采集数据
- `/bgp`:BGP 专题观测
- `/ai`:AI,管理模型供应商、WebSearch 等工具和测试台
- `/alerts/system`:系统告警
- `/settings`:系统配置
## 5. 查看运行状态
```bash
./planet.sh health
```
这个命令会显示容器状态,并检查:
- 后端
- AI Provider
- 前端
## 6. 查看日志
最近日志:
```bash
./planet.sh log
```
持续查看某个服务:
```bash
./planet.sh log -f
./planet.sh log -b
./planet.sh log -a
```
含义:
- `-f`:前端日志
- `-b`:后端日志
- `-a`:AI Provider 日志
## 7. 常用重启
只重启前端:
```bash
./planet.sh restart -f
```
只重启后端:
```bash
./planet.sh restart -b
```
只重启 AI Provider:
```bash
./planet.sh restart -a
```
只重启数据库:
```bash
./planet.sh restart -d
```
全量重启:
```bash
./planet.sh restart
```
## 8. 局域网访问
如果希望 Windows 浏览器、手机或同一局域网的其他设备访问:
```bash
./planet.sh start --allow-lan
```
这会让前端和后端监听局域网可访问地址。
注意:`--allow-lan` 只负责让 Planet 服务监听 `0.0.0.0`,不等于自动把 WSL 服务暴露到 Windows 局域网 IP。常见情况是:
- WSL 内 `localhost:3000` / `localhost:8000` 能访问
- Windows 本机 `localhost:3000` / `localhost:8000` 能访问
- 但手机或其他电脑访问 `http://<Windows局域网IP>:3000` 失败
这通常说明 Windows 端还缺少端口转发或防火墙放行。
如果访问失败,先在运行 Planet 的 shell 中检查:
```bash
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'
```
如果确认 WSL 中已监听 `0.0.0.0:3000` 和 `0.0.0.0:8000`,但局域网 IP 仍不能访问,请在管理员 PowerShell 中配置 Windows 端转发和防火墙:
```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```
## 9. 停止服务
```bash
./planet.sh stop
```
停止后会关闭前端、后端、AI Provider、PostgreSQL 和 Redis。
`/docs` 是文档站。未登录可看:本快速开始、使用手册、常见问题。登录后被分配 `docs_user` / `docs_developer` / `docs_admin` 权限组的用户可以看更多技术文档。
## 下一步
- 完整操作说明见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)
- 控制台结构见 [控制台前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
- Earth 结构见 [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
- 后端采集器见 [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
- 完整 UI 操作说明:[Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)
- 排障与配置疑问:[常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)
- Earth 坐标候选采集详细流程:[Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)
- 部署 / 运维相关命令:[Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)
+7 -1
View File
@@ -16,12 +16,18 @@
## Current Version
- `main` 当前主线历史推导到:`0.16.5`
- `dev` 当前开发分支历史推导到:`0.51.1`
- `dev` 当前开发分支历史推导到:`0.57.0`
## Timeline
| Version | Type | Branch | Commit | Summary |
| --- | --- | --- | --- | --- |
| `0.57.0` | feature | `dev` | `pending` | WSL `--allow-lan` 新增临时 Windows relay,保持 localhost 与局域网同用 3000/8000,并自动处理旧 portproxy、防火墙授权和 Vite ESM 配置 |
| `0.56.0` | feature | `dev` | `pending` | 修复 Earth 卫星 ECI/TEME 到 ECF 坐标转换和闭合预测轨道,调校真实高度压缩上限,统一 BGP 光晕色调,并更新超算图标与 Earth HUD/新闻体验 |
| `0.55.0` | feature | `dev` | `pending` | Earth 卫星新增真实高度压缩显示开关,轨迹和预测轨道跟随高度模式切换,并补齐设置面板、FAQ、用户手册和开发者文档 |
| `0.54.0` | feature | `dev` | `pending` | 新增 Earth 轨迹显示设置并迁移到桌面/移动设置面板,持久化轨迹偏好,同时优化卫星呼吸闪烁参数和算力中心图标资产 |
| `0.53.0` | feature | `dev` | `pending` | 新增 Gitea Actions CI/CD、生产镜像、Kubernetes Helm chart 与 staging 部署 smoke test,明确 Vite 生产构建和 planet.sh 开发入口边界 |
| `0.52.0` | feature | `dev` | `pending` | 新增邮箱验证码账号自助链路、AISStream 船只实时采集与受控 snapshot/WS 展示、数据产品统计接口、受控图层接口和数据源批量运维 |
| `0.51.1` | bugfix | `dev` | `pending` | 修复 Earth 静态资源模块相对路径与 Material Symbols 本地字体加载,避免部署路径变化或外部字体不可用时图标/边界资源失效 |
| `0.51.0` | feature | `dev` | `pending` | 新增 AI Settings 控制台与 ai_tools 工具层;重写算力中心候选预览/保存交互(呼吸圈 + 即时图标);动作捕捉 zoom 改为 mirror-safe trend + pose hold 双通道,支持持续触发 |
| `0.50.0` | feature | `dev` | `pending` | 新增 Earth 动捕双通道控制、Motion Agent、Presentation 持久展示、AI Provider 多 provider 设置、位置候选 LLM 兜底与 FAQ |
+6
View File
@@ -0,0 +1,6 @@
node_modules
dist
.vite
*.log
coverage
.DS_Store
+11 -2
View File
@@ -1,4 +1,4 @@
FROM oven/bun:1-alpine
FROM oven/bun:1-alpine AS build
WORKDIR /app
@@ -6,7 +6,16 @@ COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun run build
FROM nginx:1.27-alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 3000
CMD ["bun", "run", "dev", "--", "--host", "0.0.0.0"]
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD wget -qO- http://127.0.0.1:3000/health >/dev/null || exit 1
CMD ["nginx", "-g", "daemon off;"]
+5
View File
@@ -19,6 +19,7 @@
"zustand": "^4.4.7",
},
"devDependencies": {
"@types/node": "^24.0.0",
"@types/react": "^18.2.45",
"@types/react-dom": "^18.2.18",
"@vitejs/plugin-react": "^4.2.1",
@@ -226,6 +227,8 @@
"@types/estree": ["@types/estree@1.0.8", "", {}, "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w=="],
"@types/node": ["@types/node@24.12.4", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GUUEShf+PBCGW2KaXwcIt3Yk+e3pkKwWKb9GSyM9WQVE+ep2jzmHdGsHzu4wgcZy5fN9FBdVzjpBQsYlpfpgLA=="],
"@types/prop-types": ["@types/prop-types@15.7.15", "", {}, "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw=="],
"@types/react": ["@types/react@18.3.27", "", { "dependencies": { "@types/prop-types": "*", "csstype": "^3.2.2" } }, "sha512-cisd7gxkzjBKU2GgdYrTdtQx1SORymWyaAFhaxQPK9bYO9ot3Y5OikQRvY0VYQtvwjeQnizCINJAenh/V7MK2w=="],
@@ -458,6 +461,8 @@
"typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
"undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
"update-browserslist-db": ["update-browserslist-db@1.2.3", "", { "dependencies": { "escalade": "^3.2.0", "picocolors": "^1.1.1" }, "peerDependencies": { "browserslist": ">= 4.21.0" }, "bin": "cli.js" }, "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w=="],
"use-sync-external-store": ["use-sync-external-store@1.6.0", "", { "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w=="],
+56
View File
@@ -0,0 +1,56 @@
server {
listen 3000;
server_name _;
root /usr/share/nginx/html;
index index.html;
gzip on;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;
location = /health {
add_header Content-Type text/plain;
return 200 "ok\n";
}
location = /api/health {
proxy_pass http://planet-backend:8000/health;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/ {
proxy_pass http://planet-backend:8000/api/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /ws {
proxy_pass http://planet-backend:8000/ws;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location = /index.html {
add_header Cache-Control "no-store";
try_files $uri =404;
}
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable";
try_files $uri =404;
}
location / {
try_files $uri $uri/ /index.html;
}
}
+2 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planet-frontend",
"version": "0.51.1",
"version": "0.57.0",
"private": true,
"packageManager": "bun@1",
"dependencies": {
@@ -20,6 +20,7 @@
"devDependencies": {
"@types/react": "^18.2.45",
"@types/react-dom": "^18.2.18",
"@types/node": "^24.0.0",
"@vitejs/plugin-react": "^4.2.1",
"typescript": "^5.3.3",
"vite": "^5.0.10"
@@ -1,3 +1,3 @@
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="#38bdf8" class="bi bi-pc" viewBox="0 0 16 16">
<path d="M5 0a1 1 0 0 0-1 1v14a1 1 0 0 0 1 1h6a1 1 0 0 0 1-1V1a1 1 0 0 0-1-1H5Zm.5 14a.5.5 0 1 1 0 1 .5.5 0 0 1 0-1Zm2 0a.5.5 0 1 1 0 1 .5.5 0 0 1 0-1ZM5 1.5a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5ZM5.5 3h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1 0-1Z"/>
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="#38bdf8" class="bi bi-buildings-fill" viewBox="0 0 16 16">
<path d="M15 .5a.5.5 0 0 0-.724-.447l-8 4A.5.5 0 0 0 6 4.5v3.14L.342 9.526A.5.5 0 0 0 0 10v5.5a.5.5 0 0 0 .5.5h9a.5.5 0 0 0 .5-.5V14h1v1.5a.5.5 0 0 0 .5.5h3a.5.5 0 0 0 .5-.5V.5ZM2 11h1v1H2v-1Zm2 0h1v1H4v-1Zm-1 2v1H2v-1h1Zm1 0h1v1H4v-1Zm9-10v1h-1V3h1ZM8 5h1v1H8V5Zm1 2v1H8V7h1ZM8 9h1v1H8V9Zm2 0h1v1h-1V9Zm-1 2v1H8v-1h1Zm1 0h1v1h-1v-1Zm3-2v1h-1V9h1Zm-1 2h1v1h-1v-1Zm-2-4h1v1h-1V7Zm3 0v1h-1V7h1Zm-2-2v1h-1V5h1Zm1 0h1v1h-1V5Z"/>
</svg>

Before

Width:  |  Height:  |  Size: 383 B

After

Width:  |  Height:  |  Size: 562 B

+3 -3
View File
@@ -1,7 +1,7 @@
/* earth-stats.css — compact KPI grid panel */
.hud-panel-stats {
top: var(--hud-offset);
bottom: var(--hud-offset);
right: var(--hud-offset);
border-radius: 0; /* square / angular — matches layer panel */
padding: 0;
@@ -129,9 +129,9 @@
/* ── Layout-expanded: slide off-screen ───────────────────────── */
.earth-app.layout-expanded .hud-panel-stats:not([data-dragged="true"]) {
top: var(--hud-offset);
bottom: var(--hud-offset);
right: var(--hud-offset);
transform: translate(calc(100% - var(--hud-offset)), calc(-100% + var(--hud-offset)));
transform: translate(calc(100% - var(--hud-offset)), calc(100% - var(--hud-offset)));
}
.layout-mode-mobile .hud-panel-stats {
Loaded 100 of 138 files, more files were not shown because too many files have changed in this diff. Show more