364 lines
15 KiB
Markdown
364 lines
15 KiB
Markdown
# 常见问题
|
||
|
||
这页集中收录本地启动、Windows / WSL、依赖、动捕、凭证和文档权限相关的常见排障路径。更完整的背景说明仍在对应专题文档中，这里只保留最常用的判断顺序和命令。
|
||
|
||
## 启动与端口
|
||
|
||
### 启动时报后端地址已被占用怎么办？
|
||
|
||
现象通常类似：
|
||
|
||
```text
|
||
后端地址已被占用: 0.0.0.0:8000 / 127.0.0.1:8000 / [::1]:8000
|
||
Address already in use
|
||
```
|
||
|
||
先尝试：
|
||
|
||
```bash
|
||
./planet.sh restart -b
|
||
```
|
||
|
||
如果仍然占用，临时换端口：
|
||
|
||
```bash
|
||
./planet.sh start -b 8001
|
||
```
|
||
|
||
在 WSL 中，端口可能不是 Linux 进程占用，而是 Windows 侧 listener。常见输出如下：
|
||
|
||
```text
|
||
Windows listener: 0.0.0.0:8000 pid=4700 process=svchost.exe services=iphlpsvc
|
||
```
|
||
|
||
`iphlpsvc` 是 Windows IP Helper 服务。它经常承载 IPv6、隧道、代理、端口转发、WSL 或开发工具注册的网络能力。不要优先 `taskkill` 这个 `svchost.exe`；更推荐先找是不是旧的 portproxy 规则。
|
||
|
||
管理员 PowerShell 中先查 portproxy：
|
||
|
||
```powershell
|
||
netsh interface portproxy show all
|
||
```
|
||
|
||
如果看到 `0.0.0.0:8000` 或 `listenport=8000`，删除对应规则：
|
||
|
||
```powershell
|
||
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
|
||
```
|
||
|
||
如果没有 portproxy 规则，再确认 PID 内承载的服务：
|
||
|
||
```powershell
|
||
netstat -ano | findstr :8000
|
||
tasklist /svc /fi "PID eq 4700"
|
||
```
|
||
|
||
临时排障可以在管理员 PowerShell 中停止 IP Helper：
|
||
|
||
```powershell
|
||
Stop-Service iphlpsvc -Force
|
||
```
|
||
|
||
这可能影响部分网络、代理或转发能力。长期不推荐禁用该服务；`--allow-lan` 会直接绑定 `3000` / `8000` / `8010`，不再需要保留持久 portproxy。
|
||
|
||
如果脚本输出 `Windows 侧端口 ... 存在监听者`，或 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`，局域网仍访问 `3000` / `8000` / `8010`。
|
||
|
||
### 默认端口冲突时应该改哪些参数？
|
||
|
||
常用端口如下：
|
||
|
||
| 服务 | 默认端口 | 参数 |
|
||
| --- | --- | --- |
|
||
| 前端 | `3000` | `-f <port>` |
|
||
| 后端 | `8000` | `-b <port>` |
|
||
| AI Provider | `8010` | `-a <port>` |
|
||
| Motion Agent | `8765` | `--motion-agent-port <port>` |
|
||
|
||
示例：
|
||
|
||
```bash
|
||
./planet.sh start -f 3001 -b 8001 -a 8101
|
||
```
|
||
|
||
## Windows / WSL / 局域网
|
||
|
||
### Windows / WSL 下局域网访问不通怎么办？
|
||
|
||
建议按下面顺序排查：
|
||
|
||
```bash
|
||
# 在 WSL 或运行 Planet 的 shell 中
|
||
curl http://localhost:3000
|
||
curl http://localhost:8000/health
|
||
curl http://localhost:8010/health
|
||
```
|
||
|
||
再到 Windows PowerShell 验证：
|
||
|
||
```powershell
|
||
curl http://localhost:3000
|
||
curl http://localhost:8000/health
|
||
curl http://localhost:8010/health
|
||
```
|
||
|
||
如果 WSL 和 Windows localhost 都通，但手机或其他电脑访问不通，再考虑局域网开放：
|
||
|
||
```bash
|
||
./planet.sh start --allow-lan
|
||
```
|
||
|
||
参数必须写成 `--allow-lan`。`allowlan` 或 `--allowlan` 不会被启动脚本识别。如果服务已经启动，只想重新开放前端，需要显式重启前端：
|
||
|
||
```bash
|
||
./planet.sh restart -f 3000 --allow-lan
|
||
```
|
||
|
||
如果 `ss -ltnp` 显示前端已经监听 `0.0.0.0:3000`，但 Windows PowerShell 中 `Test-NetConnection <Windows局域网IP> -Port 3000` 仍失败，问题通常不在 Vite 或 `.zshrc`，而是在 Windows 侧端口占用、旧 `portproxy` 或防火墙。
|
||
|
||
`./planet.sh start --allow-lan` 会直接开放 `3000` / `8000` / `8010`，并在启动前检测端口、旧 `portproxy` 和 Windows 防火墙规则。端口被 Windows 侧 listener 占用时，脚本会请求管理员 PowerShell 清理；缺少入站允许规则时，也会触发一次 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
|
||
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010
|
||
|
||
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
|
||
New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010
|
||
```
|
||
|
||
局域网设备访问 Windows 对外端口，例如 `http://<Windows局域网IP>:3000/earth`。
|
||
|
||
如果 `wslinfo --networking-mode` 输出 `mirrored`，还需要检查 Hyper-V firewall。普通 Windows 防火墙规则存在时，Hyper-V firewall 仍可能拦截外部设备进入 WSL。管理员 PowerShell 中按端口开放访问：
|
||
|
||
```powershell
|
||
New-NetFirewallHyperVRule -Name "Planet-Frontend-3000" -DisplayName "Planet Frontend 3000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 3000 -Action Allow
|
||
New-NetFirewallHyperVRule -Name "Planet-Backend-8000" -DisplayName "Planet Backend 8000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8000 -Action Allow
|
||
New-NetFirewallHyperVRule -Name "Planet-AIProvider-8010" -DisplayName "Planet AI Provider 8010" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8010 -Action Allow
|
||
```
|
||
|
||
也可以用下面命令确认当前 Hyper-V firewall 状态：
|
||
|
||
```powershell
|
||
Get-NetFirewallHyperVVMSetting -Name "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}"
|
||
Get-NetFirewallHyperVRule -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}"
|
||
```
|
||
|
||
局域网设备访问的是 Windows 的局域网 IP，例如 `http://<Windows局域网IP>:3000/earth`，不是 WSL 内部 IP。
|
||
|
||
### `--allow-lan` 和 Motion Agent 局域网地址怎么配？
|
||
|
||
`--allow-lan` 会让前端、后端和可选 Motion Agent 监听 `0.0.0.0`。如果远端浏览器要连本机 Motion Agent，Earth URL 需要显式带 Agent 地址：
|
||
|
||
```text
|
||
http://<LAN_IP>:3000/earth?motion=1&motionProvider=agent&motionAgent=ws://<LAN_IP>:8765/ws/gestures
|
||
```
|
||
|
||
如果选择浏览器摄像头输入源，不需要 `motionAgent` 参数。
|
||
|
||
## 依赖与环境变量
|
||
|
||
### 为什么不要用 `pip`，要用 `uv`？
|
||
|
||
Planet 的 Python 依赖统一由 `uv` 和 `pyproject.toml` 管理。不要用 `pip install` 往当前环境里塞包，否则容易出现锁文件、虚拟环境和启动脚本不一致。
|
||
|
||
Motion Agent live 模式缺依赖时，推荐：
|
||
|
||
```bash
|
||
uv add mediapipe opencv-python
|
||
```
|
||
|
||
`planet.sh start --motion-agent` 会自动检查并安装这些 live 依赖。若要禁止自动安装：
|
||
|
||
```bash
|
||
PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start --motion-agent
|
||
```
|
||
|
||
### 为什么不要用 `npm run`，要用 `bun`？
|
||
|
||
前端运行时统一使用 Bun，避免 WSL / Windows 混合环境里触发 `cmd.exe` 路径兼容问题。
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
bun install
|
||
bun run dev
|
||
bun run build
|
||
```
|
||
|
||
如果非交互 shell 找不到 `bun`，`planet.sh` 会依次查找当前 PATH、`~/.bun/bin`、zsh 配置和 PowerShell 中的可执行路径。
|
||
|
||
### `.zshrc` 里的环境变量什么时候会被读取？
|
||
|
||
`planet.sh` 默认只静态解析 `~/.zshrc` 中简单的：
|
||
|
||
```bash
|
||
export KEY=value
|
||
KEY=value
|
||
```
|
||
|
||
这样可以避免 shell 主题、插件或交互初始化拖慢启动。复杂 shell 展开需要显式启用 source 模式：
|
||
|
||
```bash
|
||
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
|
||
```
|
||
|
||
如果排障时想完全忽略 `~/.zshrc`：
|
||
|
||
```bash
|
||
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
|
||
```
|
||
|
||
不要把密钥值写进文档或提交到仓库；文档只应写变量名和用途。
|
||
|
||
## Motion Capture / 摄像头
|
||
|
||
### Browser Camera 模式需要 `motionAgent` 参数吗？
|
||
|
||
不需要。浏览器摄像头模式直接用网页 `getUserMedia` 调本机摄像头，并在浏览器本地识别动作。
|
||
|
||
推荐 URL：
|
||
|
||
```text
|
||
/earth?motion=1&motionProvider=browser
|
||
```
|
||
|
||
也可以在 Earth 设置中打开“动捕调试模式”，并把“动捕输入源”选为“浏览器摄像头”。页面必须运行在 HTTPS 或 localhost，且用户需要允许浏览器摄像头权限。
|
||
|
||
### Motion Agent 什么时候才需要？
|
||
|
||
这些场景才需要 Motion Agent：
|
||
|
||
- 双 USB 摄像头
|
||
- RTSP / HTTP 摄像头流
|
||
- 边缘设备或客户端集成
|
||
- 需要独立本地识别服务
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
./planet.sh start --motion-agent
|
||
./planet.sh start --motion-agent --motion-agent-camera-indexes 0,1
|
||
./planet.sh start --motion-agent --motion-agent-camera-urls rtsp://example/live
|
||
./planet.sh start --motion-agent --motion-agent-dry-run
|
||
```
|
||
|
||
`--motion-agent-dry-run` 只用于协议和前端连接测试，不会打开摄像头。
|
||
|
||
### WSL 下摄像头为什么扫不到？
|
||
|
||
Windows 摄像头通常不会自动出现在 WSL 的 `/dev/video*`。先确认：
|
||
|
||
```bash
|
||
ls /dev/video*
|
||
```
|
||
|
||
如果没有设备，普通网页演示优先走 Browser Camera。需要 Agent live 模式时，可以用 RTSP / HTTP 摄像头 URL：
|
||
|
||
```bash
|
||
./planet.sh start --motion-agent --motion-agent-camera-urls http://192.168.1.20:8080/video
|
||
```
|
||
|
||
USB 摄像头透传到 WSL 属于高级路径；脚本不会默认把无摄像头场景降级成 dry-run。
|
||
|
||
## Docker / AI Provider
|
||
|
||
### AI Provider 改了 key、Base URL 或模型后为什么没有重建镜像？
|
||
|
||
密钥、Base URL、模型这类运行期配置变化不会触发 Docker 镜像重建。重启 AI Provider 即可：
|
||
|
||
```bash
|
||
./planet.sh restart -a
|
||
```
|
||
|
||
首次构建慢通常是 Docker build context、镜像层或 `uv sync` 下载依赖耗时。后续构建会复用 `.dockerignore`、BuildKit 和 uv cache。
|
||
|
||
### Docker 健康检查没过怎么办？
|
||
|
||
先看统一健康检查：
|
||
|
||
```bash
|
||
./planet.sh health
|
||
```
|
||
|
||
再看日志：
|
||
|
||
```bash
|
||
./planet.sh log
|
||
```
|
||
|
||
如果只有 AI Provider 异常，优先重启单个服务：
|
||
|
||
```bash
|
||
./planet.sh restart -a
|
||
```
|
||
|
||
## 数据源与采集器凭证
|
||
|
||
### 采集器连接验证通过，但正式采集拿不到凭证怎么办？
|
||
|
||
连接验证会读取控制台保存配置、环境变量和部分 `~/.zshrc` 凭证。正式采集更推荐把凭证保存到“采集管理 -> 采集器”，尤其是 AISStream 这类长连接 collector。
|
||
|
||
如果只把 `AISSTREAM_API_KEY` 放在 `~/.zshrc`，需要确认后端进程实际继承了该变量。否则可能出现连接验证可用，但 collector 运行时没有 key 的情况。
|
||
|
||
### BarentsWatch / AISStream 凭证应该放哪里？
|
||
|
||
临时联调可以先放环境变量或 `~/.zshrc`，例如：
|
||
|
||
```bash
|
||
export AISSTREAM_API_KEY="..."
|
||
export BARENTSWATCH_CLIENT_ID="..."
|
||
export BARENTSWATCH_CLIENT_SECRET="..."
|
||
```
|
||
|
||
稳定运行时，优先在控制台“采集管理 -> 采集器”中保存凭证，保证连接验证、采集任务和 Earth 实时聚合使用同一份配置。
|
||
|
||
## Docs / 权限
|
||
|
||
### 为什么 Docs 里有些文档看不到？
|
||
|
||
Docs 按 Gatekeeper 权限组控制可见性：
|
||
|
||
- 快速开始、使用手册、FAQ 等基础文档公开可见。
|
||
- 开发文档通常需要 `docs_developer`。
|
||
- 运维和服务控制文档通常需要 `docs_admin`。
|
||
- `admin` 和 `super_admin` 默认具备文档权限；普通用户需要在控制台“用户管理”中分配权限组。
|
||
|
||
## Earth 常见操作
|
||
|
||
### 为什么国界提示“未配置 endpoint”或只能看到低精度？
|
||
|
||
国界已经从采集器体系移出，不再通过数据源采集任务生成。低精度国界是随前端打包的兜底资产，本地未构建高精 PMTiles 时会自动使用它。
|
||
|
||
要启用高精国界，有两条入口：
|
||
|
||
- Earth 页面齿轮设置里的“国界精度”：切到“高精”会启动首次后台下载/构建，并显示百分比，完成后自动应用。
|
||
- 控制台 `运维与配置 -> 智能星球内容 -> 国界精度`：适合查看 provider、manifest、PMTiles、fallback 状态，编辑源配置 JSON，或手动重建。
|
||
|
||
如果看到“更新源未配置完整”，先到 `智能星球内容 -> 国界精度` 保存源配置；本机私有配置写入 `config/earth-boundary-sources.local.json`，不要提交到仓库。没有高精产物时，使用低精 fallback 是正常行为。
|
||
|
||
### Earth 位置候选采集后没有写入怎么办？
|
||
|
||
“采集候选”和“保存候选”是两步。候选可以先在 Earth 上预览，只有点击保存或使用待定位列表中的“一键采用”后，才会写入维表并刷新图层。
|
||
|
||
算力中心候选保存后会写入 `compute_center_locations`。没有可用候选的记录会保留在待定位列表中，系统不会用国家中心点或硬编码 hint 伪造位置。
|
||
|
||
### 智能星球品牌 logo 或标题改完后为什么没恢复默认？
|
||
|
||
智能星球品牌资源在控制台 `运维与配置 -> 智能星球内容 -> 品牌资源` 中维护。上传图片后页面会使用返回的智能星球品牌资产地址；如果只是清空标题、ARIA 文案等文本字段，系统会回退到默认标题，避免出现空白品牌。
|
||
|
||
要恢复发布包自带的默认 logo、标题图和文案，使用“重置品牌资源”。只刷新 Earth 页面不会删除已经保存的运行时品牌配置。
|
||
|
||
### 为什么卫星看起来不在同一个球面上？
|
||
|
||
Earth 默认开启“真实卫星高度”。卫星位置仍来自 TLE/SGP4，但高度会经过压缩映射：低轨卫星靠近地球，高轨卫星更远，同时保持在当前视图可读范围内。最高显示偏移使用 `25`，约等于当前地球显示半径的四分之一；这是视觉上区分 GEO / MEO / LEO 和保持镜头可读性的折中，不是把真实公里数按比例直接画出来。这个设置也会影响卫星轨迹和锁定后的预测轨道。
|
||
|
||
如果需要旧版所有卫星位于同一显示球面的效果，在 Earth 设置里关闭“真实卫星高度”。缺失 TLE 或传播失败的卫星仍会回退到旧版固定高度，不会因为无法计算真实高度而消失。
|
||
|
||
低倾角高轨卫星应该沿赤道附近或固定经度附近分布，而不是绕出接近南北向的大圈。Earth 会先把 SGP4 的惯性系位置转换成地固坐标再绘制当前点；锁定后的预测轨道则固定当前地球姿态来画一圈惯性轨道，所以应该闭合并保留正确倾角。如果以后看到详情卡倾角接近 `0°`，但预测轨道像极轨一样竖着绕，优先检查 ECI/TEME 到 ECF 的转换和预测轨道是否错误使用了逐采样 `gstime`。
|
||
|
||
### 动捕调试面板为什么看不到摄像头画面？
|
||
|
||
如果输入源是 Browser Camera，调试面板会显示浏览器本机摄像头实时预览，并在画面上绘制骨架。如果勾选了 `只显示骨骼`，视频预览会被隐藏，只显示深色背景和红/绿骨架。
|
||
|
||
如果输入源是 Motion Agent，Agent WebSocket 只发送归一化关节点、骨架连线和匹配动作，不发送原始摄像头帧，以降低隐私、带宽和延迟风险。因此远端 Agent 模式下看到的是骨架调试视图，而不是视频流。
|