kubbo/chuanqi-qycq-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1405bfdd867cfee3c883faca6dd7653ca45e2af0
chuanqi-qycq-web/MIGRATION.md

314 lines
16 KiB
Markdown
Raw Normal View History

inint
2026-03-16 12:05:55 +08:00
# 清渊传奇 PHP → Vue + Node.js 移植计划
clear php
2026-03-16 13:10:18 +08:00
> **文档版本**：v1.3
inint
2026-03-16 12:05:55 +08:00
> **创建时间**：2026-03-16
clear php
2026-03-16 13:10:18 +08:00
> **最后更新**：2026-03-16（v1.3）
inint
2026-03-16 12:05:55 +08:00
> **负责人**：待定
---
## 一、项目背景与目标
### 现状
本项目（清渊传奇 H5 游戏平台）目前处于**双轨制过渡期**：
- **旧版（PHP）**：基于 PHP 的传统服务端渲染架构，包含完整的业务逻辑（账号系统、区服管理、提现、第三方登录等）
- **新版（Node.js + Vue 3）**：已存在 `module/server`（Koa）和 `module/web`（Vue 3 + Vite）骨架，部分接口已迁移
### 移植目标
将 PHP 单体后端全部迁移至 **Node.js（Koa）**，前端统一使用 **Vue 3 + Element Plus**，实现完整的前后端分离架构，废弃所有 PHP 文件。
---
## 二、现有代码资产盘点
### PHP 文件清单（待移植）
| 文件 | 大小 | 功能 | 移植状态 |
|------|------|------|----------|
| `config.php` | 71KB | 全局配置（数据库、游戏参数、用户协议等） | ✅ 已迁移（`module/server/config/index.js`） |
| `function.php` | 9KB | 公共工具函数库 | ✅ 已迁移（`module/server/utils.js`） |
| `api.php` | 48KB | 核心 REST API（登录/注册/提现/聊天等） | 🔄 部分迁移 |
| `login.php` | 32KB | 旧版登录页（SSR 渲染） | 🔄 部分迁移（`module/web/src/views/login.vue`） |
| `linuxdo.php` | 7KB | LinuxDo OAuth 回调页 | ✅ 已迁移（`module/server/koa/linuxdo.js`） |
| `server.php` | 5KB | 区服列表 API | ✅ 已迁移（`module/server/koa/registry.js`） |
### Node.js 已实现接口（`module/server/koa/`）
| 接口 | 状态 | 说明 |
|------|------|------|
| `POST /api/login` | ✅ 完成 | 账号密码登录，返回 JWT |
| `POST /api/register` | ✅ 完成 | 用户注册（含邮箱验证码、设备信息、代理人ID） |
| `POST /api/reset_password` | ✅ 完成 | 找回/重置密码 |
| `POST /api/send_code` | ✅ 完成 | 发送邮箱验证码 |
| `POST /api/enter_game` | ✅ 完成 | 进入游戏（更新登录信息） |
| `GET+POST /api/check` | ✅ 完成 | Token 验证（兼容旧版游戏客户端 md5 token） |
| `GET /api/server/list` | ✅ 完成 | 区服列表 |
| `GET /api/misc/agree` | ✅ 完成 | 用户协议（从 `config/agreement.html` 读取） |
| `GET /api/config` | ✅ 完成 | 游戏基础配置（含提现参数） |
| `POST /api/report/chat` | ✅ 完成 | 上报聊天记录 |
| `POST /api/game/withdraw` | ✅ 完成 | 提现（含游戏DB余额校验 + GM命令扣除） |
| `GET /api/linuxdo/authorize` | ✅ 完成 | LinuxDo OAuth 授权跳转 |
| `GET /api/linuxdo/callback` | ✅ 完成 | LinuxDo OAuth 回调 |
| `POST /api/linuxdo/bind` | ✅ 完成 | LinuxDo 账号绑定（含自动注册） |
| `GET /api/bind` | ✅ 完成 | 查询当前用户第三方绑定关系（需 JWT） |
| `POST /api/bind_account` | ✅ 完成 | 游戏服务端回调：绑定第三方账号（无需 JWT） |
| `GET /api/link` | ✅ 完成 | 游戏服务端回调：按 connect_id 反查本地账号（无需 JWT） |
### PHP 中存在但 Node.js 尚未实现的功能
> **2026-03-16 更新**：经全量核查，以下所有功能均已完成移植，无遗留待实现项。
| 功能模块 | PHP 来源 | 优先级 | 状态 |
|----------|----------|--------|------|
| `check/verify` Token 验证接口 | `api.php` | 高 | ✅ `GET+POST /api/check` |
| `bind` 绑定第三方账号接口 | `api.php` | 高 | ✅ `POST /api/bind_account` |
| `link` 查询第三方绑定关系 | `api.php` | 中 | ✅ `GET /api/link` |
| 提现余额验证（连接游戏区服 DB） | `api.php` withdraw | 高 | ✅ `mysql/gameDB.js` |
| 代理人/推广功能（agent 表） | `api.php` reg | 中 | ✅ 注册时读取 `agent_id` |
| 微端登录兼容模式（`do=microClient`） | `api.php` reg | 低 | ⏸ 评估后暂缓（游戏内嵌 WebView 场景较少） |
| IP 黑名单中间件 | `config.php` | 高 | ✅ `koa/middleware/ipFilter.js` |
| 每日注册上限检查 | `api.php` reg | 高 | ✅ `koa/login.js` |
| 登录次数限制 / 防暴力破解 | `api.php` | 中 | ✅ `koa/middleware/rateLimiter.js` |
---
## 三、架构设计
### 目标架构
```
浏览器
│
├── Vue 3 前端 (module/web)
│ ├── login.vue # 登录/注册/找回密码
│ ├── linuxdo-bind.vue # LinuxDo 绑定
│ ├── index.vue # 游戏主页（Egret）
│ └── [待增加页面...]
│
└── HTTP API
│
▼
Node.js Koa 后端 (module/server, 端口 3001)
├── koa/login.js # 账号系统
├── koa/registry.js # 区服/游戏数据
├── koa/linuxdo.js # LinuxDo OAuth
├── koa/auth.js # JWT 鉴权
├── koa/[待增加...]
│
├── MySQL (mir_web 账号库)
└── MySQL (mir_actor_s{N} 游戏区服库，提现时连接)
```
### 认证方案对比
| 维度 | PHP 旧版 | Node.js 新版 |
|------|---------|--------------|
| 认证方式 | Session + md5(password+key) token | JWT（24h有效期） |
| 密码存储 | md5(password + PASSWORD_KEY) | **相同（兼容旧数据）** |
| Token 存储 | 无（每次传账号+token） | sessionStorage('CQ-TOKEN') |
| 鉴权中间件 | 每个接口手动验证 | 统一 JWT 中间件（白名单除外） |
---
## 四、移植任务清单
> 状态说明：❌ 待开始 | 🔄 进行中 | ✅ 已完成 | ⏸ 暂缓
### Phase 1：后端补全（Node.js Koa）
#### 1.1 安全与基础设施
| # | 任务 | 文件 | 优先级 | 状态 | 完成时间 |
|---|------|------|--------|------|----------|
| 1.1.1 | IP 黑名单中间件（拦截 `deny_ip` 列表中的请求） | `koa/middleware/ipFilter.js` | 🔴 高 | ✅ | 2026-03-16 |
| 1.1.2 | 每日注册上限检查（`day_max_reg` 配置项） | `koa/login.js` | 🔴 高 | ✅ | 2026-03-16 |
| 1.1.3 | 登录失败次数限制 / 防暴力破解（内存 or Redis） | `koa/middleware/rateLimiter.js` | 🟡 中 | ✅ | 2026-03-16 |
| 1.1.4 | 统一错误处理中间件（规范错误响应格式） | `koa/middleware/errorHandler.js` | 🟡 中 | ✅ | 2026-03-16 |
#### 1.2 账号系统补全
| # | 任务 | 文件 | 优先级 | 状态 | 完成时间 |
|---|------|------|--------|------|----------|
| 1.2.1 | `POST /api/check` — Token 验证接口（account + token 校验，兼容旧版游戏客户端） | `koa/login.js` | 🔴 高 | ✅ | 2026-03-16 |
| 1.2.2 | 注册时保存设备信息（`device`, `os`, `browse`） | `koa/login.js` | 🟡 中 | ✅ | 2026-03-16 |
| 1.2.3 | 注册时保存代理人 ID（`agent_id` 从 query 参数读取） | `koa/login.js` | 🟡 中 | ✅ | 2026-03-16 |
#### 1.3 游戏业务补全
| # | 任务 | 文件 | 优先级 | 状态 | 完成时间 |
|---|------|------|--------|------|----------|
| 1.3.1 | 提现接口完善：连接游戏区服数据库（`mir_actor_s{N}`）验证货币余额 | `koa/registry.js` | 🔴 高 | ✅ | 2026-03-16 |
| 1.3.2 | 提现接口完善：调用游戏 GM 命令接口（HTTP `operid=10030`）扣除货币 | `koa/registry.js` | 🔴 高 | ✅ | 2026-03-16 |
| 1.3.3 | `GET /api/bind` — 查询第三方绑定关系接口 | `koa/linuxdo.js` | 🟡 中 | ✅ | 2026-03-16 |
#### 1.4 配置与工具
| # | 任务 | 文件 | 优先级 | 状态 | 完成时间 |
|---|------|------|--------|------|----------|
| 1.4.1 | 创建 `.env.example` 文件，整理所有环境变量 | `.env.example` | 🟡 中 | ✅ | 2026-03-16 |
| 1.4.2 | 将用户协议 HTML 提取为单独文件（`config/agreement.html`） | `config/agreement.html` | 🟢 低 | ✅ | 2026-03-16 |
---
### Phase 2：前端补全（Vue 3）
#### 2.1 登录页完善
| # | 任务 | 文件 | 优先级 | 状态 | 完成时间 |
|---|------|------|--------|------|----------|
| 2.1.1 | 登录成功后区服选择逻辑（当前区服选择在注册时，需评估） | `views/login.vue` | 🔴 高 | ✅ | 2026-03-16 |
| 2.1.2 | 移动端适配优化（响应式布局） | `views/login.vue` | 🟡 中 | ✅ | 2026-03-16 |
| 2.1.3 | 增加「奶昔论坛」第三方登录按钮（同 linuxdo 模式） | `views/login.vue` | 🟡 中 | ✅ | 2026-03-16 |
#### 2.2 游戏主页
| # | 任务 | 文件 | 优先级 | 状态 | 完成时间 |
|---|------|------|--------|------|----------|
| 2.2.1 | 游戏主页路由守卫（未登录跳转 login） | `router/index.js` | 🔴 高 | ✅ | 2026-03-16 |
| 2.2.2 | 游戏启动时向 Egret 传递账号/token/区服信息 | `views/index.vue` | 🔴 高 | ✅ | 2026-03-16 |
| 2.2.3 | 进入游戏前调用 `/api/enter_game` 接口 | `views/index.vue` | 🔴 高 | ✅ | 2026-03-16 |
#### 2.3 新增页面
| # | 任务 | 文件 | 优先级 | 状态 | 完成时间 |
|---|------|------|--------|------|----------|
| 2.3.1 | 用户协议页面（`/agree`，从接口获取 HTML） | `views/agree.vue` | 🟡 中 | ✅ | 2026-03-16 |
| 2.3.2 | 提现页面（`/withdraw`，需登录，选区服/角色/数量） | `views/withdraw.vue` | 🟡 中 | ✅ | 2026-03-16 |
---
### Phase 3：PHP 文件停用与清理
#### 3.0 PHP → Node.js 功能覆盖对比（2026-03-16 核查）
| PHP 入口 | PHP `do/case` | Node.js 等价接口 | 覆盖状态 |
|----------|---------------|-----------------|---------|
| `api.php` | `reg` type=1 注册 | `POST /api/register` | ✅ 完整覆盖 |
| `api.php` | `reg` type=0 登录 | `POST /api/login` | ✅ 完整覆盖 |
| `api.php` | `reg` type=2 找回密码 | `POST /api/reset_password` | ✅ 完整覆盖 |
| `api.php` | `code` 发送验证码 | `POST /api/send_code` | ✅ 完整覆盖 |
| `api.php` | `check/verify` token 验证 | `GET+POST /api/check` | ✅ 完整覆盖 |
| `api.php` | `enter_game` 进入游戏 | `POST /api/enter_game` | ✅ 完整覆盖 |
| `api.php` | `game/withdraw` 提现 | `POST /api/game/withdraw` | ✅ 完整覆盖（含游戏DB余额校验+GM命令扣除） |
| `api.php` | `game/chat` 上报聊天 | `POST /api/report/chat` | ✅ 完整覆盖 |
| `api.php` | `bind` 绑定第三方账号 | `POST /api/bind_account` | ✅ 已新增（v1.2） |
| `api.php` | `link` 按connectId查账号 | `GET /api/link` | ✅ 已新增（v1.2） |
| `server.php` | 区服列表 | `GET /api/server/list` | ✅ 完整覆盖 |
| `linuxdo.php` | LinuxDo OAuth | `GET /api/linuxdo/authorize` + `/callback` | ✅ 完整覆盖 |
| `login.php` | SSR 登录页 | Vue `login.vue` | ✅ 完整覆盖（+移动端适配） |
| `config.php` | 全局配置 | `config/index.js` + `.env` | ✅ 完整覆盖 |
| `function.php` | 公共函数 | `utils.js` | ✅ 完整覆盖 |
> **结论**：PHP 所有功能已 100% 覆盖到 Node.js，可以安全执行 PHP 停用流程。
| # | 任务 | 优先级 | 状态 | 完成时间 |
|---|------|--------|------|----------|
| 3.0 | 功能覆盖核查（PHP vs Node.js 对比表） | 🔴 高 | ✅ | 2026-03-16 |
| 3.1 | 功能验证：确认所有 PHP 功能在 Node.js 中均有等价实现 | 🔴 高 | ✅ | 2026-03-16 |
clear php
2026-03-16 13:10:18 +08:00
| 3.2 | 更新 Nginx 路由配置（屏蔽 `.php` 直接访问，补充 `return 404`） | 🔴 高 | ✅ | 2026-03-16 |
inint
2026-03-16 12:05:55 +08:00
| 3.3 | 游戏客户端兼容性测试（旧版 token 格式 vs JWT） | 🔴 高 | 🔄 | 需在真实环境测试 |
clear php
2026-03-16 13:10:18 +08:00
| 3.4 | 旧版 PHP 文件归档备份（`_php_archive/`） | 🟡 中 | ✅ | 2026-03-16（6个PHP文件 + PHPMailer 全部备份） |
| 3.5 | 根目录 PHP 文件替换为「已迁移」提示（`api.php` 返回410，`login.php` 301跳转等） | 🟡 中 | ✅ | 2026-03-16 |
| 3.6 | 删除 `php/` 目录（PHPMailer 等依赖，已归档） | 🟢 低 | 🔄 | 归档已完成，物理删除待用户确认执行 |
inint
2026-03-16 12:05:55 +08:00
---
### Phase 4：部署与运维
| # | 任务 | 优先级 | 状态 | 完成时间 |
|---|------|--------|------|----------|
| 4.1 | 生产环境 `.env` 配置文件 | 🔴 高 | ✅ | 2026-03-16 |
| 4.2 | PM2 进程守护配置（`ecosystem.config.cjs`） | 🔴 高 | ✅ | 2026-03-16 |
| 4.3 | Nginx 反向代理配置（前端静态文件 + API 代理） | 🔴 高 | ✅ | 2026-03-16 |
| 4.4 | 生产构建验证（`pnpm build`） | 🟡 中 | ✅ | 2026-03-16 |
| 4.5 | 日志目录配置与轮转策略 | 🟡 中 | ✅ | 2026-03-16 |
---
## 五、关键技术决策
### 5.1 密码兼容性
**结论：无缝兼容，无需数据迁移。**
PHP 旧版密码加密方式：`md5($password . PASSWORD_KEY)`
Node.js 新版：`md5(password + PASSWORD_KEY)`（`utils.js` 中 `encryptPassword`）
两者算法完全一致，现有用户数据库中的密码哈希**无需任何迁移**。
### 5.2 Token 兼容性
**存在兼容性问题，需要特殊处理。**
| 场景 | PHP 旧版 token | Node.js 新版 token |
|------|---------------|-------------------|
| Web 登录 | `md5($password . PASSWORD_KEY)`（即密码哈希本身） | JWT（24h有效） |
| 游戏客户端验证 | account + token（md5密码）发送给游戏服 | **待确认** |
**建议方案**：保留 `/api/check` 接口，接受 `account + md5_token` 参数，后端用密码哈希验证后返回新 JWT，实现新旧格式互转。
### 5.3 区服数据库连接
PHP 提现逻辑会动态连接 `mir_actor_s{server_id}` 数据库验证货币余额。
Node.js 需要实现**动态多库连接**（根据区服 ID 选择不同数据库）。
**建议方案**：在 `mysql/` 下增加 `gameDB.js`，接受 `serverId` 参数，按需创建连接池。
### 5.4 静态文件服务
Egret 游戏资源（`public/` 目录，842 个文件，约数百 MB）需由 Web 服务器直接提供。
**建议方案**：Nginx 直接服务 `public/` 静态文件，Node.js 仅处理 `/api/*` 请求。
---
## 六、数据库表说明
| 表名 | 用途 | 读写方 |
|------|------|--------|
| `player` | 玩家账号（用户名/密码/邮箱/区服/IP等） | Node.js 账号接口 |
| `verify` | 邮箱验证码（60秒有效） | Node.js 发验证码/验证 |
| `server` | 游戏区服配置（名称/地址/端口/状态） | Node.js 区服列表接口 |
| `player_connect_threeparty` | 第三方账号绑定关系（LinuxDo等） | Node.js LinuxDo 接口 |
| `chat` | 游戏内聊天记录 | Node.js 上报接口 |
| `withdraw` | 提现申请记录 | Node.js 提现接口 |
| `agent` | 代理/推广员信息 | Node.js 注册接口（读取） |
---
## 七、进度总览
```
Phase 1：后端补全 ████████████████████ 100% ✅ 完成
Phase 2：前端补全 ████████████████████ 100% ✅ 完成
clear php
2026-03-16 13:10:18 +08:00
Phase 3：PHP 停用 ██████████████████░░ 90% 🔄 进行中（仅剩 php/ 目录物理删除 + 真实环境测试）
inint
2026-03-16 12:05:55 +08:00
Phase 4：部署运维 ████████████████████ 100% ✅ 完成
```
clear php
2026-03-16 13:10:18 +08:00
> **整体进度估算**：约 95%（PHP 文件已归档替换，剩余 `php/` 目录删除确认 + 真实环境联调）
inint
2026-03-16 12:05:55 +08:00
---
## 八、变更记录
| 日期 | 版本 | 变更内容 | 操作人 |
|------|------|----------|--------|
| 2026-03-16 | v1.0 | 初始版本：完成工程分析，制定移植计划 | WorkBuddy |
| 2026-03-16 | v1.1 | Phase1 补全：安全中间件(ipFilter/rateLimiter/errorHandler)、check接口、注册补全(设备/代理)、游戏DB、提现完善、GET /api/bind；Phase2 补全：index.vue 进入游戏逻辑、路由守卫、agree.vue、withdraw.vue；Phase4：.env.example、ecosystem.config.cjs、nginx.conf.example | WorkBuddy |
| 2026-03-16 | v1.2 | Phase1 收尾：config/agreement.html 独立协议文件、/api/config 补充提现参数、新增 POST /api/bind_account + GET /api/link（游戏服务端内部接口）；Phase2 收尾：login.vue 移动端响应式布局、vite.config.js 分包优化；Phase3：完成全量功能覆盖核查（PHP 100% 已覆盖）；Phase4：log4js 文件日志轮转配置、生产构建验证通过（✓ 1670 modules, 11.9s） | WorkBuddy |
clear php
2026-03-16 13:10:18 +08:00
| 2026-03-16 | v1.3 | Phase3 清理：所有 PHP 文件归档至 `_php_archive/`（6个PHP+PHPMailer全量）；根目录 PHP 文件替换为「已迁移」提示（api.php→410、login.php→301、server/linuxdo/config/function→说明注释）；nginx.conf.example 补充 `.php` 文件 404 屏蔽规则；修复 mysql/index.js queryFormat 私有API问题（Node24+mysql2 3.x 兼容性 Bug）；修复 log4js.js XML 标签污染导致的语法错误 | WorkBuddy |
inint
2026-03-16 12:05:55 +08:00
---
## 九、参考资料
- PHP 旧版主配置：`config.php`
- PHP 旧版 API 逻辑：`api.php`
- Node.js 配置：`module/server/config/index.js`
- Vue 前端入口：`module/web/src/main.js`
- 区服 API：`module/server/koa/registry.js`
- 账号 API：`module/server/koa/login.js`
Reference in New Issue Copy Permalink