205 lines
7.4 KiB
Markdown
205 lines
7.4 KiB
Markdown
# 部署指南
|
||
|
||
## 整站与后台管理端
|
||
|
||
本项目是**一个 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/devlop.py`** | **本地打包 → SSH 上传解压 → 宝塔 API 重启 Node 项目（Windows/Mac/Linux 通用）** |
|
||
| 宝塔 API 模块 | `scripts/deploy_baota_pure_api.py` | 被 devlop.py 内部调用（重启 Node）；也可单独用于仅重启或触发计划任务 |
|
||
| 宝塔自动化 | `开发文档/8、部署/Next.js自动化部署流程.md` | GitHub Webhook + 宝塔，推送即自动部署 |
|
||
| NAS 部署 | `deploy_to_nas.sh`、`redeploy.sh`、`quick_deploy.sh` | 部署到 NAS / 内网环境 |
|
||
|
||
无 `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` 中的服务器信息（42.194.232.22、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. 监控支付异常
|