Отладка на сервере 1С 8.3: как разрешить подключение отладчика

Отладка на сервере 1С включается параметром -debug в строке запуска агента сервера ragent. После этого отладчик Конфигуратора или расширения для VS Code может подключаться к серверным процессам кластера. Отдельной «кнопки отладки» в консоли кластера нет: всё решает команда, которой запущена служба.

Параметр нужен, если вы хотите пройти по шагам серверный код: общие модули с флагом «Сервер», модули объектов, регламентные задания, фоновые процессы. Для клиент-серверной базы без -debug точки останова в серверном коде просто не сработают.

Ниже порядок действий для Windows и Linux, затем технологический журнал, работа через rac и ras и обязательная уборка за собой. Всё про платформу 8.3.

Что проверить до начала

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

• 🔐 У вас есть права администратора ОС на сервере. Нужно менять параметры службы и запускать её заново.
• 🧪 Лучше работать на тестовой копии базы или на отдельном сервере разработки. На боевом сервере отладка тормозит процессы: остановка на точке блокирует сеанс.
• 🔌 Версия платформы на сервере и версия клиента, где открыт Конфигуратор, совпадают по первым трём числам. Иначе отладчик не подключится или будет вести себя странно.
• 🛡️ Порты агента и отладчика открыты в брандмауэре между рабочим местом разработчика и сервером.

Не включайте отладку на боевом сервере «на всякий случай». Пока параметр действует, к серверу может подключиться любой, у кого есть сетевой доступ к порту и права в базе.

Где задаётся режим отладки: параметр -debug у ragent

Агент сервера ragent запускается либо как служба Windows, либо как демон на Linux. Режим отладки задаётся ключом в его командной строке. Файла настроек, в котором достаточно поставить галочку, нет: ключ нужно дописать в строку запуска.

Платформа поддерживает два способа обмена с отладчиком:

Для большинства задач хватает первого варианта. Если сеть разделена и в ней разрешён только HTTP, смотрите справку платформы по серверу отладки dbgs. Параметры этой утилиты зависят от релиза, поэтому здесь я их не привожу.

Windows: правка службы

Службу можно пересоздать заново, но проще дописать ключ в существующую.

1. Откройте редактор реестра и перейдите в ветку HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services.
2. Найдите раздел службы «Агент сервера 1С:Предприятия 8.3» — его имя начинается с 1C:Enterprise 8.3 Server Agent.
3. В параметре ImagePath в конец строки запуска добавьте -debug.
4. Перезапустите службу через оснастку «Службы».

Типичный вид строки после правки:

"C:\Program Files\1cv8\8.3.xx.xxxx\bin\ragent.exe" -srvc -agent -regport 1541 -port 1540 -range 1560:1591 -d "C:\srvinfo" -debug

Номер релиза и пути у вас свои. Меняйте только хвост, остальное оставьте как было.

Linux: правка файла конфигурации демона

На Linux агент запускается скриптом из пакета сервера, а параметры лежат в конфигурационном файле службы. Расположение зависит от дистрибутива и способа установки, поэтому найдите файл, в котором перечислены -port, -regport и -range, и добавьте туда -debug. Затем перезапустите службу командой systemctl restart с именем вашего юнита.

Как понять, что режим включился

Проверка простая: откройте Конфигуратор на рабочем месте, подключитесь к базе на этом сервере и запустите отладку. Если серверный код доступен для пошаговой отладки, значит ключ подхвачен. Также можно посмотреть командную строку процесса ragent в диспетчере задач или через ps — там должен быть -debug.

Отдельно про безопасность. Отладчик даёт возможность останавливать и изучать серверные процессы, поэтому порт отладки не стоит открывать наружу. Оставьте доступ только с адресов рабочих мест разработчиков или через VPN. Если сервер смотрит в интернет, закройте эти порты на периметре полностью.

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

Подключение отладчика из Конфигуратора

Когда сервер готов, подключаем клиента. В Конфигураторе откройте нужную базу и запустите отладку командой меню Отладка → Начать отладку. Платформа сама найдёт серверный процесс, к которому нужно прицепиться.

Что полезно настроить заранее:

• 🎯 Включите остановку по ошибке: в параметрах отладки есть пункт «Остановка по ошибке», он помогает ловить исключения в серверных вызовах.
• 🧵 Откройте окно «Отладка → Окна отладки», где видны вызовы и переменные, и закрепите его — так не придётся искать его в момент остановки.
• 🧷 Ставьте точки останова в модулях, а не в формах, если код вызывается и с сервера, и с клиента.

Если отладчик «не видит» сервер, причина обычно в одном из трёх: ключа -debug нет в строке запуска, служба не перезапущена после правки или версии платформы клиента и сервера расходятся.

Технологический журнал: когда отладчика недостаточно

Отладчик показывает, что делает ваш код. Технологический журнал (ТЖ) показывает, что происходит внутри платформы: блокировки, исключения, долгие вызовы СУБД и обращения к серверу. Он нужен, когда ошибка плавающая и шагами её не поймать.

ТЖ настраивается файлом logcfg.xml. Его кладут в каталог conf внутри каталога установки платформы, например C:\Program Files\1cv8\conf. Платформа перечитывает файл сама, перезапускать службу не нужно.

Минимальный пример: пишем исключения в отдельный каталог и храним сутки.

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://v8.1c.ru/v8/tech-log">
  <log location="C:\1c_logs\excp" history="24">
    <event>
      <eq property="name" value="EXCP"/>
    </event>
    <property name="all"/>
  </log>
</config>

Здесь location — каталог журнала, history — срок хранения в часах, событие EXCP — исключения. Каталог создайте заранее и дайте на него права учётной записи, от которой запущена служба 1С, иначе файлы не появятся.

Что важно помнить:

• 📁 Журнал быстро растёт. Ограничивайте события фильтром и всегда задавайте history.
• 💾 Пишите на отдельный диск, не на системный раздел. Заполненный диск остановит сервер.
• 🔍 Для поиска блокировок и ожиданий берут события TLOCK, TTIMEOUT, TDEADLOCK. Для медленных запросов — DBMSSQL или DBPOSTGRS с условием по длительности.

Управление кластером через rac и ras

Консоль серверов 1С — удобная вещь, но при отладке часто надо быстро посмотреть сеансы и процессы из командной строки. Для этого есть пара утилит: ras — сервер администрирования, rac — клиент к нему.

Сначала запускаем ras, указав порт и адрес агента:

ras cluster --port=1545 localhost:1540

Дальше rac обращается к нему. Базовые команды:

rac localhost:1545 cluster list
rac localhost:1545 session list --cluster=<идентификатор кластера>
rac localhost:1545 process list --cluster=<идентификатор кластера>

Идентификатор кластера вы получите из вывода первой команды. Список сеансов покажет, кто работает и в какой базе, а список процессов — какие рабочие процессы запущены и сколько памяти они занимают. Полный перечень подкоманд и параметров смотрите в справке rac help.

Завершать сеансы или процессы через rac можно, но делайте это осознанно: пользователь потеряет несохранённые данные. Для разработческой базы это обычно не страшно, для рабочей — повод предупредить людей.

Как разбирать логи и находить причину ошибки

Отладка и ТЖ дают материал, а выводы делаете вы. Порядок работы, который экономит время:

1. Воспроизведите проблему на тестовой базе и зафиксируйте точное время.
2. В ТЖ найдите событие EXCP рядом с этим временем. В строке будет текст исключения и контекст вызова.
3. Определите, где ошибка: в вашем коде, в типовой конфигурации, в СУБД или в платформе.
4. Если нужен ход выполнения, поставьте точку останова чуть раньше места падения и пройдите код по шагам.
5. Сравните поведение с точкой останова и без неё: если проблема пропала при отладке, подозревайте гонки и блокировки.

Для блокировок удобно собрать журнал с событиями TLOCK и TTIMEOUT и найти пары «кто ждал» и «кто держал». Для медленных запросов — отсортировать события СУБД по длительности и посмотреть самые тяжёлые.

Отключение отладки и уборка после работы

Закончили — верните сервер в исходное состояние. Забытый -debug и разросшийся журнал — самые частые «подарки» себе на будущее.

1. Уберите ключ -debug из строки запуска службы или из файла демона.
2. Перезапустите службу агента сервера, предупредив пользователей.
3. Переименуйте или удалите logcfg.xml, либо оставьте только узкий фильтр, который вам действительно нужен.
4. Очистите каталоги журналов, которые больше не нужны.
5. Закройте временные правила в брандмауэре, открытые для отладки.
6. Остановите ras, если запускали его вручную для этой работы.

Если на сервере работает несколько разработчиков, договоритесь о правилах: кто и когда включает отладку, где лежат журналы и кто их чистит. Иначе настройки накапливаются, и через месяц никто не помнит, зачем сервер запущен в режиме отладки.

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