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.
本地 / 局域网 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 同端口),没有混合内容 / 跨源问题。
步骤
# 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 的设备才信任:
mkcert -CAROOT # 打印 CA 目录,里面的 rootCA.pem 拷到设备并信任
LAN IP 不在证书 SAN 里会报名称不匹配——setup-certs.sh 已自动把探测到的
en0/en1 IP 加进 SAN;换网络换了 IP,重跑脚本即可。
证书不入库
deploy/.gitignore 已忽略 certs/。私钥不要提交。