From 241374db588de3aea7345b438be6fbf787d73a5a Mon Sep 17 00:00:00 2001 From: Lemon-miaow Date: Sun, 12 Jul 2026 03:41:52 +0800 Subject: [PATCH] docs: Update README.md --- README.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README_EN.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 182 insertions(+) create mode 100644 README.md create mode 100644 README_EN.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9ae310e --- /dev/null +++ b/README.md @@ -0,0 +1,92 @@ +# Felis + +一个 Kubernetes 驱动的 Minecraft 服务器托管平台，一行命令部署，自动管理服务器启动、备份与安全。 +A Kubernetes-driven Minecraft server hosting platform — one command to deploy, automatic lifecycle, backup, and security. + +[简体中文](README.md) | [English](README_EN.md) + +## 目录 + +- [特性](#特性) +- [使用方式](#使用方式) +- [从源码构建](#从源码构建) +- [开源协议](#开源协议) +- [致谢](#致谢) + +## 特性 + +- **即开即玩**：玩家连接服务器时自动启动，空闲后自动停止，像休眠一样省资源。 +- **Web 控制面板**：浏览器中查看服务器状态、管理备份、审批模组包、管理玩家账号。 +- **自动备份与恢复**：定时打包世界存档，支持从任意备份点一键恢复。 +- **智慧回收**：超过 15 天无人游玩的世界自动备份后删除，不浪费磁盘。 +- **多核心支持**：兼容 Paper、Fabric、Forge、NeoForge，通过 Velocity 代理统一入口。 +- **模组自助提交**：玩家可自行上传模组包，服主审批通过后自动构建并部署。 +- **Passkey 登录**：支持指纹、面容、硬件密钥等无密码认证方式。 +- **零信任安全**：基于 Cloudflare Zero Trust 架构，面板流量由 Cloudflare Access 保护，集群内 API 不暴露到公网。 + +## 使用方式 + +### 环境要求 + +- Linux 主机（amd64，Kernel ≥ 5.4） +- 4 GB 内存起步，推荐 8 GB +- 20 GB 磁盘起步 +- root 或 sudo 权限 + +### 一键安装 + +在准备好的 Linux 主机上执行： + +```bash +curl -fsSL https://raw.githubusercontent.com/MliroLirrorsIngenuity/Felis/main/deploy/bootstrap.sh | sudo bash +``` + +脚本会自动安装 K3s 集群，部署 Felis 控制平面，并启动 TUI 设置向导引导你完成域名、管理员账号等初始配置。 + +### 创建服务器 + +1. 打开浏览器访问配置的域名，登录控制面板 +2. 进入「服务器」页面，点击「创建服务器」 +3. 选择核心类型和版本，设置内存上限和子域名 +4. 点击创建，系统自动构建镜像并启动 + +### 玩家入驻 + +玩家在 Minecraft 客户端中添加 Velocity 代理地址即可进入大厅。使用 `/link` 命令获取绑定码，在面板中完成账号绑定。 + +## 从源码构建 + +本项目基于 Go 和 Node.js 开发： + +```bash +# 后端（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 . +``` + +更多开发细节请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 + +## 开源协议 + +本项目代码部分遵循 MIT License 开源协议。 + +### 协议注意事项 + +1. **保留版权声明**：在您分发本项目的副本或基于本项目衍生的软件中，必须包含原作者的版权声明和许可声明。 +2. **免责声明**：本项目按"原样"提供，作者不承担任何因使用本项目而产生的法律责任。 + +## 致谢 + +- [Kubernetes](https://kubernetes.io/) / [K3s](https://k3s.io/) —— 底层编排引擎 +- [Cloudflare Zero Trust](https://www.cloudflare.com/zero-trust/) —— 零信任安全基础设施 +- [PostgreSQL](https://www.postgresql.org/) —— 数据持久化 +- [React](https://react.dev/) + [Vite](https://vitejs.dev/) + [TailwindCSS](https://tailwindcss.com/) —— 前端技术栈 +- [Bubble Tea](https://github.com/charmbracelet/bubbletea) —— TUI 框架 +- [Minecraft](https://www.minecraft.net/) —— 让这一切值得做 diff --git a/README_EN.md b/README_EN.md new file mode 100644 index 0000000..0bcad46 --- /dev/null +++ b/README_EN.md @@ -0,0 +1,90 @@ +# Felis + +A Kubernetes-driven Minecraft server hosting platform — one command to deploy, automatic lifecycle, backup, and security. +一个 Kubernetes 驱动的 Minecraft 服务器托管平台，一行命令部署，自动管理服务器启动、备份与安全。 + +[简体中文](README.md) | [English](README_EN.md) + +## Table of Contents + +- [Features](#features) +- [Getting Started](#getting-started) +- [Build from Source](#build-from-source) +- [License](#license) +- [Acknowledgements](#acknowledgements) + +## Features + +- **Wake on Join**: Servers start automatically when a player connects, and stop when idle — like hibernate for your server. +- **Web Dashboard**: Monitor server status, manage backups, approve modpack submissions, and manage player accounts from your browser. +- **Auto Backup & Restore**: Scheduled world backups with one-click restore from any backup point. +- **World Reaper**: Worlds idle for more than 15 days are automatically backed up and removed to free disk space. +- **Multi-core Support**: Compatible with Paper, Fabric, Forge, and NeoForge, federated behind a Velocity proxy. +- **Modpack Submission**: Players submit custom modpacks; admin approval triggers automatic build and deployment. +- **Passkey Login**: Passwordless authentication via fingerprint, face recognition, or hardware security keys. +- **Zero Trust Security**: Cloudflare Access JWT + Tunnel secures the panel; the internal API is never exposed to the internet. + +## Getting Started + +### Requirements + +- Linux host (amd64, Kernel ≥ 5.4) +- 4 GB RAM minimum, 8 GB recommended +- 20 GB disk minimum +- root or sudo privileges + +### One-command Install + +```bash +curl -fsSL https://raw.githubusercontent.com/MliroLirrorsIngenuity/Felis/main/deploy/bootstrap.sh | sudo bash +``` + +The script automatically installs K3s, deploys the Felis control plane, and launches a TUI setup wizard to guide you through domain configuration, admin account setup, and more. + +### Creating a Server + +1. Open your browser and navigate to the configured domain +2. Go to the Servers page and click "Create Server" +3. Choose the core type and version, set memory limits and subdomain +4. Click create — the system auto-builds the image and launches the server + +### Player Onboarding + +Players add the Velocity proxy address to their Minecraft client to join the lobby. Use the `/link` command to get a binding code, then complete account linking in the dashboard. + +## Build from Source + +Felis is built with Go and Node.js: + +```bash +# Backend (Go 1.26+) +go build -o felis ./cmd/felis + +# Frontend panel (Node.js 22+) +cd panel +npm ci +npm run build + +# Docker image +docker build -t felis:custom . +``` + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for more details. + +## License + +The source code is released under the MIT License. + +### License Notes + +1. **Attribution**: Any distribution of this project or derivative works must include the original copyright notice and license statement. +2. **Disclaimer**: This project is provided "as is", without warranty of any kind. + +## Acknowledgements + +- [Kubernetes](https://kubernetes.io/) / [K3s](https://k3s.io/) — the underlying orchestration engine +- [Cloudflare Zero Trust](https://www.cloudflare.com/zero-trust/) — zero trust security infrastructure +- [PostgreSQL](https://www.postgresql.org/) — data persistence +- [React](https://react.dev/) + [Vite](https://vitejs.dev/) + [TailwindCSS](https://tailwindcss.com/) — frontend stack +- [Bubble Tea](https://github.com/charmbracelet/bubbletea) — TUI framework +- [Minecraft](https://www.minecraft.net/) — what makes this all worthwhile