docs/02-系统架构.md

@@ -213,11 +213,73 @@ CREATE TABLE usage_daily (
 ## 部署架构
 
 ```
-CDN（静态资源） ← 用户浏览器
+用户浏览器
-Nginx 负载均衡（sticky session for WebSocket）
+    ↓
-  ├── Gateway-1 ──→ Redis
+Nginx（同源反代 + 负载均衡）
-  ├── Gateway-2 ──→ Redis
+  ├── /            → 前端静态资源（CDN 或本地 dist）
-  └── Gateway-N ──→ AI Services（外部 API）
+  ├── /api/*       → Go Gateway（REST API）
+  └── /ws          → Go Gateway（WebSocket）
+        ├── Gateway-1 ──→ Redis
+        ├── Gateway-2 ──→ Redis
+        └── Gateway-N ──→ AI Services（外部 API）
 ```
 
-WebSocket 是长连接，Nginx 需要配置 `proxy_set_header Upgrade` 和 sticky session，确保同一用户的请求始终路由到同一个 Gateway 实例。
+**跨域策略**：Nginx 将前端和后端统一到同一域名下，浏览器无跨域问题。
+
+### Nginx 配置
+
+```nginx
+server {
+    listen 80;
+    server_name camtalk.example.com;
+
+    # 前端静态资源
+    location / {
+        root /var/www/camtalk/dist;
+        try_files $uri $uri/ /index.html;
+    }
+
+    # REST API 反代
+    location /api/ {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # WebSocket 反代
+    location /ws {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_read_timeout 86400s;   # 长连接超时 24h
+        proxy_send_timeout 86400s;
+    }
+}
+```
+
+> WebSocket 是长连接，Nginx 必须配置 `Upgrade` 和 `Connection` 头。`proxy_read_timeout` 需要覆盖心跳间隔（客户端 30s ping），否则 Nginx 会主动断开空闲连接。
+
+### 开发环境（Vite proxy）
+
+开发时前端（Vite :5173）和后端（Gin :8080）不同端口，用 Vite 内置代理解决跨域：
+
+```typescript
+// frontend/vite.config.ts
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    proxy: {
+      "/api": "http://localhost:8080",
+      "/ws": {
+        target: "ws://localhost:8080",
+        ws: true,
+      },
+    },
+  },
+});
+```
+
+前端代码中 WebSocket 地址改为相对路径 `ws://localhost:5173/ws`，Vite 自动代理到后端。部署时 Nginx 同理，前端无需区分开发/生产地址。

docs/03-接口文档.md

@@ -1085,3 +1085,25 @@ function reconnect(attempt: number) {
 }
 // attempt: 0 → 1s, 1 → 2s, 2 → 4s, 3 → 8s, ... 最大 30s
 ```
+
+### 跨域处理
+
+采用 **Nginx 同源反代**方案，前后端统一到同一域名，浏览器层面不存在跨域问题。
+
+**生产环境**：Nginx 将 `/`（前端）、`/api/*`（REST）、`/ws`（WebSocket）统一反代到同一域名，详见 `02-系统架构.md` 部署架构章节。
+
+**开发环境**：Vite 内置代理，前端 :5173 的 `/api` 和 `/ws` 请求代理到后端 :8080：
+
+```typescript
+// frontend/vite.config.ts
+server: {
+  proxy: {
+    "/api": "http://localhost:8080",
+    "/ws":  { target: "ws://localhost:8080", ws: true },
+  },
+},
+```
+
+**Go 后端 WebSocket CheckOrigin**：生产环境 Nginx 同源，`CheckOrigin` 可保持默认（拒绝跨域）。开发环境由 Vite proxy 转发，不存在跨域。因此后端无需配置 CORS 中间件，`CheckOrigin` 保持 gorilla/websocket 默认值即可。
+
+> 如果未来需要支持第三方客户端直连（如移动端），再按需添加 CORS 中间件和 `CheckOrigin` 白名单。