linkong/planet
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

release: bump version to 0.52.0

Browse Source
This commit is contained in:
linkong
2026-05-12 17:15:02 +08:00
parent b15d097b9c
commit b87cb310fd
70 changed files with 5589 additions and 2187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

248
docs/technical/zh/quickstart.md
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`：看采集器是否已经产出数据
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)