# 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 + 访问控制。

---

## 九、手机麦克风无法使用？

电脑能看到麦克风按钮，手机提示「检测不到麦克风」，通常是以下原因：

### 1. 未使用 HTTPS（最常见）

手机浏览器规定：`getUserMedia`（麦克风）**仅在 HTTPS / localhost 下可用**。

| 访问方式 | 电脑 | 手机 |
|----------|------|------|
| `http://192.168.x.x:5683` | 可能显示按钮但录音失败 | ❌ 检测不到麦克风 |
| `https://你的域名`（NPS+反代） | ✅ | ✅ |

**解决：** 按本文档配置 NPS + 云服务器 HTTPS，用手机访问域名。

### 2. 云反代未放行麦克风权限

在云服务器的 Nginx / 面板反代中，确认响应头包含（教程示例，在你自己的反代里配置）：

```nginx
add_header Permissions-Policy "microphone=(self), camera=(self)" always;
```

Trading Studio 应用层也会发送该头；若反代覆盖了响应头，需在反代侧补上。

### 3. iOS / 微信浏览器限制

- **iOS**：请用 **Safari** 打开 HTTPS 域名，首次点击麦克风时点「允许」
- **微信内置浏览器**：通常**不支持**网页录音 → 右上角「在浏览器中打开」
- **已安装 PWA**：从桌面图标启动后，在系统设置中检查 Safari/Chrome 麦克风权限

### 4. 临时替代：上传录音文件

在 HTTP 内网或无法授权麦克风时，点击音频区域的 **「上传」** 标签，选择手机「语音备忘录」导出的 `.m4a` / `.wav` 文件，功能与现场录音相同。

---

## 十、HTTP 内网直连（不装 App）

局域网内 `http://192.168.x.x:5683` 可正常使用全部功能，仅 **PWA 安装** 受限。  
点击页面「安装 App」会提示需 HTTPS；功能不受影响。

---

## 相关文档

- 内网部署：`DEPLOY.md`  
- 服务器更新：`bash server-update.sh`  
- 麦克风问题：见上文 **第九节**