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

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

Без этого ключа точки останова в модулях с &НаСервере, в модулях менеджеров и в общих серверных модулях просто не срабатывают: клиент-серверная база выполняет этот код в рабочих процессах rphost, а они запущены без отладки. Ниже — порядок для Windows и Linux, проверка кластера утилитами ras и rac, настройка технологического журнала и возврат сервера в рабочий режим.

Подготовка сервера 1С к отладке и меры безопасности

Отладку на сервере 1С включают для всего кластера сразу. Каждый рабочий процесс начинает принимать подключения отладчика, и это касается всех баз на этом сервере. Поэтому сначала решите, где вы будете отлаживать.

🔹 Лучший вариант — отдельный тестовый сервер или копия базы на нём. Отладка не мешает пользователям, можно спокойно ставить точки останова.

🔹 Рабочий сервер — только если ошибка воспроизводится исключительно там. Тогда включайте отладку в нерабочее время и выключайте сразу после поиска.

Что подготовить заранее:

1. Права локального администратора на сервере — без них не поменять параметры службы.
2. Учётную запись администратора кластера, если она задана: пригодится для rac.
3. Номер версии платформы на сервере. Конфигуратор, из которого вы отлаживаете, должен быть той же версии, иначе он не подключится к базе.
4. Окно для перезапуска службы. Перезапуск агента обрывает все сеансы пользователей на сервере — предупредите людей и дождитесь, пока они закроют документы.

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

Как включить отладку на сервере 1С под Windows

На Windows агент сервера работает как служба. Её имя зависит от версии и способа установки, обычно это 1C:Enterprise 8.3 Server Agent (x86-64). Точное имя посмотрите в services.msc, в свойствах службы на вкладке «Общие».

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

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

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"

Сохраните её в текстовый файл. Это ваша точка отката.

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

Удобнее всего править через реестр:

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

Должно получиться так:

"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" -debug

Шаг 3. Выберите протокол: TCP или HTTP

В платформе 8.3 есть два механизма отладки.

Для HTTP можно задать адрес, порт и пароль сервера отладки ключами -debugServerAddr, -debugServerPort и -debugServerPwd. По умолчанию сервер отладки слушает порт 1550. Пароль ставьте всегда, если сервер виден кому-то, кроме вас.

Пример хвоста строки для HTTP:

-debug -http -debugServerPwd StrongPass42

Протокол в Конфигураторе должен совпадать с протоколом сервера. Его выбирают в параметрах Конфигуратора, в разделе про отладку: там же указывают адрес сервера отладки для HTTP.

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

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

Если служба не стартует, почти всегда виновата опечатка в ImagePath: лишняя кавычка или ключ, слипшийся с путём. Верните строку из сохранённого файла и допишите -debug заново.

Режим отладки на сервере 1С под Linux

На Linux порядок тот же: добавить -debug к запуску ragent и перезапустить сервис. Отличается только место, где хранится строка запуска.

🐧 Старые установки со скриптом srv1cv83. Параметры лежат в файле /etc/sysconfig/srv1cv83 (семейство Red Hat) или /etc/default/srv1cv83 (Debian, Ubuntu). Найдите строку SRV1CV8_DEBUG, снимите комментарий и поставьте значение 1:

SRV1CV8_DEBUG=1

Затем перезапустите сервис:

sudo systemctl restart srv1cv83

🐧 Установки с юнитом systemd. В свежих версиях 8.3 сервер ставится юнитом, в имени которого есть номер версии. Список юнитов покажет команда:

systemctl list-units --type=service | grep 1cv8

Строку запуска не правьте прямо в файле пакета: он перезапишется при обновлении. Используйте sudo systemctl edit <имя юнита>, переопределите ExecStart, скопировав исходную строку и добавив -debug, затем выполните sudo systemctl daemon-reload и перезапуск сервиса.

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

Сервер готов, теперь нужно, чтобы Конфигуратор подключался к его процессам.

1. Откройте базу в Конфигураторе по тому же пути, по которому работают пользователи: сервер\имя_базы.
2. Убедитесь, что протокол отладки в параметрах Конфигуратора совпадает с серверным.
3. Откройте Отладка → Подключение.
4. Нажмите кнопку автоматического подключения и отметьте в списке серверные предметы отладки. Для отладки тонкого клиента нужен как клиент, так и сервер.
5. Запустите Отладка → Начать отладку → Тонкий клиент или подключитесь к уже открытому сеансу через окно «Подключение».
6. Поставьте точку останова в процедуре с директивой &НаСервере и выполните действие в клиенте.

Если выполнение остановилось на точке — отладка на сервере работает.

Замер производительности по серверным вызовам

Включённая серверная отладка открывает ещё один инструмент — замер производительности. Запустите его в Конфигураторе командой из меню Отладка, выполните медленную операцию в клиенте и остановите замер.

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

Утилиты ras и rac: проверка кластера после включения отладки

Сам ключ -debug через rac не включается — он задаётся только в строке запуска агента. Но связка ras + rac нужна, чтобы убедиться, что кластер после перезапуска жив, и понять, какой рабочий процесс обслуживает нужную базу.

ras — сервер администрирования, rac — консольный клиент к нему. На Windows ras обычно запускают так:

"C:\Program Files\1cv8\8.3.24.1342\bin\ras.exe" cluster --port=1545 localhost:1540

Здесь 1545 — порт самого ras, а 1540 — порт агента сервера. Для постоянной работы ras регистрируют отдельной службой, но для разовой проверки хватит запуска в окне консоли.

Дальше в другом окне:

rac localhost:1545 cluster list

Команда выведет кластеры и их идентификаторы. С идентификатором кластера смотрите рабочие процессы и сеансы:

rac localhost:1545 process list --cluster=<id кластера>
rac localhost:1545 session list --cluster=<id кластера>

По списку сеансов видно, кто сейчас работает в базе. Это пригодится, чтобы не подключиться отладчиком к сеансу бухгалтера вместо своего. Если на кластере задан администратор, добавляйте к командам --cluster-user и --cluster-pwd. Остальные подкоманды смотрите в справке rac help.

Технологический журнал: уровни детализации и файл logcfg.xml

Отладчик показывает, что делает код. Но если жалоба звучит как «по утрам всё тормозит», точку останова ставить некуда. Здесь нужен технологический журнал — журнал событий платформы, который пишет каждый процесс сервера.

Журнал настраивают вручную файлом logcfg.xml. Его кладут в каталог conf установленной платформы, например C:\Program Files\1cv8\8.3.24.1342\bin\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="TDEADLOCK"/>
    </event>
    <event>
      <eq property="name" value="TTIMEOUT"/>
    </event>
    <property name="all"/>
  </log>
</config>

Что здесь задано:

• 📁 location — каталог для журнала. Выбирайте диск с запасом места, не системный.
• 🕒 history="24" — сколько часов хранить файлы. Старые платформа удаляет сама.
• ⚡ EXCP — исключения, то есть ошибки, которые видели пользователи и которые падали «молча».
• 🔒 TDEADLOCK и TTIMEOUT — взаимоблокировки и ожидания на управляемых блокировках, частая причина тормозов при одновременном проведении.
• 📋 <property name="all"/> — писать все свойства событий, включая контекст: строку модуля, где возникло событие.

Как выбрать детализацию

Технологический журнал не имеет переключателя «уровень 1–5». Детализацию задаёт набор событий и фильтров.

Для поиска медленных запросов к СУБД ставьте фильтр по свойству duration и проверяйте единицы измерения в документации к своей версии платформы: ошибка в порядке числа превращает фильтр в «пиши всё».

Анализ логов: где искать причины ошибок и тормозов

Журнал раскладывается по подкаталогам с именами процессов: rphost_4520, rmngr_3104, ragent_2980. Число — идентификатор процесса. Внутри — файлы по часам с именем вида 24100709.log: год, месяц, день и час.

Каждая строка начинается со времени и длительности события, затем идёт имя события и свойства через запятую. Для ошибок самое ценное — свойства Descr (текст ошибки) и Context (стек вызовов с модулем и номером строки).

Быстрый поиск без сторонних программ в PowerShell:

Select-String -Path "D:\techlog\*\*.log" -Pattern "TDEADLOCK" | Select-Object -First 20

На Linux то же делает grep:

grep -r "EXCP" /var/log/1c/techlog/ | head -50

Порядок разбора на практике:

1. Узнайте у пользователя время ошибки с точностью до минуты.
2. Откройте файлы этого часа во всех каталогах rphost_*.
3. Найдите событие EXCP или TTIMEOUT в нужную минуту.
4. По свойству Context выйдите на модуль и строку кода.
5. Поставьте там точку останова и повторите сценарий уже под отладчиком.

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

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

Отладку не оставляют включённой «на всякий случай». Серверные процессы тратят ресурсы на поддержку отладчика, а открытый порт отладки — лишняя дверь в систему.

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

Частые вопросы об отладке на сервере 1С