Move reverse proxy docs to PWA_NPS.md for NPS setup; remove bundled nginx config.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-12 15:04:43 +08:00
parent 21400700c5
commit 90e77f8f70
6 changed files with 420 additions and 335 deletions
@@ -140,50 +140,26 @@ SKIP_PYTORCH=1 bash deploy.sh deps

 下载过程中出现 `Retrying... Read timed out` 属于正常重试，**并非卡死**，请耐心等待 10-30 分钟。

-### 0.7 PWA 安装 App 与 HTTPS 反向代理
+### 0.7 PWA 安装 App（需 HTTPS）

 | 访问方式 | 浏览器行为 |
 |----------|------------|
-| `http://IP:5683` | 只能「快捷方式 / 添加到主屏幕」，**不能**系统级一键安装 |
-| `https://IP` 或 `https://域名` | Chrome/Edge 可弹出 **「安装 Trading Studio」**，独立窗口运行 |
+| `http://内网IP:5683` | 只能「快捷方式 / 添加到主屏幕」 |
+| `https://域名`（经云服务器反代） | Chrome/Edge 可 **「安装 Trading Studio」** |

-**原因：** PWA 规范要求 **HTTPS 安全上下文**（`localhost` 除外）。局域网直连 HTTP 是正常现象，不是代码 bug。
+内网 HTTP 直连无法一键安装 App，这是浏览器 PWA 安全策略，不是程序缺陷。

-#### 推荐方案：Nginx + 自签证书（纯局域网）
+**反向代理不在本仓库代码中配置。** 若你使用 **云服务器 + NPS 内网穿透**（或其它反代方案），请阅读独立教程：

-```bash
-cd /opt/Trading_Studio
-bash server-update.sh   # 或 git pull
+👉 **[PWA_NPS.md](./PWA_NPS.md)** — 云服务器 HTTPS 反代 + NPS 穿透到 `5683` 的完整步骤

-# 1. 安装 Nginx
-sudo apt install -y nginx
+要点摘要：

-# 2. 生成自签 SSL（替换为你的服务器局域网 IP）
-sudo bash scripts/gen_ssl_cert.sh 192.168.8.100
-
-# 3. 启用站点配置
-sudo cp nginx/trading_studio.conf /etc/nginx/sites-available/trading_studio.conf
-sudo ln -sf /etc/nginx/sites-available/trading_studio.conf /etc/nginx/sites-enabled/
-sudo nginx -t && sudo systemctl reload nginx
-
-# 4. 确保 Gradio 仍由 PM2 监听 127.0.0.1:5683（仅本机），外网只走 443
-pm2 restart trading_studio
-```
-
-**访问：** `https://192.168.8.100`（首次需在手机/平板点「高级 → 继续访问」信任证书）
-
-**安装 App：**
- 电脑 Chrome：地址栏出现 ⊕ 安装图标，或点页面「安装 App」按钮
- 安卓 Chrome：菜单 → 安装应用
- iPad/iPhone Safari：分享 → 添加到主屏幕（iOS 无系统安装弹窗，但 HTTPS 下体验更完整）
-
-#### 有公网域名时
-
-在 Nginx 前加 [Let's Encrypt](https://letsencrypt.org/) 免费证书（`certbot`），可免信任自签证书步骤。
-
-#### 无反向代理时的替代
-
-HTTP 下点击「安装 App」会显示手动引导；桌面快捷方式仍可用，功能不受影响。
+1. 内网物理机 PM2 监听 `5683` 即可  
+2. NPS 将 `127.0.0.1:5683` 穿透到云服务器  
+3. 云服务器用已有 Nginx/面板配置 **HTTPS 域名** 反代到 NPS 端口  
+4. 反代须透传 **WebSocket**（Gradio 必需）  
+5. 用户通过 `https://你的域名` 访问后再安装 App  

 ---

@@ -0,0 +1,187 @@
+# PWA 安装 App 教程 — 云服务器反代 + NPS 内网穿透
+
+Trading Studio 的 Gradio 服务跑在**内网物理机** `0.0.0.0:5683`。  
+要通过浏览器 **「安装 App」**（而非仅快捷方式），用户访问的地址必须是 **HTTPS**。
+
+本教程面向：**云服务器做 HTTPS 反向代理 + NPS 穿透到内网 3060Ti 机器** 的架构。  
+**不在 Trading Studio 代码仓库内捆绑任何 Nginx/Caddy 配置文件**，反代在你自己的云服务器 / NPS 面板中完成。
+
+---
+
+## 一、为什么 HTTP 只能快捷方式？
+
+| 访问地址 | 安装表现 |
+|----------|----------|
+| `http://内网IP:5683` | 仅「添加快捷方式 / 创建快捷方式」 |
+| `https://你的域名`（经云服务器） | Chrome/Edge 可 **「安装 Trading Studio」** |
+
+PWA 要求 **安全上下文（HTTPS）**。内网直连 HTTP 是浏览器限制，与项目代码无关。
+
+---
+
+## 二、推荐架构
+
+```
+手机 / 平板 / 电脑
+        │
+        ▼  https://studio.example.com  （云服务器：SSL 证书 + 反代）
+        │
+   云服务器 Nginx / Caddy / 面板反代
+        │
+        ▼  NPS 隧道（TCP 或 HTTP 代理）
+        │
+   内网 3060Ti 物理机
+   PM2 → Gradio  0.0.0.0:5683
+```
+
+要点：
+
+1. **内网机**：只跑 `pm2`，监听 `5683`，无需在云服务器上装 PyTorch。
+2. **NPS**：把内网 `5683` 映射到云服务器某一端口，或做 HTTP 域名转发。
+3. **云服务器**：对外提供 **HTTPS 域名**，反代到 NPS 暴露的地址。
+4. **用户永远用 HTTPS 域名访问**，不要用 `http://IP:5683` 装 App。
+
+---
+
+## 三、内网物理机（Trading Studio）
+
+确保服务正常：
+
+```bash
+cd /opt/Trading_Studio
+pm2 status
+# 应看到 trading_studio 运行中，监听 5683
+
+curl -I http://127.0.0.1:5683
+```
+
+`config.py` 中保持：
+
+```python
+HOST = "0.0.0.0"
+PORT = 5683
+```
+
+Ollama 等仍走局域网 `.env` 配置，与穿透无关。
+
+---
+
+## 四、NPS 客户端配置（内网机）
+
+在 NPS **客户端**（npc）新增隧道，将本机 Gradio 暴露给服务端。常见两种方式：
+
+### 方式 A：TCP 隧道（简单）
+
+| 配置项 | 示例值 |
+|--------|--------|
+| 类型 | TCP |
+| 内网目标 | `127.0.0.1:5683` |
+| 服务端端口 | 如 `25683`（云服务器上监听） |
+
+云服务器反代目标：`http://127.0.0.1:25683`
+
+### 方式 B：HTTP 代理 / 域名模式（推荐，若 NPS 面板支持）
+
+| 配置项 | 示例值 |
+|--------|--------|
+| 类型 | HTTP 代理 |
+| 内网目标 | `127.0.0.1:5683` |
+| 自定义域名 | `studio.example.com`（需在云解析到云服务器 IP） |
+
+此时 HTTPS 可在 NPS 服务端或上层 Nginx 终止，按你现有 NPS 面板习惯配置即可。
+
+> 不同 NPS 版本面板字段名略有差异，核心都是：**外网请求 → NPS → 内网 5683**。
+
+---
+
+## 五、云服务器 HTTPS 反向代理
+
+在**云服务器**（已安装 SSL 证书）上配置反代。以下为**示例**，请按你现有环境（宝塔 / 1Panel / 手写 Nginx）调整，**勿复制到 Trading Studio 仓库**。
+
+### Nginx 示例（仅文档参考）
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name studio.example.com;
+
+    ssl_certificate     /path/to/fullchain.pem;
+    ssl_certificate_key /path/to/privkey.pem;
+
+    client_max_body_size 200M;
+
+    location / {
+        # TCP 隧道时指向 NPS 映射端口；HTTP 模式时指向 NPS 提供的 upstream
+        proxy_pass http://127.0.0.1:25683;
+
+        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_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+    }
+}
+```
+
+**Gradio 必须开启 WebSocket 透传**（`Upgrade` / `Connection` 头），否则页面能开但交互/上传会失败。
+
+### 证书
+
+- 有域名：Let's Encrypt / 云厂商免费证书均可。
+- 仅 IP：部分浏览器 PWA 安装仍要求可信证书，**强烈建议绑定域名**。
+
+---
+
+## 六、验证穿透与 HTTPS
+
+1. 内网机：`curl http://127.0.0.1:5683` 返回 200  
+2. 云服务器：`curl http://127.0.0.1:25683`（NPS 映射端口）正常  
+3. 外网浏览器：`https://studio.example.com` 能打开 Trading Studio  
+4. 地址栏为 **🔒 安全**（非「不安全」）
+
+---
+
+## 七、安装 App（各端）
+
+配置好 HTTPS 域名后：
+
+| 设备 | 操作 |
+|------|------|
+| Windows Chrome / Edge | 地址栏 **⊕ 安装**，或点击页面 **「安装 App」** |
+| 安卓 Chrome | 菜单 → **安装应用** |
+| iPad / iPhone Safari | 分享 → **添加到主屏幕**（iOS 无 Chrome 式安装弹窗，但 HTTPS 下可全屏独立运行） |
+
+若仍只能快捷方式，检查：
+
+- [ ] 是否仍用 `http://` 或内网 IP 访问  
+- [ ] 证书是否有效、是否混合内容报错  
+- [ ] NPS / 反代是否透传 WebSocket  
+- [ ] 浏览器 DevTools → Application → Manifest 是否加载成功  
+
+---
+
+## 八、安全建议
+
+1. **不要**将 `5683` 直接端口映射到公网而不加鉴权；至少使用 HTTPS + 强密码或 IP 白名单。  
+2. NPS 服务端与客户端使用强密钥，定期更换。  
+3. 云服务器防火墙仅开放 443 / NPS 必要端口。  
+4. Trading Studio 处理交易录音，建议域名 + HTTPS + 访问控制。
+
+---
+
+## 九、HTTP 内网直连（不装 App）
+
+局域网内 `http://192.168.x.x:5683` 可正常使用全部功能，仅 **PWA 安装** 受限。  
+点击页面「安装 App」会提示需 HTTPS；功能不受影响。
+
+---
+
+## 相关文档
+
+- 内网部署：`DEPLOY.md`  
+- 服务器更新：`bash server-update.sh`
@@ -179,6 +179,7 @@ Trading_Studio/
 ├── requirements.txt       # Python 依赖
 ├── README.md              # 本文件
 ├── DEPLOY.md              # 部署指南（含一键部署教程）
+├── PWA_NPS.md             # 云服务器反代 + NPS 穿透 + PWA 安装教程
 ├── .gitignore
 ├── speaker_emb.pt         # 音色文件（运行时生成，不入库）
 ├── uploads/               # 上传临时目录
@@ -239,7 +239,7 @@ PWA_HEAD = """
  function manualInstallGuide() {
    var httpWarn = "";
    if (!isSecure()) {
-      httpWarn = "<div class='pwa-modal-warn'><strong>⚠️ 当前为 HTTP 访问</strong><br>浏览器只能创建<strong>快捷方式</strong>，无法弹出系统级「安装 App」。<br>要一键安装，请配置 <strong>HTTPS 反向代理</strong>（见服务器 DEPLOY.md）。</div>";
+      httpWarn = "<div class='pwa-modal-warn'><strong>⚠️ 当前为 HTTP 访问</strong><br>浏览器只能创建<strong>快捷方式</strong>，无法弹出系统级「安装 App」。<br>请通过 <strong>HTTPS 域名</strong>（云服务器反代 + NPS 穿透）访问，详见 <strong>PWA_NPS.md</strong>。</div>";
    }
    var steps = isIOS()
      ? "<ol><li>点击 Safari 底部分享按钮 <strong>□↑</strong></li><li>选择 <strong>「添加到主屏幕」</strong></li><li>点击 <strong>添加</strong></li></ol>"
@@ -1,45 +0,0 @@
-# Trading Studio — Nginx HTTPS 反向代理
-# 将 https://你的域名或IP 转发到本机 Gradio 5683
-#
-# 安装步骤见 DEPLOY.md「PWA 安装与 HTTPS」
-
-# HTTP 自动跳转 HTTPS（可选，不需要可删除此 server 块）
-server {
-    listen 80;
-    listen [::]:80;
-    server_name trading.local _;
-
-    return 301 https://$host$request_uri;
-}
-
-server {
-    listen 443 ssl http2;
-    listen [::]:443 ssl http2;
-    server_name trading.local _;
-
-    # 自签证书路径（先用 scripts/gen_ssl_cert.sh 生成）
-    ssl_certificate     /etc/nginx/ssl/trading_studio.crt;
-    ssl_certificate_key /etc/nginx/ssl/trading_studio.key;
-
-    ssl_protocols TLSv1.2 TLSv1.3;
-    ssl_ciphers HIGH:!aNULL:!MD5;
-
-    client_max_body_size 200M;
-
-    location / {
-        proxy_pass http://127.0.0.1:5683;
-        proxy_http_version 1.1;
-
-        # Gradio WebSocket 必需
-        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_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-
-        proxy_read_timeout 86400s;
-        proxy_send_timeout 86400s;
-    }
-}
@@ -1,34 +0,0 @@
-#!/usr/bin/env bash
-# 生成本地 HTTPS 自签证书（局域网 PWA 安装用）
-# 用法: sudo bash scripts/gen_ssl_cert.sh [服务器局域网IP]
-set -euo pipefail
-
-SERVER_IP="${1:-}"
-SSL_DIR="/etc/nginx/ssl"
-KEY="${SSL_DIR}/trading_studio.key"
-CRT="${SSL_DIR}/trading_studio.crt"
-
-if [[ "${EUID:-0}" -ne 0 ]]; then
-  echo "请使用 root: sudo bash scripts/gen_ssl_cert.sh 192.168.x.x"
-  exit 1
-fi
-
-if [[ -z "${SERVER_IP}" ]]; then
-  SERVER_IP=$(hostname -I | awk '{print $1}')
-  echo "[INFO] 未指定 IP，使用: ${SERVER_IP}"
-fi
-
-mkdir -p "${SSL_DIR}"
-
-openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
-  -keyout "${KEY}" \
-  -out "${CRT}" \
-  -subj "/CN=TradingStudio/O=Trading/C=CN" \
-  -addext "subjectAltName=IP:${SERVER_IP},DNS:trading.local,DNS:localhost"
-
-chmod 600 "${KEY}"
-echo "[OK] 证书已生成:"
-echo "  ${CRT}"
-echo "  ${KEY}"
-echo ""
-echo "手机/平板首次访问 HTTPS 需点「继续访问」信任自签证书，之后即可安装 App。"