ngrok内网穿透完全指南:camera-to-blender手机HTTPS拍照的3个关键坑与解法

原创2026-10-25 16:13:071,677 阅读

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 本身就不该用局域网地址。

解法:

  1. 先让服务器监听所有网卡(默认 --host 只绑定本机,ngrok 无法转发进来):

    uvicorn relay_server:app --host 0.0.0.0 --port 8000
    
  2. 另开一个终端启动内网穿透:

    ngrok http 8000
    
  3. 复制 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 为例:

  1. 把 https 换成 wss;
  2. 路径固定为 /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 分钟跑通全流程

  1. 安装依赖并配置密钥:

    pip install -r requirements.txt
    cp .env.example .env
    

    按 .env.example 填入 TRIPO_API_KEY(必需,生成 3D 模型)和 GEMINI_API_KEY(可选,抠背景,留空则跳过)。

  2. 启动服务器:

    uvicorn relay_server:app --host 0.0.0.0 --port 8000
    
  3. 另开终端启动内网穿透:

    ngrok http 8000
    
  4. Blender 安装插件:Edit → Preferences → Add-ons → Install,选择 ws_import_addon.zip 并启用,然后按 N → WS Import 标签页粘贴 wss://<域名>/ws?client=blender,点击 Connect。

  5. 手机浏览器打开 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 插件源码)一起阅读,改起来也很快。

登录后查看全文
camera-to-blender