cwhitelist

cwhitelist

为了解决服务器不在在线模式时的白名单问题

CWhitelist - Minecraft 高级白名单管理


🔒 适用于现代 Minecraft 服务器的智能白名单系统，支持 API 集成

release issues license NeoForge

English | 中文

✨ 功能特性

🔐 多维认证

  • 玩家名：传统的基于用户名的白名单验证
  • UUID：安全的玩家身份识别
  • IP 地址：基于 IP 的认证，支持通配符（例如 192.168.*.*）
  • 可配置检查类型：独立启用/禁用每种认证方法

🌐 API 集成

  • 双模式运行：API 优先，本地回退
  • 集中管理：跨多服务器统一数据源
  • 实时同步：自动更新白名单
  • 基于 Token 的认证：安全的 API 通信，带权限等级
  • 健康监控：内置 API 健康检查

📊 智能日志系统

  • 全面审计追踪：记录玩家登录尝试及时间戳
  • 日志轮转：自动文件管理，带大小限制
  • 保留策略：可配置的日志保留期限
  • 远程日志：可选的基于 API 的事件记录

🛠️ 高级管理

  • 异步操作：非阻塞的 API 调用和文件操作
  • 智能缓存：可配置的缓存时长以减少 API 负载
  • 错误恢复：API 不可用时优雅降级
  • 热重载：无需重启服务器即可应用配置更改

🎮 用户体验

  • 基于权限的命令：细粒度的命令访问控制
  • 实时反馈：即时操作确认
  • 全面状态：详细的 API 和 Token 信息
  • 回退保护：API 中断时无缝切换至本地操作

🚀 快速开始

安装

  1. 从 Releases 下载最新的 cwhitelist-x.x-NeoForge-1.21.x.jar
  2. 将其放入服务器的 mods 文件夹
  3. 启动服务器以生成默认配置
  4. 配置完成后重启服务器

基本配置

仅本地模式：

# config/cwhitelist-common.toml
[basic]
enableLogging = true
logRetentionDays = 7
logCutSizeMB = 10
[checks]
enableNameCheck = true
enableUuidCheck = true
enableIpCheck = true


[api]
enableApi = false  # 禁用 API 集成

启用 API 模式：

[api]
enableApi = true
baseUrl = "http://your-api-server.com/api"
token = "your-secure-api-token-here"
useHeaderAuth = true
timeoutSeconds = 10
syncOnStartup = true
logLoginEvents = true

后端程序仓库地址：cwhitelist-backend

⚙️ 配置指南

基本设置 ([basic])

参数 默认值 描述 范围
enableLogging true 启用本地文件日志记录 布尔值
logRetentionDays 7 日志文件保留天数 1-365
logCutSizeMB 10 日志文件最大大小（MB） 1-100

检查设置 ([checks])

参数 默认值 描述
enableNameCheck true 按玩家名验证
enableUuidCheck true 按玩家 UUID 验证
enableIpCheck true 按 IP 地址验证

API 设置 ([api])

参数 默认值 描述
enableApi false 启用 API 集成
baseUrl http://127.0.0.1:5000/api API 服务器基础 URL
token "" API 认证 Token
useHeaderAuth true 使用 Authorization 请求头（true）或查询参数（false）
timeoutSeconds 10 API 请求超时时间
cacheDurationSeconds 30 本地缓存时长（0 表示禁用）
syncOnStartup true 服务器启动时与 API 同步
logLoginEvents true 将登录事件发送至 API
serverId "" 可选的服务器标识符
sendServerId false 在 API 请求中包含服务器 ID
includeExpired false 同步时包含已过期条目

📋 命令参考

🎮 玩家命令

命令 描述 权限
无直接玩家命令 所有白名单管理均需管理员权限 -

👑 管理员命令

基本白名单管理：

# 添加条目
/cwhitelist add name <username>
/cwhitelist add uuid <uuid>
/cwhitelist add ip <ip-address>
移除条目


/cwhitelist remove name <username>
/cwhitelist remove uuid <uuid>
/cwhitelist remove ip <ip-address>


查看条目


/cwhitelist list


重载配置


/cwhitelist reload

API 管理命令：

# 检查 API 状态
/cwhitelist api status
验证 API Token


/cwhitelist api verify


执行健康检查


/cwhitelist api health


从 API 手动同步


/cwhitelist api sync


清除 API 缓存


/cwhitelist api clearcache

🔌 API 集成

API 要求

CWhitelist 支持与实现以下端点的兼容 API 服务器集成：

  • GET /health - 健康检查（无需认证）
  • GET /whitelist/sync - 获取白名单条目（需要读取权限）
  • POST /whitelist/entries - 添加新条目（需要写入权限）
  • DELETE /whitelist/entries/{type}/{value} - 移除条目（需要删除权限）
  • POST /login/log - 记录登录事件（需要写入权限）
  • GET /tokens/verify - 验证 Token 有效性（需要认证）

Token 权限

API Token 必须使用具有相应权限的账号创建：

  • 读取：同步白名单所需
  • 写入：添加条目和记录事件所需
  • 删除：移除条目所需
  • 管理：系统管理（通常不需要）

认证方法

请求头认证（推荐）：

Authorization: Bearer your-token-here

查询参数认证：

GET /api/whitelist/sync?token=your-token-here

🗂️ 文件结构

config/
├── cwhitelist-common.toml          # 主配置
└── cwhitelist_entries.json         # 本地白名单备份
logs/
└── cwhitelist/
    ├── 2024-01-01.log              # 每日日志文件
    └── 2024-01-01.log.1704067200000 # 轮转日志

数据文件格式

cwhitelist_entries.json:

[
  {"type": "name", "value": "PlayerOne"},
  {"type": "uuid", "value": "123e4567-e89b-12d3-a456-426614174000"},
  {"type": "ip", "value": "192.168.1.*"}
]

🔄 运行模式

模式 1：仅本地（默认）

  • 所有数据存储于本地
  • 无外部依赖
  • 部署简单
  • 适用于单服务器

模式 2：API 优先带回退

  • 主要：与中央 API 同步
  • 回退：API 不可用时使用本地缓存
  • API 恢复时自动重新同步
  • 适用于多服务器设置

模式 3：仅 API

  • 所有操作通过 API 进行
  • 无本地白名单存储
  • 集中管理
  • 需要可靠的 API 连接

🛡️ 安全特性

认证安全

  • 基于 Token 的认证：安全的 API 通信
  • 权限验证：细粒度的访问控制
  • Token 过期：自动的 Token 有效性检查
  • 无硬编码密钥：基于配置文件的管理方式

数据保护

  • 本地加密：配置文件中的敏感数据
  • 访问控制：仅限管理员命令权限（等级 4）
  • 审计日志：全面的访问日志记录
  • 输入验证：经净化的 API 请求参数

网络安全

  • 支持 HTTPS：安全的 API 通信（配置后）
  • 超时保护：可配置的请求超时时间
  • 重试逻辑：优雅的错误处理
  • 速率限制：内置重试逻辑和请求排队

📈 性能优化

缓存策略

// 可配置的缓存时长
cacheDurationSeconds = 30  // 在新鲜度和 API 负载之间取得平衡
// 智能缓存失效


    

  • 添加/移除操作清除缓存
    • 

  • 手动同步刷新缓存
    • 

  • 自动定期验证

异步操作

  • 非阻塞 API 调用：HTTP 请求在独立线程上执行
  • 并行处理：并发请求处理
  • 队列管理：有序的请求处理
  • 资源优化：高效的内存使用

🐛 故障排除

常见问题

API 连接失败：

[Server] WARN API health check failed, falling back to local file

解决方案： 验证 API 服务器是否正在运行且可访问。检查网络连接和防火墙设置。

认证失败：

[Server] ERROR Token verification failed: Authentication required

解决方案： 验证 API Token 是否正确且具有所需权限。使用 /cwhitelist api verify 进行测试。

权限被拒绝：

[Server] ERROR Token does not have write permission

解决方案： 使用相应权限的账号生成新 Token，或使用具有正确权限的现有 Token。

缓存问题：

[Server] DEBUG API cache cleared

解决方案： 缓存会在修改时自动清除。使用 /cwhitelist api clearcache 强制刷新。

日志文件

查看日志文件以获取详细的错误信息：

  • 位置：logs/cwhitelist/YYYY-MM-DD.log
  • 包含内容：API 调用、认证尝试、错误
  • 格式：[HH:mm:ss] [RESULT] PlayerName UUID IP

调试命令

# 检查当前模式
/cwhitelist list
验证 API 连接


/cwhitelist api health


测试 Token 权限


/cwhitelist api verify


查看详细状态


/cwhitelist api status

🧩 API 兼容性

支持的 API 版本

  • 最低：v1.0.0
  • 推荐：v1.1.0+
  • 测试环境：CWhitelist API v1.2.0

预期响应格式

{
  "success": true,
  "message": "Operation successful",
  "data": { /* operation-specific data */ }
}

错误处理

该模组处理以下 HTTP 状态码：

  • 200-299：成功 - 处理响应
  • 401：未授权 - Token 无效/已过期
  • 403：禁止 - 权限不足
  • 429：请求过多 - 自动重试并退避
  • 500+：服务器错误 - 回退至本地模式

🔧 开发

从源码构建

# 克隆仓库
git clone https://github.com/SkyDreamLG/CWhitelist.git
cd CWhitelist
使用 Gradle 构建


./gradlew build


输出：build/libs/cwhitelist-x.x.x.jar

前置要求

  • Java：17 或更高版本
  • Minecraft：1.21.x
  • NeoForge：最新推荐构建
  • 构建工具：Gradle 8.0+

项目结构

src/main/java/org/skydream/cwhitelist/
├── Cwhitelist.java              # 主模组类
├── Config.java                  # 配置管理
├── ApiClient.java               # API 通信
├── WhitelistManager.java        # 核心白名单逻辑
├── WhitelistCommand.java        # 命令实现
├── LogHandler.java              # 日志系统
└── WhitelistEntry.java          # 数据模型

扩展模组

添加新的认证方法：

  1. 在 Config.java 中更新新的检查设置
  2. 修改 WhitelistManager.isAllowed() 方法
  3. 添加相应的命令处理器
  4. 更新 API 客户端以支持新的端点

自定义 API 集成：

// 实现自定义 ApiClient 接口
public interface CustomApiClient {
    CompletableFuture<List<WhitelistEntry>> fetchEntries();
    CompletableFuture<Boolean> validateEntry(WhitelistEntry entry);
}

🤝 参与贡献

我们欢迎任何形式的贡献！请参阅我们的 贡献指南 了解详情。

开发流程

  1. Fork 本仓库
  2. 创建功能分支（git checkout -b feature/amazing-feature）
  3. 提交更改（git commit -m 'Add amazing feature'）
  4. 推送到分支（git push origin feature/amazing-feature）
  5. 发起 Pull Request

编码规范

  • 遵循现有代码风格和模式
  • 添加完整的 JavaDoc 注释
  • 为新功能包含单元测试
  • 更新 API 变更的文档
  • 确保向后兼容性

第三方许可证

  • Gson：Apache 许可证 2.0
  • NeoForge：LGPL 2.1
  • SLF4J：MIT 许可证

🌟 致谢

  • NeoForge 团队，感谢优秀的模组框架
  • Mojang Studios，感谢 Minecraft
  • 贡献者，帮助改进此项目
  • 社区，提供反馈和支持

📞 支持

由 SkyDream Team 用 ❤️ 构建
如果您觉得这个项目有用，请在 GitHub 上给它一个 ⭐ 吧！

🎯 快速参考

部署清单

- [ ] 验证 Java 17+ 安装 - [ ] 配置 API Token（如果使用 API 模式） - [ ] 设置适当的权限等级 - [ ] 测试 API 连接 - [ ] 配置日志偏好 - [ ] 设置日志轮转计划 - [ ] 测试本地回退功能

性能提示

  1. 缓存时长：根据更新频率设置 cacheDurationSeconds
  2. 日志轮转：配置 logCutSizeMB 以防止磁盘空间问题
  3. 超时设置：根据网络延迟调整 timeoutSeconds
  4. API 调用：在高峰时段尽量减少 API 调用

安全最佳实践

  1. Token 安全：将 Token 存储在配置中，而不是代码中
  2. 最小权限：授予最低所需权限
  3. 定期审计：检查日志文件以发现可疑活动
  4. API 安全：使用 HTTPS 进行 API 通信
  5. 备份策略：定期备份本地白名单文件

准备好保护您的 Minecraft 服务器了吗？ 立即安装 CWhitelist，体验专业级的白名单管理！