soul-yongping/开发文档/8、部署/Next.js宝塔部署方案.md

# Next.js 宝塔面板部署方案

> 适用于本项目的 Next.js（`output: 'standalone'`）在宝塔面板上的部署。统一入口：`scripts/devlop.py`。

---

## 一、方案概览

| 方式 | 命令 | 说明 |
|------|------|------|
| **推荐：deploy（直接覆盖）** | `python scripts/devlop.py --mode deploy` | 本地 build → 打 tar.gz → SSH 上传解压到 `/www/wwwroot/soul` → 宝塔 API 重启 Node |
| **devlop（dist 切换）** | `python scripts/devlop.py` 或 `--mode devlop` | 本地 build → 打 zip → 上传到 dist2 → 服务器 pnpm install → dist↔dist2 切换 → 重启，运行目录为 `.../soul/dist` |

- **日常建议**：用 **deploy** 即可，简单、不依赖服务器上的 pnpm。
- **devlop** 适合需要在服务器上再装依赖或做 dist 双目录无损切换的场景。

---

## 二、宝塔首次准备（做一次即可）

### 1. 安装/确认环境

- **Node.js**：宝塔 → 软件商店 → 安装「Node 版本管理器」或「PM2 管理器」，并安装 Node（建议 v18+，本项目默认 v22.14.0）。
- **Nginx**：已安装并可添加站点。
- **Git**（可选）：若用 Webhook 拉代码再构建，需要 Git。

### 2. 创建网站目录

- 在宝塔「网站」里添加站点，或先建好目录。  
- 本项目默认路径：`/www/wwwroot/soul`（deploy 模式会把包解压到这里）。

### 3. 配置 Nginx 反向代理

- 域名示例：`soul.quwanzhi.com`。
- 在对应站点的「设置」→「反向代理」中新增：
  - **代理名称**：随意（如 soul）
  - **目标 URL**：`http://127.0.0.1:30006`
- 应用端口 **30006** 需与下面 PM2 的 `PORT` 一致。

### 4. 添加 Node（PM2）项目

- 宝塔 → **Node 项目**（或 PM2 管理器）→ 添加项目：
  - **项目名称**：`soul`（与脚本里 `DEPLOY_PM2_APP` 一致）
  - **项目路径**：
    - deploy 模式：`/www/wwwroot/soul`
    - devlop 模式：`/www/wwwroot/soul/dist`
  - **启动文件**：`server.js`
  - **启动方式**：`node server.js`（不要用 `npm start` / `next start`，standalone 无 next 命令）
  - **环境变量**：`PORT=30006`（与 Nginx 反代一致）

也可在服务器上用 PM2 直接启动（与上面二选一）：

```bash
cd /www/wwwroot/soul
PORT=30006 pm2 start server.js --name soul
# 或
PORT=30006 pm2 start ecosystem.config.cjs
```

### 5. 配置宝塔 API（供脚本重启 Node）

- 宝塔面板 → 设置 → API 接口：开启并保存 **API 密钥**。
- 记下面板地址（如 `https://你的服务器IP:9988`）。
- 脚本通过环境变量使用：`BAOTA_PANEL_URL`、`BAOTA_API_KEY`。

---

## 三、日常部署

### 1. 本机依赖

```bash
pip install paramiko requests
# 或
pip install -r requirements-deploy.txt
```

### 2. 执行部署（推荐 deploy）

在**项目根目录**执行：

```bash
# 完整流程：构建 + 上传 + 重启
python scripts/devlop.py --mode deploy
```

可选参数：

- `--no-build`：跳过本地 `pnpm build`（已有 .next/standalone 时用）。
- `--no-upload`：只打 tar.gz，不上传（用于调试或手动上传）。
- `--no-api`：上传后不调宝塔 API，不自动重启。

### 3. devlop 模式（dist 切换）

```bash
python scripts/devlop.py
# 或
python scripts/devlop.py --mode devlop
```

流程：本地 build → zip 上传到服务器 `dist2` → 在 dist2 执行 `pnpm install` → dist 与 dist2 互换 → 宝塔 API 重启，运行目录为 `.../soul/dist`。

### 4. 仅重启 Node（不传代码）

代码已通过其他方式更新时，只重启 PM2：

```bash
python scripts/deploy_baota_pure_api.py
```

---

## 四、环境变量（可选覆盖默认）

| 变量 | 说明 | 默认示例 |
|------|------|----------|
| `DEPLOY_HOST` | 服务器 IP | 43.139.27.93 |
| `DEPLOY_USER` | SSH 用户 | root |
| `DEPLOY_PASSWORD` | SSH 密码 | - |
| `DEPLOY_SSH_KEY` | SSH 私钥路径 | - |
| `DEPLOY_SSH_PORT` | SSH 端口 | 22022 |
| `DEPLOY_PROJECT_PATH` | 项目路径（deploy） | /www/wwwroot/soul |
| `DEPLOY_PORT` / `DEPLOY_APP_PORT` | 应用端口 | 30006 |
| `DEPLOY_PM2_APP` | PM2 项目名 | soul |
| `BAOTA_PANEL_URL` | 宝塔面板地址 | https://IP:9988 |
| `BAOTA_API_KEY` | 宝塔 API 密钥 | - |
| `DEPLOY_NODE_PATH` | 服务器 Node 路径 | /www/server/nodejs/v22.14.0/bin |

---

## 五、与现有文档的关系

- **DEPLOYMENT.md**：总览与 Vercel/环境变量等。
- **宝塔配置检查说明.md**：Nginx/PM2/端口 排查。
- **Next.js自动化部署流程.md**：GitHub Webhook + 宝塔自动部署（可选）。

---

## 六、注意事项

1. **端口一致**：Nginx `proxy_pass`、PM2 的 `PORT`、脚本中的 `DEPLOY_PORT` 必须一致（默认 30006）。
2. **standalone 必须**：`next.config.mjs` 已设置 `output: 'standalone'`，部署用 `node server.js`，不要用 `next start`。
3. **PM2 项目路径**：deploy 用 `/www/wwwroot/soul`；devlop 用 `/www/wwwroot/soul/dist`，否则易 404。
4. **首次部署**：若服务器上还没有代码，先执行一次 `python scripts/devlop.py --mode deploy`，再在宝塔里确认 Node 项目路径与启动方式。

按以上步骤即可在宝塔上稳定跑 Next.js 前台、后台和 API。