游戏服务器容器化实战：基于Archon的标准化部署与运维

1. 项目概述：当游戏服务器遇上容器化

如果你是一名游戏开发者，或者对搭建和维护游戏服务器感兴趣，那么你一定对“开服”这件事的复杂性深有体会。从依赖库的版本冲突，到不同游戏服务端对操作系统环境的苛刻要求，再到服务器迁移时那令人头疼的配置重现过程，每一个环节都可能成为压垮骆驼的稻草。而SufficientDaikon/archon这个项目，正是瞄准了游戏服务器部署与管理中的这些痛点，试图用一套标准化的容器化方案来“一劳永逸”地解决它们。

简单来说，archon是一个专门为游戏服务器设计的容器化运行环境与编排工具集。它的核心目标，是将五花八门的游戏服务端（比如《我的世界》、《泰拉瑞亚》、《CS: Source》等）打包成统一的、可移植的容器镜像，然后通过一套管理工具，实现这些容器的快速部署、启停、监控和资源调度。你可以把它理解为一个“游戏服务器领域的 Docker + Kubernetes”，但更垂直、更聚焦于游戏服务端的特殊需求。

这个项目适合谁呢？首先，是那些需要为玩家社区提供稳定、可扩展游戏服务器的社区管理员或服主。其次，是游戏开发团队，在内部测试、压力测试或搭建演示环境时，需要快速复制和销毁多个一致的服务器实例。最后，对于任何对 DevOps、容器技术和游戏后端架构感兴趣的开发者来说，archon都是一个绝佳的学习和实战案例，它展示了如何将成熟的云原生技术栈，巧妙地适配到一个非常具体的垂直领域。

2. 核心设计理念与架构拆解

2.1 为什么是容器化？游戏服务器的特殊性

在深入archon的细节之前，我们必须先理解它选择容器化这条路的根本原因。传统的游戏服务器部署，通常是在一台物理机或虚拟机上，手动安装 Java、.NET Runtime、各种动态链接库，然后上传服务端文件，修改一堆配置文件（server.properties,server.cfg等），最后启动进程。这种方式存在几个致命问题：

1. 环境依赖地狱：游戏A需要glibc 2.28，游戏B需要glibc 2.17，在同一台机器上共存几乎不可能。
2. 配置漂移与不可重现：服务器运行一段时间后，手动修改了某个配置，但没有记录，导致新部署的服务器行为不一致。
3. 资源隔离性差：一个服务器的内存泄漏或CPU爆满，可能拖垮同主机上的所有其他服务器。
4. 扩缩容缓慢：当玩家涌入需要开新服时，从头准备一台新服务器可能需要数十分钟甚至数小时。

容器技术，特别是 Docker，通过将应用及其所有依赖打包到一个独立的、轻量级的“箱子”里，完美地解决了前三个问题。每个游戏服务器运行在自己的容器中，拥有独立的文件系统、网络命名空间和资源限制，互不干扰。而archon在此基础上更进一步，它不仅要解决“如何跑起来”的问题，更要解决“如何方便地管理成百上千个这样的容器”的问题，这就是编排系统的价值。

2.2 Archon 的架构分层

archon的架构可以清晰地分为三层，这有助于我们理解它的各个组件是如何协同工作的。

第一层：容器运行时与镜像层这是最底层的基础。archon重度依赖 Docker 或 containerd 作为容器运行时。它的核心贡献之一，是提供了一套构建游戏服务器容器镜像的标准方法和基础镜像。例如，它会为基于 Java 的游戏（如 Minecraft）提供一个已优化 JVM 参数的基础镜像；为基于 Source 引擎的游戏提供一个包含必要 SteamCMD 和库文件的基础镜像。项目仓库中通常会包含一个Dockerfile目录，里面是各种游戏服务端的 Dockerfile 模板，这是实现标准化的起点。

注意：archon本身不包含游戏服务端的版权文件。它提供的是“如何构建容器”的配方（Dockerfile），用户需要自行准备合法的游戏服务端文件（如从官方渠道下载的server.jar或通过 SteamCMD 获取的文件），并在构建镜像时放入指定位置。

第二层：服务管理 API 层这是archon的“大脑”。它通常是一个 RESTful API 服务（可能用 Go 或 Python 编写），负责接收用户指令。当用户说“我想在纽约的节点上开一个 50 人位的《我的世界》1.20.1 纯净服”，API 服务会解析这个请求，然后与底层的基础设施进行交互。它的主要职责包括：

• 镜像管理：检查所需的游戏服务器镜像是否存在，或触发构建。
• 容器生命周期管理：创建、启动、停止、重启和删除容器。
• 配置注入：将用户通过 Web 界面或 CLI 提交的服务器配置（游戏模式、密码、端口等），在容器启动时动态地写入容器内的配置文件中。
• 状态收集：定期检查容器的运行状态（是否存活、CPU/内存使用率、在线玩家数等）。

第三层：调度与集群管理层（进阶）对于大规模部署，单个 Docker 主机是不够的。archon的进阶功能会引入类似 Kubernetes 的调度概念，但可能更轻量。它会有一个调度器组件，负责管理一个由多个物理机或虚拟机组成的“集群”。调度器的任务是：

• 资源调度：根据各节点的剩余资源（CPU、内存、磁盘 I/O），决定将新创建的游戏服务器容器放在哪个节点上运行。
• 高可用与故障转移：监控节点健康状态，如果某个节点宕机，自动将其上运行的容器迁移到其他健康节点上。
• 网络抽象：提供统一的网络入口。尽管每个游戏服务器容器可能被调度到不同的物理机并使用不同的内部端口，但对外可以提供统一的域名和端口范围，由调度器或负载均衡器负责转发流量。

2.3 与通用容器平台的区别

你可能会问，直接用 Docker 或 Kubernetes 不行吗？当然可以，但archon提供了关键的“领域特定”优化：

• 游戏服务器专用配置抽象：它不会让你去写复杂的 Kubernetes YAML 文件来定义“一个 Minecraft 服务器”。它可能提供这样的接口：archon create minecraft --version=1.20.1 --slots=50 --mode=survival。背后，它帮你生成了所有必要的容器 spec、配置文件和环境变量。
• 内建的游戏服务器监控：通用的监控工具（如 Prometheus）可以监控容器资源，但archon可以集成游戏服务器的 RCON（远程控制）协议或查询协议，直接获取“在线玩家列表”、“当前地图”、“TPS（每秒刻数）”等游戏特有的指标，并将其暴露给监控系统。
• 存档与数据管理：游戏服务器的世界存档、玩家数据、日志文件需要持久化存储和定期备份。archon会将这些数据卷（Volume）的管理标准化，提供一键备份、回滚到某个时间点存档的功能，这比手动操作 Docker Volume 或 Kubernetes PersistentVolume 要直观得多。

3. 核心组件与实操要点解析

3.1 镜像构建系统：标准化游戏服务器的“食谱”

archon的基石是其镜像构建系统。它不是一个单一的 Dockerfile，而是一套模板化和自动化的流程。让我们以构建一个 Minecraft Forge 服务器的镜像为例，拆解其中的要点。

典型的Dockerfile结构剖析：

# 1. 使用 archon 定制的基础镜像 FROM archon/java:17-jre-noble # 2. 设置元数据和环境变量 LABEL maintainer="SufficientDaikon" ENV SERVER_JAR="forge-1.20.1-47.2.0-universal.jar" ENV EULA="FALSE" ENV MEMORY="2G" # 3. 创建工作目录并设置用户（安全最佳实践） RUN mkdir -p /app && addgroup --system --gid 1000 minecraft && adduser --system --uid 1000 --ingroup minecraft minecraft WORKDIR /app USER minecraft # 4. 复制启动脚本和默认配置 COPY --chown=minecraft:minecraft entrypoint.sh /app/ COPY --chown=minecraft:minecraft server.properties.template /app/ # 5. 声明数据卷（用于持久化存档和配置） VOLUME ["/app/world", "/app/logs", "/app/config"] # 6. 暴露端口（Minecraft 默认 25565） EXPOSE 25565 # 7. 设置入口点，使用脚本启动 ENTRYPOINT ["/app/entrypoint.sh"]

关键脚本entrypoint.sh的作用：这个脚本是容器启动的“导演”，它负责在运行时动态处理配置。

#!/bin/bash set -e # 检查 EULA 是否已接受（Minecraft 服务器要求） if [ "${EULA}" != "TRUE" ]; then echo >&2 "错误：你必须接受 EULA 才能运行 Minecraft 服务器。" echo >&2 "请设置环境变量 EULA=TRUE" exit 1 fi # 如果配置文件不存在，则从模板生成（首次运行） if [ ! -f server.properties ]; then envsubst < server.properties.template > server.properties fi # 动态设置 JVM 内存参数 JAVA_OPTS="-Xms${MEMORY} -Xmx${MEMORY} ${ADDITIONAL_JAVA_OPTS}" # 启动服务器 exec java ${JAVA_OPTS} -jar ${SERVER_JAR} nogui

实操心得：使用envsubst命令配合环境变量来生成最终配置文件，是实现配置动态化的经典模式。这样，用户无需进入容器内部修改文件，只需在创建容器时传入不同的环境变量（如-e MOTD="My Awesome Server"），就能定制服务器属性。

3.2 控制平面 API：统一的管理入口

archon的 API 服务是其控制核心。它通常提供以下关键端点：

• POST /api/v1/servers：创建新游戏服务器。请求体中包含游戏类型、版本、资源配置、自定义配置等。
• GET /api/v1/servers：列出所有服务器及其状态。
• GET /api/v1/servers/{id}：获取特定服务器的详细信息。
• POST /api/v1/servers/{id}/start/stop/restart：控制服务器生命周期。
• GET /api/v1/servers/{id}/logs：获取服务器日志流。
• POST /api/v1/servers/{id}/command：向游戏服务器发送控制台命令（通过 RCON）。

API 设计背后的考量：

1. 幂等性：创建服务器的请求应该是幂等的。如果用户用相同的参数重复调用，API 应返回已存在的服务器 ID，而不是重复创建。这防止了因网络重试导致的服务器泛滥。
2. 异步操作：创建或启动一个大型游戏服务器（尤其是需要下载资源的）可能需要几十秒。API 不应同步等待，而应立即返回一个任务 ID 或服务器 ID，并通过 WebSocket 或轮询接口提供进度更新。
3. 安全性：所有端点都必须有认证和授权。通常使用 API Token 或 JWT。同时，要防止用户通过命令注入攻击容器主机。对command端点传入的参数必须进行严格的过滤和转义。

3.3 数据持久化与备份策略

游戏服务器的数据（世界、玩家数据、插件配置）是核心资产。archon必须有一套稳健的持久化方案。

方案一：Docker Volume（单机场景）最简单的方式是使用 Docker 的命名卷（Named Volume）。在archon的服务器定义中，会声明将容器内的/app/world目录挂载到一个特定的卷上，例如mc_server_world_data。

• 优点：管理方便，由 Docker 引擎负责生命周期。
• 缺点：备份和迁移需要直接操作 Docker 主机，跨主机迁移复杂。

方案二：NFS/分布式文件系统（集群场景）在集群部署中，所有节点需要访问同一份持久化数据。这时会使用 NFS（如 AWS EFS、Google Filestore）或分布式文件系统（如 Ceph、Longhorn）。

• 实操要点：在 Kubernetes 环境下，这对应着PersistentVolume和PersistentVolumeClaim。archon的调度器在创建 Pod（容器组）时，会为其声明一个 PVC，由集群自动绑定到可用的 PV（背后可能是网络存储）。

备份策略的实现：archon可以在 API 层提供备份触发点。其工作流程可能是：

1. 用户通过 API 发起备份请求，或系统根据定时任务触发。
2. API 服务向目标游戏服务器容器发送保存命令（如 Minecraft 的save-all）。
3. 确认游戏数据已刷盘后，API 服务通知运行该容器的节点上的一个“Sidecar”容器（或直接通过 Docker API），对指定的数据卷进行快照或打包压缩。
4. 将备份文件上传到对象存储（如 AWS S3、MinIO）。
5. 记录备份元信息（时间点、服务器 ID、备份文件路径）到数据库。

踩坑记录：直接在游戏服务器运行时对文件系统进行打包备份，可能会导致存档损坏，特别是对于频繁写入的数据库类文件（如某些插件使用的 SQLite）。最佳实践是：先通过游戏命令触发保存并等待完成，然后停止服务器容器，再进行备份操作，最后重启服务器。对于要求 24/7 在线的服务器，可以采用文件系统级别的快照功能（如 LVM 快照、ZFS 快照），在瞬间完成一致性备份，对服务影响最小。

4. 从零开始部署与配置实战

假设我们有一台干净的 Ubuntu 22.04 服务器，目标是部署archon的核心组件，并成功启动一个 Minecraft 服务器。

4.1 基础环境准备

首先，安装 Docker 和 Docker Compose。archon的轻量级单机部署通常使用 Docker Compose 来编排其多个组件。

# 更新系统包 sudo apt-get update && sudo apt-get upgrade -y # 安装 Docker 官方 GPG 密钥和仓库 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker Engine 和 Compose Plugin sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y # 验证安装 sudo docker run hello-world

4.2 获取与配置 Archon

接下来，从 GitHub 克隆archon项目（假设项目结构包含docker-compose.yml）。

git clone https://github.com/SufficientDaikon/archon.git cd archon/deploy

查看docker-compose.yml文件，它可能定义了以下服务：

version: '3.8' services: archon-api: image: sufficientdaikon/archon-api:latest container_name: archon-api ports: - "8080:8080" # API 服务端口 environment: - DATABASE_URL=postgresql://postgres:password@archon-db/archon - DOCKER_HOST=unix:///var/run/docker.sock volumes: - /var/run/docker.sock:/var/run/docker.sock # 挂载 Docker 套接字，让 API 能控制宿主机 Docker - ./config:/app/config depends_on: - archon-db archon-db: image: postgres:15-alpine container_name: archon-db environment: - POSTGRES_DB=archon - POSTGRES_USER=postgres - POSTGRES_PASSWORD=your_strong_password_here # 务必修改！ volumes: - postgres_data:/var/lib/postgresql/data archon-webui: # 可选，Web管理界面 image: sufficientdaikon/archon-webui:latest container_name: archon-webui ports: - "80:80" environment: - API_BASE_URL=http://archon-api:8080 depends_on: - archon-api volumes: postgres_data:

关键配置解析：

1. DOCKER_HOST环境变量与 Docker Socket 挂载：这是archon-api服务能够管理本地容器的关键。它将宿主机的 Docker 守护进程套接字挂载到容器内，使 API 容器获得了几乎与 root 用户等同的控制宿主 Docker 的能力。这是一个重大的安全考量，在生产环境中，需要严格限制 API 服务的网络访问权限，并确保其本身没有漏洞。
2. 数据库：使用 PostgreSQL 存储服务器实例的元数据、用户信息、备份记录等。密码必须修改为强密码。
3. 网络：所有服务在默认的docker-compose网络内，可以通过服务名（如archon-db）相互访问。

修改密码后，启动服务：

# 在包含 docker-compose.yml 的目录下 sudo docker compose up -d

使用sudo docker compose logs -f archon-api查看 API 服务日志，确认启动无误。

4.3 构建第一个游戏服务器镜像

archon项目可能已经提供了一些示例游戏镜像的 Dockerfile。我们以 Minecraft Vanilla 为例。

# 进入示例目录 cd ../examples/minecraft-vanilla # 查看 Dockerfile cat Dockerfile # 通常，你需要准备 server.jar 文件。可以从 Mojang 官网下载。 # 假设已下载 server.jar 到当前目录。 # 构建镜像 sudo docker build -t archon/minecraft:1.20.1-vanilla . # 将镜像打上标签，推送到私有仓库（如果是在集群中部署） # sudo docker tag archon/minecraft:1.20.1-vanilla myregistry.local:5000/archon/minecraft:1.20.1-vanilla # sudo docker push myregistry.local:5000/archon/minecraft:1.20.1-vanilla

4.4 通过 API 创建并管理服务器

现在，archon-api服务已在8080端口运行。我们可以使用curl或 Postman 与之交互。

1. 创建服务器：

curl -X POST http://your_server_ip:8080/api/v1/servers \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -d '{ "name": "my-first-mc-server", "game": "minecraft", "version": "1.20.1-vanilla", "image": "archon/minecraft:1.20.1-vanilla", "env": { "EULA": "TRUE", "MEMORY": "2G", "MOTD": "Welcome to Archon-Powered Server!" }, "resources": { "cpu_limit": "1.0", "memory_limit": "3Gi" }, "network": { "port_bindings": { "25565/tcp": 25565 } } }'

如果成功，API 会返回一个 JSON，包含服务器 ID 和状态（如"status": "creating"）。

2. 查询服务器状态：

curl -H "Authorization: Bearer YOUR_API_TOKEN" http://your_server_ip:8080/api/v1/servers

3. 查看服务器日志：

# 假设服务器ID是 `srv_abc123` curl -H "Authorization: Bearer YOUR_API_TOKEN" http://your_server_ip:8080/api/v1/servers/srv_abc123/logs?tail=100

4. 停止服务器：

curl -X POST -H "Authorization: Bearer YOUR_API_TOKEN" http://your_server_ip:8080/api/v1/servers/srv_abc123/stop

至此，你已经完成了一个最基本的archon环境搭建和游戏服务器生命周期管理。玩家现在可以通过你的服务器 IP 和指定的端口（如25565）连接到这个 Minecraft 服务器了。

5. 集群化部署与高级运维

对于生产环境，单点部署显然不够。我们需要考虑高可用、负载均衡和横向扩展。archon的集群模式通常会引入一个“节点代理”（Node Agent）和一个中央“调度器”（Scheduler）。

5.1 集群架构深化

1. 节点代理（Archon Agent）：部署在集群的每个工作节点（物理机或虚拟机）上。它负责：
   • 向中央调度器注册节点，并定期上报心跳和资源使用情况（可用 CPU、内存、磁盘空间）。
   • 接收来自调度器的指令，在本节点上执行容器的创建、启停等操作。
   • 收集本节点上所有容器的运行指标（资源使用、游戏内指标）并上报。
2. 中央调度器（Archon Scheduler）：作为archon-api的扩展或独立服务。它维护着整个集群的视图（有哪些节点、各节点剩余资源），当 API 收到创建服务器的请求时，调度器根据策略（如“资源最充足”、“玩家地理位置最近”）选择一个最优节点，并将任务下发到该节点的 Agent 上执行。
3. 服务发现与网络：当容器被调度到不同节点时，它们的 IP 是动态的。需要一个覆盖网络（如 Docker Swarm Overlay Network、Calico、Flannel）或一个入口控制器（如 Traefik、Ingress-Nginx）来统一对外暴露服务。archon可能会为每个游戏服务器自动分配一个子域名（如srv_abc123.yourgame.com），并将流量路由到正确的容器。

一个简化的集群部署docker-compose.yml（仅展示核心服务）可能如下：

version: '3.8' services: archon-scheduler: image: sufficientdaikon/archon-scheduler:latest environment: - DB_URL=postgresql://postgres:password@archon-db/archon - ETCD_ENDPOINTS=http://etcd:2379 # 使用 etcd 存储集群节点和任务状态 depends_on: - archon-db - etcd archon-agent: image: sufficientdaikon/archon-agent:latest environment: - SCHEDULER_URL=http://archon-scheduler:8081 - NODE_NAME=worker-node-1 - NODE_LABELS=zone=us-east, gpu=false volumes: - /var/run/docker.sock:/var/run/docker.sock deploy: # 使用 Docker Swarm 模式部署到所有工作节点 mode: global etcd: image: bitnami/etcd:latest environment: - ALLOW_NONE_AUTHENTICATION=yes - ETCD_ADVERTISE_CLIENT_URLS=http://etcd:2379

5.2 监控与告警体系搭建

运维游戏服务器，监控至关重要。archon生态应集成监控。

1. 指标收集：
   • 容器资源指标：在每个节点部署node-exporter，配合cAdvisor收集容器级别的 CPU、内存、网络、磁盘指标。
   • 游戏业务指标：这是archon的亮点。Agent 或一个 Sidecar 容器可以通过游戏查询协议（如 A2S）或 RCON 定期获取“在线玩家数”、“服务器帧率（TPS）”、“当前地图”等信息，并将其以 Prometheus 格式暴露出来。
2. 可视化与告警：使用Grafana绘制仪表盘，展示集群总览、单个服务器状态、玩家在线趋势等。配置Alertmanager设置告警规则，例如“当某个服务器 TPS 持续 5 分钟低于 15 时告警”、“当节点内存使用率超过 90% 时告警”。

示例 Prometheus 抓取配置片段：

scrape_configs: - job_name: 'archon-nodes' static_configs: - targets: ['node-exporter:9100', 'cadvisor:8080'] - job_name: 'archon-game-metrics' static_configs: - targets: ['archon-agent-worker-1:9101', 'archon-agent-worker-2:9101'] # Agent 暴露的游戏指标端口

5.3 安全加固实践

将 Docker Socket 挂载给容器是强大的，也是危险的。以下是必须实施的安全措施：

1. 最小权限原则：不要使用默认的archon-api镜像。基于它构建自己的镜像，并以非 root 用户运行 API 服务。在 Docker 守护进程侧，可以配置daemon.json，通过 TLS 认证和证书来限制 API 容器的权限，而不是直接挂载 socket。
2. 网络隔离：使用 Docker 的桥接网络或用户自定义网络，严格限制容器间的通信。archon-api、数据库、工作节点之间应使用独立的内部网络。
3. 镜像安全扫描：在 CI/CD 流水线中集成Trivy或Clair等工具，对自建的游戏服务器镜像进行漏洞扫描，确保基础镜像和安装的软件没有已知高危漏洞。
4. API 认证与授权：使用强化的 JWT 或 OAuth2，并为不同用户（如管理员、服主、普通玩家）分配不同的角色和权限（RBAC）。例如，服主只能管理自己创建的服务器，不能访问其他人的。

6. 常见问题与故障排查实录

在实际运营中，你会遇到各种各样的问题。这里记录一些典型场景和排查思路。

6.1 服务器创建失败

• 现象：通过 API 创建服务器，长时间处于"creating"状态，最终超时或报错。
• 排查步骤：
  1. 查 API 日志：sudo docker compose logs archon-api。看是否有明显的错误信息，如“镜像拉取失败”、“端口冲突”、“资源不足”。
  2. 查 Docker 守护进程日志：sudo journalctl -u docker.service。看 Docker 是否收到了创建容器的请求，以及执行过程中是否有报错。
  3. 检查镜像：确认指定的镜像标签是否存在且可拉取。在节点上手动执行sudo docker pull <image_name>测试。
  4. 检查资源：在单机模式下，检查宿主机内存和磁盘空间是否充足。在集群模式下，检查调度器选中的目标节点资源是否足够。
  5. 检查网络策略：如果使用集群覆盖网络，确保网络插件（如 Calico）工作正常，容器能分配到 IP。

6.2 游戏服务器进程异常退出

• 现象：容器在运行，但内部的游戏服务进程崩溃，容器不断重启。
• 排查步骤：
  1. 查看容器日志：sudo docker logs <container_id>。这是最直接的入口。日志中通常会打印 Java 的OutOfMemoryError、原生库加载失败、配置文件语法错误等信息。
  2. 检查环境变量与配置：确认通过 API 传入的环境变量（如MEMORY="2G"）是否被正确解析。进入容器内部检查生成的最终配置文件（如server.properties）内容是否正确：sudo docker exec -it <container_id> cat /app/server.properties。
  3. 检查数据卷权限：如果游戏服务器需要向挂载的数据卷写入数据（如世界存档），确保容器内运行进程的用户（如上面的minecraft用户，UID 1000）对该目录有写权限。这是一个非常常见的坑。可以通过sudo docker exec -it <container_id> ls -la /app/world检查。
  4. 资源限制过紧：检查创建容器时设置的memory_limit。如果 JVM 堆内存设置（-Xmx）接近或超过容器的内存限制，当 JVM 需要更多内存用于堆外操作（如线程栈、直接内存）时，会被 Docker 的 OOM Killer 直接终止。经验法则：容器的内存限制应至少比 JVM 堆内存（-Xmx）大 1GB。

6.3 玩家无法连接服务器

• 现象：服务器状态显示为"running"，但玩家客户端连接超时。
• 排查步骤：
  1. 检查端口映射：确认docker run或docker-compose中是否正确映射了端口。例如，-p 25565:25565是将容器内25565端口映射到宿主机25565端口。使用sudo ss -tulnp | grep 25565查看宿主机端口是否在监听。
  2. 检查防火墙：宿主机防火墙（如ufw）或云服务商的安全组规则必须允许该端口的入站流量。
  3. 检查容器内服务是否真的在监听：进入容器，用netstat或ss命令检查游戏服务器进程是否绑定了正确的端口（通常是0.0.0.0:25565，而不是127.0.0.1:25565）。某些服务端配置可能需要显式设置server-ip=0.0.0.0。
  4. 检查网络模式：如果容器使用了host网络模式，端口冲突的可能性更大。如果使用了自定义桥接网络，需要确保端口映射正确。

6.4 性能问题：服务器卡顿（TPS 低）

• 现象：玩家反馈游戏卡顿，通过监控发现服务器 TPS 持续偏低。
• 排查思路：
  1. 资源瓶颈：首先通过docker stats或监控面板，检查容器的 CPU 和内存使用率。CPU 持续接近 100% 或内存使用率过高是首要怀疑对象。
  2. 磁盘 I/O：如果游戏世界频繁保存或插件大量读写文件，磁盘 I/O 可能成为瓶颈。检查宿主机磁盘使用率（iostat）和容器所在卷的读写延迟。考虑将数据卷放在 SSD 上。
  3. 游戏内因素：使用游戏内命令（如 Minecraft 的/tps或/debug）或通过archon集成的监控查看具体是哪个方面（实体、区块加载、红石电路）导致的性能下降。过多的实体、复杂的红石机器是常见原因。
  4. 宿主机邻居干扰：在共享宿主机环境下，其他容器或进程可能正在消耗大量资源（如 CPU、网络带宽）。需要利用 Docker 的--cpus、--memory限制，并考虑使用--cpu-shares为关键游戏服务器容器分配更高的权重。

6.5 备份与恢复失败

• 现象：定时备份任务失败，或恢复备份后服务器无法启动。
• 排查步骤：
  1. 检查存储空间：备份目标位置（如 NFS 目录、S3 桶）是否有足够空间。
  2. 检查权限：执行备份操作的进程（可能是archon-api或一个专门的sidecar容器）是否对数据卷有读权限，对备份目标有写权限。
  3. 验证备份文件完整性：备份完成后，应有一个校验步骤（如计算 MD5）。恢复前也应先校验。压缩包损坏是常见问题。
  4. 恢复流程问题：恢复操作通常需要先停止服务器容器。确保恢复脚本的逻辑正确：停止容器 -> 清空当前数据目录 -> 解压备份 -> 重启容器。任何一步出错都会导致失败。强烈建议在恢复前，对当前数据做一次快照备份，以便回滚。