soul-yongping/DEPLOYMENT.md

# 部署指南

## 整站与后台管理端

本项目是**一个 Next.js 应用**，前台 H5、后台管理、API 都在同一套代码里：

- **前台**：`/`、`/chapters`、`/read/*`、`/my`、`/match` 等
- **后台管理端**：`/admin`、`/admin/login`、`/admin/settings`、`/admin/users` 等
- **API**：`/api/*`（含 `/api/admin/*`）

**部署一次 = 前台 + 后台 + API 一起上线。** 后台无需单独部署，上线后访问：

- 后台首页：`https://你的域名/admin`
- 后台登录：`https://你的域名/admin/login`（账号见项目文档，如 `admin` / `key123456`）

---

## 项目内已有的部署配置

| 类型 | 文件/目录 | 说明 |
|------|------------|------|
| 总览文档 | `DEPLOYMENT.md`（本文件） | 部署步骤、环境变量、支付回调 |
| Next 配置 | `next.config.mjs` | `output: 'standalone'` 供宝塔 standalone 部署使用 |
| **宝塔部署（统一入口）** | **`scripts/devlop.py`** | **本地打包 → SSH 上传解压 → 宝塔 API 重启 Node 项目（Windows/Mac/Linux 通用）** |
| 宝塔 API 模块 | `scripts/deploy_baota_pure_api.py` | 被 devlop.py 内部调用（重启 Node）；也可单独用于仅重启或触发计划任务 |
| 宝塔方案说明 | `开发文档/8、部署/Next.js宝塔部署方案.md` | 宝塔首次准备与日常部署步骤 |
| 宝塔自动化 | `开发文档/8、部署/Next.js自动化部署流程.md` | GitHub Webhook + 宝塔，推送即自动部署 |

无 `vercel.json` 时，Vercel 会按默认规则部署本仓库；若需自定义路由或头信息，可再加 `vercel.json`。

---

## 宝塔部署（统一使用 devlop.py）

**日常部署**统一使用 **`scripts/devlop.py`**：本地打包 → SSH 上传解压 → 宝塔 API 重启，Windows / Mac / Linux 通用，不依赖 sshpass 或 shell。

### 1. 安装依赖

\`\`\`bash
pip install -r requirements-deploy.txt
\`\`\`

### 2. 配置（可选）

脚本默认使用 `.cursorrules` 中的服务器信息（43.139.27.93、root、项目路径 /www/wwwroot/soul 等）。如需覆盖，可设置环境变量：

- `DEPLOY_HOST`、`DEPLOY_USER`、`DEPLOY_PASSWORD` 或 `DEPLOY_SSH_KEY`
- `DEPLOY_PROJECT_PATH`（如 /www/wwwroot/soul）
- `BAOTA_PANEL_URL`、`BAOTA_API_KEY`
- `DEPLOY_PM2_APP`（默认 soul）

### 3. 执行部署

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

\`\`\`bash
python scripts/devlop.py
\`\`\`

- **流程**：本地 `pnpm build` → 打包 `.next/standalone`（含 static、public、ecosystem.config.cjs）→ SSH 上传并解压到服务器 → **宝塔 API 重启 Node 项目**。
- **参数**：`--no-build` 跳过构建；`--no-upload` 仅构建+打包；`--no-api` 上传后不调 API 重启。

部署完成后访问：

- 前台：`https://soul.quwanzhi.com`
- 后台：`https://soul.quwanzhi.com/admin`

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

若只需在宝塔上重启 Node 项目（代码已通过其他方式更新），可单独使用宝塔 API 模块：

\`\`\`bash
pip install requests
python scripts/deploy_baota_pure_api.py              # 重启 Node 项目 soul
python scripts/deploy_baota_pure_api.py --create-dir # 并创建项目目录
python scripts/deploy_baota_pure_api.py --task-id 1  # 触发计划任务 ID=1
\`\`\`

### 5. 首次在宝塔上准备

若服务器上尚未有代码，需先在宝塔上：

1. 在网站目录（如 `/www/wwwroot/soul`）创建目录，或从本地上传/克隆代码。
2. 在宝塔「PM2 管理器」中新增项目：项目目录选该路径，启动文件为 `node server.js`，环境变量 `PORT=30006`。
3. 配置 Nginx 反向代理到 `127.0.0.1:30006`，并绑定域名 soul.quwanzhi.com。
4. 之后日常部署执行 `python scripts/devlop.py` 即可。

---

## 生产环境部署步骤

### 1. Vercel部署

\`\`\`bash
# 安装Vercel CLI
npm install -g vercel

# 登录Vercel
vercel login

# 部署项目
vercel --prod
\`\`\`

### 2. 环境变量配置

在Vercel项目设置中添加以下环境变量：

**支付宝配置：**
- `ALIPAY_PARTNER_ID`: 2088511801157159
- `ALIPAY_KEY`: lz6ey1h3kl9zqkgtjz3avb5gk37wzbrp
- `ALIPAY_APP_ID`: wx432c93e275548671
- `ALIPAY_RETURN_URL`: https://your-domain.com/payment/success
- `ALIPAY_NOTIFY_URL`: https://your-domain.com/api/payment/alipay/notify

**微信支付配置：**
- `WECHAT_APP_ID`: wx432c93e275548671
- `WECHAT_APP_SECRET`: 25b7e7fdb7998e5107e242ebb6ddabd0
- `WECHAT_MCH_ID`: 1318592501
- `WECHAT_API_KEY`: wx3e31b068be59ddc131b068be59ddc2
- `WECHAT_NOTIFY_URL`: https://your-domain.com/api/payment/wechat/notify

**基础配置：**
- `NEXT_PUBLIC_BASE_URL`: https://your-domain.com

### 3. 域名配置

1. 在Vercel项目设置中绑定自定义域名
2. 配置DNS记录指向Vercel
3. 启用HTTPS（Vercel自动配置SSL证书）

### 4. 支付回调配置

**支付宝配置：**
1. 登录支付宝开放平台
2. 在应用详情中配置异步通知地址：`https://your-domain.com/api/payment/alipay/notify`
3. 配置同步返回地址：`https://your-domain.com/payment/success`

**微信支付配置：**
1. 登录微信商户平台
2. 在产品中心配置支付回调URL：`https://your-domain.com/api/payment/wechat/notify`
3. 添加支付授权域名：`your-domain.com`

**提现（商家转账到零钱）：** 详见 `开发文档/提现功能完整技术文档.md`。需配置：
- `WECHAT_MCH_ID`：商户号
- `WECHAT_APP_ID`：小程序/公众号 AppID（如 `wxb8bbb2b10dec74aa`）
- `WECHAT_API_V3_KEY` 或 `WECHAT_MCH_KEY`：APIv3 密钥（32 字节，用于回调解密）
- `WECHAT_KEY_PATH` 或 `WECHAT_MCH_PRIVATE_KEY_PATH`：商户私钥文件路径（apiclient_key.pem）
- `WECHAT_MCH_CERT_SERIAL_NO`：商户证书序列号（OpenSSL 从 apiclient_cert.pem 提取）
- 商户平台需配置：商家转账到零钱、转账结果通知 URL：`https://你的域名/api/payment/wechat/transfer/notify`

### 5. 测试流程

1. 创建测试订单
2. 使用沙箱环境测试支付宝支付
3. 使用微信开发者工具测试微信支付
4. 验证回调接口正常接收
5. 确认订单状态更新正确
6. 验证内容解锁功能

### 6. 监控和日志

- 在Vercel Dashboard查看部署日志
- 使用Vercel Analytics监控访问数据
- 配置错误告警通知

## 本地开发

\`\`\`bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 访问 http://localhost:3000
\`\`\`

### Windows 本地执行 `pnpm build` 报 EPERM symlink

本项目使用 `output: 'standalone'`，构建时 Next.js 会创建符号链接。**Windows 默认不允许普通用户创建符号链接**，会报错：

- `EPERM: operation not permitted, symlink ... -> .next\standalone\node_modules\...`

**可选做法（任选其一）：**

1. **开启 Windows 开发者模式（推荐，一劳永逸）**  
   - 设置 → 隐私和安全性 → 针对开发人员 → **开发人员模式** 打开  
   - 开启后无需管理员即可创建符号链接，本地 `pnpm build` 可正常完成。

2. **以管理员身份运行终端再执行构建**  
   - 右键 Cursor/终端 → “以管理员身份运行”，在项目根目录执行 `pnpm build`。

若只做部署、不在本机打 standalone 包，可用 `python scripts/devlop.py --no-build` 跳过构建后上传已有包，或由服务器/计划任务在服务器上执行构建。

## 注意事项

1. 生产环境必须使用HTTPS
2. 定期更新支付密钥
3. 保护环境变量安全
4. 备份用户数据
5. 监控支付异常