whale-town-end/DEPLOYMENT.md

🚀 Whale Town 部署指南

本文档详细说明如何部署 Whale Town 像素游戏后端服务到生产环境。

📋 前置要求

基础环境

• Node.js 18+ (推荐 20.x LTS)
• pnpm 包管理器
• MySQL 8.0+
• Redis 6.0+ (可选，支持文件存储模式)
• PM2 进程管理器（推荐）
• Nginx 反向代理（推荐）

新增要求 (管理员后台)

• Web服务器 (Nginx/Apache) - 用于前端管理界面
• SSL证书 (推荐) - 保护管理后台安全

部署步骤

1. 服务器环境准备

# 安装 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. 克隆项目

# 创建项目目录
sudo mkdir -p /var/www
cd /var/www

# 克隆项目（替换为你的实际仓库地址）
git clone https://gitea.xinghangee.icu/datawhale/whale-town-end.git
cd whale-town-end

3. 配置环境

# 复制环境配置文件
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. 数据库设置

# 登录 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. 安装依赖和构建

# 安装后端依赖
pnpm install --frozen-lockfile

# 安装前端依赖 (新增)
cd client
pnpm install --frozen-lockfile
cd ..

# 构建后端
pnpm run build

# 构建前端管理界面 (新增)
cd client
pnpm run build
cd ..

6. 启动服务

# 使用 PM2 启动应用
pm2 start ecosystem.config.js --env production

# 保存 PM2 配置
pm2 save

# 设置开机自启
pm2 startup
# 按照提示执行显示的命令

7. 配置 Nginx

方案一: 分离部署 (推荐)

创建后端API配置：

sudo nano /etc/nginx/sites-available/whale-town-api

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;
    }
}

创建前端管理界面配置：

sudo nano /etc/nginx/sites-available/whale-town-admin

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";
    }
}

方案二: 单域名部署

创建统一配置：

sudo nano /etc/nginx/sites-available/whale-town-unified

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;
    }
}

启用配置：

# 启用站点
sudo ln -s /etc/nginx/sites-available/whale-town-* /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重载配置
sudo systemctl reload nginx

🔒 SSL证书配置 (推荐)

使用 Let's Encrypt

# 安装 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 中添加：

# 管理员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
2. 配置：
   • 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

✅ 验证部署

基础服务检查

# 检查PM2服务状态
pm2 status

# 检查后端API
curl http://localhost:3000/
curl http://localhost:3000/api-docs

# 检查前端管理界面
curl -I https://admin.whaletown.com

管理员后台测试

# 测试管理员登录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证书配置正确

🔧 常用命令

服务管理

# 重启后端服务
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

更新部署

# 更新后端
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 ..

日志管理

# 查看应用日志
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)
• 清理旧日志文件
• 监控磁盘使用情况