GameServerManager/ARM64-启动指南.md

GameServerManager ARM64 启动指南

本指南介绍如何在 ARM64 架构或通过 QEMU 模拟环境中启动 GameServerManager 开发环境。

🚀 快速开始

首次使用

# 一键安装依赖并启动双终端开发环境
./start-arm64.sh

日常开发

# 直接启动开发环境（假设依赖已安装）
./dev-arm64.sh

📋 所有启动选项

1. 主启动脚本 (start-arm64.sh)

./start-arm64.sh                # 安装依赖 + 双终端启动
./start-arm64.sh install        # 仅安装依赖
./start-arm64.sh dev-dual       # 双终端启动（推荐）
./start-arm64.sh dev-simple     # 后台启动
./start-arm64.sh dev            # 并发启动
./start-arm64.sh help           # 显示帮助

2. 快速开发脚本 (dev-arm64.sh)

./dev-arm64.sh                  # 直接启动双终端开发环境

3. 详细脚本 (scripts/arm/setup-and-run.sh)

./scripts/arm/setup-and-run.sh [选项]

4. 独立启动脚本

./scripts/arm/start-dev-dual-terminal.sh    # 双终端模式
./scripts/arm/start-dev-simple.sh           # 后台模式

🎯 启动模式对比

模式	脚本	优点	缺点	适用场景
双终端	dev-dual	实时输出，易调试	需要图形界面	日常开发（推荐）
后台	dev-simple	不占用终端	看不到实时输出	后台运行
并发	dev	单终端显示	输出混合	简单测试

🔧 环境要求

系统依赖

# 安装 QEMU 用户模式模拟器
sudo apt-get install qemu-user-static

# 安装 ARM64 交叉编译库
sudo apt-get install libc6-dev-arm64-cross

ARM64 Node.js

确保 ARM64 版本的 Node.js v20.19.0 已安装到：

/home/xiaozhu/qemu/Node/node-v20.19.0-linux-arm64/

🌐 访问地址

启动成功后，可通过以下地址访问：

• 前端（客户端）: http://localhost:5173
• 后端（API）: http://localhost:3000

🛠️ 故障排除

1. 终端未打开

• 确保系统安装了图形界面和终端模拟器
• 支持的终端：gnome-terminal, konsole, xfce4-terminal, xterm, terminator

2. 权限问题

chmod +x *.sh scripts/arm/*.sh

3. 依赖未安装

./start-arm64.sh install

4. 端口被占用

# 检查端口占用
lsof -i :3000
lsof -i :5173

# 停止相关进程
pkill -f "node.*tsx.*src/index.ts"
pkill -f "vite"

5. 查看日志（后台模式）

tail -f /tmp/gsm-server.log    # 服务端日志
tail -f /tmp/gsm-client.log    # 客户端日志

📝 开发工作流

1. 首次设置

   ./start-arm64.sh
   

2. 日常开发

   ./dev-arm64.sh
   

3. 代码修改

   • 前端代码修改会自动热重载
   • 后端代码修改会自动重启服务

4. 停止服务

   • 双终端模式：在对应终端按 Ctrl+C
   • 后台模式：运行清理命令或重启脚本

5. 重新启动

   ./dev-arm64.sh
   

🎉 成功标志

启动成功后，您应该看到：

1. 双终端模式：

   • 两个独立的终端窗口
   • 服务端终端显示后端日志
   • 客户端终端显示 Vite 开发服务器信息

2. 浏览器访问：

   • http://localhost:5173 显示前端界面
   • http://localhost:3000 可访问 API

3. 热重载：

   • 修改前端代码，浏览器自动刷新
   • 修改后端代码，服务自动重启

📚 相关文档

• scripts/arm/README.md - ARM64 脚本详细说明
• README.md - 项目主文档
• docs/开发说明.md - 开发指南