CWhitelist - Minecraft 高级白名单管理
? 具有 API 集成的智能白名单系统,适用于现代 Minecraft 服务器
✨ 功能特性
? 多维度身份验证
- 玩家名称:基于传统用户名的白名单机制
- UUID:安全的玩家身份标识
- IP 地址:支持通配符的 IP 认证(例如
192.168.*.*)
- 可配置的检查类型:独立启用或禁用每种身份验证方式
? API 集成
- 双模式运行:优先使用 API,本地作为后备方案
- 集中化管理:跨多个服务器的单一数据源
- 实时同步:自动更新白名单
- 基于令牌的认证:具有权限级别的安全 API 通信
- 健康监控:内置 API 健康检查
? 智能日志系统
- 全面的审计追踪:带有时间戳的玩家登录尝试记录
- 日志轮转:自动文件管理并限制大小
- 保留策略:可配置的日志保留期限
- 远程日志记录:可选的基于 API 的事件日志记录
?️ 高级管理
- 异步操作:非阻塞式 API 调用和文件操作
- 智能缓存:可配置的缓存时长以减少 API 负载
- 错误弹性:当 API 不可用时优雅降级
- 热重载:无需重启服务器即可更改配置
? 用户体验
- 基于权限的命令:细粒度的命令访问控制
- 实时反馈:即时操作确认
- 全面的状态信息:详细的 API 和令牌信息
- 后备保护:API 中断期间无缝进行本地操作
? 快速开始
安装
- 从 Releases 下载最新的
cwhitelist-x.x-NeoForge-1.21.x.jar
- 将其放入服务器的
mods 文件夹中
- 启动服务器以生成默认配置
- 配置完成后重启服务器
基本配置
仅本地模式:
# 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 |
启用本地文件日志记录 |
boolean |
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 |
同步时包含已过期的条目 |
? 命令参考
? 玩家命令
| 命令 |
描述 |
权限 |
| 无直接玩家命令 |
所有白名单管理需要管理员权限 |
- |
? 管理员命令
基本白名单管理:
# 添加条目
/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 令牌
/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 - 验证令牌有效性(需要身份验证)
令牌权限
API 令牌必须使用适当的权限创建:
- 读取 (Read):同步白名单所需
- 写入 (Write):添加条目和记录事件所需
- 删除 (Delete):移除条目所需
- 管理 (Manage):系统管理(通常不需要)
身份验证方法
标头认证(推荐):
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 连接
?️ 安全功能
身份验证安全
- 基于令牌的认证:安全的 API 通信
- 权限验证:细粒度的访问控制
- 令牌过期:自动检查令牌有效性
- 无硬编码密钥:基于配置文件的令牌管理
数据保护
- 本地加密:配置中的敏感数据
- 访问控制:仅限管理员的命令权限(等级 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 令牌是否正确且具有所需的权限。使用 /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
调试命令
# 检查当前模式
/cwhitelist list
# 验证 API 连接性
/cwhitelist api health
# 测试令牌权限
/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": { /* 特定于操作的数据 */ }
}
错误处理
该模组处理以下 HTTP 状态码:
200-299:成功 - 处理响应
401:未授权 - 令牌无效或已过期
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 # 数据模型
扩展模组
添加新的认证方式:
- 在
Config.java 中更新新的检查设置
- 修改
WhitelistManager.isAllowed() 方法
- 添加相应的命令处理器
- 更新 API 客户端以支持新端点
自定义 API 集成:
// 实现自定义 ApiClient 接口
public interface CustomApiClient {
CompletableFuture<List<WhitelistEntry>> fetchEntries();
CompletableFuture<Boolean> validateEntry(WhitelistEntry entry);
}
? 贡献指南
我们欢迎贡献!详情请参阅我们的 贡献指南。
开发工作流
- Fork 仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature)
- 提交更改 (
git commit -m 'Add amazing feature')
- 推送到分支 (
git push origin feature/amazing-feature)
- 发起 Pull Request
编码规范
- 遵循现有的代码风格和模式
- 添加全面的 JavaDoc 注释
- 为新功能包含单元测试
- 为 API 更改更新文档
- 确保向后兼容性
第三方许可证
- Gson: Apache License 2.0
- NeoForge: LGPL 2.1
- SLF4J: MIT License
? 致谢
- NeoForge Team 提供的优秀模组开发框架
- Mojang Studios 开发的 Minecraft
- Contributors 帮助改进此项目的贡献者
- Community 提供的反馈和支持
? 支持
Built with ❤️ by SkyDream Team
If you find this project useful, please consider giving it a ⭐ on GitHub!
? 快速参考
部署清单
- 验证 Java 17+ 安装
- 配置 API 令牌(如果使用 API 模式)
- 设置适当的权限级别
- 测试 API 连通性
- 配置日志偏好
- 设置日志轮转计划
- 测试本地回退功能
性能建议
- 缓存时长:根据更新频率设置
cacheDurationSeconds
- 日志轮转:配置
logCutSizeMB 以防止磁盘空间问题
- 超时设置:根据网络延迟调整
timeoutSeconds
- API 调用:在高峰时段尽量减少 API 调用
安全最佳实践
- 令牌安全:将令牌存储在配置文件中,而非代码中
- 最小权限原则:授予所需的最小权限
- 定期审计:审查日志文件以查找可疑活动
- API 安全:使用 HTTPS 进行 API 通信
- 备份策略:定期备份本地白名单文件
准备好保护您的 Minecraft 服务器了吗? 立即安装 CWhitelist,体验专业级的白名单管理!
CWhitelist - Advanced Whitelist Management for Minecraft
? Intelligent Whitelist System with API Integration for Modern Minecraft Servers
✨ Features
? Multi-Dimensional Authentication
- Player Name: Traditional username-based whitelisting
- UUID: Secure player identification
- IP Address: IP-based authentication with wildcard support (e.g.,
192.168.*.*)
- Configurable Check Types: Enable/disable each authentication method independently
? API Integration
- Dual-Mode Operation: API-first with local fallback
- Centralized Management: Single source of truth across multiple servers
- Real-time Synchronization: Automatic whitelist updates
- Token-based Authentication: Secure API communication with permission levels
- Health Monitoring: Built-in API health checks
? Intelligent Logging System
- Comprehensive Audit Trail: Player login attempts with timestamps
- Log Rotation: Automatic file management with size limits
- Retention Policies: Configurable log retention periods
- Remote Logging: Optional API-based event logging
?️ Advanced Management
- Async Operations: Non-blocking API calls and file operations
- Smart Caching: Configurable cache durations to reduce API load
- Error Resilience: Graceful degradation when API is unavailable
- Hot Reloading: Configuration changes without server restart
? User Experience
- Permission-Based Commands: Granular command access control
- Real-time Feedback: Immediate operation confirmation
- Comprehensive Status: Detailed API and token information
- Fallback Protection: Seamless local operation during API outages
? Quick Start
Installation
- Download the latest
cwhitelist-x.x-NeoForge-1.21.x.jar from Releases
- Place it in your server's
mods folder
- Start the server to generate default configuration
- Restart the server after configuration
Basic Configuration
For Local-Only Mode:
# config/cwhitelist-common.toml
[basic]
enableLogging = true
logRetentionDays = 7
logCutSizeMB = 10
[checks]
enableNameCheck = true
enableUuidCheck = true
enableIpCheck = true
[api]
enableApi = false # Disable API integration
For API-Enabled Mode:
[api]
enableApi = true
baseUrl = "http://your-api-server.com/api"
token = "your-secure-api-token-here"
useHeaderAuth = true
timeoutSeconds = 10
syncOnStartup = true
logLoginEvents = true
Backend program repository address:cwhitelist-backend
⚙️ Configuration Guide
Basic Settings ([basic])
| Parameter |
Default |
Description |
Range |
enableLogging |
true |
Enable local file logging |
boolean |
logRetentionDays |
7 |
Days to keep log files |
1-365 |
logCutSizeMB |
10 |
Maximum log file size (MB) |
1-100 |
Check Settings ([checks])
| Parameter |
Default |
Description |
enableNameCheck |
true |
Validate by player name |
enableUuidCheck |
true |
Validate by player UUID |
enableIpCheck |
true |
Validate by IP address |
API Settings ([api])
| Parameter |
Default |
Description |
enableApi |
false |
Enable API integration |
baseUrl |
http://127.0.0.1:5000/api |
API server base URL |
token |
"" |
API authentication token |
useHeaderAuth |
true |
Use Authorization header (true) or query param (false) |
timeoutSeconds |
10 |
API request timeout |
cacheDurationSeconds |
30 |
Local cache duration (0 to disable) |
syncOnStartup |
true |
Sync with API on server start |
logLoginEvents |
true |
Send login events to API |
serverId |
"" |
Optional server identifier |
sendServerId |
false |
Include server ID in API requests |
includeExpired |
false |
Include expired entries when syncing |
? Command Reference
? Player Commands
| Command |
Description |
Permission |
| No direct player commands |
All whitelist management requires admin permissions |
- |
? Admin Commands
Basic Whitelist Management:
# 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 Management Commands:
# 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 Integration
API Requirements
CWhitelist supports integration with compatible API servers that implement the following endpoints:
GET /health - Health check (no authentication required)
GET /whitelist/sync - Retrieve whitelist entries (requires read permission)
POST /whitelist/entries - Add new entries (requires write permission)
DELETE /whitelist/entries/{type}/{value} - Remove entries (requires delete permission)
POST /login/log - Log login events (requires write permission)
GET /tokens/verify - Verify token validity (requires authentication)
Token Permissions
API tokens must be created with appropriate permissions:
- Read: Required for syncing whitelist
- Write: Required for adding entries and logging events
- Delete: Required for removing entries
- Manage: System administration (not typically needed)
Authentication Methods
Header Authentication (Recommended):
Authorization: Bearer your-token-here
Query Parameter Authentication:
GET /api/whitelist/sync?token=your-token-here
?️ File Structure
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
Data Files Format
cwhitelist_entries.json:
[
{"type": "name", "value": "PlayerOne"},
{"type": "uuid", "value": "123e4567-e89b-12d3-a456-426614174000"},
{"type": "ip", "value": "192.168.1.*"}
]
? Operation Modes
Mode 1: Local-Only (Default)
- All data stored locally
- No external dependencies
- Simple deployment
- Suitable for single servers
Mode 2: API-Primary with Fallback
- Primary: Sync with central API
- Fallback: Use local cache if API unavailable
- Automatic re-sync when API restored
- Ideal for multi-server setups
Mode 3: API-Only
- All operations through API
- No local whitelist storage
- Centralized management
- Requires reliable API connection
?️ Security Features
Authentication Security
- Token-based Authentication: Secure API communication
- Permission Validation: Granular access control
- Token Expiry: Automatic token validity checks
- No Hardcoded Secrets: Config file-based token management
Data Protection
- Local Encryption: Sensitive data in configuration
- Access Control: Admin-only command permissions (level 4)
- Audit Logging: Comprehensive access logging
- Input Validation: Sanitized API request parameters
Network Security
- HTTPS Support: Secure API communication (when configured)
- Timeout Protection: Configurable request timeouts
- Retry Logic: Graceful error handling
- Rate Limiting: Built-in request queuing
? Performance Optimization
Caching Strategy
// 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
Async Operations
- Non-blocking API Calls: HTTP requests on separate threads
- Parallel Processing: Concurrent request handling
- Queue Management: Ordered request processing
- Resource Optimization: Efficient memory usage
? Troubleshooting
Common Issues
API Connection Failed:
[Server] WARN API health check failed, falling back to local file
Solution: Verify API server is running and accessible. Check network connectivity and firewall settings.
Authentication Failed:
[Server] ERROR Token verification failed: Authentication required
Solution: Verify API token is correct and has required permissions. Use /cwhitelist api verify to test.
Permission Denied:
[Server] ERROR Token does not have write permission
Solution: Generate new token with appropriate permissions or use existing token with correct permissions.
Cache Issues:
[Server] DEBUG API cache cleared
Solution: Cache automatically clears on modification. Use /cwhitelist api clearcache to force refresh.
Log Files
Check log files for detailed error information:
- Location:
logs/cwhitelist/YYYY-MM-DD.log
- Contains: API calls, authentication attempts, errors
- Format:
[HH:mm:ss] [RESULT] PlayerName UUID IP
Debug Commands
# Check current mode
/cwhitelist list
# Verify API connectivity
/cwhitelist api health
# Test token permissions
/cwhitelist api verify
# View detailed status
/cwhitelist api status
? API Compatibility
Supported API Versions
- Minimum: v1.0.0
- Recommended: v1.1.0+
- Tested With: CWhitelist API v1.2.0
Response Format Expectations
{
"success": true,
"message": "Operation successful",
"data": { /* operation-specific data */ }
}
Error Handling
The mod handles the following HTTP status codes:
200-299: Success - Process response
401: Unauthorized - Token invalid/expired
403: Forbidden - Insufficient permissions
429: Rate Limited - Automatic retry with backoff
500+: Server Error - Fallback to local mode
? Development
Building from Source
# 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
Prerequisites
- Java: 17 or higher
- Minecraft: 1.21.x
- NeoForge: Latest recommended build
- Build Tools: Gradle 8.0+
Project Structure
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
Extending the Mod
Adding New Authentication Methods:
- Update
Config.java with new check setting
- Modify
WhitelistManager.isAllowed() method
- Add corresponding command handlers
- Update API client for new endpoint support
Custom API Integration:
// Implement custom ApiClient interface
public interface CustomApiClient {
CompletableFuture<List<WhitelistEntry>> fetchEntries();
CompletableFuture<Boolean> validateEntry(WhitelistEntry entry);
}
? Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
Development Workflow
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit changes (
git commit -m 'Add amazing feature')
- Push to branch (
git push origin feature/amazing-feature)
- Open a Pull Request
Coding Standards
- Follow existing code style and patterns
- Add comprehensive JavaDoc comments
- Include unit tests for new features
- Update documentation for API changes
- Ensure backward compatibility
Third-Party Licenses
- Gson: Apache License 2.0
- NeoForge: LGPL 2.1
- SLF4J: MIT License
? Acknowledgments
- NeoForge Team for the excellent modding framework
- Mojang Studios for Minecraft
- Contributors who help improve this project
- Community for feedback and support
? Support
Built with ❤️ by SkyDream Team
If you find this project useful, please consider giving it a ⭐ on GitHub!
? Quick Reference
Deployment Checklist
- Verify Java 17+ installation
- Configure API token (if using API mode)
- Set appropriate permission levels
- Test API connectivity
- Configure logging preferences
- Set up log rotation schedule
- Test local fallback functionality
Performance Tips
- Cache Duration: Set
cacheDurationSeconds based on update frequency
- Log Rotation: Configure
logCutSizeMB to prevent disk space issues
- Timeout Settings: Adjust
timeoutSeconds based on network latency
- API Calls: Minimize API calls during peak hours
Security Best Practices
- Token Security: Store tokens in configuration, not in code
- Permission Minimization: Grant minimum required permissions
- Regular Audits: Review log files for suspicious activity
- API Security: Use HTTPS for API communication
- Backup Strategy: Regular backups of local whitelist files
Ready to secure your Minecraft server? Install CWhitelist today and experience professional-grade whitelist management!
评论 0
登录后参与评分
还没有评论,来抢沙发吧