206 lines
6.6 KiB
Markdown
206 lines
6.6 KiB
Markdown
# 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`。
|