树莓派部署私有游戏服务器：从零搭建Pretend You‘re Xyzzy

1. 项目概述与核心价值

如果你和我一样，喜欢和朋友在线玩一些轻松有趣的派对游戏，但又对公共服务器的稳定性、自定义内容或者隐私有所顾虑，那么搭建一个属于自己的游戏服务器会是个绝佳的选择。今天要聊的，就是在树莓派上部署一个完全私有的“Pretend You're Xyzzy”（以下简称PYX）游戏服务器。PYX是一款开源的、基于网页的卡牌游戏，你可以把它理解为线上版的“反人类卡牌”（Cards Against Humanity），玩法幽默诙谐，非常适合朋友间聚会娱乐。

选择树莓派作为服务器硬件，核心优势在于它的“全天候待命”特性。这个小巧的设备功耗极低，常年开机电费几乎可以忽略不计，而且非常安静，你可以把它塞在路由器旁边或者任何一个角落，让它7x24小时默默提供服务。相比使用个人电脑临时开服，或者租用云服务器，树莓派方案在长期成本、可控性和隐私性上都有明显优势。整个过程涉及Linux系统操作、网络配置、Java环境搭建以及服务自动化，是一次非常典型的嵌入式应用部署实践，无论你是想拥有一个永不掉线的游戏房间，还是希望学习服务端应用的部署流程，这个项目都能给你带来实实在在的收获。

2. 硬件与软件准备清单

在开始动手之前，我们需要把“食材”和“厨具”准备好。这个环节看似基础，但准备得当能避免后续很多不必要的麻烦。

2.1 硬件选择与考量

首先是最关键的硬件——树莓派。根据我的实测经验，树莓派3B+和树莓派4B（2GB或4GB内存版本）是完美选择。它们的处理器性能足够流畅运行PYX的Java服务，内存也绰绰有余。我手头一台树莓派4B 4GB，在运行PYX服务器时，内存占用长期维持在500MB以下，CPU负载也很低，完全是大材小用。

这里有一个重要的避坑点：尽量避免使用树莓派Zero W。虽然理论上可行，但Zero W的ARMv6架构单核处理器和512MB内存，在运行Java虚拟机（JVM）时非常吃力。社区有用户通过移除旧版JRE、安装特定的OpenJDK 8精简版才勉强跑起来，过程繁琐且运行不稳定，容易在游戏进行中卡顿或崩溃，影响体验。对于希望获得稳定服务的朋友，直接从树莓派3或4起步是更明智的选择。

其他硬件包括：

• Micro SD卡：推荐容量至少8GB，Class 10或UHS-I以上速度。我习惯用32GB的卡，并不是PYX需要这么大空间（它本身很小），而是为系统日志、未来可能安装的其他服务留出余地。一个快速的SD卡能显著提升系统响应和服务的启动速度。
• 电源适配器：务必使用官方推荐或质量可靠的5V/3A电源（树莓派4尤其需要）。供电不足会导致树莓派运行不稳定，表现为随机重启或SD卡损坏，这是很多奇怪问题的根源。
• 网络连接：优先使用网线（以太网）连接。有线网络比Wi-Fi更稳定，延迟更低，对于游戏服务器至关重要。如果只能使用Wi-Fi，请确保信号强度良好。
• 散热方案：树莓派4运行时发热量较大，建议配备一个小型散热片或风扇外壳。长期高温运行会触发CPU降频，影响性能，甚至缩短硬件寿命。

2.2 软件与工具准备

软件方面，我们需要准备系统镜像和几个必要的工具：

1. Raspberry Pi OS（原Raspbian）镜像：访问树莓派官网下载页面，选择“Raspberry Pi OS Lite”（无桌面版）即可。Lite版本没有图形界面，资源占用更少，更适合作为纯服务器运行。下载后得到一个.img文件。
2. SD卡烧录工具：在Windows上，我常用Raspberry Pi Imager（树莓派官方工具）或BalenaEtcher。它们界面友好，自动验证烧录结果，比老牌的Win32 Disk Imager更省心。如果你用macOS或Linux，BalenaEtcher是跨平台的好选择。
3. SSH客户端：用于远程连接树莓派。Windows用户可以使用PuTTY，或者Windows 10/11自带的PowerShell/终端（支持SSH命令）。macOS和Linux用户直接使用系统终端即可。

注意：在烧录系统前，建议先对SD卡进行全盘格式化，而不是快速格式化。可以使用SD卡协会官方的格式化工具，确保卡上没有任何残留的分区表错误，这能最大程度避免系统安装后出现无法启动的玄学问题。

3. 系统初始化与网络配置

拿到烧录好系统的SD卡，我们的树莓派还只是一个“裸机”。接下来要通过“无头模式”（Headless）完成初始设置，即不连接显示器键盘，直接通过网络进行配置。

3.1 启用SSH与配置Wi-Fi（无头启动关键）

将烧录好的SD卡重新插入电脑。你会看到一个名为boot的盘符（在Linux下是挂载点）。这个分区是FAT32格式，用于存放启动引导文件。我们需要在这里创建两个文件：

1. 启用SSH服务：在boot分区根目录下，新建一个名为ssh的空文件（注意没有后缀名）。在Windows下，你可以打开记事本，不输入任何内容，然后选择“另存为”，在保存类型中选择“所有文件”，文件名输入ssh即可。这个文件的存在会告诉树莓派系统在第一次启动时自动开启SSH服务。
2. 预配置Wi-Fi：如果你使用Wi-Fi连接，需要在boot分区根目录下创建另一个文件：wpa_supplicant.conf。用文本编辑器打开，输入以下内容，并替换你的Wi-Fi信息：

country=CN ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev update_config=1 network={ ssid="你的Wi-Fi名称" psk="你的Wi-Fi密码" key_mgmt=WPA-PSK }

这里有几个细节：

• country=CN：设置国家代码为中国，这会影响可用的Wi-Fi信道。
• key_mgmt=WPA-PSK：指定加密方式为WPA/WPA2个人版，这是目前家庭网络最通用的。
• 请确保你的Wi-Fi名称（SSID）和密码正确，并且密码包含在双引号内。

完成以上两步后，安全弹出SD卡，将其插入树莓派，接通电源。等待约1-2分钟，让系统完成首次扩展文件系统等初始化操作。

3.2 首次连接与基础安全设置

现在需要找到树莓派的IP地址。有多种方法：

• 路由器后台查看：登录你家路由器的管理界面（通常是192.168.1.1或192.168.0.1），在“已连接设备”或“DHCP客户端列表”中查找名为raspberrypi的设备及其IP地址。这是最直接的方法。
• 使用网络扫描工具：在电脑上使用Advanced IP Scanner或Angry IP Scanner等工具，扫描你的局域网段。
• 使用mDNS名称：如果你的网络支持mDNS（大多数现代系统都支持），你可以直接使用raspberrypi.local这个主机名进行连接。在终端里ping raspberrypi.local试试。

获得IP地址后，打开SSH客户端（如PuTTY），输入树莓派的IP地址，端口22，连接类型SSH。首次连接会弹出安全警告，点击“是”接受密钥即可。

登录默认凭证为：

• 用户名：pi
• 密码：raspberry

登录后第一件事，务必修改默认密码！在终端中输入passwd，然后按照提示设置一个强密码。这是将设备暴露在网络上最基本的安全措施。

接下来，建议更新系统软件包并设置时区：

# 更新软件包列表 sudo apt update # 升级所有已安装的软件包（可选，但推荐） sudo apt upgrade -y # 设置时区为亚洲/上海 sudo timedatectl set-timezone Asia/Shanghai # 可选：更改主机名，方便识别，比如改为`pyx-server` sudo raspi-config # 在raspi-config界面中，选择`System Options` -> `Hostname`，进行修改��然后重启生效。

4. 核心服务环境部署

PYX服务器是一个Java Web应用，它使用Maven进行构建，并内嵌了Jetty作为Web服务器。因此，我们需要在树莓派上搭建Java和Maven环境。

4.1 安装Java运行环境

树莓派OS的软件源中提供了OpenJDK，这是开源且兼容性良好的Java实现。PYX项目推荐使用Java 8，但经过测试，较新的Java 11 LTS版本兼容性更好，资源管理也更优。

# 安装OpenJDK 11（包含JRE和JDK） sudo apt install -y openjdk-11-jdk-headless # 安装完成后验证版本 java -version # 输出应类似：openjdk version "11.0.xx" ...

安装headless版本意味着不包含图形界面相关的库，对于服务器环境来说更精简，占用空间更小。如果你执行java -version看到版本信息，说明安装成功。

4.2 安装Git与Maven

Git用于从代码仓库拉取PYX的源代码，Maven则是Java项目的标准构建工具。

# 安装Git版本控制工具 sudo apt install -y git # 安装Maven项目管理和构建工具 sudo apt install -y maven # 验证Maven安装 mvn -version

Maven安装过程可能会稍长一些，因为它会下载一些基础组件。安装完成后，mvn -version会显示Maven和Java的版本信息。

4.3 获取PYX服务器源代码

所有准备工作就绪，现在可以获取游戏服务器本体了。PYX是一个开源项目，托管在GitHub上。

# 切换到用户主目录 cd ~ # 克隆PretendYoureXyzzy仓库 git clone https://github.com/ajanata/PretendYoureXyzzy.git # 进入项目目录 cd PretendYoureXyzzy

git clone命令会将项目所有的源代码、配置文件和历史版本下载到本地的PretendYoureXyzzy目录中。国内访问GitHub有时可能较慢，如果克隆失败，可以尝试多执行几次，或者检查网络连接。

5. 针对树莓派的专项配置修改

这是让PYX服务器能在树莓派（ARM架构）上正常运行的核心步骤。原始代码库中的某些依赖库版本对ARM平台支持不佳，需要我们手动调整。

5.1 修改数据库驱动版本（关键步骤）

PYX使用SQLite作为内置数据库来存储游戏数据、用户信息等。它通过一个叫sqlite-jdbc的Java驱动来操作SQLite。项目默认引用的某个旧版本驱动在ARM平台上存在兼容性问题，会导致服务器启动失败。

我们需要修改项目对象模型文件pom.xml，这是Maven的核心配置文件。

# 使用nano编辑器打开pom.xml文件 sudo nano pom.xml

在nano编辑器中，使用方向键向下翻页，或者按Ctrl+W然后输入sqlite-jdbc进行搜索。找到如下代码块：

<dependency> <groupId>org.xerial</groupId> <artifactId>sqlite-jdbc</artifactId> <version>3.34.0</version> <!-- 这个版本号可能不同 --> </dependency>

你需要将<version>标签内的版本号修改为3.28.0。这是经过社区验证，在树莓派上稳定工作的版本。修改后应为：

<version>3.28.0</version>

修改完成后，按Ctrl+O（写入），回车确认文件名，再按Ctrl+X退出nano。

为什么是3.28.0？新版本的sqlite-jdbc驱动有时会包含针对x86_64架构的本地优化库（.so文件），而这些预编译的库在ARM架构的树莓派上无法加载。版本3.28.0是一个相对稳定且被确认在ARM上兼容性良好的发布版。如果未来你发现这个版本也有问题，可以尝试在GitHub的sqlite-jdbc仓库的Issues中搜索“ARM”或“Raspberry Pi”寻找其他可用的版本号。

5.2 配置数据库连接属性（可选但推荐）

接下来，我们需要复制一份数据库配置模板，并可以按需修改。

# 进入项目根目录（如果不在的话） cd ~/PretendYoureXyzzy # 复制配置文件模板 cp build.properties.example build.properties # 编辑配置文件 sudo nano build.properties

这个文件里主要配置了Hibernate（一个数据库ORM框架）的连接参数。默认使用HSQLDB内存数据库，这对于测试是OK的。但如果你希望游戏数据（如自定义卡包、用户分数）在服务器重启后能保留，可以考虑将其指向一个SQLite文件数据库。不过，PYX默认的HSQLDB配置对于轻量级使用完全足够，且性能更好。我们主要关注以下两行，修改默认的弱密码：

hibernate.connection.username=sa hibernate.connection.password= （一个空密码）

建议将密码改为一个复杂的字符串，即使这只是本地数据库。修改后保存退出。

6. 构建、运行与测试

配置完成后，激动人心的时刻到了——第一次启动我们的服务器。

6.1 首次构建与启动

在项目目录下，执行Maven命令来编译项目、打包并启动内嵌的Jetty服务器。

cd ~/PretendYoureXyzzy mvn clean package war:exploded jetty:run -Dmaven.buildNumber.doCheck=false -Dmaven.buildNumber.doUpdate=false

这个命令做了以下几件事：

• clean：清理之前构建的旧文件。
• package：编译源代码并打包成WAR文件。
• war:exploded：将WAR包解压成展开形式，便于Jetty直接运行。
• jetty:run：启动内嵌的Jetty Web服务器。
• 两个-D参数：用于跳过项目版本号的检查和更新，避免因网络问题导致构建失败。

第一次执行会非常耗时（可能10-20分钟），因为Maven需要从中央仓库下载大量的依赖库（JAR包）到本地。树莓派的处理器和网络速度会影响这个过程，请耐心等待。你会看到屏幕上飞速滚过大量的下载和编译信息。

当最终看到类似下面的输出时，说明启动成功了：

[INFO] Started ServerConnector@xxxxxxxx{HTTP/1.1,[http/1.1]}{0.0.0.0:8080} [INFO] Started @xxxxxxms [INFO] Started Jetty Server [INFO] Console reloading is ENABLED. Hit ENTER on the console to restart the context.

最关键的一行是{0.0.0.0:8080}，它表示服务器正在监听所有网络接口的8080端口。

6.2 访问测试与功能验证

现在，打开你局域网内的任何一台电脑或手机的浏览器。在地址栏输入：

http://你的树莓派IP地址:8080

例如：http://192.168.1.100:8080

你应该能看到Pretend You‘re Xyzzy的欢迎页面。你可以尝试：

1. 创建游戏：点击“Create Game”，设置游戏名称、密码（可选）、卡包等。
2. 加入游戏：在另一台设备上访问同一地址，应该能看到创建的游戏房间并加入。
3. 进行一轮游戏：体验发卡、出牌、评选等完整流程。

如果页面无法打开，请按顺序排查：

1. 检查服务器进程：在树莓派终端里，确认Maven命令仍在运行，没有报错退出。
2. 检查防火墙：树莓派OS Lite默认没有启用防火墙（ufw）。如果你手动启用过，需要放行8080端口：sudo ufw allow 8080。
3. 检查IP地址：确认你输入的IP地址正确。可以在树莓派终端用hostname -I命令查看。
4. 检查网络连通性：从你的电脑ping一下树莓派的IP，确保网络层是通的。

7. 实现开机自启动服务

目前服务器是运行在前台的，一旦关闭SSH窗口，进程就会终止。我们需要将其配置为系统服务，实现开机自启和后台运行。

7.1 创建系统服务单元文件（推荐方法）

相比使用crontab的@reboot，使用systemd服务是更现代、更专业的管理方式。它能更好地管理进程的生命周期、日志和依赖关系。

首先，创建一个服务配置文件：

sudo nano /etc/systemd/system/pretend-xyzzy.service

将以下内容粘贴进去，请根据你的实际路径修改WorkingDirectory和ExecStart：

[Unit] Description=Pretend You're Xyzzy Game Server After=network.target [Service] Type=simple User=pi WorkingDirectory=/home/pi/PretendYoureXyzzy ExecStart=/usr/bin/mvn jetty:run -Dmaven.buildNumber.doCheck=false -Dmaven.buildNumber.doUpdate=false Restart=on-failure RestartSec=10 StandardOutput=journal StandardError=journal [Install] WantedBy=multi-user.target

关键参数解析：

• User=pi：以pi用户身份运行服务，避免权限问题。
• WorkingDirectory：指定命令执行的工作目录，必须指向项目根目录。
• ExecStart：这里我们不再使用clean package，因为依赖已经下载，代码也已编译。直接使用mvn jetty:run可以极大加快启动速度（从几分钟缩短到几十秒）。
• Restart=on-failure：当进程异常退出时自动重启。
• RestartSec=10：重启前等待10秒，避免频繁重启循环。

保存退出后，执行以下命令启用服务：

# 重新加载systemd配置，使新服务文件生效 sudo systemctl daemon-reload # 启用服务，使其在开机时自动启动 sudo systemctl enable pretend-xyzzy.service # 立即启动服务 sudo systemctl start pretend-xyzzy.service # 查看服务状态和日志，确认运行正常 sudo systemctl status pretend-xyzzy.service # 持续查看日志（按Ctrl+C退出） sudo journalctl -u pretend-xyzzy.service -f

如果状态显示active (running)，并且日志中没有明显的错误信息，说明服务已成功在后台运行。

7.2 管理服务常用命令

配置为服务后，管理起来就非常方便了：

# 启动服务 sudo systemctl start pretend-xyzzy.service # 停止服务 sudo systemctl stop pretend-xyzzy.service # 重启服务（修改配置后常用） sudo systemctl restart pretend-xyzzy.service # 查看服务实时状态 sudo systemctl status pretend-xyzzy.service # 禁用开机自启 sudo systemctl disable pretend-xyzzy.service

8. 进阶配置与优化

基础服务跑起来后，我们可以进行一些优化和个性化设置，让服务器更稳定、更好用。

8.1 配置反向代理与域名访问（可选）

直接通过IP和端口号访问不够友好，且HTTP连接不够安全。我们可以利用家庭路由器或树莓派本机安装的Nginx，实现反向代理和HTTPS。

方案A：在树莓派上安装Nginx（如果树莓派性能充足）

# 安装Nginx sudo apt install -y nginx # 创建PYX的Nginx配置文件 sudo nano /etc/nginx/sites-available/pretend-xyzzy

写入以下配置，假设你想用pyx.yourhome.com访问（需要在路由器或本地hosts文件做DNS解析）：

server { listen 80; server_name pyx.yourhome.com; # 替换为你的域名或局域网IP location / { proxy_pass http://127.0.0.1:8080; 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; } }

然后启用该配置并重启Nginx：

sudo ln -s /etc/nginx/sites-available/pretend-xyzzy /etc/nginx/sites-enabled/ sudo nginx -t # 测试配置语法 sudo systemctl restart nginx

现在，你就可以通过http://pyx.yourhome.com（或树莓派局域网IP）直接访问PYX服务器，无需输入端口号。

方案B：在家庭路由器上配置端口转发与DDNS如果你希望从外网访问，需要在路由器上设置端口转发（Port Forwarding），将公网IP的某个端口（如8080）转发到树莓派的内网IP的8080端口。请注意，将家庭网络服务暴露到公网存在安全风险，务必确保树莓派系统密码强壮，并考虑定期更新。

由于家庭宽带公网IP通常是动态的，会变化，可以搭配使用动态DNS（DDNS）服务，如花生壳（Oray）或DynDNS，获得一个固定的域名。

8.2 服务器维护与监控

服务器长期运行，需要一些基本的维护：

• 查看资源占用：使用htop命令可以直观地看到CPU、内存占用和进程情况。安装：sudo apt install htop。
• 查看服务日志：如前所述，sudo journalctl -u pretend-xyzzy.service -f可以跟踪服务日志。-f参数表示持续输出。
• 定期更新系统：每月执行一次sudo apt update && sudo apt upgrade -y，保持系统安全补丁最新。
• 备份自定义卡组：如果你上传了自定义卡包，其文件通常位于项目目录下的web/子目录或数据库文件中。定期备份整个PretendYoureXyzzy目录是个好习惯。

8.3 性能调优与问题排查实录

在实际运行中，你可能会遇到以下情况及解决方法：

问题1：服务器启动后，玩家连接卡顿或频繁断开。

• 排查：首先在树莓派上运行htop，观察CPU和内存使用率。PYX服务器本身不耗资源，但如果同时运行了其他服务（如桌面环境、Nginx、MySQL等），可能导致资源紧张。
• 解决：确保树莓派有良好的散热，避免CPU因过热降频。如果内存不足，可以考虑为树莓派增加交换空间（Swap），但注意SD卡频繁交换会降低寿命。最根本的还是升级到内存更大的树莓派4。

问题2：Maven构建时卡在下载某个依赖（Downloading...）。

• 原因：网络连接至Maven中央仓库速度慢或不稳定。
• 解决：
  1. 更换为国内镜像源。编辑Maven的全局配置文件（/etc/maven/settings.xml或~/.m2/settings.xml），在<mirrors>部分添加阿里云镜像：

     <mirror> <id>alimaven</id> <name>aliyun maven</name> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>central</mirrorOf> </mirror>

  2. 如果第一次构建失败，可以多次重试mvn clean package ...命令，Maven会续传未完成的下载。

问题3：服务（systemd）启动失败，状态为failed。

• 排查：使用sudo journalctl -u pretend-xyzzy.service -xe查看详细的错误日志。
• 常见原因及解决：
  • WorkingDirectory路径错误：检查/home/pi/PretendYoureXyzzy目录是否存在，且pi用户有读取权限。
  • Java环境问题：确认java -version和mvn -version命令能正确执行。有时需要显式设置JAVA_HOME环境变量。
  • 端口占用：8080端口可能被其他程序占用。可以用sudo netstat -tlnp | grep :8080查看。如果被占用，可以修改PYX的监听端口（需修改项目源码配置，较复杂），或者停止占用端口的程序。

问题4：如何更新PYX服务器到新版本？PYX项目仍在GitHub上维护，可能会有功能更新或Bug修复。

# 进入项目目录 cd ~/PretendYoureXyzzy # 停止当前服务 sudo systemctl stop pretend-xyzzy.service # 备份当前版本（可选） cp -r PretendYoureXyzzy PretendYoureXyzzy_backup_$(date +%Y%m%d) # 拉取最新代码（如果本地有修改，请谨慎，可能会被覆盖） git pull origin master # 重新构建（因为代码可能更新了依赖） mvn clean package -Dmaven.buildNumber.doCheck=false -Dmaven.buildNumber.doUpdate=false # 重启服务 sudo systemctl restart pretend-xyzzy.service

注意：更新前务必阅读GitHub仓库的Release Notes，确认没有不兼容的更改。git pull会覆盖本地修改，如果你修改过pom.xml以外的源码文件，需要做好合并或备份。

经过以上步骤，你已经拥有了一个部署在树莓派上、开机自启、稳定运行的私有Pretend You‘re Xyzzy游戏服务器。它不仅是一个随时可用的游戏平台，更是一个深入了解Linux服务部署、网络配置和问题排查的实践案例。你可以将这套方法举一反三，用于部署其他基于Java、Python或Node.js的轻量级网络应用，真正把树莓派变成家庭网络中的多功能服务器。