# H5 部署说明

最后更新：2026-06-12

## 目标环境

- 域名：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`。

## 本地构建

在项目根目录执行：

```powershell
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`。

构建后重点检查：

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

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

## 部署步骤

生成部署包：

```powershell
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 .
```

上传到服务器：

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

替换线上站点：

```powershell
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` 回退。

```nginx
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;
}
```

每次修改配置后执行：

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

## 部署后验证

公网资源响应：

```powershell
curl.exe -I --max-time 30 https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260611_093623/app_nav_manifest.json
curl.exe -I --max-time 30 https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260611_093623/models_by_floor/L1.glb
curl.exe -I --max-time 30 https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260611_093623/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 校验文件，可上传到站点宿主目录：

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

验证：

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

当前 `gpL0svkeao.txt` 预期返回：

```text
b772216640a14171ba5655085c8523be
```

页面验证：

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

## 常见问题

### 模型请求返回 HTML

现象：

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

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

处理：

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

### 馆内 3D 首屏加载过慢

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

### 浏览器缓存旧包

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

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

## 回滚

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

```powershell
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
'
```

## 最近部署记录

- 2026-06-10：补齐 H5 模型资源打包，新增 `/static/nav-assets/` Nginx 规则，修复模型资源请求返回 HTML 的问题。
- 2026-06-10：馆内 3D 默认加载当前楼层模型，减少首屏模型解析压力。线上备份：`/dmdata/nginx/html/_backups/guide-before-floor-first-20260610033959.tar.gz`。
- 2026-06-10：上传域名根目录校验文件 `gpL0svkeao.txt`，公网验证地址为 `https://guide.whaoyue.com/gpL0svkeao.txt`。
- 2026-06-12：按 H5 模式重新打包并部署功能更新，线上资源包为 `app_nav_assets_v2_clean_20260611_093623`。验证通过：`pnpm type-check`、`pnpm build:h5`、Nginx `nginx -t`、manifest 200 JSON、L1.glb 200 `model/gltf-binary`、缺失 GLB 404。线上备份：`/dmdata/nginx/html/_backups/guide-before-deploy-20260612032520.tar.gz`。