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  # Отключить интеграцию с 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])

Настройки проверок ([checks])

Настройки API ([api])

📋 Справочник команд

🎮 Команды игроков

👑 Команды администратора

Базовое управление вайтлистом:

# Добавить записи
/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 (при настройке)
• Защита от таймаутов: Настраиваемые таймауты запросов
• Логика повторных попыток: Корректная обработка ошибок
• Ограничение частоты: Встроенная очередь запросов

📈 Оптимизация производительности

Стратегия кэширования

// 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 # Главный класс мода ├── Config.java # Управление конфигурацией ├── ApiClient.java # Взаимодействие с API ├── WhitelistManager.java # Основная логика вайтлиста ├── WhitelistCommand.java # Реализация команд ├── LogHandler.java # Система логирования └── WhitelistEntry.java # Модель данных

### Расширение мода

**Добавление новых методов аутентификации:**
1. Обновите `Config.java`, добавив новую настройку проверки
2. Измените метод `WhitelistManager.isAllowed()`
3. Добавьте соответствующие обработчики команд
4. Обновите API-клиент для поддержки нового эндпоинта

**Интеграция собственного API:**
```java
// Реализуйте собственный интерфейс ApiClient
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. Откройте Pull Request

Стандарты кода

• Следуйте существующему стилю и паттернам кода
• Добавляйте подробные комментарии JavaDoc
• Включайте юнит-тесты для новых функций
• Обновляйте документацию при изменениях API
• Обеспечивайте обратную совместимость

Сторонние лицензии

• Gson: Apache License 2.0
• NeoForge: LGPL 2.1
• SLF4J: MIT License

🌟 Благодарности

• Команде NeoForge за отличный фреймворк для моддинга
• Mojang Studios за Minecraft
• Участникам, помогающим улучшать этот проект
• Сообществу за отзывы и поддержку

📞 Поддержка

• Документация: GitHub Wiki
• Проблемы: GitHub Issues
• Обсуждения: GitHub Discussions
• Email: 1607002411@qq.com

🎯 Краткая справка

Чек-лист развёртывания

• [ ] Проверьте установку Java 17+
• [ ] Настройте API-токен (если используете режим API)
• [ ] Задайте подходящие уровни прав
• [ ] Проверьте подключение к API
• [ ] Настройте параметры логирования
• [ ] Настройте расписание ротации логов
• [ ] Проверьте работу локального резервного режима

Советы по производительности

1. Длительность кэша: задайте cacheDurationSeconds в зависимости от частоты обновлений
2. Ротация логов: настройте logCutSizeMB, чтобы избежать проблем с местом на диске
3. Настройки таймаута: подберите timeoutSeconds под задержку сети
4. Запросы к API: минимизируйте запросы к API в часы пик

Лучшие практики безопасности

1. Безопасность токенов: храните токены в конфигурации, а не в коде
2. Минимум прав: выдавайте только необходимые права
3. Регулярные проверки: просматривайте логи на подозрительную активность
4. Безопасность API: используйте HTTPS для взаимодействия с API
5. Стратегия резервного копирования: регулярно делайте бэкапы локальных файлов вайтлиста

Готовы защитить свой Minecraft-сервер? Установите CWhitelist сегодня и оцените управление вайтлистом профессионального уровня!