Настройка Xdebug 3 на внешнем сервере в Docker-контейнере через SSH-туннель

В нашей организации используется такой подход к разработке - на локальной машине (Windows 11) установлен PhpStorm и находится репозиторий с кодом. В PhpStorm настроена автоматическая выгрузка изменений на dev-стенд (внешний сервер), где и исполняется код. На dev-стенде: Ubuntu 20 и Docker (swarm mode).

Общий принцип настройки Xdebug таков:

Открываем SSH-туннель между локальной машиной и dev-стендом
Xdebug из контейнера подключается к 9003-му порту хоста (dev-стенд)
dev-стенд по SSH-туннелю перенаправляет запрос на 9003-й порт локальной машины

1.Настройка на стороне внешнего сервера:

1.1.Добавить Xdebug в образ

В Dockerfile, из которого собирается Ваш образ PHP-FPM необходимо добавить установку и активацию XDebug 3:

FROM php:8.0.6-fpm-alpine 

RUN apk add --no-cache \  
    $PHPIZE_DEPS \  
    && pecl install xdebug \  
    && docker-php-ext-enable xdebug

1.2.Определить IP адрес, по которому хост доступен из контейнера

Для этого нужно выполнить в нем команду:

docker exec $(docker ps -q --filter="NAME=php-fpm") \
/sbin/ip route|awk '/default/ { print $3 }'

php-fpm - это название сервиса PHP-FPM, указанное в compose-файле.

Получим IP, который будем далее указывать в настройках Xdebug и правилах перенаправления пакетов.

В моем случае - 172.18.0.1

1.3.Настройка Xdebug в php.ini

[X-debug]  
xdebug.mode=debug  
xdebug.client_host=172.18.0.1  
xdebug.client_port=9003

В опции xdebug.client_host указан IP, полученный на шаге 1.2

1.4.Правки docker-compose.yml

Для сервиса php-fpm необходимо добавить переменную окружения PHP_IDE_CONFIG с названием сервера, в котором в PhpStorm будет задан маппинг. Docker - это название сервера в настройках PhpStorm (Шаг 2.2).

version: "3.9"

services:

  ### php-fpm ###########################################################
  php-fpm:
    image: ${PHP_FPM_IMAGE}
    environment:
      PHP_IDE_CONFIG: serverName=Docker

1.5.Переадресация трафика на внешний порт

sudo iptables -t nat -I PREROUTING -p tcp -d 172.18.0.1 \
--dport 9003 -j DNAT --to 127.0.0.1:9003

172.18.0.1 - это адрес, по которому можно обратиться к хост-машине из контейнера (пункт 1.2).

Для того, чтобы правила сохранялись после перезагрузки необходимо установть пакет iptables-persistent

sudo apt-get install iptables-persistent

В процессе установки будет предложено сохранить все правила для IPv4. Ответить нужно положительно.

2.Настройка на стороне локальной машины:

2.1.Открыть SSH-туннель

Вы должны иметь возможность подключения к внешнему серверу по SSH.

Запустите SSH-туннель с проброской 9003-го порта внешнего сервера на 9003-й порт локального хоста:

ssh -R <remote_port>:localhost:<local_port> <user>@<host>
# например
ssh -R 9003:localhost:9003 Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.

my-user - это имя вашего пользователя на внешнем сервер

example.com - это адрес внешнего сервера

2.2.Настройка PhpStorm

В настройках PHP -> Servers добавить сервер под названием Docker. Хост и порт не важны, можно оставить localhost и 80-й порт.
Главное - задать маппинг от корня локального проекта до корня проекта в контейнере на внешнем сервере

3.Использование

3.1. Включить "прослушку" порта 9003 в PhpStorm:

3.2. Инициализация отладки через браузер

Необходимо установить специальное расширение Xdebug Helper для вашего браузера, которое позволит легко запускать режим отладки.

Для Firefox - https://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/

Для Chrome - https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc

Включить режим отладки:

В PhpStorm установите в нужном месте точку останова и перезагрузите страницу.

После этого должно произойти подключение к PhpStorm и начаться сессия отладки.

3.3.Инициализация откладки консольных команд.

Необходимо в команду добавить опцию -dxdebug.start_with_request=yes
Например,

php -dxdebug.start_with_request=yes bin/phpunit

4.Отладка подключения

Если подключение к PHPStorm не происходит, то можно воспользоваться легковесным клиентом для проверки подключения - https://xdebug.org/docs/dbgpClient
Его нужно скачать на локальный хост.
Запустить сначала на локальном хосте и попытаться подключиться к нему из контейнера:

curl -Iv 172.18.0.1:9003

Если в терминале с клиентом появилась надпись Connect from 127.0.0.1:xxxxx, то X-debug успешно соединяется с клиентом и проблема в настройках PHPStorm

Статьи