331 lines
11 KiB
Markdown
331 lines
11 KiB
Markdown
# 常见问题
|
||
|
||
这页集中收录本地启动、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
|
||
```
|
||
|
||
这可能影响部分网络、代理或转发能力。长期不推荐禁用该服务；如果必须保留 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>` |
|
||
|
||
示例：
|
||
|
||
```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 场景下，管理员 PowerShell 中配置 portproxy 和防火墙：
|
||
|
||
```powershell
|
||
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 中按端口放行：
|
||
|
||
```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 伪造位置。
|
||
|
||
### 动捕调试面板为什么看不到摄像头画面？
|
||
|
||
如果输入源是 Browser Camera，调试面板会显示浏览器本机摄像头实时预览，并在画面上绘制骨架。如果勾选了 `只显示骨骼`，视频预览会被隐藏，只显示深色背景和红/绿骨架。
|
||
|
||
如果输入源是 Motion Agent，Agent WebSocket 只发送归一化关节点、骨架连线和匹配动作，不发送原始摄像头帧，以降低隐私、带宽和延迟风险。因此远端 Agent 模式下看到的是骨架调试视图，而不是视频流。
|