feat: 添加生产环境部署配置

- 添加 Dockerfile 和 docker-compose.yml 支持容器化部署 - 添加 PM2 配置文件 ecosystem.config.js - 添加部署脚本模板 deploy.sh.example - 添加 Gitea webhook 处理器模板 webhook-handler.js.example - 添加生产环境配置模板 .env.production.example - 添加详细的部署指南 DEPLOYMENT.md - 更新 .gitignore 排除敏感配置文件
2025-12-17 15:37:40 +08:00
parent 178130bb27
commit a907e64f40
8 changed files with 482 additions and 0 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -0,0 +1,217 @@
+# 部署指南
+
+本文档详细说明如何部署 Pixel Game Server 到生产环境。
+
+## 前置要求
+
+- Node.js 18+
+- pnpm 包管理器
+- MySQL 8.0+
+- PM2 进程管理器（推荐）
+- Nginx（可选，用于反向代理）
+
+## 部署步骤
+
+### 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
+
+# 克隆项目（替换为你的实际仓库地址）
+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. 配置环境
+
+```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
+
+# 构建项目
+pnpm run build
+```
+
+### 6. 启动服务
+
+```bash
+# 使用 PM2 启动应用
+pm2 start ecosystem.config.js --env production
+
+# 保存 PM2 配置
+pm2 save
+
+# 设置开机自启
+pm2 startup
+# 按照提示执行显示的命令
+```
+
+### 7. 配置 Nginx（可选）
+
+创建 Nginx 配置文件：
+
+```bash
+sudo nano /etc/nginx/sites-available/pixel-game-server
+```
+
+添加以下内容：
+
+```nginx
+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;
+    }
+}
+```
+
+启用站点：
+
+```bash
+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`
+
+## 验证部署
+
+```bash
+# 检查服务状态
+pm2 status
+
+# 查看日志
+pm2 logs pixel-game-server
+pm2 logs webhook-handler
+
+# 测试 API
+curl http://localhost:3000/
+curl http://localhost:3000/api-docs
+```
+
+## 常用命令
+
+```bash
+# 重启服务
+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 服务状态
+- 验证数据库用户权限
+- 检查网络连接