fix:优化启动配置

README.md

@@ -74,7 +74,19 @@ npm start
 浏览器访问 **http://localhost:3000**，会自动加载 `config.json` 中的立方体六面图（`image/mobile_*.jpg`）。  
 服务端会创建 **`server/data/store.json`**（纯 JSON 存储，无原生依赖），用于存储：**累积播放、实时在看、点赞数、分享数、留言（弹幕）**。留言以弹幕形式在画面上方滚动播放。
 
-### 2. 构建出站目录（部署用）
+### 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
@@ -82,7 +94,7 @@ npm run build
 
 会将 `index.html`、`config.json`、`lib/`、`image/` 复制到 **`dist/`**。若需保留统计与弹幕功能，需将 **Node 服务（server.js + db.js + data/）** 一并部署；仅部署静态 `dist/` 时，前端会请求 `/api` 失败，观看/点赞/分享/留言不落库。
 
-### 3. 预览构建结果
+### 4. 预览构建结果
 
 ```bash
 npm run preview
@@ -113,7 +125,7 @@ npm run preview
 
 若使用单张 2:1 全景图，可改为 `"type": "equirectangular"`、`"panorama": "panorama/panorama.jpg"`。
 
-### 5. 其它方式起 HTTP 服务
+### 6. 其它方式起 HTTP 服务
 
 因浏览器安全限制，不能直接用 `file://` 打开。除 `npm start` 外也可：
 
@@ -129,7 +141,7 @@ python3 -m http.server 8080
 npx serve -p 8080
 ```
 
-### 6. 离线部署到其它机器
+### 7. 离线部署到其它机器
 
 将整个项目（或仅 `dist/`）拷贝到 U 盘或内网服务器，在目标机器上执行 `npm start` 或部署 `dist/` 到 Web 服务器即可，无需外网。
 

docs/Linux启动说明.md

@@ -0,0 +1,138 @@
+# Linux 环境启动说明
+
+本文说明在 Linux 服务器上如何启动本项目（联合模式与前后端分离模式）。
+
+---
+
+## 环境要求
+
+- **Node.js** >= 14（推荐 18 或 20 LTS）
+- 可选：Python 3（仅在使用 `scripts/` 下 720 云提取脚本时需要）
+
+安装 Node（示例，以实际环境为准）：
+
+```bash
+# 使用 nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+source ~/.bashrc
+nvm install 18
+nvm use 18
+
+# 或使用系统包管理器
+# Ubuntu/Debian: sudo apt install nodejs npm
+# CentOS: sudo yum install nodejs npm
+```
+
+---
+
+## 方式一：联合启动（前后端同机、单端口）
+
+适合本机或单台服务器同时提供页面和 API，访问一个端口即可。
+
+1. 上传项目到服务器（或 `git clone`），进入项目根目录：
+
+   ```bash
+   cd /path/to/720yun-offline
+   ```
+
+2. 使用启动脚本（推荐）：
+
+   ```bash
+   chmod +x start.sh
+   ./start.sh
+   ```
+
+   或在当前终端前台运行：
+
+   ```bash
+   bash start.sh
+   ```
+
+3. 或手动执行：
+
+   ```bash
+   npm install
+   npm start
+   ```
+
+4. 默认端口 **3000**。修改端口可设置环境变量后再启动：
+
+   ```bash
+   export PORT=8080
+   ./start.sh
+   ```
+
+5. 浏览器访问：`http://服务器IP:3000`（或你设置的端口）。
+
+**说明**：`start.sh` 会先执行根目录 `npm install`，再执行 `node server.js`，同时提供静态页面和 `/api` 接口。
+
+---
+
+## 方式二：前后端分离启动
+
+适合前端、后端分别部署（如前端 Nginx、后端 Node），或需要单独调试 API 时使用。
+
+### 1. 启动后端 API
+
+在项目根目录执行：
+
+```bash
+chmod +x start-api.sh
+./start-api.sh
+```
+
+或手动：
+
+```bash
+cd server
+npm install
+npm start
+```
+
+- 默认端口以 **start-api.sh** 内为准（如 5599），若与联合模式同机需避免端口冲突。
+- 修改端口：`PORT=3001 ./start-api.sh` 或 `cd server && PORT=3001 npm start`。
+- 数据文件：`server/data/store.json`（自动创建）。
+- **重要**：前后端分离时，前端 **api.config.json** 的 `apiBase` 必须填后端完整地址（含端口），例如 `"http://你的域名或IP:5599"`，否则页面无法请求统计/弹幕等接口。
+- 生产环境建议用 **pm2** 保活，例如：
+  ```bash
+  cd server && npm install && PORT=5599 npx pm2 start index.js --name pano-api
+  ```
+
+### 2. 启动前端（静态资源）
+
+**选项 A：用脚本构建并临时预览**
+
+```bash
+chmod +x start-front.sh
+./start-front.sh
+```
+
+- 会执行 `npm run build` 生成 `dist/`，再用静态服务托管 `dist/`，默认端口 **8080**。
+- 修改端口：`FRONT_PORT=8080 ./start-front.sh`。
+- 此时前端与后端分离，需在 **根目录 `api.config.json`**（构建会复制到 dist）中设置 `apiBase` 为后端地址**且端口与 start-api.sh 一致**，例如后端端口 5599 则填 `"http://你的域名或IP:5599"`，否则页面无法请求到统计/弹幕等接口。
+
+**选项 B：部署到 Nginx**
+
+1. 在项目根目录执行 `npm run build`。
+2. 将 `dist/` 内所有文件拷贝到 Nginx 站点目录。
+3. 在 Nginx 中配置该目录为 root。若 API 同域并反代到后端（如 `proxy_pass http://127.0.0.1:5599`），则 `api.config.json` 的 `apiBase` 可留空 `""`；否则必须填后端完整地址（含端口）。
+
+---
+
+## 脚本说明
+
+| 脚本 | 作用 |
+|------|------|
+| **start.sh** | 联合启动：根目录安装依赖并启动 `server.js`，同时提供静态 + API（默认 3000）。 |
+| **start-api.sh** | 仅启动后端：进入 `server/` 安装依赖并启动 API（默认 3000）。 |
+| **start-front.sh** | 构建前端到 `dist/` 并启动静态服务预览（默认 8080），需自行配置 `api.config.json` 指向后端。 |
+
+所有脚本均可在 Linux 下直接执行，需先 `chmod +x 脚本名`。
+
+---
+
+## 常见问题
+
+- **端口被占用**：修改 `PORT`（联合/后端）或脚本内前端端口后再启动。
+- **无权限监听 80**：使用 3000/8080 等高位端口，或用 Nginx 反代。
+- **跨域**：前后端分离且不同域时，后端已设置 CORS；可限制来源：在启动后端前设置 `CORS_ORIGIN=https://你的前端域名`。

run.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# 部署流程：拉代码 → 安装依赖 → 构建前端到 dist/ → 启动后端 API（5599）
+# 若 Nginx 未反代 /api，请先设置 API_BASE_URL 再执行，例如：
+#   export API_BASE_URL="http://你的域名或IP:5599"
+#   ./run.sh
+# 若 Nginx 已将 /api 反代到本机 5599，可留空 api.config.json（apiBase 为空即可）。
+
+set -e
+cd "$(dirname "$0")"
+
+git fetch origin && git reset --hard origin/master
+npm install --no-audit --no-fund
+
+# 若设置了 API_BASE_URL，则写入 api.config.json，供 build 复制到 dist/
+if [ -n "$API_BASE_URL" ]; then
+  echo "[run.sh] 使用 API_BASE_URL=$API_BASE_URL"
+  node -e "require('fs').writeFileSync('api.config.json', JSON.stringify({ apiBase: process.env.API_BASE_URL }, null, 2))"
+fi
+
+node build.js
+bash start-api.sh

start-api.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# 仅启动后端 API（前后端分离时使用）
+# 在项目根目录执行: ./start-api.sh 或 PORT=3001 ./start-api.sh
+# 若修改了默认端口，前端 api.config.json 的 apiBase 需填完整地址（含端口），如 http://域名或IP:5599
+
+set -e
+cd "$(dirname "$0")/server"
+PORT="${PORT:-5599}"
+export PORT
+
+echo "[720yun-offline-api] 安装依赖..."
+npm install --no-audit --no-fund
+
+echo "[720yun-offline-api] 启动 API http://0.0.0.0:${PORT}"
+echo "[720yun-offline-api] 前端请将 api.config.json 的 apiBase 设为: http://本机IP或域名:${PORT}"
+exec node index.js

start-front.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# 构建前端并启动静态服务预览（前后端分离时前端预览）
+# 在项目根目录执行: ./start-front.sh 或 FRONT_PORT=8080 ./start-front.sh
+# 需在 api.config.json 中配置 apiBase 指向后端地址
+
+set -e
+cd "$(dirname "$0")"
+FRONT_PORT="${FRONT_PORT:-8990}"
+
+echo "[720yun-offline] 构建前端到 dist/..."
+npm run build
+
+echo "[720yun-offline] 启动静态预览 http://0.0.0.0:${FRONT_PORT}（仅前端，API 需单独启动并配置 api.config.json）"
+exec npx --yes serve dist -l "${FRONT_PORT}"

start.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# 联合启动：静态 + API，单端口（默认 3000）
+# 在项目根目录执行: ./start.sh 或 PORT=8080 ./start.sh
+
+set -e
+cd "$(dirname "$0")"
+PORT="${PORT:-3000}"
+export PORT
+
+echo "[720yun-offline] 安装依赖..."
+npm install --no-audit --no-fund
+
+echo "[720yun-offline] 启动（静态+API） http://0.0.0.0:${PORT}"
+exec node server.js