Add optional frpc deployment profile

- Add frpc/frpc.toml template for mapping the local Docker web entry on port 4002 to the public frps server. - Add an optional Docker Compose frpc service behind the frpc profile, mounting the reusable frpc.toml configuration. - Document how to enable the frpc profile, inspect frpc logs, and keep normal local startup unchanged. - Clarify that public deployments should map only port 4002 and let Nginx Proxy Manager provide HTTPS for sstwbg.example.com instead of exposing 4443. - Update Docker and deployment docs to match the reusable frpc workflow.
2026-05-08 16:38:39 +08:00
parent 3313811d2f
commit a781227474
5 changed files with 78 additions and 6 deletions
--- a/README.md
+++ b/README.md
@@ -245,6 +245,7 @@ docker-compose down
 - Docker 前端同时暴露 `http://localhost:4002` 和自签名证书的 `https://localhost:4443`；麦克风听写建议使用 HTTPS 演示入口。
 - `api` 服务运行 NestJS 后端，启动时默认执行 `prisma migrate deploy` 和 `prisma db seed`，并把上传文件目录挂载到 `uploads_data` volume。
 - `db` 服务运行 PostgreSQL 16。
+- `frpc` 服务是可选公网隧道客户端。`# XXX` 默认通过 Compose profile 关闭，配置文件在 `frpc/frpc.toml`，需要映射到公网服务器时再启用。
 - `nginx.conf` 已配置 SPA 路由回退、`/api` 反向代理和 `100m` 请求体上限。
 - `nginx.conf` 已支持 `/api/speech/iat` WebSocket upgrade。
 完整 Docker 说明见 [docs/docker.md](./docs/docker.md)。
@@ -281,18 +282,40 @@ docker-compose up -d --build
 curl http://127.0.0.1:4002/api/health
 ```

-如果使用 frpc 把本机 `4002` 映射到公网服务器，示例配置如下，端口号按你的 frps 实际开放端口调整：
+如果使用 frpc 把本机 `4002` 映射到公网服务器，先编辑仓库内置配置：

 ```toml
-# XXX frpc 示例：把本机 Docker 前端入口 4002 暴露到公网服务器的一个内网监听端口。
+# frpc/frpc.toml
+# XXX 替换公网 frps 地址和 token；不要把正式 token 提交到仓库。
+serverAddr = "XX.XX.XX.XX"
+serverPort = 7000
+
+auth.method = "token"
+auth.token = "XXX"
+
 [[proxies]]
-name = "surclaw-web"
+name = "TuWen_System_V2"
 type = "tcp"
 localIP = "127.0.0.1"
 localPort = 4002
 remotePort = 4002
 ```

+`# XXX` 当前 `docker-compose.yaml` 已内置可选 `frpc` 服务，并使用 `network_mode: host` 让 frpc 容器可以访问本机 `127.0.0.1:4002`。启动完整系统和 frpc：
+
+```bash
+docker-compose --profile frpc up -d --build
+docker-compose logs -f frpc
+```
+
+如果只想先启动系统、不启用公网隧道，继续使用：
+
+```bash
+docker-compose up -d --build
+```
+
+`# XXX` 公网正式访问只需要映射 `4002` 到公网服务器，再由公网 Nginx Proxy Manager 提供 `https://sstwbg.example.com`。不建议把 `4443` 映射到公网域名；`4443` 是本机自签名 HTTPS 演示入口，主要用于 `https://localhost:4443` 测试麦克风。
+
 Nginx Proxy Manager 中为 `sstwbg.example.com` 新建 Proxy Host：

 - `Domain Names`：`sstwbg.example.com`
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -67,6 +67,21 @@ services:
      timeout: 5s
      retries: 6

+  frpc:
+    # XXX Optional public tunnel client. Edit frpc/frpc.toml before enabling this service.
+    image: snowdreamtech/frpc:latest
+    container_name: tuwen_frpc
+    restart: unless-stopped
+    network_mode: host
+    command: ["-c", "/etc/frp/frpc.toml"]
+    volumes:
+      - ./frpc/frpc.toml:/etc/frp/frpc.toml:ro
+    depends_on:
+      web:
+        condition: service_healthy
+    profiles:
+      - frpc
+
 volumes:
  postgres_data:
  uploads_data:
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -85,6 +85,7 @@ docker-compose up -d --build
 - `web`：前端静态站点，暴露 `http://localhost:4002` 和 `https://localhost:4443`。
 - `api`：NestJS API，暴露 `http://localhost:3002`。
 - `db`：PostgreSQL 16，暴露 `localhost:5433`。
+- `frpc`：`# XXX` 可选公网隧道客户端，通过 `--profile frpc` 启用，读取 `frpc/frpc.toml` 把本机 `4002` 映射到公网 frps。
 - `uploads_data`：后端文件持久化 volume。

 `api` 容器启动时默认会等待数据库健康，执行 `prisma migrate deploy` 和 `prisma db seed`，再启动 NestJS API。可通过 `RUN_DB_MIGRATIONS` 和 `RUN_DB_SEED` 关闭自动初始化。
@@ -120,7 +121,10 @@ docker-compose up -d --build
 export SESSION_SECRET="替换为足够长的随机字符串"
 export SESSION_COOKIE_SECURE="true"
 export TRUST_PROXY="true"
-docker-compose up -d --build
+
+# XXX 先编辑 frpc/frpc.toml，替换 serverAddr 和 auth.token，再启用 frpc profile。
+docker-compose --profile frpc up -d --build
+docker-compose logs -f frpc
 ```

 Nginx Proxy Manager 代理 `sstwbg.example.com` 时：
@@ -130,6 +134,8 @@ Nginx Proxy Manager 代理 `sstwbg.example.com` 时：
 - 绑定 SSL 证书并开启 `Force SSL`，否则浏览器不会开放公网麦克风权限。
 - Advanced 中建议设置 `client_max_body_size 100m;`、`proxy_read_timeout 3600s;`、`proxy_send_timeout 3600s;`。

+`# XXX` 公网正式访问只映射 `4002` 即可；不要把 Docker 自签名 HTTPS 演示入口 `4443` 映射到公网域名。
+
 ## 麦克风访问

 浏览器不允许普通局域网 HTTP 页面调用麦克风，代码无法绕过这个限制。Docker 演示环境建议使用：
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -4,13 +4,14 @@

 ## 服务组成

-`docker-compose.yaml` 启动三个服务：
+`docker-compose.yaml` 默认启动三个核心服务，另提供一个可选 frpc 服务：

 | 服务 | 容器名 | 说明 | 宿主机端口 |
 | --- | --- | --- | --- |
 | `web` | `tuwen_web` | Nginx 托管前端静态文件，并代理 `/api` 到后端 | `4002`、`4443` |
 | `api` | `tuwen_api` | NestJS API、Session、AI/语音代理、文件上传 | `3002` |
 | `db` | `tuwen_db` | PostgreSQL 16 | `5433` |
+| `frpc` | `tuwen_frpc` | `# XXX` 可选公网隧道客户端，通过 `--profile frpc` 启用 | 使用 `frpc/frpc.toml` |

 持久化 volume：

@@ -124,7 +125,10 @@ https://localhost:4443
 export SESSION_SECRET="替换为足够长的随机字符串"
 export SESSION_COOKIE_SECURE="true"
 export TRUST_PROXY="true"
-docker-compose up -d --build
+
+# XXX 先编辑 frpc/frpc.toml，替换 serverAddr 和 auth.token，再启用 frpc profile。
+docker-compose --profile frpc up -d --build
+docker-compose logs -f frpc
 ```

 Nginx Proxy Manager 配置要点：
@@ -136,6 +140,8 @@ Nginx Proxy Manager 配置要点：
 - SSL 页签绑定证书并开启 `Force SSL`，保证浏览器开放麦克风权限。
 - Advanced 中建议设置 `client_max_body_size 100m;`、`proxy_read_timeout 3600s;`、`proxy_send_timeout 3600s;`。

+`# XXX` 公网正式访问只映射 `4002` 即可；不要把本机自签名 HTTPS 演示入口 `4443` 直接映射为公网域名入口。公网 HTTPS 应由 Nginx Proxy Manager 负责。
+
 公网验收先访问 `https://sstwbg.example.com/api/health`，再登录并测试报告保存、视频抽帧、AI 对话和语音听写。

 ## 生产部署前必须修改
--- a/frpc/frpc.toml
+++ b/frpc/frpc.toml
@@ -0,0 +1,22 @@
+# XXX frpc template for exposing the local Docker web entry http://127.0.0.1:4002
+# XXX Replace serverAddr and auth.token before deploying; do not commit real production tokens.
+
+# 基础连接配置
+serverAddr = "XX.XX.XX.XX"
+serverPort = 7000
+
+# 权限验证 - 必须与服务端一致
+auth.method = "token"
+auth.token = "XXX"
+
+# 传输配置优化
+transport.poolCount = 5
+transport.heartbeatTimeout = -1
+
+# --- 映射 图文系统访问端口 (TCP) ---
+[[proxies]]
+name = "TuWen_System_V2"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 4002
+remotePort = 4002