release: bump version to 0.42.0

docs/technical/zh/quickstart.md

@@ -0,0 +1,193 @@
+# 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)