admin/Mdeical_Sur_Report
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Polish generic NAS deployment template

Browse Source 
- Rework docker-compose-Nas.yaml as a QNAP/NAS-friendly generic template with placeholders for NAS IP, public domain, proxy, and secrets.

- Preserve QNAP-specific fixes including relative build context, api network alias, NAS persistent paths, and 127.0.0.1 health checks.

- Keep optional frpc profile while avoiding real server addresses or tokens in the reusable template.

- Replace residual deployment examples with generic your-domain.example, NAS_IP, PROXY_IP, and LAN_CIDR placeholders in README and Docker docs.
This commit is contained in:
admin
2026-05-09 03:46:56 +08:00
parent 95a4678340
commit e159d18f01
4 changed files with 38 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
README.md
View File

@@ -278,15 +278,15 @@ docker compose -f docker-compose-Nas.yaml ps
# XXX 必改：生产环境不要继续使用默认 Session 密钥。 # XXX 必改：生产环境不要继续使用默认 Session 密钥。
SESSION_SECRET=替换为足够长的随机字符串 SESSION_SECRET=替换为足够长的随机字符串
# XXX 如果公网入口是 https://sstwbg.example.com，建议开启这两项。 # XXX 如果公网入口是 https://your-domain.example，建议开启这两项。
SESSION_COOKIE_SECURE=true SESSION_COOKIE_SECURE=true
TRUST_PROXY=true TRUST_PROXY=true
CORS_ORIGIN=http://192.168.31.5:4002,https://sstwbg.example.com CORS_ORIGIN=http://NAS_IP:4002,https://your-domain.example
# XXX 如需代理构建或让后端访问外网，可按 NAS 网络环境配置。 # XXX 如需代理构建或让后端访问外网，可按 NAS 网络环境配置。
HTTP_PROXY=http://192.168.31.7:7893 HTTP_PROXY=http://PROXY_IP:PROXY_PORT
HTTPS_PROXY=http://192.168.31.7:7893 HTTPS_PROXY=http://PROXY_IP:PROXY_PORT
NO_PROXY=localhost,127.0.0.1,192.168.31.0/24,tuwen_db,tuwen_api,tuwen_web,api,db,web NO_PROXY=localhost,127.0.0.1,LAN_CIDR,tuwen_db,tuwen_api,tuwen_web,api,db,web
``` ```
启用 NAS 上的 frpc 隧道： 启用 NAS 上的 frpc 隧道：
@@ -297,16 +297,16 @@ docker compose -f docker-compose-Nas.yaml --profile frpc up -d --build
docker compose -f docker-compose-Nas.yaml logs -f frpc docker compose -f docker-compose-Nas.yaml logs -f frpc
``` ```
`# XXX` NAS 公网访问仍然只需要把 `4002` 通过 frpc 映射到公网服务器，再由 Nginx Proxy Manager 给 `sstwbg.example.com` 提供 HTTPS。`4443` 仍只是本机自签名 HTTPS 演示入口，不建议映射到公网域名。 `# XXX` NAS 公网访问仍然只需要把 `4002` 通过 frpc 映射到公网服务器，再由 Nginx Proxy Manager 给 `your-domain.example` 提供 HTTPS。`4443` 仍只是本机自签名 HTTPS 演示入口，不建议映射到公网域名。
## 公网反向代理部署 ## 公网反向代理部署
<!-- # XXX 公网部署新增：适用于本机 Docker 4002 端口通过 frpc 映射到公网服务器，再由 Nginx Proxy Manager 绑定 sstwbg.example.com 的部署链路。 --> <!-- # XXX 公网部署新增：适用于本机 Docker 4002 端口通过 frpc 映射到公网服务器，再由 Nginx Proxy Manager 绑定 your-domain.example 的部署链路。 -->
推荐公网链路： 推荐公网链路：
```text ```text
浏览器 https://sstwbg.example.com 浏览器 https://your-domain.example
-> 公网服务器 Nginx Proxy Manager -> 公网服务器 Nginx Proxy Manager
-> frps/frpc 映射端口 -> frps/frpc 映射端口
-> 本机 Docker web:4002 -> 本机 Docker web:4002
@@ -363,17 +363,17 @@ docker-compose logs -f frpc
docker-compose up -d --build docker-compose up -d --build
``` ```
`# XXX` 公网正式访问只需要映射 `4002` 到公网服务器，再由公网 Nginx Proxy Manager 提供 `https://sstwbg.example.com`。不建议把 `4443` 映射到公网域名；`4443` 是本机自签名 HTTPS 演示入口，主要用于 `https://localhost:4443` 测试麦克风。 `# XXX` 公网正式访问只需要映射 `4002` 到公网服务器，再由公网 Nginx Proxy Manager 提供 `https://your-domain.example`。不建议把 `4443` 映射到公网域名；`4443` 是本机自签名 HTTPS 演示入口，主要用于 `https://localhost:4443` 测试麦克风。
Nginx Proxy Manager 中为 `sstwbg.example.com` 新建 Proxy Host： Nginx Proxy Manager 中为 `your-domain.example` 新建 Proxy Host：
- `Domain Names`：`sstwbg.example.com` - `Domain Names`：`your-domain.example`
- `Scheme`：`http` - `Scheme`：`http`
- `Forward Hostname / IP`：frps 可访问到的映射地址，通常是 `127.0.0.1`、公网服务器内网 IP 或 frps 指定监听地址。 - `Forward Hostname / IP`：frps 可访问到的映射地址，通常是 `127.0.0.1`、公网服务器内网 IP 或 frps 指定监听地址。
- `Forward Port`：frpc 暴露出来的 `remotePort`，例如 `4002`。 - `Forward Port`：frpc 暴露出来的 `remotePort`，例如 `4002`。
- `Websockets Support`：开启。`# XXX` 语音识别使用 `/api/speech/iat` WebSocket，必须透传 Upgrade。 - `Websockets Support`：开启。`# XXX` 语音识别使用 `/api/speech/iat` WebSocket，必须透传 Upgrade。
- `Block Common Exploits`：开启。 - `Block Common Exploits`：开启。
- `SSL`：申请或绑定 `sstwbg.example.com` 证书，开启 `Force SSL`。`# XXX` 浏览器麦克风权限要求 HTTPS，普通公网 HTTP 下语音识别不可用。 - `SSL`：申请或绑定 `your-domain.example` 证书，开启 `Force SSL`。`# XXX` 浏览器麦克风权限要求 HTTPS，普通公网 HTTP 下语音识别不可用。
Nginx Proxy Manager 的 `Advanced` 可加入： Nginx Proxy Manager 的 `Advanced` 可加入：
@@ -389,8 +389,8 @@ proxy_send_timeout 3600s;
公网验收顺序： 公网验收顺序：
```text ```text
1. 打开 https://sstwbg.example.com/api/health，确认 API 健康检查可访问。 1. 打开 https://your-domain.example/api/health，确认 API 健康检查可访问。
2. 打开 https://sstwbg.example.com 登录 admin / 123456。 2. 打开 https://your-domain.example 登录 admin / 123456。
3. 进入系统设置，确认 AI Provider 和讯飞语音配置有效。 3. 进入系统设置，确认 AI Provider 和讯飞语音配置有效。
4. 进入报告编辑页，测试上传视频、自动抽帧、报告保存、AI 对话和语音听写。 4. 进入报告编辑页，测试上传视频、自动抽帧、报告保存、AI 对话和语音听写。
5. 浏览器控制台执行 window.isSecureContext，应返回 true；否则语音麦克风权限不会开放。 5. 浏览器控制台执行 window.isSecureContext，应返回 true；否则语音麦克风权限不会开放。

35
docker-compose-Nas.yaml
View File

@@ -1,5 +1,5 @@
# XXX QNAP/NAS deployment compose. Designed for Container Station or docker compose on a NAS. # XXX 威联通/QNAP NAS 部署模板。
# XXX Edit /share paths, proxy variables, SESSION_SECRET, and frpc/frpc.toml before public deployment. # XXX 使用前建议复制一份 .env，按实际 NAS IP、域名、代理和密钥修改变量。
services: services:
tuwen_db: tuwen_db:
@@ -11,7 +11,7 @@ services:
POSTGRES_USER: ${POSTGRES_USER:-surclaw} POSTGRES_USER: ${POSTGRES_USER:-surclaw}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-surclaw_dev_password} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-surclaw_dev_password}
volumes: volumes:
# XXX NAS persistent database directory. Change this path if your QNAP share is different. # XXX 默认适配威联通 Container 共享目录；如目录不同，修改 NAS_DATA_ROOT。
- ${NAS_DATA_ROOT:-/share/Container/tuwen_system_v2/data}/postgres:/var/lib/postgresql/data - ${NAS_DATA_ROOT:-/share/Container/tuwen_system_v2/data}/postgres:/var/lib/postgresql/data
healthcheck: healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-surclaw} -d $${POSTGRES_DB:-surclaw}"] test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-surclaw} -d $${POSTGRES_DB:-surclaw}"]
@@ -21,38 +21,38 @@ services:
tuwen_api: tuwen_api:
build: build:
# XXX Keep relative context for QNAP, otherwise Container Station may fail to resolve absolute paths. # XXX 威联通 Container Station 对绝对路径解析不稳定，保持相对 context。
context: . context: .
dockerfile: Dockerfile.server dockerfile: Dockerfile.server
args: args:
HTTP_PROXY: ${HTTP_PROXY:-} HTTP_PROXY: ${HTTP_PROXY:-}
HTTPS_PROXY: ${HTTPS_PROXY:-} HTTPS_PROXY: ${HTTPS_PROXY:-}
NO_PROXY: ${NO_PROXY:-localhost,127.0.0.1,192.168.31.0/24,tuwen_db,tuwen_api,tuwen_web,api,db,web} NO_PROXY: ${NO_PROXY:-localhost,127.0.0.1,tuwen_db,tuwen_api,tuwen_web,api,db,web}
container_name: tuwen_api container_name: tuwen_api
restart: unless-stopped restart: unless-stopped
networks: networks:
default: default:
aliases: aliases:
# XXX nginx.conf proxies /api to http://api:3100, so NAS service keeps this alias. # XXX nginx.conf 中 /api 固定代理到 http://api:3100，NAS 服务需要保留该别名。
- api - api
depends_on: depends_on:
tuwen_db: tuwen_db:
condition: service_healthy condition: service_healthy
ports: ports:
# XXX Optional host API port for NAS diagnostics; public users should enter through web:4002/NPM. # XXX API 诊断端口；公网访问应走 web:4002/Nginx Proxy Manager。
- "${NAS_API_PORT:-4102}:3100" - "${NAS_API_PORT:-4102}:3100"
volumes: volumes:
# XXX NAS persistent upload directory for signatures, videos, keyframes, and template images. # XXX 持久化签名、视频、关键帧和模板图片等上传文件。
- ${NAS_DATA_ROOT:-/share/Container/tuwen_system_v2/data}/uploads:/app/uploads - ${NAS_DATA_ROOT:-/share/Container/tuwen_system_v2/data}/uploads:/app/uploads
environment: environment:
NODE_ENV: production NODE_ENV: production
API_PORT: 3100 API_PORT: 3100
API_BODY_LIMIT: ${API_BODY_LIMIT:-100mb} API_BODY_LIMIT: ${API_BODY_LIMIT:-100mb}
DATABASE_URL: postgresql://${POSTGRES_USER:-surclaw}:${POSTGRES_PASSWORD:-surclaw_dev_password}@tuwen_db:5432/${POSTGRES_DB:-surclaw}?schema=public DATABASE_URL: postgresql://${POSTGRES_USER:-surclaw}:${POSTGRES_PASSWORD:-surclaw_dev_password}@tuwen_db:5432/${POSTGRES_DB:-surclaw}?schema=public
CORS_ORIGIN: ${CORS_ORIGIN:-http://192.168.31.5:4002,https://sstwbg.example.com} # XXX 示例：CORS_ORIGIN=http://NAS_IP:4002,https://your-domain.example
# XXX Replace in NAS .env or Container Station variables before real deployment. CORS_ORIGIN: ${CORS_ORIGIN:-http://localhost:4002,https://localhost:4443}
# XXX 生产环境必须替换；公网 HTTPS 入口建议同时设置 SESSION_COOKIE_SECURE=true 和 TRUST_PROXY=true。
SESSION_SECRET: ${SESSION_SECRET:-change-me-in-production} SESSION_SECRET: ${SESSION_SECRET:-change-me-in-production}
# XXX For public HTTPS through Nginx Proxy Manager, set SESSION_COOKIE_SECURE=true and TRUST_PROXY=true.
SESSION_COOKIE_SECURE: ${SESSION_COOKIE_SECURE:-false} SESSION_COOKIE_SECURE: ${SESSION_COOKIE_SECURE:-false}
TRUST_PROXY: ${TRUST_PROXY:-false} TRUST_PROXY: ${TRUST_PROXY:-false}
FILE_STORAGE_DIR: /app/uploads FILE_STORAGE_DIR: /app/uploads
@@ -64,9 +64,9 @@ services:
HTTPS_PROXY: ${HTTPS_PROXY:-} HTTPS_PROXY: ${HTTPS_PROXY:-}
http_proxy: ${HTTP_PROXY:-} http_proxy: ${HTTP_PROXY:-}
https_proxy: ${HTTPS_PROXY:-} https_proxy: ${HTTPS_PROXY:-}
NO_PROXY: ${NO_PROXY:-localhost,127.0.0.1,192.168.31.0/24,tuwen_db,tuwen_api,tuwen_web,api,db,web} NO_PROXY: ${NO_PROXY:-localhost,127.0.0.1,tuwen_db,tuwen_api,tuwen_web,api,db,web}
healthcheck: healthcheck:
# XXX Use 127.0.0.1 instead of localhost to avoid IPv6 resolution issues on some NAS firmware. # XXX 使用 127.0.0.1，规避部分 NAS 固件中 localhost 优先解析 IPv6 的问题。
test: ["CMD-SHELL", "node -e \"fetch('http://127.0.0.1:3100/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""] test: ["CMD-SHELL", "node -e \"fetch('http://127.0.0.1:3100/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
interval: 10s interval: 10s
timeout: 5s timeout: 5s
@@ -75,13 +75,12 @@ services:
tuwen_web: tuwen_web:
build: build:
# XXX Keep relative context for QNAP.
context: . context: .
dockerfile: Dockerfile dockerfile: Dockerfile
args: args:
HTTP_PROXY: ${HTTP_PROXY:-} HTTP_PROXY: ${HTTP_PROXY:-}
HTTPS_PROXY: ${HTTPS_PROXY:-} HTTPS_PROXY: ${HTTPS_PROXY:-}
NO_PROXY: ${NO_PROXY:-localhost,127.0.0.1,192.168.31.0/24,tuwen_db,tuwen_api,tuwen_web,api,db,web} NO_PROXY: ${NO_PROXY:-localhost,127.0.0.1,tuwen_db,tuwen_api,tuwen_web,api,db,web}
container_name: tuwen_web container_name: tuwen_web
restart: unless-stopped restart: unless-stopped
depends_on: depends_on:
@@ -89,10 +88,10 @@ services:
condition: service_healthy condition: service_healthy
ports: ports:
- "${NAS_WEB_PORT:-4002}:80" - "${NAS_WEB_PORT:-4002}:80"
# XXX Local self-signed HTTPS demo only. Public HTTPS should be handled by Nginx Proxy Manager. # XXX 仅用于本机自签名 HTTPS 演示；公网 HTTPS 应由 Nginx Proxy Manager 提供。
- "${NAS_HTTPS_DEMO_PORT:-4443}:443" - "${NAS_HTTPS_DEMO_PORT:-4443}:443"
environment: environment:
APP_URL: ${APP_URL:-http://192.168.31.5:4002} APP_URL: ${APP_URL:-http://localhost:4002}
healthcheck: healthcheck:
test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1/ || exit 1"] test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1/ || exit 1"]
interval: 10s interval: 10s
@@ -100,7 +99,7 @@ services:
retries: 6 retries: 6
frpc: frpc:
# XXX Optional public tunnel client. Edit frpc/frpc.toml before enabling this profile. # XXX 可选公网隧道客户端。启用前先编辑 frpc/frpc.toml。
image: snowdreamtech/frpc:latest image: snowdreamtech/frpc:latest
container_name: tuwen_frpc container_name: tuwen_frpc
restart: unless-stopped restart: unless-stopped

4
docs/deployment.md
View File

@@ -106,7 +106,7 @@ docker-compose up -d --build
推荐链路： 推荐链路：
```text ```text
浏览器 https://sstwbg.example.com 浏览器 https://your-domain.example
-> 公网服务器 Nginx Proxy Manager -> 公网服务器 Nginx Proxy Manager
-> frps/frpc 映射端口 -> frps/frpc 映射端口
-> 本机 Docker web:4002 -> 本机 Docker web:4002
@@ -127,7 +127,7 @@ docker-compose --profile frpc up -d --build
docker-compose logs -f frpc docker-compose logs -f frpc
``` ```
Nginx Proxy Manager 代理 `sstwbg.example.com` 时： Nginx Proxy Manager 代理 `your-domain.example` 时：
- 代理目标指向 frpc 暴露的 `4002` 映射端口。 - 代理目标指向 frpc 暴露的 `4002` 映射端口。
- 开启 `Websockets Support`，否则 `/api/speech/iat` 语音 WebSocket 会失败。 - 开启 `Websockets Support`，否则 `/api/speech/iat` 语音 WebSocket 会失败。

10
docs/docker.md
View File

@@ -85,7 +85,7 @@ curl http://127.0.0.1:4002/api/health
SESSION_SECRET=替换为足够长的随机字符串 SESSION_SECRET=替换为足够长的随机字符串
SESSION_COOKIE_SECURE=true SESSION_COOKIE_SECURE=true
TRUST_PROXY=true TRUST_PROXY=true
CORS_ORIGIN=http://192.168.31.5:4002,https://sstwbg.example.com CORS_ORIGIN=http://NAS_IP:4002,https://your-domain.example
``` ```
启用 NAS 上的 frpc 隧道： 启用 NAS 上的 frpc 隧道：
@@ -149,9 +149,9 @@ https://localhost:4443
## 公网域名反向代理 ## 公网域名反向代理
<!-- # XXX 公网部署新增：适用于本机 Docker 4002 端口经 frpc 映射到公网服务器，再由 Nginx Proxy Manager 绑定 sstwbg.example.com。 --> <!-- # XXX 公网部署新增：适用于本机 Docker 4002 端口经 frpc 映射到公网服务器，再由 Nginx Proxy Manager 绑定 your-domain.example。 -->
如果使用 `本机 Docker 4002 -> frpc -> 公网服务器 Nginx Proxy Manager -> sstwbg.example.com`，推荐流程： 如果使用 `本机 Docker 4002 -> frpc -> 公网服务器 Nginx Proxy Manager -> your-domain.example`，推荐流程：
```bash ```bash
# XXX 使用公网 HTTPS 入口时，compose 变量可从 shell 或 .env 覆盖。 # XXX 使用公网 HTTPS 入口时，compose 变量可从 shell 或 .env 覆盖。
@@ -166,7 +166,7 @@ docker-compose logs -f frpc
Nginx Proxy Manager 配置要点： Nginx Proxy Manager 配置要点：
- `Domain Names` 使用 `sstwbg.example.com`。 - `Domain Names` 使用 `your-domain.example`。
- `Forward Hostname / IP` 指向 frpc 在公网服务器暴露的地址。 - `Forward Hostname / IP` 指向 frpc 在公网服务器暴露的地址。
- `Forward Port` 填 frpc 暴露的端口，例如 `4002`。 - `Forward Port` 填 frpc 暴露的端口，例如 `4002`。
- 开启 `Websockets Support`，保证 `/api/speech/iat` 语音听写 WebSocket 可升级。 - 开启 `Websockets Support`，保证 `/api/speech/iat` 语音听写 WebSocket 可升级。
@@ -175,7 +175,7 @@ Nginx Proxy Manager 配置要点：
`# XXX` 公网正式访问只映射 `4002` 即可；不要把本机自签名 HTTPS 演示入口 `4443` 直接映射为公网域名入口。公网 HTTPS 应由 Nginx Proxy Manager 负责。 `# XXX` 公网正式访问只映射 `4002` 即可；不要把本机自签名 HTTPS 演示入口 `4443` 直接映射为公网域名入口。公网 HTTPS 应由 Nginx Proxy Manager 负责。
公网验收先访问 `https://sstwbg.example.com/api/health`，再登录并测试报告保存、视频抽帧、AI 对话和语音听写。 公网验收先访问 `https://your-domain.example/api/health`，再登录并测试报告保存、视频抽帧、AI 对话和语音听写。
## 生产部署前必须修改 ## 生产部署前必须修改