chore: solidify guide P1 snapshot
This commit is contained in:
204
docs/H5_DEPLOYMENT_GUIDE.md
Normal file
204
docs/H5_DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# 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`。
|
||||
|
||||
## 本地构建
|
||||
|
||||
在项目根目录执行：
|
||||
|
||||
```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_20260609_075339' -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_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 校验文件，可上传到站点宿主目录：
|
||||
|
||||
```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_20260609_075339`。
|
||||
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`。
|
||||
Reference in New Issue
Block a user