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

Чтобы включить debug на сервере 1С, добавьте ключ -debug в строку запуска агента сервера ragent и перезапустите службу. В Windows это параметр ImagePath службы агента в реестре, в Linux — переменная SRV1CV8_DEBUG=1 или аргумент в unit-файле systemd. Флажка «включить отладку» в консоли кластера нет.

Типичная ситуация: программист поставил точку останова в общем модуле с директивой &НаСервере, запустил базу, а отладчик проходит мимо. В файловой базе всё работает, в клиент-серверной — тишина. Причина почти всегда одна: агент сервера запущен без режима отладки, и серверные процессы к отладчику не подключаются.

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

Без ключа -debug рабочие процессы rphost не принимают подключение отладчика. Клиентский код отлаживается, серверный — нет. Поэтому debug на сервере нужен, когда проблема живёт на стороне сервера.

Типичные поводы:

• 🐞 ошибка воспроизводится только в клиент-серверной базе, а в файловой копии её нет;
• ⏳ нужно пройти по шагам проведение документа, закрытие месяца , расчёт зарплаты;
• ⚙️ падает регламентное или фоновое задание, и надо увидеть значения переменных в момент ошибки;
• 🌐 нужно отладить HTTP-сервис или веб-сервис, который выполняется на сервере;
• 🔌 обмен через COM-соединение ведёт себя иначе, чем при ручном запуске.

Для разработки и тестовых баз отладку включают один раз и не выключают. Для продуктивного сервера — на время разбора инцидента, лучше в нерабочие часы.

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

У платформы 8.3 два механизма отладки. От выбора зависит строка запуска агента и настройка Конфигуратора.

При HTTP-отладке появляется посредник — сервер отладки dbgs.exe. Его запускает Конфигуратор или сам агент, и через него идут все команды отладчика. По умолчанию он слушает порт 1550.

💡 Если вы работаете в EDT, выбирайте HTTP: EDT использует именно этот протокол. Для Конфигуратора подойдут оба, но протокол в Конфигураторе и на сервере должен совпадать.

В Конфигураторе протокол выбирают в Сервис → Параметры, на закладке «Отладка». Там же задают адрес сервера отладки, если он запущен не на вашем компьютере.

Способ 1. Ключ -debug в службе агента сервера в Windows

Это основной и постоянный способ. Агент сервера работает как служба Windows, и всё, что передаётся ragent.exe при старте, записано в свойствах службы.

Шаг 1. Найдите имя службы

Откройте командную строку от имени администратора и выполните:

sc query state= all | findstr /i "1C:Enterprise"

Для 64-разрядного сервера имя обычно такое: 1C:Enterprise 8.3 Server Agent (x86-64). Если на сервере стоят несколько версий платформы, в имени может быть номер версии.

Шаг 2. Посмотрите текущую строку запуска

sc qc "1C:Enterprise 8.3 Server Agent (x86-64)"

В поле BINARY_PATH_NAME будет примерно так:

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

Номер версии, порты и каталог srvinfo у вас могут быть другими. Не меняйте их — только добавьте ключ.

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

Вариант через реестр:

1. Запустите regedit.
2. Перейдите в HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ и откройте раздел с именем службы из шага 1.
3. Откройте параметр ImagePath.
4. Сразу после пути к ragent.exe (после закрывающей кавычки) допишите -debug для TCP или -debug -http для HTTP.
5. Нажмите «ОК».

Результат должен выглядеть так:

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

Тот же результат даёт sc config. Пробел после binPath= обязателен, а внутренние кавычки экранируются обратной косой чертой:

sc config "1C:Enterprise 8.3 Server Agent (x86-64)" binPath= "\"C:\Program Files\1cv8\8.3.24.1342\bin\ragent.exe\" -debug -srvc -agent -regport 1541 -port 1540 -range 1560:1591 -d \"C:\Program Files\1cv8\srvinfo\""

Сделайте экспорт раздела службы из regedit перед правкой: одна потерянная кавычка — и служба не стартует.

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

net stop "1C:Enterprise 8.3 Server Agent (x86-64)"
net start "1C:Enterprise 8.3 Server Agent (x86-64)"

Можно и через оснастку services.msc. После старта проверьте sc qc ещё раз: ключ -debug должен быть в строке.

Способ 2. Отладка на сервере 1С под Linux

На Linux ключ передают так же, меняется только место, где записана строка запуска. Оно зависит от того, как установлен сервер.

Старая схема: init-скрипт и файл настроек

Если служба называется srv1cv83 и запускается скриптом из /etc/init.d/, параметры лежат в отдельном файле:

• /etc/sysconfig/srv1cv83 — в дистрибутивах семейства RHEL;
• /etc/default/srv1cv83 — в Debian и Ubuntu.

Найдите в нём строку с SRV1CV8_DEBUG, раскомментируйте и поставьте единицу:

SRV1CV8_DEBUG=1

Затем перезапустите службу (сеансы пользователей оборвутся):

sudo systemctl restart srv1cv83

Новая схема: unit-файл systemd

В свежих версиях платформы сервер регистрируется как unit systemd с номером версии в имени. Посмотрите, как он называется и что запускает:

systemctl list-units --all | grep -i srv1cv8
systemctl cat <имя-юнита>

В выводе systemctl cat найдите строку ExecStart с вызовом ragent. Править файл в каталоге платформы не надо — при обновлении он перезапишется. Создайте переопределение:

sudo systemctl edit <имя-юнита>

И впишите в открывшийся редактор:

[Service]
ExecStart=
ExecStart=<скопированная строка ExecStart> -debug

Пустой ExecStart= обязателен: он сбрасывает исходную команду, иначе systemd откажется запускать сервис с двумя командами. Потом:

sudo systemctl daemon-reload
sudo systemctl restart <имя-юнита>
ps aux | grep ragent

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

💡 При HTTP-отладке на Linux добавьте -debug -http и откройте в файрволе порт сервера отладки, по умолчанию 1550.

Способ 3. Временный запуск ragent из консоли

Когда службу трогать нельзя (например, она настроена подрядчиком) или отладка нужна на час, агент запускают вручную.

1. Остановите службу агента (сеансы оборвутся).
2. Откройте командную строку от имени администратора.
3. Запустите ragent с теми же параметрами, что в службе, но без -srvc и с ключом -debug:

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

4. Не закрывайте окно: пока оно открыто, сервер работает в режиме отладки.
5. После отладки закройте окно (Ctrl+C) и снова запустите службу — она стартует без -debug.

Каталог -d указывайте тот же, что у службы. Иначе агент создаст новый пустой кластер, и ваших баз в нём не окажется.

Что можно сделать в консоли администрирования кластера

Включить отладку из консоли нельзя: ключ задаётся только при запуске агента. Но консоль пригодится:

• 👀 найти сеанс программиста и фоновые задания в списке сеансов;
• 🔄 после перезапуска убедиться, что рабочие процессы rphost поднялись заново;
• ⛔ завершить зависший сеанс, если код остановлен на точке останова, а программист ушёл.

Перед завершением сеанса предупредите его владельца: несохранённые данные пропадут.

Подключение отладчика к серверу и проверка

Ключ на сервере — половина дела. Теперь Конфигуратор нужно подключить к серверным предметам отладки.

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

Если в окне подключения появились серверные предметы отладки, а точка останова в &НаСервере срабатывает — всё включено.

Запустить клиента в режиме отладки можно и без Конфигуратора, ключами командной строки:

"C:\Program Files\1cv8\8.3.24.1342\bin\1cv8.exe" ENTERPRISE /S "srv1c\buh" /DEBUG -http /DEBUGGERURL "http://devpc:1550"

Здесь srv1c\buh — сервер и имя базы, devpc — компьютер, где запущен отладчик. Клиент сам подключится к нему.

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

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

Файл кладут в каталог conf платформы:

• Windows: C:\Program Files\1cv8\conf\logcfg.xml;
• Linux: /opt/1cv8/conf/logcfg.xml или каталог conf конкретной версии.

Перезапуск не нужен: платформа сама перечитывает файл, обычно в течение минуты.

Пример: только исключения и долгие обращения к СУБД, хранение 24 часа.

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://v8.1c.ru/v8/tech-log">
  <dump create="false"/>
  <log location="D:\1c_tj" history="24">
    <event>
      <eq property="name" value="EXCP"/>
    </event>
    <event>
      <eq property="name" value="DBMSSQL"/>
      <gt property="duration" value="1000000"/>
    </event>
    <property name="all"/>
  </log>
</config>

Как читать параметры:

• location — каталог журнала, лучше на отдельном диске, не системном;
• history — сколько часов хранить, старые файлы платформа удаляет сама;
• <eq>, <ne>, <gt>, <lt> — фильтры: «равно», «не равно», «больше», «меньше»;
• duration в 8.3 задаётся в микросекундах, поэтому 1000000 — это одна секунда.

Что исключать из записи

Журнал без фильтров на нагруженном сервере пишет гигабайты в час. Отсекайте лишнее сразу:

• 🚫 не пишите все события подряд: условие <ne property="name" value="..."/> без других фильтров оставляет почти весь поток;
• 🎯 ограничивайте журнал одной базой: добавьте в событие <eq property="p:processName" value="buh"/>, где buh — имя базы в кластере;
• ⏱ для запросов к СУБД ставьте порог по duration, иначе в журнал попадут тысячи быстрых запросов;
• 👤 для разбора жалобы конкретного человека фильтруйте по свойству Usr.

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

Отладку на продуктивном сервере выключают сразу после работы. Порядок такой:

1. Отключите Конфигуратор от предметов отладки и закройте его.
2. Уберите ключ -debug (и -http, если добавляли) из ImagePath, из SRV1CV8_DEBUG или из переопределения systemd. Для systemd проще всего удалить переопределение: sudo systemctl revert <имя-юнита>.
3. Перезапустите службу агента в нерабочее время — сеансы пользователей оборвутся.
4. Удалите или переименуйте logcfg.xml. Подождите пару минут, пока платформа перестанет писать журнал.
5. Скопируйте нужные файлы журнала в архив для разбора, остальное удалите из каталога location.

Разбирать журнал удобно не на самом сервере: скопируйте файлы .log на рабочую машину и ищите по ним findstr или grep. Каждая строка начинается с времени события и длительности, дальше идёт имя события, например EXCP или DBMSSQL.

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