数据包部署指南

本文档说明如何部署众趣 VR 模型数据包到阿里云存储（oss），以实现静态资源的独立部署。

一、模型数据包结构

模型资源包由众趣侧编辑、制作产生，交付格式为 {模型id}.zip。解压后目录结构如下：

{模型id}/                              # 模型数据主目录，名称为模型 ID
├── version.txt                        # 记录模型版本信息
├── background.jpg                     # 背景图
├── {版本时间戳}/                       # 模型版本目录，如 2025-06-11-13-26-28，一个模型可能存在多个版本号目录
│   ├── locations/                     # 全景切图资源
│   ├── pano_3k/                       # 3K（3000×1500）全景图资源
│   ├── resources/                     # 编辑产生的资源数据（标签、热点等）
│   ├── texture_high/                  # 高分辨率纹理文件（模型贴图）
│   └── {换装id}/                       # 换装资源目录（如有），存储换装切图
└── audio/                             # AI 讲房音频文件（如有）

目录说明

目录	说明
`locations/`	全景切图，用于全景漫游时的分块加载
`pano_3k/`	3K 分辨率全景图，用于快速预览或低带宽场景
`resources/`	编辑器产生的资源数据，包含标签、热点、导览路径等
`texture_high/`	高分辨率纹理，用于 Dollhouse 和户型图渲染
`{换装id}/`	换装资源，支持一键换装功能的全景图资源目录
`audio/`	AI 讲房音频，支持智能讲房功能音频资源目录

目录截图示意

模型版本目录其他文件相关说明模型版本-户型图图图片模型版本-其他资源

二、部署方式

2.1 云存储部署（推荐）

将数据包上传至云存储（如阿里云OSS），保持原有目录结构：

https://your-bucket.oss-cn-hangzhou.aliyuncs.com/
└── {模型id}/
    ├── version.txt
    ├── {版本号}/
    │   ├── locations/
    │   ├── pano_3k/
    │   └── ...
    └── audio/

2.2 company部署（仅需要部署一次即可）

需要额外上传一份{{your_host}}/company/company.txt的配置文件，用于zqsdk获取公司配置信息

众趣会提供一份公司配置文件夹，这里包含了公司配置文件相关数据和目录： company 公司相关资源文件夹 │ └─ resource 公司级资源文件夹，包含通用的加载动画、logo或视频素材 │ ├─ loading loading资源文件 │ ├─ logo logo资源文件 │ ├─ video 电视广告video资源文件 company.txt 记录公司级配置相关信息，如UI展示权限配置，全景慢漫游参数配置等

注意： company.txt是您公司在众趣云平台侧配置的相关资源数据，如loading资源，logo资源等文件。如果是在您进行二次开发的情况下，可以不关心resource文件夹数据（您可以使用任意的loading资源，logo资源），仅需要保证company.txt存在即可

注意事项：

CORS 配置：需配置跨域访问，允许前端域名访问资源
访问权限：设置为公开读取或配置 CDN 加速（可选）
目录结构：必须保持与数据包一致，不可修改目录名称

三、SDK 配置

部署完成后，需在 SDK 初始化时配置资源路径前缀，使 SDK 从自有服务加载资源。

3.1 resourceRequestConf 参数说明

参数	说明	示例
`resourceType`	数据包资源类型-> zq_cloud: 众趣云平台资源 custom_host: 自定义域名资源	`zq_cloud`
`customDomain`	版本资源路径前缀	`https://your_domain.com/`

3.2 代码示例

window.zqsdk.init({
  modelId: 'your_model_id',
  // (可选) 资源请求配置
  // 当众趣模型的静态资源需要在客户自己的服务器维护时使用
  // 需要设置资源请求的域名
  resourceRequestConf: {
      resourceType: 'custom_host', // zq_cloud: 众趣云平台资源  custom_host: 自定义域名资源， 当设置为zq_cloud时， customDomain的值无效， zqsdk会自动请求众趣云平台的资源
      customDomain: 'https://your_domain.com/',
  },
  complete: () => {
    // SDK 初始化完成
    window.housePlay.start()
  },
})

3.3 本仓库配置位置

在 src/stores/vr.ts 的 initSdk 函数中配置：

window.zqsdk.init({
  modelId: id,
  // (可选) 资源请求配置
  // 当众趣模型的静态资源需要在客户自己的服务器维护时使用
  // 需要设置资源请求的域名
  resourceRequestConf: {
      resourceType: 'custom_host',
      customDomain: 'https://your_domain.com/',
  },
  complete: () => {
    // ...
  },
})

四、验证部署

检查资源可访问：在浏览器中直接访问资源 URL，确认可正常下载
```
https://your-cdn.com/{模型id}/version.txt
```
检查 CORS：打开浏览器开发者工具，确认无跨域错误
检查 SDK 加载：在控制台查看网络请求，确认资源从配置的路径加载