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

将 [720云](https://www.720yun.com) VR 全景页面内容抓取并本地化，实现**完全离线**部署与查看。

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

---

## 项目结构

```
720yun-offline/
├── index.html       # 本地全景查看页（Pannellum）
├── config.json      # 全景配置（默认使用 image/ 六面图）
├── lib/
│   ├── pannellum.js
│   └── pannellum.css
├── image/           # 六面体全景图（mobile_f/r/b/l/u/d.jpg），默认展示来源
├── panorama/        # 单张全景图（可选）
├── server.js        # Node 静态 + API 服务（统计、留言、弹幕）
├── db.js            # SQLite 封装（data/pano.db）
├── data/            # 数据库目录（自动创建，已 gitignore）
├── build.js         # 构建脚本，产出 dist/ 便于部署
├── package.json     # Node 脚本：start / build / preview
├── fetch_720yun.py  # 自动抓取脚本（若页面有直出 URL 则可用）
├── parse_720yun_doc.py  # 从 text.md 解析 URL，--download 下载到 image/
└── README.md
```

---

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

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

```bash
cd 720yun-offline
python3 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/` 下六面图**（由 `parse_720yun_doc.py --download` 拉取），打开页面即自动加载。

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

```bash
cd 720yun-offline
npm install
npm start
```

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

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

```bash
npm run build
```

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

### 3. 预览构建结果

```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"`。

### 5. 其它方式起 HTTP 服务

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

**Python 3：**

```bash
python3 -m http.server 8080
```

**npx serve：**

```bash
npx serve -p 8080
```

### 6. 离线部署到其它机器

将整个项目（或仅 `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 链接对应的全景即可在本地完全离线查看与部署。