soul/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`（本文件） | 部署步骤、环境变量、支付回调 |
| Docker | `Dockerfile` | Next.js 独立构建（`output: 'standalone'`） |
| Docker 编排 | `docker-compose.yml` | 整站容器、端口 3000、支付/基础环境变量 |
| Next 配置 | `next.config.mjs` | `output: 'standalone'` 供 Docker 使用 |
| 宝塔一键部署 | `scripts/deploy-to-server.sh` | SSH 到宝塔服务器，拉代码、安装依赖、构建、PM2 重启 |
| 宝塔自动化 | `开发文档/8、部署/Next.js自动化部署流程.md` | GitHub Webhook + 宝塔，推送即自动部署 |
| NAS 部署 | `deploy_to_nas.sh`、`redeploy.sh`、`quick_deploy.sh` | 部署到 NAS / 内网环境 |
| **宝塔部署（跨平台）** | **`scripts/deploy_baota.py`** | **Python 脚本，Windows/Mac/Linux 通用，不依赖 .sh 或 sshpass** |

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

---

## 宝塔部署（Python 跨平台）

本项目在 Mac 上开发，原有一键部署脚本为 `scripts/deploy-to-server.sh`（依赖 sshpass，仅 Linux/Mac）。为在 **Windows / Mac / Linux** 上都能部署到宝塔，提供了 **Python 脚本**，不依赖 shell 或 sshpass。

### 1. 安装依赖

\`\`\`bash
pip install paramiko
\`\`\`

### 2. 配置服务器信息

复制示例配置并填写真实信息（**不要提交到 Git**）：

\`\`\`bash
cp scripts/deploy_config.example.json deploy_config.json
# 编辑 deploy_config.json，填写 server_host、server_user、project_path、branch、pm2_app_name 等
\`\`\`

或使用环境变量（不写配置文件时，脚本会提示输入密码）：

- `DEPLOY_HOST`：服务器 IP
- `DEPLOY_USER`：SSH 用户名（如 root）
- `DEPLOY_PROJECT_PATH`：服务器上项目路径（如 /www/wwwroot/soul）
- `DEPLOY_BRANCH`：要部署的分支（如 soul-content）
- `DEPLOY_PM2_APP`：PM2 应用名（如 soul）
- `DEPLOY_SSH_KEY`：SSH 私钥路径（可选，不填则用密码）

### 3. 执行部署

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

\`\`\`bash
python scripts/deploy_baota.py
# 或指定配置
python scripts/deploy_baota.py --config scripts/deploy_config.json
# 仅查看将要执行的步骤（不连接）
python scripts/deploy_baota.py --dry-run
\`\`\`

脚本会依次执行：SSH 连接 → 拉取代码 → 安装依赖 → 构建 → PM2 重启。部署完成后访问：

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

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

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

1. 在网站目录（如 `/www/wwwroot/soul`）执行 `git clone <你的仓库> .`，或从本地上传代码。
2. 在宝塔「PM2 管理器」中新增项目：项目目录选该路径，启动文件为 `node_modules/next/dist/bin/next` 或 `node server.js`（若使用 standalone 输出），启动参数为 `start -p 3006`（与 `package.json` 里 `start` 端口一致）。
3. 配置 Nginx 反向代理到该端口，并绑定域名。
4. 之后即可用 `python scripts/deploy_baota.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/deploy_baota.py`，构建会在**服务器（Linux）**上执行，不会遇到该问题。

## 注意事项

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