720yun 全景本地化 / 离线部署

将 720云 VR 全景页面内容抓取并本地化，实现完全离线部署与查看。

目标示例：https://www.720yun.com/vr/c8525usOunr

---

项目结构（前后端分离）

720yun-offline/
├── index.html       # 前端页面（Pannellum + 统计/弹幕）
├── config.json      # 全景配置（六面图、简介等）
├── api.config.json  # 前端用：API 根地址，空为同源
├── lib/             # Pannellum
├── image/           # 六面体全景图
├── server.js        # 本地联合模式：静态 + 挂载 server/ API
├── build.js         # 构建前端静态到 dist/
├── package.json     # 根目录：start / build / preview
├── server/          # 后端（可单独部署）
│   ├── server.js    # Express API 路由
│   ├── db.js        # JSON 存储（统计、留言、弹幕开关）
│   ├── index.js     # 单独启动 API：node index.js
│   ├── package.json # 后端依赖
│   └── data/        # store.json（自动创建）
├── scripts/         # 720 云资源提取脚本（Python）
│   ├── fetch_720yun.py   # 按 URL 抓取并下载全景图到 panorama/
│   └── parse_720yun_doc.py # 从 text.md 解析资源，--download 下载到 image/
├── docs/部署说明.md # 前后端分离部署与弹幕配置
└── README.md

---

一、获取 720yun 全景图（二选一）

方式 A：自动抓取（仅当页面 HTML 里直接包含图片 URL 时有效）

cd 720yun-offline
python3 scripts/fetch_720yun.py "https://www.720yun.com/vr/c8525usOunr"

若输出「未在页面 HTML 中发现全景图 URL」，说明该页由前端 JS 请求接口加载数据，请用方式 B。

方式 B：手动获取（推荐，适用于所有 720 链接）

1. 在浏览器中打开目标链接：
   https://www.720yun.com/vr/c8525usOunr
2. 打开开发者工具：F12（或 右键 → 检查）→ 切到 Network（网络）。
3. 勾选 Disable cache，刷新页面（F5）。
4. 在筛选里选择 Img 或 XHR/Fetch：
   • Img：找尺寸很大的图片（如 4096×2048、8192×4096 等），即全景图。
   • XHR/Fetch：找返回 JSON 的接口（如含 scene、panorama、url 等字段），从返回里拿到全景图 URL。
5. 在找到的图片或接口响应里复制图片 URL，在浏览器新标签页打开该 URL，右键 → 图片另存为，保存到本项目的 panorama/ 目录，命名为 panorama.jpg（或其它名字，见下方配置）。

若有多场景（多个全景图），可保存为 panorama/scene1.jpg、panorama/scene2.jpg 等，并在 config.json 的 scenes 中配置多场景（见 Pannellum 文档）。

---

二、Node 构建与部署（推荐）

项目已用 Node 方式组织，默认使用 image/ 下六面图（由 scripts/parse_720yun_doc.py --download 拉取），打开页面即自动加载。

1. 安装与运行（开发/本地）

cd 720yun-offline
npm install
npm start

浏览器访问 http://localhost:3000，会自动加载 config.json 中的立方体六面图（image/mobile_*.jpg）。
服务端会创建 server/data/store.json（纯 JSON 存储，无原生依赖），用于存储：累积播放、实时在看、点赞数、分享数、留言（弹幕）。留言以弹幕形式在画面上方滚动播放。

2. Linux 启动脚本（推荐）

在 Linux 服务器上可使用根目录下的 shell 脚本一键启动，详见 docs/Linux启动说明.md。

脚本	说明
./start.sh	联合启动：静态 + API，单端口（默认 3000）
./start-api.sh	仅启动后端 API（前后端分离时用）
./start-front.sh	构建前端并启动静态预览（默认 8080）

首次使用需执行 chmod +x start.sh start-api.sh start-front.sh。修改端口可设置环境变量 PORT 或 FRONT_PORT。

3. 构建出站目录（部署用）

npm run build

会将 index.html、config.json、lib/、image/ 复制到 dist/。若需保留统计与弹幕功能，需将 Node 服务（server.js + db.js + data/） 一并部署；仅部署静态 dist/ 时，前端会请求 /api 失败，观看/点赞/分享/留言不落库。

4. 预览构建结果

npm run preview

先执行 npm run build，再以 dist/ 为根目录启动服务器，用于验证部署包。

4. 确认/修改 config.json

默认已配置为使用 立方体六面图（image/ 下 mobile_f → mobile_d）：

{
  "type": "cubemap",
  "cubeMap": [
    "image/mobile_f.jpg",
    "image/mobile_r.jpg",
    "image/mobile_b.jpg",
    "image/mobile_l.jpg",
    "image/mobile_u.jpg",
    "image/mobile_d.jpg"
  ],
  "title": "720° 全景离线",
  "autoLoad": true,
  ...
}

若使用单张 2:1 全景图，可改为 "type": "equirectangular"、"panorama": "panorama/panorama.jpg"。

6. 其它方式起 HTTP 服务

因浏览器安全限制，不能直接用 file:// 打开。除 npm start 外也可：

Python 3：

python3 -m http.server 8080

npx serve：

npx serve -p 8080

7. 离线部署到其它机器

将整个项目（或仅 dist/）拷贝到 U 盘或内网服务器，在目标机器上执行 npm start 或部署 dist/ 到 Web 服务器即可，无需外网。

---

三、多场景与热点（可选）

若 720 原页有多场景或热点，可参考 Pannellum 配置说明：

• 多场景：在 config.json 中使用 default.firstScene + scenes，每个 scene 指定自己的 panorama 路径。
• 热点：在对应 scene 下配置 hotSpots（pitch、yaw、type、text、sceneId 等）。

可将 720 页面上的场景列表与热点信息手工抄写到 config.json，实现与线上类似的跳转效果。

---

四、技术说明

• 查看器：Pannellum（轻量、开源、支持 equirectangular 全景）。
• 图片格式：支持 2:1 等距柱状投影（equirectangular）全景图；若 720 提供的是立方体六面图，可在 config.json 中设置 type: "cubemap" 并配置 cubeMap 六张图路径。
• 版权：仅建议对您拥有版权或已获授权的内容做本地化与离线使用。

---

五、常见问题

问题	处理
打开 index.html 空白或报错	必须通过 http://localhost:端口 访问，不要用 file://。
提示「全景图加载失败」	检查 config.json 里 panorama 或 cubeMap 路径是否正确，以及 image/（或 panorama/）下是否有对应文件。
自动脚本拿不到图	720 很多页面是前端请求接口再渲染，用「方式 B」在 Network 里找图片或接口即可。
想用 VR 眼镜 / 陀螺仪	Pannellum 支持部分设备朝向；如需完整 VR，可考虑其全屏 + 设备 API 或其它 WebXR 方案。

完成以上步骤后，该 720 链接对应的全景即可在本地完全离线查看与部署。