feat: new projiect

2026-03-07 19:13:49 +08:00
commit ea760bb71c
27 changed files with 5866 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,162 @@
+# 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 链接对应的全景即可在本地完全离线查看与部署。