whale-town-end/DEPLOYMENT.md

部署指南

本文档详细说明如何部署 Pixel Game Server 到生产环境。

前置要求

• Node.js 18+
• pnpm 包管理器
• MySQL 8.0+
• PM2 进程管理器（推荐）
• Nginx（可选，用于反向代理）

部署步骤

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

# 克隆项目（替换为你的实际仓库地址）
sudo git clone https://your-gitea-server.com/username/pixel-game-server.git
sudo chown -R $USER:$USER pixel-game-server
cd pixel-game-server

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

# 构建项目
pnpm run build

6. 启动服务

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

# 保存 PM2 配置
pm2 save

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

7. 配置 Nginx（可选）

创建 Nginx 配置文件：

sudo nano /etc/nginx/sites-available/pixel-game-server

添加以下内容：

server {
    listen 80;
    server_name your-domain.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;
    }

    location /webhook {
        proxy_pass http://localhost:9000;
        proxy_http_version 1.1;
        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;
    }
}

启用站点：

sudo ln -s /etc/nginx/sites-available/pixel-game-server /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Gitea Webhook 配置

1. 在 Gitea 仓库中进入 Settings → Webhooks
2. 点击 Add Webhook → Gitea
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

验证部署

# 检查服务状态
pm2 status

# 查看日志
pm2 logs pixel-game-server
pm2 logs webhook-handler

# 测试 API
curl http://localhost:3000/
curl http://localhost:3000/api-docs

常用命令

# 重启服务
pm2 restart pixel-game-server

# 查看日志
pm2 logs pixel-game-server --lines 100

# 手动部署
bash deploy.sh

# 更新代码（不重启）
git pull origin main
pnpm install
pnpm run build
pm2 reload pixel-game-server

故障排除

服务无法启动

• 检查环境变量配置
• 检查数据库连接
• 查看 PM2 日志

Webhook 不工作

• 检查防火墙设置
• 验证 webhook URL 可访问性
• 检查 Gitea webhook 日志
• 验证签名密钥是否一致

数据库连接失败

• 检查 MySQL 服务状态
• 验证数据库用户权限
• 检查网络连接