Усунення несправностей

Поширені проблеми та їх вирішення.

Зашифрована автентифікація (ZimaOS / CasaOS)

Проблема

Команда /auth persistence Encrypted не працює або не зберігається після перезапуску контейнера. Це відбувається через:

1. ZimaOS/CasaOS не можуть правильно монтувати /etc/machine-id:ro
2. Контейнер створює порожній файл /etc/machine-id
3. Без дійсного machine-id зашифроване зберігання облікових даних не працює

Рішення

Використовуйте альтернативний docker-compose файл без монтування machine-id:

# Завантажити compose сумісний з CasaOS
curl -O https://raw.githubusercontent.com/ketbome/hytale-server/main/docker-compose.casaos.yml

# Запустити з цим файлом
docker compose -f docker-compose.casaos.yml up -d

Контейнер:

1. Згенерує унікальний machine-id при першому запуску
2. Збереже його в ./server/.machine-id
3. Автоматично відновить при кожному перезапуску

Ручне виправлення (за потреби)

Якщо проблеми залишаються, можна налаштувати machine-id вручну:

# Увійти в контейнер
docker exec -it hytale-server bash

# Згенерувати та встановити machine-id
dbus-uuidgen > /etc/machine-id

# Перевірити
cat /etc/machine-id

# Тепер виконати команду auth
# /auth persistence Encrypted

Потім скопіюйте machine-id до папки server для збереження:

docker exec hytale-server cat /etc/machine-id > ./server/.machine-id

Файли сервера не знайдено

Проблема

Сервер показує "Waiting for files..." і не запускається.

Рішення

Варіант 1: Автозавантаження (тільки x64)

Переконайтеся, що AUTO_DOWNLOAD=true у вашому файлі .env. Завантажувач потребує автентифікації - перевірте панель на запити входу.

Варіант 2: Ручне завантаження

1. Завантажте з hytale.com:

   • HytaleServer.jar
   • Assets.zip

2. Помістіть їх у папку ./server/

3. Перезапустіть контейнер

ARM64: Автозавантаження недоступне

Проблема

На ARM64 пристроях (Apple Silicon, Raspberry Pi) автозавантаження не працює.

Рішення

Бінарник hytale-downloader тільки для x64. Завантажте файли вручну:

# На x64 машині завантажте файли
# Потім перенесіть на ваш ARM64 сервер:
scp HytaleServer.jar Assets.zip user@server:~/hytale/server/

Див. Підтримка ARM64 для деталей.

Контейнер постійно перезапускається

Проблема

Контейнер перезапускається знову і знову без запуску сервера.

Можливі причини

1. Недостатньо RAM: Перевірте JAVA_XMX у вашому .env
2. Відсутні файли: Переконайтеся що існують HytaleServer.jar та Assets.zip
3. Конфлікт портів: Перевірте чи порт 5520/UDP доступний

Діагностика

# Переглянути логи
docker compose logs -f hytale

# Перевірити статус контейнера
docker ps -a

Панель не може підключитися до сервера

Проблема

Веб-панель показує "Container not found" або не може керувати сервером.

Рішення

1. Перевірте що назва контейнера співпадає:

   # Перевірити фактичну назву контейнера
   docker ps
   
   # Має співпадати з CONTAINER_NAME в .env (за замовчуванням: hytale-server)

2. Переконайтеся що Docker socket змонтовано:

   # В docker-compose.yml
   volumes:
     - /var/run/docker.sock:/var/run/docker.sock:ro

3. Перевірте що контейнери в одній мережі:

   docker network ls
   docker network inspect hytale_default

Помилки дозволів

Проблема

Не вдається записувати файли або сервер не може запуститися через дозволи.

Рішення

Контейнер спочатку запускається як root для виправлення дозволів, потім переключається на користувача hytale. Якщо є проблеми:

# Виправити дозволи вручну
sudo chown -R 1000:1000 ./server/

Моди не завантажуються

Проблема

Встановлені моди не з'являються в грі.

Рішення

1. Перевірте що SERVER_EXTRA_ARGS включає флаг модів:

   SERVER_EXTRA_ARGS=--mods mods

2. Перевірте що моди в правильній папці: ./server/mods/

3. Перезапустіть сервер після додавання модів

4. Перевірте логи сервера на помилки завантаження модів

Отримання допомоги

Якщо вашої проблеми немає в списку:

1. Перевірте GitHub Issues
2. Пошукайте існуючі issues перед створенням нового
3. Включіть логи та вашу конфігурацію при повідомленні про баги