soul-yongping/开发文档/8、部署/宝塔配置检查说明.md

# Soul 项目宝塔配置检查说明

> 用于排查 soul.quwanzhi.com 在宝塔上的 Nginx / PM2 / 端口 配置问题。

---

## 一、已发现并修复的问题

### 1. 应用端口与 Nginx 不一致（已修复）

- **现象**：部署脚本用 `pm2 start server.js --name soul` 启动，未指定端口。Next.js standalone 默认监听 **3000**。
- **宝塔约定**：根据 `开发文档/服务器管理/references/端口配置表.md`，soul 使用端口 **30006**，Nginx 反代到 `127.0.0.1:30006`。
- **结果**：应用实际在 3000 监听，Nginx 请求 30006 → 无进程 → **502 Bad Gateway**。
- **修复**：部署脚本 `scripts/devlop.py` 通过宝塔 API 重启 Node 项目，服务器上 PM2 启动时需设置 `PORT=30006`（可与 `ecosystem.config.cjs` 或环境变量 `DEPLOY_APP_PORT` 一致），保证与 Nginx 一致。

---

## 二、宝塔侧需自检的配置

### 1. Nginx 反向代理

- **域名**：soul.quwanzhi.com
- **要求**：`proxy_pass http://127.0.0.1:30006;`（与端口配置表一致）
- **检查**：宝塔 → 网站 → soul.quwanzhi.com → 设置 → 反向代理 / 配置文件，确认 `proxy_pass` 指向 `127.0.0.1:30006`。
- **SSL**：若走 HTTPS，确认已配置 443 与证书（端口配置表注明使用通配符证书）。

### 2. PM2 与部署脚本一致

- **项目名**：soul（与 `scripts/devlop.py` 中 `DEPLOY_PM2_APP` 一致）
- **启动方式**：**必须用 `node server.js`**，工作目录 `/www/wwwroot/soul`，环境变量 `PORT=30006`。
- **不要用**：`npm start` / `next start`。standalone 部署后没有完整 node_modules，也没有 `next` 命令，会报 `next: command not found`。
- **宝塔 PM2 管理器**：启动文件填 `server.js`，启动命令填 `node server.js`（或选「Node 项目」后只填 `server.js`），环境变量添加 `PORT=30006`。也可用 `pm2 start ecosystem.config.cjs`（项目根目录已提供该文件）。
- **注意**：若同时在宝塔「PM2 管理器」里添加了同名项目，可能产生 root 与 www 用户冲突，建议只保留一种方式（要么只用脚本部署 + 命令行 PM2，要么只用宝塔 PM2 界面）。

### 3. 项目目录与端口

- **项目路径**：`/www/wwwroot/soul`（与 `DEPLOY_PROJECT_PATH` 一致）
- **应用端口**：30006（与端口配置表、Nginx、部署脚本中的 `PORT` 一致）

---

## 三、快速检查命令（SSH 到服务器后执行）

```bash
# 1. 应用是否在 30006 监听
ss -tlnp | grep 30006

# 2. PM2 列表（是否有 soul，状态 online）
pm2 list

# 3. Nginx 配置是否包含 soul 且 proxy_pass 为 30006
grep -r "soul\|30006" /www/server/panel/vhost/nginx/

# 4. Nginx 语法
nginx -t
```

---

## 四、环境变量（可选）

部署时若需改端口，可在本机执行脚本前设置：

```bash
set DEPLOY_APP_PORT=30006
python scripts/devlop.py
```

或修改 `scripts/devlop.py` 中 `get_cfg()` 的 `app_port` 默认值（当前为 30006）。

---

## 五、参考文档

- 端口与域名：`开发文档/服务器管理/references/端口配置表.md`
- 常见问题：`开发文档/服务器管理/references/常见问题手册.md`
- 部署步骤：`DEPLOYMENT.md`（宝塔部署章节）