Отладка серверного кода 1С 8.3: ключ -debug, Windows и Linux

Режим отладки на сервере 1С включается ключом -debug в командной строке службы агента сервера ragent.exe. Ключ дописывают в параметры службы (в Windows — через реестр, в Linux — в unit-файл или конфиг скрипта запуска), затем перезапускают службу. После этого серверные процедуры появляются в окне Отладка → Подключение Конфигуратора, и в них можно ставить точки останова.

Без этого ключа точки останова в модулях с &НаСервере срабатывают только в файловой базе. В клиент-серверной отладчик их просто пропускает, и кажется, что код не выполняется.

Что проверить перед включением отладки на сервере

Отладка серверного кода — инструмент для тестового контура. Перед тем как править службу, пройдитесь по списку:

• 🖥️ Сервер. Лучше отдельный тестовый сервер или копия базы на нём. На рабочем сервере включайте только на время и в нерабочие часы.
• 🔢 Версии. Конфигуратор и сервер должны быть одной версии платформы, вплоть до четвёртой цифры (например, оба 8.3.24.1586). Иначе Конфигуратор не подключится к базе вообще, а не только к отладке.
• 🔑 Права. Нужны права локального администратора на сервере (правка службы и реестра) и пользователь базы с правом на Конфигуратор.
• 🔌 Порты. При отладке по TCP отладчик ходит к рабочим процессам по портам из диапазона рабочего сервера (по умолчанию 1560:1591). При отладке по HTTP добавляется порт сервера отладки dbgs (по умолчанию 1550). Эти порты должны быть открыты от машины разработчика до сервера.
• 👥 Пользователи. Перезапуск службы агента обрывает все сеансы на сервере. Предупредите людей заранее.

TCP или HTTP: какой протокол выбрать

Для большинства задач хватает TCP. Протокол на сервере и в Конфигураторе должен совпадать, иначе предметы отладки не появятся.

Включение режима отладки на сервере 1С под Windows

Агент сервера в Windows работает как служба. Ключ -debug надо добавить в её командную строку.

Шаг 1. Найдите службу и текущую командную строку

Откройте PowerShell от имени администратора:

Get-CimInstance Win32_Service |
  Where-Object { $_.PathName -like '*ragent*' } |
  Select-Object Name, State, PathName | Format-List

Типичный результат для 64-битного сервера:

Name     : 1C:Enterprise 8.3 Server Agent (x86-64)
State    : Running
PathName : "C:\Program Files\1cv8\8.3.24.1586\bin\ragent.exe" -srvc -agent -regport 1541 -port 1540 -range 1560:1591 -d "C:\Program Files\1cv8\srvinfo"

Имя службы бывает другим, если сервер ставили с несколькими версиями платформы или вручную. Ориентируйтесь на PathName: в нём должен быть ragent.exe.

Шаг 2. Добавьте ключ -debug в реестр

1. Запустите regedit.
2. Перейдите в HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ и откройте раздел с именем службы из шага 1.
3. Дважды щёлкните параметр ImagePath.
4. Допишьте -debug после пути к ragent.exe, перед остальными ключами.

Было и стало:

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

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

Для HTTP-отладки вместо -debug пишут -debug -http.

Шаг 3. Перезапустите службу

Перезапуск агента обрывает сеансы всех пользователей сервера, включая фоновые задания. Делайте это, когда в базах никто не работает .

Restart-Service -Name "1C:Enterprise 8.3 Server Agent (x86-64)"

Или через services.msc: служба агента → Перезапустить.

Шаг 4. Убедитесь, что ключ применился

Повторите команду из шага 1 — в PathName должен быть -debug. Надёжнее посмотреть командную строку живого процесса:

Get-CimInstance Win32_Process -Filter "Name='ragent.exe'" | Select-Object CommandLine

Если -debug в реестре есть, а в процессе нет — служба не перезапускалась.

Включение отладки сервера 1С в Linux

В Linux порядок тот же: найти, как запускается ragent, и добавить ключ.

Старые сборки со скриптом srv1cv83 в /etc/init.d. Параметры читаются из файла /etc/sysconfig/srv1cv83 (RHEL-подобные системы) или /etc/default/srv1cv83 (Debian, Ubuntu). В нём есть переменная отладки:

SRV1CV8_DEBUG=1

Затем перезапуск:

sudo systemctl restart srv1cv83

Новые версии платформы с unit-файлом systemd. Посмотрите, как описан запуск:

systemctl list-units | grep -i 1c
systemctl cat <имя-службы>

Найдите строку ExecStart с ragent и переопределите её через sudo systemctl edit <имя-службы>: сначала пустая строка ExecStart=, затем исходная команда с добавленным -debug. Править сам файл в /lib/systemd или /opt/1cv8 не стоит — его перезапишет обновление платформы .

sudo systemctl daemon-reload
sudo systemctl restart <имя-службы>
ps -ef | grep [r]agent

В выводе ps у процесса ragent должен появиться ключ -debug.

Ключи командной строки и подключение из Конфигуратора

Включённая на сервере отладка ничего не делает, пока к ней не подключится Конфигуратор. Ключи, которые встречаются в этой работе:

Пример ярлыка тонкого клиента , который сразу подключается к отладке:

"C:\Program Files\1cv8\common\1cestart.exe" ENTERPRISE /S"srv-1c\buh_test" /DEBUG /DEBUGGERURL "tcp://dev-pc"

Порядок подключения в Конфигураторе:

1. Откройте базу в Конфигураторе на машине разработчика.
2. Для HTTP-отладки включите протокол HTTP в Сервис → Параметры, на закладке отладки.
3. Откройте Отладка → Подключение. В окне видны предметы отладки: клиентские сеансы и серверные.
4. Нажмите Автоматическое подключение и отметьте флажки «Сервер» и нужные клиенты (тонкий клиент, веб-клиент, фоновое задание).
5. Запустите клиент из Конфигуратора (F5) или ярлыком с /DEBUG.
6. Поставьте точку останова (F9) в серверной процедуре и выполните действие в клиенте.

Флажок «Сервер» в автоподключении появится только после того, как служба агента запущена с -debug. Это самый быстрый способ проверить, что ключ сработал.

Что настроить в консоли кластера для удобной отладки

Сам ключ -debug в консоли администрирования не включается. Но консоль помогает сделать сеанс отладки предсказуемым.

• ⏸️ Блокировка регламентных заданий. В свойствах информационной базы на тестовом сервере включите флажок блокировки регламентных заданий. Иначе задания обмена или загрузки курсов срабатывают в момент, когда вы стоите на точке останова, и путают картину.
• ⚙️ Рабочие процессы. В свойствах рабочего сервера задаются ограничения «Количество ИБ на процесс» и «Количество соединений на процесс». На тестовом сервере с одной базой удобно, чтобы все сеансы шли в один rphost — так проще сопоставлять записи логов с вашим сеансом.
• 👀 Сеансы. В ветке Сеансы базы видно, какой сеанс ваш, с какого компьютера и в каком процессе он работает. Если отладчик держит сеанс на точке останова, здесь он висит активным.
• 🔒 Блокировки. Ветка Блокировки показывает, что держит сеанс, остановленный в транзакции. Это пригодится, если коллеги жалуются на «зависание» во время вашей отладки.

Журнал регистрации и технологический журнал при отладке

Отладчик показывает одно выполнение. Логи показывают, что происходило до и после, в том числе в чужих сеансах.

Журнал регистрации

Смотрится в Конфигураторе через Администрирование → Журнал регистрации или в пользовательском режиме из раздела администрирования. Удобные фильтры при отладке:

• по пользователю и компьютеру — чтобы видеть только свои действия;
• по уровню «Ошибка» — исключения с текстом и модулем;
• по событию фонового задания — если отлаживаете обработку в фоне.

Физически журнал лежит на сервере в каталоге кластера, в папке базы: srvinfo\reg_1541\<идентификатор базы>\1Cv8Log. Идентификатор базы виден в консоли кластера в свойствах базы.

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

Технологический журнал пишет события платформы: исключения, запросы к СУБД, ожидания на блокировках. Он включается файлом 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="D:\techlog" history="24">
    <event>
      <eq property="name" value="EXCP"/>
    </event>
    <event>
      <eq property="name" value="DBMSSQL"/>
    </event>
    <event>
      <eq property="name" value="TLOCK"/>
    </event>
    <property name="all"/>
  </log>
</config>

Здесь history="24" — хранить 24 часа. На нагруженном сервере техжурнал без фильтров заполняет диск за часы. Пишите его на отдельный диск, включайте на время и отключайте, удалив или переименовав logcfg.xml.

Поиск узких мест: замер производительности

Когда сервер отлажен, следующий вопрос обычно — почему медленно. Для серверного кода есть два инструмента.

Замер производительности в Конфигураторе. Включается в меню Отладка → Замер производительности при подключённой отладке. Порядок:

1. Включите замер.
2. Выполните в клиенте медленную операцию один раз.
3. Выключите замер — откроется таблица строк кода с числом вызовов и временем.
4. Отсортируйте по проценту времени и идите сверху вниз.

С флажком «Сервер» в автоподключении замер покажет строки серверных модулей. Без серверной отладки в таблице будет только клиентский вызов, а всё время ляжет на одну строку с вызовом сервера.

Технологический журнал. Покажет то, чего нет в замере: сколько секунд шёл конкретный запрос к СУБД (DBMSSQL), ждал ли сеанс чужую блокировку (TLOCK), не было ли взаимоблокировки. В событиях есть свойство duration — длительность; в журналах 8.3 она в микросекундах.

Что обычно находится этими двумя способами:

• 🐢 запрос в цикле — тысячи вызовов одной строки в замере;
• 🔁 обращение через точку к реквизитам ссылки внутри цикла — неявные запросы к базе;
• ⏳ долгое ожидание блокировки — видно в TLOCK, а не в замере;
• 📦 передача больших коллекций между клиентом и сервером — много времени на строке вызова серверного метода.

Как выключить отладку и почему не оставлять её на рабочем сервере

Режим отладки на постоянной основе — плохая идея по трём причинам:

• 🛑 Остановка держит ресурсы. Если разработчик поставил точку останова в серверном коде внутри транзакции, сеанс замирает с открытой транзакцией. Его блокировки ждут другие пользователи.
• 🐌 Нагрузка. Сервер с отладкой тратит ресурсы на поддержку отладочной информации, серверный код работает медленнее.
• 🔓 Доступ. Любой, кто открыл базу в Конфигураторе, может подключиться к серверным предметам отладки и смотреть значения переменных в чужих сеансах, включая персональные данные.

Чтобы выключить:

1. Отключитесь от предметов отладки в Конфигураторе и закройте его.
2. Уберите -debug (и -http, если был) из ImagePath в реестре или из переопределения systemd. В старом скрипте Linux верните SRV1CV8_DEBUG=0.
3. Перезапустите службу агента — снова в момент, когда никто не работает.
4. Проверьте командную строку ragent, что ключа нет.
5. Снимите блокировку регламентных заданий, если включали её на рабочей базе, и уберите logcfg.xml.

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