soul-yongping/本机运行文档.md

# 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
cd soul-admin && pnpm dev
```

- 访问：http://localhost:5174（端口占用时自动切到 5175）
- API 地址：本地开发自动请求 `http://localhost:8080`（见 `.env.development`）

### 2.2.1 一键本地启动（推荐）

```bash
bash scripts/本地启动.sh
```

- 自动编译并启动 soul-api（Mac 版），再启动 soul-admin
- 访问 http://localhost:5174，账号 `admin` / `admin123`

### 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 |

### 3.2 soul-admin 的 API 地址（本地 vs 部署）

| 环境 | 配置文件 | API 地址 |
|------|----------|----------|
| 本地开发 `pnpm dev` | `.env.development` | `http://localhost:8080` |
| 部署构建 `pnpm build` | `.env.production` | `https://soulapi.quwanzhi.com` |

**流程**：本地改代码用 `pnpm dev`，会自动请求本机 soul-api；部署时执行 `pnpm build`，产物自动用线上 API，无需改配置。

---

## 四、常见问题

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，避免再次触发封禁。