194 lines
3.7 KiB
Markdown
194 lines
3.7 KiB
Markdown
# Quickstart
|
||
|
||
这份 Quickstart 面向第一次启动 Planet 的开发者或演示操作者。目标是用最短路径把服务跑起来，并知道应该打开哪些入口。
|
||
|
||
## 前置条件
|
||
|
||
推荐在 WSL / Linux shell 中运行。
|
||
|
||
需要具备：
|
||
|
||
- Docker / Docker Compose 可用
|
||
- 当前 shell 能访问 `uv` 和 `bun`
|
||
- 仓库已 clone 到本机
|
||
|
||
如果是新机器，优先执行仓库自带初始化脚本：
|
||
|
||
```bash
|
||
./scripts/bootstrap-dev.sh
|
||
```
|
||
|
||
这个脚本会检查并同步常用依赖，并在缺少时生成：
|
||
|
||
- `backend/.env`
|
||
- `aiprovider/.env`
|
||
- `frontend/.env.local`
|
||
|
||
## 1. 启动服务
|
||
|
||
在仓库根目录执行：
|
||
|
||
```bash
|
||
./planet.sh start
|
||
```
|
||
|
||
启动完成后，常用入口是：
|
||
|
||
| 入口 | 默认地址 | 用途 |
|
||
| --- | --- | --- |
|
||
| Earth | `http://localhost:3000/earth` | 公开 3D Earth 可视化页面 |
|
||
| 控制台 | `http://localhost:3000/admin` | 登录后的管理后台 |
|
||
| 文档站 | `http://localhost:3000/docs` | 公开开发文档和使用手册 |
|
||
| AI Playground | `http://localhost:3000/playground` | 登录后的 AI 调试入口 |
|
||
| 后端 API 文档 | `http://localhost:8000/docs` | FastAPI / OpenAPI 接口文档 |
|
||
|
||
如果默认端口被占用，可以指定端口：
|
||
|
||
```bash
|
||
./planet.sh start -f 3001 -b 8001 -a 8101
|
||
```
|
||
|
||
## 2. 创建登录用户
|
||
|
||
控制台需要登录。首次使用可以执行：
|
||
|
||
```bash
|
||
./planet.sh createuser
|
||
```
|
||
|
||
按提示输入用户名、密码和角色。
|
||
|
||
## 3. 打开 Earth
|
||
|
||
访问：
|
||
|
||
```text
|
||
http://localhost:3000/earth
|
||
```
|
||
|
||
Earth 是公开页面，不需要登录。
|
||
|
||
进入后可以先确认：
|
||
|
||
- 地球正常显示
|
||
- 右侧图层控制可打开/关闭图层
|
||
- 搜索可以查找海缆、卫星、算力中心、BGP 事件
|
||
- 设置面板可以切换巡航模式、日夜模式、卫星显示风格
|
||
|
||
## 4. 打开控制台
|
||
|
||
访问：
|
||
|
||
```text
|
||
http://localhost:3000/admin
|
||
```
|
||
|
||
控制台用于数据源、采集数据、专题观测、告警、系统日志和配置管理。
|
||
|
||
首次排查建议查看：
|
||
|
||
- `/datasources`：数据源配置和采集状态
|
||
- `/data`：已采集数据
|
||
- `/bgp`：BGP 专题观测
|
||
- `/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
|
||
```
|
||
|
||
这会让前端和后端监听局域网可访问地址。
|
||
|
||
如果访问失败，先在运行 Planet 的 shell 中检查：
|
||
|
||
```bash
|
||
curl http://localhost:3000
|
||
curl http://localhost:8000/health
|
||
ss -ltnp | grep -E ':3000|:8000'
|
||
```
|
||
|
||
## 9. 停止服务
|
||
|
||
```bash
|
||
./planet.sh stop
|
||
```
|
||
|
||
停止后会关闭前端、后端、AI Provider、PostgreSQL 和 Redis。
|
||
|
||
## 下一步
|
||
|
||
- 完整操作说明见 [manual.md](/home/ray/dev/linkong/planet/docs/technical/manual.md)
|
||
- 控制台结构见 [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/frontend-admin-frontend-context.md)
|
||
- Earth 结构见 [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/earth-frontend-context.md)
|
||
- 后端采集器见 [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/backend-collectors.md)
|