Felis 文档

简体中文

English

简体中文

English

主题

贡献指南 ​

本文说明如何运行、测试和理解项目。修改应尽量小，并与当前代码保持一致。

项目结构 ​

Felis 是基于 Kubernetes 的 Minecraft 服务器控制平面。仓库分为四个主要部分：

  • cmd/felis/：单一 Go CLI 二进制，分发 api、operator、migrate、reaper、restore、manifests、breakGlass 等子命令。
  • internal/：API 处理器、存储迁移、Kubernetes 清单渲染、operator 协调、构建、备份、恢复及相关业务逻辑。
  • panel/：React/Vite Web 控制面板。
  • plugins/：Velocity、Paper、Fabric、Forge、NeoForge 的 Minecraft 侧插件和模组。

代码按职责拆分。优先修改实际负责该行为的最小模块，避免增加宽泛抽象或重写周边代码。

本地开发 ​

大部分日常开发可在 macOS 或 Linux 上完成，不需要完整集群。完整产品依赖 Postgres 和 Kubernetes，单元测试与前端开发可以本地运行。

建议准备：

  • 与 go.mod 一致的 Go 版本。
  • panel/ 所需的 Node.js 和 npm。
  • 插件开发所需的 JDK/Gradle（可选）。
  • 安装 Docker、k3s 和 Postgres 的干净 Linux 虚拟机或服务器，供集成测试使用（可选）。

检查工具版本：

bash
go version
node --version
npm --version
java -version

后端命令 ​

在仓库根目录运行：

bash
cd /path/to/Felis

运行全部 Go 测试：

bash
go test ./...

运行指定包的测试：

bash
go test ./internal/api
go test ./cmd/felis

隔离测试使用内存替身。业务存储 SQL 则单独针对真实 Postgres 验证，必须使用名称包含 pgint 的临时数据库。测试工具会删除并重建 schema，再重放内嵌迁移：

bash
FELIS_TEST_PG_URL='postgres://felis:***@127.0.0.1:5432/felis_pgint?sslmode=disable' \
  go test -tags pgint ./internal/pgint/ -v

修改 internal/api/pgrepo.go、internal/submit、internal/build、internal/dbbackup 中涉及 SQL 的代码后，应运行此测试。替身描述接口约定，这套测试负责发现替身与真实查询之间的偏差。felis db backup 和 restore 测试还需要与服务器大版本一致的 pg_dump、pg_restore、psql。服务器在容器中时，可像生产的 felis-postgres 一样在容器内执行：

bash
FELIS_TEST_PG_EXEC='docker exec -i <container>' FELIS_TEST_PG_URL=... go test -tags pgint ./internal/pgint/

构建 CLI：

bash
go build -o /tmp/felis-dev ./cmd/felis
/tmp/felis-dev help

在不连接集群的情况下渲染 Kubernetes 清单：

bash
/tmp/felis-dev manifests \
  --felis-image registry.felis.svc:5000/felis:dev \
  --velocity-cidr 10.0.0.5/32

felis api、felis operator、felis migrate up、felis reaper 是实际运行命令，需要 Postgres 和／或 Kubernetes 配置，不适合作为快速本地迭代的起点。

前端命令 ​

进入前端工作目录：

bash
cd /path/to/Felis/panel

安装依赖：

bash
npm ci

连接 http://localhost:8080 上的真实后端：

bash
npm run dev

使用本地模拟 API：

bash
npm run dev:mock

模拟开发服务器启动时会输出账号、绑定码和重置命令。没有运行 Go API 和集群时，可用它开发前端。

常用前端检查：

bash
npm run typecheck
npm test
npm run build

模拟 API ​

前端模拟 API 位于 panel/dev/，仅由 npm run dev:mock 加载。模拟逻辑不得进入生产代码或业务组件。

在前端目录运行：

bash
cd /path/to/Felis/panel
npm run dev:mock

当前模拟账号：

用户名密码场景
ownerdevpassword已绑定的管理员
userdevpassword未绑定的普通用户
linkeddevpassword已绑定的普通用户
setupdevpassword首次登录需要修改密码的管理员

模拟 Minecraft 绑定码：

text
LINK1234

重置模拟状态：

bash
curl -X POST http://127.0.0.1:5173/api/v1/__mock/reset

模拟规则：

  • 模拟专用逻辑保留在 panel/dev/。
  • panel/src/ 不得导入模拟代码。
  • 响应结构与 panel/src/lib/types.ts 和 Go API 处理器保持一致。
  • 使用真实错误码，不能只覆盖成功情况。
  • 不得将模拟数据呈现为生产实时数据。

完整集成环境 ​

在 Linux 主机的仓库根目录运行集成和部署命令：

bash
cd /path/to/Felis

设置 TUI 面向干净的 Linux 主机，不适合普通 macOS 开发机：

bash
sudo felis setup

常用覆盖配置：

bash
export FELIS_REPO_URL=<your fork url>
export FELIS_REF=<your branch>          # pins the build; overrides the channel below
export FELIS_IMAGE=felis:dev
export FELIS_ROOT_DOMAIN=<node-ip>.nip.io

安装器默认使用最新的已发布 GitHub release。开发分支需要显式选择；私有 fork 还需要用于查询发布版和克隆的令牌：

bash
export FELIS_VERSION_BOOTSTRAP=dev      # build main instead of the newest release
export FELIS_GITHUB_TOKEN=<token>       # private forks only: read access to the fork

首次 vX.Y.Z 标签发布前，也需使用 dev；没有发布版时默认通道无法解析，安装器会停止并提示此选项。

发布版默认下载该标签由 CI 生成的二进制、镜像和 Velocity 插件，校验 SHA256SUMS 后导入；面板内嵌于同一二进制（internal/panel）。dev 克隆并编译源码。发布版附件缺失或校验失败时，仅对应组件回退到同一标签的本机构建，并输出警告；不会悄悄切换提交。设置 FELIS_REF 会强制源码路径。具体安装行为以安装与部署和二进制与镜像来源为准。

通道决定二进制里的版本戳（felis version），供 felis update 与上游比较：发布版使用标签，开发版使用 <latest-tag>+g<short-sha>；固定 FELIS_REF 跳过通道及标签查询，使用 v0.0.0+g<short-sha>。未设置版本戳的构建显示 dev，禁用更新报告；测试该路径时，应通过 bootstrap.sh 或 Dockerfile 的 FELIS_VERSION 构建参数设置版本，不要仅执行普通 go build。

设置流程包装主机初始化，随后在同一命令中完成所有者账号及可选 Cloudflare 边缘设置。调试安装器时，仍可直接运行 deploy/bootstrap.sh 做底层主机配置。

请使用虚拟机或可丢弃的 Linux 服务器作为集成、验收环境，普通编码和快速测试仍在本地完成。

插件开发 ​

插件说明见服务端插件，各模块保持独立 Gradle 构建：

bash
# cwd: repository root
cd /path/to/Felis

bash plugins/velocity/gradlew -p plugins/velocity build
bash plugins/paper/gradlew -p plugins/paper build
bash plugins/fabric/gradlew -p plugins/fabric build
bash plugins/forge/gradlew -p plugins/forge build
bash plugins/neoforge/gradlew -p plugins/neoforge build
  • 所有模块都使用各自的 Gradle wrapper，版本和校验和由模块固定。
  • Java 和 Minecraft 版本要求以插件版本表为准；不要把各模块的工具链要求混为一谈。
  • 首次构建会下载和重映射 Minecraft 依赖，可能较慢。

前端状态 ​

面板仍处于早期开发阶段。目前已提供服务器列表与状态、启停和认领、控制台/RCON、文件管理、账号绑定、白名单/封禁/OP/LuckPerms、计划任务及备份恢复等功能。当前功能范围以项目说明与具体后端接口为准；模拟 API 仅用于本地前端开发。

新增功能时如实反映后端状态。没有实际端点时使用明确的占位提示，不能用假数据冒充实时数据；更完整的交互深度及组件、浏览器测试仍需持续完善。

国际化说明 ​

这里讨论的是 Felis 控制面板的国际化，文档站的中英文切换是独立功能。面板尚未建立完整 i18n 系统，用户可见字符串多数仍内联于 TSX 或辅助函数。

优先覆盖：

  • 根据稳定 API 错误码映射的错误消息。
  • 导航标签、页面标题与主要操作。
  • 阶段、状态标签。
  • 空白、加载、错误状态。

建议从以下结构开始：

text
panel/src/i18n/
  index.ts
  en.ts
  zh-CN.ts

先使用小型类型化词典。需要运行时切换语言、复数规则、外部翻译流程或更复杂本地化时，再引入 i18next/react-i18next 等库。

除非贡献者确有需要，否则不翻译代码注释、内部日志或模拟环境专用终端消息。

贡献规范 ​

沿用现有代码，修改范围小且便于审阅。

  • 优先最小修改，避免重写。
  • 新抽象应消除实际重复，或表达清晰的局部概念。
  • 前端模拟代码不得进入业务组件。
  • 后端测试靠近负责该行为的包。
  • 保持公共 API 和持久化结构，除非修改明确要求更新约定。
  • 不提交 panel/dist/、node_modules/、Gradle 构建目录或本地二进制等生成产物。

欢迎使用 AI 辅助，但贡献者负责最终结果。不能提交全部由 AI 生成、本人未审阅的 PR。低质量内容、大范围无视现有设计的重写、未验证修改，或作者无法解释的代码，不会被接受。

交付前执行最小且有意义的检查：

bash
go test ./...
cd panel && npm run typecheck && npm test && npm run build

无法运行相关检查时，交付说明中须明确说明。

来源：CONTRIBUTING.md。安装及功能状态另据主仓库 README 和插件文档同步。

FelisMC · 使用 VitePress 构建