15 KiB
常见问题
这页集中收录本地启动、Windows / WSL、依赖、动捕、凭证和文档权限相关的常见排障路径。更完整的背景说明仍在对应专题文档中，这里只保留最常用的判断顺序和命令。
启动与端口
启动时报后端地址已被占用怎么办？
现象通常类似：
后端地址已被占用: 0.0.0.0:8000 / 127.0.0.1:8000 / [::1]:8000
Address already in use
先尝试：
./planet.sh restart -b
如果仍然占用，临时换端口：
./planet.sh start -b 8001
在 WSL 中，端口可能不是 Linux 进程占用，而是 Windows 侧 listener。常见输出如下：
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：
netsh interface portproxy show all
如果看到 0.0.0.0:8000 或 listenport=8000，删除对应规则：
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
如果没有 portproxy 规则，再确认 PID 内承载的服务：
netstat -ano | findstr :8000
tasklist /svc /fi "PID eq 4700"
临时排障可以在管理员 PowerShell 中停止 IP Helper：
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> |
示例：
./planet.sh start -f 3001 -b 8001 -a 8101
Windows / WSL / 局域网
Windows / WSL 下局域网访问不通怎么办？
建议按下面顺序排查：
# 在 WSL 或运行 Planet 的 shell 中
curl http://localhost:3000
curl http://localhost:8000/health
curl http://localhost:8010/health
再到 Windows PowerShell 验证：
curl http://localhost:3000
curl http://localhost:8000/health
curl http://localhost:8010/health
如果 WSL 和 Windows localhost 都通，但手机或其他电脑访问不通，再考虑局域网开放：
./planet.sh start --allow-lan
参数必须写成 --allow-lan。allowlan 或 --allowlan 不会被启动脚本识别。如果服务已经启动，只想重新开放前端，需要显式重启前端：
./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 请求来自动创建。若自动请求被取消，可以手动清理：
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 中按端口放行：
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 状态：
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 地址：
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 模式缺依赖时，推荐：
uv add mediapipe opencv-python
planet.sh start --motion-agent 会自动检查并安装这些 live 依赖。若要禁止自动安装：
PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start --motion-agent
为什么不要用 npm run，要用 bun？
前端运行时统一使用 Bun，避免 WSL / Windows 混合环境里触发 cmd.exe 路径兼容问题。
常用命令：
bun install
bun run dev
bun run build
如果非交互 shell 找不到 bun，planet.sh 会依次查找当前 PATH、~/.bun/bin、zsh 配置和 PowerShell 中的可执行路径。
.zshrc 里的环境变量什么时候会被读取？
planet.sh 默认只静态解析 ~/.zshrc 中简单的：
export KEY=value
KEY=value
这样可以避免 shell 主题、插件或交互初始化拖慢启动。复杂 shell 展开需要显式启用 source 模式：
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
如果排障时想完全忽略 ~/.zshrc：
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
不要把密钥值写进文档或提交到仓库；文档只应写变量名和用途。
Motion Capture / 摄像头
Browser Camera 模式需要 motionAgent 参数吗？
不需要。浏览器摄像头模式直接用网页 getUserMedia 调本机摄像头，并在浏览器本地识别动作。
推荐 URL：
/earth?motion=1&motionProvider=browser
也可以在 Earth 设置中打开“动捕调试模式”，并把“动捕输入源”选为“浏览器摄像头”。页面必须运行在 HTTPS 或 localhost，且用户需要允许浏览器摄像头权限。
Motion Agent 什么时候才需要？
这些场景才需要 Motion Agent：
- 双 USB 摄像头
- RTSP / HTTP 摄像头流
- 边缘设备或客户端集成
- 需要独立本地识别服务
常用命令：
./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*。先确认：
ls /dev/video*
如果没有设备，普通网页演示优先走 Browser Camera。需要 Agent live 模式时，可以用 RTSP / HTTP 摄像头 URL：
./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 即可：
./planet.sh restart -a
首次构建慢通常是 Docker build context、镜像层或 uv sync 下载依赖耗时。后续构建会复用 .dockerignore、BuildKit 和 uv cache。
Docker 健康检查没过怎么办？
先看统一健康检查：
./planet.sh health
再看日志：
./planet.sh log
如果只有 AI Provider 异常，优先重启单个服务：
./planet.sh restart -a
数据源与采集器凭证
采集器连接验证通过，但正式采集拿不到凭证怎么办？
连接验证会读取控制台保存配置、环境变量和部分 ~/.zshrc 凭证。正式采集更推荐把凭证保存到“采集管理 -> 采集器”，尤其是 AISStream 这类长连接 collector。
如果只把 AISSTREAM_API_KEY 放在 ~/.zshrc，需要确认后端进程实际继承了该变量。否则可能出现连接验证可用，但 collector 运行时没有 key 的情况。
BarentsWatch / AISStream 凭证应该放哪里？
临时联调可以先放环境变量或 ~/.zshrc，例如：
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 模式下看到的是骨架调试视图，而不是视频流。