ai-video-fullstack/deploy/README.md

开发 HTTPS 调试部署

语音预览要求麦克风可用,浏览器只在 安全上下文(localhost 或 https)下放行 getUserMedia。本机用 localhost 就够;局域网或远程机器用 IP/域名给别的设备测, 就要走 https。开发环境推荐 nginx 统一做 TLS 入口,前端页面、HTTP API 和 WS 信令都同源。

结构

浏览器 ──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 同端口),没有混合内容 / 跨源问题。

路径 A:本机 / 局域网,nginx 直接跑在宿主机

适合 Mac 本机调试,或同一局域网里手机访问电脑 IP。

# 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>   (脚本结尾会打印)

deploy/nginx/ai-video.dev.conf 里的证书路径是本机绝对路径。换目录或换机器时, 把 ssl_certificate 和 ssl_certificate_key 改到当前仓库的 deploy/certs/。

路径 B:远程开发机,Docker nginx + 宿主机 npm/uvicorn

适合在云主机/远程 Linux 上开发:数据库可以用 Docker,但前端和后端单独跑, 便于热更新和看日志。nginx 跑在 Docker 容器里,通过 host.docker.internal 反代到宿主机上的 3000/8000。

1. 准备证书

有域名时推荐使用正式证书,把证书文件放到:

deploy/certs/ai-video.pem
deploy/certs/ai-video-key.pem

只做开发调试也可以用 mkcert。远程机器上把访问用的 IP/域名传给脚本:

./deploy/setup-certs.sh <远程机器公网IP或内网IP> <可选域名>

mkcert 是本地 CA。浏览器所在设备要免警告,需要信任这台远程机器生成的 rootCA.pem;否则可以临时接受浏览器的自签证书警告。

2. 启动数据库并初始化

docker compose up -d postgres
make db-seed

make db-seed 会建表、同步接口定义、写入模型资源和助手示例。模型密钥不放 .env,启动后到前端「组件 / 模型」里把 replace-me 换成真实密钥。

3. 单独启动后端

后端必须监听 0.0.0.0,否则 nginx 容器连不到宿主机端口:

cd backend
cp .env.example .env

# 如果 postgres 用 docker compose,宿主机连库可用 localhost:5432
# backend/.env:
# DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/postgres

uv run --with-requirements requirements.txt \
  uvicorn app:app --host 0.0.0.0 --port 8000 --reload

4. 单独启动前端

前端也监听 0.0.0.0。NEXT_PUBLIC_API_BASE_URL 只有一个规则: 写浏览器地址栏里访问 nginx 的同源地址。如果地址栏带端口,这里也必须带端口; 如果地址栏不带端口,这里也不带端口。不要写后端直连端口 :8000。

cd frontend
npm install

# nginx 使用默认 443 时:
NEXT_PUBLIC_API_BASE_URL=https://<远程机器IP或域名> \
  npm run dev -- --hostname 0.0.0.0

5. 启动 Docker nginx

推荐用 compose profile:

docker compose --profile remote-dev up -d nginx-remote-dev

如果远程机器希望用非标准 HTTPS 端口,例如 18189,把宿主机端口映射到 容器的 443 即可:

NGINX_HTTPS_PORT=18189 docker compose --profile remote-dev up -d nginx-remote-dev

此时前端也要使用带端口的同源地址:

NEXT_PUBLIC_API_BASE_URL=https://<远程机器IP或域名>:18189 \
  npm run dev -- --hostname 0.0.0.0

浏览器访问:

https://<远程机器IP或域名>:18189

也可以直接 docker run:

docker run --rm --name ai-video-nginx \
  --add-host=host.docker.internal:host-gateway \
  -p 80:80 -p 18189:443 \
  -v "$PWD/deploy/nginx/ai-video.remote-dev.conf:/etc/nginx/nginx.conf:ro" \
  -v "$PWD/deploy/certs:/etc/nginx/certs:ro" \
  nginx:alpine

访问:

https://<远程机器IP或域名>:18189

6. 远程语音 / WebRTC 注意事项

• 云安全组至少放行 80/tcp、443/tcp。
• 如果 HTTPS 映射到 18189,云安全组要放行 18189/tcp。
• 如果浏览器和后端不在同一内网,WebRTC 媒体链路通常需要 TURN。
• 启动 coturn:

# 项目根 .env:
# PUBLIC_IP=<远程机器公网IP>
# TURN_SECRET=<和 backend/.env 一致的密钥>

docker compose --profile remote up -d coturn

• 云安全组放行 3478/tcp、3478/udp、49152-49200/udp。
• backend/.env 中配置:

TURN_URLS=turn:<远程机器公网IP>:3478?transport=udp,turn:<远程机器公网IP>:3478?transport=tcp
TURN_SECRET=<同上>

前端怎么连后端

前端读环境变量 NEXT_PUBLIC_API_BASE_URL。走 nginx 后,让它等于浏览器访问 页面的 origin 即可。origin 包含协议、host 和可选端口:

默认 443:   NEXT_PUBLIC_API_BASE_URL=https://<访问用的host>
自定义端口: NEXT_PUBLIC_API_BASE_URL=https://<访问用的host>:18189

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/。私钥不要提交。

常见问题

nginx 容器里为什么不用 127.0.0.1?

Docker 容器里的 127.0.0.1 是容器自己,不是宿主机。远程开发路径使用 host.docker.internal,并通过 host-gateway 映射到宿主机。

页面能打开,但 HMR 或语音 WS 断开?

检查 nginx 配置里是否保留了 Upgrade、Connection 头,以及 /ws/ 的 proxy_read_timeout 3600s。本仓库的两份开发 nginx 配置都已经包含。

API 请求跨域报错?

走 nginx 时前端和后端同源,通常不需要跨源。若你绕过 nginx 直接访问后端, 需要在 backend/.env 的 CORS_ORIGINS 加上前端实际 origin。