ngrok内网穿透完全指南:camera-to-blender手机HTTPS拍照的3个关键坑与解法
ngrok内网穿透完全指南:camera-to-blender手机HTTPS拍照的3个关键坑与解法
camera-to-blender 是一个"手机拍照 → 自动生成 3D 模型 → 导入 Blender"的开源项目:用手机拍一张实物照片,服务端调用 AI 生成 3D 模型,再通过 WebSocket 推送进 Blender。而要让手机打开相机,ngrok 内网穿透几乎是必选项——因为手机浏览器的摄像头 API 强制要求 HTTPS 环境。本文用 3 个最常见的坑,帮你一次跑通整条链路 📱✨
原理速览:为什么手机拍照必须走 ngrok 内网穿透
整个系统的分工是这样的:
- 电脑端:运行 FastAPI 中转服务器 relay_server.py,负责调用 Tripo3D 生成模型、调用 Gemini 抠背景,并通过 WebSocket 把模型转发给 Blender;
- 手机端:打开一个基于网页的相机应用 webapp/app.js,拍照、预览、一键发送;
- Blender 端:加载插件 blender_addon/init.py,通过 WebSocket 接收并自动导入 GLB 模型。
关键在于浏览器安全规则:getUserMedia()(调用摄像头)只在安全上下文中可用。http://192.168.x.x:8000 这种本地 IP 地址不算安全上下文,手机摄像头会直接拒绝打开。
而 ngrok 内网穿透恰好能解决:它把本机的 8000 端口映射成一条公网 HTTPS 隧道,手机访问隧道地址,摄像头就能正常工作。这正是项目 README.md 中把 ngrok 列为手机使用必需项的原因。
坑 1:手机打开的是本地 IP,摄像头死活打不开
现象:在手机上输入 http://192.168.1.x:8000,页面能加载,但点开始拍照后黑屏、无反应,或控制台报 getUserMedia 相关错误。
原因:如上所述,HTTP + 局域网 IP 不属于安全上下文,手机浏览器会静默禁用摄像头权限。这不是 ngrok 没配好,而是 URL 本身就不该用局域网地址。
解法:
-
先让服务器监听所有网卡(默认
--host只绑定本机,ngrok 无法转发进来):uvicorn relay_server:app --host 0.0.0.0 --port 8000 -
另开一个终端启动内网穿透:
ngrok http 8000 -
复制 ngrok 给出的
https://abc123.ngrok-free.app这类地址到手机浏览器——必须是 https,不能是局域网 IP。
💡 小细节:ngrok 免费隧道首次访问会显示一个安全提示页,点 "Visit Site" 进入即可,手机端同样适用。
另外,webapp/app.js 中 API_BASE = window.location.origin 的写法意味着前端会自动跟随当前域名发起请求,所以你只要换对入口 URL,接口地址无需任何修改。
坑 2:Blender 用 ws:// 连接失败——一个字母的差别
现象:手机一切正常,模型也生成了,但点击 "Send to Blender" 后提示 "Failed to send to Blender"。
原因:ngrok 隧道是 HTTPS 的,对应的 WebSocket 协议必须写成 wss://(加密版),而不是 ws://。很多人直接把 https:// 换成 ws://,协议不匹配导致握手失败。
解法:Blender 连接地址的完整公式是——
wss://<ngrok域名>/ws?client=blender
以 https://abc123.ngrok-free.app 为例:
- 把
https换成wss; - 路径固定为
/ws?client=blender(client=blender是服务端识别转发目标的关键参数)。
操作路径:Blender 按 N 打开侧栏 → WS Import 标签页 → 粘贴上面的地址 → Connect,看到 Status: Connected 才算成功。插件中该配置的说明可以直接见 blender_addon/init.py。
还有一个"偷懒"技巧:relay_server.py 提供了 /connection-info 接口,它会主动查询 ngrok 本地 API(127.0.0.1:4040/api/tunnels),自动拼好正确的 wss:// 地址返回。手机网页里也可以直接查看这个现成的 Blender 连接地址并一键复制。
坑 3:ngrok 免费地址每次重启都会变
现象:昨天还好好的,今天重启电脑 / 重启 ngrok 后,手机打不开页面,Blender 也断线了。
原因:ngrok 免费版分配的随机域名(abc123.ngrok-free.app)在每次启动时都会更换,旧地址立即失效。这是免费档位的限制,不是故障。
解法:
- 手动流程:重启后从 ngrok 终端输出里复制新 URL → 手机重新打开 → 回到 Blender 把 WS Import 的地址换成新的
wss://...→ 重新 Connect。 - 半自动流程:打开手机页面后,页面上展示的 Blender 连接地址会跟随新隧道自动生成(依赖前文提到的
/connection-info自动检测逻辑),只需更新 Blender 这一处。 - 彻底解决:升级 ngrok 付费版获取固定域名,一次配置长期有效;或者在 ngrok 配置文件里绑定自定义域名。
⚠️ 排查顺序建议:手机打不开 → 先检查 ngrok 进程是否存活;Blender 收不到模型 → 先检查 Status 是否为 Connected,再核对 URL 是否
wss://开头、?client=blender结尾。
完整启动清单:5 分钟跑通全流程
-
安装依赖并配置密钥:
pip install -r requirements.txt cp .env.example .env按 .env.example 填入
TRIPO_API_KEY(必需,生成 3D 模型)和GEMINI_API_KEY(可选,抠背景,留空则跳过)。 -
启动服务器:
uvicorn relay_server:app --host 0.0.0.0 --port 8000 -
另开终端启动内网穿透:
ngrok http 8000 -
Blender 安装插件:Edit → Preferences → Add-ons → Install,选择 ws_import_addon.zip 并启用,然后按
N→ WS Import 标签页粘贴wss://<域名>/ws?client=blender,点击 Connect。 -
手机浏览器打开 ngrok 的 HTTPS 地址 → 允许相机权限 → 对准实物拍照 → 确认照片 → 等待 30~60 秒生成 → 点击 Send to Blender,模型自动出现在视口中 🎉
没有手机?用笔记本摄像头也能测试:跳过 ngrok,手机部分改为打开
http://localhost:8000,Blender 改用ws://localhost:8000/ws?client=blender。
故障排查速查表
| 症状 | 最可能原因 | 处理 |
|---|---|---|
| 手机摄像头不打开 | 用了 http:// 本地 IP |
换成 ngrok 的 https:// 隧道地址 |
| Failed to send to Blender | 插件未连接 / 协议写错 | 确认 Status: Connected,URL 为 wss://...?client=blender |
| 地址突然全部失效 | ngrok 重启后域名更换 | 复制新 URL,手机和 Blender 同步更新 |
| 抠背景失败(429/401) | Gemini 额度或密钥问题 | 清空 GEMINI_API_KEY 跳过抠图,用原图继续 |
| 手机能连但 Blender 收不到 | /relay 找不到目标客户端 |
检查 relay_server.py 终端日志中是否有 blender 连接记录 |
写在最后
ngrok 内网穿透在 camera-to-blender 里承担的角色很纯粹:给手机一个能开摄像头的 HTTPS 入口,顺手给 Blender 一个 wss:// 通道。只要记住三件事——手机必须走 https 隧道、Blender 必须用 wss 协议加 client 参数、免费域名重启即变——这套"拍一张照片,Blender 里多出 3D 模型"的流程就能稳定跑起来。
项目核心代码都很短,建议结合 relay_server.py(服务端中转逻辑)、webapp/(手机端相机页面)和 blender_addon/(Blender 插件源码)一起阅读,改起来也很快。