179 lines
7.1 KiB
Markdown
179 lines
7.1 KiB
Markdown
# 720yun 全景本地化 / 离线部署
|
||
|
||
将 [720云](https://www.720yun.com) 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 时有效）
|
||
|
||
```bash
|
||
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. 安装与运行（开发/本地）
|
||
|
||
```bash
|
||
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](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. 构建出站目录（部署用）
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
会将 `index.html`、`config.json`、`lib/`、`image/` 复制到 **`dist/`**。若需保留统计与弹幕功能，需将 **Node 服务（server.js + db.js + data/）** 一并部署；仅部署静态 `dist/` 时，前端会请求 `/api` 失败，观看/点赞/分享/留言不落库。
|
||
|
||
### 4. 预览构建结果
|
||
|
||
```bash
|
||
npm run preview
|
||
```
|
||
|
||
先执行 `npm run build`，再以 `dist/` 为根目录启动服务器，用于验证部署包。
|
||
|
||
### 4. 确认/修改 `config.json`
|
||
|
||
默认已配置为使用 **立方体六面图**（`image/` 下 mobile_f → mobile_d）：
|
||
|
||
```json
|
||
{
|
||
"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：**
|
||
|
||
```bash
|
||
python3 -m http.server 8080
|
||
```
|
||
|
||
**npx serve：**
|
||
|
||
```bash
|
||
npx serve -p 8080
|
||
```
|
||
|
||
### 7. 离线部署到其它机器
|
||
|
||
将整个项目（或仅 `dist/`）拷贝到 U 盘或内网服务器，在目标机器上执行 `npm start` 或部署 `dist/` 到 Web 服务器即可，无需外网。
|
||
|
||
---
|
||
|
||
## 三、多场景与热点（可选）
|
||
|
||
若 720 原页有多场景或热点，可参考 [Pannellum 配置说明](https://pannellum.org/documentation/reference/)：
|
||
|
||
- **多场景**：在 `config.json` 中使用 `default.firstScene` + `scenes`，每个 scene 指定自己的 `panorama` 路径。
|
||
- **热点**：在对应 scene 下配置 `hotSpots`（`pitch`、`yaw`、`type`、`text`、`sceneId` 等）。
|
||
|
||
可将 720 页面上的场景列表与热点信息手工抄写到 `config.json`，实现与线上类似的跳转效果。
|
||
|
||
---
|
||
|
||
## 四、技术说明
|
||
|
||
- **查看器**：[Pannellum](https://pannellum.org/)（轻量、开源、支持 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 链接对应的全景即可在本地完全离线查看与部署。
|