跳至正文

环境要求 ​

本页面向规划 Felis 主机的管理员,列出支持的操作系统、应准备的 CPU、内存与磁盘、Felis 使用的端口、网段与 DNS 记录、对地址和时钟的要求,以及安装器在修改主机前执行的检查。安装步骤见安装与部署。

支持的主机 ​

Felis 默认安装在单台 Linux 主机上。将游戏服务器分布到多台机器为可选功能,见多机部署与高可用。

主机须满足:

  • 64 位 x86(x86_64)或 ARM(aarch64)处理器,不支持 32 位主机;
  • 以 systemd 作为 init 系统,并启用内存 cgroup 控制器;
  • 具有 root 权限;
  • 使用下表中的一种包管理器。
发行版包管理器架构
CentOS Stream 9、RHEL 9、Rocky Linux 9、AlmaLinux 9、Fedoradnfx86_64、aarch64
Ubuntu 24.04 LTS 及其他 Ubuntu 版本、Debian 12aptx86_64、aarch64
openSUSE Leap、openSUSE Tumbleweedzypperx86_64、aarch64
Arch Linuxpacmanx86_64、aarch64

CentOS Stream 9(aarch64,启用 firewalld 且 SELinux 为 enforcing)和 Ubuntu 24.04 LTS(x86_64)为参考平台,其他发行版使用相同的安装流程。

其余依赖由安装器负责安装:k3s、游戏代理所需的 Java 运行时、cloudflared,以及需要在主机上构建镜像时所需的 Docker。PostgreSQL 以 felis-postgres Deployment 运行在 k3s 中,数据位于主机的 /var/lib/felis/postgres。主机上已安装的 k3s 服务端会被复用,Felis 在该集群中添加自己的命名空间。主机上存在其他 Kubernetes 发行版(kubelet、RKE2、k0s、MicroK8s)或 k3s agent 时,安装器拒绝安装。全新安装所使用的组件版本见组件版本。

资源规划 ​

平台自身的资源占用 ​

平台空闲时的大致内存占用:

组件内存
k3s(API server、控制器、调度器、kubelet)约 370 MiB
k3s 的 containerd 及 Pod shim约 170 MiB
CoreDNS 及 local-path 存储供应器约 105 MiB
游戏代理 Velocity(空闲时;随玩家增加)约 175 MiB
felis-api、felis-operator、registry gate合计约 85 MiB
镜像仓库约 25 MiB
PostgreSQL约 40 MiB,另有页面缓存
基础设施合计约 1 GB

系统服务器另计:登录空间(Limbo,Pod 限制 512 MiB,实际占用约 0.16 GB)和可选的正式大厅(Paper,Pod 限制 1 GiB,启用时实际占用约 0.7–0.85 GB)。全新安装默认停用正式大厅(可通过 FELIS_WITH_LOBBY=1 在安装时启用,或安装后在玩家进入策略中随时开关);小内存配置不部署大厅,登录空间的 Pod 限制为 320 MiB。每台游戏服务器另需其所有者分配的内存:Pod 的 limit 等于 request,Java 堆大小据此计算。每位用户可用的内存受配额限制(见配额)。

安装发布版时不在主机上构建任何内容。安装器需要在主机上构建镜像时,峰值占用来自镜像构建(Docker 及 Gradle 容器);构建完成后安装器停止 Docker,释放的内存归还给服务器使用。没有交换空间的节点上,安装器创建与物理内存等大的 /swapfile(至少 2 GiB),供服务器休眠时存放内存;根文件系统在安装后剩余空间不足 10% 时不创建。节点已有交换空间时保持不变,交换空间小于物理内存时安装器给出提示。部分云厂商的系统镜像将 vm.swappiness 设为 0,此时内核在内存耗尽前不使用交换空间,主机会因反复回收页面缓存而失去响应;安装器发现交换空间已启用而该值为 0 时,将其恢复为内核默认值 60,写入 /etc/sysctl.d/99-zz-felis-swappiness.conf 并给出提示。

配置建议 ​

同时在线玩家同时运行的游戏服务器CPU内存FELIS_VELOCITY_XMX
不超过 201–2 台小型服务器2 vCPU4 GB + 2 GB swap1G(默认)
不超过 1003–5 台4 vCPU8–16 GB1G
不超过 3005–10 台8 vCPU16–32 GB2G
300 以上更多8 vCPU 以上32 GB 以上3G–4G

玩家数为规划估算值:Minecraft 服务器的开销主要取决于玩家行为(视距、红石、模组)。内存按以下方式估算:基础设施约 1 GB,登录空间约 0.2 GB(启用正式大厅时合计约 1 GB),加上预计同时运行的各服务器内存之和,再增加四分之一供页面缓存和 PostgreSQL 使用。

小内存主机 ​

内存低于 3.5 GiB 的主机在首次安装时使用小内存配置,以降低平台自身的内存占用:

  • 不部署正式大厅。玩家在登录空间完成身份验证后直接进入目标服务器,目标服务器启动期间在登录空间等待,见玩家进入策略;
  • 登录空间的 Pod 限制为 320 MiB;
  • 游戏代理的堆内存上限默认为 256M,见游戏代理内存;
  • k3s 不运行 Felis 未使用的 Helm 控制器,其 Go 堆的软上限为 400 MiB。

在系统可见内存约 1.6 GiB 的 2 GB 云主机上,小内存配置下平台空载约占 0.6 GB,系统镜像自带的组件另占约 0.4 GB,剩余内存不足以运行一台 Paper 服务器:服务器启动时主机持续换页,平台随之失去响应。因此,单节点安装中主机内存低于 3.5 GiB 时只运行平台:面板与 API 拒绝新建游戏服务器(错误码 host_too_small),已有服务器不受影响。运行游戏服务器需要至少 4 GB 内存的主机(见配置建议),或在多机部署中添加工作节点。该判断依据主机的实际内存,与所用配置无关:小内存配置的主机增加内存后即可新建服务器。

安装器变量 FELIS_HOST_PROFILE 选择配置:

取值行为
auto(默认)全新安装且内存低于 3.5 GiB 时使用 small,其他情况使用 standard。之后的运行沿用 /etc/felis/host-profile 中记录的配置,主机增加内存后也不改变。
small使用小内存配置。已部署大厅的安装不能改为此配置,安装器拒绝运行。
standard使用标准配置。以此值重新运行小内存配置的安装器后,可在「登录与大厅」中创建正式大厅。

游戏代理内存 ​

游戏代理(Velocity)每位玩家所需内存很少。其堆内存上限为 FELIS_VELOCITY_XMX:默认 1G,小内存配置下默认 256M;最小 256M,格式为 <n>M 或 <n>G。journalctl -u felis-velocity 出现较长的垃圾回收停顿或 OutOfMemoryError 时,应调高该值。

  • 在面板中:在「平台设置 → 访问与安全 → 游戏代理」中设置「内存上限」(256M 至 64G),然后选择「应用」。该值在重新运行安装器或更新后保持不变。
  • 在命令行中:带 FELIS_VELOCITY_XMX 重新运行安装器,例如 FELIS_VELOCITY_XMX=2G。安装器每次运行都会读取该变量。

注意

修改内存上限会重启游戏代理,所有在线玩家都会被断开。请在玩家较少时操作。

磁盘 ​

磁盘至少准备 40 GB;世界和自定义镜像增多后,建议 60 GB 以上。世界、世界归档、镜像仓库、上传内容和容器镜像都存放在 /var/lib/rancher/k3s 下,共用同一个文件系统,卷的申请容量不会强制生效。如需将这些数据与系统盘分开,可将 /var/lib/rancher/k3s 放到独立磁盘上(见将数据迁移到独立磁盘)。

各部分占用的空间以及之后的扩容方法,见存储与磁盘。安装器所需的可用空间见安装前检查。

网络 ​

端口 ​

端口协议用途访问来源
25565(FELIS_GAME_PORT)TCP游戏代理,玩家由此连接玩家
30443(FELIS_PANEL_NODEPORT)TCP面板和 API(HTTPS)面板用户,或面板前方的反向代理;由 Cloudflare Tunnel 提供面板时不对公网开放
6443TCPKubernetes API(k3s)本机及其 Pod;多机部署中的其他节点
6444、10248–10259TCPk3s 的 supervisor、kubelet、kube-proxy、controller manager 和调度器仅本机
5000TCP镜像仓库的回环端口仅本机
15432TCP数据库的回环端口仅本机

面板的访问方式(直接访问、自有反向代理或 Cloudflare Tunnel)见访问方式。节点之间的网络要求见隔离与网络要求。

防火墙与网段 ​

安装器会在主机防火墙中添加放行规则,不会关闭防火墙。

  • 启用 firewalld 时,放行面板端口、游戏端口和 6443,并将 k3s 的 Pod 网段和 Service 网段加入 trusted 区域。
  • 启用 ufw 时(Ubuntu 和 Debian 上常见),放行 10.42.0.0/16、10.43.0.0/16、面板端口和游戏端口,每条规则的注释为 felis-…。6443 端口不对网络开放,因为 Pod 从自身网段访问 API server。
  • 卸载时会删除这些规则。

主机前方的其他防火墙也须放行相同的流量。Pod 流量被丢弃时,首次部署会超时并提示 control-plane rollout did not complete。

k3s 使用 10.42.0.0/16 作为 Pod 网段,10.43.0.0/16 作为 Service 网段。主机地址及其路由的网络必须位于这两个网段之外,常见冲突来自 Docker 网络。覆盖范围更大的路由(例如 10.0.0.0/8 VPN)会使主机无法访问这两个网段内的地址,预检会给出警告。

出站访问 ​

主机须能直接或经 https_proxy 以 HTTPS 访问以下地址:

地址下载内容
github.com 及其发布版下载所重定向的 githubusercontent.com 主机Felis 发布版附件、k3s 及其镜像、cloudflared、Temurin JRE、ViaVersion、ViaBackwards 和 ViaRewind
raw.githubusercontent.comk3s 安装脚本,k3s 安装完成前需要
rpm.rancher.io在启用 SELinux 的 Red Hat 系或 SUSE 系主机(CentOS Stream、RHEL、Rocky、Alma、Fedora、openSUSE Leap)上,由 k3s 安装脚本添加的 k3s-selinux,k3s 安装完成前需要
fill-data.papermc.ioVelocity jar,通过 FELIS_VELOCITY_FORK_JAR 提供时除外
发行版软件源基础软件包(缺少时安装 CA 证书、OpenSSL、curl 和 tar),以及与 k3s-selinux 配套的 container-selinux
Docker Hub仅在主机上构建镜像时需要

不支持完全离线安装。使用预先下载的发布版附件安装时,无需下载 Felis 自身的二进制和镜像,其他软件仍需下载(见使用预下载附件安装)。部分安装器覆盖项会增加下载地址:FELIS_JRE_VERSION 访问 api.adoptium.net;非固定版本的 FELIS_VELOCITY_VERSION 访问 fill.papermc.io;FELIS_GAME_STACK=latest 在主机上构建镜像,需要访问 Docker Hub、PaperMC、Limbo 的 CI 和 LuckPerms。

为进行时间同步,还须放行出站 UDP 123(见时间同步)。

DNS ​

Felis 的全部服务都位于同一个根域名下,在首次安装时通过 FELIS_ROOT_DOMAIN 设置。默认值为 <主机地址>.nip.io,云主机为 <公网地址>.nip.io(见公网地址),无需自行配置 DNS 记录。重新运行安装器时沿用已安装的域名;之后可用 felis domain set 更换(见更换根域名)。

名称用途
<name>.<root>玩家连接各游戏服务器时使用的地址;游戏端口不是 25565 时附加 :<port>
console.<root>面板
op.console.<root>管理控制台

使用自有域名时,为 <root>、*.<root>、console.<root> 和 op.console.<root> 创建指向主机的记录。通配符记录不覆盖三级名称 op.console.<root>,须为其单独创建记录。由 Cloudflare Tunnel 提供面板时,只需让 <root> 和 *.<root> 指向主机。玩家的加入方式见玩家接入。

固定地址 ​

安装与安装时使用的 IPv4 地址绑定:k3s 节点、网络策略和面板证书都包含该地址,默认的 nip.io 域名包含该地址或转发到该地址的公网地址。安装前应为主机设置静态地址或 DHCP 保留。

  • 地址为 DHCP 租约时,安装器给出警告。
  • 主机失去该地址时,看门狗报告 host-address(严重,持续 5 分钟后)。见故障排查。
  • k3s 节点名在安装时固定,修改主机名不受影响。

公网地址 ​

玩家与浏览器通过主机的公网 IPv4 地址访问主机。云主机自身的地址通常为私有地址(位于 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16 或 100.64.0.0/10),由云服务商将公网地址转发到该地址。主机地址为私有地址且能访问云服务商的元数据服务时,安装器判定为云主机,先从元数据服务读取公网地址(阿里云、腾讯云与提供 public-ipv4 的服务商),读取不到时通过 HTTPS 查询(先访问 1.1.1.1,失败时访问 api.ipify.org),并将其用于:

  • 首次安装时的默认根域名(<公网地址>.nip.io);
  • 面板证书,证书同时包含两个地址;
  • 安装器输出的面板地址与游戏地址。

k3s 节点、网络策略与防火墙规则仍使用主机自身的地址。安装器日志说明所用的地址及原因。已安装的根域名始终保持不变。

  • FELIS_PUBLIC_IP=<地址> 直接指定公网地址,不再查询。
  • FELIS_PUBLIC_IP=none 使用主机自身的地址,不查询公网地址。
  • 家庭或办公网络中的主机不是云主机,安装器使用主机自身的地址;玩家经路由器端口转发访问时,用 FELIS_PUBLIC_IP 指定公网地址。
  • 查询失败时,安装器使用主机自身的地址并给出警告。

时间同步 ​

主机时钟必须由 NTP 同步。登录验证码和会话按时钟过期;签名时间偏差超过 15 分钟时,S3 会拒绝异地副本上传;时钟偏差过大还会导致证书校验失败。

  • 安装器开启 NTP(timedatectl set-ntp true;没有可启用的客户端时安装 chrony),并等待时钟完成同步。由其他方式校时的主机可设置 FELIS_MANAGE_TIME_SYNC=0。
  • 放行出站 UDP 123;防火墙丢弃该流量时,时钟将无法同步。
  • 看门狗将未同步的时钟报告为 clock(警告,持续 30 分钟后)。可用 timedatectl(应显示 System clock synchronized: yes 和 NTP service: active)和 chronyc sources 检查。见故障排查。

安装前检查 ​

安装器在修改主机前先检查主机,一次性报告全部问题;存在问题时停止,主机保持原样。检查项如下:

  • 平台:架构(x86_64 或 aarch64)、systemd 是否为 init,以及 k3s 所需的内存 cgroup 控制器。在 Raspberry Pi 上,需在 /boot/firmware/cmdline.txt 中添加 cgroup_memory=1 cgroup_enable=memory 并重启。

  • 内存:低于 1.5 GiB 时拒绝安装(标称「2 GB」的云主机扣除内核占用后约有 1.6–1.9 GiB,可以通过);低于 3.5 GiB 的全新安装使用小内存配置,并提示该主机只运行平台、不能新建游戏服务器。Felis-nano 不设内存下限。

  • 可用磁盘空间:按安装器写入的每个文件系统检查,多个目录位于同一文件系统时累加:

    目录所需可用空间(首次安装)重新安装或目录已有数据时
    /var/lib/rancher10 GiB3 GiB
    /var/lib/felis安装发布版时 4 GiB,否则 2 GiB3 GiB 或 1 GiB
    /opt/felis3 GiB1 GiB
    /var/lib/containerd(仅在主机上构建镜像时)8 GiB2 GiB

    在只有一个文件系统的空白主机上,合计约为:安装发布版 17 GiB,使用 FELIS_ARTIFACT_DIR 15 GiB,在主机上构建镜像 23 GiB;重新安装约 7 GiB。安装后文件系统占用将超过 85% 时给出警告,因为 k3s 此时会开始删除缓存镜像。

  • 端口:游戏端口、6443、6444、10248、10249、10250、10256、10257、10259、面板端口、镜像仓库回环端口 5000 和数据库回环端口 15432。被安装器自身服务占用的端口(重新安装时)视为通过;被其他程序占用时,报告该程序的名称。

  • 其他 Kubernetes:主机上存在其他发行版(kubelet、RKE2、k0s、MicroK8s)或 k3s agent 时拒绝安装。

  • 网段:主机地址或其路由的网络落在 10.42.0.0/16 或 10.43.0.0/16 内时拒绝安装;覆盖这两个网段的更大范围路由给出警告。

  • 出站 HTTPS:检查本次安装的各个下载地址(见出站访问)。完成 TLS 握手即视为可达,每个地址最多尝试三次、间隔两秒,无法访问的地址在一条消息中列出(cannot reach … over HTTPS)。安装发布版时,Docker Hub 不可达仅给出警告;使用 FELIS_ARTIFACT_DIR 时不检查 Docker Hub。

检查结果与实际情况不符时,可设置 FELIS_PREFLIGHT=warn,将相同问题降为警告并继续安装。