fnvtk/soul-yongping
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b9b100689b03119d82a18d598ab9489681b48ee3
soul-yongping/本机运行文档.md
卡若 b7c35a89b0 初始提交：一场soul的创业实验-永平 网站与小程序 
Made-with: Cursor
2026-03-07 22:58:43 +08:00

7.1 KiB
Raw Blame History

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）

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）

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 主站）

cd soul/dist
PORT=3006 node server.js
  • 访问：http://localhost:3006
  • 依赖：soul/dist/.env 中的 DATABASE_URL（已配置腾讯云 MySQL）
  • 如缺少依赖：cd soul/dist && pnpm install（可选）

2.4 一键启动（三服务）

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

访问：

三、关键配置文件

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 地址

  • 正式：https://soulapi.quwanzhi.com
  • 开发：https://souldev.quwanzhi.com（打包时已写死）
  • 本机联调：/etc/hosts 加 127.0.0.1 soulapi.quwanzhi.com，管理后台会访问本机 8080

四、常见问题

  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）

# 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 管理：

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 时：登录 宝塔面板 → 终端，在服务器上执行：

# 解封所有 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 scripts/本机配置SSH免密登录.sh

配置完成后，部署永平到Kr宝塔.sh 会优先使用密钥，不再用 sshpass，避免再次触发封禁。