升级
本页面向运维人员,说明如何检查并应用 Felis 更新、更新期间会重启哪些组件、如何管理 Felis 之外的配套组件版本、如何跨越 PostgreSQL 大版本,以及升级失败后如何回滚。安装通道的区别见安装与部署。
检查与应用更新
felis update 默认只做检查,不修改主机。它报告各组件的已安装版本与上游可用版本,解析 Felis 的目标版本,下载与该目标匹配的安装器并检查其语法,最后打印一条明确的应用命令。
sudo felis update # 检查默认目标
sudo felis update --all # 同时规划发布版固定的 k3s 与 cloudflared 升级
sudo felis update --version v0.2.0 # 检查指定的已发布版本
sudo felis update --dev # 检查 main 分支的最新提交
sudo felis update --ref <commit-or-tag> # 检查指定的源码版本未指定目标时,默认目标取决于主机运行的版本:发布版的默认目标是最新稳定发布版;开发版(版本号带有提交,例如 v0.1.0+g1a2b3c4)的默认目标是 main 分支的最新提交,见开发通道。
上游版本表仅供参考。应用时统一采用目标版本中相互兼容的固定版本,不会逐个安装各组件的上游最新版;用户服务器的游戏镜像保持不变。--k3s、--cloudflared、--jre、--postgres 等选项只缩小报告范围;应用任一核心组件都会收敛整个平台组件包。
应用更新:
- 需要限定更新时段时,在「维护与备份 → 版本更新」设置维护窗口。维护窗口为可选设置。
- 执行检查,确认输出中的目标版本、完整提交、影响范围和重启影响。
- 原样执行检查打印的
--apply命令;设置了维护窗口时,在窗口内执行。发布版的命令带--version <tag> --expect-commit <完整 SHA>,标签被移动时拒绝执行;源码版本的命令带--ref <完整 SHA>。
sudo felis update --apply --version v0.2.0 --expect-commit <完整 SHA>应用过程依次执行以下步骤,任一步失败即停止:
- 检查维护窗口。未设置窗口时直接继续。
- 备份数据库、
/etc/felis和全部 MinecraftServer 资源,生成一个pre-migrate数据库备份包。备份失败时不做任何修改。 - 再次检查维护窗口。
- 运行目标版本的安装器,收敛
felis命令、API、operator 与面板、清单与 RBAC、游戏插件、游戏代理和系统服务器镜像,并实时输出安装器进度。安装器的部署就绪检查决定更新是否成功。 - 校验已安装的
felis版本与目标一致。
其他选项:
--force重新安装同一版本,或允许有意降级 Felis;降级到更早的发布版时必须指定。它不会跳过维护窗口、备份或组件兼容性检查。--all同时执行发布版固定的 k3s 和 cloudflared 升级,见组件版本。
felis update -h 中没有 --apply 的旧版 felis 须先运行一次安装器以获得此更新器。在已完成的安装上,sudo felis setup 只打开配置控制台,不能用于升级。
注意
应用更新时,API、游戏代理和系统服务器可能重启:面板短暂不可用,代理重启会断开所有在线玩家。应选择玩家较少的时段应用。
更新期间的重启
安装器只在组件运行的内容发生变化时重启它:
| 组件 | 重启条件 |
|---|---|
游戏代理 felis-velocity | 其单元、Java 运行时、velocity.jar、velocity.toml、转发密钥、felis-link 设置(插件自动重新读取的 service-token 除外)或插件 jar 发生变化,或服务未运行。指纹记录在 /etc/felis/velocity.fingerprint,删除该文件可强制重启。 |
| 登录空间与大厅的 Pod | 重新构建的 Limbo 或大厅镜像 ID 发生变化(记录在 /etc/felis/system-server-images)。安装器将该服务器的镜像固定到新摘要,由 operator 逐个更新 Pod;镜像仓库不可达时直接重建 Pod。 |
| felis-postgres | 发布版更换了 PostgreSQL 镜像或修改了 Pod,API 随之暂停数秒。 |
| felis-api、felis-operator、镜像仓库 Pod | 镜像标签发生变化(升级),或同版本重新运行时重新构建了镜像。 |
felis-api 和 felis-operator 均为单副本、Recreate 策略,升级期间面板和 API 暂停,通常为数秒,需要导入镜像时更久。新 Pod 无法启动(例如镜像缺失)时,安装器在 180 秒后报告部署失败,并打印 kubectl describe 诊断,其中可见 ErrImagePull 或 ImagePullBackOff。
平台升级不重启运行中的游戏服务器。游戏服务器的初始化容器也使用 Felis 镜像,运行中的服务器保留启动时的版本,下次启动时使用新版本。若发布版以其他方式修改了游戏 Pod,运行中的服务器会像编辑服务器设置后一样重启一次。
在面板中更新
所有者可以在面板中直接更新 Felis,不必登录主机执行 felis update --apply。
入口与权限:入口在「维护与备份 → 版本更新」。每日版本检查发现 felis-api 有可用的新发布版时,更新报告下方出现以「立即更新到」加目标版本号为标题的卡片,显示当前版本、目标版本和该组件的说明。开发版主机在 main 分支有新提交时出现同一卡片,标题为「立即更新到开发版本」加目标提交的前 7 位,卡片显示完整的目标提交,更新只安装该提交,见开发通道。只有所有者可以使用,管理员看不到该卡片。选择「立即更新」并在确认框中确认后,须完成身份验证,更新才开始。主机上已有其他主机任务在运行时,按钮不可用,待其结束后再操作。
更新内容:与命令行的 --apply 相同。更新前自动备份数据库与部署状态,随后运行目标版本的安装器;felis-api、游戏代理和系统服务器会重启,在线玩家可能断开,见更新期间的重启。
维护窗口:
- 未设置维护窗口,或当前在窗口内:确认框只需确认。
- 设置了窗口且当前不在窗口内:确认框提示「当前不在维护窗口内,更新将立即开始」,须额外勾选「我确认在维护窗口外立即更新」才能确认。这等同于
--apply --now,即显式开始一次临时维护。
执行方式:更新在主机上名为 felis-update-<任务 ID>.service 的临时 systemd 单元中执行,不依赖 felis-api 或 node-control 进程,因此二者在更新期间重启不会中断更新。更新期间面板的请求会短暂失败,页面显示「面板正在重启,正在重新连接…」并持续重试;node-control 重启后接回同一任务,阶段显示为「已重新连接,继续等待更新完成」。任务最长运行 90 分钟,超时后任务记为失败,主机上的更新单元不会被中止。主机在更新过程中重启时,任务以失败结束,须先在主机上运行 felis version 与 felis update --check 确认当前版本,再决定是否重试。
结果:
- 成功:页面显示已更新到的版本号。面板资源已随版本更换,选择「重新加载面板」载入新版本。
- 失败:页面显示错误和日志末尾,其中包含安装器输出,并附回滚说明。更新前的数据库与部署状态备份已保留。先在主机上运行
felis update --check查看当前安装的版本,再按更新失败时排查,需要退回时按回滚处理。
多机部署:面板更新只更新主控节点。工作节点仍使用节点升级任务,见更新节点。
维护窗口
维护窗口为可选设置,用于限定更新的开始时段。未设置窗口时,felis update --apply、在面板中更新和重新运行安装器都在发起后立即开始;设置窗口后,它们等到窗口开始后才能开始;窗口结束后不再限制。在「维护与备份 → 版本更新」的「维护窗口(可选)」中设置:
- 选择「开始时间」和「结束时间」。时间按浏览器的本地时区选择和显示;结束时间必须晚于开始时间。
- 选择「保存维护窗口」。「清除维护窗口」删除已设置的窗口,此后更新不再受时段限制。
窗口状态显示为「当前生效中」「已计划(未来)」「已过期(过去)」或「未设置」。已过期的窗口不再限制更新。
应用更新时,felis update 在备份前和安装前各读取一次窗口:
- 未设置窗口或窗口已结束时,直接应用。
- 窗口尚未开始时,拒绝应用,并在提示中给出窗口的起止时间。
- 备份开始时窗口已开放、备份结束时窗口已关闭的,拒绝应用。
--apply --now显式开始一次临时维护,不使用已设置的窗口。- 无法读取窗口时始终拒绝,
--now也不例外。 --force不会跳过窗口检查。- 每日定时检查(
felis update --record)从不应用更新。
在已安装的主机上重新运行安装器时,安装器在修改主机之前检查维护窗口:设置了窗口且窗口尚未开始时停止,并给出窗口的起止时间。设置 FELIS_IGNORE_MAINTENANCE_WINDOW=1 可在窗口外运行;felis update --apply 已完成窗口检查,由它运行的安装器不再重复检查。无法读取窗口时(例如数据库未运行),安装器给出警告后继续,以便通过重新运行安装器修复主机。首次安装和面板发起的节点操作不检查维护窗口。
开发通道
使用开发通道(FELIS_VERSION_BOOTSTRAP=dev)安装的主机运行开发版,从源码构建并跟随 main 分支。开发版的版本号带有构建所用的提交,例如 v0.1.0+g1a2b3c4。在这类主机上,未指定目标的 felis update 与 felis update --dev 相同:
sudo felis update检查报告 main 分支是否有新提交,打印 main 最新提交的完整 SHA,以及一条带 --ref <完整 SHA> 的应用命令,该命令固定为检查时的提交。未指定目标的 --apply(或 --apply --dev)则在执行时重新解析 main 的最新提交,仅在有意如此时使用。指定 --version 或 --ref 时改用指定的目标。
每日检查(felis update --record)同样比较已安装的提交与 main 的最新提交。main 有新提交时,「组件版本」卡片中的 felis-api 显示为「有可用更新」,「更新版本」一栏显示目标提交的前 7 位;所有者可在面板中直接更新到该提交,见在面板中更新。
也可以直接重新运行安装器升级。重新运行会保留已安装的根域名,但须再次指定通道,否则安装器按默认的发布通道安装:
curl -fsSL https://raw.githubusercontent.com/FelisMC/Felis/main/deploy/bootstrap.sh | sudo FELIS_VERSION_BOOTSTRAP=dev bash源码构建需要在主机上构建镜像的资源,见环境要求。
组件版本
felis-update-check.timer 每天约 05:30 运行 felis update --record(错过时在开机后补执行),结果显示在面板「维护与备份 → 版本更新」的「组件版本」卡片中:每个组件的已安装版本和更新版本;有更新时给出 sudo felis update --<组件> 命令,该命令打印应用方法。Felis 不会自动应用任何更新。最近一次记录超过 26 小时未更新时,卡片显示「检查已逾期」,说明定时任务已停止:
systemctl list-timers felis-update-check.timer
journalctl -u felis-update-check -n 50 --no-pager
sudo felis update --record # 立即记录一次检查更新器复用安装器收敛 Felis 及其核心组件。安装器安装的其他组件按下表处理:
| 组件 | 重新运行安装器时 | 升级方式 |
|---|---|---|
| Velocity、Limbo、Paper、LuckPerms | 跟随发布版的游戏组件锁定文件(deploy/game-stack.lock) | 发布版更新锁定文件后重新运行安装器或应用更新 |
| Temurin Java 运行时 | 安装器安装的运行时更新到固定的补丁版本;其他来源的运行时保持不变 | 重新运行安装器 |
| k3s | 保持现有版本 | FELIS_UPGRADE_DEPS=1 重新运行安装器,或 felis update --all:通过固定版本的安装脚本升级,每次只升一个 minor 版本,从不降级 |
| cloudflared | 保持现有版本 | FELIS_UPGRADE_DEPS=1 或 felis update --all:将 /usr/local/bin/cloudflared 替换为已校验 sha256 的固定版本并重启 cloudflared-felis;发行版软件包安装的 cloudflared 仍由包管理器维护 |
| PostgreSQL | 跟随发布版固定的镜像 | minor 版本随 Felis 发布版更新,重新运行时重启 felis-postgres,API 暂停数秒;major 版本见 PostgreSQL 大版本升级 |
| Docker、git、nftables | 发行版软件包 | 包管理器 |
当前发布版固定的版本:
| 组件 | 固定版本 | 安装器变量 |
|---|---|---|
| k3s | v1.36.4+k3s1 | FELIS_K3S_VERSION |
| cloudflared | 2026.9.1 | FELIS_CLOUDFLARED_VERSION;其他版本须同时提供 FELIS_CLOUDFLARED_SHA256 |
| Temurin Java 运行时(游戏代理) | 25(25.0.4.1+1) | FELIS_JRE_VERSION |
| PostgreSQL | 18.6,官方 postgres 镜像按摘要固定 | — |
k3s 跨越多个 minor 版本时,安装器在修改前停止,并提示先将 FELIS_K3S_VERSION 设为下一个 minor 版本的最新发布。
游戏组件锁定文件固定登录空间、大厅、普通 Paper 镜像和游戏代理所用的上游构建及其 sha256,因此同一发布版在每台主机上构建出相同的镜像。FELIS_GAME_STACK=latest 改为在安装时解析上游最新构建并在主机上构建,FELIS_VELOCITY_VERSION=<minor> 安装指定 minor 版本的最新 Velocity 构建。已创建的服务器固定在创建时的镜像摘要上,不会随平台镜像变化;将世界迁移到新的 Minecraft 版本见游戏镜像。
PostgreSQL 大版本升级
felis-postgres 的数据库集群位于 /var/lib/felis/postgres/<major>/docker。发布版将镜像换到新的 major 版本时,安装器发现旧版本的集群后会在修改前停止,以免新服务器在旁边创建空集群。升级方法是在当前发布版上创建备份包,再恢复到新 major 版本的空集群中。
注意
以下步骤会停止面板和全部服务器管理功能,直到恢复完成。在维护窗口内执行,并保留旧集群目录作为回退手段。
在当前运行的发布版上创建备份包,停止数据库,并将旧集群移开:
bashb="$(sudo felis db backup -label pre-upgrade | sed -n 's/^felis db backup: wrote //p')" sudo k3s kubectl -n felis scale deploy/felis-postgres --replicas=0 sudo mv /var/lib/felis/postgres/18 /var/lib/felis/postgres-18.old安装新发布版。它在新 major 版本上创建空集群并建立数据库结构:
bashcurl -fsSL <安装器地址> | sudo bash恢复数据,并将数据库结构迁移到新发布版:
bashsudo k3s kubectl -n felis scale deploy/felis-api deploy/felis-operator --replicas=0 sudo felis db restore -yes -no-safety-backup "$b" sudo felis migrate up -config /etc/felis/felis.host.toml sudo k3s kubectl -n felis scale deploy/felis-api deploy/felis-operator --replicas=1
新版本稳定运行一段时间后,删除 /var/lib/felis/postgres-18.old。需要回退时,将 felis-postgres 缩容到 0,把新 major 版本的目录移出 /var/lib/felis/postgres,将 postgres-18.old 移回为 /var/lib/felis/postgres/18,再重新运行旧发布版的安装器。备份包的内容与恢复规则见恢复数据库。
升级旧安装
补全旧安装的配置
安装中有三部分保留创建时的状态,felis setup 和 kubectl rollout restart 都不会更新它们:felis-api 的 Deployment(后来新增的环境变量,例如 FELIS_SMTP_PASSWORD,在重新渲染前不存在)、大厅镜像(早期构建不含 LuckPerms,面板中的每次权限修改都返回 luckperms_missing),以及 MinecraftServer 资源(后来新增的字段保持为空)。按以下顺序更新,先更新镜像:
重新运行安装器。它渲染并应用控制面配置,重新构建并导入登录空间和大厅镜像,并重建这两个 Pod;
felis setup写入的[smtp]中继保持不变。为系统服务器补全新增的字段,再为 RCON 成为默认设置之前创建的用户服务器启用 RCON:
bashsudo felis converge sudo felis converge -user-rcon注意
-user-rcon要求服务器镜像开启 RCON 监听;镜像不支持 RCON 时,服务器可能无法启动。仅对支持 RCON 的镜像执行。用户服务器在下次启动时应用新的 RCON 设置。
面板中的对应操作是「平台设置 → 访问与安全」→「系统服务器补全」。检查各部分:
sudo k3s kubectl -n felis get deploy felis-api \
-o jsonpath='{.spec.template.spec.containers[0].env[*].name}' | tr ' ' '\n' | grep SMTP
sudo k3s kubectl -n minecraft exec lobby-0 -- ls /data/plugins | grep -i luckperms
sudo k3s kubectl -n minecraft get minecraftserver \
-o custom-columns=NAME:.metadata.name,RCON:.spec.rcon.enabled,IDLE:.spec.idle.autoStopEnabled环境变量只携带邮件中继的密码,中继本身仍需配置,见邮件中继。系统服务器字段的说明见系统服务器配置。
宿主机 PostgreSQL 迁入 k3s
早期发布版将数据库运行在安装器安装于宿主机的 PostgreSQL 上。首次在这类主机上重新运行包含 felis-postgres 的发布版时,安装器执行一次迁移:
- 停止 felis-api、felis-operator 和主机定时任务,并在宿主机
pg_hba.conf顶部加入规则,拒绝迁移连接之外对felis数据库的访问;原文件保存为pg_hba.conf.pre-pg-move。 - 创建
pre-pg-move备份包,恢复到 felis-postgres,并比较两个服务器上每个表的行数。至此任何失败都会恢复pg_hba.conf和控制面,平台继续使用未改动的宿主机数据库。 - 停止并禁用宿主机的
postgresql服务(软件包和数据副本保留),写入/var/lib/felis/postgres-moved。宿主机服务器还承载其他数据库时,服务保持运行,felis副本只能经回环地址访问。
迁移后,主机配置通过 127.0.0.1:15432 连接 felis-postgres,[database] deployment = "felis/felis-postgres" 使 felis db 在 Pod 内运行 pg_dump、psql 和 pg_restore;Pod 使用 felis-postgres.felis.svc:5432。
回退到宿主机数据库(例如重新安装迁移前的发布版):
sudo k3s kubectl -n felis scale deploy/felis-api deploy/felis-operator deploy/felis-postgres --replicas=0
hba="$(sudo -u postgres psql -XtAc 'SHOW hba_file' 2>/dev/null || echo /var/lib/pgsql/data/pg_hba.conf)"
sudo cp -p "${hba}.pre-pg-move" "$hba"
sudo systemctl enable --now postgresql
sudo rm /var/lib/felis/postgres-moved
curl -fsSL <该发布版的安装器地址> | sudo bashSHOW hba_file 需要数据库正在运行;数据库停止时使用 EL 系发行版的默认路径,Debian 和 Ubuntu 的文件位于 /etc/postgresql/<major>/main/。迁移之后的写入只存在于 felis-postgres 中;需要保留时,先执行 sudo felis db backup,回退后再恢复到宿主机数据库。迁移稳定运行一段时间后,可删除宿主机上的旧副本:
sudo systemctl start postgresql; sudo -u postgres dropdb felis; sudo -u postgres dropuser felis服务器资源校验
每次运行安装器都会应用 felis 程序内嵌的 MinecraftServer CRD。API server 拒绝 operator 无法处理的取值:
| 字段 | 允许的取值 |
|---|---|
spec.rcon.port | 未设置、0 或 25575;网络策略只开放 25575 |
spec.startup.timeoutSeconds、spec.startup.readinessTimeoutSeconds | 0–86400 |
spec.startup.healthHTTPPort | 0–65535 |
spec.lifecycle.terminationGracePeriodSeconds | 0–3600 |
spec.idle.emptySecondsBeforeStop | 0–604800(面板上限为 86400) |
0 均表示使用 operator 的默认值。在这些规则生效前保存的对象,越界值会保留到有人编辑该字段为止;operator 将负值视为默认值,过大的值按原值执行。用 sudo k3s kubectl -n minecraft edit minecraftserver <name> 手动修正。
回滚
回滚控制面镜像
每个发布版使用独立的镜像标签,例如 felis/felis:v1.2.3。升级结束时,安装器打印原来的标签,并记录在 /etc/felis/previous-felis-image。回滚到上一个版本的镜像:
sudo k3s kubectl -n felis rollout undo deployment/felis-api deployment/felis-operator
sudo k3s kubectl -n felis rollout status deploy/felis-api镜像通常仍在节点上;被清理时由集群内镜像仓库重新提供,仓库始终保留最新的 5 个 felis/felis 标签和仍被游戏 Pod 使用的镜像。同版本重新运行会复用同一标签,此后的 rollout undo 仍会回到该标签。下一次运行安装器会再次应用其安装的版本。
rollout undo 只回滚镜像,升级执行过的数据库迁移仍然保留。
回滚损坏数据库的升级
数据库迁移只能向前执行。升级前生成的 pre-migrate 备份包是回退的依据:felis update --apply 在安装前创建一份,安装器运行 felis migrate up 且有待执行的迁移时也会先创建一份。
危险
恢复会以备份包替换整个数据库,备份包之后的数据库变更全部丢失。恢复前,系统会自动为当前数据库创建一份 pre-restore 备份包。
停止控制面,找到升级生成的备份包并恢复,然后回滚镜像:
bashsudo k3s kubectl -n felis scale deployment felis-api felis-operator --replicas=0 sudo felis db list | grep pre-migrate # 最新的一份属于本次升级 sudo felis db restore -yes <该备份包> sudo k3s kubectl -n felis rollout undo deploy/felis-api sudo k3s kubectl -n felis rollout undo deploy/felis-operator sudo k3s kubectl -n felis scale deployment felis-api felis-operator --replicas=1此时不要运行
felis migrate up:主机上的felis已是新版本,会重新应用正在回滚的迁移。用旧发布版自己的安装器和附件重新安装该版本,使主机与数据库一致(以
v1.2.3为例):bashcurl -fsSL https://raw.githubusercontent.com/FelisMC/Felis/v1.2.3/deploy/bootstrap.sh \ | sudo FELIS_RELEASE=v1.2.3 bashFELIS_RELEASE使安装器安装指定的发布版;不设置时会再次安装最新版本并重新执行其迁移。它不能与FELIS_REF、FELIS_ARTIFACT_DIR、FELIS_SKIP_FETCH或FELIS_VERSION_BOOTSTRAP=dev同时使用,未发布的标签会在任何修改前停止安装。早于该变量的安装器会忽略它(curl -fsSL <安装器地址> | grep -c FELIS_RELEASE输出0),此时改用FELIS_REF=v1.2.3从源码构建该标签。
恢复的详细规则见恢复数据库。
数据库结构检查
felis-api、世界清理、异地副本和 felis migrate up 会比较数据库记录的迁移与程序内置的迁移:
- 数据库由更新的发布版迁移过时,它们停止并报告
database schema is newer than this felis build: it records migration 0026, and this build knows migrations up to 0025。跨越迁移执行rollout undo后,felis-api 会处于 CrashLoopBackOff,直到恢复pre-migrate备份包。 - 数据库缺少迁移时,felis-api、世界清理和异地副本报告
database schema is behind this felis build,直到运行felis migrate up;felis setup的预检会自动应用缺少的迁移。
更新失败时
安装器较早替换 /usr/local/bin/felis(后续步骤运行新版本),并将旧版本保留为 felis.prev,直到新版本投入使用。在数据库迁移开始前失败时,安装器恢复旧版本,使主机定时任务和 felis setup 与仍在运行的数据库和控制面一致;重新运行可从此处继续。迁移开始后失败时保留新版本。
安装器失败可能已修改部分组件,数据库结构不会自动回滚。保留更新前的备份包,查看安装器输出后再重试,或按回滚损坏数据库的升级回退。