Felis/README.md

Felis

此项目仍处于早期开发阶段，您不该在任何生产环境使用该项目。若产生任何问题，贵用户的使用行为与 FelisMC 团队无任何民事刑事法律关系。 THIS PROJECT IS STILL WIP, YOU SHOULD DO NOT USE THIS PROJECT IN ANY PRODUCTION USAGE. WE ARE NOT RESPOND FOR ANY LEGAL OR HUMANLY PROBLEM.

一款 Kubernetes 驱动的 Minecraft 服务器托管平台，一行命令部署，自动管理生命周期与安全。
A Kubernetes-driven Minecraft server hosting platform — one command to deploy, automatic lifecycle, backup, and security.

简体中文 | English

目录

• 特性
• 使用方式
• 从源码构建
• 开源协议
• 致谢

特性

• 即开即玩：玩家尝试连接时自动唤醒服务器，空闲后自动休眠，像游戏主机一样省资源。
• Web 控制面板：浏览器中查看服务器状态、在线玩家与资源用量，管理备份与恢复。
• 备份与恢复：一键把整服数据（世界、配置、插件/模组，即整个 /data 卷）打包进集群内的归档库，支持从任意备份点回滚；默认安装就已启用（归档 PVC 与路径由安装器一并生成）。
• 控制面数据库备份：账号、服务器归属、配额与存档索引所在的数据库每天自动备份，每次升级迁移前先快照，出错可用 felis db restore 整库原子回滚；面板「维护与备份」页显示备份是否新鲜（见 故障排查 §16）。
• 运维自检：sudo felis status 一屏列出节点、控制面、游戏代理、每台服务器、备份与未解决的告警；sudo felis doctor 把健康检查全跑一遍，按区域给出问题和下一步去哪看，不发邮件；sudo felis support-bundle 打出一个脱敏的诊断包，求助时直接附上（见 故障排查 §0）。
• 智慧回收（可选开启）：超过 15 天无人游玩的世界自动备份后删除，释放磁盘空间；安装时设置 FELIS_WORLDS_HOST_PATH（k3s 默认 /var/lib/rancher/k3s/storage）即启用每日回收，不设置则不删任何世界。过期备份无论是否开启都会每天清理。
• 多核心支持：兼容 Paper、Fabric、Forge、NeoForge，经由 Velocity 代理统一入口。
• 模组自助提交：玩家自行上传模组包，服主审批通过后自动构建；构建产物进入镜像白名单，可直接选用为服务器镜像完成部署。
• Passkey 登录：支持指纹、面容、硬件密钥等无密码认证方式。
• 零信任安全：面板流量由 Cloudflare Access 保护，集群内 API 不暴露到公网。

使用方式

在准备好的 Linux 主机上执行（已验证的发行版与架构见 运维手册 §1：CentOS Stream 9 aarch64 实机验证，Ubuntu 24.04 x86_64 每次推送由 CI 跑全新安装、重跑、升级和下面这条命令本身）：

curl -fsSL https://raw.githubusercontent.com/FelisMC/Felis/main/deploy/bootstrap.sh | sudo bash

脚本将自动安装 K3s，在 K3s 内部署 PostgreSQL 与控制平面，并启动设置向导。完成后浏览器访问已配置的域名进入控制面板即可使用。

安装发布版时，二进制、全部镜像与 Velocity 插件都取自该版本在 CI 里预构建好的 release 附件，逐个核对 SHA256SUMS 后导入，主机上无需 Docker、Gradle 或 Go，也不从 Docker Hub 拉取；某个附件缺失或校验不符时，只有那一个镜像退回到本机构建，并给出提示（见 故障排查 §15c）。附件也可以先拷到本机，再用 FELIS_ARTIFACT_DIR=<绝对路径> 安装，Felis 自己的二进制、镜像和插件就都取自这个目录；k3s 及其镜像、JRE、cloudflared、Velocity 和 Via 插件照旧从 GitHub 与 PaperMC 下载，RHEL、Fedora、openSUSE Leap 这类开着 SELinux 的主机还要从 rpm.rancher.io 装 k3s-selinux，系统软件包来自发行版的源。所以出网受限的主机要放行这几处的 HTTPS（或设 https_proxy），preflight 会在改动主机之前逐个探测，完全断网的主机目前装不了（地址清单见 运维手册 §1）。旧版本装在宿主上的 PostgreSQL 会在重跑时整库迁进 K3s，宿主上的那份停用保留，供回退（见 运维手册 §4）。

动手之前，脚本先检查内存、磁盘、端口、网段冲突、已有的 Kubernetes 和外网连通，把所有问题一次列出并停下，主机上什么都没改（检查项见 运维手册 §1）。

本仓库当前为私有，上面这条会返回 404。请改用带凭据的形式；安装器自身也需要同一个 token 去解析并下载 release，所以用 sudo -E 把它带进去：

export FELIS_GITHUB_TOKEN=<对本仓库有读权限的 token>
printf 'header = "Authorization: Bearer %s"\n' "$FELIS_GITHUB_TOKEN" \
  | curl -fsSL --config - -H "Accept: application/vnd.github.raw" \
      https://api.github.com/repos/FelisMC/Felis/contents/deploy/bootstrap.sh \
  | sudo -E bash

token 经 stdin 交给 curl --config -，不放在命令行上：argv 在 /proc 下对本机任意用户可读， 而这正是安装器内部 github_api 采用同一写法的原因。

重跑这条命令也是把 felis-api 升到新版本的方式（felis setup 做不到，它用的是本机已有的二进制）。 重跑会沿用已安装的根域名，但不会沿用通道：若本机跟随 main，需一并 export FELIS_VERSION_BOOTSTRAP=dev。

从源码构建

本项目基于 Go 和 Node.js 开发：

# 后端（Go 1.26+）
go build -o felis ./cmd/felis

# 前端（Node.js 22+）
cd panel
npm ci
npm run build

# Docker 镜像
docker build -t felis:custom .

开源协议

本项目遵循 AGPL-3.0-only 开源协议。

协议注意事项

1. 衍生作品同样是 AGPL：分发本项目的副本或基于本项目衍生的软件时，必须以 AGPL-3.0 开源，并保留原作者的版权声明和许可声明。
2. 通过网络提供服务同样要开源（AGPL 第 13 条）：如果你把修改过的 Felis 架起来给别人用，即使从不分发任何二进制，也必须向这些用户提供你那份修改后的完整源码。这是 AGPL 相对 GPL 的唯一实质区别，而 Felis 正是一个跑在网络上的托管平台，所以这一条基本总会触发。
3. 免责声明：本项目按"原样"提供，作者不承担任何因使用本项目而产生的法律责任。

致谢

• Kubernetes：底层容器编排引擎
• K3s：轻量级 Kubernetes 发行版
• Cloudflare Zero Trust：零信任安全基础设施
• PostgreSQL：数据持久化
• React：前端用户界面框架
• Vite：前端构建工具
• TailwindCSS：CSS 框架
• Bubble Tea：TUI 框架
• Minecraft：让这一切值得做