# 本地 / 局域网 HTTPS 调试

语音预览要求麦克风可用,浏览器只在 **安全上下文**(localhost 或 https)下放行
`getUserMedia`。本机用 localhost 就够;**要在局域网用 IP 给别的设备测,就得上 https**。
这里用 mkcert 签本地受信任证书 + nginx 反代统一 TLS。

## 结构

```
浏览器 ──https/wss──> nginx :443 (唯一 TLS 入口, mkcert 证书)
                       ├── /ws/    → 后端 :8000  (/ws/voice 信令、/ws/stream 裸流)
                       ├── /api/   → 后端 :8000  (assistants/model-resources/...)
                       ├── /health → 后端 :8000
                       └── /       → 前端 :3000  (Next dev + HMR)
```

前端页面和信令 ws 同源(同 host 同端口),没有混合内容 / 跨源问题。

## 步骤

```bash
# 1) 装 mkcert(只需一次)
brew install mkcert nss

# 2) 生成证书(本机 CA + localhost/LAN IP/ai-video.local 的证书)
./deploy/setup-certs.sh

# 3) 起前后端(任选其一)
docker compose up -d            # api:8000 + ui:3030 都发布到 localhost
#   或本地分别 npm run dev / uvicorn app:app --port 8000

# 4) 起 nginx(装一下:brew install nginx)
nginx -c "$(pwd)/deploy/nginx/ai-video.dev.conf" -g 'daemon off;'

# 5) 访问
#   本机:  https://localhost  或  https://ai-video.local
#   局域网:https://<本机IP>   (脚本结尾会打印)
```

## 前端怎么连后端

前端读环境变量 `NEXT_PUBLIC_API_BASE_URL`(compose 里已设)。走 nginx 后,
让它指向**同源**即可,ws 地址由它推导:

```
NEXT_PUBLIC_API_BASE_URL = https://<访问用的host>      # 同源,不再写 :8000
wsUrl = NEXT_PUBLIC_API_BASE_URL.replace(/^http/, 'ws') + '/ws/voice'
```

> 没有反代、直连后端时则是 `https://<host>:8000`,但那样要给后端单独配证书、
> 还有跨源,不推荐。统一走 nginx 最干净。

## 给别的设备(手机等)免警告

证书是 mkcert 本地 CA 签的,只有装了该 CA 的设备才信任:

```bash
mkcert -CAROOT          # 打印 CA 目录,里面的 rootCA.pem 拷到设备并信任
```

LAN IP 不在证书 SAN 里会报名称不匹配——`setup-certs.sh` 已自动把探测到的
en0/en1 IP 加进 SAN;换网络换了 IP,重跑脚本即可。

## 证书不入库

`deploy/.gitignore` 已忽略 `certs/`。私钥不要提交。