planet/docs/technical/zh/quickstart.md

快速开始

这份快速开始面向第一次启动 Planet 的开发者或演示操作者。目标是用最短路径把服务跑起来，并知道应该打开哪些入口。

如果遇到端口占用、Windows / WSL 局域网访问、uv / bun、摄像头或 Docs 权限问题，先看 常见问题。

前置条件

推荐在 WSL / Linux shell 中运行。

需要具备：

• Docker / Docker Compose 可用
• 当前 shell 能访问 uv 和 bun
• 仓库已 clone 到本机

如果是新机器，优先执行仓库自带初始化脚本：

./scripts/bootstrap-dev.sh

这个脚本会检查并同步常用依赖，并在缺少时生成：

• backend/.env
• aiprovider/.env
• frontend/.env.local

AI Provider 的个人配置也可以放在 ~/.zshrc。planet.sh 会读取简单的 export AI_...=... 或 AI_...=... 行，并在启动 AI Provider 时传给容器。修改模型、密钥或 Base URL 后，通常只需要重启 AI Provider：

./planet.sh restart -a

AISStream、BarentsWatch 等采集器凭证也可以先写在 ~/.zshrc 里供连接验证读取，例如：

export AISSTREAM_API_KEY="..."
export BARENTSWATCH_CLIENT_ID="..."
export BARENTSWATCH_CLIENT_SECRET="..."

正式采集更推荐在控制台 设置 -> 采集器设置 保存凭证，尤其是 AISStream 这类长连接 WebSocket collector。这样连接验证、后端采集任务和 Earth 实时船只聚合会使用同一份配置。

1. 启动服务

在仓库根目录执行：

./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 接口文档

如果默认端口被占用，可以指定端口：

./planet.sh start -f 3001 -b 8001 -a 8101

后端 8000 被 Windows listener 或旧 portproxy 占用时，排查顺序见 常见问题。

2. 创建登录用户

控制台需要登录。首次使用可以执行：

./planet.sh createuser

按提示输入用户名、密码和角色。

如果需要阅读开发或运维文档，用 super_admin 登录控制台后，在“用户管理”里给目标用户分配 Gatekeeper 权限组：docs_developer 用于开发文档，docs_admin 用于服务控制和运维文档。

3. 打开 Earth

访问：

http://localhost:3000/earth

Earth 是公开页面，不需要登录。

进入后可以先确认：

• 地球正常显示
• 右侧图层控制可打开/关闭图层
• 搜索可以查找海缆、卫星、算力中心、BGP 事件
• 算力中心和 BGP 观测站详情卡可以自动采集并预览坐标候选；常规来源无候选时会用当前默认 AI Provider 做 LLM factcheck 兜底；算力中心待定位气泡可以打开列表并保存候选
• 鼠标拖动、滚轮缩放和缩放百分比提示正常工作
• 设置面板可以切换旋转 / 巡航 / 动捕模式、日夜模式、卫星显示风格；动捕调试模式下浏览器摄像头可显示本机预览和骨架

4. 打开控制台

访问：

http://localhost:3000/admin

控制台用于数据源、采集数据、专题观测、告警、系统日志和配置管理。

首次排查建议查看：

• /datasources：数据源目录和采集触发；接口、请求头和凭证配置在 /settings 的“采集器设置”
• /data：已采集数据
• /bgp：BGP 专题观测
• /ai：AI，管理模型供应商、WebSearch 等工具和测试台
• /alerts/system：系统告警
• /settings：系统配置

5. 查看运行状态

./planet.sh health

这个命令会显示容器状态，并检查：

• 后端
• AI Provider
• 前端

6. 查看日志

最近日志：

./planet.sh log

持续查看某个服务：

./planet.sh log -f
./planet.sh log -b
./planet.sh log -a

含义：

• -f：前端日志
• -b：后端日志
• -a：AI Provider 日志

7. 常用重启

只重启前端：

./planet.sh restart -f

只重启后端：

./planet.sh restart -b

只重启 AI Provider：

./planet.sh restart -a

只重启数据库：

./planet.sh restart -d

全量重启：

./planet.sh restart

8. 局域网访问

如果希望 Windows 浏览器、手机或同一局域网的其他设备访问：

./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 中检查：

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 端转发和防火墙：

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. 停止服务

./planet.sh stop

停止后会关闭前端、后端、AI Provider、PostgreSQL 和 Redis。

下一步

• 完整操作说明见 Planet 使用手册
• 控制台结构见 控制台前端结构
• Earth 结构见 Earth 前端结构
• 后端采集器见 数据采集系统