forked from datawhale/whale-town-end
d80d2c5cb8
- 更新README.md：添加管理员后台系统介绍，更新测试统计为154个用例 - 更新CONTRIBUTORS.md：补充jianuo的管理员后台开发贡献，更新项目里程碑 - 更新DEPLOYMENT.md：完善前后端分离部署方案，添加管理员后台配置说明 - 反映最新管理员后台功能的部署要求和配置变更
418 lines
8.9 KiB
Markdown
418 lines
8.9 KiB
Markdown
# 🚀 Whale Town 部署指南
|
||
|
||
本文档详细说明如何部署 Whale Town 像素游戏后端服务到生产环境。
|
||
|
||
## 📋 前置要求
|
||
|
||
### 基础环境
|
||
- **Node.js** 18+ (推荐 20.x LTS)
|
||
- **pnpm** 包管理器
|
||
- **MySQL** 8.0+
|
||
- **Redis** 6.0+ (可选，支持文件存储模式)
|
||
- **PM2** 进程管理器（推荐）
|
||
- **Nginx** 反向代理（推荐）
|
||
|
||
### 新增要求 (管理员后台)
|
||
- **Web服务器** (Nginx/Apache) - 用于前端管理界面
|
||
- **SSL证书** (推荐) - 保护管理后台安全
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 服务器环境准备
|
||
|
||
```bash
|
||
# 安装 Node.js (使用 NodeSource 仓库)
|
||
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs
|
||
|
||
# 安装 pnpm
|
||
curl -fsSL https://get.pnpm.io/install.sh | sh
|
||
source ~/.bashrc
|
||
|
||
# 安装 PM2
|
||
npm install -g pm2
|
||
|
||
# 安装 MySQL
|
||
sudo apt update
|
||
sudo apt install mysql-server
|
||
sudo mysql_secure_installation
|
||
```
|
||
|
||
### 2. 克隆项目
|
||
|
||
```bash
|
||
# 创建项目目录
|
||
sudo mkdir -p /var/www
|
||
cd /var/www
|
||
|
||
# 克隆项目（替换为你的实际仓库地址）
|
||
git clone https://gitea.xinghangee.icu/datawhale/whale-town-end.git
|
||
cd whale-town-end
|
||
```
|
||
|
||
### 3. 配置环境
|
||
|
||
```bash
|
||
# 复制环境配置文件
|
||
cp .env.production.example .env.production
|
||
|
||
# 编辑环境配置（填入实际的数据库信息）
|
||
nano .env.production
|
||
|
||
# 复制部署脚本
|
||
cp deploy.sh.example deploy.sh
|
||
chmod +x deploy.sh
|
||
|
||
# 编辑部署脚本（修改路径配置）
|
||
nano deploy.sh
|
||
|
||
# 复制 webhook 处理器
|
||
cp webhook-handler.js.example webhook-handler.js
|
||
|
||
# 编辑 webhook 处理器（修改密钥和路径）
|
||
nano webhook-handler.js
|
||
```
|
||
|
||
### 4. 数据库设置
|
||
|
||
```bash
|
||
# 登录 MySQL
|
||
sudo mysql -u root -p
|
||
|
||
# 创建数据库和用户
|
||
CREATE DATABASE pixel_game_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
CREATE USER 'pixel_game'@'localhost' IDENTIFIED BY 'your_secure_password';
|
||
GRANT ALL PRIVILEGES ON pixel_game_db.* TO 'pixel_game'@'localhost';
|
||
FLUSH PRIVILEGES;
|
||
EXIT;
|
||
```
|
||
|
||
### 5. 安装依赖和构建
|
||
|
||
```bash
|
||
# 安装后端依赖
|
||
pnpm install --frozen-lockfile
|
||
|
||
# 安装前端依赖 (新增)
|
||
cd client
|
||
pnpm install --frozen-lockfile
|
||
cd ..
|
||
|
||
# 构建后端
|
||
pnpm run build
|
||
|
||
# 构建前端管理界面 (新增)
|
||
cd client
|
||
pnpm run build
|
||
cd ..
|
||
```
|
||
|
||
### 6. 启动服务
|
||
|
||
```bash
|
||
# 使用 PM2 启动应用
|
||
pm2 start ecosystem.config.js --env production
|
||
|
||
# 保存 PM2 配置
|
||
pm2 save
|
||
|
||
# 设置开机自启
|
||
pm2 startup
|
||
# 按照提示执行显示的命令
|
||
```
|
||
|
||
### 7. 配置 Nginx
|
||
|
||
#### 方案一: 分离部署 (推荐)
|
||
|
||
创建后端API配置：
|
||
```bash
|
||
sudo nano /etc/nginx/sites-available/whale-town-api
|
||
```
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name api.whaletown.com;
|
||
|
||
location / {
|
||
proxy_pass http://localhost:3000;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection 'upgrade';
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_cache_bypass $http_upgrade;
|
||
}
|
||
}
|
||
```
|
||
|
||
创建前端管理界面配置：
|
||
```bash
|
||
sudo nano /etc/nginx/sites-available/whale-town-admin
|
||
```
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name admin.whaletown.com;
|
||
root /var/www/whale-town-end/client/dist;
|
||
index index.html;
|
||
|
||
# SPA路由支持
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# API代理
|
||
location /api/ {
|
||
proxy_pass http://api.whaletown.com/;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
}
|
||
|
||
# 静态资源缓存
|
||
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
|
||
expires 1y;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 方案二: 单域名部署
|
||
|
||
创建统一配置：
|
||
```bash
|
||
sudo nano /etc/nginx/sites-available/whale-town-unified
|
||
```
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name whaletown.com;
|
||
|
||
# API接口
|
||
location /api/ {
|
||
proxy_pass http://localhost:3000/;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
|
||
# 管理后台
|
||
location /admin/ {
|
||
alias /var/www/whale-town-end/client/dist/;
|
||
try_files $uri $uri/ /admin/index.html;
|
||
}
|
||
|
||
# 主站点 (可选)
|
||
location / {
|
||
proxy_pass http://localhost:3000;
|
||
}
|
||
}
|
||
```
|
||
|
||
启用配置：
|
||
```bash
|
||
# 启用站点
|
||
sudo ln -s /etc/nginx/sites-available/whale-town-* /etc/nginx/sites-enabled/
|
||
|
||
# 测试配置
|
||
sudo nginx -t
|
||
|
||
# 重载配置
|
||
sudo systemctl reload nginx
|
||
```
|
||
|
||
## 🔒 SSL证书配置 (推荐)
|
||
|
||
### 使用 Let's Encrypt
|
||
```bash
|
||
# 安装 Certbot
|
||
sudo apt install certbot python3-certbot-nginx
|
||
|
||
# 为API域名申请证书
|
||
sudo certbot --nginx -d api.whaletown.com
|
||
|
||
# 为管理后台申请证书
|
||
sudo certbot --nginx -d admin.whaletown.com
|
||
|
||
# 设置自动续期
|
||
sudo crontab -e
|
||
# 添加: 0 12 * * * /usr/bin/certbot renew --quiet
|
||
```
|
||
|
||
## 🎛️ 管理员后台配置
|
||
|
||
### 环境变量配置
|
||
在 `.env.production` 中添加：
|
||
```bash
|
||
# 管理员Token配置 (必须)
|
||
ADMIN_TOKEN_SECRET=your_super_strong_random_secret_at_least_32_chars
|
||
ADMIN_TOKEN_TTL_SECONDS=28800
|
||
|
||
# 首次部署启用管理员引导
|
||
ADMIN_BOOTSTRAP_ENABLED=true
|
||
ADMIN_USERNAME=admin
|
||
ADMIN_PASSWORD=YourStrongPassword123!
|
||
ADMIN_NICKNAME=系统管理员
|
||
|
||
# CORS配置 (如果前后端分离)
|
||
CORS_ORIGIN=https://admin.whaletown.com
|
||
```
|
||
|
||
### 访问管理后台
|
||
- **地址**: https://admin.whaletown.com
|
||
- **默认账号**: admin / YourStrongPassword123!
|
||
|
||
**⚠️ 重要**: 首次登录后立即修改密码并关闭引导功能 (`ADMIN_BOOTSTRAP_ENABLED=false`)
|
||
|
||
## 📡 Gitea Webhook 配置
|
||
1. 在 Gitea 仓库中进入 **Settings** → **Webhooks**
|
||
3. 配置：
|
||
- **Target URL**: `http://your-server.com:9000/webhook` 或 `http://your-domain.com/webhook`
|
||
- **HTTP Method**: `POST`
|
||
- **POST Content Type**: `application/json`
|
||
- **Secret**: 与 `webhook-handler.js` 中的 `SECRET` 一致
|
||
- **Trigger On**: 选择 `Push events`
|
||
- **Branch filter**: `main`
|
||
|
||
## ✅ 验证部署
|
||
|
||
### 基础服务检查
|
||
```bash
|
||
# 检查PM2服务状态
|
||
pm2 status
|
||
|
||
# 检查后端API
|
||
curl http://localhost:3000/
|
||
curl http://localhost:3000/api-docs
|
||
|
||
# 检查前端管理界面
|
||
curl -I https://admin.whaletown.com
|
||
```
|
||
|
||
### 管理员后台测试
|
||
```bash
|
||
# 测试管理员登录API
|
||
curl -X POST https://api.whaletown.com/admin/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"identifier":"admin","password":"YourStrongPassword123!"}'
|
||
|
||
# 访问管理界面
|
||
# 浏览器打开: https://admin.whaletown.com
|
||
```
|
||
|
||
### 功能验证清单
|
||
- [ ] 后端API服务正常响应
|
||
- [ ] API文档可访问
|
||
- [ ] 前端管理界面加载正常
|
||
- [ ] 管理员登录功能正常
|
||
- [ ] 用户管理功能正常
|
||
- [ ] 日志查看功能正常
|
||
- [ ] SSL证书配置正确
|
||
|
||
## 🔧 常用命令
|
||
|
||
### 服务管理
|
||
```bash
|
||
# 重启后端服务
|
||
pm2 restart whale-town-end
|
||
|
||
# 重启前端服务 (如果使用PM2托管)
|
||
pm2 restart whale-town-admin
|
||
|
||
# 查看服务日志
|
||
pm2 logs whale-town-end --lines 100
|
||
pm2 logs whale-town-admin --lines 100
|
||
|
||
# 手动部署
|
||
bash deploy.sh
|
||
```
|
||
|
||
### 更新部署
|
||
```bash
|
||
# 更新后端
|
||
git pull origin main
|
||
pnpm install
|
||
pnpm run build
|
||
pm2 reload whale-town-end
|
||
|
||
# 更新前端管理界面
|
||
cd client
|
||
git pull origin main
|
||
pnpm install
|
||
pnpm run build
|
||
sudo systemctl reload nginx
|
||
cd ..
|
||
```
|
||
|
||
### 日志管理
|
||
```bash
|
||
# 查看应用日志
|
||
tail -f logs/app.log
|
||
|
||
# 查看管理员操作日志
|
||
tail -f logs/admin.log
|
||
|
||
# 查看Nginx日志
|
||
sudo tail -f /var/log/nginx/access.log
|
||
sudo tail -f /var/log/nginx/error.log
|
||
```
|
||
|
||
## 🚨 故障排除
|
||
|
||
### 后端服务问题
|
||
**服务无法启动**
|
||
- 检查环境变量配置 (`cat .env.production`)
|
||
- 检查数据库连接 (`mysql -u pixel_game -p`)
|
||
- 查看PM2日志 (`pm2 logs whale-town-end`)
|
||
- 检查端口占用 (`netstat -tlnp | grep 3000`)
|
||
|
||
**管理员登录失败**
|
||
- 验证 `ADMIN_TOKEN_SECRET` 配置
|
||
- 检查管理员账号是否创建
|
||
- 查看后端错误日志
|
||
- 确认密码复杂度要求
|
||
|
||
### 前端管理界面问题
|
||
**界面无法访问**
|
||
- 检查前端构建是否成功 (`ls -la client/dist/`)
|
||
- 验证Nginx配置 (`sudo nginx -t`)
|
||
- 检查域名解析
|
||
- 查看Nginx错误日志
|
||
|
||
**API请求失败**
|
||
- 检查CORS配置
|
||
- 验证API代理设置
|
||
- 确认后端服务状态
|
||
- 检查防火墙规则
|
||
|
||
### 数据库连接问题
|
||
**连接失败**
|
||
- 检查MySQL服务状态 (`sudo systemctl status mysql`)
|
||
- 验证数据库用户权限
|
||
- 检查网络连接
|
||
- 确认数据库配置
|
||
|
||
### SSL证书问题
|
||
**证书验证失败**
|
||
- 检查证书有效期 (`sudo certbot certificates`)
|
||
- 验证域名解析
|
||
- 重新申请证书 (`sudo certbot --nginx -d your-domain.com`)
|
||
|
||
### 性能问题
|
||
**响应缓慢**
|
||
- 检查系统资源使用 (`htop`, `df -h`)
|
||
- 优化数据库查询
|
||
- 配置Redis缓存
|
||
- 启用Nginx压缩
|
||
|
||
### 日志文件过大
|
||
**磁盘空间不足**
|
||
- 配置日志轮转 (`sudo nano /etc/logrotate.d/whale-town`)
|
||
- 清理旧日志文件
|
||
- 监控磁盘使用情况 |