204 lines
7.4 KiB
Markdown
204 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/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. 监控支付异常
|