lyf/frontend-miniapp

Fork 0

Files

lyf 9790501c3b chore: solidify guide P1 snapshot

2026-06-11 16:18:57 +08:00

6.3 KiB

Raw Blame History

H5 部署说明

最后更新：2026-06-10

目标环境

域名：https://guide.whaoyue.com/
SSH 连接别名：自然博物馆-测试服务器
服务器 IP：1.92.206.90
站点宿主目录：/dmdata/nginx/html/guide
Nginx 配置：/dmdata/nginx/conf.d/guide.whaoyue.com.conf
Nginx 容器：nginx-server
H5 构建目录：dist/build/h5

说明：Nginx 容器内站点根目录为 /usr/share/nginx/html/guide，宿主机对应目录为 /dmdata/nginx/html/guide。

本地构建

在项目根目录执行：

pnpm install
pnpm type-check
pnpm build:h5

pnpm build:h5 会先执行 uni build -p h5，再执行 scripts/copy-h5-nav-assets.cjs，把 static/nav-assets 复制到 dist/build/h5/static/nav-assets。

构建后重点检查：

Get-ChildItem -LiteralPath 'dist\build\h5\static\nav-assets\app_nav_assets_v2_clean_20260609_075339' -Recurse -File |
  Measure-Object Length -Sum |
  Select-Object Count,Sum

当前导航模型资源包应包含 25 个文件，文件总字节数约 26811587。

部署步骤

生成部署包：

New-Item -ItemType Directory -Force -Path '.tmp' | Out-Null
$archive = '.tmp\museum-guide-h5.tar.gz'
if (Test-Path -LiteralPath $archive) { Remove-Item -LiteralPath $archive -Force }
tar -C 'dist\build\h5' -czf $archive .

上传到服务器：

scp -o BatchMode=yes '.tmp\museum-guide-h5.tar.gz' '自然博物馆-测试服务器:/tmp/museum-guide-h5.tar.gz'

替换线上站点：

ssh -o BatchMode=yes '自然博物馆-测试服务器' 'set -e
SITE=/dmdata/nginx/html/guide
ARCHIVE=/tmp/museum-guide-h5.tar.gz
TS=$(date +%Y%m%d%H%M%S)
BACKUP_DIR=/dmdata/nginx/html/_backups
[ "$SITE" = "/dmdata/nginx/html/guide" ]
test -f "$ARCHIVE"
mkdir -p "$SITE" "$BACKUP_DIR"
tar -C "$SITE" -czf "$BACKUP_DIR/guide-before-deploy-$TS.tar.gz" .
find "$SITE" -mindepth 1 -maxdepth 1 ! -name ".well-known" -exec rm -rf -- {} +
tar -C "$SITE" -xzf "$ARCHIVE"
mkdir -p "$SITE/.well-known/acme-challenge"
chown -R root:root "$SITE"
docker exec nginx-server nginx -t
docker exec nginx-server nginx -s reload
printf "backup=%s\n" "$BACKUP_DIR/guide-before-deploy-$TS.tar.gz"
printf "files=%s\n" "$(find "$SITE" -type f | wc -l)"
'

Nginx 关键配置

/static/nav-assets/ 必须独立配置，避免模型、manifest、楼层数据缺失时落入 SPA 的 /index.html 回退。

location ^~ /static/nav-assets/ {
    types {
        application/json json;
        model/gltf-binary glb;
        model/gltf+json gltf;
        text/csv csv;
        text/markdown md;
    }
    default_type application/octet-stream;
    expires 30d;
    add_header Cache-Control "public";
    try_files $uri =404;
}

location / {
    try_files $uri $uri/ /index.html;
}

每次修改配置后执行：

ssh -o BatchMode=yes '自然博物馆-测试服务器' 'docker exec nginx-server nginx -t && docker exec nginx-server nginx -s reload'

部署后验证

公网资源响应：

curl.exe -I --max-time 30 https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260609_075339/app_nav_manifest.json
curl.exe -I --max-time 30 https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260609_075339/models_by_floor/L1.glb
curl.exe -I --max-time 30 https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260609_075339/models_by_floor/MISSING.glb

预期结果：

app_nav_manifest.json：200，Content-Type: application/json
models_by_floor/L1.glb：200，Content-Type: model/gltf-binary
缺失 GLB：404，不能返回 index.html

域名根目录校验文件

如第三方平台要求在域名根目录放置 TXT 校验文件，可上传到站点宿主目录：

scp -o BatchMode=yes 'E:\MyWork\深圳自然馆\服务器信息\对接文档\gpL0svkeao.txt' '自然博物馆-测试服务器:/dmdata/nginx/html/guide/gpL0svkeao.txt'

验证：

curl.exe -L --max-time 30 https://guide.whaoyue.com/gpL0svkeao.txt

当前 gpL0svkeao.txt 预期返回：

b772216640a14171ba5655085c8523be

页面验证：

打开 https://guide.whaoyue.com/#/
切换到 室内3D
首次进入应加载当前楼层模型，而不是先加载全馆 overview 模型
不应出现 Unexpected token '<', "<!DOCTYPE "... is not valid JSON

常见问题

模型请求返回 HTML

现象：

SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON

原因通常是 H5 产物缺少 static/nav-assets，或 Nginx 未对 /static/nav-assets/ 使用 try_files $uri =404。

处理：

确认 pnpm build:h5 已执行资源复制脚本。
确认服务器存在 /dmdata/nginx/html/guide/static/nav-assets/app_nav_assets_v2_clean_20260609_075339。
确认 Nginx /static/nav-assets/ 配置生效。
强刷浏览器，避免继续使用旧 JS。

室内 3D 首屏加载过慢

导览页已配置为 initial-view="floor"，进入室内 3D 时优先加载当前楼层模型。不要在导览壳层中默认加载全馆 overview 模型，否则低性能设备可能长时间停留在 100% 或页面无响应。

浏览器缓存旧包

如果线上已经替换但页面仍异常，使用带参数的地址强制刷新：

https://guide.whaoyue.com/?v=YYYYMMDDHHmm#/

回滚

部署脚本会在 /dmdata/nginx/html/_backups 下生成备份包。回滚示例：

ssh -o BatchMode=yes '自然博物馆-测试服务器' 'set -e
SITE=/dmdata/nginx/html/guide
BACKUP=/dmdata/nginx/html/_backups/guide-before-deploy-YYYYMMDDHHmmss.tar.gz
[ "$SITE" = "/dmdata/nginx/html/guide" ]
test -f "$BACKUP"
find "$SITE" -mindepth 1 -maxdepth 1 ! -name ".well-known" -exec rm -rf -- {} +
tar -C "$SITE" -xzf "$BACKUP"
docker exec nginx-server nginx -t
docker exec nginx-server nginx -s reload
'

6.3 KiB Raw Blame History Unescape Escape