Dockerfile/docs/troubleshooting.md

🐛 Решение проблем

Частые ошибки

1. "missing separator. Stop."

Причина: В Makefile используются пробелы вместо табов.

Решение:

sed -i 's/^    /\t/' makefile

2. "docker: command not found"

Причина: Docker не установлен или не в PATH.

Решение:

# Установка Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Проверка
docker version

3. "unauthorized: authentication required"

Причина: Не выполнена авторизация в registry.

Решение:

make docker login REGISTRY=hub.cism-ms.ru
# или
docker login hub.cism-ms.ru

4. "No rule to make target 'commit'"

Причина: Использование старых команд без префикса группы.

Решение:

# Вместо: make commit
# Используйте: make git commit

5. "Образ не найден"

Причина: Указан неверный SRC_IMAGE или IMAGE не собран.

Решение:

# Проверка существующих образов
docker images

# Сборка образа
make docker build IMAGE=myapp TAG=latest

6. "Buildx: no builder instance"

Причина: Buildx не инициализирован.

Решение:

# Создание builder'а
make docker create-builder

# Использование builder'а
make docker use-builder

Отладка

Просмотр конфигурации

# Показать конфигурацию
make docker print-config

# Проверить образ
make docker inspect

# Просмотр логов
make docker build 2>&1 | tee build.log

# Проверка Docker daemon
docker info

# Проверка доступных образов
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

Проблемы с памятью

Увеличение лимита памяти для Docker

# В /etc/docker/daemon.json
{
  "default-ulimits": {
    "memlock": {
      "Hard": -1,
      "Name": "memlock",
      "Soft": -1
    }
  }
}

Очистка неиспользуемых ресурсов

# Очистка неиспользуемых образов
docker image prune -f

# Очистка неиспользуемых контейнеров
docker container prune -f

# Полная очистка системы
docker system prune -a -f

Проблемы с сетью

Проверка сетевых настроек

# Проверка сетевых интерфейсов
docker network ls
docker network inspect bridge

# Тестирование подключения
make docker check RUN_CMD="ping -c 3 8.8.8.8"

# Проверка DNS
make docker check RUN_CMD="nslookup google.com"

Настройка прокси

# Настройка прокси для Docker
mkdir -p /etc/systemd/system/docker.service.d
cat > /etc/systemd/system/docker.service.d/http-proxy.conf << EOF
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

Проблемы с правами доступа

Исправление прав на файлы

# Исправление прав на Makefile
chmod +x makefile
chmod 644 dockerfile

# Проверка прав пользователя
make docker check RUN_CMD="id && whoami"

# Добавление пользователя в группу docker
sudo usermod -aG docker $USER
newgrp docker

Проблемы с SELinux (CentOS/RHEL)

# Временное отключение SELinux
sudo setenforce 0

# Постоянное отключение SELinux
sudo sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
sudo reboot

Проблемы с производительностью

Медленная сборка

# Сборка с подробным выводом
make docker build IMAGE=myapp TAG=v1.0.0 QUIET=0

# Анализ времени сборки
time make docker build IMAGE=myapp TAG=v1.0.0

# Сборка без кэша для диагностики
make docker build IMAGE=myapp TAG=v1.0.0 NO_CACHE=1

Большой размер образа

# Анализ размера образа
docker history myapp:latest

# Анализ слоев
docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  wagoodman/dive:latest myapp:latest

# Сжатие образа
make docker save SRC_IMAGE=myapp:latest COMPRESS=1

Проблемы с registry

Ошибки авторизации

# Очистка кэша авторизации
docker logout
docker login

# Проверка конфигурации Docker
cat ~/.docker/config.json

# Удаление старых токенов
rm -rf ~/.docker/config.json
docker login

Проблемы с SSL сертификатами

# Добавление недоверенного registry
echo '{"insecure-registries":["registry.example.com:5000"]}' | sudo tee /etc/docker/daemon.json

# Перезапуск Docker
sudo systemctl restart docker

Проблемы с Git

"Not a git repository"

# Инициализация Git репозитория
git init
git remote add origin <url>

# Проверка статуса
make git status

"Git push failed"

# Проверка текущей ветки
git branch

# Проверка удаленного репозитория
git remote -v

# Принудительный push (осторожно!)
git push --force-with-lease origin main

Проблемы с архивами

Ошибка при загрузке архива

# Проверка целостности архива
sha256sum -c images/myapp_v1.0.0.tar.gz.sha256

# Проверка размера файла
ls -lh images/myapp_v1.0.0.tar.gz

# Пересоздание архива
make docker save SRC_IMAGE=myapp:latest COMPRESS=1

Проблемы с разбиением на части

# Объединение частей архива
cat images/myapp_v1.0.0.tar.gz.part.* > images/myapp_v1.0.0.tar.gz

# Проверка целостности
sha256sum -c images/myapp_v1.0.0.tar.gz.sha256

Диагностические команды

Проверка системы

# Информация о системе
uname -a
cat /etc/os-release

# Информация о Docker
docker version
docker info

# Информация о Make
make --version

# Информация о Git
git --version

Проверка ресурсов

# Использование диска
df -h

# Использование памяти
free -h

# Использование CPU
top -n 1

# Процессы Docker
ps aux | grep docker

Логи системы

# Логи Docker
sudo journalctl -u docker.service

# Логи системы
sudo journalctl -f

# Логи сборки
tail -f logs/build_*.log

Получение помощи

Сбор информации для отчета об ошибке

# Создание отчета об ошибке
{
  echo "=== System Info ==="
  uname -a
  cat /etc/os-release
  
  echo -e "\n=== Docker Info ==="
  docker version
  docker info
  
  echo -e "\n=== Make Info ==="
  make --version
  
  echo -e "\n=== Git Info ==="
  git --version
  
  echo -e "\n=== Project Config ==="
  make docker print-config
  
  echo -e "\n=== Recent Logs ==="
  tail -20 logs/build_*.log 2>/dev/null || echo "No logs found"
} > bug_report.txt

Полезные ресурсы

• Docker Documentation
• Make Documentation
• Git Documentation
• Stack Overflow