HomeBox на сервере: частые ошибки и решения

MAATRIX

HomeBox — удобный self-hosted инструмент для инвентаризации домашнего имущества: что где лежит, сколько стоило, когда куплено и на что распространяется гарантия. Пока всё работает — вопросов нет, но стоит перенести контейнер на новый сервер, обновить образ или включить бэкапы, как вылезают ошибки: пустая база после рестарта, битые фото, 502 через reverse proxy. Разберём самые частые проблемы и рабочие решения без лишней теории.

Проблема 1: данные пропадают после пересоздания контейнера

Самая частая жалоба — «настроил всё, а после docker compose down и up инвентарь пустой». Причина почти всегда одна: том с данными не примонтирован явно, и Docker создал анонимный volume, который при пересборке контейнера потерялся.

Проверьте, что в docker-compose.yml для HomeBox есть именованный volume, а не «пустое» место:

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    environment:
      - HBOX_LOG_LEVEL=info
      - HBOX_WEB_MAX_UPLOAD_SIZE=25
    ports:
      - "3100:7745"
    volumes:
      - homebox_data:/data

volumes:
  homebox_data:

Ключевой момент — секция volumes: на верхнем уровне файла и запись homebox_data:/data внутри сервиса. Без неё Docker при каждом up --force-recreate создаёт новый анонимный том, а старый просто становится «висячим» (dangling) и удаляется командой docker volume prune.

Проверить, куда физически смонтирован том, можно так:

docker volume inspect homebox_data

В выводе будет поле Mountpoint — реальный путь на хосте вида /var/lib/docker/volumes/homebox_data/_data. Если вы делали docker volume ls и видите десяток томов с случайными хэш-именами вместо homebox_data — это и есть следы прошлых пересозданий с потерей данных.

Если база уже потеряна безвозвратно — восстановить нечем, если бэкапов не было. Поэтому следующий раздел — не опция, а обязательный шаг сразу после установки. Про то, как вообще устроены типы томов в Docker и когда какой уместен, есть отдельный разбор: Docker volumes: типы и когда какой использовать.

Проблема 2: SQLite база блокируется или повреждается

HomeBox по умолчанию хранит данные в SQLite-файле внутри /data. Это удобно для одного пользователя, но создаёт две типичные проблемы на сервере: блокировки при параллельном доступе и повреждение файла при жёстком перезапуске (docker kill, обрыв питания на хосте, OOM killer).

Признаки: в логах контейнера видно database is locked или disk I/O error, а веб-интерфейс либо зависает на загрузке, либо отдаёт 500-ю ошибку.

Первое, что стоит сделать — проверить целостность файла напрямую:

docker exec -it homebox sh
apk add sqlite 2>/dev/null || true
sqlite3 /data/homebox.db "PRAGMA integrity_check;"

Если ответ ok — база цела, проблема в блокировке (обычно от параллельного бэкап-скрипта, который читает файл через cp в момент записи). Если ответ другой — файл повреждён, и без бэкапа тут не восстановиться, PRAGMA integrity_check только диагностирует, не лечит.

Правильный способ бэкапить SQLite «на горячую» — не cp, а встроенная команда .backup, которая учитывает блокировки:

docker exec homebox sqlite3 /data/homebox.db ".backup /data/homebox-backup.db"

Добавьте это в cron на хосте вместе с копированием файла за пределы контейнера:

# /etc/cron.d/homebox-backup
0 3 * * * root docker exec homebox sqlite3 /data/homebox.db ".backup /data/homebox-backup.db" && docker cp homebox:/data/homebox-backup.db /opt/backups/homebox/homebox-$(date +\%F).db

Если объём инвентаря вырос до нескольких тысяч предметов с фото и приложениями и SQLite стал узким местом (долгие запросы, частые блокировки) — HomeBox поддерживает PostgreSQL как альтернативный бэкенд через переменные HBOX_DATABASE_DRIVER=postgres и HBOX_DATABASE_*. Это отдельная миграция данных, но для домашнего каталога вещей она обычно избыточна — SQLite с регулярным .backup справляется нормально даже на бюджетном VPS.

Проблема 3: 502 Bad Gateway при работе через reverse proxy

Если HomeBox стоит за Traefik, Caddy или nginx для выдачи по домену с HTTPS, частая ошибка — 502 сразу после деплоя или после обновления образа. Причины обычно две:

1. Порт внутри контейнера указан неверно. HomeBox слушает 7745 внутри контейнера — это фиксированный порт приложения, а не то, что вы пробрасываете наружу через ports:. Если в конфиге reverse proxy указан любой другой порт (например, по аналогии с другим сервисом) — proxy будет стучаться в пустоту.

1. Контейнеры не в одной Docker-сети. Reverse proxy и HomeBox должны быть в общей user-defined сети, иначе имя сервиса homebox не резолвится по DNS Docker.

Пример корректного фрагмента для Traefik через labels:

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    networks:
      - traefik_net
    volumes:
      - homebox_data:/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.homebox.rule=Host(`inventory.example.com`)"
      - "traefik.http.routers.homebox.entrypoints=websecure"
      - "traefik.http.routers.homebox.tls.certresolver=letsencrypt"
      - "traefik.http.services.homebox.loadbalancer.server.port=7745"

networks:
  traefik_net:
    external: true

volumes:
  homebox_data:

Обратите внимание на последнюю строку labels — server.port=7745, это внутренний порт контейнера, а не тот, что снаружи. Если вы копировали конфиг с другого сервиса и забыли поменять порт — получите 502 при полностью «зелёном» статусе контейнера в docker ps.

Проверить сетевую связность быстро можно изнутри контейнера reverse proxy:

docker exec -it traefik wget -qO- http://homebox:7745/api/v1/status

Если ответ есть — проблема точно в конфигурации роутера, а не в сети. Если Traefik ведёт себя странно и после этой проверки — стоит заглянуть в разбор частых проблем самого Traefik: Traefik на сервере: частые ошибки и решения. Если вы ещё выбираете между Traefik и Caddy для выдачи SSL — есть сравнение: Caddy или Nginx: что выбрать для сервера.

Проблема 4: фотографии вложений пропадают или не загружаются

HomeBox хранит фото товаров и вложенные документы в том же каталоге /data, в подпапке attachments — то есть физически в том же volume, что и база. Если фото «пропадают» после переезда на новый сервер — почти всегда это значит, что при миграции скопировали только базу, а не весь /data целиком.

Правильная миграция — переносить весь том, а не выборочные файлы:

# на старом сервере
docker run --rm -v homebox_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/homebox-data.tar.gz -C /data .

# скопировать архив на новый сервер (scp, rsync — что удобнее)
scp homebox-data.tar.gz user@new-server:/opt/

# на новом сервере, том должен уже существовать (docker compose up хотя бы раз)
docker run --rm -v homebox_data:/data -v /opt:/backup alpine \
  tar xzf /backup/homebox-data.tar.gz -C /data

Вторая частая причина пропавших фото — переменная HBOX_WEB_MAX_UPLOAD_SIZE. Если её значение слишком маленькое (по умолчанию несколько мегабайт), фото с современного смартфона в исходном разрешении просто не загрузится — HomeBox вернёт ошибку загрузки, которую легко принять за баг. Увеличьте лимит явно (HBOX_WEB_MAX_UPLOAD_SIZE=25, значение в мегабайтах) — если вы фотографируете вещи на телефон без сжатия, 25–50 МБ разумный запас.

Проблема 5: после обновления образа интерфейс не открывается или ломается миграция

HomeBox активно развивается, и мажорные обновления образа иногда меняют схему базы данных. Симптом — контейнер стартует, в логах видно строки про миграции (migration, schema), а веб-интерфейс либо не открывается, либо открывается с ошибками на части страниц.

Порядок действий: перед docker compose pull && docker compose up -d всегда снимите бэкап /data целиком (см. раздел про SQLite .backup и архив тома), затем смотрите логи сразу после обновления:

docker compose logs -f homebox --tail=100

Если миграция упала на середине — это видно по явной ошибке SQL в логе, а не по «зависшему» контейнеру. Если откат нужен срочно — верните предыдущий тег образа в docker-compose.yml (не latest, а конкретную версию, например v0.14.2) и восстановите бэкап /data, если миграция уже успела частично изменить схему:

docker compose down
docker run --rm -v homebox_data:/data -v /opt/backups/homebox:/backup alpine \
  sh -c "rm -rf /data/* && tar xzf /backup/homebox-data-2026-08-20.tar.gz -C /data"
docker compose up -d

Общий вывод: фиксируйте версию образа тегом, а не latest, если инвентарь для вас критичен (страховка, наследство, налоговый учёт). Обновляйтесь осознанно, читая changelog релиза, а не «на автопилоте» через watchtower. Если автообновление контейнеров у вас всё же настроено и вы хотите держать HomeBox вне его зоны действия — механизм исключения сервисов из watchtower разобран здесь: Автообновление watchtower на сервере: частые ошибки и решения.

Проблема 6: медленный отклик и высокая нагрузка на слабом VPS

HomeBox сам по себе лёгкий сервис — Go-бэкенд плюс SQLite почти всегда справляются даже на 1 vCPU / 1 ГБ RAM для домашнего каталога в несколько сотен позиций. Если интерфейс тормозит именно на VPS, причины обычно внешние: диск на медленном сетевом хранилище (SQLite чувствителен к latency при записи — каждая транзакция это fsync), накопившиеся тяжёлые фото по 15–20 МБ без ограничения размера загрузки, либо OOM killer, убивающий контейнер под нагрузкой — проверяется командой dmesg | grep -i oom на хосте.

Быстрая проверка, во что упирается контейнер:

docker stats homebox --no-stream

Если CPU и память в норме, а отклик всё равно медленный — почти наверняка дело в диске. Для инвентаризации с большим количеством фотографий разумно сразу закладывать VPS с NVMe и хотя бы 2 ГБ RAM — с запасом на будущий рост базы и параллельные бэкапы, которые тоже читают диск.

Проблема 7: нет HTTPS или сертификат не выпускается

Если вы выдаёте HomeBox наружу по домену (не только из локальной сети через VPN), HTTPS обязателен — в интерфейсе вводится пароль, а без шифрования он уходит открытым текстом. Типичная ошибка новичков — открыть порт 3100 напрямую в интернет без reverse proxy вообще, понадеявшись «настроить сертификат потом».

Правильная схема: HomeBox слушает только на 127.0.0.1 или во внутренней Docker-сети, наружу торчит только reverse proxy на 80/443 с автоматическим Let's Encrypt. Через Caddy это буквально три строки Caddyfile:

inventory.example.com {
    reverse_proxy homebox:7745
}

Caddy сам получит и обновит сертификат, если DNS-запись домена указывает на IP вашего сервера и порты 80/443 открыты в файрволе. Если сертификат не выпускается — почти всегда проблема в DNS (запись ещё не разошлась) или в закрытом порте 80, который нужен для HTTP-01 challenge даже при выдаче сертификата для HTTPS. Подробный разбор именно такой ситуации есть здесь: Caddy с авто-SSL на сервере: частые ошибки и решения.

Проверить, что порт снаружи действительно открыт:

sudo ss -tlnp | grep -E ':80|:443'

Если строк нет — файрвол или сам reverse proxy не слушает нужные порты, и Let's Encrypt не сможет достучаться до сервера для валидации.

Частые вопросы