# 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://你的前端域名`。