147 lines
5.1 KiB
Markdown
147 lines
5.1 KiB
Markdown
# 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。
|