【像素贪吃蛇小游戏】部署文档-linux篇

Linux 部署指南

本文档将帮助你在 Linux 系统上部署像素贪吃蛇游戏。

📋 目录

文章目录

[Linux 部署指南](#Linux 部署指南)
- [📋 目录](#📋 目录)
- [🔧 环境要求](#🔧 环境要求)
- - 必需软件
  - [支持的 Linux 发行版](#支持的 Linux 发行版)
- 其他主流发行版
- [📦 安装 Node.js](#📦 安装 Node.js)
- - [方法一：使用 NodeSource（推荐）](#方法一：使用 NodeSource（推荐）)
  - - Ubuntu/Debian
    - CentOS/RHEL
  - [方法二：使用 NVM（Node Version Manager）](#方法二：使用 NVM（Node Version Manager）)
  - 验证安装
- [📥 安装步骤](#📥 安装步骤)
- - 方法一：离线部署（推荐）
  - - [1. 下载离线部署包](#1. 下载离线部署包)
    - [2. 解压压缩包](#2. 解压压缩包)
    - [3. 安装依赖](#3. 安装依赖)
    - [4. 查看离线部署说明](#4. 查看离线部署说明)
  - [方法二：使用 Git 克隆](#方法二：使用 Git 克隆)
  - - [1. 克隆项目](#1. 克隆项目)
    - [2. 安装依赖](#2. 安装依赖)
- [🚀 开发模式运行](#🚀 开发模式运行)
- - 启动开发服务器
  - 后台运行
  - 访问游戏
  - 停止服务
- [🏭 生产环境部署](#🏭 生产环境部署)
- - 方法一：直接运行
  - - [1. 构建项目](#1. 构建项目)
    - [2. 启动生产服务器](#2. 启动生产服务器)
    - [3. 后台运行](#3. 后台运行)
  - [方法二：使用 PM2（推荐）](#方法二：使用 PM2（推荐）)
  - - [1. 安装 PM2](#1. 安装 PM2)
    - [2. 创建 ecosystem 配置文件](#2. 创建 ecosystem 配置文件)
    - [3. 构建并启动](#3. 构建并启动)
    - [4. PM2 常用命令](#4. PM2 常用命令)
    - [5. 设置开机自启](#5. 设置开机自启)
  - [方法三：使用 Systemd（系统服务）](#方法三：使用 Systemd（系统服务）)
  - - [1. 创建服务文件](#1. 创建服务文件)
    - [2. 添加以下内容](#2. 添加以下内容)
    - [3. 启动服务](#3. 启动服务)
    - [4. 管理服务](#4. 管理服务)
- [🌐 Nginx 反向代理](#🌐 Nginx 反向代理)
- - [安装 Nginx](#安装 Nginx)
  - - Ubuntu/Debian
    - CentOS/RHEL
  - [配置 Nginx](#配置 Nginx)
  - - [1. 创建配置文件](#1. 创建配置文件)
    - [2. 添加配置](#2. 添加配置)
    - [3. 启用配置](#3. 启用配置)
  - [配置 HTTPS（使用 Let's Encrypt）](#配置 HTTPS（使用 Let's Encrypt）)
  - - [1. 安装 Certbot](#1. 安装 Certbot)
    - [2. 获取证书](#2. 获取证书)
    - [3. 自动续期](#3. 自动续期)
- [🔥 防火墙配置](#🔥 防火墙配置)
- - Ubuntu/Debian (UFW)
  - CentOS/RHEL (Firewalld)
- [🐳 Docker 部署](#🐳 Docker 部署)
- - [1. 创建 Dockerfile](#1. 创建 Dockerfile)
  - [2. 创建 docker-compose.yml](#2. 创建 docker-compose.yml)
  - [3. 构建并运行](#3. 构建并运行)
  - [4. 使用 Nginx 容器](#4. 使用 Nginx 容器)
- [📊 性能优化](#📊 性能优化)
- - [1. 启用 Gzip 压缩](#1. 启用 Gzip 压缩)
  - [2. 配置 CDN](#2. 配置 CDN)
  - [3. Nginx 缓存配置](#3. Nginx 缓存配置)
- [🔒 安全建议](#🔒 安全建议)
- [🐛 常见问题](#🐛 常见问题)
- - [Q1: 端口 5000 被占用？](#Q1: 端口 5000 被占用？)
  - [Q2: npm install 失败？](#Q2: npm install 失败？)
  - [Q3: 构建失败，内存不足？](#Q3: 构建失败，内存不足？)
  - [Q4: PM2 应用自动重启？](#Q4: PM2 应用自动重启？)
- 端口冲突
- - [Q5: Nginx 502 错误？](#Q5: Nginx 502 错误？)
  - [Q6: 无法访问服务器？](#Q6: 无法访问服务器？)
- [📈 监控和日志](#📈 监控和日志)
- - [使用 PM2 监控](#使用 PM2 监控)
  - 日志管理
  - 系统监控
- [🔄 更新部署](#🔄 更新部署)
- - [使用 Git 更新](#使用 Git 更新)
- **祝你部署顺利！🎉**

🔧 环境要求

必需软件

软件	版本要求	安装命令
Node.js	18+	见下方
pnpm	最新版本	`npm install -g pnpm`
Git	任意版本	`sudo apt install git` (Ubuntu/Debian)
Nginx	可选	`sudo apt install nginx`
PM2	可选	`npm install -g pm2`

支持的 Linux 发行版

Ubuntu 20.04+
Debian 10+
CentOS 7+
Amazon Linux 2

其他主流发行版

📦 安装 Node.js

方法一：使用 NodeSource（推荐）

Ubuntu/Debian

Bash 复制代码

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

CentOS/RHEL

Bash 复制代码

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

方法二：使用 NVM（Node Version Manager）

Bash 复制代码

# 安装 NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载配置
source ~/.bashrc

# 安装最新 LTS 版本
nvm install --lts
nvm use --lts

验证安装

Bash 复制代码

node --version  # 应显示 v18.x.x 或更高
npm --version   # 应显示 9.x.x 或更高

📥 安装步骤

方法一：离线部署（推荐）

使用预打包的离线部署包，无需 Git 克隆。

1. 下载离线部署包

下载 pixel-snake-offline-v1.0.0.tar.gz 压缩包。
压缩包下载

2. 解压压缩包

Bash 复制代码

tar -xzf pixel-snake-offline-v1.0.0.tar.gz
cd pixel-snake-package

3. 安装依赖

Bash 复制代码

# 如果未安装 pnpm，先全局安装
npm install -g pnpm

# 安装项目依赖
pnpm install

4. 查看离线部署说明

Bash 复制代码

cat OFFLINE_INSTALL.md

方法二：使用 Git 克隆

1. 克隆项目

Bash 复制代码

git clone <your-repository-url>
cd pixel-snake

2. 安装依赖

Bash 复制代码

# 安装 pnpm
npm install -g pnpm

# 安装项目依赖
pnpm install

🚀 开发模式运行

开发模式支持热更新，适合开发和测试。

启动开发服务器

Bash 复制代码

pnpm dev

后台运行

Bash 复制代码

nohup pnpm dev > dev.log 2>&1 &

查看日志：

Bash 复制代码

tail -f dev.log

访问游戏

Plain 复制代码

http://localhost:5000

或使用服务器 IP：

Plain 复制代码

http://your-server-ip:5000

停止服务

Bash 复制代码

# 查找进程
ps aux | grep "pnpm dev"

# 结束进程（假设 PID 是 12345）
kill 12345

🏭 生产环境部署

方法一：直接运行

1. 构建项目

Bash 复制代码

pnpm build

2. 启动生产服务器

Bash 复制代码

pnpm start

3. 后台运行

Bash 复制代码

nohup pnpm start > production.log 2>&1 &

方法二：使用 PM2（推荐）

PM2 是一个强大的进程管理器，适合生产环境。

1. 安装 PM2

Bash 复制代码

npm install -g pm2

2. 创建 ecosystem 配置文件

创建 ecosystem.config.js：

JavaScript 复制代码

module.exports = {
  apps: [{
    name: 'pixel-snake',
    script: 'node_modules/next/dist/bin/next',
    args: 'start',
    cwd: '/path/to/pixel-snake',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      PORT: 5000
    }
  }]
};

3. 构建并启动

Bash 复制代码

pnpm build
pm2 start ecosystem.config.js

4. PM2 常用命令

Bash 复制代码

# 查看应用状态
pm2 status

# 查看日志
pm2 logs pixel-snake

# 重启应用
pm2 restart pixel-snake

# 停止应用
pm2 stop pixel-snake

# 删除应用
pm2 delete pixel-snake

# 清空日志
pm2 flush

# 监控
pm2 monit

5. 设置开机自启

Bash 复制代码

# 保存当前进程列表
pm2 save

# 生成开机启动脚本
pm2 startup

执行输出的命令，例如：

Bash 复制代码

sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u yourusername --hp /home/yourusername

方法三：使用 Systemd（系统服务）

1. 创建服务文件

Bash 复制代码

sudo nano /etc/systemd/system/pixel-snake.service

2. 添加以下内容

TOML 复制代码

[Unit]
Description=Pixel Snake Game
After=network.target

[Service]
Type=simple
User=yourusername
WorkingDirectory=/path/to/pixel-snake
ExecStart=/usr/bin/node node_modules/next/dist/bin/next start
Restart=on-failure
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=pixel-snake
Environment=NODE_ENV=production
Environment=PORT=5000

[Install]
WantedBy=multi-user.target

替换 yourusername 和 /path/to/pixel-snake 为实际值。

3. 启动服务

Bash 复制代码

# 重新加载 systemd
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start pixel-snake

# 设置开机自启
sudo systemctl enable pixel-snake

# 查看状态
sudo systemctl status pixel-snake

4. 管理服务

Bash 复制代码

# 停止服务
sudo systemctl stop pixel-snake

# 重启服务
sudo systemctl restart pixel-snake

# 查看日志
sudo journalctl -u pixel-snake -f

🌐 Nginx 反向代理

使用 Nginx 作为反向代理，提供更好的性能和安全性。

安装 Nginx

Ubuntu/Debian

Bash 复制代码

sudo apt update
sudo apt install nginx

CentOS/RHEL

Bash 复制代码

sudo yum install nginx

配置 Nginx

1. 创建配置文件

Bash 复制代码

sudo nano /etc/nginx/sites-available/pixel-snake

2. 添加配置

Nginx 复制代码

server {
    listen 80;
    server_name your-domain.com;

    # 访问日志和错误日志
    access_log /var/log/nginx/pixel-snake-access.log;
    error_log /var/log/nginx/pixel-snake-error.log;

    # 最大上传大小
    client_max_body_size 10M;

    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        
        # WebSocket 支持
        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;
        
        # 超时配置
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # 静态资源缓存
    location /_next/static {
        proxy_pass http://localhost:5000;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

替换 your-domain.com 为你的域名或服务器 IP。

3. 启用配置

Bash 复制代码

# 创建软链接
sudo ln -s /etc/nginx/sites-available/pixel-snake /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重启 Nginx
sudo systemctl restart nginx

配置 HTTPS（使用 Let's Encrypt）

1. 安装 Certbot

Bash 复制代码

sudo apt install certbot python3-certbot-nginx

2. 获取证书

Bash 复制代码

sudo certbot --nginx -d your-domain.com

3. 自动续期

Certbot 会自动设置自动续期，也可以手动测试：

Bash 复制代码

sudo certbot renew --dry-run

🔥 防火墙配置

Ubuntu/Debian (UFW)

Bash 复制代码

# 允许 SSH
sudo ufw allow 22/tcp

# 允许 HTTP
sudo ufw allow 80/tcp

# 允许 HTTPS
sudo ufw allow 443/tcp

# 启用防火墙
sudo ufw enable

# 查看状态
sudo ufw status

CentOS/RHEL (Firewalld)

Bash 复制代码

# 允许 HTTP
sudo firewall-cmd --permanent --add-service=http

# 允许 HTTPS
sudo firewall-cmd --permanent --add-service=https

# 重载防火墙
sudo firewall-cmd --reload

# 查看状态
sudo firewall-cmd --list-all

🐳 Docker 部署

1. 创建 Dockerfile

Dockerfile 复制代码

# 构建阶段
FROM node:18-alpine AS builder

WORKDIR /app

COPY package.json pnpm-lock.yaml ./

RUN npm install -g pnpm
RUN pnpm install --frozen-lockfile

COPY . .

RUN pnpm build

# 生产阶段
FROM node:18-alpine AS runner

WORKDIR /app

ENV NODE_ENV production

COPY --from=builder /app/package.json ./
COPY --from=builder /app/pnpm-lock.yaml ./
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/public ./public

EXPOSE 5000

CMD ["node_modules/next/dist/bin/next", "start"]

2. 创建 docker-compose.yml

YAML 复制代码

version: '3.8'

services:
  pixel-snake:
    build: .
    ports:
      - "5000:5000"
    environment:
      - NODE_ENV=production
      - PORT=5000
    restart: unless-stopped

3. 构建并运行

Bash 复制代码

# 构建镜像
docker-compose build

# 启动容器
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止容器
docker-compose down

4. 使用 Nginx 容器

YAML 复制代码

version: '3.8'

services:
  pixel-snake:
    build: .
    expose:
      - "5000"
    environment:
      - NODE_ENV=production
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - pixel-snake
    restart: unless-stopped

📊 性能优化

1. 启用 Gzip 压缩

在 next.config.ts 中添加：

TypeScript 复制代码

const nextConfig = {
  compress: true,
};

export default nextConfig;

2. 配置 CDN

将静态资源上传到 CDN，如 Cloudflare、阿里云 CDN 等。

3. Nginx 缓存配置

在 Nginx 配置中添加：

Nginx 复制代码

# 在 http 块中添加
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m 
                 max_size=10g inactive=60m use_temp_path=off;

# 在 location 块中添加
location / {
    proxy_cache my_cache;
    proxy_cache_valid 200 60m;
    proxy_cache_valid 404 1m;
    proxy_cache_bypass $http_upgrade;
    ...
}

🔒 安全建议

使用防火墙限制访问
配置 HTTPS加密传输
定期更新系统和依赖包
使用强密码保护服务器
禁用 root 登录
配置 fail2ban防止暴力破解
定期备份重要数据

🐛 常见问题

Q1: 端口 5000 被占用？

Bash 复制代码

# 查找占用端口的进程
sudo lsof -i :5000

# 或使用 netstat
sudo netstat -tulpn | grep :5000

# 结束进程（假设 PID 是 1234）
sudo kill 1234

Q2: npm install 失败？

Bash 复制代码

# 清除缓存
npm cache clean --force

# 删除 node_modules
rm -rf node_modules pnpm-lock.yaml

# 重新安装
pnpm install

Q3: 构建失败，内存不足？

Bash 复制代码

# 增加交换空间
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Q4: PM2 应用自动重启？

查看日志找出原因：

Bash 复制代码

pm2 logs pixel-snake --lines 100

常见原因：

内存溢出
未捕获的异常

端口冲突

Q5: Nginx 502 错误？

检查后端服务是否运行：

Bash 复制代码

curl http://localhost:5000

如果后端未运行，启动服务。

Q6: 无法访问服务器？

检查防火墙和安全组设置：

Bash 复制代码

# 检查防火墙
sudo ufw status

# 检查端口是否监听
sudo netstat -tulpn | grep :5000

📈 监控和日志

使用 PM2 监控

Bash 复制代码

# 实时监控
pm2 monit

# 查看详细信息
pm2 show pixel-snake

日志管理

Bash 复制代码

# 查看实时日志
pm2 logs pixel-snake --lines 100

# 清空日志
pm2 flush

# 导出日志
pm2 install pm2-logrotate

系统监控

Bash 复制代码

# 查看系统资源
htop

# 查看磁盘使用
df -h

# 查看内存使用
free -m

🔄 更新部署

使用 Git 更新

Bash 复制代码

# 拉取最新代码
git pull origin main

# 安装新依赖
pnpm install

# 重新构建
pnpm build

# 重启服务
pm2 restart pixel-snake