# 常见问题

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

## 启动与端口

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

现象通常类似：

```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` 会用临时 Windows relay 暴露 `3000` / `8000`，不再需要保留持久 portproxy。

如果脚本输出 `failed-stop-service`、`failed-stop-process`，或 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`，脚本会启动临时 relay，局域网仍访问 `3000` / `8000`。

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

常用端口如下：

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

再到 Windows PowerShell 验证：

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

传统 WSL NAT 场景下，`./planet.sh start --allow-lan` 会启动临时 Windows relay，让 Windows 对外仍使用 `3000` / `8000`。脚本会在启动前检测并请求管理员 PowerShell 删除旧 `portproxy`，也会检测 Windows 防火墙规则；如果缺少 `3000` / `8000` 入站放行，会触发一次 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

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
```

局域网设备访问 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
```

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

## Earth 常见操作

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

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

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

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

Earth 默认开启“真实卫星高度”。卫星位置仍来自 TLE/SGP4，但高度会经过压缩映射：低轨卫星靠近地球，高轨卫星更远，同时保持在当前视图可读范围内。最高显示偏移使用 `25`，约等于当前地球显示半径的四分之一；这是视觉上区分 GEO / MEO / LEO 和保持镜头可读性的折中，不是把真实公里数按比例直接画出来。这个设置也会影响卫星轨迹和锁定后的预测轨道。

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

低倾角高轨卫星应该沿赤道附近或固定经度附近分布，而不是绕出接近南北向的大圈。Earth 会先把 SGP4 的惯性系位置转换成地固坐标再绘制当前点；锁定后的预测轨道则固定当前地球姿态来画一圈惯性轨道，所以应该闭合并保留正确倾角。如果以后看到详情卡倾角接近 `0°`，但预测轨道像极轨一样竖着绕，优先检查 ECI/TEME 到 ECF 的转换和预测轨道是否错误使用了逐采样 `gstime`。

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

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

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