0adb3ed8a1
- Introduce `setup-certs.sh` script for generating trusted local TLS certificates using mkcert. - Add Nginx configuration files for local and Docker environments to handle HTTPS requests and proxy to backend services. - Update `docker-compose.yaml` to include Nginx service for unified TLS entry and adjust frontend service ports for local development. - Create `AGENTS.md` and `README.md` files to document the local HTTPS setup process and usage instructions. - Modify backend startup commands in `README.md` for consistency with new requirements. - Add `.gitignore` to exclude generated certificates from version control.
67 lines
2.3 KiB
Markdown
67 lines
2.3 KiB
Markdown
# 本地 / 局域网 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/credentials/...)
|
|
├── /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/`。私钥不要提交。
|