Add remote development support with Docker Nginx configuration

- Introduce a new `nginx-remote-dev` service in `docker-compose.yaml` for remote development environments, allowing Nginx to proxy requests to the host machine's frontend and backend services.
- Create a new Nginx configuration file `ai-video.remote-dev.conf` tailored for remote setups, ensuring proper handling of WebSocket and API requests.
- Update `README.md` to include detailed instructions for setting up remote development with Nginx, including certificate generation and service initialization.
- Enhance the `setup-certs.sh` script to support additional hostnames for certificate signing, improving flexibility for remote access.
- Revise documentation to clarify the development paths and requirements for local and remote environments.

deploy/README.md

@@ -1,8 +1,8 @@
-# 本地 / 局域网 HTTPS 调试
+# 开发 HTTPS 调试部署
 
 语音预览要求麦克风可用,浏览器只在 **安全上下文**(localhost 或 https)下放行
-`getUserMedia`。本机用 localhost 就够;**要在局域网用 IP 给别的设备测,就得上 https**。
-这里用 mkcert 签本地受信任证书 + nginx 反代统一 TLS。
+`getUserMedia`。本机用 localhost 就够;**局域网或远程机器用 IP/域名给别的设备测,
+就要走 https**。开发环境推荐 nginx 统一做 TLS 入口,前端页面、HTTP API 和 WS 信令都同源。
 
 ## 结构
 
@@ -16,7 +16,9 @@
 
 前端页面和信令 ws 同源(同 host 同端口),没有混合内容 / 跨源问题。
 
-## 步骤
+## 路径 A:本机 / 局域网,nginx 直接跑在宿主机
+
+适合 Mac 本机调试,或同一局域网里手机访问电脑 IP。
 
 ```bash
 # 1) 装 mkcert(只需一次)
@@ -37,6 +39,118 @@ nginx -c "$(pwd)/deploy/nginx/ai-video.dev.conf" -g 'daemon off;'
 #   局域网: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. 准备证书
+
+有域名时推荐使用正式证书,把证书文件放到:
+
+```text
+deploy/certs/ai-video.pem
+deploy/certs/ai-video-key.pem
+```
+
+只做开发调试也可以用 mkcert。远程机器上把访问用的 IP/域名传给脚本:
+
+```bash
+./deploy/setup-certs.sh <远程机器公网IP或内网IP> <可选域名>
+```
+
+mkcert 是本地 CA。浏览器所在设备要免警告,需要信任这台远程机器生成的
+`rootCA.pem`;否则可以临时接受浏览器的自签证书警告。
+
+### 2. 启动数据库并初始化
+
+```bash
+docker compose up -d postgres
+make db-seed
+```
+
+`make db-seed` 会建表、同步接口定义、写入模型资源和助手示例。模型密钥不放
+`.env`,启动后到前端「组件 / 模型」里把 `replace-me` 换成真实密钥。
+
+### 3. 单独启动后端
+
+后端必须监听 `0.0.0.0`,否则 nginx 容器连不到宿主机端口:
+
+```bash
+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 的
+https 地址,不要写 `:8000`:
+
+```bash
+cd frontend
+npm install
+NEXT_PUBLIC_API_BASE_URL=https://<远程机器IP或域名> \
+  npm run dev -- --hostname 0.0.0.0
+```
+
+### 5. 启动 Docker nginx
+
+推荐用 compose profile:
+
+```bash
+docker compose --profile remote-dev up -d nginx-remote-dev
+```
+
+也可以直接 `docker run`:
+
+```bash
+docker run --rm --name ai-video-nginx \
+  --add-host=host.docker.internal:host-gateway \
+  -p 80:80 -p 443: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
+```
+
+访问:
+
+```text
+https://<远程机器IP或域名>
+```
+
+### 6. 远程语音 / WebRTC 注意事项
+
+- 云安全组至少放行 `80/tcp`、`443/tcp`。
+- 如果浏览器和后端不在同一内网,WebRTC 媒体链路通常需要 TURN。
+- 启动 coturn:
+
+```bash
+# 项目根 .env:
+# PUBLIC_IP=<远程机器公网IP>
+# TURN_SECRET=<和 backend/.env 一致的密钥>
+
+docker compose --profile remote up -d coturn
+```
+
+- 云安全组放行 `3478/tcp`、`3478/udp`、`49152-49200/udp`。
+- `backend/.env` 中配置:
+
+```text
+TURN_URLS=turn:<远程机器公网IP>:3478?transport=udp,turn:<远程机器公网IP>:3478?transport=tcp
+TURN_SECRET=<同上>
+```
+
 ## 前端怎么连后端
 
 前端读环境变量 `NEXT_PUBLIC_API_BASE_URL`(compose 里已设)。走 nginx 后,
@@ -50,7 +164,7 @@ wsUrl = NEXT_PUBLIC_API_BASE_URL.replace(/^http/, 'ws') + '/ws/voice'
 > 没有反代、直连后端时则是 `https://<host>:8000`,但那样要给后端单独配证书、
 > 还有跨源,不推荐。统一走 nginx 最干净。
 
-## 给别的设备(手机等)免警告
+## 给别的设备免警告
 
 证书是 mkcert 本地 CA 签的,只有装了该 CA 的设备才信任:
 
@@ -64,3 +178,20 @@ 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。