ai-video-fullstack/deploy

开发 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。

Next dev 还会校验开发资源的来源。远程访问时,把浏览器地址栏里的 host 加到 frontend/next.config.ts 的 allowedDevOrigins,并重启前端 dev server:

// frontend/next.config.ts
const nextConfig = {
  allowedDevOrigins: ["127.0.0.1", "<远程机器IP或域名>"],
};

如果漏掉这一步,页面 HTML 可能能打开,但客户端 JS 无法接管:按钮无响应, 列表一直停在 正在加载,同时 Next dev 内部资源可能返回 403 Unauthorized。

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. 部署 coturn(TURN 中继)

如果浏览器和后端不在同一内网,WebRTC 媒体链路通常需要 TURN。项目里的 docker-compose.yaml 已经带了 coturn,用 remote profile 启动即可。

6.1 配项目根目录 .env

项目根目录的 .env 给 coturn 容器用:

PUBLIC_IP=<远程机器公网IP>
TURN_SECRET=<一串足够长的随机密钥>

示例:

PUBLIC_IP=118.89.89.89
TURN_SECRET=change-me-to-a-long-random-string

6.2 配后端 backend/.env

后端用同一个 TURN_SECRET 签发短时 TURN 凭证:

TURN_URLS=turn:<远程机器公网IP>:3478?transport=udp,turn:<远程机器公网IP>:3478?transport=tcp
TURN_SECRET=<和项目根 .env 一致的密钥>

示例:

TURN_URLS=turn:118.89.89.89:3478?transport=udp,turn:118.89.89.89:3478?transport=tcp
TURN_SECRET=change-me-to-a-long-random-string

改完 backend/.env 后,重启后端 uvicorn。

6.3 启动 coturn

docker compose --profile remote up -d coturn

查看状态和日志:

docker compose ps coturn
docker compose logs -f coturn

6.4 放行端口

云安全组至少放行:

80/tcp
443/tcp
3478/tcp
3478/udp
49152-49200/udp

如果 HTTPS 映射到 18189,还要放行:

18189/tcp

如果远程机器启用了 ufw:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 18189/tcp
sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 49152:49200/udp

6.5 验证后端已下发 TURN

后端和 nginx 都跑起来后:

curl -k https://<远程机器IP或域名>:18189/api/webrtc/ice-servers

应该能看到 stun: 和 turn::

{
  "iceServers": [
    {"urls": "stun:stun.l.google.com:19302"},
    {
      "urls": "turn:<远程机器公网IP>:3478?transport=udp",
      "username": "...",
      "credential": "..."
    }
  ]
}

前端怎么连后端

前端读环境变量 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 直接访问正常?

先确认前端 dev server 已用浏览器访问同源地址启动:

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

再确认 frontend/next.config.ts 的 allowedDevOrigins 包含同一个 host:

allowedDevOrigins: ["127.0.0.1", "<远程机器IP或域名>"],

修改 NEXT_PUBLIC_API_BASE_URL 或 allowedDevOrigins 后都必须重启 npm run dev。若 API 直接返回 200,但页面按钮无响应、弹窗打不开、列表 仍停在 正在加载,通常是 Next dev 的 _next/* 客户端资源被跨源保护拦截, 不是后端接口没有数据。

API 请求跨域报错?

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