cwhitelist

CWhitelist – Minecraft 高级白名单管理

---

✨ 功能特性

🔐 多维身份验证

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

🌐 API 集成

• 双模式运行：优先使用 API，失败时回退到本地模式
• 集中管理：在多台服务器间共享统一的数据源
• 实时同步：自动更新白名单
• 基于令牌的身份验证：支持权限级别的安全 API 通信
• 运行状况监控：内置 API 健康检查

📊 智能日志系统

• 完整的审计记录：记录玩家登录尝试及时间戳
• 日志轮换：根据大小限制自动管理文件
• 保留策略：可配置日志保留时长
• 远程日志记录：可选通过 API 记录事件

🛠️ 高级管理

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

🎮 使用体验

• 基于权限的命令：精细控制命令访问权限
• 实时反馈：操作完成后立即确认
• 全面状态信息：详细显示 API 和令牌信息
• 回退保护：API 中断期间可无缝切换到本地模式

🚀 快速开始

安装

1. 从cwhitelist-x.x-NeoForge-1.21.x.jar下载最新版本Releases
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  # Disable API integration

启用 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 身份验证令牌 |
| useHeaderAuth | true | 使用 Authorization 请求头（true）或查询参数（false） |
| timeoutSeconds | 10 | API 请求超时时间 |
| cacheDurationSeconds | 30 | 本地缓存时长（设为 0 可禁用） |
| syncOnStartup | true | 服务器启动时与 API 同步 |
| logLoginEvents | true | 将登录事件发送到 API |
| serverId | "" | 可选的服务器标识符 |
| sendServerId | false | 在 API 请求中包含服务器 ID |
| includeExpired | false | 同步时包含已过期条目 |

📋 命令参考

🎮 玩家命令

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

👑 管理员命令

基础白名单管理：

# Add entries
/cwhitelist add name <username>
/cwhitelist add uuid <uuid>
/cwhitelist add ip <ip-address>

# Remove entries
/cwhitelist remove name <username>
/cwhitelist remove uuid <uuid>
/cwhitelist remove ip <ip-address>

# View entries
/cwhitelist list

# Reload configuration
/cwhitelist reload

API 管理命令：

# Check API status
/cwhitelist api status

# Verify API token
/cwhitelist api verify

# Perform health check
/cwhitelist api health

# Manual sync from API
/cwhitelist api sync

# Clear API cache
/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 – 验证令牌有效性（需要身份验证）

令牌权限

API 令牌必须具有相应权限：

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

身份验证方式

请求头身份验证（推荐）：

Authorization: Bearer your-token-here

查询参数身份验证：

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

🗂️ 文件结构

config/
├── cwhitelist-common.toml          # Main configuration
└── cwhitelist_entries.json         # Local whitelist backup

logs/
└── cwhitelist/
    ├── 2024-01-01.log              # Daily log files
    └── 2024-01-01.log.1704067200000 # Rotated logs

数据文件格式

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 连接

🛡️ 安全功能

身份验证安全

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

数据保护

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

网络安全

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

📈 性能优化

缓存策略

// Configurable cache duration
cacheDurationSeconds = 30  // Balance between freshness and API load

// Smart cache invalidation
- Add/Remove operations clear cache
- Manual sync refreshes cache
- Automatic periodic validation

异步操作

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

🐛 故障排除

常见问题

API 连接失败：

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

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

身份验证失败：

[Server] ERROR Token verification failed: Authentication required

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

权限被拒绝：

[Server] ERROR Token does not have write permission

解决方案： 生成具有适当权限的新令牌，或使用具有正确权限的现有令牌。

缓存问题：

[Server] DEBUG API cache cleared

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

日志文件

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

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

调试命令

# Check current mode
/cwhitelist list

# Verify API connectivity
/cwhitelist api health

# Test token permissions
/cwhitelist api verify

# View detailed status
/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: 未授权 – 令牌无效或已过期
• 403: 禁止访问 – 权限不足
• 429: 请求过于频繁 – 自动退避重试
• 500+: 服务器错误 – 回退到本地模式

🔧 开发

从源代码构建

# Clone repository
git clone https://github.com/SkyDreamLG/CWhitelist.git
cd CWhitelist

# Build with Gradle
./gradlew build

# Output: 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              # Main mod class
├── Config.java                  # Configuration management
├── ApiClient.java               # API communication
├── WhitelistManager.java        # Core whitelist logic
├── WhitelistCommand.java        # Command implementation
├── LogHandler.java              # Logging system
└── WhitelistEntry.java          # Data model

扩展模组

添加新的身份验证方式：

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

自定义 API 集成：

// Implement custom ApiClient interface
public interface CustomApiClient {
    CompletableFuture<List<WhitelistEntry>> fetchEntries();
    CompletableFuture<Boolean> validateEntry(WhitelistEntry entry);
}

🤝 参与贡献

欢迎贡献！详情请参阅贡献指南。

开发流程

1. 复刻代码仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建拉取请求

编码规范

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

第三方许可证

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

🌟 致谢

• NeoForge 团队提供了出色的模组开发框架
• Mojang Studios开发了 Minecraft
• 贡献者帮助改进本项目
• 社区提供反馈和支持

📞 支持

• 文档: GitHub Wiki
• 问题反馈: GitHub Issues
• 讨论: GitHub Discussions
• 电子邮箱: [email protected]

---

🎯 快速参考

部署检查清单

• [ ] 确认已安装 Java 17 或更高版本
• [ ] 配置 API 令牌（如果使用 API 模式）
• [ ] 设置适当的权限级别
• [ ] 测试 API 连通性
• [ ] 配置日志记录偏好
• [ ] 设置日志轮转计划
• [ ] 测试本地回退功能

性能优化建议

1. 缓存时长: 根据更新频率设置cacheDurationSeconds
2. 日志轮转: 配置logCutSizeMB以避免磁盘空间不足
3. 超时设置: 根据网络延迟调整timeoutSeconds
4. API 调用: 尽量避免在高峰时段调用 API

安全最佳实践

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

---

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