planet/docs/technical/zh/faq.md

常见问题

这页集中收录本地启动、Windows / WSL、依赖、动捕、凭证和 Docs 权限相关的常见排障路径。更完整的背景说明仍在对应专题文档中，这里只保留最常用的判断顺序和命令。

启动与端口

启动时报后端地址已被占用怎么办？

现象通常类似：

后端地址已被占用: 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

这可能影响部分网络、代理或转发能力。长期不推荐禁用该服务；如果必须保留 Windows 转发，改用不同后端端口更稳。

如果脚本输出 failed-stop-service 或 failed-stop-process，说明当前权限无法清理 Windows listener。脚本会停止启动，避免后端再次遇到同一端口冲突。

默认端口冲突时应该改哪些参数？

常用端口如下：

服务	默认端口	参数
前端	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

再到 Windows PowerShell 验证：

curl http://localhost:3000
curl http://localhost:8000/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 侧转发或防火墙。

传统 WSL NAT 场景下，管理员 PowerShell 中配置 portproxy 和防火墙：

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

如果 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

也可以用下面命令确认当前 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 默认具备 Docs 权限；普通用户需要在控制台“用户管理”中分配权限组。

Earth 常见操作

Earth 位置候选采集后没有写入怎么办？

“采集候选”和“保存候选”是两步。候选可以先在 Earth 上预览，只有点击保存或使用待定位列表中的“一键采用”后，才会写入维表并刷新图层。

算力中心候选保存后会写入 compute_center_locations。没有可用候选的记录会保留在待定位列表中，系统不会用国家中心点或硬编码 hint 伪造位置。

为什么卫星看起来不在同一个球面上？

Earth 默认开启“真实卫星高度”。卫星位置仍来自 TLE/SGP4，但高度会经过压缩映射：低轨卫星靠近地球，高轨卫星更远，同时保持在当前视图可读范围内。这个设置也会影响卫星轨迹和锁定后的预测轨道。

如果需要旧版所有卫星位于同一显示球面的效果，在 Earth 设置里关闭“真实卫星高度”。缺失 TLE 或传播失败的卫星仍会回退到旧版固定高度，不会因为无法计算真实高度而消失。

动捕调试面板为什么看不到摄像头画面？

如果输入源是 Browser Camera，调试面板会显示浏览器本机摄像头实时预览，并在画面上绘制骨架。如果勾选了 只显示骨骼，视频预览会被隐藏，只显示深色背景和红/绿骨架。

如果输入源是 Motion Agent，Agent WebSocket 只发送归一化关节点、骨架连线和匹配动作，不发送原始摄像头帧，以降低隐私、带宽和延迟风险。因此远端 Agent 模式下看到的是骨架调试视图，而不是视频流。