开发与构建 - lmxdg/ZeroLogin GitHub Wiki

开发与构建

本页面向希望从源码构建或参与开发的用户。

环境要求

工具 版本
JDK 17 或更高
Maven 3.8+
网络 可访问 PaperMC 仓库与 Maven 中央仓库

构建

git clone https://github.com/lmxdg/ZeroLogin.git
cd ZeroLogin
mvn clean package

产物：target/ZeroLogin-<版本>.jar（约 14 MB，已内联并 relocate SQLite JDBC 驱动）

运行测试

mvn test

共 43 个单元测试，覆盖：

  • 口令散列（加盐、校验、参数升级、畸形输入容错）
  • 密码校验规则（长度、混合字符）
  • 消息解析（语言归一化、auto 回退）
  • 账号编解码（转义、往返、损坏检测）
  • 文件存储读写（保存 / 加载 / 删除 / 改名 / 损坏跳过）
  • SQLite 存储读写（建库、UPSERT、改名、批量 saveAll、重启持久化）
  • 后端间数据迁移（file → sqlite、sqlite → file、目标非空中止、force 备份、同名冲突跳过）

兼容性门禁

这是本项目保证"单 JAR 兼容 1.20 ~ 26.1.2"的核心手段：针对 API 上下限分别编译，只有源码仅使用两端点 API 交集时才能双双通过。

mvn clean package              # 对齐 1.20.1 API（下限）
mvn -Papi-latest clean package # 对齐 26.1.2 API（上限）

两条命令均编译通过，才说明单 JAR 在全区间可用。另有 api-1202、api-12111 两个中间版本 Profile 用于额外抽查。

兼容性设计三要点

  1. api-version: '1.20' Paper 采用「api-version ≤ 服务端版本即允许加载」规则，声明 1.20 可被 1.20 与 26.x 同时加载。

  2. 编译目标 Java 17 1.20 运行于 Java 17，26.x 运行于 Java 25。Java 17 字节码（major 61）可直接在 Java 25 JVM 上运行，无需多版本构建。

  3. 只用 API 交集 开发期对 1.20.1 与 26.1.2 两个 paper-api 包做类与方法签名的逐一比对，确保调用的 API 在两端均存在。

项目结构

src/main/java/dev/zerologin/
├── ZeroLoginPlugin.java        # 插件主类：装配与生命周期、存储切换、旧数据自动导入
├── auth/
│   ├── AuthService.java        # 纯认证逻辑（密码规则、散列、校验）
│   ├── PasswordHasher.java     # PBKDF2 散列实现
│   └── SessionManager.java     # 内存会话与 IP 会话窗口
├── command/                    # 各命令执行器（含 /zerologin 的 5 个子命令）
├── config/Settings.java        # 配置强类型读取
├── listener/AuthListener.java  # 未认证保护拦截
├── locale/Messages.java        # 本地化：7 语言、auto 解析、模板导出
└── storage/
    ├── AuthStore.java          # 存储抽象（全部方法返回 CompletableFuture）
    ├── AuthRecord.java         # 账号数据载体
    ├── FileAuthStore.java      # 文件后端（v1.0）
    ├── SqliteAuthStore.java    # SQLite 后端（WAL + 专用 IO 线程）
    ├── StorageMigrator.java    # 后端间非破坏式迁移
    └── AccountCodec.java       # 账号文件编解码

src/main/resources/
├── plugin.yml                  # 插件描述（api-version: '1.20'）
├── config.yml                  # 默认配置
├── messages_zh_cn.yml          # 简体中文消息
├── messages_zh_tw.yml          # 繁體中文消息
├── messages_en_us.yml          # 英文消息
├── messages_ja_jp.yml          # 日本語メッセージ
├── messages_ko_kr.yml          # 한국어 메시지
├── messages_ru_ru.yml          # Русские сообщения
└── messages_es_es.yml          # Mensajes en español

src/test/java/dev/zerologin/    # 单元测试（43 个）

设计原则

  • 认证逻辑与 Bukkit 解耦：AuthService / PasswordHasher / AccountCodec / FileAuthStore / SqliteAuthStore 不依赖 Bukkit，可直接单测。
  • 加密零外部依赖：仅用 JDK 自带加密实现，避免依赖冲突与类加载隔离问题。
  • 存储后端抽象：认证流程只依赖 AuthStore 接口，StorageMigrator 同样只面向接口，未来新增后端（如 MySQL）无需改认证与迁移代码。
  • 异步 IO：SQLite 的所有 SQL 在专用 IO 线程串行执行，调用方拿到 CompletableFuture，主线程零阻塞。
  • 账号文件自包含：file 后端用自研 AccountCodec 序列化，不依赖 Bukkit YAML，规避跨版本配置 API 变动。

相关： 安装指南 · 更新日志