# 橙仓游戏站搭建部署教程

**橙仓游戏站系统项目是一个基于nuxt前端+WordPress后端进行开发的游戏站系统部署很简单一看就会！**

本教程对应当前项目的正式架构：

- 前台：`https://game.wanhuitu.top`
- 后台：`https://cms.wanhuitu.top`
- 前台技术：Nuxt 构建后的纯静态文件
- 后台技术：WordPress + PHP + MySQL
- 数据接口：WordPress REST API

服务器不需要安装 Node.js、PM2、TypeScript，也不需要运行 `npm run dev`。Node.js 只在本地开发或重新生成前台文件时使用，宝塔服务器只负责静态文件、PHP 和 MySQL。

## 一、准备工作

准备以下内容：

1. 一个已经解析到服务器的域名，例如 `wanhuitu.top`。
2. 宝塔面板管理员权限。
3. 当前项目压缩包：

| 文件 | 用途 |
| --- | --- |
| `game-site-wordpress-frontend-v20.zip` | 前台纯静态网站，包含官方下载平台 SVG 图标 |
| `orange-game-cms-v12.zip` | WordPress 游戏、资源、排行、Hero 和站点配置 |
| `orange-game-importer-v7.zip` | 导入旧站 WordPress XML，并把多个下载地址聚合为一条资源 |
| `orange-game-users-v2.zip` | 前台注册、登录、收藏、投稿和密码相关接口 |
| `orange-headless-redirect-v2.zip` | 将 WordPress 普通前台访问跳回 Nuxt 前台 |

当前压缩包都在项目的 `game-site` 目录中。

## 二、解析域名

在域名服务商处添加两条 A 记录，指向宝塔服务器公网 IP：

| 主机记录 | 类型 | 记录值 |
| --- | --- | --- |
| `game` | A | 服务器公网 IP |
| `cms` | A | 服务器公网 IP |

等待解析生效后，在本地命令行测试：

```text
ping game.wanhuitu.top
ping cms.wanhuitu.top
```

如果返回的 IP 是你的服务器 IP，再继续创建网站。

## 三、创建后台网站和数据库

### 1. 创建 WordPress 网站

进入宝塔：

```text
网站 -> 添加站点
```

填写：

```text
域名：cms.wanhuitu.top
根目录：/www/wwwroot/cms.wanhuitu.top
PHP 版本：PHP 8.1、8.2 或 8.3
```

建议勾选创建数据库，数据库类型选择 MySQL。数据库名、用户名和密码使用宝塔自动生成的值，并保存到本地密码管理器。

### 2. 数据库字段怎么填

安装 WordPress 时填写的是数据库信息，不是域名：

| WordPress 字段 | 填写内容 |
| --- | --- |
| 数据库名 | 宝塔创建的 MySQL 数据库名 |
| 用户名 | 宝塔创建的数据库用户名 |
| 密码 | 宝塔显示的数据库密码 |
| 数据库主机 | `127.0.0.1` 或 `localhost` |
| 表前缀 | 默认 `wp_` 即可 |

数据库主机绝对不能填写 `game.wanhuitu.top` 或 `cms.wanhuitu.top`。这两个只是网站域名。

### 3. 安装 WordPress

在浏览器访问：

```text
https://cms.wanhuitu.top
```

按 WordPress 安装页面填写数据库信息，设置管理员账号和密码。管理员账号不要使用 `admin`，密码使用至少 12 位的随机密码。

安装完成后进入：

```text
https://cms.wanhuitu.top/wp-admin/
```

## 四、给后台开启 HTTPS

在宝塔进入：

```text
网站 -> cms.wanhuitu.top -> SSL
```

使用“Let's Encrypt”申请证书，勾选：

```text
强制 HTTPS
```

然后进入 WordPress：

```text
设置 -> 常规
```

确认以下两项都是 HTTPS：

```text
WordPress 地址：https://cms.wanhuitu.top
站点地址：https://cms.wanhuitu.top
```

## 五、安装和更新 WordPress 插件

### 方式 A：宝塔直接覆盖，最简单

1. 在宝塔文件管理打开：

   ```text
   /www/wwwroot/cms.wanhuitu.top/wp-content/plugins/
   ```

2. 上传 `orange-game-cms-v12.zip`。

3. 解压后确认出现目录：

   ```text
   /www/wwwroot/cms.wanhuitu.top/wp-content/plugins/orange-game-cms/
   ```

4. 如果提示同名目录，选择覆盖文件。

5. 对 `orange-game-users`、`orange-headless-redirect`、`orange-game-importer` 按同样方法操作。

插件目录里应该直接有 PHP 主文件，不能多套一层：

```text
正确：wp-content/plugins/orange-game-cms/orange-game-cms.php
错误：wp-content/plugins/orange-game-cms/orange-game-cms/orange-game-cms.php
```

### 方式 B：WordPress 后台上传

进入：

```text
插件 -> 安装插件 -> 上传插件
```

分别上传并启用：

1. `orange-game-cms-v12.zip`
2. `orange-game-users-v2.zip`
3. `orange-headless-redirect-v2.zip`
4. `orange-game-importer-v7.zip`

CMS 插件已经内置 CSF 框架，不需要单独安装或启用 `codestar-framework.zip`。

### 更新旧插件时

如果 WordPress 提示“目标文件夹已存在”：

1. 先在“插件”页面停用旧插件。
2. 使用宝塔文件管理覆盖同名插件目录。
3. 返回 WordPress 插件页面重新启用。

更新 CMS 或导入器不会删除游戏、资源和设置，它们都保存在现有 MySQL 数据库中。

## 六、设置 WordPress 固定链接

进入：

```text
设置 -> 固定链接
```

选择：

```text
文章名
```

点击“保存更改”一次。即使原来已经是“文章名”，也建议重新保存一次，让 WordPress 刷新重写规则。

## 七、配置游戏站后台

进入：

```text
设置 -> 橙仓游戏站
```

填写：

```text
网站名称：你的游戏站名称
Nuxt 前台地址：https://game.wanhuitu.top
网站描述：你的站点介绍
联系邮箱：管理员邮箱
```

这里还可以设置：

- 网站名称和描述
- 首页公告
- 顶部导航
- 页脚链接
- SEO 关键词
- 版权文字
- 维护模式

这些设置保存后由前台 REST API 读取。

## 八、创建前台纯静态网站

### 1. 在宝塔添加网站

进入：

```text
网站 -> 添加站点
```

填写：

```text
域名：game.wanhuitu.top
根目录：/www/wwwroot/game.wanhuitu.top
```

这个网站不需要绑定数据库，也不需要选择 PHP。可以创建普通静态网站。如果宝塔必须选择运行环境，选择静态或 PHP 均可，但不要给前台配置 PHP 接口。

### 2. 上传前台压缩包

上传：

```text
game-site-wordpress-frontend-v20.zip
```

解压到：

```text
/www/wwwroot/game.wanhuitu.top/
```

解压完成后，根目录必须直接看到：

```text
index.html
_nuxt/
assets/
download-icons/
games/
```

不能出现这种多套目录：

```text
/www/wwwroot/game.wanhuitu.top/game-site-wordpress-frontend-v20/index.html
```

如果多了一层目录，把里面的全部文件剪切到网站根目录。

### 3. 给前台申请 SSL

在宝塔：

```text
网站 -> game.wanhuitu.top -> SSL
```

申请 Let's Encrypt 证书并开启“强制 HTTPS”。前台请求后台接口时使用 HTTPS，两个域名不能一个 HTTPS、一个 HTTP。

## 九、前台伪静态配置

进入：

```text
网站 -> game.wanhuitu.top -> 伪静态
```

如果是 Nginx，只填下面内容：

```nginx
location / {
    try_files $uri $uri/ /index.html;
}
```

保存后访问：

```text
https://game.wanhuitu.top/games/zephon
```

如果刷新后仍能正常打开游戏详情页，说明伪静态正确。

不要把 `location` 配置粘贴到 `/www/server/nginx/conf/nginx.conf` 全局文件中。它只能放在 `game.wanhuitu.top` 这个网站自己的 Nginx 配置里。

普通静态前台不需要添加：

```nginx
client_max_body_size 5G;
```

这个配置是上传文件大小限制，放错位置会导致 Nginx 无法启动。游戏压缩包建议上传到 WordPress 媒体库或对象存储，前台只保存真实下载地址。

## 十、检查接口是否正常

浏览器分别打开：

```text
https://cms.wanhuitu.top/index.php?rest_route=/orange/v1/site
https://cms.wanhuitu.top/index.php?rest_route=/orange/v1/games
https://cms.wanhuitu.top/index.php?rest_route=/orange/v1/rankings
```

正常时会看到 JSON 数据，而不是 WordPress 404 页面。

详情游戏接口示例：

```text
https://cms.wanhuitu.top/index.php?rest_route=/orange/v1/games&slug=游戏别名
```

如果返回 `game: null`，说明游戏不是“已发布”状态，或者别名填写错误。

## 十一、导入旧站游戏

1. 确认 CMS 插件和导入器都已启用。

2. 进入：

   ```text
   工具 -> 旧站游戏导入
   ```

3. 上传旧 WordPress 导出的 XML 文件。

4. 点击“开始导入”。

导入器会读取：

- 游戏标题和正文
- 摘要
- 封面地址
- 开发商和发行日期
- 游戏评分和热度
- 系统配置要求
- 下载地址
- 提取码和备注

同一个游戏的多个下载地址会聚合到一条“游戏名 · 下载资源”中。重复导入同一 XML 时会更新原游戏，不会重复创建游戏；旧版分散资源会移动到 WordPress 回收站，可以恢复。

原 XML 没有提供封面或下载地址的游戏，导入器不会凭空生成数据。

## 十二、后台发布游戏

进入：

```text
游戏 -> 添加新游戏
```

建议按下面顺序填写：

 1. 标题：游戏中文名称。
 2. 正文：使用 WordPress 编辑器填写完整详情。
 3. 摘要：填写列表页和首页使用的简介。
 4. 特色图片：设置游戏封面。
 5. 游戏分类：选择或新建分类。
 6. 游戏基本信息：平台、容量、发行日期、开发商、发行商。
 7. 游戏特色：每行一条。
 8. 配置要求：按照页面提示填写。
 9. 首页与排行设置：设置精选、热度、推荐度、讨论数和排序。
10. 点击发布。

## 十三、后台发布下载资源

进入：

```text
资源 -> 添加资源版本
```

填写关联游戏、版本号和资源类型。

多个下载渠道每行填写一条，格式为：

```text
百度网盘下载 | https://pan.baidu.com/xxx | 提取码：abcd
夸克网盘下载 | https://pan.quark.cn/xxx
123云盘下载 | https://www.123pan.com/xxx
Steam 商店下载 | https://store.steampowered.com/app/xxx
```

保存后，前台会显示多个带官方 Logo 的下载按钮。后台没有填写 Logo 的平台，前台使用通用下载图标。

## 十四、管理首页 Hero 和排行榜

### 首页 Hero

进入：

```text
首页焦点 -> 添加首页焦点
```

可设置标题、描述、封面、按钮文字、跳转地址、关联游戏、显示顺序和是否启用。

### 排行榜

进入：

```text
排行榜
```

每条排行榜都可以设置：

- 榜单标题
- 榜单说明
- 自动规则：热度、推荐度、本周更新、玩家热议
- 手动游戏 ID
- 显示数量
- 底部提示文字
- 主题颜色
- 排序和启用状态

手动游戏 ID 可以在“游戏”列表标题旁看到，多个 ID 使用英文逗号分隔。

## 十五、帮助中心、关于我们和隐私政策

当前这三个页面属于前台静态页面，页面文字在前台源码中，不是 WordPress 文章，所以修改后需要重新生成前台压缩包。

当前推荐的内容管理方式是后续把它们迁移为 WordPress 页面：

```text
页面 -> 新建页面
```

创建以下页面并设置固定链接：

```text
help
about
privacy
```

如果当前 CMS 插件版本还没有“页面内容 API”，暂时不要直接创建同名页面期待前台自动读取；前台仍会显示静态内容。需要我继续改造时，应增加 WordPress 页面 REST 接口并让前台按 slug 读取。

## 十六、邮件和普通用户

普通用户功能由 `orange-game-users` 插件提供，包括注册、登录、收藏、投稿和密码相关接口。

如果需要找回密码和邮箱验证，必须在 WordPress 服务器配置 SMTP。建议使用企业邮箱、QQ 邮箱或 163 邮箱的 SMTP 授权码，不要填写邮箱网页登录密码。

邮件配置通常需要：

```text
SMTP 主机
SMTP 端口
SMTP 用户名
SMTP 授权码
SSL 或 TLS
```

如果暂时不配置 SMTP，账号和数据库仍然可以使用，但验证邮件和找回密码邮件无法发送。

## 十七、文件上传设置

如果要在 WordPress 媒体库上传大压缩包，进入宝塔：

```text
软件 -> 已安装 -> PHP 8.x -> 配置 -> 配置修改
```

按实际需要调整：

```ini
upload_max_filesize = 2G
post_max_size = 2G
max_execution_time = 600
max_input_time = 600
memory_limit = 512M
```

修改后重启对应 PHP 服务。前台纯静态站点不需要设置上传大小。

如果文件很大，推荐上传到对象存储、百度网盘、夸克网盘或其他可公开访问的存储，然后在资源中填写地址。下载按钮只会跳转到后台保存的真实 URL。

## 十八、更新前台

更新前台只需要：

1. 在宝塔备份当前网站目录。
2. 上传新的前台 ZIP。
3. 解压并覆盖网站根目录。
4. 确认 `index.html`、`_nuxt`、`assets` 和 `download-icons` 直接在根目录。
5. 浏览器执行 `Ctrl + F5`。

不要删除 WordPress 数据库，也不要修改后台域名。

## 十九、更新 WordPress 插件

更新插件前先备份数据库和插件目录，然后：

1. WordPress 后台停用旧插件。
2. 宝塔覆盖对应插件目录。
3. WordPress 后台重新启用插件。
4. 打开一次游戏、资源和设置页面。

更新 CMS 插件不会删除数据库中的游戏、资源、用户、排行榜和网站配置。

## 二十、常见问题

### 前台显示空白

确认网站根目录有 `index.html`，而不是多套了一层文件夹；然后检查 SSL 和浏览器控制台。

### 刷新游戏详情页 404

检查前台网站自己的伪静态是否是：

```nginx
location / {
    try_files $uri $uri/ /index.html;
}
```

不要把这段配置放到服务器全局 Nginx 配置中。

### 前台没有新发布的游戏

确认游戏状态是“已发布”，CMS 插件已启用，并打开 `/orange/v1/games` 接口查看是否返回数据。之后使用 `Ctrl + F5`。

### 删除游戏后前台仍能看到

确认删除的是“游戏”本身，不只是资源；确认前台已经覆盖最新静态包，并执行强制刷新。CMS 接口只返回 `publish` 状态的游戏。

### 下载按钮显示通用图标

这是因为平台没有匹配到已配置的官方 SVG，或者下载域名是自定义短链。百度、123、夸克、阿里、迅雷、UC、Steam 使用官方 SVG；自定义短链需要在后台把渠道名称写清楚，例如“百度网盘下载”。

### WordPress 插件提示无效或致命错误

检查 PHP 版本至少为 7.4，推荐 PHP 8.2；确认插件主文件没有多套目录；CMS 插件不要拆出或单独安装 CSF 框架。

### Nginx 测试失败并提示 `client_max_body_size directive is not allowed here`

删除错误粘贴到全局 Nginx 配置的 `client_max_body_size` 行。普通前台完全不需要这项配置；大文件上传应在 PHP 配置中调整 `upload_max_filesize` 和 `post_max_size`。

### 后台接口被跨域拦截

确认前台和后台都使用 HTTPS，后台地址为 `cms.wanhuitu.top`，前台设置中的地址为 `https://game.wanhuitu.top`，并确认 CMS 与用户插件已启用。

## 二十一、上线检查清单

- [ ] `game.wanhuitu.top` 和 `cms.wanhuitu.top` DNS 已解析。

- [ ] 两个网站都申请并启用了 SSL。

- [ ] WordPress 数据库连接正常。

- [ ] WordPress 固定链接已保存为“文章名”。

- [ ] CMS、用户、Headless 跳转插件已启用。

- [ ] 前台根目录直接有 `index.html` 和 `_nuxt`。

- [ ] 前台根目录有 `download-icons` 官方 SVG 图标目录。

- [ ] 前台伪静态已配置在前台网站自己的配置中。

- [ ] `/orange/v1/site`、`/orange/v1/games`、`/orange/v1/rankings` 可以返回 JSON。

- [ ] 可以发布一款测试游戏并在前台看到。

- [ ] 可以添加一条资源并点击真实下载地址。

- [ ] 已备份 WordPress 数据库和网站目录。