fnvtk/soul-yongping
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0f6fb134ddc850824e686bb6bf63f75558fc7dc9
soul-yongping/本机运行文档.md

232 lines
7.3 KiB
Markdown
Raw Normal View History

初始提交：一场soul的创业实验-永平 网站与小程序 Made-with: Cursor
2026-03-07 22:58:43 +08:00
# Soul 永平版 · 本机运行文档
> 基于 KR 宝塔 (43.139.27.93) 实际运行配置整理，目录与线上一致。
---
## 一、服务器实际运行架构
### 1.1 进程与端口
| 进程 | 路径 | 端口 | 域名 |
|------|------|------|------|
| soul-api（正式） | `/www/wwwroot/自营/soul-api/soul-api` | 8080 | soulapi.quwanzhi.com |
| soul-dev（开发） | `/www/wwwroot/自营/soul-dev/soul-api` | 8081 | souldev.quwanzhi.com |
| soul-admin | 静态 | - | souladmin.quwanzhi.com |
| soul 主站（Next.js） | `/www/wwwroot/soul` (PM2) | 3006 | soul.quwanzhi.com |
| soul-book-api | `/www/wwwroot/self/soul-book-api` (systemd) | 3007 | 内部中间件 |
### 1.2 目录对应关系
| 服务器路径 | 本地路径 | 说明 |
|------------|----------|------|
| 自营/soul-api | soul-api/ | Go API 二进制 + .env + certs |
| 自营/soul-dev | soul-dev/ | Go 开发 API（端口 8081） |
| 自营/soul-admin | soul-admin/ | Vue 管理后台 dist |
| 自营/soul | soul/ | Next.js 主站（含 dist/.next/standalone） |
---
## 二、本机运行步骤
### 2.1 启动 Go API（soul-api）
```bash
cd soul-api
./soul-api
```
- **注意**：`soul-api` 为 Linux x86-64 可执行文件，**Mac 无法直接运行**。可选：
- 使用线上 API：`https://soulapi.quwanzhi.com`（管理后台默认）
- 在 Linux 服务器或 Docker 中运行 soul-api
- 若有 Go 源码，可在本机 `go build` 后运行
- 默认端口：8080（由 `.env` 中 `PORT=8080` 控制）
- 依赖：`.env`、`certs/apiclient_cert.pem`、`certs/apiclient_key.pem`
- 数据库：腾讯云 MySQL `soul_miniprogram`（.env 已配置）
- 健康检查：`curl http://localhost:8080/health`
### 2.2 启动管理后台（soul-admin）
```bash
npx serve soul-admin/dist -p 5174
```
- 访问：http://localhost:5174
- API 地址：默认请求 `https://soulapi.quwanzhi.com`；开发模式会切到 `https://souldev.quwanzhi.com`
- **本机联调**：在 `/etc/hosts` 添加 `127.0.0.1 soulapi.quwanzhi.com`，则管理后台会请求本机 8080
### 2.3 启动主站（soul 主站）
```bash
cd soul/dist
PORT=3006 node server.js
```
- 访问：http://localhost:3006
- 依赖：`soul/dist/.env` 中的 `DATABASE_URL`（已配置腾讯云 MySQL）
- 如缺少依赖：`cd soul/dist && pnpm install`（可选）
### 2.4 一键启动（三服务）
```bash
# 终端 1：Go API
cd soul-api && ./soul-api
# 终端 2：管理后台
npx serve soul-admin/dist -p 5174
# 终端 3：主站
cd soul/dist && PORT=3006 node server.js
```
访问：
- 主站：http://localhost:3006
- 管理后台：http://localhost:5174
- API：http://localhost:8080
---
## 三、关键配置文件
### 3.1 soul-api/.env
| 配置项 | 说明 | 本机 |
|--------|------|------|
| PORT | 服务端口 | 8080 |
| DB_DSN | 数据库连接串 | 已配置腾讯云 |
| WECHAT_* | 微信支付/转账 | 已配置，本机一般不影响浏览 |
| WECHAT_CERT_PATH / WECHAT_KEY_PATH | 证书路径 | certs/ 下 |
| CORS_ORIGINS | 允许的跨域源 | 含 localhost、soul.quwanzhi.com |
sync: 多文件 | 原因: 本地开发更新
2026-03-08 17:43:53 +08:00
### 3.2 soul-admin 的 API 地址（本地 vs 部署）
初始提交：一场soul的创业实验-永平 网站与小程序 Made-with: Cursor
2026-03-07 22:58:43 +08:00
sync: 多文件 | 原因: 本地开发更新
2026-03-08 17:43:53 +08:00
| 环境 | 配置文件 | API 地址 |
|------|----------|----------|
| 本地开发 `pnpm dev` | `.env.development` | `http://localhost:8080` |
| 部署构建 `pnpm build` | `.env.production` | `https://soulapi.quwanzhi.com` |
**流程**：本地改代码用 `pnpm dev`，会自动请求本机 soul-api；部署时执行 `pnpm build`，产物自动用线上 API，无需改配置。
初始提交：一场soul的创业实验-永平 网站与小程序 Made-with: Cursor
2026-03-07 22:58:43 +08:00
---
## 四、常见问题
1. **Mac 无法运行 soul-api**
soul-api 为 Linux 二进制，Mac 上需用线上 API 或 Docker/Linux 环境。管理后台默认请求 soulapi.quwanzhi.com，网络可达即可用。
2. **Linux 下 soul-api 权限不足**
`chmod +x soul-api/soul-api`
3. **soul-admin 请求 API 跨域**
soul-api 已配置 CORS，包含 `http://localhost:5174`；本机通过 hosts 指向 8080 时一般无跨域问题。
4. **主站 3006 端口被占用**
修改启动命令：`PORT=3007 node server.js`
5. **soul-api 连接数据库失败**
检查 `.env` 中 DB_DSN 及本机网络是否能访问腾讯云 MySQL。
---
## 五、线上 Nginx 参考
- soulapi.quwanzhi.com → `proxy_pass http://127.0.0.1:8080`
- souldev.quwanzhi.com → `proxy_pass http://127.0.0.1:8081`
- souladmin.quwanzhi.com → `root .../soul-admin/dist`（静态）
- soul.quwanzhi.com → Kr宝塔本机:
- `/api/book/latest-chapters`、`/api/book/all-chapters` → 3007（soul-book-api）
- `/api/vip/`、`/api/withdraw/`、`/api/match/`、`/api/user/`、`/api/admin/` 等 → 3006（Next.js）
- `/api/miniprogram/login`、`/api/miniprogram/pay`、`/api/referral/` 等 → 8080（Go API）
- `/admin` → 3006（Next.js 管理后台）
- `/_next/` → 3006（Next.js 静态资源）
- `/` → soul-admin/dist（SPA 前端）
### Nginx 路由优先级
1. 精确匹配 `= /api/book/latest-chapters` → 3007
2. 前缀匹配 `/api/vip/`、`/api/withdraw/` 等 → 3006
3. 默认 `/api/` → 8080（Go API）
4. `/admin` → 3006
5. `/_next/` → 3006
6. `/` → 静态文件
---
## 六、HTTP 502 问题排查与预防（管理后台登录）
### 6.1 问题原因
souladmin.quwanzhi.com 登录时出现 **HTTP 502**，通常由以下其一导致：
1. **Nginx 未运行** → 整站不可用
2. **soul-dev (8081) 未运行** → souladmin 的 `/api/` 代理失败
3. **api-proxy 错误配置** → 代理到外网 `https://souldev.quwanzhi.com` 易超时/502
### 6.2 修复步骤（Kr宝塔 43.139.27.93:22022）
```bash
# 1. 检查 Nginx
systemctl status nginx
systemctl start nginx # 若未运行
# 2. 检查 8081
ss -tlnp | grep 8081
# 无则启动: cd /www/wwwroot/自营/soul-dev && ./soul-api &
# 3. 确认 api-proxy 直连本机（避免外网绕行）
# 文件: /www/server/panel/vhost/nginx/extension/souladmin.quwanzhi.com/api-proxy.conf
# proxy_pass 应为: http://127.0.0.1:8081
```
### 6.3 预防（开机自启）
已配置 systemd 服务，重启后自动拉起：
- `soul-api.service` → 8080
- `soul-dev.service` → 8081
- `nginx.service` → 默认 enabled
若需改为 systemd 管理：
```bash
systemctl enable soul-api soul-dev
systemctl restart soul-api soul-dev
```
### 6.4 souladmin 登录「Failed to fetch」
与 502 同源：前端无法连到 `/api/admin` 后端。处理方式同上（确保 Nginx、soul-dev 运行，api-proxy 指向 `http://127.0.0.1:8081`）。若本机 IP 被 fail2ban 封禁，解封后再试（见第七章）。
---
## 七、SSH 封禁与免密配置（避免 sshpass 触发限制）
### 7.1 现象
使用 `sshpass` 频繁 SSH 登录后，出现 `Connection closed by ... port 22022`，多为 fail2ban 封禁。
### 7.2 解封（需通过宝塔终端或 VNC）
**无法 SSH 时**：登录 宝塔面板 → 终端，在服务器上执行：
```bash
# 解封所有 fail2ban 封禁
fail2ban-client unban --all 2>/dev/null
# 放宽 SSH 限制（可选）
sed -i 's/maxretry = .*/maxretry = 15/' /etc/fail2ban/jail.local 2>/dev/null || true
systemctl restart fail2ban 2>/dev/null
```
完整脚本见：`scripts/服务器解封与免密配置.sh`（需先 scp 到服务器或复制内容执行）。
### 7.3 改用 SSH 密钥（推荐）
本机执行：
```bash
bash scripts/本机配置SSH免密登录.sh
```
配置完成后，`部署永平到Kr宝塔.sh` 会优先使用密钥，不再用 sshpass，避免再次触发封禁。
Reference in New Issue Copy Permalink