Svacer Wiki - User contributions [en]

Changelog

2026-02-09T06:31:42Z

Chernykov sv:

=== Release 12-0-1 ===

* Убраны ограничения на размер поля advanced filter в пользовательских фильтрах
* В публичных запросах возвращающих маркеры добавлено поле <code>checker_situation</code> соответствующее полю `situation` в детекторах
* Добавлена возможность фильтрации по <code>checker_situation</code> в advanced filter
* Добавлена возможность фильтрации по <code>checker_labels</code> в advanced filter
* Добавлен публичный фильтр по детекторам, соответствующим <code>ГОСТ 71207-2024</code> . Импортировано описание детекторов из <code>Svace version 5.0.251220</code>
* При миграции со старых версий баз (а так же при миграциях, связанных с изменением схемы генерации инвариантов) реализовано полное сохранение разметки и комментариев на маркерах и последующее восстановление пропущенных, после миграций, разметок и комментариев (при обнаружении таковых)
* Вынесен ряд timeout-ов на уровень переменных окружения для адаптации под пользовательские сценарии
* Добавлена подсветка синтаксиса для языка Lua
* Исправлены проблемы безопасности, связанные с импортом данных и механизмом токенов доступа (PAT)

=== Release 12-0-0 ===
28.11.2025

* API методы на fullmarkers позволяют [[Help:Public API#Примеры использования фильтров в public api|указать фильтр]] с полем фильтрации по checker reliability
* В функциональность полнотекстового поиска добавлен поиск маркеров по id и инварианту
* Промежуточное хранилище при импорте результатов командой <code>svacer import / svacer sarif2 import</code> теперь использует новый формат представления. Это должно снизить использование памяти при импорте
* Сериализация JSON переведена на jsonv2 библиотеку в Go
* Импорт SARIF теперь более устойчив к пропускам в файле (отсутствие таких полей как location)
* Добавлены переменные окружения <code>SVACER_TIMEOUT_IMPORT_RESULTS</code> для [[Help:Configuration#Переменные окружения|контроля таймаута]] на ожидание начала импорта результатов и <code>SVACER_NUM_PARALLEL_IMPORTS</code> на [[Help:Configuration#Переменные окружения|ограничение числа параллельных импортов]]. По умолчанию значения 15 минут и <code>(максимальное число коннектов к БД) / 2</code>. Ограничения необходимы для предотвращения бесконечных ожиданий и зависаний при импорте данных
* Убраны лишние сообщения об устаревших детекторах при старте сервера или импорте снимков
* В метрики Prometheus добавлен ряд показателей размеров object store
* Размер лога сервера, показываемого в Web-интерфейсе, ограничен. Размер [[Help:Configuration#Переменные окружения|задается переменной окружения]] SVACER_TAIL_LOG_SIZE (по умолчанию 1Мб). Показывается последний кусок не более SVACER_TAIL_LOG_SIZE. Сам лог файл не ограничивается в размерах и кнопка выгрузки лога выгружает полный лог
* ['''Экспериментально'''] Можно [[Help:Configuration#Переменные окружения|указать JSON-формат]] лог-файла посредством параметра <code>svacer-server --log-format=json ...</code>, также формат может быть указан через переменную окружения <code>SVACER_LOG_FORMAT=json</code>. Опции также работают для CLI-клиента svacer
* При запуске сервера можно указать флаг <code>--force-invariant-refresh</code> для принудительной регенерации инвариантов. Это может решить проблему с переносом разметки
* Добавлена переменная окружения SVACER_INV_GEN_JOBS для контроля числа параллельных заданий при регенерации инвариантов. При ограниченных ресурсах машины рекомендуем ставить значение 2. По умолчанию значение ставится в 70% от <code>runtime.GOMAXPROCS</code>
* Добавлена функциональность по чистке object store при удалении снимков
* Добавлена возможность создания [[Afilters|сложных пользовательских фильтров]] по условиям, выраженным предикатом
* Проведена работа по предотвращению зависаний при исчерпывании доступных соединений с PostgreSQL сервером
* Добавлен файл с чексуммой бинарника сервера <code>svacer-server</code> и проверка чексуммы при запуске
* Упростили [[Help:XSvacer:AIAssistant#Активация и запуск ИИ-ассистента|деплой ИИ-ассистента]]: добавили его сервис в docker-compose и deb/rpm пакеты
* Расширили возможности конфигурации при запуске сервера через [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose]: теперь можно включить debug, указать конфиг LDAP и параметр public-url
* Добавлена возможность указания минимального количества снимков, которое необходимо оставлять в ветке, тип очистки и период удаления в [[Help:CLI/cleanup|автоматическом удалении снимков]]
* ['''Экспериментально'''] Добавлена возможность [[Edit markers (command line)|автоматически обрабатывать маркеры]] при импорте данных. Также обработка маркеров доступна через [[Help:UI manual#Работа со снимками|UI]]
* Добавлен флаг <code>diff-url</code> для команды <code>quickdiff</code> в CLI, также как и для команд <code>import</code>, <code>upload</code>, <code>sarif2 import</code> с указанием опции <code>quick-stat</code>. Данный флаг позволяет получать ссылку на diff снимков
* Добавлены предупреждения если в командах <code>import</code>, <code>sarif2 import</code> используются флаги, которые используются флагом <code>upload</code>, но флаг <code>upload</code> не установлен
* Добавлена интеграция с внешними системами посредством механизма [[Help:Configuration#Механизм интеграции с внешними системами посредством Webhook-ов|Webhooks]]
* Добавлена [[Help:Configuration#Настройка защиты от перебора паролей пользователей|защита от перебора пароля пользователя]]
* Добавлена возможность задать [[Help:Configuration#Настройка парольной политики внутреннего механизма аутентификации Svacer|парольную политику безопасности]] для пользователей, использующих встроенный механизм аутентификации Svacer
* Добавлена возможность задать [[Help:Configuration#Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутреннего механизма аутентификации Svacer)|вкладку по умолчанию]] для страницы входа в систему
* Исправлена ошибка, приводящая к разрастанию базы данных
* Исправлена ошибка, связанная с невозможностью в ряде случаев использовать механизм подписок
* Форма [[Help:UI manual#Разметка маркера с помощью ассистента AI|разметки]] с помощью [[Help:XSvacer:AIAssistant|ИИ-ассистента]] реализована в основном интерфейсе Svacer
* [[Help:XSvacer:Webide#Запуск функциональности при использовании docker compose|Упрощён запуск функциональности Webide]] при запуске сервера через [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose]

=== Release 11-2-0 ===
22.07.2025

* Исправлены зависания сервера
* Добавлено автоматическое удаление архивов и прочих временных файлов при импорте .svace-dir и SARIF-файлов через REST API

=== Release 11-1-0 ===
08.07.2025

* Команды <code>--project-group, --if-no-group, --autoclean, --autoclean-svace</code> можно использовать в REST API для импорта svace-dir
* При использовании REST API для импорта svace-dir сервер будет автоматически удалять директории <code>.svace-dir</code> и <code>.svacer</code> если не указаны явные опции <code>--autoclean=false, --autoclean-svace=false</code>
* Добавлена опция запуска сервера <code>--classic-inv-mode</code> для включения режима совместимости по генерации инвариантов с версией <= 8.x.x
* Исправлены ошибки в работе <code>--quality-gate</code>, добавлена возможность учета статусов разметки. Добавлена возможность [[Help:Import from Svace#Флаг --baseline|указания baseline]] для сравнений при использовании опции <code>--quality-gate</code>
* Исправлены ошибки при подключении к PostgreSQL в SSL-режиме
* Исправлен ряд ошибок при работе с LDAP
* Команда <code>quickdiff</code> в CLI теперь выдает информацию также о Same и Matched предупреждениях

=== Release 11-0-0 ===
19.05.2025

* Убраны излишние сообщения в логе сервера о login/logout операциях. Они будут выводиться только при запуске сервера с опцией <code>--debug</code>
* Команды CLI <code>svacer sarif *</code> были убраны, для [[Help:Sarif|импорта и экспорта]] следует использовать <code>svacer sarif2 *</code>
* Экспорт SARIF теперь включает все комментарии как отдельные объекты в <code>Properties</code>
* При экспорте в SARIF теперь экспортируются поля <code>Labels, Orig function</code>
* Импорт SARIF теперь корректным образом учитывает relatedLocations и формирует трассу
* Импорт SARIF теперь автоматически импортирует исходники, если они включены в сам SARIF файл
* Добавлена возможность указания [[Help:Sarif#Мэппинг severity|мэппинга severity]] детекторов при импорте из SARIF
* Добавлен механизм указания правил резолвинга путей при импортировании исходного кода вместе с SARIF файлом
* Экспорт исходников из снимка будет доступен только при наличии исходников на сервере
* Добавлены флаги <code>--autoclean</code>, <code>--autoclean-svace</code> в команду <code>svacer import</code> для автоматического удаления <code>.svace-dir / .svacer-dir</code> после успешного импорта и загрузки данных на сервер
* Улучшена поддержка [[OIDC]]
* Улучшена поддержка [[LDAP configuration|LDAP]]
* Добавлена интеграция с хранилищем секретов [[Infisical]]
* Добавлена [[Notifications|служба нотификаций]] пользователей через почтовые сообщения и мессенджер telegram
* Добавлен механизм аутентификации и [[Help:UI manual#Управление токенами доступа|управления]] персональными токенами доступа
* Добавлен механизм упоминания пользователей через специальную конструкцию @login в комментариях к разметке
* В разделе Статистика добавлен дашборд с [[Release notes 11-0-0#Изменения в разделе Статистика|Общей статистикой]], содержащей метрики по последним импортированным снимкам в ветках проектов
* В статистике по активности пользователей добавлена возможность просмотра панели с актуальной информацией о маркере и опция показа только действий с актуальной разметкой
* Большинство CLI команд, работающих с сервером, теперь делают явный logout после завершения
* Svacer при импорте результатов Svace автоматически импортирует файлы <code>*.warn, *.err</code> с предупреждениями от самого анализатора Svace. Автоматический импорт не будет происходить при размере этих файлов более 30Мб (большой размер может свидетельствовать о проблемах в ходе анализа)
* Переменная окружения <code>SVACER_CACHE_DIR</code> теперь учитывается во всех местах (ранее в ряде случаев мог неявно использоваться <code>$HOME/.cache</code>)
* Добавлена возможность [[Help:CLI/cleanup|автоматического удаления снимков]]

=== Release 10-0-1 ===
17.02.2025

* Исправлена ошибка с временной таблицей при обработке планов автомиграции разметки при импорте результатов (ERROR: relation "loaded_review" already exists)

=== Release 10-0-0 ===
16.01.2025

* Множество изменений в UI, смотрите [[Release notes 10-0-0]]
* Сделали [[Help:Installation#deb/rpm|dnf/yum репозиторий]] для RPM-пакетов Svacer
* Реализована возможность [[Markup2|экспорта, импорта и копирования разметки посредством Public REST API и CLI]]
* Реализован дополнительный экспериментальный механизм [[Help:UI manual#Настройка интерфейса|генерации PDF на основе HTML]]. Генерация PDF переведена на асинхронный режим с показом нотификации пользователю
* Добавлена возможность очистки всей разметки и/или комментариев на ветке проекта
* Улучшения функциональности просмотра маркеров в встроенном IDE Theia
* Добавлена функциональность по [[Help:UI manual#Глобальный поиск|глобальному поиску]] маркеров, комментариев и снимков по различным атрибутам
* Добавлена возможность [[Help:UI manual#Просмотр статистики|получения статистики]] по маркерам и активностям пользователей при разметке
* В API fullmarkers добавлен параметр <code>labels: true/false</code> для выгрузки меток маркера
* Реализован Public API для получения/добавления/удаления меток маркеров
* Настройки LDAP и прочие настройки аутентификации добавлены в единый конфигурационный файл
* Добавлена возможность удаления кода из снимка при частичном импорте в Svacer
* Добавлена опция minVersion, maxVersion для TLS при запуске сервера Svacer
* Добавлена поддержка групп проектов при импорте снимков в CLI
* При импорте снимков реализована поддержка автоматического определения пути префикса для переноса разметки
* Исправлен ряд ошибок в импорте и генерации [[Help:Sarif|SARIF]]
* Исправлены ошибки в копировании разметки между ветками, клонировании проектов и веток
* Добавлена возможность отключения бэкграунд задач по очистке мусора
* Добавлено экспериментальное CLI API для просмотра асинхронных задач на генерацию PDF
* Добавлена возможность визуализации производительности сервера на основе [https://github.com/arl/statsviz statsviz]
* Добавлена поддержка относительных путей в svres файле
* Добавлена возможность ожидания завершения операций по очистки мусора при выполнении операций по импорту результатов анализа
* Добавлена поддержка CWE таксономий при экспорте [[Help:Sarif|SARIF]]
* Добавлена переменная окружения SVACER_TOKEN_LIFETIME для управления временем жизни токена аутентификации
* Добавлена переменная окружения SVACER_RESET_ADMIN_PASSWORD для явного указания желаемого пароля при операции по сбросу пароля администратора
* Добавлен [[Notifications|механизм нотификаций пользователей]] о внутренних событиях Svacer (экспериментальный функционал)

=== Release 9-0-2 ===
22.07.2024

* Еще некоторые исправления, связанные с миграцией данных
* Исправлена проблема с навигацией по Go to Definition

=== Release 9-0-1 ===
15.07.2024

* Исправлены ошибки в клонировании проектов, приводящие к размножению записей в некоторых внутренних таблицах
* Различные исправления, связанные с миграцией данных
* Исправлена работа ряда CLI команд с включенным TLS на сервере
* Исправлен ряд ошибок в генерации PDF

=== Release 9-0-0 ===
04.06.2024

* Множество изменений в UI, смотрите [[Release notes 9-0-0]]
* Svacer разделен на два исполняемых файла: <code>svacer-server</code> — сервер и <code>svacer</code> — клиент
* {{Note}}Object store заменен на другую реализацию. Конвертация данных запускается автоматически при апгрейде и требует примерно 2х-2.2х дискового пространства, после конвертации старый object store будет удален. Время конвертации зависит от объема данных и скорости диска
* {{Note}}Изменен [[Help:Match|алгоритм сопоставления предупреждений]]. При старте сервера будет произведена регенерация всех инвариантов во всех ветках. Это может занять продолжительное время (зависит от мощности сервера и объемов данных)
* Добавлена возможность [[Help:Match#Ручное сопоставление предупреждений (экспериментальная возможность)|ручного сопоставления предупреждений]] для переноса разметки
* Добавлена экспериментальная поддержка [[OIDC|OpenID]] протокола для аутентификации
* Добавлена экспериментальная возможность [[Help:CLI#Слияние снимков из CLI (экспериментальная опция)|слияния снимков через CLI]]
* Исправлены баги в [[Help:Sarif|импорте Sarif]], добавлена поддержка импорта с относительными путями к файлам (флаг <code>--base-dir</code>)
* Лог сервера работает в режиме append, прежние данные не затираются
* Добавлена возможность передачи токена аутентификации в клиент Svacer через переменную окружения <code>SVACER_AUTH_TOKEN=token</code>
* Добавлена возможность передачи логина и пароля в клиент Svacer через переменную окружения <code>SVACER_AUTH_CREDS=login:password</code>
* Добавлен public REST endpoint для импорта <code>.svace-dir</code> на стороне сервера
* Добавлена возможность импорта <code>.svace-dir</code> из веб-интерфейса
* Добавлены [[Metrics|метрики]] для Prometheus, доступны при запуске сервера с переменной окружения <code>SVACER_TRACE_OPTIONS=prom_metrics_on</code> на <code>/api/metrics</code>
* Добавлена очистка БД от мусора с возможностью настройки периодичности данной операции через переменную окружения <code>SVACER_GC_PERIOD=val</code> где val — duration в формате <code>hhmmss</code> или [https://en.wikipedia.org/wiki/Cron Cron]
* Добавлена возможность клонирования проектов
* Добавлен импорт <code>*warn, *.err</code> файлов из <code>.svace-dir</code>, которые содержат диагностические сообщения от Svace
* Добавлена возможность [[Help:CLI#Ограничение числа запросов|ограничения числа запросов]] на сервер с указанием параметров в переменной окружения <code>SVACER_SERVER_THROTTLE_PARAMS</code>
* Добавлен шаблон для импорта разметки из кода на Go: <code>DEFAULT_GO</code>
* Добавлена возможность [[Help:CLI#Аутентификация из файла|аутентификации из файла]]
* Исправлены проблемы безопасности
* Добавлена возможность просмотра исходного кода снимка с предупреждениями анализатора во внешней IDE собранной на базе [https://theia-ide.org/ Theia IDE]
* К команде automigrate add в CLI добавлен флаг <code>skip-exist</code>, чтобы при добавлении паттерна, который уже существует, не выдавало ошибки
* К команде upload (import с флагом upload) с указанием флага <code>quality-gate</code> теперь можно добавить флаг <code>quality-gate-verbose</code>. Если его указать, то также будет выведен результат успешных проверок quality-gate
* Улучшения в поддержке протокола LDAP

=== Release 8-0-1 ===
22.01.2024

* Исправлена работа в изолированной от сети среде. Загрузка Web UI больше не требует доступа к публичным CDN
* Добавлена поддержка функций при указании пользовательского фильтра
* Добавлено API для управления пользовательскими фильтрами. Детали и пример использования можно найти здесь: https://gitlab.ispras.ru/svacer-public/api-go-examples/-/tree/master/api-ui-settings
* Исправлено отображение Checker Severity при экспорте в SARIF. Теперь Critical -> error; Major, Normal -> warning; Minor -> note; any other -> warning

=== Release 8-0-0 ===
21.11.2023

* Множество изменений в UI. Смотрите обзор в [[Release notes 8-0-0]]
* Добавлен новый импорт и экспорт из SARIF в command line с поддержкой исходного кода в SARIF файлах и импортом описания детекторов из SARIF
* Добавлены группы проектов
* Переделана модель ролей и доступов. Добавлен CLI для управления ролями и доступами
* Добавлена возможность настройки автопереноса разметки между ветками, в том числе в разных проектах
* Импорт/экспорт снимков включает информацию о детекторах
* Исправлена работа интерфейса с Undefined детекторами (т. е. детекторами, информация о которых отсутствует в Svacer)
* Добавлено экспериментальное API по управлению детекторами и конфигурациями детекторов
* Добавлена очистка исходного кода от Svacer-specific комментариев перед экспортом разметки в код
* Добавлена возможность включения режима обязательного комментария при разметке кода. Комментарий будет сгруппирован с операцией разметки и будет иметь ссылку на нее
* Утилита миграции со старого svace-сервера больше не поддерживается. При необходимости миграции используйте утилиту из прошлых релизов Svacer
* Добавлена Swagger документация на API
* Добавлено хранение истории изменений комментариев
* Опция <code>--pathPrefix</code> поддерживает файлы в JSON формате вида: <code>[{ "prefix": "/some/path", "replace": "/test" }, ...]</code>
* При использовании операции по обновлению <code>pathPrefix</code> на сервере, данные о прежнем <code>pathPrefix</code> запоминаются в мета-информации о снимке
* Добавлена возможность переименования снимков в UI
* Sensitive информация (детали подключения к БД с данными аутентификации) убрана из UI и API
* ОС в docker-образе Svacer обновлена с Ubuntu 18 до Ubuntu 22
* Улучшена логика автоопределения портов и протоколов при соединении с сервером из Svacer CLI

=== Release 7-0-1 ===
23.05.2023

* Исправлена проблема с фильтрацией предупреждений для C# проектов

=== Release 7-0-0 ===
16.05.2023

* Убрана зависимость от PostgreSQL из .deb и .rpm пакетов, чтобы проще было ставить Svacer только как клиент
* Сделан пакет для Windows (.msi) и документация по установке и запуску на Windows
* Теперь, если при svacer import и svacer sarif не указан путь к проекту, им считается текущая директория
* Информация о разметке и блокировках теперь обновляется автоматически при изменении в другом браузере (табе) или другим пользователем
* UI для пользовательских фильтров улучшен и перенесен в правую верхнюю часть экрана
* UI для выбора проекта, ветки и снимка теперь находится на одном уровне
* Улучшен UI для режима сравнения снимков
* Добавлена возможность работать одновременно с несколькими открытыми файлами в режиме Code, это поведение можно изменить в настройках профиля пользователя
* В левой навигационной панели детекторы теперь по умолчанию группируются по серьезности, это поведение можно изменить в настройках профиля пользователя
* Профиль текущего пользователя теперь можно смотреть/редактировать только через меню в правом верхнем углу
* Добавлена возможность копирования в системном логе и журнале
* Для пользователя теперь запоминается последний контекст (проект/ветка/снимок), с которым он работал, он автоматически открывается при старте новой сессии
* Групповая разметка теперь делается единой транзакцией, в случае ошибок или отмены все изменения откатываются
* Добавлено предупреждение при использовании некорректных путей при использовании REST API с префиксом /api
* Поддержка указания паролей из файла или pipe-а при использование Svacer CLI
* Добавлена поддержка multi-tab code view для режима просмотра кода объекта сборки
* Добавлена поддержка сохранения информации об удаленных детекторах при загрузке информации о детекторах из новой версии Svace
* Исправлен импорт результатов анализа, если сборка проводилась с опцией --disable-dxr
* Исправлены проблемы при импорте и прикреплении нескольких файлов к снимку
* Исправлены ошибки с входом в систему пользователей LDAP (специальные символы в пароле, вход по атрибуту mail)
* Добавлена возможность использования резервных серверов LDAP
* Добавлена возможность автоматического назначения пользователям LDAP роли Svacer, в зависимости от принадлежности пользователя к LDAP группе
* Добавлены новые public запросы на получение маркеров/снимков/проектов с учетом заданных параметров фильтрации
* Добавлена поддержка TLS при работе сервера по протоколам HTTP и gRPC
* Добавлена возможность загрузки статистики по общему количеству предупреждений и по количеству размеченных предупреждений для проектов и веток через REST API
* Добавлена вкладка выбора проектов в расширении VSCode
* Убрана возможность использовать всплывающее окно в VScode для добавления/редактирования/удаления комментариев, установки ревью-статусов, локов и т.д.

=== Release 6-0-3 ===
25.01.2023

* RPM-пакет теперь при сборке упаковывается в gzip вместо zstd для обратной совместимости со старыми дистрибутивами
* Если short url некорректен, то Svacer теперь будет возвращать корректный http error NotFound
* Если путь к лог файлу явно не указан, то svacer.log будет создаваться во временной директории. Это решает проблемы при запуске Svacer из директорий с запретом на запись. Путь к лог файлу будет печататься в stdout
* Лог файлы не будут создаваться, когда используется опция --help
* Исправлены проблемы при миграции схемы данных, когда в PostgreSQL используется SSL подключение
* Добавлены описания детекторов из последнего релиза Svace, которые были пропущены в релизе 6-0-2
* Исправлена работа Svacer за proxy-сервером, где выставляется Header "X-Content-Type-Options nosniff"
* Добавлены кнопки для скачивания системного лога и журнала из web-интерфейса
* Поправлен ряд ошибок валидации схемы при экспорте в SARIF
* Исправлено поведение при наличии нескольких хуков в конфигурационном файле
* В информацию о маркере для хуков добавлены checker severity и reliability
* Исправлен случайный порядок URL для маркеров при использовании public API для получения URL-ов
* На главную страницу добавлена кнопка "Помощь", которая открывает документацию
* При использовании команд навигации в режиме "Browse code" текущий файл теперь корректно подсвечивается в дереве файлов
* В диалоге групповой разметки убран индикатор изменений в виде кружочка, наличие изменений можно определить по активности кнопок "Apply" и "Reset"
* Кнопка обновления в верхнем меню теперь корректно обновляет информацию на странице Settings/Project
* Различные небольшие исправления в пользовательском интерфейсе

=== Release 6-0-2 ===
16.12.2022

* Исправлена проблема в UI с сохраненными пользовательскими фильтрами

=== Release 6-0-1 ===
13.12.2022

* Добавлено описание ряда детекторов, которые есть в последнем релизе Svace 3.3.2 но были пропущены в Svacer
* Исправлено вылетание в Login Screen при удалении нотификации из панели нотификаций
* Исправлено появление белого экрана при клике на детектор, информация о котором отсутствует
* Ряд различных небольших исправлений в UI
* Промежуточное хранилище будет очищаться по умолчанию при использовании команды import

=== Release 6-0-0 ===
30.11.2022

* Добавлено копирование комментариев при копировании разметки
* Комментарии добавлены к отчету в формате csv
* Добавлена возможность вводить пароль с клавиатуры для консольных команд
* Добавлена возможность импортировать разметку из объекта сборки (из ранее загруженных данных)
* Добавлена возможность импортировать разметку сразу после загрузки на сервер (опция для команды svacer upload)
* Добавлена возможность загружать исходный код не из папки .svace-dir
* Добавлена возможность бэкапа и восстановление объектного хранилища в сервер PostgresSQL
* Добавлена возможность создания отчета по проекту в формате PDF через интерфейс командной строки и посредством REST API
* Добавлена возможность подавления предупреждений через inline комментарии в коде
* Добавлена возможность подавления предупреждений по идентификатору предупреждения через command line и REST API
* Добавлена возможность ассоциировать организацию с пользователем и реестр организаций
* Добавлена фильтрация списка комментариев по пользователю в правой панели веб-интерфейса
* Добавлен поиск пользователей по его атрибутам в панели управления пользователями
* Добавлена возможность заполнения данных профиля LDAP пользователя данными, полученными от LDAP сервера
* Добавлена возможность прикреплять файлы к снимкам при импорте результатов (данные файлы составляют часть экспортируемых данных при экспорте снимков)
* Добавлена возможность ассоциировать пользовательские атрибуты типа "строка" или массив строк со снимком при импорте данных (данные атрибуты составляют часть экспортируемых данных при экспорте снимков)
* Добавлены command line операции по получению прикрепленных файлов и пользовательских атрибутов со снимков
* Добавлена возможность группового добавления комментариев
* Добавлена возможность указания сетевого интерфейса для работы WEB и GRPC серверов
* Добавлен вывод краткой статистики по загруженному снимку при команде upload. Поддерживается текстовой и JSON форматы вывода
* Существенно расширены возможности по интеграции Visual Studio Code с сервером Svacer
* Добавлен флаг --git в команду import. При наличии такого флага, ищется ближайший git репозиторий содержащий .svace-dir и при наличии такого - используется путь к гит репозиторию для замены путей на префикс .build.
* Portable PostgreSQL больше не входит в поставку. Вместо него поставляется docker-compose.yml файл для запуска PostgreSQL в докер-контейнере
* Добавлено больше данных и информации об ошибках в вывод команды svacer import
* Изменение Public API: добавлена точка входа /api/public/login
* Операции по импорту и экспорту снимков доступны теперь обычным пользователям (не администраторам) при использовании command line интерфейса
* Операция по экспорту снимков доступна обычному пользователю из веб-интерфейса (импорт все еще требует роль администратора для веб-интерфейса)
* Операции по экспорту снимков переведены на асинхронный режим. Нотификация о готовности будет показана пользователю и доступна в панели нотификаций
* Обновлено описание детекторов в соответствии с релизом Svace 3.3.2
* Исправлена ошибка обработки корневых сертификатов при подключении к LDAP серверу по протоколу ldaps
* Исправлено ошибочное создание дубликатов локальных учетных записей LDAP пользователей (case sensitive login)
* Различные исправления в пользовательском интерфейсе с целью оптимизации производительности
* Добавлены пропущенные проверки ролей при работе с веб-интерфейсом
* Svacer больше не создает временные файлы в директории с исполняемым файлом
* Устаранены задержки при удалении веток и проектов

LDAP configuration

2025-11-27T11:24:38Z

Chernykov sv: /* Некоторые замечания для пользователей, которые использовали LDAP, начиная с версии Svacer 5-1-0 до 5-2-0 */

==== Общий принцип аутентификации ====
Схема аутентификации с помощью протокола LDAP следующая:

# Сервер запускается с указанием конфигурационного файла с настройками для LDAP аутентификации
# В форме аутентификации пользователь выбирает нужный тип аутентификации (svacer или LDAP)
# При выборе аутентификации LDAP, после заполнения необходимых параметров, запрос на аутентификацию отправляется на сервер Svacer
# Сервер Svacer, используя настройки из конфигурационного файла, обращается к внешнему LDAP серверу и проводит проверку пользователя
# В случае успешной аутентификации, в БД сервера Svacer создается запись (если ее еще нет) для пользователя, чтобы можно было управлять ролями данного пользователя
# Сервер возвращает токен безопасности для дальнейшей работы, аналогичный токену, возвращаемому при аутентификации локальных пользователей

Для каждого пользователя, успешно прошедшего проверку на LDAP сервере, создается локальная запись в БД Svacer. Управлять таким пользователем можно как и обычным пользователем, за исключением:
* Пользователю нельзя сменить пароль
* Пользователь не может сменить пароль самостоятельно
* В случае отсутствия связи между сервером Svacer и сервером LDAP, данный пользователь не сможет зайти в систему

==== Запуск сервера с поддержкой LDAP ====
Сервер может быть запущен как в с поддержкой аутентификации через LDAP, так и без. Для того, чтобы включить аутентификацию через LDAP необходимо указать конфигурационный файл. Типовой пример конфигурационного файла для подключения к контроллеру домена MS ActiveDirectory или серверу openLDAP можно получить с помощью команды:

svacer ldap print

Запуск сервера с поддержкой LDAP осуществляется командой:

svacer-server run --ldap ldap.json

При запуске сервер svacer формирует список доступных для LDAP аутентификации серверов и выводит соответствующее сообщение. В логах сервера должна появится информация о добавлении сервера вида: "LDAP Server added: xxxx".

После запуска сервера svacer с поддержкой LDAP в GUI становится активна вкладка LDAP ([[Help:UI manual#Авторизация в пользовательском интерфейсе сервера Svacer|Авторизация]]).

Для аутентификации с помощью LDAP необходимо выбрать сервер из выпадающего списка.

При нажатии на кнопку '''Details''' появляется более подробная информация о сервере и его доступности (параметр '''Alive'''). Доступность сервера LDAP проверяется в момент запуска сервера Svacer, при аутентификации пользователя, а также (в случае наличия соответствующего параметра в конфигурационном файле) периодически.
В случае конфигурации сервера Svacer с поддержкой LDAP можно отключить возможность аутентификации пользователей встроенными средствами сервера Svacer (вкладка Svacer на странице входа). В этом случае вкладка Svacer на странице входа будет неактивной и пользователи смогут заходить в систему только с помощью LDAP аутентификации. Данное поведение распространяется и на работу с сервером с помощью интерфейса командной строки.

Для отключения возможности аутентификации встроенными средствами сервера Svacer нужно использовать опцию '''disable-svacer-auth'''.

Пример:
svacer-server run --ldap ldap.json --disable-svacer-auth

==== Конфигурационный файл сервера для поддержки LDAP ====
Типовой пример конфигурации:
{
"servers": [
{
"name": "active_directory",
"basedn": "dc=domain,dc=home,dc=org",
"useGroup": true,
"hideURL": true,
"checkAlivePeriod": 60,
"connection": {
"url": "ldaps://192.168.11.71:636",
"mirrors":["ldaps://192.168.11.72:636","ldaps://192.168.11.73:636"]
"connectAs": "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org",
"password": "12345678",
"ignoreCertCheck": false,
"caCertFiles":["/etc/ssl/certs/a*","/etc/ssl/certs/my_certs/*"]
},
"group": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Group)(cn=dep_devops))",
"userMember": "member",
"display":"cn",
"svacerRole":"cn"
},
"user": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Person)(sAMAccountName=*))",
"login": "sAMAccountName",
"group": "dn",
"info": {
"display": "cn",
"email": "email",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
},
{
"name": "open_ldap",
"basedn": "dc=example,dc=com",
"useGroup": true,
"connection": {
"url": "ldap://127.0.0.1:389",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678"
},
"group": {
"basedn": "ou=groups",
"filter": "(&(objectClass=groupOfNames)(cn=svacer))",
"userMember": "member",
"display":"cn"
},
"user": {
"basedn": "ou=users",
"filter": "(&(objectClass=PosixAccount))",
"login": "uid",
"group": "dn",
"info": {
"display": "dn",
"email": "mail",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
}
]
}

В конфигурации можно указать несколько серверов. Все сервера в совокупности рассматриваются как единый источник проверки пользователей. То есть если на двух серверах будут два пользователя с одинаковым логином, они будут считаться идентичными. Ниже приводится описание параметров конфигурации.
* name — произвольное имя (уникальное для каждого сервера)
* trace — флаг, позволяющий получить детальную информацию по этапам обработки запроса на вход пользователя LDAP в Svacer
* basedn — DN относительно которого будут проводится все операции в LDAP каталоге
* useGroup — проверять ли принадлежность пользователя к группе
* hideURL — не передавать сетевой адрес LDAP сервера. Конечные пользователи будут видеть в выпадающем списке только имя сервера, указанное в поле name. В поле URL будет пустая строка
* checkAlivePeriod — Промежуток времени в секундах, который должен проходить между периодическими проверками доступности сервера LDAP. Если параметр равен 0 или не указан, такая проверка не проводится.
* connection — подсекция, описывающая параметры соединения с сервером
:* url — адрес сервера, формата: ldap[s]://domain:port В случае использования TLS для подключения к LDAP серверу, необходимо указать правильный порт (по умолчанию 636)
:* mirrors — список хостов, которые будут использованы в случае недоступности основного хоста, указанного в поле URL. Формат указания хостов тот же, что и в поле URL. Префикс ldap[s] должен быть одинаковым для всех хостов и совпадать с префиксом в поле URL
:* connectAs — имя пользователя в формате DN, от которого будут производится операции в LDAP каталоге
:* password — пароль пользователя
:* ignoreCertCheck — не проверять сертификат в случае ldaps:// соединения. Полезно при самоподписанных сертификатах. Если флаг установлен в значение false, необходимо установить значение поля caCertFiles
:* CaCertFiles — массив значений, описывающих какие файлы корневых сертификатов добавлять в конфигурацию Svacer. Формат файлов сертификатов — PEM
* group — подсекция, описывает параметры проверки принадлежности пользователя к группе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске группы. Необходимо, если надо указать несколько групп
:* userMember — атрибут, содержащий пользователей группы
:* display — атрибут, содержащий имя группы для отображения
:* svacerRole — атрибут, из которого будет извлечено имя роли, созданной в Svacer, и автоматически сопоставляемой с пользователем
* user — подсекция, описывает параметры получения информации о пользователе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске пользователей
:* login — атрибут, в котором находится login пользователя
:* group — атрибут, на который ссылается атрибут group.userMember (обычно это «dn» пользователя)
:* defaultRole — роль Svacer, автоматически добавляемая всем пользователям LDAP, успешно вошедшим в Svacer
:* info — подсекция описывающая в каких атрибутах находится информация о пользователе
::* display — атрибут, содержащий полное имя пользователя для отображения (ФИО)
::* email — атрибут с почтовым адресом
::* firstName — атрибут с именем
::* lastName — атрибут с фамилией
* enabled — использовать или нет данный сервер

Конфигурацию для подключения к серверам '''LDAP''' можно также задать в конфигурационном файле '''Svacer'''. Например:

auth:
ldap:
servers:
- name: freeIPA
basedn: dc=example,dc=com
useGroup: false
type: freeIPA
hideURL: true
checkAlivePeriod: 1
connection:
url: ldap://svacer.local:7001
connectAs: cn=admin,dc=example,dc=com
password: 12345678
user:
basedn: ou=users
filter: "(&(objectClass=inetOrgPerson)(memberOf=*))"
login: cn
info:
display: cn
email: mail
firstName: givenName
lastName: sn
enabled: true
- name: example1
basedn: dc=example,dc=com
useGroup: false
hideURL: true
checkAlivePeriod: 1
connection:
url: ldap://svacer.local:7001
connectAs: cn=admin,dc=example,dc=com
password: 12345678
user:
basedn: <nowiki>''</nowiki>
filter: "(&(objectClass=inetOrgPerson)(memberOf=*))"
login: cn
group: dn
info:
display: cn
email: mail
firstName: givenName
lastName: sn
enabled: true

[[LDAP configuration|Подробное описание взаимодействия SVACER с LDAP сервером]]

Рассмотрим пример обработки запроса на вход в систему LDAP пользователя, указавшего значение ivanov_ii в поле логина и выбравшего конфигурацию active_directory из примера выше
:# Svacer создает служебное подключение к хосту 192.168.11.71 со следующими параметрами
:#* используется TLS соединение (ldaps префикс)
:#* порт 636
:#* проверяется сертификат LDAP сервера (ignoreCertCheck = false); для проверки используются сертификаты CA (из папки /etc/ssl/certs — все сертификаты, начинающиеся с буквы a; из папки /etc/ssl/certs/my_certs/ — все сертификаты)
:#* логин для подключения к LDAP серверу: "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org" (connectAs); пароль: 12345678 (password)
:# Если подключение к хосту невозможно (хост недоступен), то пробуются хосты 192.168.11.72,192.168.11.73 с параметрами, аналогичными параметрам пункта 1
:# Если подключение невозможно, процесс входа завершается с ошибкой
:# Производится поиск пользователя в LDAP каталоге со следующими параметрами:
:#* строка запроса: (&(sAMAccountName=ivanov_ii)((&(objectCategory=Person)(sAMAccountName=*)))), sAMAccountName — взят из поля user.login конфиг файла; ivanov_ii — введено пользователем; (&(objectCategory=Person)(sAMAccountName=*)) — взято из поля user.filter конфиг файла
:#*начальный узел, с которого будет произведен поиск: cn=users,dc=domain,dc=home,dc=org
:#*поиск производится по всему поддереву
:# Если пользователей не найдено или найдено больше 1 пользователя, процесс входа завершается с ошибкой
:# Флаг useGroup = true, поэтому производится дополнительная проверка группы пользователя
:#* выполняется поиск групп в каталоге LDAP со следующими параметрами:
:#**строка запроса: (&(objectCategory=Group)(cn=dep_devops)) — взято из поля group.filter
:#**начальный узел: cn=users,dc=domain,dc=home,dc=org, где cn=users — взято из поля group.basedn; значение dc=domain,dc=home,dc=org — взято из поля basedn конфиг файла
:#**поиск производится по всему поддереву
:#**определяется список пользователей группы, каждому пользователю соответствует значение атрибута с именем member (взято из поля group.userMember конфиг файла)
:#* Если ни одной группы не найдено, то процесс входа завершается с ошибкой
:#*Определяются группы, в которые входит пользователь. Для этого для каждой группы, найденной в пункте выше, просматривается список пользователей и ищется значение cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org (в поле user.group конфиг файла указано значение dn, что означает, что необходимо использовать DN пользователя для данной процедуры). Если атрибут найден, считается что пользователь принадлежит группе.
:#* Если пользователь не принадлежит ни к одной группе, процесс входа завершается с ошибкой
:# Производится попытка подключения к хосту LDAP с параметрами, аналогичными параметрам из пункта 1, за исключением логина (cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org) и пароля пользователя (введен в поле пароль формы входа)
:# Если подключение не удалось создать, то процесс входа завершается с ошибкой
:# Процесс аутентификации пользователя произведен успешно
:# Производится создание локального пользователя svacer с именем ivanov_ii, если его еще нет {{Note|type=warn|text=С версии 11 наличие двух пользователей с одинаковым логином: локального и пользователя LDAP — не допускается}}
:# Так как useGroup = true и указан атрибут svacerRole с непустым значением, то производится привязка ролей Savcer пользователя на основе его участия в группах LDAP (смотри соответствующий пункт)

==== Привязка группы LDAP к роли Svacer ====
Возможно автоматическое назначение пользователям LDAP ролей Svacer. Для использования данной функции необходимо выполнить следующие предварительные действия:
:* Администратор LDAP сервера создает в каталоге LDAP нужные группы (например cn=users,ou=svacer,dc=example,dc=com и cn=admins,ou=svacer,dc=example,dc=com), которые будут привязаны к ролям Svacer
:* Администратор LDAP сервера помещает пользователей LDAP в соответствующие LDAP группы (cn=users,ou=svacer,dc=example,dc=com или cn=admins,ou=svacer,dc=example,dc=com)
:* Администратор Svacer создает роли в Svacer, имеющие в точности такое же название, как значение атрибута, указанного в поле svacerRole конфигурационного файла. В пример можно использовать аттрибут cn и в этом случае необходимо создать роли users и admins
:* Администратор Svacer добавляет в конфигурационный файл в поле svacerRole имя атрибута, по которому будет производится привязка. Для примера выше — строчку svacerRole="cn"
После выполнения данных действий, во время входа пользователя в систему пользователю будут добавлены роли по следующему алгоритму:
:* Производится поиск групп, к которым принадлежит пользователь. Поиск производится по параметрам, указанным в секции group конфигурационного файла {{Note|text=На первом этапе будет произведен поиск всех групп, которые подпадают под условие фильтра в секции group. По этой причине необходимо указывать наиболее точное значение для фильтра группы, чтобы не было чрезмерно большого количества записей в результатах поиска (для MSAD — 2000 записей)}} Для примера, пользователь может состоять в следующих группах: (cn=users,ou=svacer,dc=example,dc=com), (cn=dep_dev,dc=example,dc=com)
:* Для каждой найденной группы, выбирается значение атрибута, указанного в поле svacerRole. В примере — имя атрибута cn. Получаются два имени: users, dep_dev (это те группы, которые могут быть привязаны к ролям Svacer)
:* Производится поиск ролей Svacer с именем users и dep_dev. Если такие роли найдены, то пользователю они будут добавлены. Так как в примере роль dep_dev не создана, то будет добавлена только роль users.

Удаление ролей автоматически не производится. Вместо этого предлагается ручной режим синхронизации ролей пользователя. Для синхронизации ролей с текущими группами, в которых состоит пользователь, используется команда cli

svacer ldap sync_roles --login [user_login] --server [server_name] --apply

Данная команда проверит наличие пользователя user_login в соответствующей роли группе LDAP и если его в группе не будет, уберет роль у пользователя. Также команда добавит недостающие роли, на основе механизма, описанного выше (при входе пользователя). Флаг apply позволяет "оценить" получаемые изменения прежде чем они будут применены. По умолчанию флаг apply = false.

Автоматическое назначение пользователю LDAP некоторой роли также возможно осуществить, указав необходимую роль в параметре '''user.defaultRole''' конфигурационного файла LDAP. Данная роль будет назначена в том случае, если она существует на момент входа пользователя в систему. Добавление роли будет происходить при каждом входе пользователя в систему. Поэтому даже если у пользователя эту роль удалить явно, она все равно будет добавлена пользователю при следующем входе. Данный механизм назначения роли работает независимо от настройки привязки роли к группе LDAP.

==== Использование CLI сервера Svacer с поддержкой LDAP ====
Для выполнения некоторых действий в cli с помощью команды svacer требуется аутентификация пользователя. Для аутентификации с помощью ldap сервера необходимо указать в команде кроме имени пользователя и пароля имя сервера с помощью флага ldap_server (имя сервера регистр-зависимо). Например:

svacer quickdiff --user loginok --password loginok --ldap_server openLDAP2 --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Если флаг ldap_server не указан, аутентификация производится механизмами сервера svacer, как и в предыдущих версиях. Параметр ldap_server можно опустить, указав сервер в переменной окружения SVACER_LDAP_SERVER. Например:

SVACER_LDAP_SERVER="openLDAP2" svacer quickdiff --user loginok --password loginok --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Для получения списка поддерживаемых свейсером LDAP серверов используйте команду:

svacer ldap servers --host 127.0.0.1 --port 8080

Вывод содержит два столбца (имя и URL сервера). В качестве значения для параметра ldap_server необходимо использовать содержимое первого столбца.

==== Обновление данных LDAP пользователей ====
Для каждого LDAP пользователя создается соответствующая ему запись в БД Svacer, в которую включается ФИО из LDAP и адрес его электронной почты. Через какое-то время данные пользователей могут меняться, в этом случае возможно обновить данные LDAP пользователей, хранящиеся в Svacer, синхронизировав их с данными LDAP сервера.
Для обновления данных одного пользователя можно воспользоваться окном редактирования пользователя, в котором можно нажать кнопку '''Load from LDAP'''. В соответствующие окна будут добавлены данные, загруженные из LDAP сервера (см. раздел [[Help:UI manual#Управление пользователями|Управление пользователями]]).

Также данные пользователей можно обновить с помощью интерфейса командной строки. Для этого можно использовать подкоманду '''updateUsers''' команды '''ldap'''. Общий синтаксис команды выглядит следующим образом:

svacer ldap updateUsers --onlyEmpty

Флаг '''onlyEmpty''' позволяет обновлять только пустые поля ФИО и eMail. Заполненные поля не будут изменены. Команда обновит данные всех пользователей, записи о которых имеются в базе Svacer.

==== Пример конфигурации сервера Svacer для поддержки аутентификации по LDAP протоколу ====

Для упрощения настройки интеграции с LDAP сервером, процесс настройки можно разбить на этапы и переходить к следующему только если успешно завершен предыдущий этап. В первую очередь необходимо выяснить актуальные параметры подключения к ldap серверу:
* URL; Например ldap://10.11.12.13:389 или ldaps://10.11.12.13:636
* Учетные данные с которыми будет осуществляться подключение к LDAP серверу при каждой попытке входа пользователем; Например, login: cn=admin,dc=example,dc=com, пароль: 12345678
* Определиться с корнем LDAP дерева (базовый узел), относительно которого будут выполняться все операции; Например: dc=example,dc=com
* Проверить, что с указанными учетными данными возможно подключение к серверу LDAP и просмотр его содержимого с некоторого узла, расположенного ниже базового; Например, с узла ou=users,dc=example,dc=com для рассматриваемого примера. Проверить можно, например, используя следующую команду:
:<pre>LDAPTLS_REQCERT=never ldapsearch -v -x -D cn=admin,dc=example,dc=com -w 12345678 -b ou=users,dc=example,dc=com -H ldaps://127.0.0.1:636</pre>
:для случая поддержки TLS, или
:<pre>ldapsearch -v -x -D cn=admin,dc=example,dc=com -w 12345678 -b ou=users,dc=example,dc=com -H ldap://127.0.0.1:389</pre>
:для случая без поддержки TLS
* Определиться с атрибутом записи, по которой будет осуществляться вход. Например cn, mail или sAMAccountName
* Если используется Active Directory, целесообразно в качестве фильтра для поиска записей о пользователе указать значение (&(objectCategory=Person)(sAMAccountName=*))

===== Основные настройки LDAP =====
* Использовать следующий шаблон конфигурации, заменив текст, выделенный жирным, актуальными данными
{
"servers": [
{
"name": "test_ldap",
"basedn": '''"dc=example,dc=com"''',
"connection": {
"url": '''"ldap://ldap1.example.com:389"''',
"connectAs": '''"cn=admin,dc=example,dc=com"''',
"password": '''"12345678"'''
},
"user": {
"basedn": '''"ou=users"''',
"filter": '''"(&(objectClass=PosixAccount)(cn=*))"''',
"login": '''"cn"''',
"info": {
"display": "cn",
"email": "mail",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
}
]
}

* Поиск пользователя в каталоге LDAP будет производится от узла, DN которого является конкатенацией значений user.basedn и basedn. В примере это будет узел ou=users,dc=example,dc=com. Полный DN пользователя указывать в user.basedn не нужно (можно указать пустой или не указывать вообще)
* Убедиться, что при старте сервера в логах присутствуют строки:
2023-04-24T12:35:44.650+0300 info Loading ldap configuration from file: ldap2.json
2023-04-24T12:35:44.650+0300 info LDAP server added: test_ldap
* Выполнить команду, заменив хост и порт актуальными значениями
svacer ldap servers --host 127.0.0.1 --port 8080
* Убедиться, что в выводе команды присутствуют записи вида:
Available LDAP servers list:
Name: test_ldap Url: ldap://ldap1.example.com:389
* Убедиться, что возможен вход тестовым пользователем через cli:
curl -X POST --data '{"login":"test_login","password":"test_password","auth_type":"ldap","server":"test_ldap"}' 127.0.0.1:8080/api/public/login
Вывод должен быть вида:
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODI5MzYxODcsImlhdCI6MTY4MjMzMTM4Nywicm9sZXMiOlsiYWRtaW5zIl0sInVzZXIiO ..."}

===== Добавление проверки по группе LDAP =====
Принадлежность пользователя к группе определяется следующим образом:
* Формируется список всех возможных групп на основе значения group.filter
* Для каждой сформированной группы формируется список входящих в нее пользователей по следующему принципу:
** Каждое значение атрибута group.userMember (их может быть несколько) узла LDAP (соответствующего группе) однозначно идентифицирует некоторого пользователя
** Пользователь входит в группу, если значение атрибута user.group пользователя входит в множество записей, полученных в пункте выше

Для настройки проверки по группе целесообразно выполнить следующие действия:
* Определиться с узлом в LDAP, относительно которого будет производится поиск групп (поле group.basedn). Поиск групп в каталоге LDAP будет производится от узла, DN которого является конкатенацией значений group.basedn и basedn. В примере это будет узел ou=svacer_groups,ou=groups,dc=example,dc=com
* Для Active Directory в поле filter можно указать, например, (&(objectCategory=Group)(cn=dep_ivanov)), что будет означать группу dep_ivanov.
* Изменить конфигурационный файл следующим образом:
{
"name": "test_ldap",
...
},
"user": {
...
'''"group": "dn"''',
},
'''"useGroup": true,'''
'''"group": {''''
'''"basedn": "ou=svacer_groups,ou=groups",'''
'''"filter": "(&(objectClass=groupOfNames)(cn=*))",'''
'''"userMember": "member",'''
'''"display":"cn",'''
},
"enabled": true
}

* Перезапустить Svacer
* Убедиться, что возможен вход пользователей, состоящих в группе/группах, и не возможен вход пользователей, не состоящих в группе/группах.
===== Добавление привязки ролей Svacer к группам LDAP =====
* Добавить нужные группы в Svacer. Например admins и users.
* Определиться в каком атрибуте LDAP группы будет хранится имя роли (все сравнения будут чувствительны к регистру). Например, пусть это будет атрибут cn
* Изменить конфигурационный файл следующим образом
{
"name": "test_ldap",
...
"user": {
...
},
''' "useGroup": true, '''
''' "group": { '''
''' "basedn": "ou=svacer_groups,ou=groups", '''
''' "filter": "(&(objectClass=groupOfNames)(cn=*))", '''
''' "userMember": "member", '''
''' "display": "cn", '''
''' "svacerRole": "cn" '''
''' }, '''
"enabled": true
}

* Убедиться, что пользователю назначаются роли, выполнив команду в cli (требуются учетные данные администратора для проверки; по умолчанию admin / admin). Для проверки привязки ролей Svacer к пользователю loginok можно использовать следующую команду:
svacer ldap sync_roles --login loginok --host 127.0.0.1 --port 8080 --user admin --password admin --server test_ldap
Вывод должен быть следующий:
SvacerUserID: 457039b4-4aef-4857-831d-1c080ea154d4
SvacerUserLogin: loginok
LDAPUserDN: cn=loginok,ou=users,dc=example,dc=com
Roles: [314e7571-706c-4463-9280-6a4eee03b42d]
Links: [cn=admins,ou=svacer_groups,ou=groups,dc=example,dc=com -> admins (314e7571-706c-4463-9280-6a4eee03b42d)]
Applied: false

===== Добавление серверов LDAP, работающих по TLS =====
* Изменить конфигурационный файл следующим образом:
{
"name": "test_ldap",
"basedn": "dc=example,dc=com",
"connection": {
"url": "'''ldaps'''://ldap1.example.com:'''636'''",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678",
"ignoreCertCheck": '''true'''
},
"user": {
...
},
...
"enabled": true
}

* Убедиться, что возможен вход пользователем LDAP. Для проверки можно использовать утилиту curl, как указано в примере с основными настройками
* Для проверки сертификата LDAP сервера добавить сертификат CA (например, ldap.crt) в папку с сертификатами (например, /etc/ssl/certs/) и внести следующие изменения в конфигурационный файл:
{
"name": "test_ldap",
"basedn": "dc=example,dc=com",
"connection": {
"url": "ldaps://ldap1.example.com:636",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678",
"ignoreCertCheck": '''false''',
'''"caCertFiles": ["/etc/ssl/certs/ldap.crt"]'''
},
"user": {
...
},
...
},
"enabled": true
}

* Убедиться, что в логах сервера присутствуют записи вида:
2023-04-24T13:49:49.298+0300 info added 1 ca certs from ldap.crt
* Убедиться, что пользователь LDAP может зайти в систему

===== Добавление резервных серверов LDAP =====
* Добавить в конфигурационный файл резервные сервера в поле mirrors:
{
"name": "test_ldap",
"basedn": "dc=example,dc=com",
"connection": {
"url": "ldaps://ldap1.example.com:636",
'''"mirrors": ["ldaps://ldap2.example.com:636","ldaps://ldap3.example.com:636"],'''
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678",
...
},
"user": {
...
},
...
"enabled": true
}

* Проверить, что вход пользователя LDAP в систему возможен
* Изменить значение в URL на любое (чтобы сервер, указанный в URL, был не доступен)
* Перезапустить Svacer
* Убедиться, что вход пользователя LDAP в систему возможен
* Поменять значение в URL на верное

==== Возможные ошибки конфигурации ====
В случае ошибки входа пользователя в систему сервер выводит текстовые сообщения, указывающие на причину ошибки. Наиболее полную информацию об ошибке можно видеть, использовав флаг <code>--debug</code> при запуске сервера Svacer. Логи сервера можно посмотреть в GUI Svacer из под пользователя с правами администратора в разделе '''Settings > Server information'''. Ниже приводится таблица с перечислением возможных ошибок входа пользователя LDAP в систему.

'''Сообщения об ошибках и их возможные причины'''
{| class="wikitable" style="margin:auto"
|-
!Действие !! Сообщение !! Причина !! Решение
|-
| Вход в систему || LDAP server unavailable || 1. Нет соединения с сервером<br/>2. Неверные учетные данные для соединения с сервером || Проверить доступность сервера LDAP с хоста, на котором установлен Svacer. См. утилиту ldapsearch
|-
| Вход в систему || LDAP user is not in group||Пользователь не состоит в заданной конфигурацией группе/группах||Проверить поля user.group, group.filter, group.userMember. В списке групп, полученных с использованием group.filter должна быть хотя бы одна группа, в которую входит пользователь
|-
| Вход в систему || LDAP group not found. Check configuration || Во время поиска групп, подходящих под фильтр, не найдено ни одной группы || Проверить значение поля group.filter и значения basedn, group.basedn
|-
| Вход в систему || LDAP user not allowed or not found || Во время поиска пользователей, подходящих под фильтр, не найдено ни одного пользователя || Проверить значение поля user.filter и значения basedn, user.basedn
|-
| Вход в систему || too much record for user ('%s') found || Поиск пользователя в LDAP с указанными в конфигурации парамтерами дал несколько записей|| Проверить значение поля user.filter и значения basedn, user.basedn. Поиск всегда должен давать одну запись
|-
| Запуск сервера || caCert source [%v] ignored || Ошибка поиска сертификатов по указанному шаблону || Проверить поле connection.caCertFiles конфигурации и убедится, что по указанному в поле шаблону присутствуют сертификаты и к ним есть доступ (проверить права). Все пути должны быть абсолютными
|-
|Запуск сервера || Server [%v] configuration has ignoreCertCheck=false, but no CA certs added. In this case LDAP auth may be impossible || Ошибка конфигурации TLS. В результате обработки значений из поля connection.CaCertFiles не было добавлено ни одного сертификата. Это приводит к тому, что Svacer не может проверить сертификат LDAP сервера, а флаг ignoreCertCheck указан в значении false, что приведет к заведомо ошибочной проверке пользователя || Проверить поле connection.caCertFiles конфигурации и убедится, что по указанному в поле шаблону присутствуют сертификаты и к ним есть доступ (проверить права). Все пути должны быть абсолютными
|}
Для определения проблем с входом пользователей LDAP в систему при первоначальной настройке интеграции, полезно установить флаг trace в значение true. Результатом станет вывод в лог сервера Debug сообщения с указанием этапа обработки запроса и его параметров.

==== Некоторые замечания для пользователей, которые использовали LDAP в версиях Svacer 5-1-X ====

Если использовался функционал по интеграции Svacer с LDAP серверами в версиях 5-1-X (с 30.03.2022 по 15.07.2022), желательно выполнить модификацию базы данных, так как в ней могут быть ошибки, влияющие на

* механизм тегирования пользователей в комментариях
* механизм уведомления

Если наблюдаются сбои в работе указанных механизмов, то следует выполнить следующйи sql запрос в БД, с которой работает Svacer:

<pre class="">insert into users_status (user_id,status)
select id,1 from users
left join users_status us on us.user_id=users.id
where status is null;</pre>

Help:Installation

2025-11-27T11:22:11Z

Chernykov sv: /* Upgrade notes */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

Если вы использовали аутентификацию с помощью LDAP в версиях Svacer 5-1-X и у вас не работает механизм тегирования или уведомлений (подписки), см [[LDAP configuration#Некоторые замечания для пользователей, которые использовали LDAP, начиная с версии Svacer 5-1-0 до 5-2-0|Решение проблем с отстутствием статуса пользователя в БД]]

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны четыре способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки [[LDAP]], [[Help:CLI#Personal Access Token|PAT]] или [[OIDC]] аутентификации см. соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции '''auth.svacer''' конфигурационного файла Svacer. Ниже приведен пример настроек:
<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>
Параметр '''min_length''' задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр '''complexity''' содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке — полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля).

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку — Svacer или LDAP — использовать по умолчанию. Для этого используется параметр '''auth.svacer.default'''. Если данный параметр установлен в значение '''true''', то вкладкой по умолчанию будет вкладка Svacer, иначе — вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помощью параметра '''auth.svacer.enabled'''.

Ниже приведен пример конфигурационного файла Svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том случае, если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:

<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>

Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: 1s,1m,60m и т. д.

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):

<pre class="">svacer user-provider unlock --user admin --password admin --login locked_user</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационном файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настраивается в конфигурационном файле в секции '''webhook'''. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см. [[Help:Installation#Модель поддерживаемых событий|Модель поддерживаемых событий]]) и отправляется на обработку в каждую из настроенных целей, которыми являются http-обработчики. Отправкой занимаются работники (их количество настраивается в конфигурационном файле в параметре '''workers_count'''). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог-файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр '''ca_certs''' конфигурационного файла. Работникам можно указать таймаут соединения с webhook-сервером (в мс, по умолчанию 1000мс, параметр '''timeout''') и количество попыток отправки (по умолчанию — одна попытка, параметр '''retry_count''').

В настройках можно указать фильтр на отправляемые события (параметр '''filter'''). Фильтр указывается посредством задания выражения. В выражениях используется [https://github.com/expr-lang/expr синтаксис go-expr]. Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр '''journal_length'''). По умолчанию он равен 86400 записей — по 1 записи на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.

Для настройки аутентификации работника можно использовать параметр '''headers''', который представляет собой список значений вида '''key:value'''. Данные пары будут добавлены в заголовки каждого http-запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "<nowiki>https://test-host.local:8080/webhook</nowiki>"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

svacer server webhook journal
svacer server webhook stat

Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (особенно интересными могут быть поля '''sendError''' и '''skip''').

Пример вывода для первой команды (с флагом '''--humanize'''; если флага нет, то вывод будет в формате json):

==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: <nowiki>https://swarm-mgr.home:8080/webhook</nowiki>
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: <nowiki>https://swarm-mgr.home:8080/webhook</nowiki>
ProcessTime: 3 ms

Пример вывода команды статистики:

{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "<nowiki>https://swarm-mgr.home:8080/webhook</nowiki>",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]
}

==== Модель поддерживаемых событий ====
syntax = "proto3";
import "google/protobuf/any.proto";
option go_package="svacer/proto/webhook";
package webhook;

enum EventType {
EventNone = 0;
EventTest = 1;
EventReviewMarker = 2;
EventPurgeReview = 3;
EventGroupReview = 4;
EventImportSnapshot = 5;
EventCopySnapshot = 6;
EventNewComment = 7;
EventUpdateComment = 8;
EventNewContainer = 9;
EventDeleteContainer = 10;
EventUpdateContainer =11;
EventImportMarkup = 12;
EventDeleteSnapshot = 13;
UpdateSnapshot = 14;
}

message MarkerDetails {
string id = 1;
string file = 2;
string line = 3;
string lang = 4;
}

message Event {
uint64 timestamp = 1;
EventType type = 2;
string created_by = 3;
google.protobuf.Any payload = 4;
}

message PayloadMarkerReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
repeated MarkerDetails markers = 7;
string comment = 8;
string severity = 9;
string action = 10;
string status = 11;
bool group_review = 12;
string created_by_id = 13;
string created_by_login = 14;
}

message PayloadPurgeReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string created_by_id = 5;
string created_by_login = 6;
}

message PayloadImportSnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
}

message PayloadMarkerComment {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
MarkerDetails marker = 7;
string comment = 8;
string created_by_id = 9;
string created_by_login = 10;
}

message PayloadCopySnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
string created_by_id = 7;
string created_by_login = 8;
}

message Container {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
Container source = 5;
}

message PayloadNewContainer {
repeated Container containers = 1;
}

message PayloadDeleteContainer {
repeated Container projects = 1;
repeated Container branches = 2;
}

message PayloadUpdateContainer {
Container container = 1;
}

message CopyResult {
uint64 total = 1;
uint64 applied_reviews = 2;
uint64 applied_comments = 3;
uint64 skipped_reviews = 4;
uint64 duplicate_reviews = 5;
uint64 duplicate_comments = 6;
}

message PayloadImportMarkup {
Container source=1;
Container target=2;
CopyResult copy_result =3;
}

message Snapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}

message PayloadDeleteSnapshots {
repeated Snapshot snapshots = 1;
}

message PayloadUpdateSnapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

При импорте результатов на сервер индексация идет в фоновой задачи. Появление новых данных в результатах поиска может занять некоторое время.

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

== Расширенные параметры настройки сервера ==

=== Переменные окружения ===
Пользователь может использовать следующие переменные окружения для изменения внутренних параметров сервера:
{| class="wikitable"
|+
!Переменная
!Значение по умолчанию
!Описание
|-
|<code>SVACER_TIMEOUT_IMPORT_RESULTS</code>
|15 минут
|Таймаут ожидания процесса начала импорта на сервере. При превышении, запрос на импорт будет отклонен с ошибкой. Формат Go Duration string: 1h2m3s. Переменная затрагивает только ожидание начала, но не ограничивает сам процесс импорта.
|-
|<code>SVACER_NUM_PARALLEL_IMPORTS</code>
|(<code>максимальное число коннектов к БД) / 2</code>
|Число одновременных параллельных импортов. Остальные ждут в очереди. На ожидание влияет переменная <code>SVACER_TIMEOUT_IMPORT_RESULTS</code>
|-
|<code>SVACER_TAIL_LOG_SIZE</code>
|1Мб
|Число. Размер буффера для показа лога сервера в WEB. Показывается последние SVACER_TAIL_LOG_SIZE байт из лога.
|-
|<code>SVACER_LOG_FORMAT</code>
|<пусто>
|При указании формата json вывод формат лога заменяется на JSON. Предназначено для интеграции с агрегаторами логов. Так же можно указать через флаг при старте
<code>svacer-server --log-format=json</code>
|-
|<code>SVACER_INV_GEN_JOBS</code>
|0.7 * runtime.GOMAXPROCS
|Максимальное число параллельных job-ов для генерации инвариантов при миграции старой базы или импорте результатов.
При ограниченных ресурсах сервера устанавливать в значение 1 или 2. Пользователь не может увеличить больше, чем GOMAXPROCS
|-
|
|
|
|}

=== Пересчет инвариантов ===
При миграции со старых версий иногда могут быть проблемы с переносом разметки. Для принудительного пересчета инвариантов пользователь может запустить сервер с опцией <code>--force-invariant-refresh</code>.

=== Объектное хранилище ===
При больших размерах объектного хранилища (object store) пользователь может запустить сервер с параметром <code>--compact-object-store</code> - это приведет к поиску недостижимых объектов в объектном хранилище и сокращении размера базы. Операция может занять продолжительное время.

'''ЭКСПЕРИМЕНТАЛЬНО''': Для быстрого получения копии текущего объектного хранилища пользователь может использовать CLI команду
svacer server backup --host <nowiki>http://localhost:8080</nowiki> --user admin --password <admin pwd> --checkpoint <path>
Данная команда создаст по пути ''<path>'' на '''хосте, где работает сервер''', копию object store. При создании копии по возможности используются hard link-и, для ускорения процесса. Процесс работает в background-е и можно запускать для работающего сервера.

Help:Installation

2025-11-27T10:43:15Z

Chernykov sv: /* 12-x-x */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

Если вы использовали аутентификацию с помощью LDAP в версиях Svacer с 5-1-0 по 5-2-0 и у вас не работает механизм тегирования или уведомлений (подписки), см [[LDAP configuration#Некоторые замечания для пользователей, которые использовали LDAP, начиная с версии Svacer 5-1-0 до 5-2-0|Решение проблем с отстутствием статуса пользователя в БД]]

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны четыре способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки [[LDAP]], [[Help:CLI#Personal Access Token|PAT]] или [[OIDC]] аутентификации см. соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции '''auth.svacer''' конфигурационного файла Svacer. Ниже приведен пример настроек:
<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>
Параметр '''min_length''' задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр '''complexity''' содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке — полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля).

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку — Svacer или LDAP — использовать по умолчанию. Для этого используется параметр '''auth.svacer.default'''. Если данный параметр установлен в значение '''true''', то вкладкой по умолчанию будет вкладка Svacer, иначе — вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помощью параметра '''auth.svacer.enabled'''.

Ниже приведен пример конфигурационного файла Svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том случае, если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:

<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>

Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: 1s,1m,60m и т. д.

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):

<pre class="">svacer user-provider unlock --user admin --password admin --login locked_user</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационном файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настраивается в конфигурационном файле в секции '''webhook'''. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см. [[Help:Installation#Модель поддерживаемых событий|Модель поддерживаемых событий]]) и отправляется на обработку в каждую из настроенных целей, которыми являются http-обработчики. Отправкой занимаются работники (их количество настраивается в конфигурационном файле в параметре '''workers_count'''). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог-файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр '''ca_certs''' конфигурационного файла. Работникам можно указать таймаут соединения с webhook-сервером (в мс, по умолчанию 1000мс, параметр '''timeout''') и количество попыток отправки (по умолчанию — одна попытка, параметр '''retry_count''').

В настройках можно указать фильтр на отправляемые события (параметр '''filter'''). Фильтр указывается посредством задания выражения. В выражениях используется [https://github.com/expr-lang/expr синтаксис go-expr]. Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр '''journal_length'''). По умолчанию он равен 86400 записей — по 1 записи на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.

Для настройки аутентификации работника можно использовать параметр '''headers''', который представляет собой список значений вида '''key:value'''. Данные пары будут добавлены в заголовки каждого http-запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "<nowiki>https://test-host.local:8080/webhook</nowiki>"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

svacer server webhook journal
svacer server webhook stat

Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (особенно интересными могут быть поля '''sendError''' и '''skip''').

Пример вывода для первой команды (с флагом '''--humanize'''; если флага нет, то вывод будет в формате json):

==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: <nowiki>https://swarm-mgr.home:8080/webhook</nowiki>
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: <nowiki>https://swarm-mgr.home:8080/webhook</nowiki>
ProcessTime: 3 ms

Пример вывода команды статистики:

{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "<nowiki>https://swarm-mgr.home:8080/webhook</nowiki>",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]
}

==== Модель поддерживаемых событий ====
syntax = "proto3";
import "google/protobuf/any.proto";
option go_package="svacer/proto/webhook";
package webhook;

enum EventType {
EventNone = 0;
EventTest = 1;
EventReviewMarker = 2;
EventPurgeReview = 3;
EventGroupReview = 4;
EventImportSnapshot = 5;
EventCopySnapshot = 6;
EventNewComment = 7;
EventUpdateComment = 8;
EventNewContainer = 9;
EventDeleteContainer = 10;
EventUpdateContainer =11;
EventImportMarkup = 12;
EventDeleteSnapshot = 13;
UpdateSnapshot = 14;
}

message MarkerDetails {
string id = 1;
string file = 2;
string line = 3;
string lang = 4;
}

message Event {
uint64 timestamp = 1;
EventType type = 2;
string created_by = 3;
google.protobuf.Any payload = 4;
}

message PayloadMarkerReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
repeated MarkerDetails markers = 7;
string comment = 8;
string severity = 9;
string action = 10;
string status = 11;
bool group_review = 12;
string created_by_id = 13;
string created_by_login = 14;
}

message PayloadPurgeReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string created_by_id = 5;
string created_by_login = 6;
}

message PayloadImportSnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
}

message PayloadMarkerComment {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
MarkerDetails marker = 7;
string comment = 8;
string created_by_id = 9;
string created_by_login = 10;
}

message PayloadCopySnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
string created_by_id = 7;
string created_by_login = 8;
}

message Container {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
Container source = 5;
}

message PayloadNewContainer {
repeated Container containers = 1;
}

message PayloadDeleteContainer {
repeated Container projects = 1;
repeated Container branches = 2;
}

message PayloadUpdateContainer {
Container container = 1;
}

message CopyResult {
uint64 total = 1;
uint64 applied_reviews = 2;
uint64 applied_comments = 3;
uint64 skipped_reviews = 4;
uint64 duplicate_reviews = 5;
uint64 duplicate_comments = 6;
}

message PayloadImportMarkup {
Container source=1;
Container target=2;
CopyResult copy_result =3;
}

message Snapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}

message PayloadDeleteSnapshots {
repeated Snapshot snapshots = 1;
}

message PayloadUpdateSnapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

При импорте результатов на сервер индексация идет в фоновой задачи. Появление новых данных в результатах поиска может занять некоторое время.

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

== Расширенные параметры настройки сервера ==

=== Переменные окружения ===
Пользователь может использовать следующие переменные окружения для изменения внутренних параметров сервера:
{| class="wikitable"
|+
!Переменная
!Значение по умолчанию
!Описание
|-
|<code>SVACER_TIMEOUT_IMPORT_RESULTS</code>
|15 минут
|Таймаут ожидания процесса начала импорта на сервере. При превышении, запрос на импорт будет отклонен с ошибкой. Формат Go Duration string: 1h2m3s. Переменная затрагивает только ожидание начала, но не ограничивает сам процесс импорта.
|-
|<code>SVACER_NUM_PARALLEL_IMPORTS</code>
|(<code>максимальное число коннектов к БД) / 2</code>
|Число одновременных параллельных импортов. Остальные ждут в очереди. На ожидание влияет переменная <code>SVACER_TIMEOUT_IMPORT_RESULTS</code>
|-
|<code>SVACER_TAIL_LOG_SIZE</code>
|1Мб
|Число. Размер буффера для показа лога сервера в WEB. Показывается последние SVACER_TAIL_LOG_SIZE байт из лога.
|-
|<code>SVACER_LOG_FORMAT</code>
|<пусто>
|При указании формата json вывод формат лога заменяется на JSON. Предназначено для интеграции с агрегаторами логов. Так же можно указать через флаг при старте
<code>svacer-server --log-format=json</code>
|-
|<code>SVACER_INV_GEN_JOBS</code>
|0.7 * runtime.GOMAXPROCS
|Максимальное число параллельных job-ов для генерации инвариантов при миграции старой базы или импорте результатов.
При ограниченных ресурсах сервера устанавливать в значение 1 или 2. Пользователь не может увеличить больше, чем GOMAXPROCS
|-
|
|
|
|}

=== Пересчет инвариантов ===
При миграции со старых версий иногда могут быть проблемы с переносом разметки. Для принудительного пересчета инвариантов пользователь может запустить сервер с опцией <code>--force-invariant-refresh</code>.

=== Объектное хранилище ===
При больших размерах объектного хранилища (object store) пользователь может запустить сервер с параметром <code>--compact-object-store</code> - это приведет к поиску недостижимых объектов в объектном хранилище и сокращении размера базы. Операция может занять продолжительное время.

'''ЭКСПЕРИМЕНТАЛЬНО''': Для быстрого получения копии текущего объектного хранилища пользователь может использовать CLI команду
svacer server backup --host <nowiki>http://localhost:8080</nowiki> --user admin --password <admin pwd> --checkpoint <path>
Данная команда создаст по пути ''<path>'' на '''хосте, где работает сервер''', копию object store. При создании копии по возможности используются hard link-и, для ускорения процесса. Процесс работает в background-е и можно запускать для работающего сервера.

LDAP configuration

2025-11-27T10:40:12Z

Chernykov sv:

==== Общий принцип аутентификации ====
Схема аутентификации с помощью протокола LDAP следующая:

# Сервер запускается с указанием конфигурационного файла с настройками для LDAP аутентификации
# В форме аутентификации пользователь выбирает нужный тип аутентификации (svacer или LDAP)
# При выборе аутентификации LDAP, после заполнения необходимых параметров, запрос на аутентификацию отправляется на сервер Svacer
# Сервер Svacer, используя настройки из конфигурационного файла, обращается к внешнему LDAP серверу и проводит проверку пользователя
# В случае успешной аутентификации, в БД сервера Svacer создается запись (если ее еще нет) для пользователя, чтобы можно было управлять ролями данного пользователя
# Сервер возвращает токен безопасности для дальнейшей работы, аналогичный токену, возвращаемому при аутентификации локальных пользователей

Для каждого пользователя, успешно прошедшего проверку на LDAP сервере, создается локальная запись в БД Svacer. Управлять таким пользователем можно как и обычным пользователем, за исключением:
* Пользователю нельзя сменить пароль
* Пользователь не может сменить пароль самостоятельно
* В случае отсутствия связи между сервером Svacer и сервером LDAP, данный пользователь не сможет зайти в систему

==== Запуск сервера с поддержкой LDAP ====
Сервер может быть запущен как в с поддержкой аутентификации через LDAP, так и без. Для того, чтобы включить аутентификацию через LDAP необходимо указать конфигурационный файл. Типовой пример конфигурационного файла для подключения к контроллеру домена MS ActiveDirectory или серверу openLDAP можно получить с помощью команды:

svacer ldap print

Запуск сервера с поддержкой LDAP осуществляется командой:

svacer-server run --ldap ldap.json

При запуске сервер svacer формирует список доступных для LDAP аутентификации серверов и выводит соответствующее сообщение. В логах сервера должна появится информация о добавлении сервера вида: "LDAP Server added: xxxx".

После запуска сервера svacer с поддержкой LDAP в GUI становится активна вкладка LDAP ([[Help:UI manual#Авторизация в пользовательском интерфейсе сервера Svacer|Авторизация]]).

Для аутентификации с помощью LDAP необходимо выбрать сервер из выпадающего списка.

При нажатии на кнопку '''Details''' появляется более подробная информация о сервере и его доступности (параметр '''Alive'''). Доступность сервера LDAP проверяется в момент запуска сервера Svacer, при аутентификации пользователя, а также (в случае наличия соответствующего параметра в конфигурационном файле) периодически.
В случае конфигурации сервера Svacer с поддержкой LDAP можно отключить возможность аутентификации пользователей встроенными средствами сервера Svacer (вкладка Svacer на странице входа). В этом случае вкладка Svacer на странице входа будет неактивной и пользователи смогут заходить в систему только с помощью LDAP аутентификации. Данное поведение распространяется и на работу с сервером с помощью интерфейса командной строки.

Для отключения возможности аутентификации встроенными средствами сервера Svacer нужно использовать опцию '''disable-svacer-auth'''.

Пример:
svacer-server run --ldap ldap.json --disable-svacer-auth

==== Конфигурационный файл сервера для поддержки LDAP ====
Типовой пример конфигурации:
{
"servers": [
{
"name": "active_directory",
"basedn": "dc=domain,dc=home,dc=org",
"useGroup": true,
"hideURL": true,
"checkAlivePeriod": 60,
"connection": {
"url": "ldaps://192.168.11.71:636",
"mirrors":["ldaps://192.168.11.72:636","ldaps://192.168.11.73:636"]
"connectAs": "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org",
"password": "12345678",
"ignoreCertCheck": false,
"caCertFiles":["/etc/ssl/certs/a*","/etc/ssl/certs/my_certs/*"]
},
"group": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Group)(cn=dep_devops))",
"userMember": "member",
"display":"cn",
"svacerRole":"cn"
},
"user": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Person)(sAMAccountName=*))",
"login": "sAMAccountName",
"group": "dn",
"info": {
"display": "cn",
"email": "email",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
},
{
"name": "open_ldap",
"basedn": "dc=example,dc=com",
"useGroup": true,
"connection": {
"url": "ldap://127.0.0.1:389",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678"
},
"group": {
"basedn": "ou=groups",
"filter": "(&(objectClass=groupOfNames)(cn=svacer))",
"userMember": "member",
"display":"cn"
},
"user": {
"basedn": "ou=users",
"filter": "(&(objectClass=PosixAccount))",
"login": "uid",
"group": "dn",
"info": {
"display": "dn",
"email": "mail",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
}
]
}

В конфигурации можно указать несколько серверов. Все сервера в совокупности рассматриваются как единый источник проверки пользователей. То есть если на двух серверах будут два пользователя с одинаковым логином, они будут считаться идентичными. Ниже приводится описание параметров конфигурации.
* name — произвольное имя (уникальное для каждого сервера)
* trace — флаг, позволяющий получить детальную информацию по этапам обработки запроса на вход пользователя LDAP в Svacer
* basedn — DN относительно которого будут проводится все операции в LDAP каталоге
* useGroup — проверять ли принадлежность пользователя к группе
* hideURL — не передавать сетевой адрес LDAP сервера. Конечные пользователи будут видеть в выпадающем списке только имя сервера, указанное в поле name. В поле URL будет пустая строка
* checkAlivePeriod — Промежуток времени в секундах, который должен проходить между периодическими проверками доступности сервера LDAP. Если параметр равен 0 или не указан, такая проверка не проводится.
* connection — подсекция, описывающая параметры соединения с сервером
:* url — адрес сервера, формата: ldap[s]://domain:port В случае использования TLS для подключения к LDAP серверу, необходимо указать правильный порт (по умолчанию 636)
:* mirrors — список хостов, которые будут использованы в случае недоступности основного хоста, указанного в поле URL. Формат указания хостов тот же, что и в поле URL. Префикс ldap[s] должен быть одинаковым для всех хостов и совпадать с префиксом в поле URL
:* connectAs — имя пользователя в формате DN, от которого будут производится операции в LDAP каталоге
:* password — пароль пользователя
:* ignoreCertCheck — не проверять сертификат в случае ldaps:// соединения. Полезно при самоподписанных сертификатах. Если флаг установлен в значение false, необходимо установить значение поля caCertFiles
:* CaCertFiles — массив значений, описывающих какие файлы корневых сертификатов добавлять в конфигурацию Svacer. Формат файлов сертификатов — PEM
* group — подсекция, описывает параметры проверки принадлежности пользователя к группе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске группы. Необходимо, если надо указать несколько групп
:* userMember — атрибут, содержащий пользователей группы
:* display — атрибут, содержащий имя группы для отображения
:* svacerRole — атрибут, из которого будет извлечено имя роли, созданной в Svacer, и автоматически сопоставляемой с пользователем
* user — подсекция, описывает параметры получения информации о пользователе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске пользователей
:* login — атрибут, в котором находится login пользователя
:* group — атрибут, на который ссылается атрибут group.userMember (обычно это «dn» пользователя)
:* defaultRole — роль Svacer, автоматически добавляемая всем пользователям LDAP, успешно вошедшим в Svacer
:* info — подсекция описывающая в каких атрибутах находится информация о пользователе
::* display — атрибут, содержащий полное имя пользователя для отображения (ФИО)
::* email — атрибут с почтовым адресом
::* firstName — атрибут с именем
::* lastName — атрибут с фамилией
* enabled — использовать или нет данный сервер

Конфигурацию для подключения к серверам '''LDAP''' можно также задать в конфигурационном файле '''Svacer'''. Например:

auth:
ldap:
servers:
- name: freeIPA
basedn: dc=example,dc=com
useGroup: false
type: freeIPA
hideURL: true
checkAlivePeriod: 1
connection:
url: ldap://svacer.local:7001
connectAs: cn=admin,dc=example,dc=com
password: 12345678
user:
basedn: ou=users
filter: "(&(objectClass=inetOrgPerson)(memberOf=*))"
login: cn
info:
display: cn
email: mail
firstName: givenName
lastName: sn
enabled: true
- name: example1
basedn: dc=example,dc=com
useGroup: false
hideURL: true
checkAlivePeriod: 1
connection:
url: ldap://svacer.local:7001
connectAs: cn=admin,dc=example,dc=com
password: 12345678
user:
basedn: <nowiki>''</nowiki>
filter: "(&(objectClass=inetOrgPerson)(memberOf=*))"
login: cn
group: dn
info:
display: cn
email: mail
firstName: givenName
lastName: sn
enabled: true

[[LDAP configuration|Подробное описание взаимодействия SVACER с LDAP сервером]]

Рассмотрим пример обработки запроса на вход в систему LDAP пользователя, указавшего значение ivanov_ii в поле логина и выбравшего конфигурацию active_directory из примера выше
:# Svacer создает служебное подключение к хосту 192.168.11.71 со следующими параметрами
:#* используется TLS соединение (ldaps префикс)
:#* порт 636
:#* проверяется сертификат LDAP сервера (ignoreCertCheck = false); для проверки используются сертификаты CA (из папки /etc/ssl/certs — все сертификаты, начинающиеся с буквы a; из папки /etc/ssl/certs/my_certs/ — все сертификаты)
:#* логин для подключения к LDAP серверу: "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org" (connectAs); пароль: 12345678 (password)
:# Если подключение к хосту невозможно (хост недоступен), то пробуются хосты 192.168.11.72,192.168.11.73 с параметрами, аналогичными параметрам пункта 1
:# Если подключение невозможно, процесс входа завершается с ошибкой
:# Производится поиск пользователя в LDAP каталоге со следующими параметрами:
:#* строка запроса: (&(sAMAccountName=ivanov_ii)((&(objectCategory=Person)(sAMAccountName=*)))), sAMAccountName — взят из поля user.login конфиг файла; ivanov_ii — введено пользователем; (&(objectCategory=Person)(sAMAccountName=*)) — взято из поля user.filter конфиг файла
:#*начальный узел, с которого будет произведен поиск: cn=users,dc=domain,dc=home,dc=org
:#*поиск производится по всему поддереву
:# Если пользователей не найдено или найдено больше 1 пользователя, процесс входа завершается с ошибкой
:# Флаг useGroup = true, поэтому производится дополнительная проверка группы пользователя
:#* выполняется поиск групп в каталоге LDAP со следующими параметрами:
:#**строка запроса: (&(objectCategory=Group)(cn=dep_devops)) — взято из поля group.filter
:#**начальный узел: cn=users,dc=domain,dc=home,dc=org, где cn=users — взято из поля group.basedn; значение dc=domain,dc=home,dc=org — взято из поля basedn конфиг файла
:#**поиск производится по всему поддереву
:#**определяется список пользователей группы, каждому пользователю соответствует значение атрибута с именем member (взято из поля group.userMember конфиг файла)
:#* Если ни одной группы не найдено, то процесс входа завершается с ошибкой
:#*Определяются группы, в которые входит пользователь. Для этого для каждой группы, найденной в пункте выше, просматривается список пользователей и ищется значение cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org (в поле user.group конфиг файла указано значение dn, что означает, что необходимо использовать DN пользователя для данной процедуры). Если атрибут найден, считается что пользователь принадлежит группе.
:#* Если пользователь не принадлежит ни к одной группе, процесс входа завершается с ошибкой
:# Производится попытка подключения к хосту LDAP с параметрами, аналогичными параметрам из пункта 1, за исключением логина (cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org) и пароля пользователя (введен в поле пароль формы входа)
:# Если подключение не удалось создать, то процесс входа завершается с ошибкой
:# Процесс аутентификации пользователя произведен успешно
:# Производится создание локального пользователя svacer с именем ivanov_ii, если его еще нет {{Note|type=warn|text=С версии 11 наличие двух пользователей с одинаковым логином: локального и пользователя LDAP — не допускается}}
:# Так как useGroup = true и указан атрибут svacerRole с непустым значением, то производится привязка ролей Savcer пользователя на основе его участия в группах LDAP (смотри соответствующий пункт)

==== Привязка группы LDAP к роли Svacer ====
Возможно автоматическое назначение пользователям LDAP ролей Svacer. Для использования данной функции необходимо выполнить следующие предварительные действия:
:* Администратор LDAP сервера создает в каталоге LDAP нужные группы (например cn=users,ou=svacer,dc=example,dc=com и cn=admins,ou=svacer,dc=example,dc=com), которые будут привязаны к ролям Svacer
:* Администратор LDAP сервера помещает пользователей LDAP в соответствующие LDAP группы (cn=users,ou=svacer,dc=example,dc=com или cn=admins,ou=svacer,dc=example,dc=com)
:* Администратор Svacer создает роли в Svacer, имеющие в точности такое же название, как значение атрибута, указанного в поле svacerRole конфигурационного файла. В пример можно использовать аттрибут cn и в этом случае необходимо создать роли users и admins
:* Администратор Svacer добавляет в конфигурационный файл в поле svacerRole имя атрибута, по которому будет производится привязка. Для примера выше — строчку svacerRole="cn"
После выполнения данных действий, во время входа пользователя в систему пользователю будут добавлены роли по следующему алгоритму:
:* Производится поиск групп, к которым принадлежит пользователь. Поиск производится по параметрам, указанным в секции group конфигурационного файла {{Note|text=На первом этапе будет произведен поиск всех групп, которые подпадают под условие фильтра в секции group. По этой причине необходимо указывать наиболее точное значение для фильтра группы, чтобы не было чрезмерно большого количества записей в результатах поиска (для MSAD — 2000 записей)}} Для примера, пользователь может состоять в следующих группах: (cn=users,ou=svacer,dc=example,dc=com), (cn=dep_dev,dc=example,dc=com)
:* Для каждой найденной группы, выбирается значение атрибута, указанного в поле svacerRole. В примере — имя атрибута cn. Получаются два имени: users, dep_dev (это те группы, которые могут быть привязаны к ролям Svacer)
:* Производится поиск ролей Svacer с именем users и dep_dev. Если такие роли найдены, то пользователю они будут добавлены. Так как в примере роль dep_dev не создана, то будет добавлена только роль users.

Удаление ролей автоматически не производится. Вместо этого предлагается ручной режим синхронизации ролей пользователя. Для синхронизации ролей с текущими группами, в которых состоит пользователь, используется команда cli

svacer ldap sync_roles --login [user_login] --server [server_name] --apply

Данная команда проверит наличие пользователя user_login в соответствующей роли группе LDAP и если его в группе не будет, уберет роль у пользователя. Также команда добавит недостающие роли, на основе механизма, описанного выше (при входе пользователя). Флаг apply позволяет "оценить" получаемые изменения прежде чем они будут применены. По умолчанию флаг apply = false.

Автоматическое назначение пользователю LDAP некоторой роли также возможно осуществить, указав необходимую роль в параметре '''user.defaultRole''' конфигурационного файла LDAP. Данная роль будет назначена в том случае, если она существует на момент входа пользователя в систему. Добавление роли будет происходить при каждом входе пользователя в систему. Поэтому даже если у пользователя эту роль удалить явно, она все равно будет добавлена пользователю при следующем входе. Данный механизм назначения роли работает независимо от настройки привязки роли к группе LDAP.

==== Использование CLI сервера Svacer с поддержкой LDAP ====
Для выполнения некоторых действий в cli с помощью команды svacer требуется аутентификация пользователя. Для аутентификации с помощью ldap сервера необходимо указать в команде кроме имени пользователя и пароля имя сервера с помощью флага ldap_server (имя сервера регистр-зависимо). Например:

svacer quickdiff --user loginok --password loginok --ldap_server openLDAP2 --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Если флаг ldap_server не указан, аутентификация производится механизмами сервера svacer, как и в предыдущих версиях. Параметр ldap_server можно опустить, указав сервер в переменной окружения SVACER_LDAP_SERVER. Например:

SVACER_LDAP_SERVER="openLDAP2" svacer quickdiff --user loginok --password loginok --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Для получения списка поддерживаемых свейсером LDAP серверов используйте команду:

svacer ldap servers --host 127.0.0.1 --port 8080

Вывод содержит два столбца (имя и URL сервера). В качестве значения для параметра ldap_server необходимо использовать содержимое первого столбца.

==== Обновление данных LDAP пользователей ====
Для каждого LDAP пользователя создается соответствующая ему запись в БД Svacer, в которую включается ФИО из LDAP и адрес его электронной почты. Через какое-то время данные пользователей могут меняться, в этом случае возможно обновить данные LDAP пользователей, хранящиеся в Svacer, синхронизировав их с данными LDAP сервера.
Для обновления данных одного пользователя можно воспользоваться окном редактирования пользователя, в котором можно нажать кнопку '''Load from LDAP'''. В соответствующие окна будут добавлены данные, загруженные из LDAP сервера (см. раздел [[Help:UI manual#Управление пользователями|Управление пользователями]]).

Также данные пользователей можно обновить с помощью интерфейса командной строки. Для этого можно использовать подкоманду '''updateUsers''' команды '''ldap'''. Общий синтаксис команды выглядит следующим образом:

svacer ldap updateUsers --onlyEmpty

Флаг '''onlyEmpty''' позволяет обновлять только пустые поля ФИО и eMail. Заполненные поля не будут изменены. Команда обновит данные всех пользователей, записи о которых имеются в базе Svacer.

==== Пример конфигурации сервера Svacer для поддержки аутентификации по LDAP протоколу ====

Для упрощения настройки интеграции с LDAP сервером, процесс настройки можно разбить на этапы и переходить к следующему только если успешно завершен предыдущий этап. В первую очередь необходимо выяснить актуальные параметры подключения к ldap серверу:
* URL; Например ldap://10.11.12.13:389 или ldaps://10.11.12.13:636
* Учетные данные с которыми будет осуществляться подключение к LDAP серверу при каждой попытке входа пользователем; Например, login: cn=admin,dc=example,dc=com, пароль: 12345678
* Определиться с корнем LDAP дерева (базовый узел), относительно которого будут выполняться все операции; Например: dc=example,dc=com
* Проверить, что с указанными учетными данными возможно подключение к серверу LDAP и просмотр его содержимого с некоторого узла, расположенного ниже базового; Например, с узла ou=users,dc=example,dc=com для рассматриваемого примера. Проверить можно, например, используя следующую команду:
:<pre>LDAPTLS_REQCERT=never ldapsearch -v -x -D cn=admin,dc=example,dc=com -w 12345678 -b ou=users,dc=example,dc=com -H ldaps://127.0.0.1:636</pre>
:для случая поддержки TLS, или
:<pre>ldapsearch -v -x -D cn=admin,dc=example,dc=com -w 12345678 -b ou=users,dc=example,dc=com -H ldap://127.0.0.1:389</pre>
:для случая без поддержки TLS
* Определиться с атрибутом записи, по которой будет осуществляться вход. Например cn, mail или sAMAccountName
* Если используется Active Directory, целесообразно в качестве фильтра для поиска записей о пользователе указать значение (&(objectCategory=Person)(sAMAccountName=*))

===== Основные настройки LDAP =====
* Использовать следующий шаблон конфигурации, заменив текст, выделенный жирным, актуальными данными
{
"servers": [
{
"name": "test_ldap",
"basedn": '''"dc=example,dc=com"''',
"connection": {
"url": '''"ldap://ldap1.example.com:389"''',
"connectAs": '''"cn=admin,dc=example,dc=com"''',
"password": '''"12345678"'''
},
"user": {
"basedn": '''"ou=users"''',
"filter": '''"(&(objectClass=PosixAccount)(cn=*))"''',
"login": '''"cn"''',
"info": {
"display": "cn",
"email": "mail",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
}
]
}

* Поиск пользователя в каталоге LDAP будет производится от узла, DN которого является конкатенацией значений user.basedn и basedn. В примере это будет узел ou=users,dc=example,dc=com. Полный DN пользователя указывать в user.basedn не нужно (можно указать пустой или не указывать вообще)
* Убедиться, что при старте сервера в логах присутствуют строки:
2023-04-24T12:35:44.650+0300 info Loading ldap configuration from file: ldap2.json
2023-04-24T12:35:44.650+0300 info LDAP server added: test_ldap
* Выполнить команду, заменив хост и порт актуальными значениями
svacer ldap servers --host 127.0.0.1 --port 8080
* Убедиться, что в выводе команды присутствуют записи вида:
Available LDAP servers list:
Name: test_ldap Url: ldap://ldap1.example.com:389
* Убедиться, что возможен вход тестовым пользователем через cli:
curl -X POST --data '{"login":"test_login","password":"test_password","auth_type":"ldap","server":"test_ldap"}' 127.0.0.1:8080/api/public/login
Вывод должен быть вида:
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODI5MzYxODcsImlhdCI6MTY4MjMzMTM4Nywicm9sZXMiOlsiYWRtaW5zIl0sInVzZXIiO ..."}

===== Добавление проверки по группе LDAP =====
Принадлежность пользователя к группе определяется следующим образом:
* Формируется список всех возможных групп на основе значения group.filter
* Для каждой сформированной группы формируется список входящих в нее пользователей по следующему принципу:
** Каждое значение атрибута group.userMember (их может быть несколько) узла LDAP (соответствующего группе) однозначно идентифицирует некоторого пользователя
** Пользователь входит в группу, если значение атрибута user.group пользователя входит в множество записей, полученных в пункте выше

Для настройки проверки по группе целесообразно выполнить следующие действия:
* Определиться с узлом в LDAP, относительно которого будет производится поиск групп (поле group.basedn). Поиск групп в каталоге LDAP будет производится от узла, DN которого является конкатенацией значений group.basedn и basedn. В примере это будет узел ou=svacer_groups,ou=groups,dc=example,dc=com
* Для Active Directory в поле filter можно указать, например, (&(objectCategory=Group)(cn=dep_ivanov)), что будет означать группу dep_ivanov.
* Изменить конфигурационный файл следующим образом:
{
"name": "test_ldap",
...
},
"user": {
...
'''"group": "dn"''',
},
'''"useGroup": true,'''
'''"group": {''''
'''"basedn": "ou=svacer_groups,ou=groups",'''
'''"filter": "(&(objectClass=groupOfNames)(cn=*))",'''
'''"userMember": "member",'''
'''"display":"cn",'''
},
"enabled": true
}

* Перезапустить Svacer
* Убедиться, что возможен вход пользователей, состоящих в группе/группах, и не возможен вход пользователей, не состоящих в группе/группах.
===== Добавление привязки ролей Svacer к группам LDAP =====
* Добавить нужные группы в Svacer. Например admins и users.
* Определиться в каком атрибуте LDAP группы будет хранится имя роли (все сравнения будут чувствительны к регистру). Например, пусть это будет атрибут cn
* Изменить конфигурационный файл следующим образом
{
"name": "test_ldap",
...
"user": {
...
},
''' "useGroup": true, '''
''' "group": { '''
''' "basedn": "ou=svacer_groups,ou=groups", '''
''' "filter": "(&(objectClass=groupOfNames)(cn=*))", '''
''' "userMember": "member", '''
''' "display": "cn", '''
''' "svacerRole": "cn" '''
''' }, '''
"enabled": true
}

* Убедиться, что пользователю назначаются роли, выполнив команду в cli (требуются учетные данные администратора для проверки; по умолчанию admin / admin). Для проверки привязки ролей Svacer к пользователю loginok можно использовать следующую команду:
svacer ldap sync_roles --login loginok --host 127.0.0.1 --port 8080 --user admin --password admin --server test_ldap
Вывод должен быть следующий:
SvacerUserID: 457039b4-4aef-4857-831d-1c080ea154d4
SvacerUserLogin: loginok
LDAPUserDN: cn=loginok,ou=users,dc=example,dc=com
Roles: [314e7571-706c-4463-9280-6a4eee03b42d]
Links: [cn=admins,ou=svacer_groups,ou=groups,dc=example,dc=com -> admins (314e7571-706c-4463-9280-6a4eee03b42d)]
Applied: false

===== Добавление серверов LDAP, работающих по TLS =====
* Изменить конфигурационный файл следующим образом:
{
"name": "test_ldap",
"basedn": "dc=example,dc=com",
"connection": {
"url": "'''ldaps'''://ldap1.example.com:'''636'''",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678",
"ignoreCertCheck": '''true'''
},
"user": {
...
},
...
"enabled": true
}

* Убедиться, что возможен вход пользователем LDAP. Для проверки можно использовать утилиту curl, как указано в примере с основными настройками
* Для проверки сертификата LDAP сервера добавить сертификат CA (например, ldap.crt) в папку с сертификатами (например, /etc/ssl/certs/) и внести следующие изменения в конфигурационный файл:
{
"name": "test_ldap",
"basedn": "dc=example,dc=com",
"connection": {
"url": "ldaps://ldap1.example.com:636",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678",
"ignoreCertCheck": '''false''',
'''"caCertFiles": ["/etc/ssl/certs/ldap.crt"]'''
},
"user": {
...
},
...
},
"enabled": true
}

* Убедиться, что в логах сервера присутствуют записи вида:
2023-04-24T13:49:49.298+0300 info added 1 ca certs from ldap.crt
* Убедиться, что пользователь LDAP может зайти в систему

===== Добавление резервных серверов LDAP =====
* Добавить в конфигурационный файл резервные сервера в поле mirrors:
{
"name": "test_ldap",
"basedn": "dc=example,dc=com",
"connection": {
"url": "ldaps://ldap1.example.com:636",
'''"mirrors": ["ldaps://ldap2.example.com:636","ldaps://ldap3.example.com:636"],'''
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678",
...
},
"user": {
...
},
...
"enabled": true
}

* Проверить, что вход пользователя LDAP в систему возможен
* Изменить значение в URL на любое (чтобы сервер, указанный в URL, был не доступен)
* Перезапустить Svacer
* Убедиться, что вход пользователя LDAP в систему возможен
* Поменять значение в URL на верное

==== Возможные ошибки конфигурации ====
В случае ошибки входа пользователя в систему сервер выводит текстовые сообщения, указывающие на причину ошибки. Наиболее полную информацию об ошибке можно видеть, использовав флаг <code>--debug</code> при запуске сервера Svacer. Логи сервера можно посмотреть в GUI Svacer из под пользователя с правами администратора в разделе '''Settings > Server information'''. Ниже приводится таблица с перечислением возможных ошибок входа пользователя LDAP в систему.

'''Сообщения об ошибках и их возможные причины'''
{| class="wikitable" style="margin:auto"
|-
!Действие !! Сообщение !! Причина !! Решение
|-
| Вход в систему || LDAP server unavailable || 1. Нет соединения с сервером<br/>2. Неверные учетные данные для соединения с сервером || Проверить доступность сервера LDAP с хоста, на котором установлен Svacer. См. утилиту ldapsearch
|-
| Вход в систему || LDAP user is not in group||Пользователь не состоит в заданной конфигурацией группе/группах||Проверить поля user.group, group.filter, group.userMember. В списке групп, полученных с использованием group.filter должна быть хотя бы одна группа, в которую входит пользователь
|-
| Вход в систему || LDAP group not found. Check configuration || Во время поиска групп, подходящих под фильтр, не найдено ни одной группы || Проверить значение поля group.filter и значения basedn, group.basedn
|-
| Вход в систему || LDAP user not allowed or not found || Во время поиска пользователей, подходящих под фильтр, не найдено ни одного пользователя || Проверить значение поля user.filter и значения basedn, user.basedn
|-
| Вход в систему || too much record for user ('%s') found || Поиск пользователя в LDAP с указанными в конфигурации парамтерами дал несколько записей|| Проверить значение поля user.filter и значения basedn, user.basedn. Поиск всегда должен давать одну запись
|-
| Запуск сервера || caCert source [%v] ignored || Ошибка поиска сертификатов по указанному шаблону || Проверить поле connection.caCertFiles конфигурации и убедится, что по указанному в поле шаблону присутствуют сертификаты и к ним есть доступ (проверить права). Все пути должны быть абсолютными
|-
|Запуск сервера || Server [%v] configuration has ignoreCertCheck=false, but no CA certs added. In this case LDAP auth may be impossible || Ошибка конфигурации TLS. В результате обработки значений из поля connection.CaCertFiles не было добавлено ни одного сертификата. Это приводит к тому, что Svacer не может проверить сертификат LDAP сервера, а флаг ignoreCertCheck указан в значении false, что приведет к заведомо ошибочной проверке пользователя || Проверить поле connection.caCertFiles конфигурации и убедится, что по указанному в поле шаблону присутствуют сертификаты и к ним есть доступ (проверить права). Все пути должны быть абсолютными
|}
Для определения проблем с входом пользователей LDAP в систему при первоначальной настройке интеграции, полезно установить флаг trace в значение true. Результатом станет вывод в лог сервера Debug сообщения с указанием этапа обработки запроса и его параметров.

==== Некоторые замечания для пользователей, которые использовали LDAP, начиная с версии Svacer 5-1-0 до 5-2-0 ====

Для пользователей, которые использовали функционал по интеграции с LDAP серверами в период между релизами Svacer 5-1-0 и 5-2-0 (с 30.03.2022 по 15.07.2022) желательная ручная модификации базы данных, так как в ней могут быть ошибки, влияющие на

* механизм тегирования пользователей в комментариях
* механизм уведомления

Если в процессе функционирования сервера наблюдаются сбои в работе указанных механизмов, то следует выполнить следующйи sql запрос в БД, с которой работает Svacer:

<pre class="">insert into users_status (user_id,status)
select id,1 from users
left join users_status us on us.user_id=users.id
where status is null;</pre>

LDAP configuration

2025-11-27T10:39:55Z

Chernykov sv:

==== Общий принцип аутентификации ====
Схема аутентификации с помощью протокола LDAP следующая:

# Сервер запускается с указанием конфигурационного файла с настройками для LDAP аутентификации
# В форме аутентификации пользователь выбирает нужный тип аутентификации (svacer или LDAP)
# При выборе аутентификации LDAP, после заполнения необходимых параметров, запрос на аутентификацию отправляется на сервер Svacer
# Сервер Svacer, используя настройки из конфигурационного файла, обращается к внешнему LDAP серверу и проводит проверку пользователя
# В случае успешной аутентификации, в БД сервера Svacer создается запись (если ее еще нет) для пользователя, чтобы можно было управлять ролями данного пользователя
# Сервер возвращает токен безопасности для дальнейшей работы, аналогичный токену, возвращаемому при аутентификации локальных пользователей

Для каждого пользователя, успешно прошедшего проверку на LDAP сервере, создается локальная запись в БД Svacer. Управлять таким пользователем можно как и обычным пользователем, за исключением:
* Пользователю нельзя сменить пароль
* Пользователь не может сменить пароль самостоятельно
* В случае отсутствия связи между сервером Svacer и сервером LDAP, данный пользователь не сможет зайти в систему

==== Запуск сервера с поддержкой LDAP ====
Сервер может быть запущен как в с поддержкой аутентификации через LDAP, так и без. Для того, чтобы включить аутентификацию через LDAP необходимо указать конфигурационный файл. Типовой пример конфигурационного файла для подключения к контроллеру домена MS ActiveDirectory или серверу openLDAP можно получить с помощью команды:

svacer ldap print

Запуск сервера с поддержкой LDAP осуществляется командой:

svacer-server run --ldap ldap.json

При запуске сервер svacer формирует список доступных для LDAP аутентификации серверов и выводит соответствующее сообщение. В логах сервера должна появится информация о добавлении сервера вида: "LDAP Server added: xxxx".

После запуска сервера svacer с поддержкой LDAP в GUI становится активна вкладка LDAP ([[Help:UI manual#Авторизация в пользовательском интерфейсе сервера Svacer|Авторизация]]).

Для аутентификации с помощью LDAP необходимо выбрать сервер из выпадающего списка.

При нажатии на кнопку '''Details''' появляется более подробная информация о сервере и его доступности (параметр '''Alive'''). Доступность сервера LDAP проверяется в момент запуска сервера Svacer, при аутентификации пользователя, а также (в случае наличия соответствующего параметра в конфигурационном файле) периодически.
В случае конфигурации сервера Svacer с поддержкой LDAP можно отключить возможность аутентификации пользователей встроенными средствами сервера Svacer (вкладка Svacer на странице входа). В этом случае вкладка Svacer на странице входа будет неактивной и пользователи смогут заходить в систему только с помощью LDAP аутентификации. Данное поведение распространяется и на работу с сервером с помощью интерфейса командной строки.

Для отключения возможности аутентификации встроенными средствами сервера Svacer нужно использовать опцию '''disable-svacer-auth'''.

Пример:
svacer-server run --ldap ldap.json --disable-svacer-auth

==== Конфигурационный файл сервера для поддержки LDAP ====
Типовой пример конфигурации:
{
"servers": [
{
"name": "active_directory",
"basedn": "dc=domain,dc=home,dc=org",
"useGroup": true,
"hideURL": true,
"checkAlivePeriod": 60,
"connection": {
"url": "ldaps://192.168.11.71:636",
"mirrors":["ldaps://192.168.11.72:636","ldaps://192.168.11.73:636"]
"connectAs": "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org",
"password": "12345678",
"ignoreCertCheck": false,
"caCertFiles":["/etc/ssl/certs/a*","/etc/ssl/certs/my_certs/*"]
},
"group": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Group)(cn=dep_devops))",
"userMember": "member",
"display":"cn",
"svacerRole":"cn"
},
"user": {
"basedn": "cn=users",
"filter": "(&(objectCategory=Person)(sAMAccountName=*))",
"login": "sAMAccountName",
"group": "dn",
"info": {
"display": "cn",
"email": "email",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
},
{
"name": "open_ldap",
"basedn": "dc=example,dc=com",
"useGroup": true,
"connection": {
"url": "ldap://127.0.0.1:389",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678"
},
"group": {
"basedn": "ou=groups",
"filter": "(&(objectClass=groupOfNames)(cn=svacer))",
"userMember": "member",
"display":"cn"
},
"user": {
"basedn": "ou=users",
"filter": "(&(objectClass=PosixAccount))",
"login": "uid",
"group": "dn",
"info": {
"display": "dn",
"email": "mail",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
}
]
}

В конфигурации можно указать несколько серверов. Все сервера в совокупности рассматриваются как единый источник проверки пользователей. То есть если на двух серверах будут два пользователя с одинаковым логином, они будут считаться идентичными. Ниже приводится описание параметров конфигурации.
* name — произвольное имя (уникальное для каждого сервера)
* trace — флаг, позволяющий получить детальную информацию по этапам обработки запроса на вход пользователя LDAP в Svacer
* basedn — DN относительно которого будут проводится все операции в LDAP каталоге
* useGroup — проверять ли принадлежность пользователя к группе
* hideURL — не передавать сетевой адрес LDAP сервера. Конечные пользователи будут видеть в выпадающем списке только имя сервера, указанное в поле name. В поле URL будет пустая строка
* checkAlivePeriod — Промежуток времени в секундах, который должен проходить между периодическими проверками доступности сервера LDAP. Если параметр равен 0 или не указан, такая проверка не проводится.
* connection — подсекция, описывающая параметры соединения с сервером
:* url — адрес сервера, формата: ldap[s]://domain:port В случае использования TLS для подключения к LDAP серверу, необходимо указать правильный порт (по умолчанию 636)
:* mirrors — список хостов, которые будут использованы в случае недоступности основного хоста, указанного в поле URL. Формат указания хостов тот же, что и в поле URL. Префикс ldap[s] должен быть одинаковым для всех хостов и совпадать с префиксом в поле URL
:* connectAs — имя пользователя в формате DN, от которого будут производится операции в LDAP каталоге
:* password — пароль пользователя
:* ignoreCertCheck — не проверять сертификат в случае ldaps:// соединения. Полезно при самоподписанных сертификатах. Если флаг установлен в значение false, необходимо установить значение поля caCertFiles
:* CaCertFiles — массив значений, описывающих какие файлы корневых сертификатов добавлять в конфигурацию Svacer. Формат файлов сертификатов — PEM
* group — подсекция, описывает параметры проверки принадлежности пользователя к группе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске группы. Необходимо, если надо указать несколько групп
:* userMember — атрибут, содержащий пользователей группы
:* display — атрибут, содержащий имя группы для отображения
:* svacerRole — атрибут, из которого будет извлечено имя роли, созданной в Svacer, и автоматически сопоставляемой с пользователем
* user — подсекция, описывает параметры получения информации о пользователе
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
:* filter — фильтр, используемый при поиске пользователей
:* login — атрибут, в котором находится login пользователя
:* group — атрибут, на который ссылается атрибут group.userMember (обычно это «dn» пользователя)
:* defaultRole — роль Svacer, автоматически добавляемая всем пользователям LDAP, успешно вошедшим в Svacer
:* info — подсекция описывающая в каких атрибутах находится информация о пользователе
::* display — атрибут, содержащий полное имя пользователя для отображения (ФИО)
::* email — атрибут с почтовым адресом
::* firstName — атрибут с именем
::* lastName — атрибут с фамилией
* enabled — использовать или нет данный сервер

Конфигурацию для подключения к серверам '''LDAP''' можно также задать в конфигурационном файле '''Svacer'''. Например:

auth:
ldap:
servers:
- name: freeIPA
basedn: dc=example,dc=com
useGroup: false
type: freeIPA
hideURL: true
checkAlivePeriod: 1
connection:
url: ldap://svacer.local:7001
connectAs: cn=admin,dc=example,dc=com
password: 12345678
user:
basedn: ou=users
filter: "(&(objectClass=inetOrgPerson)(memberOf=*))"
login: cn
info:
display: cn
email: mail
firstName: givenName
lastName: sn
enabled: true
- name: example1
basedn: dc=example,dc=com
useGroup: false
hideURL: true
checkAlivePeriod: 1
connection:
url: ldap://svacer.local:7001
connectAs: cn=admin,dc=example,dc=com
password: 12345678
user:
basedn: <nowiki>''</nowiki>
filter: "(&(objectClass=inetOrgPerson)(memberOf=*))"
login: cn
group: dn
info:
display: cn
email: mail
firstName: givenName
lastName: sn
enabled: true

[[LDAP configuration|Подробное описание взаимодействия SVACER с LDAP сервером]]

Рассмотрим пример обработки запроса на вход в систему LDAP пользователя, указавшего значение ivanov_ii в поле логина и выбравшего конфигурацию active_directory из примера выше
:# Svacer создает служебное подключение к хосту 192.168.11.71 со следующими параметрами
:#* используется TLS соединение (ldaps префикс)
:#* порт 636
:#* проверяется сертификат LDAP сервера (ignoreCertCheck = false); для проверки используются сертификаты CA (из папки /etc/ssl/certs — все сертификаты, начинающиеся с буквы a; из папки /etc/ssl/certs/my_certs/ — все сертификаты)
:#* логин для подключения к LDAP серверу: "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org" (connectAs); пароль: 12345678 (password)
:# Если подключение к хосту невозможно (хост недоступен), то пробуются хосты 192.168.11.72,192.168.11.73 с параметрами, аналогичными параметрам пункта 1
:# Если подключение невозможно, процесс входа завершается с ошибкой
:# Производится поиск пользователя в LDAP каталоге со следующими параметрами:
:#* строка запроса: (&(sAMAccountName=ivanov_ii)((&(objectCategory=Person)(sAMAccountName=*)))), sAMAccountName — взят из поля user.login конфиг файла; ivanov_ii — введено пользователем; (&(objectCategory=Person)(sAMAccountName=*)) — взято из поля user.filter конфиг файла
:#*начальный узел, с которого будет произведен поиск: cn=users,dc=domain,dc=home,dc=org
:#*поиск производится по всему поддереву
:# Если пользователей не найдено или найдено больше 1 пользователя, процесс входа завершается с ошибкой
:# Флаг useGroup = true, поэтому производится дополнительная проверка группы пользователя
:#* выполняется поиск групп в каталоге LDAP со следующими параметрами:
:#**строка запроса: (&(objectCategory=Group)(cn=dep_devops)) — взято из поля group.filter
:#**начальный узел: cn=users,dc=domain,dc=home,dc=org, где cn=users — взято из поля group.basedn; значение dc=domain,dc=home,dc=org — взято из поля basedn конфиг файла
:#**поиск производится по всему поддереву
:#**определяется список пользователей группы, каждому пользователю соответствует значение атрибута с именем member (взято из поля group.userMember конфиг файла)
:#* Если ни одной группы не найдено, то процесс входа завершается с ошибкой
:#*Определяются группы, в которые входит пользователь. Для этого для каждой группы, найденной в пункте выше, просматривается список пользователей и ищется значение cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org (в поле user.group конфиг файла указано значение dn, что означает, что необходимо использовать DN пользователя для данной процедуры). Если атрибут найден, считается что пользователь принадлежит группе.
:#* Если пользователь не принадлежит ни к одной группе, процесс входа завершается с ошибкой
:# Производится попытка подключения к хосту LDAP с параметрами, аналогичными параметрам из пункта 1, за исключением логина (cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org) и пароля пользователя (введен в поле пароль формы входа)
:# Если подключение не удалось создать, то процесс входа завершается с ошибкой
:# Процесс аутентификации пользователя произведен успешно
:# Производится создание локального пользователя svacer с именем ivanov_ii, если его еще нет {{Note|type=warn|text=С версии 11 наличие двух пользователей с одинаковым логином: локального и пользователя LDAP — не допускается}}
:# Так как useGroup = true и указан атрибут svacerRole с непустым значением, то производится привязка ролей Savcer пользователя на основе его участия в группах LDAP (смотри соответствующий пункт)

==== Привязка группы LDAP к роли Svacer ====
Возможно автоматическое назначение пользователям LDAP ролей Svacer. Для использования данной функции необходимо выполнить следующие предварительные действия:
:* Администратор LDAP сервера создает в каталоге LDAP нужные группы (например cn=users,ou=svacer,dc=example,dc=com и cn=admins,ou=svacer,dc=example,dc=com), которые будут привязаны к ролям Svacer
:* Администратор LDAP сервера помещает пользователей LDAP в соответствующие LDAP группы (cn=users,ou=svacer,dc=example,dc=com или cn=admins,ou=svacer,dc=example,dc=com)
:* Администратор Svacer создает роли в Svacer, имеющие в точности такое же название, как значение атрибута, указанного в поле svacerRole конфигурационного файла. В пример можно использовать аттрибут cn и в этом случае необходимо создать роли users и admins
:* Администратор Svacer добавляет в конфигурационный файл в поле svacerRole имя атрибута, по которому будет производится привязка. Для примера выше — строчку svacerRole="cn"
После выполнения данных действий, во время входа пользователя в систему пользователю будут добавлены роли по следующему алгоритму:
:* Производится поиск групп, к которым принадлежит пользователь. Поиск производится по параметрам, указанным в секции group конфигурационного файла {{Note|text=На первом этапе будет произведен поиск всех групп, которые подпадают под условие фильтра в секции group. По этой причине необходимо указывать наиболее точное значение для фильтра группы, чтобы не было чрезмерно большого количества записей в результатах поиска (для MSAD — 2000 записей)}} Для примера, пользователь может состоять в следующих группах: (cn=users,ou=svacer,dc=example,dc=com), (cn=dep_dev,dc=example,dc=com)
:* Для каждой найденной группы, выбирается значение атрибута, указанного в поле svacerRole. В примере — имя атрибута cn. Получаются два имени: users, dep_dev (это те группы, которые могут быть привязаны к ролям Svacer)
:* Производится поиск ролей Svacer с именем users и dep_dev. Если такие роли найдены, то пользователю они будут добавлены. Так как в примере роль dep_dev не создана, то будет добавлена только роль users.

Удаление ролей автоматически не производится. Вместо этого предлагается ручной режим синхронизации ролей пользователя. Для синхронизации ролей с текущими группами, в которых состоит пользователь, используется команда cli

svacer ldap sync_roles --login [user_login] --server [server_name] --apply

Данная команда проверит наличие пользователя user_login в соответствующей роли группе LDAP и если его в группе не будет, уберет роль у пользователя. Также команда добавит недостающие роли, на основе механизма, описанного выше (при входе пользователя). Флаг apply позволяет "оценить" получаемые изменения прежде чем они будут применены. По умолчанию флаг apply = false.

Автоматическое назначение пользователю LDAP некоторой роли также возможно осуществить, указав необходимую роль в параметре '''user.defaultRole''' конфигурационного файла LDAP. Данная роль будет назначена в том случае, если она существует на момент входа пользователя в систему. Добавление роли будет происходить при каждом входе пользователя в систему. Поэтому даже если у пользователя эту роль удалить явно, она все равно будет добавлена пользователю при следующем входе. Данный механизм назначения роли работает независимо от настройки привязки роли к группе LDAP.

==== Использование CLI сервера Svacer с поддержкой LDAP ====
Для выполнения некоторых действий в cli с помощью команды svacer требуется аутентификация пользователя. Для аутентификации с помощью ldap сервера необходимо указать в команде кроме имени пользователя и пароля имя сервера с помощью флага ldap_server (имя сервера регистр-зависимо). Например:

svacer quickdiff --user loginok --password loginok --ldap_server openLDAP2 --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Если флаг ldap_server не указан, аутентификация производится механизмами сервера svacer, как и в предыдущих версиях. Параметр ldap_server можно опустить, указав сервер в переменной окружения SVACER_LDAP_SERVER. Например:

SVACER_LDAP_SERVER="openLDAP2" svacer quickdiff --user loginok --password loginok --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Для получения списка поддерживаемых свейсером LDAP серверов используйте команду:

svacer ldap servers --host 127.0.0.1 --port 8080

Вывод содержит два столбца (имя и URL сервера). В качестве значения для параметра ldap_server необходимо использовать содержимое первого столбца.

==== Обновление данных LDAP пользователей ====
Для каждого LDAP пользователя создается соответствующая ему запись в БД Svacer, в которую включается ФИО из LDAP и адрес его электронной почты. Через какое-то время данные пользователей могут меняться, в этом случае возможно обновить данные LDAP пользователей, хранящиеся в Svacer, синхронизировав их с данными LDAP сервера.
Для обновления данных одного пользователя можно воспользоваться окном редактирования пользователя, в котором можно нажать кнопку '''Load from LDAP'''. В соответствующие окна будут добавлены данные, загруженные из LDAP сервера (см. раздел [[Help:UI manual#Управление пользователями|Управление пользователями]]).

Также данные пользователей можно обновить с помощью интерфейса командной строки. Для этого можно использовать подкоманду '''updateUsers''' команды '''ldap'''. Общий синтаксис команды выглядит следующим образом:

svacer ldap updateUsers --onlyEmpty

Флаг '''onlyEmpty''' позволяет обновлять только пустые поля ФИО и eMail. Заполненные поля не будут изменены. Команда обновит данные всех пользователей, записи о которых имеются в базе Svacer.

==== Пример конфигурации сервера Svacer для поддержки аутентификации по LDAP протоколу ====

Для упрощения настройки интеграции с LDAP сервером, процесс настройки можно разбить на этапы и переходить к следующему только если успешно завершен предыдущий этап. В первую очередь необходимо выяснить актуальные параметры подключения к ldap серверу:
* URL; Например ldap://10.11.12.13:389 или ldaps://10.11.12.13:636
* Учетные данные с которыми будет осуществляться подключение к LDAP серверу при каждой попытке входа пользователем; Например, login: cn=admin,dc=example,dc=com, пароль: 12345678
* Определиться с корнем LDAP дерева (базовый узел), относительно которого будут выполняться все операции; Например: dc=example,dc=com
* Проверить, что с указанными учетными данными возможно подключение к серверу LDAP и просмотр его содержимого с некоторого узла, расположенного ниже базового; Например, с узла ou=users,dc=example,dc=com для рассматриваемого примера. Проверить можно, например, используя следующую команду:
:<pre>LDAPTLS_REQCERT=never ldapsearch -v -x -D cn=admin,dc=example,dc=com -w 12345678 -b ou=users,dc=example,dc=com -H ldaps://127.0.0.1:636</pre>
:для случая поддержки TLS, или
:<pre>ldapsearch -v -x -D cn=admin,dc=example,dc=com -w 12345678 -b ou=users,dc=example,dc=com -H ldap://127.0.0.1:389</pre>
:для случая без поддержки TLS
* Определиться с атрибутом записи, по которой будет осуществляться вход. Например cn, mail или sAMAccountName
* Если используется Active Directory, целесообразно в качестве фильтра для поиска записей о пользователе указать значение (&(objectCategory=Person)(sAMAccountName=*))

===== Основные настройки LDAP =====
* Использовать следующий шаблон конфигурации, заменив текст, выделенный жирным, актуальными данными
{
"servers": [
{
"name": "test_ldap",
"basedn": '''"dc=example,dc=com"''',
"connection": {
"url": '''"ldap://ldap1.example.com:389"''',
"connectAs": '''"cn=admin,dc=example,dc=com"''',
"password": '''"12345678"'''
},
"user": {
"basedn": '''"ou=users"''',
"filter": '''"(&(objectClass=PosixAccount)(cn=*))"''',
"login": '''"cn"''',
"info": {
"display": "cn",
"email": "mail",
"firstName": "givenName",
"lastName": "sn"
}
},
"enabled": true
}
]
}

* Поиск пользователя в каталоге LDAP будет производится от узла, DN которого является конкатенацией значений user.basedn и basedn. В примере это будет узел ou=users,dc=example,dc=com. Полный DN пользователя указывать в user.basedn не нужно (можно указать пустой или не указывать вообще)
* Убедиться, что при старте сервера в логах присутствуют строки:
2023-04-24T12:35:44.650+0300 info Loading ldap configuration from file: ldap2.json
2023-04-24T12:35:44.650+0300 info LDAP server added: test_ldap
* Выполнить команду, заменив хост и порт актуальными значениями
svacer ldap servers --host 127.0.0.1 --port 8080
* Убедиться, что в выводе команды присутствуют записи вида:
Available LDAP servers list:
Name: test_ldap Url: ldap://ldap1.example.com:389
* Убедиться, что возможен вход тестовым пользователем через cli:
curl -X POST --data '{"login":"test_login","password":"test_password","auth_type":"ldap","server":"test_ldap"}' 127.0.0.1:8080/api/public/login
Вывод должен быть вида:
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODI5MzYxODcsImlhdCI6MTY4MjMzMTM4Nywicm9sZXMiOlsiYWRtaW5zIl0sInVzZXIiO ..."}

===== Добавление проверки по группе LDAP =====
Принадлежность пользователя к группе определяется следующим образом:
* Формируется список всех возможных групп на основе значения group.filter
* Для каждой сформированной группы формируется список входящих в нее пользователей по следующему принципу:
** Каждое значение атрибута group.userMember (их может быть несколько) узла LDAP (соответствующего группе) однозначно идентифицирует некоторого пользователя
** Пользователь входит в группу, если значение атрибута user.group пользователя входит в множество записей, полученных в пункте выше

Для настройки проверки по группе целесообразно выполнить следующие действия:
* Определиться с узлом в LDAP, относительно которого будет производится поиск групп (поле group.basedn). Поиск групп в каталоге LDAP будет производится от узла, DN которого является конкатенацией значений group.basedn и basedn. В примере это будет узел ou=svacer_groups,ou=groups,dc=example,dc=com
* Для Active Directory в поле filter можно указать, например, (&(objectCategory=Group)(cn=dep_ivanov)), что будет означать группу dep_ivanov.
* Изменить конфигурационный файл следующим образом:
{
"name": "test_ldap",
...
},
"user": {
...
'''"group": "dn"''',
},
'''"useGroup": true,'''
'''"group": {''''
'''"basedn": "ou=svacer_groups,ou=groups",'''
'''"filter": "(&(objectClass=groupOfNames)(cn=*))",'''
'''"userMember": "member",'''
'''"display":"cn",'''
},
"enabled": true
}

* Перезапустить Svacer
* Убедиться, что возможен вход пользователей, состоящих в группе/группах, и не возможен вход пользователей, не состоящих в группе/группах.
===== Добавление привязки ролей Svacer к группам LDAP =====
* Добавить нужные группы в Svacer. Например admins и users.
* Определиться в каком атрибуте LDAP группы будет хранится имя роли (все сравнения будут чувствительны к регистру). Например, пусть это будет атрибут cn
* Изменить конфигурационный файл следующим образом
{
"name": "test_ldap",
...
"user": {
...
},
''' "useGroup": true, '''
''' "group": { '''
''' "basedn": "ou=svacer_groups,ou=groups", '''
''' "filter": "(&(objectClass=groupOfNames)(cn=*))", '''
''' "userMember": "member", '''
''' "display": "cn", '''
''' "svacerRole": "cn" '''
''' }, '''
"enabled": true
}

* Убедиться, что пользователю назначаются роли, выполнив команду в cli (требуются учетные данные администратора для проверки; по умолчанию admin / admin). Для проверки привязки ролей Svacer к пользователю loginok можно использовать следующую команду:
svacer ldap sync_roles --login loginok --host 127.0.0.1 --port 8080 --user admin --password admin --server test_ldap
Вывод должен быть следующий:
SvacerUserID: 457039b4-4aef-4857-831d-1c080ea154d4
SvacerUserLogin: loginok
LDAPUserDN: cn=loginok,ou=users,dc=example,dc=com
Roles: [314e7571-706c-4463-9280-6a4eee03b42d]
Links: [cn=admins,ou=svacer_groups,ou=groups,dc=example,dc=com -> admins (314e7571-706c-4463-9280-6a4eee03b42d)]
Applied: false

===== Добавление серверов LDAP, работающих по TLS =====
* Изменить конфигурационный файл следующим образом:
{
"name": "test_ldap",
"basedn": "dc=example,dc=com",
"connection": {
"url": "'''ldaps'''://ldap1.example.com:'''636'''",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678",
"ignoreCertCheck": '''true'''
},
"user": {
...
},
...
"enabled": true
}

* Убедиться, что возможен вход пользователем LDAP. Для проверки можно использовать утилиту curl, как указано в примере с основными настройками
* Для проверки сертификата LDAP сервера добавить сертификат CA (например, ldap.crt) в папку с сертификатами (например, /etc/ssl/certs/) и внести следующие изменения в конфигурационный файл:
{
"name": "test_ldap",
"basedn": "dc=example,dc=com",
"connection": {
"url": "ldaps://ldap1.example.com:636",
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678",
"ignoreCertCheck": '''false''',
'''"caCertFiles": ["/etc/ssl/certs/ldap.crt"]'''
},
"user": {
...
},
...
},
"enabled": true
}

* Убедиться, что в логах сервера присутствуют записи вида:
2023-04-24T13:49:49.298+0300 info added 1 ca certs from ldap.crt
* Убедиться, что пользователь LDAP может зайти в систему

===== Добавление резервных серверов LDAP =====
* Добавить в конфигурационный файл резервные сервера в поле mirrors:
{
"name": "test_ldap",
"basedn": "dc=example,dc=com",
"connection": {
"url": "ldaps://ldap1.example.com:636",
'''"mirrors": ["ldaps://ldap2.example.com:636","ldaps://ldap3.example.com:636"],'''
"connectAs": "cn=admin,dc=example,dc=com",
"password": "12345678",
...
},
"user": {
...
},
...
"enabled": true
}

* Проверить, что вход пользователя LDAP в систему возможен
* Изменить значение в URL на любое (чтобы сервер, указанный в URL, был не доступен)
* Перезапустить Svacer
* Убедиться, что вход пользователя LDAP в систему возможен
* Поменять значение в URL на верное

==== Возможные ошибки конфигурации ====
В случае ошибки входа пользователя в систему сервер выводит текстовые сообщения, указывающие на причину ошибки. Наиболее полную информацию об ошибке можно видеть, использовав флаг <code>--debug</code> при запуске сервера Svacer. Логи сервера можно посмотреть в GUI Svacer из под пользователя с правами администратора в разделе '''Settings > Server information'''. Ниже приводится таблица с перечислением возможных ошибок входа пользователя LDAP в систему.

'''Сообщения об ошибках и их возможные причины'''
{| class="wikitable" style="margin:auto"
|-
!Действие !! Сообщение !! Причина !! Решение
|-
| Вход в систему || LDAP server unavailable || 1. Нет соединения с сервером<br/>2. Неверные учетные данные для соединения с сервером || Проверить доступность сервера LDAP с хоста, на котором установлен Svacer. См. утилиту ldapsearch
|-
| Вход в систему || LDAP user is not in group||Пользователь не состоит в заданной конфигурацией группе/группах||Проверить поля user.group, group.filter, group.userMember. В списке групп, полученных с использованием group.filter должна быть хотя бы одна группа, в которую входит пользователь
|-
| Вход в систему || LDAP group not found. Check configuration || Во время поиска групп, подходящих под фильтр, не найдено ни одной группы || Проверить значение поля group.filter и значения basedn, group.basedn
|-
| Вход в систему || LDAP user not allowed or not found || Во время поиска пользователей, подходящих под фильтр, не найдено ни одного пользователя || Проверить значение поля user.filter и значения basedn, user.basedn
|-
| Вход в систему || too much record for user ('%s') found || Поиск пользователя в LDAP с указанными в конфигурации парамтерами дал несколько записей|| Проверить значение поля user.filter и значения basedn, user.basedn. Поиск всегда должен давать одну запись
|-
| Запуск сервера || caCert source [%v] ignored || Ошибка поиска сертификатов по указанному шаблону || Проверить поле connection.caCertFiles конфигурации и убедится, что по указанному в поле шаблону присутствуют сертификаты и к ним есть доступ (проверить права). Все пути должны быть абсолютными
|-
|Запуск сервера || Server [%v] configuration has ignoreCertCheck=false, but no CA certs added. In this case LDAP auth may be impossible || Ошибка конфигурации TLS. В результате обработки значений из поля connection.CaCertFiles не было добавлено ни одного сертификата. Это приводит к тому, что Svacer не может проверить сертификат LDAP сервера, а флаг ignoreCertCheck указан в значении false, что приведет к заведомо ошибочной проверке пользователя || Проверить поле connection.caCertFiles конфигурации и убедится, что по указанному в поле шаблону присутствуют сертификаты и к ним есть доступ (проверить права). Все пути должны быть абсолютными
|}
Для определения проблем с входом пользователей LDAP в систему при первоначальной настройке интеграции, полезно установить флаг trace в значение true. Результатом станет вывод в лог сервера Debug сообщения с указанием этапа обработки запроса и его параметров.

===== Некоторые замечания для пользователей, которые использовали LDAP, начиная с версии Svacer 5-1-0 до 5-2-0 =====

Для пользователей, которые использовали функционал по интеграции с LDAP серверами в период между релизами Svacer 5-1-0 и 5-2-0 (с 30.03.2022 по 15.07.2022) желательная ручная модификации базы данных, так как в ней могут быть ошибки, влияющие на

* механизм тегирования пользователей в комментариях
* механизм уведомления

Если в процессе функционирования сервера наблюдаются сбои в работе указанных механизмов, то следует выполнить следующйи sql запрос в БД, с которой работает Svacer:

<pre class="">insert into users_status (user_id,status)
select id,1 from users
left join users_status us on us.user_id=users.id
where status is null;</pre>

Help:Public API

2025-11-27T09:46:47Z

Chernykov sv: /* Примеры использования фильтров в public api */

== Публичные REST запросы ==

Для работы с сервером через различные приложения реализованы публичные запросы, которые не будут меняться при обновлении самого сервера. Если будут происходить значимые изменения, то запрос будет помечаться как deprecated и создаваться новый такой же запрос с пометкой '''/api/some/request/v2'''.

=== Получение токена ===

Для большинства запросов требуется JWT-токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами:

* Простой способ — POST запрос с basic auth на '''/api/login''', который вернёт JWT-токен в body. Использование данного способа не желательно, так как он может меняться в будущем, а также не всегда правильно обрабатывает спец. символы и кириллицу в логине/пароле. Пример:
<pre>curl -X POST -u admin:admin http://svacer.example.com/api/login</pre>
* Предпочтительный способ — POST запрос на '''/api/public/login''' с передачей данных в теле запроса, как описано [[Help:Public API#public-api-login|ниже]]. Пример:
<pre>curl -X POST -d '{"login": "admin", "password": "admin"}' http://svacer.example.com/api/public/login</pre>

Полученный токен надо добавлять в header всех запросов: <code>Authorization: Bearer <token></code>

=== Базовые публичные запросы ===

{| class="wikitable"
| '''/api/public/login'''
| POST
| <span id="public-api-login" />Аутентификация пользователя. Тело запроса имеет формат JSON и выглядит следующим образом:
{
"auth_type": "string",
"server": "string"
"login": "string",
"password": "string"
}
* auth_type — тип аутентификации: при указании значения "ldap" — аутентификация через LDAP, во всех остальных случаях, или если поле не указано — по внутренней базе пользователей Svacer
* server — имя LDAP-сервера, как он указан в конфигурационном файле LDAP (поле name) при запуске Svacer. Значение поля учитывается, только если <code>"auth_type": "ldap"</code>, в иных случаях его можно не указывать
* login — логин пользователя, обязательное поле
* password — пароль пользователя, обязательное поле
|-
| '''/api/public/help'''
| GET
| Дополнительная информация по public REST API. Работает без авторизации
|-
| '''/api/health'''
| GET
| Проверка доступности сервера. Не требует авторизации. Возвращает статус 200 OK если сервер работает
|}

Описание остальных запросов смотрите в спецификации OpenAPI на вашем сервере Svacer по адресу <code>/api/public/swagger/</code>

Также можете посмотреть на нашем демо-сервере: https://svacer-demo.ispras.ru/api/public/swagger/

== Управление контейнерами ==
См. [[Help:Public API/management/containers]]

== Экспорт, импорт и копирование разметки ==
См. [[Markup2]]

== Примеры использования public REST API ==

=== Получение URL загруженного снимка ===

Этот пример работает только с python3 и не работает при аутентификации в Svacer через LDAP.

Скачайте и распакуйте [[index.php?title=Media:Get link.zip|get_link.zip]]

Запрос:
<pre>python get_link.py --url http://svacer.example.com:8080 --user admin --password admin --project bash</pre>

Ответ:
<pre>http://svacer.example.com:8080/mode/review/project/0fd645aa-8e70-4a4f-b68b-766c4f337bf2/branch/8925df5a-7a98-4f07-bc88-ee4ea5b43813/snapshot/e3367efa-a804-4c05-9a7a-a7cb052bef1d</pre>

=== Примеры использования фильтров в public api ===
Данные фильтры служат только для ограничения вывода некоторых методов в public api. Они являются отдельной сущностью, наравне с глобальными фильтрами и пользовательскими фильтрами. Основное отличие в том, что время их жизни соответствует одному запросу, в котором они заданы.

==== Вспомогательные модули ====

В некоторых примерах API используется фильтр, с помощью которого можно ограничить вывод данных и получить более точные результаты. Для работы с этим фильтром используются следующие классы:

<pre class="">import requests
from requests import auth
from requests.models import HTTPBasicAuth
import json
from dataclasses import dataclass
import sys
import base64

def printerr(text):
#print in stderr and exit
print(f"{text}", file=sys.stderr, flush=True)
exit()

@dataclass
class ProjectFilter:
id: str
name: str

class ProjectFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class BranchFilter:
id: str
name: str

class BranchFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class SnapshotFilter:
id: str
name: str

class SnapshotFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class MarkerFilter:
severity: str
file: str
checker: str
review: str

class MarkerFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class Filter:
project: ProjectFilter
branch: BranchFilter
snapshot: SnapshotFilter
marker: MarkerFilter

class FilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

def CreateFilterParam(filter: Filter):
jsoned = FilterEncoder().encode(filter)
b64ed = base64.b64encode(jsoned.encode("utf-8"))
return b64ed.decode("utf-8")
</pre>
Принцип использования классов следующий:

# Создается экземпляр нужного класса XXXXFilter
# Создается base64 строка на основе объекта пункта 1, которая в дальнейшем передается в url запросе. Для этого используется метод CreateFilterParam()

Например. Для создания фильтра, ограничивающего множество проектов выражением <code>darpa*</code>, можно использовать следующие строчки кода:

<pre class="">f: Filter = Filter(ProjectFilter(id="", name="darpa*"), None, None, None)
param = CreateFilterParam(f)</pre>
Для проекта, ветки и снимка можно указать как имя так и ID. Имя можно указать с использованием регулярного выражения. ID необходимо указать полностью.

==== Метод /api/public/login ====

Данный класс может быть использован для соединения с сервером Svacer. В данном модуле демонстрируется взаимодействие с методом /api/public/login.

<pre class="">import requests

class SvacerClient:
def __init__(self, host, user, password):
"""
Initialize the Svacer client
"""
self.host = host
self.user = user
self.password = password
self.token = None
self.auth_header = None
self.session = requests.Session() # Use session for connection pooling
self.set_auth_token()

def set_auth_token(self):
"""
Get authorization token using /api/public/login and setup in session
"""
try:
response = requests.post(
url=f"{self.host}/api/public/login",
json={
"login":self.user,
"password":self.password,
},
verify=False
)
response.raise_for_status() # Raise an exception for bad status codes
body = response.json()
self.token = body["token"]
self.auth_header = {'Authorization': f'Bearer {self.token}'}

# Set the authorization header in the session
self.session.headers.update(self.auth_header)

return self.token

except requests.exceptions.RequestException as e:
raise Exception(f"Failed to get authentication token: {e}")
except KeyError as e:
raise Exception(f"Token not found in response: {e}")

def post(self, endpoint, data=None, json=None, **kwargs):
"""
Make a POST request to the API

"""
if self.auth_header is None:
raise Exception("No authentication token available. Call get_auth_token() first.")

url = f"{self.host}{endpoint}"

try:
response = self.session.post(
url,
data=data,
json=json,
verify=False,
**kwargs
)
response.raise_for_status()
return response

except requests.exceptions.RequestException as e:
raise Exception(f"POST request failed: {e}")

def get(self, endpoint, params=None, **kwargs):
"""
Make a GET request to the API

"""
if self.auth_header is None:
raise Exception("No authentication token available. Call get_auth_token() first.")

url = f"{self.host}{endpoint}"

try:
response = self.session.get(
url,
params=params,
verify=False,
**kwargs
)
response.raise_for_status()
return response

except requests.exceptions.RequestException as e:
raise Exception(f"GET request failed: {e}")
</pre>
==== Метод /api/public/projects ====

В данном примере выводится в формате json список проектов, имя которых соответствует регулярному выражению <code>darpa*</code>

<pre class="">from filters import *
from svacer import *

cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(ProjectFilter(id="", name="darpa*"), None, None, None)
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects?filters={param}")
print(f"Response: {resp.json()}")</pre>
Результат может быть следующим

<pre class="">[
{
"project":
{
"id": "019abb61-8cd3-7437-957d-aed0c87e603a",
"name": "darpa-clone",
"time": "2025-11-25T14:18:43.79526Z",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000"
},
"branches":
[
{
"id": "019abb61-83b1-7d80-8d23-ce849387bd6e",
"name": "master",
"time": "2025-11-25T14:18:41.457887Z",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000"
}
]
},
{
"project":
{
"id": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"name": "darpa",
"time": "2020-04-03T04:54:13.754864Z",
"created_by": "importer",
"created_by_id": null
},
"branches":
[
{
"id": "ab179fad-c96a-498d-8407-2a3c82719385",
"name": "master",
"time": "2020-04-03T04:54:13.754864Z",
"created_by": "importer",
"created_by_id": null
}
]
}
]</pre>
==== Метод /api/public/projects/{project_id}/branch/{branch_id}/snapshots ====

С помощью данно метода можно получить список снимков указанной ветки. Пример кода для получения снимков с именем <code>ver. 2.7.0*</code>

<pre class="">from filters import *
from svacer import *
import json

def get_snapshots(pr_id, br_id):
cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(None,None,SnapshotFilter(id="",name="ver. 2.7.0*"), None)
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects/{pr_id}/branch/{br_id}/snapshots?filters={param}")
fmt = json.dumps(resp.json())
print(f"Response: {fmt}")

get_snapshots("e6abca1b-23a0-4107-9120-4d8d3596030b","ab179fad-c96a-498d-8407-2a3c82719385")
</pre>
Возможный вывод команды:

<pre class="">[
{
"id": "4242b43a-da44-44ca-9b28-770295b98493",
"name": " ver. 2.7.1 200419 05:55",
"time": "2020-04-03T04:56:49.006218Z",
"link": "http://swarm-mgr.home:10142/mode/review/project/e6abca1b-23a0-4107-9120-4d8d3596030b/branch/ab179fad-c96a-498d-8407-2a3c82719385/snapshot/4242b43a-da44-44ca-9b28-770295b98493",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"import_time": "2019-04-20T04:26:52Z",
"details":
{
"branch": "master",
"branchIDHint": "4d1f1413-c638-4a8b-aa4d-d9fccd8df3e9",
"buildObject": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"dxrIncluded": true,
"host":
{
"hostname": "seroshki",
"user": "sergey"
},
"id": "4242b43a-da44-44ca-9b28-770295b98493",
"importTime": "2019-04-20T04:26:52Z",
"migration-data":
{
"DXR": "ce03cd6d1bd54eac92e227d4184356a90b64b7c1",
"SOURCE_TREE": "0949114563f48d5a2df6e94816b7b1095b6c6540",
"date": "2019-04-20T04:26:52Z",
"description": " ver. 2.7.1 200419 05:55",
"id": "2af625b5faad4083be881135ad1daf6b304e4c99",
"owner": "7a831745d52244db2a4f1692f0c473e61f0f0157",
"parent_id": "0d491fde062e2795a4b38758488a47bf8481d03c",
"sourceData": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"svres": "2af625b5faad4083be881135ad1daf6b304e4c99.svres.gzip",
"type": "snapshot",
"user": "jenkins"
},
"project": "darpa",
"projectIDHint": "354c9c94-7b57-4427-8ce0-c41f1e59e6c2",
"snapshot": " ver. 2.7.1 200419 05:55",
"sourceIncluded": true
}
},
{
"id": "4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"name": " ver. 2.7.1 130419 07:39",
"time": "2020-04-03T04:58:53.618464Z",
"link": "http://swarm-mgr.home:10142/mode/review/project/e6abca1b-23a0-4107-9120-4d8d3596030b/branch/ab179fad-c96a-498d-8407-2a3c82719385/snapshot/4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"import_time": "2019-04-13T04:33:46Z",
"details":
{
"branch": "master",
"branchIDHint": "c472aab7-d53f-496c-9d3d-069c0901d9bb",
"buildObject": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"dxrIncluded": false,
"host":
{
"hostname": "seroshki",
"user": "sergey"
},
"id": "4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"importTime": "2019-04-13T04:33:46Z",
"migration-data":
{
"DXR": "ce03cd6d1bd54eac92e227d4184356a90b64b7c1",
"SOURCE_TREE": "0949114563f48d5a2df6e94816b7b1095b6c6540",
"date": "2019-04-13T04:33:46Z",
"description": " ver. 2.7.1 130419 07:39",
"id": "0d491fde062e2795a4b38758488a47bf8481d03c",
"owner": "7a831745d52244db2a4f1692f0c473e61f0f0157",
"parent_id": "edca1583aa41489d37ae9fb2c348ad066ecd3ab3",
"sourceData": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"svres": "0d491fde062e2795a4b38758488a47bf8481d03c.svres.gzip",
"type": "snapshot",
"user": "jenkins"
},
"project": "darpa",
"projectIDHint": "cf032d99-2efe-4ee0-8db8-ee85ff17b296",
"snapshot": " ver. 2.7.1 130419 07:39",
"sourceIncluded": false
}
}
]</pre>
==== Метод /api/public/projects/{project_id}/branch/{branch_id}/snapshots/{snapshot_id}/fullmarkers ====

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

* трассу ошибки (параметр traces, возможные значения true,false)
* информацию о чекере (параметр checker_info, возможные значения true,false)
* историю разметки (параметр review_history, возможные значения true,false)
* история комментария (параметр comment_history, возможные значения true,false)
* идентификатор пользовательского фильтра (параметр custom_filter)
* фильтр на параметры маркера

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

Пример кода для получения всего множества информации о маркерах, размеченных со статусом <code>Conf*</code>:

<pre class="">def get_markers (pr_id, br_id, snap_id):
cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(None, None, None, MarkerFilter(severity="*",
file="*", checker="*", review="Conf*"))
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects/{pr_id}/branch/{br_id}/snapshots/{snap_id}/fullmarkers?traces=true&checker_info=true&review_history=true&comment_history=true&filters={param}")
fmt = json.dumps(resp.json())
print(f"Response: {fmt}")

get_markers("e6abca1b-23a0-4107-9120-4d8d3596030b","ab179fad-c96a-498d-8407-2a3c82719385","250a4ff1-bfc8-439a-834d-18b62a545d8d") </pre>
Возможный вывод:

<pre class="">[
{
"id": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"file": "/mnt/scratch/sources/darpa-source/challenges/Divelogger2/lib/string.cc",
"function": "_ZN6StringaSERKS_",
"line": 179,
"locID": 1006,
"lang": "CXX",
"tool": "SvEng",
"warnClass": "ASSIGN_NO_CHECK_FOR_THIS",
"mtid": "SvEng.LA.4",
"msg": "Method 'operator=' doesn't check its argument with 'this' pointer.",
"details": "d96c832835f414a119ea8c7575a8926378fd7cf6",
"flags": 0,
"traces": [
{
"role": "declaration",
"locations": [
{
"file": "/mnt/scratch/sources/darpa-source/challenges/Divelogger2/lib/string.cc",
"line": 179,
"col": 0,
"spec": false,
"info": "declaration"
}
]
}
],
"checker_severity": "Normal",
"checker_reliability": "High",
"checker_origin": "builtin",
"review": {
"id": "65796",
"status": "Confirmed",
"severity": "Major",
"action": "Fix required",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:25.216816Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba"
},
"review_history": [
{
"id": "65796",
"status": "Confirmed",
"severity": "Major",
"action": "Fix required",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:25.216816Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "250a4ff1-bfc8-439a-834d-18b62a545d8d",
"markerID": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 300319 07:08",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:40.524836Z"
}
},
{
"id": "65795",
"status": "Confirmed",
"severity": "Major",
"action": "Undecided",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:21.683963Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "250a4ff1-bfc8-439a-834d-18b62a545d8d",
"markerID": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 300319 07:08",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:40.524836Z"
}
},
{
"id": "63495",
"status": "Confirmed",
"severity": "Unspecified",
"action": "Undecided",
"createdBy": "reviewer",
"created_by_id": "077fdd75-b382-4008-97c4-ec6ef8732ccd",
"time": "2022-04-05T11:47:47.026161Z",
"createdFrom": "a94f92f4-4e3e-4071-9f10-aa8e4389dd0a",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "4242b43a-da44-44ca-9b28-770295b98493",
"markerID": "a94f92f4-4e3e-4071-9f10-aa8e4389dd0a",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 200419 05:55",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:49.006218Z"
},
"reviewer_attrs": ["review_master"]
}
],
"comments": [
{
"id": "e3287eb2-9e64-4780-a1c0-22ed9393a226",
"text": "aaaaaaaaa",
"type": "txt",
"ref": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdBy": "admin",
"created_by_id": "",
"invariant": "",
"createTs": "2025-11-25T15:04:11.358138Z",
"updateTs": "2025-11-25T15:04:17.220568Z",
"history": [
{
"id": "019abb8b-4244-7931-81f7-a7d1a4512de0",
"comment_id": "e3287eb2-9e64-4780-a1c0-22ed9393a226",
"comment_ref": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"text": "aaaa",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"create_ts": "2025-11-25T15:04:11.358138Z"
}
]
}
],
"invariant": "1pQ3T5bq6AMYEYJqzFsW+Q"
}
]
</pre>

Changelog

2025-11-26T10:42:48Z

Chernykov sv:

=== Release 12-0-0 ===
* Импорт SARIF теперь более устойчив к пропускам в файле (отсутствие таких полей как location)
* Добавлены переменные окружения <code>SVACER_TIMEOUT_IMPORT_RESULTS</code> для контроля таймаута на ожидание возможности начала операции импорта результатов (формат Go Duration string) и <code>SVACER_NUM_PARALLEL_IMPORTS</code> на ограничение числа параллельных импортов (задачи на импорт выстраиваются в очередь). По умолчанию значения 15 минут и (<code>максимальное число коннектов к БД) / 2</code>. Ограничение необходимы для предотвращения бесконечных ожиданий и зависаний при импорте данных.
* Убраны лишние сообщения об устаревших детекторах при старте сервера или импорте снимков
* В prometheus метрики добавлен ряд показателей размеров object store
* Размер лога сервера показываемого в WEB интерфейсе ограничен. Размер задается переменной окружения SVACER_TAIL_LOG_SIZE (по умолчанию 1Мб). Показывается не последний кусок не более SVACER_TAIL_LOG_SIZE. Сам лог файл может быть не ограничивается в размерах
* ['''Экспериментально'''] Можно указать формат лог файла в JSON посредством параметра <code>svacer-server --log-format=json ...</code>, так же формат может быть указан через переменную окружения <code>SVACER_LOG_FORMAT=json</code>. Опции так же работают для CLI клиента <code>svacer</code>
* При запуске сервера можно указать флаг <code>--force-invariant-refresh</code> для принудительной регенерации инвариантов (может решить проблему с переносом разметки)
* Добавлена переменная окружения SVACER_INV_GEN_JOBS для контроля числа параллельных job-ов при регенарации инвариантов. При ограниченных ресурсах машины рекомендуем ставить значение 2. По умолчанию значение ставится в 70% от <code>runtime.GOMAXPROCS</code>
* Добавлена функциональность по чистке object store при удалении снимков
* ['''Экспериментально'''] Добавлена экспериментальная функциональность по модификации маркеров при импорте результатов и снимков
* Добавлена возможность создания сложных пользовательских фильтров по условиям выраженным предикатом
* Проведена работа по предотвращению зависаний при исчерпывании доступных соединений с PostgreSQL сервером
* Добавлен файл с чексуммой бинарника сервера <code>svacer-server</code> и проверка чексуммы при запуске
* Упростили [[Help:XSvacer:AIAssistant:Deploy|деплой ИИ-ассистента]]: добавили его сервис в docker-compose и deb/rpm пакеты
* Расширили возможности конфигурации при запуске сервера через [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose]: теперь можно включить debug, указать конфиг LDAP и параметр public-url
* Добавлена возможность указания минимального количества снимков, которое необходимо оставлять в ветке, тип очистки и период удаления в [[Help:CLI/cleanup|автоматическом удалении снимков]]
* Добавлена возможность [[Edit markers (command line)|автоматически обрабатывать маркеры]] при импорте данных. Также обработка маркеров доступна через [[Help:UI manual#Работа со снимками|UI]]
* Добавлен флаг <code>diff-url</code> для команды <code>quickdiff</code> в CLI, также как и для команд <code>import</code>, <code>upload</code>, <code>sarif2 import</code> с указанием опции quick-stat. Данный флаг позволяет получать ссылку на diff снимков
* Добавлены предупреждения если в командах <code>import</code>, <code>sarif2 import</code> используются флаги, которые используются флагом <code>upload</code>, но флаг <code>upload</code> не установлен
* Добавлена интеграциия с внешними системами посредством механизма [[Help:Installation#Механизм интеграции с внешними системами посредством Webhook-ов|Webhook-ов]]
* Добавлена [[Help:Installation#Настройка защиты от перебора паролей пользователей|Защита от перебора пароля пользователя]]
* Добавлена возможность задать [[Help:Installation#Настройка парольной политики внутреннего механизма аутентификации Svacer|Парольную политику безопасности]] для пользователей, использующих встроенный мханизм аутентификации Svacer
* Добавлена возможность задать [[Help:Installation#Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer)|вкладку по умолчанию]] для страницы входа в систему
* Исправлена ошибка, приводящая к разрастанию базы данных
* Исправлена ошибка, связанная с невозможностью в ряде случаев использовать механизм подписок

=== Release 11-2-0 ===
22.07.2025

* Исправлены зависания сервера
* Добавлено автоматическое удаление архивов и прочих временных файлов при импорте .svace-dir и SARIF-файлов через REST API

=== Release 11-1-0 ===
08.07.2025

* Команды <code>--project-group, --if-no-group, --autoclean, --autoclean-svace</code> можно использовать в REST API для импорта svace-dir
* При использовании REST API для импорта svace-dir сервер будет автоматически удалять директории <code>.svace-dir</code> и <code>.svacer</code> если не указаны явные опции <code>--autoclean=false, --autoclean-svace=false</code>
* Добавлена опция запуска сервера <code>--classic-inv-mode</code> для включения режима совместимости по генерации инвариантов с версией <= 8.x.x
* Исправлены ошибки в работе <code>--quality-gate</code>, добавлена возможность учета статусов разметки. Добавлена возможность [[Help:Import from Svace#Флаг --baseline|указания baseline]] для сравнений при использовании опции <code>--quality-gate</code>
* Исправлены ошибки при подключении к PostgreSQL в SSL-режиме
* Исправлен ряд ошибок при работе с LDAP
* Команда <code>quickdiff</code> в CLI теперь выдает информацию также о Same и Matched предупреждениях

=== Release 11-0-0 ===
19.05.2025

* Убраны излишние сообщения в логе сервера о login/logout операциях. Они будут выводиться только при запуске сервера с опцией <code>--debug</code>
* Команды CLI <code>svacer sarif *</code> были убраны, для [[Help:Sarif|импорта и экспорта]] следует использовать <code>svacer sarif2 *</code>
* Экспорт SARIF теперь включает все комментарии как отдельные объекты в <code>Properties</code>
* При экспорте в SARIF теперь экспортируются поля <code>Labels, Orig function</code>
* Импорт SARIF теперь корректным образом учитывает relatedLocations и формирует трассу
* Импорт SARIF теперь автоматически импортирует исходники, если они включены в сам SARIF файл
* Добавлена возможность указания [[Help:Sarif#Мэппинг severity|мэппинга severity]] детекторов при импорте из SARIF
* Добавлен механизм указания правил резолвинга путей при импортировании исходного кода вместе с SARIF файлом
* Экспорт исходников из снимка будет доступен только при наличии исходников на сервере
* Добавлены флаги <code>--autoclean</code>, <code>--autoclean-svace</code> в команду <code>svacer import</code> для автоматического удаления <code>.svace-dir / .svacer-dir</code> после успешного импорта и загрузки данных на сервер
* Улучшена поддержка [[OIDC]]
* Улучшена поддержка [[LDAP configuration|LDAP]]
* Добавлена интеграция с хранилищем секретов [[Infisical]]
* Добавлена [[Notifications|служба нотификаций]] пользователей через почтовые сообщения и мессенджер telegram
* Добавлен механизм аутентификации и [[Help:UI manual#Управление токенами доступа|управления]] персональными токенами доступа
* Добавлен механизм упоминания пользователей через специальную конструкцию @login в комментариях к разметке
* В разделе Статистика добавлен дашборд с [[Release notes 11-0-0#Изменения в разделе Статистика|Общей статистикой]], содержащей метрики по последним импортированным снимкам в ветках проектов
* В статистике по активности пользователей добавлена возможность просмотра панели с актуальной информацией о маркере и опция показа только действий с актуальной разметкой
* Большинство CLI команд, работающих с сервером, теперь делают явный logout после завершения
* Svacer при импорте результатов Svace автоматически импортирует файлы <code>*.warn, *.err</code> с предупреждениями от самого анализатора Svace. Автоматический импорт не будет происходить при размере этих файлов более 30Мб (большой размер может свидетельствовать о проблемах в ходе анализа)
* Переменная окружения <code>SVACER_CACHE_DIR</code> теперь учитывается во всех местах (ранее в ряде случаев мог неявно использоваться <code>$HOME/.cache</code>)
* Добавлена возможность [[Help:CLI/cleanup|автоматического удаления снимков]]

=== Release 10-0-1 ===
17.02.2025

* Исправлена ошибка с временной таблицей при обработке планов автомиграции разметки при импорте результатов (ERROR: relation "loaded_review" already exists)

=== Release 10-0-0 ===
16.01.2025

* Множество изменений в UI, смотрите [[Release notes 10-0-0]]
* Сделали [[Help:Installation#rpm|dnf/yum репозиторий]] для RPM-пакетов Svacer
* Реализована возможность [[Markup2|экспорта, импорта и копирования разметки посредством Public REST API и CLI]]
* Реализован дополнительный экспериментальный механизм [[Help:UI manual#Настройка интерфейса|генерации PDF на основе HTML]]. Генерация PDF переведена на асинхронный режим с показом нотификации пользователю
* Добавлена возможность очистки всей разметки и/или комментариев на ветке проекта
* Улучшения функциональности просмотра маркеров в встроенном IDE Theia
* Добавлена функциональность по [[Help:UI manual#Глобальный поиск|глобальному поиску]] маркеров, комментариев и снимков по различным атрибутам
* Добавлена возможность [[Help:UI manual#Просмотр статистики|получения статистики]] по маркерам и активностям пользователей при разметке
* В API fullmarkers добавлен параметр <code>labels: true/false</code> для выгрузки меток маркера
* Реализован Public API для получения/добавления/удаления меток маркеров
* Настройки LDAP и прочие настройки аутентификации добавлены в единый конфигурационный файл
* Добавлена возможность удаления кода из снимка при частичном импорте в Svacer
* Добавлена опция minVersion, maxVersion для TLS при запуске сервера Svacer
* Добавлена поддержка групп проектов при импорте снимков в CLI
* При импорте снимков реализована поддержка автоматического определения пути префикса для переноса разметки
* Исправлен ряд ошибок в импорте и генерации [[Help:Sarif|SARIF]]
* Исправлены ошибки в копировании разметки между ветками, клонировании проектов и веток
* Добавлена возможность отключения бэкграунд задач по очистке мусора
* Добавлено экспериментальное CLI API для просмотра асинхронных задач на генерацию PDF
* Добавлена возможность визуализации производительности сервера на основе [https://github.com/arl/statsviz statsviz]
* Добавлена поддержка относительных путей в svres файле
* Добавлена возможность ожидания завершения операций по очистки мусора при выполнении операций по импорту результатов анализа
* Добавлена поддержка CWE таксономий при экспорте [[Help:Sarif|SARIF]]
* Добавлена переменная окружения SVACER_TOKEN_LIFETIME для управления временем жизни токена аутентификации
* Добавлена переменная окружения SVACER_RESET_ADMIN_PASSWORD для явного указания желаемого пароля при операции по сбросу пароля администратора
* Добавлен [[Notifications|механизм нотификаций пользователей]] о внутренних событиях Svacer (экспериментальный функционал)

=== Release 9-0-2 ===
22.07.2024

* Еще некоторые исправления, связанные с миграцией данных
* Исправлена проблема с навигацией по Go to Definition

=== Release 9-0-1 ===
15.07.2024

* Исправлены ошибки в клонировании проектов, приводящие к размножению записей в некоторых внутренних таблицах
* Различные исправления, связанные с миграцией данных
* Исправлена работа ряда CLI команд с включенным TLS на сервере
* Исправлен ряд ошибок в генерации PDF

=== Release 9-0-0 ===
04.06.2024

* Множество изменений в UI, смотрите [[Release notes 9-0-0]]
* Svacer разделен на два исполняемых файла: <code>svacer-server</code> — сервер и <code>svacer</code> — клиент
* {{Note}}Object store заменен на другую реализацию. Конвертация данных запускается автоматически при апгрейде и требует примерно 2х-2.2х дискового пространства, после конвертации старый object store будет удален. Время конвертации зависит от объема данных и скорости диска
* {{Note}}Изменен [[Help:Match|алгоритм сопоставления предупреждений]]. При старте сервера будет произведена регенерация всех инвариантов во всех ветках. Это может занять продолжительное время (зависит от мощности сервера и объемов данных)
* Добавлена возможность [[Help:Match#Ручное сопоставление предупреждений (экспериментальная возможность)|ручного сопоставления предупреждений]] для переноса разметки
* Добавлена экспериментальная поддержка [[OIDC|OpenID]] протокола для аутентификации
* Добавлена экспериментальная возможность [[Help:CLI#Слияние снимков из CLI (экспериментальная опция)|слияния снимков через CLI]]
* Исправлены баги в [[Help:Sarif|импорте Sarif]], добавлена поддержка импорта с относительными путями к файлам (флаг <code>--base-dir</code>)
* Лог сервера работает в режиме append, прежние данные не затираются
* Добавлена возможность передачи токена аутентификации в клиент Svacer через переменную окружения <code>SVACER_AUTH_TOKEN=token</code>
* Добавлена возможность передачи логина и пароля в клиент Svacer через переменную окружения <code>SVACER_AUTH_CREDS=login:password</code>
* Добавлен public REST endpoint для импорта <code>.svace-dir</code> на стороне сервера
* Добавлена возможность импорта <code>.svace-dir</code> из веб-интерфейса
* Добавлены [[Metrics|метрики]] для Prometheus, доступны при запуске сервера с переменной окружения <code>SVACER_TRACE_OPTIONS=prom_metrics_on</code> на <code>/api/metrics</code>
* Добавлена очистка БД от мусора с возможностью настройки периодичности данной операции через переменную окружения <code>SVACER_GC_PERIOD=val</code> где val — duration в формате <code>hhmmss</code> или [https://en.wikipedia.org/wiki/Cron Cron]
* Добавлена возможность клонирования проектов
* Добавлен импорт <code>*warn, *.err</code> файлов из <code>.svace-dir</code>, которые содержат диагностические сообщения от Svace
* Добавлена возможность [[Help:CLI#Ограничение числа запросов|ограничения числа запросов]] на сервер с указанием параметров в переменной окружения <code>SVACER_SERVER_THROTTLE_PARAMS</code>
* Добавлен шаблон для импорта разметки из кода на Go: <code>DEFAULT_GO</code>
* Добавлена возможность [[Help:CLI#Аутентификация из файла|аутентификации из файла]]
* Исправлены проблемы безопасности
* Добавлена возможность просмотра исходного кода снимка с предупреждениями анализатора во внешней IDE собранной на базе [https://theia-ide.org/ Theia IDE]
* К команде automigrate add в CLI добавлен флаг <code>skip-exist</code>, чтобы при добавлении паттерна, который уже существует, не выдавало ошибки
* К команде upload (import с флагом upload) с указанием флага <code>quality-gate</code> теперь можно добавить флаг <code>quality-gate-verbose</code>. Если его указать, то также будет выведен результат успешных проверок quality-gate
* Улучшения в поддержке протокола LDAP

=== Release 8-0-1 ===
22.01.2024

* Исправлена работа в изолированной от сети среде. Загрузка Web UI больше не требует доступа к публичным CDN
* Добавлена поддержка функций при указании пользовательского фильтра
* Добавлено API для управления пользовательскими фильтрами. Детали и пример использования можно найти здесь: https://gitlab.ispras.ru/svacer-public/api-go-examples/-/tree/master/api-ui-settings
* Исправлено отображение Checker Severity при экспорте в SARIF. Теперь Critical -> error; Major, Normal -> warning; Minor -> note; any other -> warning

=== Release 8-0-0 ===
21.11.2023

* Множество изменений в UI. Смотрите обзор в [[Release notes 8-0-0]]
* Добавлен новый импорт и экспорт из SARIF в command line с поддержкой исходного кода в SARIF файлах и импортом описания детекторов из SARIF
* Добавлены группы проектов
* Переделана модель ролей и доступов. Добавлен CLI для управления ролями и доступами
* Добавлена возможность настройки автопереноса разметки между ветками, в том числе в разных проектах
* Импорт/экспорт снимков включает информацию о детекторах
* Исправлена работа интерфейса с Undefined детекторами (т. е. детекторами, информация о которых отсутствует в Svacer)
* Добавлено экспериментальное API по управлению детекторами и конфигурациями детекторов
* Добавлена очистка исходного кода от Svacer-specific комментариев перед экспортом разметки в код
* Добавлена возможность включения режима обязательного комментария при разметке кода. Комментарий будет сгруппирован с операцией разметки и будет иметь ссылку на нее
* Утилита миграции со старого svace-сервера больше не поддерживается. При необходимости миграции используйте утилиту из прошлых релизов Svacer
* Добавлена Swagger документация на API
* Добавлено хранение истории изменений комментариев
* Опция <code>--pathPrefix</code> поддерживает файлы в JSON формате вида: <code>[{ "prefix": "/some/path", "replace": "/test" }, ...]</code>
* При использовании операции по обновлению <code>pathPrefix</code> на сервере, данные о прежнем <code>pathPrefix</code> запоминаются в мета-информации о снимке
* Добавлена возможность переименования снимков в UI
* Sensitive информация (детали подключения к БД с данными аутентификации) убрана из UI и API
* ОС в docker-образе Svacer обновлена с Ubuntu 18 до Ubuntu 22
* Улучшена логика автоопределения портов и протоколов при соединении с сервером из Svacer CLI

=== Release 7-0-1 ===
23.05.2023

* Исправлена проблема с фильтрацией предупреждений для C# проектов

=== Release 7-0-0 ===
16.05.2023

* Убрана зависимость от PostgreSQL из .deb и .rpm пакетов, чтобы проще было ставить Svacer только как клиент
* Сделан пакет для Windows (.msi) и документация по установке и запуску на Windows
* Теперь, если при svacer import и svacer sarif не указан путь к проекту, им считается текущая директория
* Информация о разметке и блокировках теперь обновляется автоматически при изменении в другом браузере (табе) или другим пользователем
* UI для пользовательских фильтров улучшен и перенесен в правую верхнюю часть экрана
* UI для выбора проекта, ветки и снимка теперь находится на одном уровне
* Улучшен UI для режима сравнения снимков
* Добавлена возможность работать одновременно с несколькими открытыми файлами в режиме Code, это поведение можно изменить в настройках профиля пользователя
* В левой навигационной панели детекторы теперь по умолчанию группируются по серьезности, это поведение можно изменить в настройках профиля пользователя
* Профиль текущего пользователя теперь можно смотреть/редактировать только через меню в правом верхнем углу
* Добавлена возможность копирования в системном логе и журнале
* Для пользователя теперь запоминается последний контекст (проект/ветка/снимок), с которым он работал, он автоматически открывается при старте новой сессии
* Групповая разметка теперь делается единой транзакцией, в случае ошибок или отмены все изменения откатываются
* Добавлено предупреждение при использовании некорректных путей при использовании REST API с префиксом /api
* Поддержка указания паролей из файла или pipe-а при использование Svacer CLI
* Добавлена поддержка multi-tab code view для режима просмотра кода объекта сборки
* Добавлена поддержка сохранения информации об удаленных детекторах при загрузке информации о детекторах из новой версии Svace
* Исправлен импорт результатов анализа, если сборка проводилась с опцией --disable-dxr
* Исправлены проблемы при импорте и прикреплении нескольких файлов к снимку
* Исправлены ошибки с входом в систему пользователей LDAP (специальные символы в пароле, вход по атрибуту mail)
* Добавлена возможность использования резервных серверов LDAP
* Добавлена возможность автоматического назначения пользователям LDAP роли Svacer, в зависимости от принадлежности пользователя к LDAP группе
* Добавлены новые public запросы на получение маркеров/снимков/проектов с учетом заданных параметров фильтрации
* Добавлена поддержка TLS при работе сервера по протоколам HTTP и gRPC
* Добавлена возможность загрузки статистики по общему количеству предупреждений и по количеству размеченных предупреждений для проектов и веток через REST API
* Добавлена вкладка выбора проектов в расширении VSCode
* Убрана возможность использовать всплывающее окно в VScode для добавления/редактирования/удаления комментариев, установки ревью-статусов, локов и т.д.

=== Release 6-0-3 ===
25.01.2023

* RPM-пакет теперь при сборке упаковывается в gzip вместо zstd для обратной совместимости со старыми дистрибутивами
* Если short url некорректен, то Svacer теперь будет возвращать корректный http error NotFound
* Если путь к лог файлу явно не указан, то svacer.log будет создаваться во временной директории. Это решает проблемы при запуске Svacer из директорий с запретом на запись. Путь к лог файлу будет печататься в stdout
* Лог файлы не будут создаваться, когда используется опция --help
* Исправлены проблемы при миграции схемы данных, когда в PostgreSQL используется SSL подключение
* Добавлены описания детекторов из последнего релиза Svace, которые были пропущены в релизе 6-0-2
* Исправлена работа Svacer за proxy-сервером, где выставляется Header "X-Content-Type-Options nosniff"
* Добавлены кнопки для скачивания системного лога и журнала из web-интерфейса
* Поправлен ряд ошибок валидации схемы при экспорте в SARIF
* Исправлено поведение при наличии нескольких хуков в конфигурационном файле
* В информацию о маркере для хуков добавлены checker severity и reliability
* Исправлен случайный порядок URL для маркеров при использовании public API для получения URL-ов
* На главную страницу добавлена кнопка "Помощь", которая открывает документацию
* При использовании команд навигации в режиме "Browse code" текущий файл теперь корректно подсвечивается в дереве файлов
* В диалоге групповой разметки убран индикатор изменений в виде кружочка, наличие изменений можно определить по активности кнопок "Apply" и "Reset"
* Кнопка обновления в верхнем меню теперь корректно обновляет информацию на странице Settings/Project
* Различные небольшие исправления в пользовательском интерфейсе

=== Release 6-0-2 ===
16.12.2022

* Исправлена проблема в UI с сохраненными пользовательскими фильтрами

=== Release 6-0-1 ===
13.12.2022

* Добавлено описание ряда детекторов, которые есть в последнем релизе Svace 3.3.2 но были пропущены в Svacer
* Исправлено вылетание в Login Screen при удалении нотификации из панели нотификаций
* Исправлено появление белого экрана при клике на детектор, информация о котором отсутствует
* Ряд различных небольших исправлений в UI
* Промежуточное хранилище будет очищаться по умолчанию при использовании команды import

=== Release 6-0-0 ===
30.11.2022

* Добавлено копирование комментариев при копировании разметки
* Комментарии добавлены к отчету в формате csv
* Добавлена возможность вводить пароль с клавиатуры для консольных команд
* Добавлена возможность импортировать разметку из объекта сборки (из ранее загруженных данных)
* Добавлена возможность импортировать разметку сразу после загрузки на сервер (опция для команды svacer upload)
* Добавлена возможность загружать исходный код не из папки .svace-dir
* Добавлена возможность бэкапа и восстановление объектного хранилища в сервер PostgresSQL
* Добавлена возможность создания отчета по проекту в формате PDF через интерфейс командной строки и посредством REST API
* Добавлена возможность подавления предупреждений через inline комментарии в коде
* Добавлена возможность подавления предупреждений по идентификатору предупреждения через command line и REST API
* Добавлена возможность ассоциировать организацию с пользователем и реестр организаций
* Добавлена фильтрация списка комментариев по пользователю в правой панели веб-интерфейса
* Добавлен поиск пользователей по его атрибутам в панели управления пользователями
* Добавлена возможность заполнения данных профиля LDAP пользователя данными, полученными от LDAP сервера
* Добавлена возможность прикреплять файлы к снимкам при импорте результатов (данные файлы составляют часть экспортируемых данных при экспорте снимков)
* Добавлена возможность ассоциировать пользовательские атрибуты типа "строка" или массив строк со снимком при импорте данных (данные атрибуты составляют часть экспортируемых данных при экспорте снимков)
* Добавлены command line операции по получению прикрепленных файлов и пользовательских атрибутов со снимков
* Добавлена возможность группового добавления комментариев
* Добавлена возможность указания сетевого интерфейса для работы WEB и GRPC серверов
* Добавлен вывод краткой статистики по загруженному снимку при команде upload. Поддерживается текстовой и JSON форматы вывода
* Существенно расширены возможности по интеграции Visual Studio Code с сервером Svacer
* Добавлен флаг --git в команду import. При наличии такого флага, ищется ближайший git репозиторий содержащий .svace-dir и при наличии такого - используется путь к гит репозиторию для замены путей на префикс .build.
* Portable PostgreSQL больше не входит в поставку. Вместо него поставляется docker-compose.yml файл для запуска PostgreSQL в докер-контейнере
* Добавлено больше данных и информации об ошибках в вывод команды svacer import
* Изменение Public API: добавлена точка входа /api/public/login
* Операции по импорту и экспорту снимков доступны теперь обычным пользователям (не администраторам) при использовании command line интерфейса
* Операция по экспорту снимков доступна обычному пользователю из веб-интерфейса (импорт все еще требует роль администратора для веб-интерфейса)
* Операции по экспорту снимков переведены на асинхронный режим. Нотификация о готовности будет показана пользователю и доступна в панели нотификаций
* Обновлено описание детекторов в соответствии с релизом Svace 3.3.2
* Исправлена ошибка обработки корневых сертификатов при подключении к LDAP серверу по протоколу ldaps
* Исправлено ошибочное создание дубликатов локальных учетных записей LDAP пользователей (case sensitive login)
* Различные исправления в пользовательском интерфейсе с целью оптимизации производительности
* Добавлены пропущенные проверки ролей при работе с веб-интерфейсом
* Svacer больше не создает временные файлы в директории с исполняемым файлом
* Устаранены задержки при удалении веток и проектов

Changelog

2025-11-26T10:41:40Z

Chernykov sv:

=== Release 12-0-0 ===
* Импорт SARIF теперь более устойчив к пропускам в файле (отсутствие таких полей как location)
* Добавлены переменные окружения <code>SVACER_TIMEOUT_IMPORT_RESULTS</code> для контроля таймаута на ожидание возможности начала операции импорта результатов (формат Go Duration string) и <code>SVACER_NUM_PARALLEL_IMPORTS</code> на ограничение числа параллельных импортов (задачи на импорт выстраиваются в очередь). По умолчанию значения 15 минут и (<code>максимальное число коннектов к БД) / 2</code>. Ограничение необходимы для предотвращения бесконечных ожиданий и зависаний при импорте данных.
* Убраны лишние сообщения об устаревших детекторах при старте сервера или импорте снимков
* В prometheus метрики добавлен ряд показателей размеров object store
* Размер лога сервера показываемого в WEB интерфейсе ограничен. Размер задается переменной окружения SVACER_TAIL_LOG_SIZE (по умолчанию 1Мб). Показывается не последний кусок не более SVACER_TAIL_LOG_SIZE. Сам лог файл может быть не ограничивается в размерах
* ['''Экспериментально'''] Можно указать формат лог файла в JSON посредством параметра <code>svacer-server --log-format=json ...</code>, так же формат может быть указан через переменную окружения <code>SVACER_LOG_FORMAT=json</code>. Опции так же работают для CLI клиента <code>svacer</code>
* При запуске сервера можно указать флаг <code>--force-invariant-refresh</code> для принудительной регенерации инвариантов (может решить проблему с переносом разметки)
* Добавлена переменная окружения SVACER_INV_GEN_JOBS для контроля числа параллельных job-ов при регенарации инвариантов. При ограниченных ресурсах машины рекомендуем ставить значение 2. По умолчанию значение ставится в 70% от <code>runtime.GOMAXPROCS</code>
* Добавлена функциональность по чистке object store при удалении снимков
* ['''Экспериментально'''] Добавлена экспериментальная функциональность по модификации маркеров при импорте результатов и снимков
* Добавлена возможность создания сложных пользовательских фильтров по условиям выраженным предикатом
* Проведена работа по предотвращению зависаний при исчерпывании доступных соединений с PostgreSQL сервером
* Добавлен файл с чексуммой бинарника сервера <code>svacer-server</code> и проверка чексуммы при запуске
* Упростили [[Help:XSvacer:AIAssistant:Deploy|деплой ИИ-ассистента]]: добавили его сервис в docker-compose и deb/rpm пакеты
* Расширили возможности конфигурации при запуске сервера через [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose]: теперь можно включить debug, указать конфиг LDAP и параметр public-url
* Добавлена возможность указания минимального количества снимков, которое необходимо оставлять в ветке, тип очистки и период удаления в [[Help:CLI/cleanup|автоматическом удалении снимков]]
* Добавлена возможность [[Edit markers (command line)|автоматически обрабатывать маркеры]] при импорте данных. Также обработка маркеров доступна через [[Help:UI manual#Работа со снимками|UI]]
* Добавлен флаг <code>diff-url</code> для команды <code>quickdiff</code> в CLI, также как и для команд <code>import</code>, <code>upload</code>, <code>sarif2 import</code> с указанием опции quick-stat. Данный флаг позволяет получать ссылку на diff снимков
* Добавлены предупреждения если в командах <code>import</code>, <code>sarif2 import</code> используются флаги, которые используются флагом <code>upload</code>, но флаг <code>upload</code> не установлен
* Добавлена интеграциия с внешними системами посредством механизма [[Help:Installation#Механизм интеграции с внешними системами посредством Webhook-ов|Webhook-ов]]
* Добавлена [[Help:Installation#Настройка защиты от перебора паролей пользователей|Защита от перебора пароля пользователя]]
* Добавлена возможность задать [[Help:Installation#Настройка парольной политики внутреннего механизма аутентификации Svacer|Парольную политику безопасности]] для пользователей, использующих встроенный мханизм аутентификации Svacer
* Добавлена возможность задать [[Help:Installation#Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer)|вкладку по умолчанию]] для страницы входа в систему
* Исправлена ошибка, приводящая к разрастанию базы данных

=== Release 11-2-0 ===
22.07.2025

* Исправлены зависания сервера
* Добавлено автоматическое удаление архивов и прочих временных файлов при импорте .svace-dir и SARIF-файлов через REST API

=== Release 11-1-0 ===
08.07.2025

* Команды <code>--project-group, --if-no-group, --autoclean, --autoclean-svace</code> можно использовать в REST API для импорта svace-dir
* При использовании REST API для импорта svace-dir сервер будет автоматически удалять директории <code>.svace-dir</code> и <code>.svacer</code> если не указаны явные опции <code>--autoclean=false, --autoclean-svace=false</code>
* Добавлена опция запуска сервера <code>--classic-inv-mode</code> для включения режима совместимости по генерации инвариантов с версией <= 8.x.x
* Исправлены ошибки в работе <code>--quality-gate</code>, добавлена возможность учета статусов разметки. Добавлена возможность [[Help:Import from Svace#Флаг --baseline|указания baseline]] для сравнений при использовании опции <code>--quality-gate</code>
* Исправлены ошибки при подключении к PostgreSQL в SSL-режиме
* Исправлен ряд ошибок при работе с LDAP
* Команда <code>quickdiff</code> в CLI теперь выдает информацию также о Same и Matched предупреждениях

=== Release 11-0-0 ===
19.05.2025

* Убраны излишние сообщения в логе сервера о login/logout операциях. Они будут выводиться только при запуске сервера с опцией <code>--debug</code>
* Команды CLI <code>svacer sarif *</code> были убраны, для [[Help:Sarif|импорта и экспорта]] следует использовать <code>svacer sarif2 *</code>
* Экспорт SARIF теперь включает все комментарии как отдельные объекты в <code>Properties</code>
* При экспорте в SARIF теперь экспортируются поля <code>Labels, Orig function</code>
* Импорт SARIF теперь корректным образом учитывает relatedLocations и формирует трассу
* Импорт SARIF теперь автоматически импортирует исходники, если они включены в сам SARIF файл
* Добавлена возможность указания [[Help:Sarif#Мэппинг severity|мэппинга severity]] детекторов при импорте из SARIF
* Добавлен механизм указания правил резолвинга путей при импортировании исходного кода вместе с SARIF файлом
* Экспорт исходников из снимка будет доступен только при наличии исходников на сервере
* Добавлены флаги <code>--autoclean</code>, <code>--autoclean-svace</code> в команду <code>svacer import</code> для автоматического удаления <code>.svace-dir / .svacer-dir</code> после успешного импорта и загрузки данных на сервер
* Улучшена поддержка [[OIDC]]
* Улучшена поддержка [[LDAP configuration|LDAP]]
* Добавлена интеграция с хранилищем секретов [[Infisical]]
* Добавлена [[Notifications|служба нотификаций]] пользователей через почтовые сообщения и мессенджер telegram
* Добавлен механизм аутентификации и [[Help:UI manual#Управление токенами доступа|управления]] персональными токенами доступа
* Добавлен механизм упоминания пользователей через специальную конструкцию @login в комментариях к разметке
* В разделе Статистика добавлен дашборд с [[Release notes 11-0-0#Изменения в разделе Статистика|Общей статистикой]], содержащей метрики по последним импортированным снимкам в ветках проектов
* В статистике по активности пользователей добавлена возможность просмотра панели с актуальной информацией о маркере и опция показа только действий с актуальной разметкой
* Большинство CLI команд, работающих с сервером, теперь делают явный logout после завершения
* Svacer при импорте результатов Svace автоматически импортирует файлы <code>*.warn, *.err</code> с предупреждениями от самого анализатора Svace. Автоматический импорт не будет происходить при размере этих файлов более 30Мб (большой размер может свидетельствовать о проблемах в ходе анализа)
* Переменная окружения <code>SVACER_CACHE_DIR</code> теперь учитывается во всех местах (ранее в ряде случаев мог неявно использоваться <code>$HOME/.cache</code>)
* Добавлена возможность [[Help:CLI/cleanup|автоматического удаления снимков]]

=== Release 10-0-1 ===
17.02.2025

* Исправлена ошибка с временной таблицей при обработке планов автомиграции разметки при импорте результатов (ERROR: relation "loaded_review" already exists)

=== Release 10-0-0 ===
16.01.2025

* Множество изменений в UI, смотрите [[Release notes 10-0-0]]
* Сделали [[Help:Installation#rpm|dnf/yum репозиторий]] для RPM-пакетов Svacer
* Реализована возможность [[Markup2|экспорта, импорта и копирования разметки посредством Public REST API и CLI]]
* Реализован дополнительный экспериментальный механизм [[Help:UI manual#Настройка интерфейса|генерации PDF на основе HTML]]. Генерация PDF переведена на асинхронный режим с показом нотификации пользователю
* Добавлена возможность очистки всей разметки и/или комментариев на ветке проекта
* Улучшения функциональности просмотра маркеров в встроенном IDE Theia
* Добавлена функциональность по [[Help:UI manual#Глобальный поиск|глобальному поиску]] маркеров, комментариев и снимков по различным атрибутам
* Добавлена возможность [[Help:UI manual#Просмотр статистики|получения статистики]] по маркерам и активностям пользователей при разметке
* В API fullmarkers добавлен параметр <code>labels: true/false</code> для выгрузки меток маркера
* Реализован Public API для получения/добавления/удаления меток маркеров
* Настройки LDAP и прочие настройки аутентификации добавлены в единый конфигурационный файл
* Добавлена возможность удаления кода из снимка при частичном импорте в Svacer
* Добавлена опция minVersion, maxVersion для TLS при запуске сервера Svacer
* Добавлена поддержка групп проектов при импорте снимков в CLI
* При импорте снимков реализована поддержка автоматического определения пути префикса для переноса разметки
* Исправлен ряд ошибок в импорте и генерации [[Help:Sarif|SARIF]]
* Исправлены ошибки в копировании разметки между ветками, клонировании проектов и веток
* Добавлена возможность отключения бэкграунд задач по очистке мусора
* Добавлено экспериментальное CLI API для просмотра асинхронных задач на генерацию PDF
* Добавлена возможность визуализации производительности сервера на основе [https://github.com/arl/statsviz statsviz]
* Добавлена поддержка относительных путей в svres файле
* Добавлена возможность ожидания завершения операций по очистки мусора при выполнении операций по импорту результатов анализа
* Добавлена поддержка CWE таксономий при экспорте [[Help:Sarif|SARIF]]
* Добавлена переменная окружения SVACER_TOKEN_LIFETIME для управления временем жизни токена аутентификации
* Добавлена переменная окружения SVACER_RESET_ADMIN_PASSWORD для явного указания желаемого пароля при операции по сбросу пароля администратора
* Добавлен [[Notifications|механизм нотификаций пользователей]] о внутренних событиях Svacer (экспериментальный функционал)

=== Release 9-0-2 ===
22.07.2024

* Еще некоторые исправления, связанные с миграцией данных
* Исправлена проблема с навигацией по Go to Definition

=== Release 9-0-1 ===
15.07.2024

* Исправлены ошибки в клонировании проектов, приводящие к размножению записей в некоторых внутренних таблицах
* Различные исправления, связанные с миграцией данных
* Исправлена работа ряда CLI команд с включенным TLS на сервере
* Исправлен ряд ошибок в генерации PDF

=== Release 9-0-0 ===
04.06.2024

* Множество изменений в UI, смотрите [[Release notes 9-0-0]]
* Svacer разделен на два исполняемых файла: <code>svacer-server</code> — сервер и <code>svacer</code> — клиент
* {{Note}}Object store заменен на другую реализацию. Конвертация данных запускается автоматически при апгрейде и требует примерно 2х-2.2х дискового пространства, после конвертации старый object store будет удален. Время конвертации зависит от объема данных и скорости диска
* {{Note}}Изменен [[Help:Match|алгоритм сопоставления предупреждений]]. При старте сервера будет произведена регенерация всех инвариантов во всех ветках. Это может занять продолжительное время (зависит от мощности сервера и объемов данных)
* Добавлена возможность [[Help:Match#Ручное сопоставление предупреждений (экспериментальная возможность)|ручного сопоставления предупреждений]] для переноса разметки
* Добавлена экспериментальная поддержка [[OIDC|OpenID]] протокола для аутентификации
* Добавлена экспериментальная возможность [[Help:CLI#Слияние снимков из CLI (экспериментальная опция)|слияния снимков через CLI]]
* Исправлены баги в [[Help:Sarif|импорте Sarif]], добавлена поддержка импорта с относительными путями к файлам (флаг <code>--base-dir</code>)
* Лог сервера работает в режиме append, прежние данные не затираются
* Добавлена возможность передачи токена аутентификации в клиент Svacer через переменную окружения <code>SVACER_AUTH_TOKEN=token</code>
* Добавлена возможность передачи логина и пароля в клиент Svacer через переменную окружения <code>SVACER_AUTH_CREDS=login:password</code>
* Добавлен public REST endpoint для импорта <code>.svace-dir</code> на стороне сервера
* Добавлена возможность импорта <code>.svace-dir</code> из веб-интерфейса
* Добавлены [[Metrics|метрики]] для Prometheus, доступны при запуске сервера с переменной окружения <code>SVACER_TRACE_OPTIONS=prom_metrics_on</code> на <code>/api/metrics</code>
* Добавлена очистка БД от мусора с возможностью настройки периодичности данной операции через переменную окружения <code>SVACER_GC_PERIOD=val</code> где val — duration в формате <code>hhmmss</code> или [https://en.wikipedia.org/wiki/Cron Cron]
* Добавлена возможность клонирования проектов
* Добавлен импорт <code>*warn, *.err</code> файлов из <code>.svace-dir</code>, которые содержат диагностические сообщения от Svace
* Добавлена возможность [[Help:CLI#Ограничение числа запросов|ограничения числа запросов]] на сервер с указанием параметров в переменной окружения <code>SVACER_SERVER_THROTTLE_PARAMS</code>
* Добавлен шаблон для импорта разметки из кода на Go: <code>DEFAULT_GO</code>
* Добавлена возможность [[Help:CLI#Аутентификация из файла|аутентификации из файла]]
* Исправлены проблемы безопасности
* Добавлена возможность просмотра исходного кода снимка с предупреждениями анализатора во внешней IDE собранной на базе [https://theia-ide.org/ Theia IDE]
* К команде automigrate add в CLI добавлен флаг <code>skip-exist</code>, чтобы при добавлении паттерна, который уже существует, не выдавало ошибки
* К команде upload (import с флагом upload) с указанием флага <code>quality-gate</code> теперь можно добавить флаг <code>quality-gate-verbose</code>. Если его указать, то также будет выведен результат успешных проверок quality-gate
* Улучшения в поддержке протокола LDAP

=== Release 8-0-1 ===
22.01.2024

* Исправлена работа в изолированной от сети среде. Загрузка Web UI больше не требует доступа к публичным CDN
* Добавлена поддержка функций при указании пользовательского фильтра
* Добавлено API для управления пользовательскими фильтрами. Детали и пример использования можно найти здесь: https://gitlab.ispras.ru/svacer-public/api-go-examples/-/tree/master/api-ui-settings
* Исправлено отображение Checker Severity при экспорте в SARIF. Теперь Critical -> error; Major, Normal -> warning; Minor -> note; any other -> warning

=== Release 8-0-0 ===
21.11.2023

* Множество изменений в UI. Смотрите обзор в [[Release notes 8-0-0]]
* Добавлен новый импорт и экспорт из SARIF в command line с поддержкой исходного кода в SARIF файлах и импортом описания детекторов из SARIF
* Добавлены группы проектов
* Переделана модель ролей и доступов. Добавлен CLI для управления ролями и доступами
* Добавлена возможность настройки автопереноса разметки между ветками, в том числе в разных проектах
* Импорт/экспорт снимков включает информацию о детекторах
* Исправлена работа интерфейса с Undefined детекторами (т. е. детекторами, информация о которых отсутствует в Svacer)
* Добавлено экспериментальное API по управлению детекторами и конфигурациями детекторов
* Добавлена очистка исходного кода от Svacer-specific комментариев перед экспортом разметки в код
* Добавлена возможность включения режима обязательного комментария при разметке кода. Комментарий будет сгруппирован с операцией разметки и будет иметь ссылку на нее
* Утилита миграции со старого svace-сервера больше не поддерживается. При необходимости миграции используйте утилиту из прошлых релизов Svacer
* Добавлена Swagger документация на API
* Добавлено хранение истории изменений комментариев
* Опция <code>--pathPrefix</code> поддерживает файлы в JSON формате вида: <code>[{ "prefix": "/some/path", "replace": "/test" }, ...]</code>
* При использовании операции по обновлению <code>pathPrefix</code> на сервере, данные о прежнем <code>pathPrefix</code> запоминаются в мета-информации о снимке
* Добавлена возможность переименования снимков в UI
* Sensitive информация (детали подключения к БД с данными аутентификации) убрана из UI и API
* ОС в docker-образе Svacer обновлена с Ubuntu 18 до Ubuntu 22
* Улучшена логика автоопределения портов и протоколов при соединении с сервером из Svacer CLI

=== Release 7-0-1 ===
23.05.2023

* Исправлена проблема с фильтрацией предупреждений для C# проектов

=== Release 7-0-0 ===
16.05.2023

* Убрана зависимость от PostgreSQL из .deb и .rpm пакетов, чтобы проще было ставить Svacer только как клиент
* Сделан пакет для Windows (.msi) и документация по установке и запуску на Windows
* Теперь, если при svacer import и svacer sarif не указан путь к проекту, им считается текущая директория
* Информация о разметке и блокировках теперь обновляется автоматически при изменении в другом браузере (табе) или другим пользователем
* UI для пользовательских фильтров улучшен и перенесен в правую верхнюю часть экрана
* UI для выбора проекта, ветки и снимка теперь находится на одном уровне
* Улучшен UI для режима сравнения снимков
* Добавлена возможность работать одновременно с несколькими открытыми файлами в режиме Code, это поведение можно изменить в настройках профиля пользователя
* В левой навигационной панели детекторы теперь по умолчанию группируются по серьезности, это поведение можно изменить в настройках профиля пользователя
* Профиль текущего пользователя теперь можно смотреть/редактировать только через меню в правом верхнем углу
* Добавлена возможность копирования в системном логе и журнале
* Для пользователя теперь запоминается последний контекст (проект/ветка/снимок), с которым он работал, он автоматически открывается при старте новой сессии
* Групповая разметка теперь делается единой транзакцией, в случае ошибок или отмены все изменения откатываются
* Добавлено предупреждение при использовании некорректных путей при использовании REST API с префиксом /api
* Поддержка указания паролей из файла или pipe-а при использование Svacer CLI
* Добавлена поддержка multi-tab code view для режима просмотра кода объекта сборки
* Добавлена поддержка сохранения информации об удаленных детекторах при загрузке информации о детекторах из новой версии Svace
* Исправлен импорт результатов анализа, если сборка проводилась с опцией --disable-dxr
* Исправлены проблемы при импорте и прикреплении нескольких файлов к снимку
* Исправлены ошибки с входом в систему пользователей LDAP (специальные символы в пароле, вход по атрибуту mail)
* Добавлена возможность использования резервных серверов LDAP
* Добавлена возможность автоматического назначения пользователям LDAP роли Svacer, в зависимости от принадлежности пользователя к LDAP группе
* Добавлены новые public запросы на получение маркеров/снимков/проектов с учетом заданных параметров фильтрации
* Добавлена поддержка TLS при работе сервера по протоколам HTTP и gRPC
* Добавлена возможность загрузки статистики по общему количеству предупреждений и по количеству размеченных предупреждений для проектов и веток через REST API
* Добавлена вкладка выбора проектов в расширении VSCode
* Убрана возможность использовать всплывающее окно в VScode для добавления/редактирования/удаления комментариев, установки ревью-статусов, локов и т.д.

=== Release 6-0-3 ===
25.01.2023

* RPM-пакет теперь при сборке упаковывается в gzip вместо zstd для обратной совместимости со старыми дистрибутивами
* Если short url некорректен, то Svacer теперь будет возвращать корректный http error NotFound
* Если путь к лог файлу явно не указан, то svacer.log будет создаваться во временной директории. Это решает проблемы при запуске Svacer из директорий с запретом на запись. Путь к лог файлу будет печататься в stdout
* Лог файлы не будут создаваться, когда используется опция --help
* Исправлены проблемы при миграции схемы данных, когда в PostgreSQL используется SSL подключение
* Добавлены описания детекторов из последнего релиза Svace, которые были пропущены в релизе 6-0-2
* Исправлена работа Svacer за proxy-сервером, где выставляется Header "X-Content-Type-Options nosniff"
* Добавлены кнопки для скачивания системного лога и журнала из web-интерфейса
* Поправлен ряд ошибок валидации схемы при экспорте в SARIF
* Исправлено поведение при наличии нескольких хуков в конфигурационном файле
* В информацию о маркере для хуков добавлены checker severity и reliability
* Исправлен случайный порядок URL для маркеров при использовании public API для получения URL-ов
* На главную страницу добавлена кнопка "Помощь", которая открывает документацию
* При использовании команд навигации в режиме "Browse code" текущий файл теперь корректно подсвечивается в дереве файлов
* В диалоге групповой разметки убран индикатор изменений в виде кружочка, наличие изменений можно определить по активности кнопок "Apply" и "Reset"
* Кнопка обновления в верхнем меню теперь корректно обновляет информацию на странице Settings/Project
* Различные небольшие исправления в пользовательском интерфейсе

=== Release 6-0-2 ===
16.12.2022

* Исправлена проблема в UI с сохраненными пользовательскими фильтрами

=== Release 6-0-1 ===
13.12.2022

* Добавлено описание ряда детекторов, которые есть в последнем релизе Svace 3.3.2 но были пропущены в Svacer
* Исправлено вылетание в Login Screen при удалении нотификации из панели нотификаций
* Исправлено появление белого экрана при клике на детектор, информация о котором отсутствует
* Ряд различных небольших исправлений в UI
* Промежуточное хранилище будет очищаться по умолчанию при использовании команды import

=== Release 6-0-0 ===
30.11.2022

* Добавлено копирование комментариев при копировании разметки
* Комментарии добавлены к отчету в формате csv
* Добавлена возможность вводить пароль с клавиатуры для консольных команд
* Добавлена возможность импортировать разметку из объекта сборки (из ранее загруженных данных)
* Добавлена возможность импортировать разметку сразу после загрузки на сервер (опция для команды svacer upload)
* Добавлена возможность загружать исходный код не из папки .svace-dir
* Добавлена возможность бэкапа и восстановление объектного хранилища в сервер PostgresSQL
* Добавлена возможность создания отчета по проекту в формате PDF через интерфейс командной строки и посредством REST API
* Добавлена возможность подавления предупреждений через inline комментарии в коде
* Добавлена возможность подавления предупреждений по идентификатору предупреждения через command line и REST API
* Добавлена возможность ассоциировать организацию с пользователем и реестр организаций
* Добавлена фильтрация списка комментариев по пользователю в правой панели веб-интерфейса
* Добавлен поиск пользователей по его атрибутам в панели управления пользователями
* Добавлена возможность заполнения данных профиля LDAP пользователя данными, полученными от LDAP сервера
* Добавлена возможность прикреплять файлы к снимкам при импорте результатов (данные файлы составляют часть экспортируемых данных при экспорте снимков)
* Добавлена возможность ассоциировать пользовательские атрибуты типа "строка" или массив строк со снимком при импорте данных (данные атрибуты составляют часть экспортируемых данных при экспорте снимков)
* Добавлены command line операции по получению прикрепленных файлов и пользовательских атрибутов со снимков
* Добавлена возможность группового добавления комментариев
* Добавлена возможность указания сетевого интерфейса для работы WEB и GRPC серверов
* Добавлен вывод краткой статистики по загруженному снимку при команде upload. Поддерживается текстовой и JSON форматы вывода
* Существенно расширены возможности по интеграции Visual Studio Code с сервером Svacer
* Добавлен флаг --git в команду import. При наличии такого флага, ищется ближайший git репозиторий содержащий .svace-dir и при наличии такого - используется путь к гит репозиторию для замены путей на префикс .build.
* Portable PostgreSQL больше не входит в поставку. Вместо него поставляется docker-compose.yml файл для запуска PostgreSQL в докер-контейнере
* Добавлено больше данных и информации об ошибках в вывод команды svacer import
* Изменение Public API: добавлена точка входа /api/public/login
* Операции по импорту и экспорту снимков доступны теперь обычным пользователям (не администраторам) при использовании command line интерфейса
* Операция по экспорту снимков доступна обычному пользователю из веб-интерфейса (импорт все еще требует роль администратора для веб-интерфейса)
* Операции по экспорту снимков переведены на асинхронный режим. Нотификация о готовности будет показана пользователю и доступна в панели нотификаций
* Обновлено описание детекторов в соответствии с релизом Svace 3.3.2
* Исправлена ошибка обработки корневых сертификатов при подключении к LDAP серверу по протоколу ldaps
* Исправлено ошибочное создание дубликатов локальных учетных записей LDAP пользователей (case sensitive login)
* Различные исправления в пользовательском интерфейсе с целью оптимизации производительности
* Добавлены пропущенные проверки ролей при работе с веб-интерфейсом
* Svacer больше не создает временные файлы в директории с исполняемым файлом
* Устаранены задержки при удалении веток и проектов

Changelog

2025-11-26T10:40:42Z

Chernykov sv:

=== Release 12-0-0 ===
* Импорт SARIF теперь более устойчив к пропускам в файле (отсутствие таких полей как location)
* Добавлены переменные окружения <code>SVACER_TIMEOUT_IMPORT_RESULTS</code> для контроля таймаута на ожидание возможности начала операции импорта результатов (формат Go Duration string) и <code>SVACER_NUM_PARALLEL_IMPORTS</code> на ограничение числа параллельных импортов (задачи на импорт выстраиваются в очередь). По умолчанию значения 15 минут и (<code>максимальное число коннектов к БД) / 2</code>. Ограничение необходимы для предотвращения бесконечных ожиданий и зависаний при импорте данных.
* Убраны лишние сообщения об устаревших детекторах при старте сервера или импорте снимков
* В prometheus метрики добавлен ряд показателей размеров object store
* Размер лога сервера показываемого в WEB интерфейсе ограничен. Размер задается переменной окружения SVACER_TAIL_LOG_SIZE (по умолчанию 1Мб). Показывается не последний кусок не более SVACER_TAIL_LOG_SIZE. Сам лог файл может быть не ограничивается в размерах
* ['''Экспериментально'''] Можно указать формат лог файла в JSON посредством параметра <code>svacer-server --log-format=json ...</code>, так же формат может быть указан через переменную окружения <code>SVACER_LOG_FORMAT=json</code>. Опции так же работают для CLI клиента <code>svacer</code>
* При запуске сервера можно указать флаг <code>--force-invariant-refresh</code> для принудительной регенерации инвариантов (может решить проблему с переносом разметки)
* Добавлена переменная окружения SVACER_INV_GEN_JOBS для контроля числа параллельных job-ов при регенарации инвариантов. При ограниченных ресурсах машины рекомендуем ставить значение 2. По умолчанию значение ставится в 70% от <code>runtime.GOMAXPROCS</code>
* Добавлена функциональность по чистке object store при удалении снимков
* ['''Экспериментально'''] Добавлена экспериментальная функциональность по модификации маркеров при импорте результатов и снимков
* Добавлена возможность создания сложных пользовательских фильтров по условиям выраженным предикатом
* Проведена работа по предотвращению зависаний при исчерпывании доступных соединений с PostgreSQL сервером
* Добавлен файл с чексуммой бинарника сервера <code>svacer-server</code> и проверка чексуммы при запуске
* Упростили [[Help:XSvacer:AIAssistant:Deploy|деплой ИИ-ассистента]]: добавили его сервис в docker-compose и deb/rpm пакеты
* Расширили возможности конфигурации при запуске сервера через [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose]: теперь можно включить debug, указать конфиг LDAP и параметр public-url
* Добавлена возможность указания минимального количества снимков, которое необходимо оставлять в ветке, тип очистки и период удаления в [[Help:CLI/cleanup|автоматическом удалении снимков]]
* Добавлена возможность [[Edit markers (command line)|автоматически обрабатывать маркеры]] при импорте данных. Также обработка маркеров доступна через [[Help:UI manual#Работа со снимками|UI]]
* Добавлен флаг <code>diff-url</code> для команды <code>quickdiff</code> в CLI, также как и для команд <code>import</code>, <code>upload</code>, <code>sarif2 import</code> с указанием опции quick-stat. Данный флаг позволяет получать ссылку на diff снимков
* Добавлены предупреждения если в командах <code>import</code>, <code>sarif2 import</code> используются флаги, которые используются флагом <code>upload</code>, но флаг <code>upload</code> не установлен
* Добавлена интеграциия с внешними системами посредством механизма [[Help:Installation#Механизм интеграции с внешними системами посредством Webhook-ов|Webhook-ов]]
* Добавлена [[Help:Installation#Настройка защиты от перебора паролей пользователей|Защита от перебора пароля пользователя]]
* Добавлена возможно задать [[Help:Installation#Настройка парольной политики внутреннего механизма аутентификации Svacer|Парольную политику безопасности]] для пользователей, использующих встроенный мханизм аутентификации Svacer
* Добавлена возможность задать [[Help:Installation#Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer)|вкладку по умолчанию]] для страницы входа в систему
* Исправлена ошибка, приводящая к разрастанию базы данных

=== Release 11-2-0 ===
22.07.2025

* Исправлены зависания сервера
* Добавлено автоматическое удаление архивов и прочих временных файлов при импорте .svace-dir и SARIF-файлов через REST API

=== Release 11-1-0 ===
08.07.2025

* Команды <code>--project-group, --if-no-group, --autoclean, --autoclean-svace</code> можно использовать в REST API для импорта svace-dir
* При использовании REST API для импорта svace-dir сервер будет автоматически удалять директории <code>.svace-dir</code> и <code>.svacer</code> если не указаны явные опции <code>--autoclean=false, --autoclean-svace=false</code>
* Добавлена опция запуска сервера <code>--classic-inv-mode</code> для включения режима совместимости по генерации инвариантов с версией <= 8.x.x
* Исправлены ошибки в работе <code>--quality-gate</code>, добавлена возможность учета статусов разметки. Добавлена возможность [[Help:Import from Svace#Флаг --baseline|указания baseline]] для сравнений при использовании опции <code>--quality-gate</code>
* Исправлены ошибки при подключении к PostgreSQL в SSL-режиме
* Исправлен ряд ошибок при работе с LDAP
* Команда <code>quickdiff</code> в CLI теперь выдает информацию также о Same и Matched предупреждениях

=== Release 11-0-0 ===
19.05.2025

* Убраны излишние сообщения в логе сервера о login/logout операциях. Они будут выводиться только при запуске сервера с опцией <code>--debug</code>
* Команды CLI <code>svacer sarif *</code> были убраны, для [[Help:Sarif|импорта и экспорта]] следует использовать <code>svacer sarif2 *</code>
* Экспорт SARIF теперь включает все комментарии как отдельные объекты в <code>Properties</code>
* При экспорте в SARIF теперь экспортируются поля <code>Labels, Orig function</code>
* Импорт SARIF теперь корректным образом учитывает relatedLocations и формирует трассу
* Импорт SARIF теперь автоматически импортирует исходники, если они включены в сам SARIF файл
* Добавлена возможность указания [[Help:Sarif#Мэппинг severity|мэппинга severity]] детекторов при импорте из SARIF
* Добавлен механизм указания правил резолвинга путей при импортировании исходного кода вместе с SARIF файлом
* Экспорт исходников из снимка будет доступен только при наличии исходников на сервере
* Добавлены флаги <code>--autoclean</code>, <code>--autoclean-svace</code> в команду <code>svacer import</code> для автоматического удаления <code>.svace-dir / .svacer-dir</code> после успешного импорта и загрузки данных на сервер
* Улучшена поддержка [[OIDC]]
* Улучшена поддержка [[LDAP configuration|LDAP]]
* Добавлена интеграция с хранилищем секретов [[Infisical]]
* Добавлена [[Notifications|служба нотификаций]] пользователей через почтовые сообщения и мессенджер telegram
* Добавлен механизм аутентификации и [[Help:UI manual#Управление токенами доступа|управления]] персональными токенами доступа
* Добавлен механизм упоминания пользователей через специальную конструкцию @login в комментариях к разметке
* В разделе Статистика добавлен дашборд с [[Release notes 11-0-0#Изменения в разделе Статистика|Общей статистикой]], содержащей метрики по последним импортированным снимкам в ветках проектов
* В статистике по активности пользователей добавлена возможность просмотра панели с актуальной информацией о маркере и опция показа только действий с актуальной разметкой
* Большинство CLI команд, работающих с сервером, теперь делают явный logout после завершения
* Svacer при импорте результатов Svace автоматически импортирует файлы <code>*.warn, *.err</code> с предупреждениями от самого анализатора Svace. Автоматический импорт не будет происходить при размере этих файлов более 30Мб (большой размер может свидетельствовать о проблемах в ходе анализа)
* Переменная окружения <code>SVACER_CACHE_DIR</code> теперь учитывается во всех местах (ранее в ряде случаев мог неявно использоваться <code>$HOME/.cache</code>)
* Добавлена возможность [[Help:CLI/cleanup|автоматического удаления снимков]]

=== Release 10-0-1 ===
17.02.2025

* Исправлена ошибка с временной таблицей при обработке планов автомиграции разметки при импорте результатов (ERROR: relation "loaded_review" already exists)

=== Release 10-0-0 ===
16.01.2025

* Множество изменений в UI, смотрите [[Release notes 10-0-0]]
* Сделали [[Help:Installation#rpm|dnf/yum репозиторий]] для RPM-пакетов Svacer
* Реализована возможность [[Markup2|экспорта, импорта и копирования разметки посредством Public REST API и CLI]]
* Реализован дополнительный экспериментальный механизм [[Help:UI manual#Настройка интерфейса|генерации PDF на основе HTML]]. Генерация PDF переведена на асинхронный режим с показом нотификации пользователю
* Добавлена возможность очистки всей разметки и/или комментариев на ветке проекта
* Улучшения функциональности просмотра маркеров в встроенном IDE Theia
* Добавлена функциональность по [[Help:UI manual#Глобальный поиск|глобальному поиску]] маркеров, комментариев и снимков по различным атрибутам
* Добавлена возможность [[Help:UI manual#Просмотр статистики|получения статистики]] по маркерам и активностям пользователей при разметке
* В API fullmarkers добавлен параметр <code>labels: true/false</code> для выгрузки меток маркера
* Реализован Public API для получения/добавления/удаления меток маркеров
* Настройки LDAP и прочие настройки аутентификации добавлены в единый конфигурационный файл
* Добавлена возможность удаления кода из снимка при частичном импорте в Svacer
* Добавлена опция minVersion, maxVersion для TLS при запуске сервера Svacer
* Добавлена поддержка групп проектов при импорте снимков в CLI
* При импорте снимков реализована поддержка автоматического определения пути префикса для переноса разметки
* Исправлен ряд ошибок в импорте и генерации [[Help:Sarif|SARIF]]
* Исправлены ошибки в копировании разметки между ветками, клонировании проектов и веток
* Добавлена возможность отключения бэкграунд задач по очистке мусора
* Добавлено экспериментальное CLI API для просмотра асинхронных задач на генерацию PDF
* Добавлена возможность визуализации производительности сервера на основе [https://github.com/arl/statsviz statsviz]
* Добавлена поддержка относительных путей в svres файле
* Добавлена возможность ожидания завершения операций по очистки мусора при выполнении операций по импорту результатов анализа
* Добавлена поддержка CWE таксономий при экспорте [[Help:Sarif|SARIF]]
* Добавлена переменная окружения SVACER_TOKEN_LIFETIME для управления временем жизни токена аутентификации
* Добавлена переменная окружения SVACER_RESET_ADMIN_PASSWORD для явного указания желаемого пароля при операции по сбросу пароля администратора
* Добавлен [[Notifications|механизм нотификаций пользователей]] о внутренних событиях Svacer (экспериментальный функционал)

=== Release 9-0-2 ===
22.07.2024

* Еще некоторые исправления, связанные с миграцией данных
* Исправлена проблема с навигацией по Go to Definition

=== Release 9-0-1 ===
15.07.2024

* Исправлены ошибки в клонировании проектов, приводящие к размножению записей в некоторых внутренних таблицах
* Различные исправления, связанные с миграцией данных
* Исправлена работа ряда CLI команд с включенным TLS на сервере
* Исправлен ряд ошибок в генерации PDF

=== Release 9-0-0 ===
04.06.2024

* Множество изменений в UI, смотрите [[Release notes 9-0-0]]
* Svacer разделен на два исполняемых файла: <code>svacer-server</code> — сервер и <code>svacer</code> — клиент
* {{Note}}Object store заменен на другую реализацию. Конвертация данных запускается автоматически при апгрейде и требует примерно 2х-2.2х дискового пространства, после конвертации старый object store будет удален. Время конвертации зависит от объема данных и скорости диска
* {{Note}}Изменен [[Help:Match|алгоритм сопоставления предупреждений]]. При старте сервера будет произведена регенерация всех инвариантов во всех ветках. Это может занять продолжительное время (зависит от мощности сервера и объемов данных)
* Добавлена возможность [[Help:Match#Ручное сопоставление предупреждений (экспериментальная возможность)|ручного сопоставления предупреждений]] для переноса разметки
* Добавлена экспериментальная поддержка [[OIDC|OpenID]] протокола для аутентификации
* Добавлена экспериментальная возможность [[Help:CLI#Слияние снимков из CLI (экспериментальная опция)|слияния снимков через CLI]]
* Исправлены баги в [[Help:Sarif|импорте Sarif]], добавлена поддержка импорта с относительными путями к файлам (флаг <code>--base-dir</code>)
* Лог сервера работает в режиме append, прежние данные не затираются
* Добавлена возможность передачи токена аутентификации в клиент Svacer через переменную окружения <code>SVACER_AUTH_TOKEN=token</code>
* Добавлена возможность передачи логина и пароля в клиент Svacer через переменную окружения <code>SVACER_AUTH_CREDS=login:password</code>
* Добавлен public REST endpoint для импорта <code>.svace-dir</code> на стороне сервера
* Добавлена возможность импорта <code>.svace-dir</code> из веб-интерфейса
* Добавлены [[Metrics|метрики]] для Prometheus, доступны при запуске сервера с переменной окружения <code>SVACER_TRACE_OPTIONS=prom_metrics_on</code> на <code>/api/metrics</code>
* Добавлена очистка БД от мусора с возможностью настройки периодичности данной операции через переменную окружения <code>SVACER_GC_PERIOD=val</code> где val — duration в формате <code>hhmmss</code> или [https://en.wikipedia.org/wiki/Cron Cron]
* Добавлена возможность клонирования проектов
* Добавлен импорт <code>*warn, *.err</code> файлов из <code>.svace-dir</code>, которые содержат диагностические сообщения от Svace
* Добавлена возможность [[Help:CLI#Ограничение числа запросов|ограничения числа запросов]] на сервер с указанием параметров в переменной окружения <code>SVACER_SERVER_THROTTLE_PARAMS</code>
* Добавлен шаблон для импорта разметки из кода на Go: <code>DEFAULT_GO</code>
* Добавлена возможность [[Help:CLI#Аутентификация из файла|аутентификации из файла]]
* Исправлены проблемы безопасности
* Добавлена возможность просмотра исходного кода снимка с предупреждениями анализатора во внешней IDE собранной на базе [https://theia-ide.org/ Theia IDE]
* К команде automigrate add в CLI добавлен флаг <code>skip-exist</code>, чтобы при добавлении паттерна, который уже существует, не выдавало ошибки
* К команде upload (import с флагом upload) с указанием флага <code>quality-gate</code> теперь можно добавить флаг <code>quality-gate-verbose</code>. Если его указать, то также будет выведен результат успешных проверок quality-gate
* Улучшения в поддержке протокола LDAP

=== Release 8-0-1 ===
22.01.2024

* Исправлена работа в изолированной от сети среде. Загрузка Web UI больше не требует доступа к публичным CDN
* Добавлена поддержка функций при указании пользовательского фильтра
* Добавлено API для управления пользовательскими фильтрами. Детали и пример использования можно найти здесь: https://gitlab.ispras.ru/svacer-public/api-go-examples/-/tree/master/api-ui-settings
* Исправлено отображение Checker Severity при экспорте в SARIF. Теперь Critical -> error; Major, Normal -> warning; Minor -> note; any other -> warning

=== Release 8-0-0 ===
21.11.2023

* Множество изменений в UI. Смотрите обзор в [[Release notes 8-0-0]]
* Добавлен новый импорт и экспорт из SARIF в command line с поддержкой исходного кода в SARIF файлах и импортом описания детекторов из SARIF
* Добавлены группы проектов
* Переделана модель ролей и доступов. Добавлен CLI для управления ролями и доступами
* Добавлена возможность настройки автопереноса разметки между ветками, в том числе в разных проектах
* Импорт/экспорт снимков включает информацию о детекторах
* Исправлена работа интерфейса с Undefined детекторами (т. е. детекторами, информация о которых отсутствует в Svacer)
* Добавлено экспериментальное API по управлению детекторами и конфигурациями детекторов
* Добавлена очистка исходного кода от Svacer-specific комментариев перед экспортом разметки в код
* Добавлена возможность включения режима обязательного комментария при разметке кода. Комментарий будет сгруппирован с операцией разметки и будет иметь ссылку на нее
* Утилита миграции со старого svace-сервера больше не поддерживается. При необходимости миграции используйте утилиту из прошлых релизов Svacer
* Добавлена Swagger документация на API
* Добавлено хранение истории изменений комментариев
* Опция <code>--pathPrefix</code> поддерживает файлы в JSON формате вида: <code>[{ "prefix": "/some/path", "replace": "/test" }, ...]</code>
* При использовании операции по обновлению <code>pathPrefix</code> на сервере, данные о прежнем <code>pathPrefix</code> запоминаются в мета-информации о снимке
* Добавлена возможность переименования снимков в UI
* Sensitive информация (детали подключения к БД с данными аутентификации) убрана из UI и API
* ОС в docker-образе Svacer обновлена с Ubuntu 18 до Ubuntu 22
* Улучшена логика автоопределения портов и протоколов при соединении с сервером из Svacer CLI

=== Release 7-0-1 ===
23.05.2023

* Исправлена проблема с фильтрацией предупреждений для C# проектов

=== Release 7-0-0 ===
16.05.2023

* Убрана зависимость от PostgreSQL из .deb и .rpm пакетов, чтобы проще было ставить Svacer только как клиент
* Сделан пакет для Windows (.msi) и документация по установке и запуску на Windows
* Теперь, если при svacer import и svacer sarif не указан путь к проекту, им считается текущая директория
* Информация о разметке и блокировках теперь обновляется автоматически при изменении в другом браузере (табе) или другим пользователем
* UI для пользовательских фильтров улучшен и перенесен в правую верхнюю часть экрана
* UI для выбора проекта, ветки и снимка теперь находится на одном уровне
* Улучшен UI для режима сравнения снимков
* Добавлена возможность работать одновременно с несколькими открытыми файлами в режиме Code, это поведение можно изменить в настройках профиля пользователя
* В левой навигационной панели детекторы теперь по умолчанию группируются по серьезности, это поведение можно изменить в настройках профиля пользователя
* Профиль текущего пользователя теперь можно смотреть/редактировать только через меню в правом верхнем углу
* Добавлена возможность копирования в системном логе и журнале
* Для пользователя теперь запоминается последний контекст (проект/ветка/снимок), с которым он работал, он автоматически открывается при старте новой сессии
* Групповая разметка теперь делается единой транзакцией, в случае ошибок или отмены все изменения откатываются
* Добавлено предупреждение при использовании некорректных путей при использовании REST API с префиксом /api
* Поддержка указания паролей из файла или pipe-а при использование Svacer CLI
* Добавлена поддержка multi-tab code view для режима просмотра кода объекта сборки
* Добавлена поддержка сохранения информации об удаленных детекторах при загрузке информации о детекторах из новой версии Svace
* Исправлен импорт результатов анализа, если сборка проводилась с опцией --disable-dxr
* Исправлены проблемы при импорте и прикреплении нескольких файлов к снимку
* Исправлены ошибки с входом в систему пользователей LDAP (специальные символы в пароле, вход по атрибуту mail)
* Добавлена возможность использования резервных серверов LDAP
* Добавлена возможность автоматического назначения пользователям LDAP роли Svacer, в зависимости от принадлежности пользователя к LDAP группе
* Добавлены новые public запросы на получение маркеров/снимков/проектов с учетом заданных параметров фильтрации
* Добавлена поддержка TLS при работе сервера по протоколам HTTP и gRPC
* Добавлена возможность загрузки статистики по общему количеству предупреждений и по количеству размеченных предупреждений для проектов и веток через REST API
* Добавлена вкладка выбора проектов в расширении VSCode
* Убрана возможность использовать всплывающее окно в VScode для добавления/редактирования/удаления комментариев, установки ревью-статусов, локов и т.д.

=== Release 6-0-3 ===
25.01.2023

* RPM-пакет теперь при сборке упаковывается в gzip вместо zstd для обратной совместимости со старыми дистрибутивами
* Если short url некорректен, то Svacer теперь будет возвращать корректный http error NotFound
* Если путь к лог файлу явно не указан, то svacer.log будет создаваться во временной директории. Это решает проблемы при запуске Svacer из директорий с запретом на запись. Путь к лог файлу будет печататься в stdout
* Лог файлы не будут создаваться, когда используется опция --help
* Исправлены проблемы при миграции схемы данных, когда в PostgreSQL используется SSL подключение
* Добавлены описания детекторов из последнего релиза Svace, которые были пропущены в релизе 6-0-2
* Исправлена работа Svacer за proxy-сервером, где выставляется Header "X-Content-Type-Options nosniff"
* Добавлены кнопки для скачивания системного лога и журнала из web-интерфейса
* Поправлен ряд ошибок валидации схемы при экспорте в SARIF
* Исправлено поведение при наличии нескольких хуков в конфигурационном файле
* В информацию о маркере для хуков добавлены checker severity и reliability
* Исправлен случайный порядок URL для маркеров при использовании public API для получения URL-ов
* На главную страницу добавлена кнопка "Помощь", которая открывает документацию
* При использовании команд навигации в режиме "Browse code" текущий файл теперь корректно подсвечивается в дереве файлов
* В диалоге групповой разметки убран индикатор изменений в виде кружочка, наличие изменений можно определить по активности кнопок "Apply" и "Reset"
* Кнопка обновления в верхнем меню теперь корректно обновляет информацию на странице Settings/Project
* Различные небольшие исправления в пользовательском интерфейсе

=== Release 6-0-2 ===
16.12.2022

* Исправлена проблема в UI с сохраненными пользовательскими фильтрами

=== Release 6-0-1 ===
13.12.2022

* Добавлено описание ряда детекторов, которые есть в последнем релизе Svace 3.3.2 но были пропущены в Svacer
* Исправлено вылетание в Login Screen при удалении нотификации из панели нотификаций
* Исправлено появление белого экрана при клике на детектор, информация о котором отсутствует
* Ряд различных небольших исправлений в UI
* Промежуточное хранилище будет очищаться по умолчанию при использовании команды import

=== Release 6-0-0 ===
30.11.2022

* Добавлено копирование комментариев при копировании разметки
* Комментарии добавлены к отчету в формате csv
* Добавлена возможность вводить пароль с клавиатуры для консольных команд
* Добавлена возможность импортировать разметку из объекта сборки (из ранее загруженных данных)
* Добавлена возможность импортировать разметку сразу после загрузки на сервер (опция для команды svacer upload)
* Добавлена возможность загружать исходный код не из папки .svace-dir
* Добавлена возможность бэкапа и восстановление объектного хранилища в сервер PostgresSQL
* Добавлена возможность создания отчета по проекту в формате PDF через интерфейс командной строки и посредством REST API
* Добавлена возможность подавления предупреждений через inline комментарии в коде
* Добавлена возможность подавления предупреждений по идентификатору предупреждения через command line и REST API
* Добавлена возможность ассоциировать организацию с пользователем и реестр организаций
* Добавлена фильтрация списка комментариев по пользователю в правой панели веб-интерфейса
* Добавлен поиск пользователей по его атрибутам в панели управления пользователями
* Добавлена возможность заполнения данных профиля LDAP пользователя данными, полученными от LDAP сервера
* Добавлена возможность прикреплять файлы к снимкам при импорте результатов (данные файлы составляют часть экспортируемых данных при экспорте снимков)
* Добавлена возможность ассоциировать пользовательские атрибуты типа "строка" или массив строк со снимком при импорте данных (данные атрибуты составляют часть экспортируемых данных при экспорте снимков)
* Добавлены command line операции по получению прикрепленных файлов и пользовательских атрибутов со снимков
* Добавлена возможность группового добавления комментариев
* Добавлена возможность указания сетевого интерфейса для работы WEB и GRPC серверов
* Добавлен вывод краткой статистики по загруженному снимку при команде upload. Поддерживается текстовой и JSON форматы вывода
* Существенно расширены возможности по интеграции Visual Studio Code с сервером Svacer
* Добавлен флаг --git в команду import. При наличии такого флага, ищется ближайший git репозиторий содержащий .svace-dir и при наличии такого - используется путь к гит репозиторию для замены путей на префикс .build.
* Portable PostgreSQL больше не входит в поставку. Вместо него поставляется docker-compose.yml файл для запуска PostgreSQL в докер-контейнере
* Добавлено больше данных и информации об ошибках в вывод команды svacer import
* Изменение Public API: добавлена точка входа /api/public/login
* Операции по импорту и экспорту снимков доступны теперь обычным пользователям (не администраторам) при использовании command line интерфейса
* Операция по экспорту снимков доступна обычному пользователю из веб-интерфейса (импорт все еще требует роль администратора для веб-интерфейса)
* Операции по экспорту снимков переведены на асинхронный режим. Нотификация о готовности будет показана пользователю и доступна в панели нотификаций
* Обновлено описание детекторов в соответствии с релизом Svace 3.3.2
* Исправлена ошибка обработки корневых сертификатов при подключении к LDAP серверу по протоколу ldaps
* Исправлено ошибочное создание дубликатов локальных учетных записей LDAP пользователей (case sensitive login)
* Различные исправления в пользовательском интерфейсе с целью оптимизации производительности
* Добавлены пропущенные проверки ролей при работе с веб-интерфейсом
* Svacer больше не создает временные файлы в директории с исполняемым файлом
* Устаранены задержки при удалении веток и проектов

Help:Public API

2025-11-25T15:19:28Z

Chernykov sv: /* Примеры использования фильтров в public api */

== Публичные REST запросы ==

Для работы с сервером через различные приложения реализованы публичные запросы, которые не будут меняться при обновлении самого сервера. Если будут происходить значимые изменения, то запрос будет помечаться как deprecated и создаваться новый такой же запрос с пометкой '''/api/some/request/v2'''.

=== Получение токена ===

Для большинства запросов требуется JWT-токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами:

* Простой способ — POST запрос с basic auth на '''/api/login''', который вернёт JWT-токен в body. Использование данного способа не желательно, так как он может меняться в будущем, а также не всегда правильно обрабатывает спец. символы и кириллицу в логине/пароле. Пример:
<pre>curl -X POST -u admin:admin http://svacer.example.com/api/login</pre>
* Предпочтительный способ — POST запрос на '''/api/public/login''' с передачей данных в теле запроса, как описано [[Help:Public API#public-api-login|ниже]]. Пример:
<pre>curl -X POST -d '{"login": "admin", "password": "admin"}' http://svacer.example.com/api/public/login</pre>

Полученный токен надо добавлять в header всех запросов: <code>Authorization: Bearer <token></code>

=== Базовые публичные запросы ===

{| class="wikitable"
| '''/api/public/login'''
| POST
| <span id="public-api-login" />Аутентификация пользователя. Тело запроса имеет формат JSON и выглядит следующим образом:
{
"auth_type": "string",
"server": "string"
"login": "string",
"password": "string"
}
* auth_type — тип аутентификации: при указании значения "ldap" — аутентификация через LDAP, во всех остальных случаях, или если поле не указано — по внутренней базе пользователей Svacer
* server — имя LDAP-сервера, как он указан в конфигурационном файле LDAP (поле name) при запуске Svacer. Значение поля учитывается, только если <code>"auth_type": "ldap"</code>, в иных случаях его можно не указывать
* login — логин пользователя, обязательное поле
* password — пароль пользователя, обязательное поле
|-
| '''/api/public/help'''
| GET
| Дополнительная информация по public REST API. Работает без авторизации
|-
| '''/api/health'''
| GET
| Проверка доступности сервера. Не требует авторизации. Возвращает статус 200 OK если сервер работает
|}

Описание остальных запросов смотрите в спецификации OpenAPI на вашем сервере Svacer по адресу <code>/api/public/swagger/</code>

Также можете посмотреть на нашем демо-сервере: https://svacer-demo.ispras.ru/api/public/swagger/

== Управление контейнерами ==
См. [[Help:Public API/management/containers]]

== Экспорт, импорт и копирование разметки ==
См. [[Markup2]]

== Примеры использования public REST API ==

=== Получение URL загруженного снимка ===

Этот пример работает только с python3 и не работает при аутентификации в Svacer через LDAP.

Скачайте и распакуйте [[Index.php?title=Media:Get link.zip|get_link.zip]]

Запрос:
<pre>python get_link.py --url http://svacer.example.com:8080 --user admin --password admin --project bash</pre>

Ответ:
<pre>http://svacer.example.com:8080/mode/review/project/0fd645aa-8e70-4a4f-b68b-766c4f337bf2/branch/8925df5a-7a98-4f07-bc88-ee4ea5b43813/snapshot/e3367efa-a804-4c05-9a7a-a7cb052bef1d</pre>

=== Примеры использования фильтров в public api ===
Данные фильтры служат только для ограничения вывода некоторых методов в public api. Они являются отдельной сущностью, наравне с глобальными фильтрами и пользовательскими фильтрами. Их основное отличие от последних двух в том, что время их жизни соответствует одному запросу, в котором они заданы.

==== Вспомогательные модули ====

В некоторых примерах API используется фильтр, с помощью которого можно ограничить вывод данных и получить более точные результаты. Для работы с этим фильтром используются следующие классы:

<pre class="">import requests
from requests import auth
from requests.models import HTTPBasicAuth
import json
from dataclasses import dataclass
import sys
import base64

def printerr(text):
#print in stderr and exit
print(f"{text}", file=sys.stderr, flush=True)
exit()

@dataclass
class ProjectFilter:
id: str
name: str

class ProjectFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class BranchFilter:
id: str
name: str

class BranchFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class SnapshotFilter:
id: str
name: str

class SnapshotFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class MarkerFilter:
severity: str
file: str
checker: str
review: str

class MarkerFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class Filter:
project: ProjectFilter
branch: BranchFilter
snapshot: SnapshotFilter
marker: MarkerFilter

class FilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

def CreateFilterParam(filter: Filter):
jsoned = FilterEncoder().encode(filter)
b64ed = base64.b64encode(jsoned.encode("utf-8"))
return b64ed.decode("utf-8")
</pre>
Принцип использования классов следующий:

# Создается экземпляр нужного класса XXXXFilter
# Создается base64 строка на основе объекта пункта 1, которая в дальнейшем передается в url запросе. Для этого используется метод CreateFilterParam()

Например. Для создания фильтра, ограничивающего множество проектов выражением darpa*, можно использовать следующие строчки кода:

<pre class="">f: Filter = Filter(ProjectFilter(id="", name="darp*"), None, None, None)
param = CreateFilterParam(f)</pre>
Как можно заметить из определения фильтра, для проекта, ветки и снимка - можно указать как имя так и ID. Имя можно указать с использованием регулярного выражения. ID необходимо указать полностью.

==== Точка входа api/public/login ====

Данный класс может быть использован для соединения с сервером Svacer. В данном модуле демонстрируется взаимодействие с точкой входа /api/public/login.

<pre class="">import requests

class SvacerClient:
def __init__(self, host, user, password):
"""
Initialize the Svacer client
"""
self.host = host
self.user = user
self.password = password
self.token = None
self.auth_header = None
self.session = requests.Session() # Use session for connection pooling
self.set_auth_token()

def set_auth_token(self):
"""
Get authorization token using /api/public/login and setup in session
"""
try:
response = requests.post(
url=f"{self.host}/api/public/login",
json={
"login":self.user,
"password":self.password,
},
verify=False
)
response.raise_for_status() # Raise an exception for bad status codes
body = response.json()
self.token = body["token"]
self.auth_header = {'Authorization': f'Bearer {self.token}'}

# Set the authorization header in the session
self.session.headers.update(self.auth_header)

return self.token

except requests.exceptions.RequestException as e:
raise Exception(f"Failed to get authentication token: {e}")
except KeyError as e:
raise Exception(f"Token not found in response: {e}")

def post(self, endpoint, data=None, json=None, **kwargs):
"""
Make a POST request to the API

"""
if self.auth_header is None:
raise Exception("No authentication token available. Call get_auth_token() first.")

url = f"{self.host}{endpoint}"

try:
response = self.session.post(
url,
data=data,
json=json,
verify=False,
**kwargs
)
response.raise_for_status()
return response

except requests.exceptions.RequestException as e:
raise Exception(f"POST request failed: {e}")

def get(self, endpoint, params=None, **kwargs):
"""
Make a GET request to the API

"""
if self.auth_header is None:
raise Exception("No authentication token available. Call get_auth_token() first.")

url = f"{self.host}{endpoint}"

try:
response = self.session.get(
url,
params=params,
verify=False,
**kwargs
)
response.raise_for_status()
return response

except requests.exceptions.RequestException as e:
raise Exception(f"GET request failed: {e}")
</pre>
==== Точка входа /api/public/projects ====

В данном примере выводятся в формате json список проектов, имя которых соответствует регулярному выражению darpa*

<pre class="">from filters import *
from svacer import *

cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(ProjectFilter(id="", name="darp*"), None, None, None)
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects?filters={param}")
print(f"Response: {resp.json()}")</pre>
Результат может быть следующим

<pre class="">[
{
"project":
{
"id": "019abb61-8cd3-7437-957d-aed0c87e603a",
"name": "darpa-clone",
"time": "2025-11-25T14:18:43.79526Z",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000"
},
"branches":
[
{
"id": "019abb61-83b1-7d80-8d23-ce849387bd6e",
"name": "master",
"time": "2025-11-25T14:18:41.457887Z",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000"
}
]
},
{
"project":
{
"id": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"name": "darpa",
"time": "2020-04-03T04:54:13.754864Z",
"created_by": "importer",
"created_by_id": null
},
"branches":
[
{
"id": "ab179fad-c96a-498d-8407-2a3c82719385",
"name": "master",
"time": "2020-04-03T04:54:13.754864Z",
"created_by": "importer",
"created_by_id": null
}
]
}
]</pre>
==== Точка входа /api/public/projects/{project_id}/branch/{branch_id}/snapshots ====

С помощью данной точки входа можно получить список снимков, указанной ветки. Пример кода, для получения снимков с именем "ver. 2.7.0*"

<pre class="">from filters import *
from svacer import *
import json

def get_snapshots(pr_id, br_id):
cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(None,None,SnapshotFilter(id="",name="ver. 2.7.0*"), None)
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects/{pr_id}/branch/{br_id}/snapshots?filters={param}")
fmt = json.dumps(resp.json())
print(f"Response: {fmt}")

get_snapshots("e6abca1b-23a0-4107-9120-4d8d3596030b","ab179fad-c96a-498d-8407-2a3c82719385")
</pre>
Возможный вывод команды:

<pre class="">[
{
"id": "4242b43a-da44-44ca-9b28-770295b98493",
"name": " ver. 2.7.1 200419 05:55",
"time": "2020-04-03T04:56:49.006218Z",
"link": "http://swarm-mgr.home:10142/mode/review/project/e6abca1b-23a0-4107-9120-4d8d3596030b/branch/ab179fad-c96a-498d-8407-2a3c82719385/snapshot/4242b43a-da44-44ca-9b28-770295b98493",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"import_time": "2019-04-20T04:26:52Z",
"details":
{
"branch": "master",
"branchIDHint": "4d1f1413-c638-4a8b-aa4d-d9fccd8df3e9",
"buildObject": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"dxrIncluded": true,
"host":
{
"hostname": "seroshki",
"user": "sergey"
},
"id": "4242b43a-da44-44ca-9b28-770295b98493",
"importTime": "2019-04-20T04:26:52Z",
"migration-data":
{
"DXR": "ce03cd6d1bd54eac92e227d4184356a90b64b7c1",
"SOURCE_TREE": "0949114563f48d5a2df6e94816b7b1095b6c6540",
"date": "2019-04-20T04:26:52Z",
"description": " ver. 2.7.1 200419 05:55",
"id": "2af625b5faad4083be881135ad1daf6b304e4c99",
"owner": "7a831745d52244db2a4f1692f0c473e61f0f0157",
"parent_id": "0d491fde062e2795a4b38758488a47bf8481d03c",
"sourceData": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"svres": "2af625b5faad4083be881135ad1daf6b304e4c99.svres.gzip",
"type": "snapshot",
"user": "jenkins"
},
"project": "darpa",
"projectIDHint": "354c9c94-7b57-4427-8ce0-c41f1e59e6c2",
"snapshot": " ver. 2.7.1 200419 05:55",
"sourceIncluded": true
}
},
{
"id": "4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"name": " ver. 2.7.1 130419 07:39",
"time": "2020-04-03T04:58:53.618464Z",
"link": "http://swarm-mgr.home:10142/mode/review/project/e6abca1b-23a0-4107-9120-4d8d3596030b/branch/ab179fad-c96a-498d-8407-2a3c82719385/snapshot/4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"import_time": "2019-04-13T04:33:46Z",
"details":
{
"branch": "master",
"branchIDHint": "c472aab7-d53f-496c-9d3d-069c0901d9bb",
"buildObject": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"dxrIncluded": false,
"host":
{
"hostname": "seroshki",
"user": "sergey"
},
"id": "4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"importTime": "2019-04-13T04:33:46Z",
"migration-data":
{
"DXR": "ce03cd6d1bd54eac92e227d4184356a90b64b7c1",
"SOURCE_TREE": "0949114563f48d5a2df6e94816b7b1095b6c6540",
"date": "2019-04-13T04:33:46Z",
"description": " ver. 2.7.1 130419 07:39",
"id": "0d491fde062e2795a4b38758488a47bf8481d03c",
"owner": "7a831745d52244db2a4f1692f0c473e61f0f0157",
"parent_id": "edca1583aa41489d37ae9fb2c348ad066ecd3ab3",
"sourceData": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"svres": "0d491fde062e2795a4b38758488a47bf8481d03c.svres.gzip",
"type": "snapshot",
"user": "jenkins"
},
"project": "darpa",
"projectIDHint": "cf032d99-2efe-4ee0-8db8-ee85ff17b296",
"snapshot": " ver. 2.7.1 130419 07:39",
"sourceIncluded": false
}
}
]</pre>
==== Точка входа /api/public/projects/{project_id}/branch/{branch_id}/snapshots/{snapshot_id}/fullmarkers ====

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

* трассу ошибки (параметр traces, возможные значения true,false)
* информацию о чекере (параметр checker_info, возможные значения true,false)
* историю разметки (параметр review_history, возможные значения true,false)
* история комментария (параметр comment_history, возможные значения true,false)
* идентификатор пользовательского фильтра (параметр custom_filter)
* фильтр на параметры маркера

Пример кода, для получения всего множества информации о маркерах в некотором снимке, размеченных со статусом Conf*:

<pre class="">def get_markers (pr_id, br_id, snap_id):
cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(None, None, None, MarkerFilter(severity="*",
file="*", checker="*", review="Conf*"))
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects/{pr_id}/branch/{br_id}/snapshots/{snap_id}/fullmarkers?traces=true&checker_info=true&review_history=true&comment_history=true&filters={param}")
fmt = json.dumps(resp.json())
print(f"Response: {fmt}")

get_markers("e6abca1b-23a0-4107-9120-4d8d3596030b","ab179fad-c96a-498d-8407-2a3c82719385","250a4ff1-bfc8-439a-834d-18b62a545d8d") </pre>
Возможный вывод:

<pre class="">[
{
"id": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"file": "/mnt/scratch/sources/darpa-source/challenges/Divelogger2/lib/string.cc",
"function": "_ZN6StringaSERKS_",
"line": 179,
"locID": 1006,
"lang": "CXX",
"tool": "SvEng",
"warnClass": "ASSIGN_NO_CHECK_FOR_THIS",
"mtid": "SvEng.LA.4",
"msg": "Method 'operator=' doesn't check its argument with 'this' pointer.",
"details": "d96c832835f414a119ea8c7575a8926378fd7cf6",
"flags": 0,
"traces": [
{
"role": "declaration",
"locations": [
{
"file": "/mnt/scratch/sources/darpa-source/challenges/Divelogger2/lib/string.cc",
"line": 179,
"col": 0,
"spec": false,
"info": "declaration"
}
]
}
],
"checker_severity": "Normal",
"checker_reliability": "High",
"checker_origin": "builtin",
"review": {
"id": "65796",
"status": "Confirmed",
"severity": "Major",
"action": "Fix required",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:25.216816Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba"
},
"review_history": [
{
"id": "65796",
"status": "Confirmed",
"severity": "Major",
"action": "Fix required",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:25.216816Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "250a4ff1-bfc8-439a-834d-18b62a545d8d",
"markerID": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 300319 07:08",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:40.524836Z"
}
},
{
"id": "65795",
"status": "Confirmed",
"severity": "Major",
"action": "Undecided",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:21.683963Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "250a4ff1-bfc8-439a-834d-18b62a545d8d",
"markerID": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 300319 07:08",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:40.524836Z"
}
},
{
"id": "63495",
"status": "Confirmed",
"severity": "Unspecified",
"action": "Undecided",
"createdBy": "reviewer",
"created_by_id": "077fdd75-b382-4008-97c4-ec6ef8732ccd",
"time": "2022-04-05T11:47:47.026161Z",
"createdFrom": "a94f92f4-4e3e-4071-9f10-aa8e4389dd0a",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "4242b43a-da44-44ca-9b28-770295b98493",
"markerID": "a94f92f4-4e3e-4071-9f10-aa8e4389dd0a",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 200419 05:55",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:49.006218Z"
},
"reviewer_attrs": ["review_master"]
}
],
"comments": [
{
"id": "e3287eb2-9e64-4780-a1c0-22ed9393a226",
"text": "aaaaaaaaa",
"type": "txt",
"ref": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdBy": "admin",
"created_by_id": "",
"invariant": "",
"createTs": "2025-11-25T15:04:11.358138Z",
"updateTs": "2025-11-25T15:04:17.220568Z",
"history": [
{
"id": "019abb8b-4244-7931-81f7-a7d1a4512de0",
"comment_id": "e3287eb2-9e64-4780-a1c0-22ed9393a226",
"comment_ref": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"text": "aaaa",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"create_ts": "2025-11-25T15:04:11.358138Z"
}
]
}
],
"invariant": "1pQ3T5bq6AMYEYJqzFsW+Q"
}
]
</pre>
Следует заметить, что данный метод может требовать достаточно большого времени выполнения для проектов с большим количеством предупреждений.

Help:Public API

2025-11-25T15:16:41Z

Chernykov sv: /* Вспомогательные модули */

== Публичные REST запросы ==

Для работы с сервером через различные приложения реализованы публичные запросы, которые не будут меняться при обновлении самого сервера. Если будут происходить значимые изменения, то запрос будет помечаться как deprecated и создаваться новый такой же запрос с пометкой '''/api/some/request/v2'''.

=== Получение токена ===

Для большинства запросов требуется JWT-токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами:

* Простой способ — POST запрос с basic auth на '''/api/login''', который вернёт JWT-токен в body. Использование данного способа не желательно, так как он может меняться в будущем, а также не всегда правильно обрабатывает спец. символы и кириллицу в логине/пароле. Пример:
<pre>curl -X POST -u admin:admin http://svacer.example.com/api/login</pre>
* Предпочтительный способ — POST запрос на '''/api/public/login''' с передачей данных в теле запроса, как описано [[Help:Public API#public-api-login|ниже]]. Пример:
<pre>curl -X POST -d '{"login": "admin", "password": "admin"}' http://svacer.example.com/api/public/login</pre>

Полученный токен надо добавлять в header всех запросов: <code>Authorization: Bearer <token></code>

=== Базовые публичные запросы ===

{| class="wikitable"
| '''/api/public/login'''
| POST
| <span id="public-api-login" />Аутентификация пользователя. Тело запроса имеет формат JSON и выглядит следующим образом:
{
"auth_type": "string",
"server": "string"
"login": "string",
"password": "string"
}
* auth_type — тип аутентификации: при указании значения "ldap" — аутентификация через LDAP, во всех остальных случаях, или если поле не указано — по внутренней базе пользователей Svacer
* server — имя LDAP-сервера, как он указан в конфигурационном файле LDAP (поле name) при запуске Svacer. Значение поля учитывается, только если <code>"auth_type": "ldap"</code>, в иных случаях его можно не указывать
* login — логин пользователя, обязательное поле
* password — пароль пользователя, обязательное поле
|-
| '''/api/public/help'''
| GET
| Дополнительная информация по public REST API. Работает без авторизации
|-
| '''/api/health'''
| GET
| Проверка доступности сервера. Не требует авторизации. Возвращает статус 200 OK если сервер работает
|}

Описание остальных запросов смотрите в спецификации OpenAPI на вашем сервере Svacer по адресу <code>/api/public/swagger/</code>

Также можете посмотреть на нашем демо-сервере: https://svacer-demo.ispras.ru/api/public/swagger/

== Управление контейнерами ==
См. [[Help:Public API/management/containers]]

== Экспорт, импорт и копирование разметки ==
См. [[Markup2]]

== Примеры использования public REST API ==

=== Получение URL загруженного снимка ===

Этот пример работает только с python3 и не работает при аутентификации в Svacer через LDAP.

Скачайте и распакуйте [[index.php?title=Media:Get link.zip|get_link.zip]]

Запрос:
<pre>python get_link.py --url http://svacer.example.com:8080 --user admin --password admin --project bash</pre>

Ответ:
<pre>http://svacer.example.com:8080/mode/review/project/0fd645aa-8e70-4a4f-b68b-766c4f337bf2/branch/8925df5a-7a98-4f07-bc88-ee4ea5b43813/snapshot/e3367efa-a804-4c05-9a7a-a7cb052bef1d</pre>

=== Примеры использования фильтров в public api ===
Данные фильтры служат только для ограничения вывода некоторых методов в public api. Они являются отдельной сущностью, наравне с глобальными фильтрами и пользовательскими фильтрами.

==== Вспомогательные модули ====

В некоторых примерах API используется фильтр, с помощью которого можно ограничить вывод данных и получить более точные результаты. Для работы с этим фильтром используются следующие классы:

<pre class="">import requests
from requests import auth
from requests.models import HTTPBasicAuth
import json
from dataclasses import dataclass
import sys
import base64

def printerr(text):
#print in stderr and exit
print(f"{text}", file=sys.stderr, flush=True)
exit()

@dataclass
class ProjectFilter:
id: str
name: str

class ProjectFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class BranchFilter:
id: str
name: str

class BranchFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class SnapshotFilter:
id: str
name: str

class SnapshotFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class MarkerFilter:
severity: str
file: str
checker: str
review: str

class MarkerFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class Filter:
project: ProjectFilter
branch: BranchFilter
snapshot: SnapshotFilter
marker: MarkerFilter

class FilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

def CreateFilterParam(filter: Filter):
jsoned = FilterEncoder().encode(filter)
b64ed = base64.b64encode(jsoned.encode("utf-8"))
return b64ed.decode("utf-8")
</pre>
Принцип использования классов следующий:

# Создается экземпляр нужного класса XXXXFilter
# Создается base64 строка на основе объекта пункта 1, которая в дальнейшем передается в url запросе. Для этого используется метод CreateFilterParam()

Например. Для создания фильтра, ограничивающего множество проектов выражением darpa*, можно использовать следующие строчки кода:

<pre class="">f: Filter = Filter(ProjectFilter(id="", name="darp*"), None, None, None)
param = CreateFilterParam(f)</pre>
Как можно заметить из определения фильтра, для проекта, ветки и снимка - можно указать как имя так и ID. Имя можно указать с использованием регулярного выражения. ID необходимо указать полностью.

==== Точка входа api/public/login ====

Данный класс может быть использован для соединения с сервером Svacer. В данном модуле демонстрируется взаимодействие с точкой входа /api/public/login.

<pre class="">import requests

class SvacerClient:
def __init__(self, host, user, password):
"""
Initialize the Svacer client
"""
self.host = host
self.user = user
self.password = password
self.token = None
self.auth_header = None
self.session = requests.Session() # Use session for connection pooling
self.set_auth_token()

def set_auth_token(self):
"""
Get authorization token using /api/public/login and setup in session
"""
try:
response = requests.post(
url=f"{self.host}/api/public/login",
json={
"login":self.user,
"password":self.password,
},
verify=False
)
response.raise_for_status() # Raise an exception for bad status codes
body = response.json()
self.token = body["token"]
self.auth_header = {'Authorization': f'Bearer {self.token}'}

# Set the authorization header in the session
self.session.headers.update(self.auth_header)

return self.token

except requests.exceptions.RequestException as e:
raise Exception(f"Failed to get authentication token: {e}")
except KeyError as e:
raise Exception(f"Token not found in response: {e}")

def post(self, endpoint, data=None, json=None, **kwargs):
"""
Make a POST request to the API

"""
if self.auth_header is None:
raise Exception("No authentication token available. Call get_auth_token() first.")

url = f"{self.host}{endpoint}"

try:
response = self.session.post(
url,
data=data,
json=json,
verify=False,
**kwargs
)
response.raise_for_status()
return response

except requests.exceptions.RequestException as e:
raise Exception(f"POST request failed: {e}")

def get(self, endpoint, params=None, **kwargs):
"""
Make a GET request to the API

"""
if self.auth_header is None:
raise Exception("No authentication token available. Call get_auth_token() first.")

url = f"{self.host}{endpoint}"

try:
response = self.session.get(
url,
params=params,
verify=False,
**kwargs
)
response.raise_for_status()
return response

except requests.exceptions.RequestException as e:
raise Exception(f"GET request failed: {e}")
</pre>
==== Точка входа /api/public/projects ====

В данном примере выводятся в формате json список проектов, имя которых соответствует регулярному выражению darpa*

<pre class="">from filters import *
from svacer import *

cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(ProjectFilter(id="", name="darp*"), None, None, None)
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects?filters={param}")
print(f"Response: {resp.json()}")</pre>
Результат может быть следующим

<pre class="">[
{
"project":
{
"id": "019abb61-8cd3-7437-957d-aed0c87e603a",
"name": "darpa-clone",
"time": "2025-11-25T14:18:43.79526Z",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000"
},
"branches":
[
{
"id": "019abb61-83b1-7d80-8d23-ce849387bd6e",
"name": "master",
"time": "2025-11-25T14:18:41.457887Z",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000"
}
]
},
{
"project":
{
"id": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"name": "darpa",
"time": "2020-04-03T04:54:13.754864Z",
"created_by": "importer",
"created_by_id": null
},
"branches":
[
{
"id": "ab179fad-c96a-498d-8407-2a3c82719385",
"name": "master",
"time": "2020-04-03T04:54:13.754864Z",
"created_by": "importer",
"created_by_id": null
}
]
}
]</pre>
==== Точка входа /api/public/projects/{project_id}/branch/{branch_id}/snapshots ====

С помощью данной точки входа можно получить список снимков, указанной ветки. Пример кода, для получения снимков с именем "ver. 2.7.0*"

<pre class="">from filters import *
from svacer import *
import json

def get_snapshots(pr_id, br_id):
cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(None,None,SnapshotFilter(id="",name="ver. 2.7.0*"), None)
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects/{pr_id}/branch/{br_id}/snapshots?filters={param}")
fmt = json.dumps(resp.json())
print(f"Response: {fmt}")

get_snapshots("e6abca1b-23a0-4107-9120-4d8d3596030b","ab179fad-c96a-498d-8407-2a3c82719385")
</pre>
Возможный вывод команды:

<pre class="">[
{
"id": "4242b43a-da44-44ca-9b28-770295b98493",
"name": " ver. 2.7.1 200419 05:55",
"time": "2020-04-03T04:56:49.006218Z",
"link": "http://swarm-mgr.home:10142/mode/review/project/e6abca1b-23a0-4107-9120-4d8d3596030b/branch/ab179fad-c96a-498d-8407-2a3c82719385/snapshot/4242b43a-da44-44ca-9b28-770295b98493",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"import_time": "2019-04-20T04:26:52Z",
"details":
{
"branch": "master",
"branchIDHint": "4d1f1413-c638-4a8b-aa4d-d9fccd8df3e9",
"buildObject": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"dxrIncluded": true,
"host":
{
"hostname": "seroshki",
"user": "sergey"
},
"id": "4242b43a-da44-44ca-9b28-770295b98493",
"importTime": "2019-04-20T04:26:52Z",
"migration-data":
{
"DXR": "ce03cd6d1bd54eac92e227d4184356a90b64b7c1",
"SOURCE_TREE": "0949114563f48d5a2df6e94816b7b1095b6c6540",
"date": "2019-04-20T04:26:52Z",
"description": " ver. 2.7.1 200419 05:55",
"id": "2af625b5faad4083be881135ad1daf6b304e4c99",
"owner": "7a831745d52244db2a4f1692f0c473e61f0f0157",
"parent_id": "0d491fde062e2795a4b38758488a47bf8481d03c",
"sourceData": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"svres": "2af625b5faad4083be881135ad1daf6b304e4c99.svres.gzip",
"type": "snapshot",
"user": "jenkins"
},
"project": "darpa",
"projectIDHint": "354c9c94-7b57-4427-8ce0-c41f1e59e6c2",
"snapshot": " ver. 2.7.1 200419 05:55",
"sourceIncluded": true
}
},
{
"id": "4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"name": " ver. 2.7.1 130419 07:39",
"time": "2020-04-03T04:58:53.618464Z",
"link": "http://swarm-mgr.home:10142/mode/review/project/e6abca1b-23a0-4107-9120-4d8d3596030b/branch/ab179fad-c96a-498d-8407-2a3c82719385/snapshot/4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"import_time": "2019-04-13T04:33:46Z",
"details":
{
"branch": "master",
"branchIDHint": "c472aab7-d53f-496c-9d3d-069c0901d9bb",
"buildObject": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"dxrIncluded": false,
"host":
{
"hostname": "seroshki",
"user": "sergey"
},
"id": "4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"importTime": "2019-04-13T04:33:46Z",
"migration-data":
{
"DXR": "ce03cd6d1bd54eac92e227d4184356a90b64b7c1",
"SOURCE_TREE": "0949114563f48d5a2df6e94816b7b1095b6c6540",
"date": "2019-04-13T04:33:46Z",
"description": " ver. 2.7.1 130419 07:39",
"id": "0d491fde062e2795a4b38758488a47bf8481d03c",
"owner": "7a831745d52244db2a4f1692f0c473e61f0f0157",
"parent_id": "edca1583aa41489d37ae9fb2c348ad066ecd3ab3",
"sourceData": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"svres": "0d491fde062e2795a4b38758488a47bf8481d03c.svres.gzip",
"type": "snapshot",
"user": "jenkins"
},
"project": "darpa",
"projectIDHint": "cf032d99-2efe-4ee0-8db8-ee85ff17b296",
"snapshot": " ver. 2.7.1 130419 07:39",
"sourceIncluded": false
}
}
]</pre>
==== Точка входа /api/public/projects/{project_id}/branch/{branch_id}/snapshots/{snapshot_id}/fullmarkers ====

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

* трассу ошибки (параметр traces, возможные значения true,false)
* информацию о чекере (параметр checker_info, возможные значения true,false)
* историю разметки (параметр review_history, возможные значения true,false)
* история комментария (параметр comment_history, возможные значения true,false)
* идентификатор пользовательского фильтра (параметр custom_filter)
* фильтр на параметры маркера

Пример кода, для получения всего множества информации о маркерах в некотором снимке, размеченных со статусом Conf*:

<pre class="">def get_markers (pr_id, br_id, snap_id):
cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(None, None, None, MarkerFilter(severity="*",
file="*", checker="*", review="Conf*"))
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects/{pr_id}/branch/{br_id}/snapshots/{snap_id}/fullmarkers?traces=true&checker_info=true&review_history=true&comment_history=true&filters={param}")
fmt = json.dumps(resp.json())
print(f"Response: {fmt}")

get_markers("e6abca1b-23a0-4107-9120-4d8d3596030b","ab179fad-c96a-498d-8407-2a3c82719385","250a4ff1-bfc8-439a-834d-18b62a545d8d") </pre>
Возможный вывод:

<pre class="">[
{
"id": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"file": "/mnt/scratch/sources/darpa-source/challenges/Divelogger2/lib/string.cc",
"function": "_ZN6StringaSERKS_",
"line": 179,
"locID": 1006,
"lang": "CXX",
"tool": "SvEng",
"warnClass": "ASSIGN_NO_CHECK_FOR_THIS",
"mtid": "SvEng.LA.4",
"msg": "Method 'operator=' doesn't check its argument with 'this' pointer.",
"details": "d96c832835f414a119ea8c7575a8926378fd7cf6",
"flags": 0,
"traces": [
{
"role": "declaration",
"locations": [
{
"file": "/mnt/scratch/sources/darpa-source/challenges/Divelogger2/lib/string.cc",
"line": 179,
"col": 0,
"spec": false,
"info": "declaration"
}
]
}
],
"checker_severity": "Normal",
"checker_reliability": "High",
"checker_origin": "builtin",
"review": {
"id": "65796",
"status": "Confirmed",
"severity": "Major",
"action": "Fix required",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:25.216816Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba"
},
"review_history": [
{
"id": "65796",
"status": "Confirmed",
"severity": "Major",
"action": "Fix required",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:25.216816Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "250a4ff1-bfc8-439a-834d-18b62a545d8d",
"markerID": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 300319 07:08",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:40.524836Z"
}
},
{
"id": "65795",
"status": "Confirmed",
"severity": "Major",
"action": "Undecided",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:21.683963Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "250a4ff1-bfc8-439a-834d-18b62a545d8d",
"markerID": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 300319 07:08",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:40.524836Z"
}
},
{
"id": "63495",
"status": "Confirmed",
"severity": "Unspecified",
"action": "Undecided",
"createdBy": "reviewer",
"created_by_id": "077fdd75-b382-4008-97c4-ec6ef8732ccd",
"time": "2022-04-05T11:47:47.026161Z",
"createdFrom": "a94f92f4-4e3e-4071-9f10-aa8e4389dd0a",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "4242b43a-da44-44ca-9b28-770295b98493",
"markerID": "a94f92f4-4e3e-4071-9f10-aa8e4389dd0a",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 200419 05:55",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:49.006218Z"
},
"reviewer_attrs": ["review_master"]
}
],
"comments": [
{
"id": "e3287eb2-9e64-4780-a1c0-22ed9393a226",
"text": "aaaaaaaaa",
"type": "txt",
"ref": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdBy": "admin",
"created_by_id": "",
"invariant": "",
"createTs": "2025-11-25T15:04:11.358138Z",
"updateTs": "2025-11-25T15:04:17.220568Z",
"history": [
{
"id": "019abb8b-4244-7931-81f7-a7d1a4512de0",
"comment_id": "e3287eb2-9e64-4780-a1c0-22ed9393a226",
"comment_ref": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"text": "aaaa",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"create_ts": "2025-11-25T15:04:11.358138Z"
}
]
}
],
"invariant": "1pQ3T5bq6AMYEYJqzFsW+Q"
}
]
</pre>
Следует заметить, что данный метод может требовать достаточно большого времени выполнения для проектов с большим количеством предупреждений.

Help:Public API

2025-11-25T15:14:16Z

Chernykov sv: /* Примеры использования public REST API */

== Публичные REST запросы ==

Для работы с сервером через различные приложения реализованы публичные запросы, которые не будут меняться при обновлении самого сервера. Если будут происходить значимые изменения, то запрос будет помечаться как deprecated и создаваться новый такой же запрос с пометкой '''/api/some/request/v2'''.

=== Получение токена ===

Для большинства запросов требуется JWT-токен, чтобы его получить нужно пройти аутентификацию. Это можно сделать двумя способами:

* Простой способ — POST запрос с basic auth на '''/api/login''', который вернёт JWT-токен в body. Использование данного способа не желательно, так как он может меняться в будущем, а также не всегда правильно обрабатывает спец. символы и кириллицу в логине/пароле. Пример:
<pre>curl -X POST -u admin:admin http://svacer.example.com/api/login</pre>
* Предпочтительный способ — POST запрос на '''/api/public/login''' с передачей данных в теле запроса, как описано [[#public-api-login|ниже]]. Пример:
<pre>curl -X POST -d '{"login": "admin", "password": "admin"}' http://svacer.example.com/api/public/login</pre>

Полученный токен надо добавлять в header всех запросов: <code>Authorization: Bearer <token></code>

=== Базовые публичные запросы ===

{| class="wikitable"
| '''/api/public/login'''
| POST
| <span id="public-api-login" />Аутентификация пользователя. Тело запроса имеет формат JSON и выглядит следующим образом:
{
"auth_type": "string",
"server": "string"
"login": "string",
"password": "string"
}
* auth_type — тип аутентификации: при указании значения "ldap" — аутентификация через LDAP, во всех остальных случаях, или если поле не указано — по внутренней базе пользователей Svacer
* server — имя LDAP-сервера, как он указан в конфигурационном файле LDAP (поле name) при запуске Svacer. Значение поля учитывается, только если <code>"auth_type": "ldap"</code>, в иных случаях его можно не указывать
* login — логин пользователя, обязательное поле
* password — пароль пользователя, обязательное поле
|-
| '''/api/public/help'''
| GET
| Дополнительная информация по public REST API. Работает без авторизации
|-
| '''/api/health'''
| GET
| Проверка доступности сервера. Не требует авторизации. Возвращает статус 200 OK если сервер работает
|}

Описание остальных запросов смотрите в спецификации OpenAPI на вашем сервере Svacer по адресу <code>/api/public/swagger/</code>

Также можете посмотреть на нашем демо-сервере: https://svacer-demo.ispras.ru/api/public/swagger/

== Управление контейнерами ==
См. [[Help:Public API/management/containers]]

== Экспорт, импорт и копирование разметки ==
См. [[Markup2]]

== Примеры использования public REST API ==

=== Получение URL загруженного снимка ===

Этот пример работает только с python3 и не работает при аутентификации в Svacer через LDAP.

Скачайте и распакуйте [[Media:get_link.zip|get_link.zip]]

Запрос:
<pre>python get_link.py --url http://svacer.example.com:8080 --user admin --password admin --project bash</pre>

Ответ:
<pre>http://svacer.example.com:8080/mode/review/project/0fd645aa-8e70-4a4f-b68b-766c4f337bf2/branch/8925df5a-7a98-4f07-bc88-ee4ea5b43813/snapshot/e3367efa-a804-4c05-9a7a-a7cb052bef1d</pre>

=== Примеры использования фильтров в public api ===

==== Вспомогательные модули ====

В некоторых примерах API используется фильтр, с помощью которого можно ограничить вывод данных и получить более точные результаты. Для работы с этим фильтром используются следующие классы:

<pre class="">import requests
from requests import auth
from requests.models import HTTPBasicAuth
import json
from dataclasses import dataclass
import sys
import base64

def printerr(text):
#print in stderr and exit
print(f"{text}", file=sys.stderr, flush=True)
exit()

@dataclass
class ProjectFilter:
id: str
name: str

class ProjectFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class BranchFilter:
id: str
name: str

class BranchFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class SnapshotFilter:
id: str
name: str

class SnapshotFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class MarkerFilter:
severity: str
file: str
checker: str
review: str

class MarkerFilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

@dataclass
class Filter:
project: ProjectFilter
branch: BranchFilter
snapshot: SnapshotFilter
marker: MarkerFilter

class FilterEncoder(json.JSONEncoder):
def default(self, o):
return o.__dict__

def CreateFilterParam(filter: Filter):
jsoned = FilterEncoder().encode(filter)
b64ed = base64.b64encode(jsoned.encode("utf-8"))
return b64ed.decode("utf-8")
</pre>
Принцип использования классов следующий:

# Создается экземпляр нужного класса XXXXFilter
# Создается base64 строка на основе объекта пункта 1, которая в дальнейшем передается в url запросе. Для этого используется метод CreateFilterParam()

Например. Для создания фильтра, ограничивающего множество проектов выражением darpa*, можно использовать следующие строчки кода:

<pre class="">f: Filter = Filter(ProjectFilter(id="", name="darp*"), None, None, None)
param = CreateFilterParam(f)</pre>
Как можно заметить из определения фильтра, для проекта, ветки и снимка - можно указать как имя так и ID. Имя можно указать с использованием регулярного выражения. ID необходимо указать полностью.

==== Точка входа api/public/login ====

Данный класс может быть использован для соединения с сервером Svacer. В данном модуле демонстрируется взаимодействие с точкой входа /api/public/login.

<pre class="">import requests

class SvacerClient:
def __init__(self, host, user, password):
"""
Initialize the Svacer client
"""
self.host = host
self.user = user
self.password = password
self.token = None
self.auth_header = None
self.session = requests.Session() # Use session for connection pooling
self.set_auth_token()

def set_auth_token(self):
"""
Get authorization token using /api/public/login and setup in session
"""
try:
response = requests.post(
url=f"{self.host}/api/public/login",
json={
"login":self.user,
"password":self.password,
},
verify=False
)
response.raise_for_status() # Raise an exception for bad status codes
body = response.json()
self.token = body["token"]
self.auth_header = {'Authorization': f'Bearer {self.token}'}

# Set the authorization header in the session
self.session.headers.update(self.auth_header)

return self.token

except requests.exceptions.RequestException as e:
raise Exception(f"Failed to get authentication token: {e}")
except KeyError as e:
raise Exception(f"Token not found in response: {e}")

def post(self, endpoint, data=None, json=None, **kwargs):
"""
Make a POST request to the API

"""
if self.auth_header is None:
raise Exception("No authentication token available. Call get_auth_token() first.")

url = f"{self.host}{endpoint}"

try:
response = self.session.post(
url,
data=data,
json=json,
verify=False,
**kwargs
)
response.raise_for_status()
return response

except requests.exceptions.RequestException as e:
raise Exception(f"POST request failed: {e}")

def get(self, endpoint, params=None, **kwargs):
"""
Make a GET request to the API

"""
if self.auth_header is None:
raise Exception("No authentication token available. Call get_auth_token() first.")

url = f"{self.host}{endpoint}"

try:
response = self.session.get(
url,
params=params,
verify=False,
**kwargs
)
response.raise_for_status()
return response

except requests.exceptions.RequestException as e:
raise Exception(f"GET request failed: {e}")
</pre>
==== Точка входа /api/public/projects ====

В данном примере выводятся в формате json список проектов, имя которых соответствует регулярному выражению darpa*

<pre class="">from filters import *
from svacer import *

cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(ProjectFilter(id="", name="darp*"), None, None, None)
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects?filters={param}")
print(f"Response: {resp.json()}")</pre>
Результат может быть следующим

<pre class="">[
{
"project":
{
"id": "019abb61-8cd3-7437-957d-aed0c87e603a",
"name": "darpa-clone",
"time": "2025-11-25T14:18:43.79526Z",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000"
},
"branches":
[
{
"id": "019abb61-83b1-7d80-8d23-ce849387bd6e",
"name": "master",
"time": "2025-11-25T14:18:41.457887Z",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000"
}
]
},
{
"project":
{
"id": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"name": "darpa",
"time": "2020-04-03T04:54:13.754864Z",
"created_by": "importer",
"created_by_id": null
},
"branches":
[
{
"id": "ab179fad-c96a-498d-8407-2a3c82719385",
"name": "master",
"time": "2020-04-03T04:54:13.754864Z",
"created_by": "importer",
"created_by_id": null
}
]
}
]</pre>
==== Точка входа /api/public/projects/{project_id}/branch/{branch_id}/snapshots ====

С помощью данной точки входа можно получить список снимков, указанной ветки. Пример кода, для получения снимков с именем "ver. 2.7.0*"

<pre class="">from filters import *
from svacer import *
import json

def get_snapshots(pr_id, br_id):
cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(None,None,SnapshotFilter(id="",name="ver. 2.7.0*"), None)
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects/{pr_id}/branch/{br_id}/snapshots?filters={param}")
fmt = json.dumps(resp.json())
print(f"Response: {fmt}")

get_snapshots("e6abca1b-23a0-4107-9120-4d8d3596030b","ab179fad-c96a-498d-8407-2a3c82719385")
</pre>
Возможный вывод команды:

<pre class="">[
{
"id": "4242b43a-da44-44ca-9b28-770295b98493",
"name": " ver. 2.7.1 200419 05:55",
"time": "2020-04-03T04:56:49.006218Z",
"link": "http://swarm-mgr.home:10142/mode/review/project/e6abca1b-23a0-4107-9120-4d8d3596030b/branch/ab179fad-c96a-498d-8407-2a3c82719385/snapshot/4242b43a-da44-44ca-9b28-770295b98493",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"import_time": "2019-04-20T04:26:52Z",
"details":
{
"branch": "master",
"branchIDHint": "4d1f1413-c638-4a8b-aa4d-d9fccd8df3e9",
"buildObject": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"dxrIncluded": true,
"host":
{
"hostname": "seroshki",
"user": "sergey"
},
"id": "4242b43a-da44-44ca-9b28-770295b98493",
"importTime": "2019-04-20T04:26:52Z",
"migration-data":
{
"DXR": "ce03cd6d1bd54eac92e227d4184356a90b64b7c1",
"SOURCE_TREE": "0949114563f48d5a2df6e94816b7b1095b6c6540",
"date": "2019-04-20T04:26:52Z",
"description": " ver. 2.7.1 200419 05:55",
"id": "2af625b5faad4083be881135ad1daf6b304e4c99",
"owner": "7a831745d52244db2a4f1692f0c473e61f0f0157",
"parent_id": "0d491fde062e2795a4b38758488a47bf8481d03c",
"sourceData": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"svres": "2af625b5faad4083be881135ad1daf6b304e4c99.svres.gzip",
"type": "snapshot",
"user": "jenkins"
},
"project": "darpa",
"projectIDHint": "354c9c94-7b57-4427-8ce0-c41f1e59e6c2",
"snapshot": " ver. 2.7.1 200419 05:55",
"sourceIncluded": true
}
},
{
"id": "4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"name": " ver. 2.7.1 130419 07:39",
"time": "2020-04-03T04:58:53.618464Z",
"link": "http://swarm-mgr.home:10142/mode/review/project/e6abca1b-23a0-4107-9120-4d8d3596030b/branch/ab179fad-c96a-498d-8407-2a3c82719385/snapshot/4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"import_time": "2019-04-13T04:33:46Z",
"details":
{
"branch": "master",
"branchIDHint": "c472aab7-d53f-496c-9d3d-069c0901d9bb",
"buildObject": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"dxrIncluded": false,
"host":
{
"hostname": "seroshki",
"user": "sergey"
},
"id": "4f706c3a-fdac-475e-bb0a-8bdd753879ca",
"importTime": "2019-04-13T04:33:46Z",
"migration-data":
{
"DXR": "ce03cd6d1bd54eac92e227d4184356a90b64b7c1",
"SOURCE_TREE": "0949114563f48d5a2df6e94816b7b1095b6c6540",
"date": "2019-04-13T04:33:46Z",
"description": " ver. 2.7.1 130419 07:39",
"id": "0d491fde062e2795a4b38758488a47bf8481d03c",
"owner": "7a831745d52244db2a4f1692f0c473e61f0f0157",
"parent_id": "edca1583aa41489d37ae9fb2c348ad066ecd3ab3",
"sourceData": "cf43335308de8b7b3ae03735a7f738a6e9246f52",
"svres": "0d491fde062e2795a4b38758488a47bf8481d03c.svres.gzip",
"type": "snapshot",
"user": "jenkins"
},
"project": "darpa",
"projectIDHint": "cf032d99-2efe-4ee0-8db8-ee85ff17b296",
"snapshot": " ver. 2.7.1 130419 07:39",
"sourceIncluded": false
}
}
]</pre>
==== Точка входа /api/public/projects/{project_id}/branch/{branch_id}/snapshots/{snapshot_id}/fullmarkers ====

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

* трассу ошибки (параметр traces, возможные значения true,false)
* информацию о чекере (параметр checker_info, возможные значения true,false)
* историю разметки (параметр review_history, возможные значения true,false)
* история комментария (параметр comment_history, возможные значения true,false)
* идентификатор пользовательского фильтра (параметр custom_filter)
* фильтр на параметры маркера

Пример кода, для получения всего множества информации о маркерах в некотором снимке, размеченных со статусом Conf*:

<pre class="">def get_markers (pr_id, br_id, snap_id):
cl = SvacerClient(host="http://swarm-mgr:10142",user="admin",password="admin")
f: Filter = Filter(None, None, None, MarkerFilter(severity="*",
file="*", checker="*", review="Conf*"))
param = CreateFilterParam(f)
resp=cl.get(f"/api/public/projects/{pr_id}/branch/{br_id}/snapshots/{snap_id}/fullmarkers?traces=true&checker_info=true&review_history=true&comment_history=true&filters={param}")
fmt = json.dumps(resp.json())
print(f"Response: {fmt}")

get_markers("e6abca1b-23a0-4107-9120-4d8d3596030b","ab179fad-c96a-498d-8407-2a3c82719385","250a4ff1-bfc8-439a-834d-18b62a545d8d") </pre>
Возможный вывод:

<pre class="">[
{
"id": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"file": "/mnt/scratch/sources/darpa-source/challenges/Divelogger2/lib/string.cc",
"function": "_ZN6StringaSERKS_",
"line": 179,
"locID": 1006,
"lang": "CXX",
"tool": "SvEng",
"warnClass": "ASSIGN_NO_CHECK_FOR_THIS",
"mtid": "SvEng.LA.4",
"msg": "Method 'operator=' doesn't check its argument with 'this' pointer.",
"details": "d96c832835f414a119ea8c7575a8926378fd7cf6",
"flags": 0,
"traces": [
{
"role": "declaration",
"locations": [
{
"file": "/mnt/scratch/sources/darpa-source/challenges/Divelogger2/lib/string.cc",
"line": 179,
"col": 0,
"spec": false,
"info": "declaration"
}
]
}
],
"checker_severity": "Normal",
"checker_reliability": "High",
"checker_origin": "builtin",
"review": {
"id": "65796",
"status": "Confirmed",
"severity": "Major",
"action": "Fix required",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:25.216816Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba"
},
"review_history": [
{
"id": "65796",
"status": "Confirmed",
"severity": "Major",
"action": "Fix required",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:25.216816Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "250a4ff1-bfc8-439a-834d-18b62a545d8d",
"markerID": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 300319 07:08",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:40.524836Z"
}
},
{
"id": "65795",
"status": "Confirmed",
"severity": "Major",
"action": "Undecided",
"createdBy": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"time": "2025-11-25T15:04:21.683963Z",
"createdFrom": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "250a4ff1-bfc8-439a-834d-18b62a545d8d",
"markerID": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 300319 07:08",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:40.524836Z"
}
},
{
"id": "63495",
"status": "Confirmed",
"severity": "Unspecified",
"action": "Undecided",
"createdBy": "reviewer",
"created_by_id": "077fdd75-b382-4008-97c4-ec6ef8732ccd",
"time": "2022-04-05T11:47:47.026161Z",
"createdFrom": "a94f92f4-4e3e-4071-9f10-aa8e4389dd0a",
"createdFromContext": {
"projectID": "e6abca1b-23a0-4107-9120-4d8d3596030b",
"branchID": "ab179fad-c96a-498d-8407-2a3c82719385",
"snapshotID": "4242b43a-da44-44ca-9b28-770295b98493",
"markerID": "a94f92f4-4e3e-4071-9f10-aa8e4389dd0a",
"projectName": "darpa",
"branchName": "master",
"snapshotName": " ver. 2.7.1 200419 05:55",
"created_by": "importer",
"created_by_id": "00000000-0000-0000-0000-000000000002",
"create_ts": "2020-04-03T04:56:49.006218Z"
},
"reviewer_attrs": ["review_master"]
}
],
"comments": [
{
"id": "e3287eb2-9e64-4780-a1c0-22ed9393a226",
"text": "aaaaaaaaa",
"type": "txt",
"ref": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"createdBy": "admin",
"created_by_id": "",
"invariant": "",
"createTs": "2025-11-25T15:04:11.358138Z",
"updateTs": "2025-11-25T15:04:17.220568Z",
"history": [
{
"id": "019abb8b-4244-7931-81f7-a7d1a4512de0",
"comment_id": "e3287eb2-9e64-4780-a1c0-22ed9393a226",
"comment_ref": "ab877a02-03ac-41ac-8b87-46f7e76791ba",
"text": "aaaa",
"created_by": "admin",
"created_by_id": "00000000-0000-0000-0000-000000000000",
"create_ts": "2025-11-25T15:04:11.358138Z"
}
]
}
],
"invariant": "1pQ3T5bq6AMYEYJqzFsW+Q"
}
]
</pre>
Следует заметить, что данный метод может требовать достаточно большого времени выполнения для проектов с большим количеством предупреждений.

Help:Installation

2025-11-19T08:08:51Z

Chernykov sv: /* Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помощью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock --user admin --password admin --login locked_user</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настривается в конфигурационном файле в секции webhook. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см.Модель поддерживаемых событий) и отправляется на обработку в каждую из настроеных целей, которыми являются http обработчики. Отправкой занимаются работники (их количествово настраивается в конфигурационном файле в параметре workers_count). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр ca_certs конфигурационного файла. Работникам можно указать таймаут соединения с webhook сервером (в мс, по умолчанию 1000мс, параметр timeout) и количество попыток отправки (по умолчанию - одна попытка, параметр retry_count).

В настройках можно указать фильтр на отправляемые события (параметр filter). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр journal_length). По умолчанию он равен 86400 штук записей - по 1 штуку на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.<br />
Для настройки аутентификации работника можно использовать параметр headers, который представляет собой список значений вида key:value. Данные пары будут добавлены в заголовки каждого http запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer serever webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (осообенно интересными могут быть поля sendError и skip)

Пример вывода для первой команды (с флагом --humanize; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]
}
==== Модель поддерживамых событий ====
syntax = "proto3";
import "google/protobuf/any.proto";
option go_package="svacer/proto/webhook";
package webhook;

enum EventType {
EventNone = 0;
EventTest = 1;
EventReviewMarker = 2;
EventPurgeReview = 3;
EventGroupReview = 4;
EventImportSnapshot = 5;
EventCopySnapshot = 6;
EventNewComment = 7;
EventUpdateComment = 8;
EventNewContainer = 9;
EventDeleteContainer = 10;
EventUpdateContainer =11;
EventImportMarkup = 12;
EventDeleteSnapshot = 13;
UpdateSnapshot = 14;
}

message MarkerDetails {
string id = 1;
string file = 2;
string line = 3;
string lang = 4;
}

message Event {
uint64 timestamp = 1;
EventType type = 2;
string created_by = 3;
google.protobuf.Any payload = 4;
}

message PayloadMarkerReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
repeated MarkerDetails markers = 7;
string comment = 8;
string severity = 9;
string action = 10;
string status = 11;
bool group_review = 12;
string created_by_id = 13;
string created_by_login = 14;
}

message PayloadPurgeReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string created_by_id = 5;
string created_by_login = 6;
}

message PayloadImportSnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
}

message PayloadMarkerComment {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
MarkerDetails marker = 7;
string comment = 8;
string created_by_id = 9;
string created_by_login = 10;
}

message PayloadCopySnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
string created_by_id = 7;
string created_by_login = 8;
}

message Container {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
Container source = 5;

}

message PayloadNewContainer {
repeated Container containers = 1;
}

message PayloadDeleteContainer {
repeated Container projects = 1;
repeated Container branches = 2;
}

message PayloadUpdateContainer {
Container container = 1;
}

message CopyResult {
uint64 total = 1;
uint64 applied_reviews = 2;
uint64 applied_comments = 3;
uint64 skipped_reviews = 4;
uint64 duplicate_reviews = 5;
uint64 duplicate_comments = 6;
}

message PayloadImportMarkup {
Container source=1;
Container target=2;
CopyResult copy_result =3;

}

message Snapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}
message PayloadDeleteSnapshots {
repeated Snapshot snapshots = 1;
}

message PayloadUpdateSnapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Help:Installation

2025-11-19T07:55:19Z

Chernykov sv: /* Настройка защиты от перебора паролей пользователей */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помозью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock --user admin --password admin --login locked_user</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настривается в конфигурационном файле в секции webhook. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см.Модель поддерживаемых событий) и отправляется на обработку в каждую из настроеных целей, которыми являются http обработчики. Отправкой занимаются работники (их количествово настраивается в конфигурационном файле в параметре workers_count). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр ca_certs конфигурационного файла. Работникам можно указать таймаут соединения с webhook сервером (в мс, по умолчанию 1000мс, параметр timeout) и количество попыток отправки (по умолчанию - одна попытка, параметр retry_count).

В настройках можно указать фильтр на отправляемые события (параметр filter). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр journal_length). По умолчанию он равен 86400 штук записей - по 1 штуку на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.<br />
Для настройки аутентификации работника можно использовать параметр headers, который представляет собой список значений вида key:value. Данные пары будут добавлены в заголовки каждого http запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer serever webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (осообенно интересными могут быть поля sendError и skip)

Пример вывода для первой команды (с флагом --humanize; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]
}
==== Модель поддерживамых событий ====
syntax = "proto3";
import "google/protobuf/any.proto";
option go_package="svacer/proto/webhook";
package webhook;

enum EventType {
EventNone = 0;
EventTest = 1;
EventReviewMarker = 2;
EventPurgeReview = 3;
EventGroupReview = 4;
EventImportSnapshot = 5;
EventCopySnapshot = 6;
EventNewComment = 7;
EventUpdateComment = 8;
EventNewContainer = 9;
EventDeleteContainer = 10;
EventUpdateContainer =11;
EventImportMarkup = 12;
EventDeleteSnapshot = 13;
UpdateSnapshot = 14;
}

message MarkerDetails {
string id = 1;
string file = 2;
string line = 3;
string lang = 4;
}

message Event {
uint64 timestamp = 1;
EventType type = 2;
string created_by = 3;
google.protobuf.Any payload = 4;
}

message PayloadMarkerReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
repeated MarkerDetails markers = 7;
string comment = 8;
string severity = 9;
string action = 10;
string status = 11;
bool group_review = 12;
string created_by_id = 13;
string created_by_login = 14;
}

message PayloadPurgeReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string created_by_id = 5;
string created_by_login = 6;
}

message PayloadImportSnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
}

message PayloadMarkerComment {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
MarkerDetails marker = 7;
string comment = 8;
string created_by_id = 9;
string created_by_login = 10;
}

message PayloadCopySnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
string created_by_id = 7;
string created_by_login = 8;
}

message Container {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
Container source = 5;

}

message PayloadNewContainer {
repeated Container containers = 1;
}

message PayloadDeleteContainer {
repeated Container projects = 1;
repeated Container branches = 2;
}

message PayloadUpdateContainer {
Container container = 1;
}

message CopyResult {
uint64 total = 1;
uint64 applied_reviews = 2;
uint64 applied_comments = 3;
uint64 skipped_reviews = 4;
uint64 duplicate_reviews = 5;
uint64 duplicate_comments = 6;
}

message PayloadImportMarkup {
Container source=1;
Container target=2;
CopyResult copy_result =3;

}

message Snapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}
message PayloadDeleteSnapshots {
repeated Snapshot snapshots = 1;
}

message PayloadUpdateSnapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Release notes 12-0-0

2025-11-18T14:05:49Z

Chernykov sv: /* Веб-хуки для нотификаций */

== Разметка маркеров с помощью AI ==
Добавлена возможность разметки маркеров с помощью ассистента AI, который на основании модели, обученной на множестве размеченных данных, предсказывает статус разметки маркера False Positive или Confirmed.

Если пользователь применяет предсказанный статус маркера, то к маркеру автоматически добавляется комментарий с информацией о дате разметки, используемой модели AI и уровне доверия, также маркеру добавляется метка '''AI'''.

{{Note|type=info|text=''Прогнозируемый ассистентом AI статус разметки маркера носит рекомендательный характер. Окончательное решение о применении предсказанного моделью статуса остается за пользователем.''}}

Форма разметки с помощью AI открывается включением параметра '''Режим разметки с помощью AI''' на стандартных формах разметки маркера или групповой разметки маркера.

Если текущий статус разметки маркера совпадает со статусом, предсказанным моделью AI, то такой маркер повторно разметить с помощью AI нельзя.

[[File:Review marker-1.png|thumb|none|x250px|Форма разметки одного маркера]]

[[File:Review marker-2.png|thumb|none|x250px|Форма групповой разметки маркеров]]

== Изменения в пользовательских фильтрах ==
В пользовательских фильтрах реализованы дополнительные возможности фильтрации маркеров:

1. Атрибут «'''Период последнего изменения'''» для фильтрации маркеров по дате (периоду) актуальной разметки.

2. Поле ввода шаблона расширенного фильтра для фильтрации маркеров по сложным предикатам, таким как:

* поля маркера, его трассы, разметки и комментариев;
* информацию из контекста (имя проекта, ветки, снимка и т. п.);
* атрибуты снимка (включая пользовательские атрибуты, заданные при импорте);
* статусы разметки;
* текст и атрибуты комментариев.

Описание, как составить выражение для расширенного фильтра, можно получить, кликнув на [[File:icon_question_mark2.png|x25px]].
[[File:Custom filter v12.png|thumb|none|x450px]]

== Изменения в разделе '''Поиск''' ==
В разделе '''Поиск''' выполнены следующие доработки:

1. Реализована возможность просмотра информации о маркере непосредственно в разделе '''Поиск'''.
[[File:Search-1.png|thumb|none|upright=4]]

2. Поиск маркеров по полям расширен дополнительными атрибутами:

* Инвариант маркера;
* ID маркера.

[[File:Search-2.png|thumb|none|upright=4]]

== Изменения на вкладке с исходным кодом файла ==
1. Панель функций перенесена на верх вкладки с файлом исходного кода.

2. Реализована возможность добавления файла в фильтр по файлам, а также исключения файла из фильтра, если он был добавлен ранее.
[[File:Cove view.png|thumb|none|upright=4.5]]

== Сравнение маркеров при их сопоставлении ==
В процессе сопоставления маркеров реализована возможность сравнения маркеров. Это помогает определить причину, почему при импорте снимка маркеры не сопоставились автоматически.
[[File:Match markers-1.png|thumb|none|upright=3.5]]

Форма сравнения маркеров открывается в отдельном диалоговом окне.
[[File:Match markers-2.png|thumb|none|upright=3.5]]

== Просмотр JSON маркера ==
В дополнение к команде копирования JSON маркера добавлена команда просмотра JSON маркера в таблице маркеров и правой панели.
[[File:JSON-1.png|thumb|none|upright=3.5]]

Просмотр JSON осуществляется в отдельном диалоговом окне.
[[File:JSON-2.png|thumb|none|upright=3.5]]

== Изменения в разделе '''Проекты''' ==
1. Фокусировка на ветке master при создании нового проекта.

2. В действия над снимком в списке снимков добавлена команда экспорта кода с разметкой. Все команды экспорта снимка вынесены в отдельное меню.
[[File:Project 1.png|thumb|none|upright=4]]

== Редактирование маркеров при импорте ==

При импорте .svace-dir, SARIF или snap-файла добавлена возможность (опция) задать правила трансформации, пропуска и дедупликации маркеров. Правила задаются в JSON-формате.

При импорте в CLI данная опция называется edit-markers и позволяет указать путь к JSON-файлу с правилами. Подробнее здесь: [[Edit markers (command line)]].

В пользовательском интерфейсе при импорте .svace-dir или SARIF возможно задать данную опцию и в ней указать путь к JSON-файлу в архиве .svace-dir или SARIF. А при импорте snap-файла возможно как подгрузить JSON-файл, так и ввести выражение в формате JSON в поле ввода.

[[File:Edit markers svace-dir.png|thumb|none|upright=3|Форма импорта .svace-dir]]
[[File:Edit_markers_sarif.png|thumb|none|upright=3|Форма импорта SARIF]]
[[File:Edit markers snap.png|thumb|none|upright=3|Форма импорта snap-файла]]

== Добавлена форма управления асинхронными задачами ==
В разделе '''Настройки > Асинхронные задачи''', где доступен просмотр и управление (отмена и откат) следующими асинхронными операциями:

* Экспорт snap-файлов;
* Экспорт SARIF;
* Копирование снимков.

Пользователь с серверным доступом '''Администрирование сервера''' может просматривать и управлять запущенными или выполненными асинхронными задачами всех пользователей. Пользователю без данного доступа доступно управление только своими асинхронными задачами.

[[File:Async tasks.png|thumb|none|upright=4|Форма Асинхронные задачи]]

В следующем релизе планируем интегрировать в данный раздел оставшиеся асинхронные операции, которые запускаются пользователями, а именно:

* Импорт snapshot;
* Импорт svace-dir;
* Импорт SARIF;
* Копирование проекта;
* Копирование ветки.

== Изменения в разделе '''Информация о сервере''' ==
В разделе '''Настройки > Информация о сервере''', который доступен пользователям с серверным доступом '''Администрирование сервера''', представление информации разделено на три вкладки:

* Параметры;
* Системный лог;
* Системный журнал.

Т. к. системный лог может иметь большой размер, то вывод информации на форме ограничен последними 1Мб (значение регулируется переменной окружения SVACER_TAIL_LOG_SIZE). Скачивание лога позволяет выгрузить файл полностью.

[[File:Server info-1.png|thumb|none|upright=4|Информация о сервере — вкладка Параметры]]
[[File:Server info-2.png|thumb|none|upright=4|Информация о сервере — вкладка Системный лог]]
[[File:Server info-3.png|thumb|none|upright=4|Информация о сервере — вкладка Системный журнал]]

== Лицензирование Svacer ==
Реализован механизм лицензирования. Просмотр и применение лицензии доступно в CLI, а также в UI, где добавлен раздел Лицензия. Просмотр лицензии доступен всем пользователям, а активация лицензии — пользователям с серверным доступом «Администрирование сервера».

[[File:Licence.png|thumb|none|upright=3.5]]

{{Note|type=info|text=''Функциональность добавлена для возможности будущего развития продукта. В дистрибутив Svacer v.12 лицензия встроена и не вносит никаких ограничений. Срок действия встроенной лицензии — до 31.12.2027.''}}

== Парольная политика ==
Реализована возможность задать парольную политику в конфигурационном файле:

1. Механизм установки минимальной сложности паролей.

Пример задания конфигурационных настроек:
auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"

В поле min_length — минимальная длина пароля. В поле complexity список регулярных выражений, задающих группу требуемых символов. В примере требуется наличие строчных, заглавных букв, цифр и спецсимволов <code>!#</code>.

2. Механизм блокировки учетной записи пользователя при нескольких неудачных попытках авторизации.

Пример задания конфигурационных настроек:

security:
login:
max_attempts: 5
lock_time: 2m

Т. е. учетная запись будет блокироваться на 2 минуты при 5 неудачных попытках авторизации.

Также реализована команда CLI для разблокировки учетной записи пользователя:
svacer user-proiver unlock -login user

Более подробно см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9D%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0_%D0%BF%D0%B0%D1%80%D0%BE%D0%BB%D1%8C%D0%BD%D0%BE%D0%B9_%D0%BF%D0%BE%D0%BB%D0%B8%D1%82%D0%B8%D0%BA%D0%B8_%D0%B2%D0%BD%D1%83%D1%82%D1%80%D0%B5%D0%BD%D0%BD%D0%B5%D0%B3%D0%BE_%D0%BC%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC%D0%B0_%D0%B0%D1%83%D1%82%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D0%B8_Svacer| Парольная политика Svacer]]

== Открытие вкладки LDAP по умолчанию ==
Добавлен параметр конфигурации default. Если он true, то на странице авторизации в пользовательском интерфейсе по умолчанию будет открываться вкладка Svacer, если false — то при наличии сконфигурированного LDAP по умолчанию будет открываться вкладка LDAP, иначе флаг default игнорируется.

Пример задания конфигурационных настроек:
auth:
svacer:
enabled: true
default: false

Более подробную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation| Вкладка LDAP в GUI Svacer]]

== Автоочистка снимков/веток/проектов ==
Расширены опции команды cleanup, вызываемой в CLI:

* cleanup-type — удалять пустые ветки и проекты;
* min-snapshots — нижняя граница по количеству снимков в ветке.

Подробное описание функции и ее опций: [[Help:CLI/cleanup]].

== Веб-хуки для нотификаций ==
Реализован механизм веб-хуков для отправки нотификаций по API во внешние системы. Механизм настраивается в конфигурационном файле в секции webhook.

Реализована отправка нотификаций по следующим событиям:

* разметка маркера / групповая разметка маркеров;
* добавление / обновление комментария маркера;
* добавление / копирование / изменение / удаление контейнеров (группа / проект / ветка);
* импорт / копирование / удаление / изменение снимков;
* копирование разметки.

Пример задания конфигурационных настроек:

webhook:
enabled: true
journalLength: 86400
targets:
- url: "<nowiki>https://swarm-mgr.home:8080/webhook</nowiki>"
workersCount: 1
enabled: true
filter: "Type == 1 and Payload.Status != 'Undecided'"
caCerts: ""
retryCount: 1
timeout: 500

Управление механизмом осуществляется в CLI с помощью команд:

* просмотра записей журнала отправки событий:

svacer server webhook journal

* просмотр статистики по работе службы:

svacer server webhook stat
Более детальную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9C%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC_%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8_%D1%81_%D0%B2%D0%BD%D0%B5%D1%88%D0%BD%D0%B8%D0%BC%D0%B8_%D1%81%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%B0%D0%BC%D0%B8_%D0%BF%D0%BE%D1%81%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B2%D0%BE%D0%BC_Webhook-%D0%BE%D0%B2| Настройка webhook]]

== Удаление неактуальных разделов интерфейса ==
В интерфейсе Svacer были удалены неиспользуемые и не поддерживаемые в актуальном состоянии разделы:

* '''Отчеты'''
* Настройки > '''Oauth Clients'''

Release notes 12-0-0

2025-11-18T14:05:35Z

Chernykov sv: /* Открытие вкладки LDAP по умолчанию */

== Разметка маркеров с помощью AI ==
Добавлена возможность разметки маркеров с помощью ассистента AI, который на основании модели, обученной на множестве размеченных данных, предсказывает статус разметки маркера False Positive или Confirmed.

Если пользователь применяет предсказанный статус маркера, то к маркеру автоматически добавляется комментарий с информацией о дате разметки, используемой модели AI и уровне доверия, также маркеру добавляется метка '''AI'''.

{{Note|type=info|text=''Прогнозируемый ассистентом AI статус разметки маркера носит рекомендательный характер. Окончательное решение о применении предсказанного моделью статуса остается за пользователем.''}}

Форма разметки с помощью AI открывается включением параметра '''Режим разметки с помощью AI''' на стандартных формах разметки маркера или групповой разметки маркера.

Если текущий статус разметки маркера совпадает со статусом, предсказанным моделью AI, то такой маркер повторно разметить с помощью AI нельзя.

[[File:Review marker-1.png|thumb|none|x250px|Форма разметки одного маркера]]

[[File:Review marker-2.png|thumb|none|x250px|Форма групповой разметки маркеров]]

== Изменения в пользовательских фильтрах ==
В пользовательских фильтрах реализованы дополнительные возможности фильтрации маркеров:

1. Атрибут «'''Период последнего изменения'''» для фильтрации маркеров по дате (периоду) актуальной разметки.

2. Поле ввода шаблона расширенного фильтра для фильтрации маркеров по сложным предикатам, таким как:

* поля маркера, его трассы, разметки и комментариев;
* информацию из контекста (имя проекта, ветки, снимка и т. п.);
* атрибуты снимка (включая пользовательские атрибуты, заданные при импорте);
* статусы разметки;
* текст и атрибуты комментариев.

Описание, как составить выражение для расширенного фильтра, можно получить, кликнув на [[File:icon_question_mark2.png|x25px]].
[[File:Custom filter v12.png|thumb|none|x450px]]

== Изменения в разделе '''Поиск''' ==
В разделе '''Поиск''' выполнены следующие доработки:

1. Реализована возможность просмотра информации о маркере непосредственно в разделе '''Поиск'''.
[[File:Search-1.png|thumb|none|upright=4]]

2. Поиск маркеров по полям расширен дополнительными атрибутами:

* Инвариант маркера;
* ID маркера.

[[File:Search-2.png|thumb|none|upright=4]]

== Изменения на вкладке с исходным кодом файла ==
1. Панель функций перенесена на верх вкладки с файлом исходного кода.

2. Реализована возможность добавления файла в фильтр по файлам, а также исключения файла из фильтра, если он был добавлен ранее.
[[File:Cove view.png|thumb|none|upright=4.5]]

== Сравнение маркеров при их сопоставлении ==
В процессе сопоставления маркеров реализована возможность сравнения маркеров. Это помогает определить причину, почему при импорте снимка маркеры не сопоставились автоматически.
[[File:Match markers-1.png|thumb|none|upright=3.5]]

Форма сравнения маркеров открывается в отдельном диалоговом окне.
[[File:Match markers-2.png|thumb|none|upright=3.5]]

== Просмотр JSON маркера ==
В дополнение к команде копирования JSON маркера добавлена команда просмотра JSON маркера в таблице маркеров и правой панели.
[[File:JSON-1.png|thumb|none|upright=3.5]]

Просмотр JSON осуществляется в отдельном диалоговом окне.
[[File:JSON-2.png|thumb|none|upright=3.5]]

== Изменения в разделе '''Проекты''' ==
1. Фокусировка на ветке master при создании нового проекта.

2. В действия над снимком в списке снимков добавлена команда экспорта кода с разметкой. Все команды экспорта снимка вынесены в отдельное меню.
[[File:Project 1.png|thumb|none|upright=4]]

== Редактирование маркеров при импорте ==

При импорте .svace-dir, SARIF или snap-файла добавлена возможность (опция) задать правила трансформации, пропуска и дедупликации маркеров. Правила задаются в JSON-формате.

При импорте в CLI данная опция называется edit-markers и позволяет указать путь к JSON-файлу с правилами. Подробнее здесь: [[Edit markers (command line)]].

В пользовательском интерфейсе при импорте .svace-dir или SARIF возможно задать данную опцию и в ней указать путь к JSON-файлу в архиве .svace-dir или SARIF. А при импорте snap-файла возможно как подгрузить JSON-файл, так и ввести выражение в формате JSON в поле ввода.

[[File:Edit markers svace-dir.png|thumb|none|upright=3|Форма импорта .svace-dir]]
[[File:Edit_markers_sarif.png|thumb|none|upright=3|Форма импорта SARIF]]
[[File:Edit markers snap.png|thumb|none|upright=3|Форма импорта snap-файла]]

== Добавлена форма управления асинхронными задачами ==
В разделе '''Настройки > Асинхронные задачи''', где доступен просмотр и управление (отмена и откат) следующими асинхронными операциями:

* Экспорт snap-файлов;
* Экспорт SARIF;
* Копирование снимков.

Пользователь с серверным доступом '''Администрирование сервера''' может просматривать и управлять запущенными или выполненными асинхронными задачами всех пользователей. Пользователю без данного доступа доступно управление только своими асинхронными задачами.

[[File:Async tasks.png|thumb|none|upright=4|Форма Асинхронные задачи]]

В следующем релизе планируем интегрировать в данный раздел оставшиеся асинхронные операции, которые запускаются пользователями, а именно:

* Импорт snapshot;
* Импорт svace-dir;
* Импорт SARIF;
* Копирование проекта;
* Копирование ветки.

== Изменения в разделе '''Информация о сервере''' ==
В разделе '''Настройки > Информация о сервере''', который доступен пользователям с серверным доступом '''Администрирование сервера''', представление информации разделено на три вкладки:

* Параметры;
* Системный лог;
* Системный журнал.

Т. к. системный лог может иметь большой размер, то вывод информации на форме ограничен последними 1Мб (значение регулируется переменной окружения SVACER_TAIL_LOG_SIZE). Скачивание лога позволяет выгрузить файл полностью.

[[File:Server info-1.png|thumb|none|upright=4|Информация о сервере — вкладка Параметры]]
[[File:Server info-2.png|thumb|none|upright=4|Информация о сервере — вкладка Системный лог]]
[[File:Server info-3.png|thumb|none|upright=4|Информация о сервере — вкладка Системный журнал]]

== Лицензирование Svacer ==
Реализован механизм лицензирования. Просмотр и применение лицензии доступно в CLI, а также в UI, где добавлен раздел Лицензия. Просмотр лицензии доступен всем пользователям, а активация лицензии — пользователям с серверным доступом «Администрирование сервера».

[[File:Licence.png|thumb|none|upright=3.5]]

{{Note|type=info|text=''Функциональность добавлена для возможности будущего развития продукта. В дистрибутив Svacer v.12 лицензия встроена и не вносит никаких ограничений. Срок действия встроенной лицензии — до 31.12.2027.''}}

== Парольная политика ==
Реализована возможность задать парольную политику в конфигурационном файле:

1. Механизм установки минимальной сложности паролей.

Пример задания конфигурационных настроек:
auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"

В поле min_length — минимальная длина пароля. В поле complexity список регулярных выражений, задающих группу требуемых символов. В примере требуется наличие строчных, заглавных букв, цифр и спецсимволов <code>!#</code>.

2. Механизм блокировки учетной записи пользователя при нескольких неудачных попытках авторизации.

Пример задания конфигурационных настроек:

security:
login:
max_attempts: 5
lock_time: 2m

Т. е. учетная запись будет блокироваться на 2 минуты при 5 неудачных попытках авторизации.

Также реализована команда CLI для разблокировки учетной записи пользователя:
svacer user-proiver unlock -login user

Более подробно см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9D%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0_%D0%BF%D0%B0%D1%80%D0%BE%D0%BB%D1%8C%D0%BD%D0%BE%D0%B9_%D0%BF%D0%BE%D0%BB%D0%B8%D1%82%D0%B8%D0%BA%D0%B8_%D0%B2%D0%BD%D1%83%D1%82%D1%80%D0%B5%D0%BD%D0%BD%D0%B5%D0%B3%D0%BE_%D0%BC%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC%D0%B0_%D0%B0%D1%83%D1%82%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D0%B8_Svacer| Парольная политика Svacer]]

== Открытие вкладки LDAP по умолчанию ==
Добавлен параметр конфигурации default. Если он true, то на странице авторизации в пользовательском интерфейсе по умолчанию будет открываться вкладка Svacer, если false — то при наличии сконфигурированного LDAP по умолчанию будет открываться вкладка LDAP, иначе флаг default игнорируется.

Пример задания конфигурационных настроек:
auth:
svacer:
enabled: true
default: false

Более подробную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation| Вкладка LDAP в GUI Svacer]]

== Автоочистка снимков/веток/проектов ==
Расширены опции команды cleanup, вызываемой в CLI:

* cleanup-type — удалять пустые ветки и проекты;
* min-snapshots — нижняя граница по количеству снимков в ветке.

Подробное описание функции и ее опций: [[Help:CLI/cleanup]].

== Веб-хуки для нотификаций ==
Реализован механизм веб-хуков для отправки нотификаций по API во внешние системы. Механизм настраивается в конфигурационном файле в секции webhook.

Реализована отправка нотификаций по следующим событиям:

* разметка маркера / групповая разметка маркеров;
* добавление / обновление комментария маркера;
* добавление / копирование / изменение / удаление контейнеров (группа / проект / ветка);
* импорт / копирование / удаление / изменение снимков;
* копирование разметки.

Пример задания конфигурационных настроек:

webhook:
enabled: true
journalLength: 86400
targets:
- url: "<nowiki>https://swarm-mgr.home:8080/webhook</nowiki>"
workersCount: 1
enabled: true
filter: "Type == 1 and Payload.Status != 'Undecided'"
caCerts: ""
retryCount: 1
timeout: 500

Управление механизмом осуществляется в CLI с помощью команд:

* просмотра записей журнала отправки событий:

svacer server webhook journal

* просмотр статистики по работе службы:

svacer server webhook stat
Более детальную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9C%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC_%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8_%D1%81_%D0%B2%D0%BD%D0%B5%D1%88%D0%BD%D0%B8%D0%BC%D0%B8_%D1%81%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%B0%D0%BC%D0%B8_%D0%BF%D0%BE%D1%81%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B2%D0%BE%D0%BC_Webhook-%D0%BE%D0%B2|Настройка webhook]]

== Удаление неактуальных разделов интерфейса ==
В интерфейсе Svacer были удалены неиспользуемые и не поддерживаемые в актуальном состоянии разделы:

* '''Отчеты'''
* Настройки > '''Oauth Clients'''

Release notes 12-0-0

2025-11-18T14:05:26Z

Chernykov sv: /* Парольная политика */

== Разметка маркеров с помощью AI ==
Добавлена возможность разметки маркеров с помощью ассистента AI, который на основании модели, обученной на множестве размеченных данных, предсказывает статус разметки маркера False Positive или Confirmed.

Если пользователь применяет предсказанный статус маркера, то к маркеру автоматически добавляется комментарий с информацией о дате разметки, используемой модели AI и уровне доверия, также маркеру добавляется метка '''AI'''.

{{Note|type=info|text=''Прогнозируемый ассистентом AI статус разметки маркера носит рекомендательный характер. Окончательное решение о применении предсказанного моделью статуса остается за пользователем.''}}

Форма разметки с помощью AI открывается включением параметра '''Режим разметки с помощью AI''' на стандартных формах разметки маркера или групповой разметки маркера.

Если текущий статус разметки маркера совпадает со статусом, предсказанным моделью AI, то такой маркер повторно разметить с помощью AI нельзя.

[[File:Review marker-1.png|thumb|none|x250px|Форма разметки одного маркера]]

[[File:Review marker-2.png|thumb|none|x250px|Форма групповой разметки маркеров]]

== Изменения в пользовательских фильтрах ==
В пользовательских фильтрах реализованы дополнительные возможности фильтрации маркеров:

1. Атрибут «'''Период последнего изменения'''» для фильтрации маркеров по дате (периоду) актуальной разметки.

2. Поле ввода шаблона расширенного фильтра для фильтрации маркеров по сложным предикатам, таким как:

* поля маркера, его трассы, разметки и комментариев;
* информацию из контекста (имя проекта, ветки, снимка и т. п.);
* атрибуты снимка (включая пользовательские атрибуты, заданные при импорте);
* статусы разметки;
* текст и атрибуты комментариев.

Описание, как составить выражение для расширенного фильтра, можно получить, кликнув на [[File:icon_question_mark2.png|x25px]].
[[File:Custom filter v12.png|thumb|none|x450px]]

== Изменения в разделе '''Поиск''' ==
В разделе '''Поиск''' выполнены следующие доработки:

1. Реализована возможность просмотра информации о маркере непосредственно в разделе '''Поиск'''.
[[File:Search-1.png|thumb|none|upright=4]]

2. Поиск маркеров по полям расширен дополнительными атрибутами:

* Инвариант маркера;
* ID маркера.

[[File:Search-2.png|thumb|none|upright=4]]

== Изменения на вкладке с исходным кодом файла ==
1. Панель функций перенесена на верх вкладки с файлом исходного кода.

2. Реализована возможность добавления файла в фильтр по файлам, а также исключения файла из фильтра, если он был добавлен ранее.
[[File:Cove view.png|thumb|none|upright=4.5]]

== Сравнение маркеров при их сопоставлении ==
В процессе сопоставления маркеров реализована возможность сравнения маркеров. Это помогает определить причину, почему при импорте снимка маркеры не сопоставились автоматически.
[[File:Match markers-1.png|thumb|none|upright=3.5]]

Форма сравнения маркеров открывается в отдельном диалоговом окне.
[[File:Match markers-2.png|thumb|none|upright=3.5]]

== Просмотр JSON маркера ==
В дополнение к команде копирования JSON маркера добавлена команда просмотра JSON маркера в таблице маркеров и правой панели.
[[File:JSON-1.png|thumb|none|upright=3.5]]

Просмотр JSON осуществляется в отдельном диалоговом окне.
[[File:JSON-2.png|thumb|none|upright=3.5]]

== Изменения в разделе '''Проекты''' ==
1. Фокусировка на ветке master при создании нового проекта.

2. В действия над снимком в списке снимков добавлена команда экспорта кода с разметкой. Все команды экспорта снимка вынесены в отдельное меню.
[[File:Project 1.png|thumb|none|upright=4]]

== Редактирование маркеров при импорте ==

При импорте .svace-dir, SARIF или snap-файла добавлена возможность (опция) задать правила трансформации, пропуска и дедупликации маркеров. Правила задаются в JSON-формате.

При импорте в CLI данная опция называется edit-markers и позволяет указать путь к JSON-файлу с правилами. Подробнее здесь: [[Edit markers (command line)]].

В пользовательском интерфейсе при импорте .svace-dir или SARIF возможно задать данную опцию и в ней указать путь к JSON-файлу в архиве .svace-dir или SARIF. А при импорте snap-файла возможно как подгрузить JSON-файл, так и ввести выражение в формате JSON в поле ввода.

[[File:Edit markers svace-dir.png|thumb|none|upright=3|Форма импорта .svace-dir]]
[[File:Edit_markers_sarif.png|thumb|none|upright=3|Форма импорта SARIF]]
[[File:Edit markers snap.png|thumb|none|upright=3|Форма импорта snap-файла]]

== Добавлена форма управления асинхронными задачами ==
В разделе '''Настройки > Асинхронные задачи''', где доступен просмотр и управление (отмена и откат) следующими асинхронными операциями:

* Экспорт snap-файлов;
* Экспорт SARIF;
* Копирование снимков.

Пользователь с серверным доступом '''Администрирование сервера''' может просматривать и управлять запущенными или выполненными асинхронными задачами всех пользователей. Пользователю без данного доступа доступно управление только своими асинхронными задачами.

[[File:Async tasks.png|thumb|none|upright=4|Форма Асинхронные задачи]]

В следующем релизе планируем интегрировать в данный раздел оставшиеся асинхронные операции, которые запускаются пользователями, а именно:

* Импорт snapshot;
* Импорт svace-dir;
* Импорт SARIF;
* Копирование проекта;
* Копирование ветки.

== Изменения в разделе '''Информация о сервере''' ==
В разделе '''Настройки > Информация о сервере''', который доступен пользователям с серверным доступом '''Администрирование сервера''', представление информации разделено на три вкладки:

* Параметры;
* Системный лог;
* Системный журнал.

Т. к. системный лог может иметь большой размер, то вывод информации на форме ограничен последними 1Мб (значение регулируется переменной окружения SVACER_TAIL_LOG_SIZE). Скачивание лога позволяет выгрузить файл полностью.

[[File:Server info-1.png|thumb|none|upright=4|Информация о сервере — вкладка Параметры]]
[[File:Server info-2.png|thumb|none|upright=4|Информация о сервере — вкладка Системный лог]]
[[File:Server info-3.png|thumb|none|upright=4|Информация о сервере — вкладка Системный журнал]]

== Лицензирование Svacer ==
Реализован механизм лицензирования. Просмотр и применение лицензии доступно в CLI, а также в UI, где добавлен раздел Лицензия. Просмотр лицензии доступен всем пользователям, а активация лицензии — пользователям с серверным доступом «Администрирование сервера».

[[File:Licence.png|thumb|none|upright=3.5]]

{{Note|type=info|text=''Функциональность добавлена для возможности будущего развития продукта. В дистрибутив Svacer v.12 лицензия встроена и не вносит никаких ограничений. Срок действия встроенной лицензии — до 31.12.2027.''}}

== Парольная политика ==
Реализована возможность задать парольную политику в конфигурационном файле:

1. Механизм установки минимальной сложности паролей.

Пример задания конфигурационных настроек:
auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"

В поле min_length — минимальная длина пароля. В поле complexity список регулярных выражений, задающих группу требуемых символов. В примере требуется наличие строчных, заглавных букв, цифр и спецсимволов <code>!#</code>.

2. Механизм блокировки учетной записи пользователя при нескольких неудачных попытках авторизации.

Пример задания конфигурационных настроек:

security:
login:
max_attempts: 5
lock_time: 2m

Т. е. учетная запись будет блокироваться на 2 минуты при 5 неудачных попытках авторизации.

Также реализована команда CLI для разблокировки учетной записи пользователя:
svacer user-proiver unlock -login user

Более подробно см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9D%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0_%D0%BF%D0%B0%D1%80%D0%BE%D0%BB%D1%8C%D0%BD%D0%BE%D0%B9_%D0%BF%D0%BE%D0%BB%D0%B8%D1%82%D0%B8%D0%BA%D0%B8_%D0%B2%D0%BD%D1%83%D1%82%D1%80%D0%B5%D0%BD%D0%BD%D0%B5%D0%B3%D0%BE_%D0%BC%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC%D0%B0_%D0%B0%D1%83%D1%82%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D0%B8_Svacer| Парольная политика Svacer]]

== Открытие вкладки LDAP по умолчанию ==
Добавлен параметр конфигурации default. Если он true, то на странице авторизации в пользовательском интерфейсе по умолчанию будет открываться вкладка Svacer, если false — то при наличии сконфигурированного LDAP по умолчанию будет открываться вкладка LDAP, иначе флаг default игнорируется.

Пример задания конфигурационных настроек:
auth:
svacer:
enabled: true
default: false

Более подробную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation|Вкладка LDAP в GUI Svacer]]

== Автоочистка снимков/веток/проектов ==
Расширены опции команды cleanup, вызываемой в CLI:

* cleanup-type — удалять пустые ветки и проекты;
* min-snapshots — нижняя граница по количеству снимков в ветке.

Подробное описание функции и ее опций: [[Help:CLI/cleanup]].

== Веб-хуки для нотификаций ==
Реализован механизм веб-хуков для отправки нотификаций по API во внешние системы. Механизм настраивается в конфигурационном файле в секции webhook.

Реализована отправка нотификаций по следующим событиям:

* разметка маркера / групповая разметка маркеров;
* добавление / обновление комментария маркера;
* добавление / копирование / изменение / удаление контейнеров (группа / проект / ветка);
* импорт / копирование / удаление / изменение снимков;
* копирование разметки.

Пример задания конфигурационных настроек:

webhook:
enabled: true
journalLength: 86400
targets:
- url: "<nowiki>https://swarm-mgr.home:8080/webhook</nowiki>"
workersCount: 1
enabled: true
filter: "Type == 1 and Payload.Status != 'Undecided'"
caCerts: ""
retryCount: 1
timeout: 500

Управление механизмом осуществляется в CLI с помощью команд:

* просмотра записей журнала отправки событий:

svacer server webhook journal

* просмотр статистики по работе службы:

svacer server webhook stat
Более детальную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9C%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC_%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8_%D1%81_%D0%B2%D0%BD%D0%B5%D1%88%D0%BD%D0%B8%D0%BC%D0%B8_%D1%81%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%B0%D0%BC%D0%B8_%D0%BF%D0%BE%D1%81%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B2%D0%BE%D0%BC_Webhook-%D0%BE%D0%B2|Настройка webhook]]

== Удаление неактуальных разделов интерфейса ==
В интерфейсе Svacer были удалены неиспользуемые и не поддерживаемые в актуальном состоянии разделы:

* '''Отчеты'''
* Настройки > '''Oauth Clients'''

Release notes 12-0-0

2025-11-18T14:05:12Z

Chernykov sv: /* Парольная политика */

== Разметка маркеров с помощью AI ==
Добавлена возможность разметки маркеров с помощью ассистента AI, который на основании модели, обученной на множестве размеченных данных, предсказывает статус разметки маркера False Positive или Confirmed.

Если пользователь применяет предсказанный статус маркера, то к маркеру автоматически добавляется комментарий с информацией о дате разметки, используемой модели AI и уровне доверия, также маркеру добавляется метка '''AI'''.

{{Note|type=info|text=''Прогнозируемый ассистентом AI статус разметки маркера носит рекомендательный характер. Окончательное решение о применении предсказанного моделью статуса остается за пользователем.''}}

Форма разметки с помощью AI открывается включением параметра '''Режим разметки с помощью AI''' на стандартных формах разметки маркера или групповой разметки маркера.

Если текущий статус разметки маркера совпадает со статусом, предсказанным моделью AI, то такой маркер повторно разметить с помощью AI нельзя.

[[File:Review marker-1.png|thumb|none|x250px|Форма разметки одного маркера]]

[[File:Review marker-2.png|thumb|none|x250px|Форма групповой разметки маркеров]]

== Изменения в пользовательских фильтрах ==
В пользовательских фильтрах реализованы дополнительные возможности фильтрации маркеров:

1. Атрибут «'''Период последнего изменения'''» для фильтрации маркеров по дате (периоду) актуальной разметки.

2. Поле ввода шаблона расширенного фильтра для фильтрации маркеров по сложным предикатам, таким как:

* поля маркера, его трассы, разметки и комментариев;
* информацию из контекста (имя проекта, ветки, снимка и т. п.);
* атрибуты снимка (включая пользовательские атрибуты, заданные при импорте);
* статусы разметки;
* текст и атрибуты комментариев.

Описание, как составить выражение для расширенного фильтра, можно получить, кликнув на [[File:icon_question_mark2.png|x25px]].
[[File:Custom filter v12.png|thumb|none|x450px]]

== Изменения в разделе '''Поиск''' ==
В разделе '''Поиск''' выполнены следующие доработки:

1. Реализована возможность просмотра информации о маркере непосредственно в разделе '''Поиск'''.
[[File:Search-1.png|thumb|none|upright=4]]

2. Поиск маркеров по полям расширен дополнительными атрибутами:

* Инвариант маркера;
* ID маркера.

[[File:Search-2.png|thumb|none|upright=4]]

== Изменения на вкладке с исходным кодом файла ==
1. Панель функций перенесена на верх вкладки с файлом исходного кода.

2. Реализована возможность добавления файла в фильтр по файлам, а также исключения файла из фильтра, если он был добавлен ранее.
[[File:Cove view.png|thumb|none|upright=4.5]]

== Сравнение маркеров при их сопоставлении ==
В процессе сопоставления маркеров реализована возможность сравнения маркеров. Это помогает определить причину, почему при импорте снимка маркеры не сопоставились автоматически.
[[File:Match markers-1.png|thumb|none|upright=3.5]]

Форма сравнения маркеров открывается в отдельном диалоговом окне.
[[File:Match markers-2.png|thumb|none|upright=3.5]]

== Просмотр JSON маркера ==
В дополнение к команде копирования JSON маркера добавлена команда просмотра JSON маркера в таблице маркеров и правой панели.
[[File:JSON-1.png|thumb|none|upright=3.5]]

Просмотр JSON осуществляется в отдельном диалоговом окне.
[[File:JSON-2.png|thumb|none|upright=3.5]]

== Изменения в разделе '''Проекты''' ==
1. Фокусировка на ветке master при создании нового проекта.

2. В действия над снимком в списке снимков добавлена команда экспорта кода с разметкой. Все команды экспорта снимка вынесены в отдельное меню.
[[File:Project 1.png|thumb|none|upright=4]]

== Редактирование маркеров при импорте ==

При импорте .svace-dir, SARIF или snap-файла добавлена возможность (опция) задать правила трансформации, пропуска и дедупликации маркеров. Правила задаются в JSON-формате.

При импорте в CLI данная опция называется edit-markers и позволяет указать путь к JSON-файлу с правилами. Подробнее здесь: [[Edit markers (command line)]].

В пользовательском интерфейсе при импорте .svace-dir или SARIF возможно задать данную опцию и в ней указать путь к JSON-файлу в архиве .svace-dir или SARIF. А при импорте snap-файла возможно как подгрузить JSON-файл, так и ввести выражение в формате JSON в поле ввода.

[[File:Edit markers svace-dir.png|thumb|none|upright=3|Форма импорта .svace-dir]]
[[File:Edit_markers_sarif.png|thumb|none|upright=3|Форма импорта SARIF]]
[[File:Edit markers snap.png|thumb|none|upright=3|Форма импорта snap-файла]]

== Добавлена форма управления асинхронными задачами ==
В разделе '''Настройки > Асинхронные задачи''', где доступен просмотр и управление (отмена и откат) следующими асинхронными операциями:

* Экспорт snap-файлов;
* Экспорт SARIF;
* Копирование снимков.

Пользователь с серверным доступом '''Администрирование сервера''' может просматривать и управлять запущенными или выполненными асинхронными задачами всех пользователей. Пользователю без данного доступа доступно управление только своими асинхронными задачами.

[[File:Async tasks.png|thumb|none|upright=4|Форма Асинхронные задачи]]

В следующем релизе планируем интегрировать в данный раздел оставшиеся асинхронные операции, которые запускаются пользователями, а именно:

* Импорт snapshot;
* Импорт svace-dir;
* Импорт SARIF;
* Копирование проекта;
* Копирование ветки.

== Изменения в разделе '''Информация о сервере''' ==
В разделе '''Настройки > Информация о сервере''', который доступен пользователям с серверным доступом '''Администрирование сервера''', представление информации разделено на три вкладки:

* Параметры;
* Системный лог;
* Системный журнал.

Т. к. системный лог может иметь большой размер, то вывод информации на форме ограничен последними 1Мб (значение регулируется переменной окружения SVACER_TAIL_LOG_SIZE). Скачивание лога позволяет выгрузить файл полностью.

[[File:Server info-1.png|thumb|none|upright=4|Информация о сервере — вкладка Параметры]]
[[File:Server info-2.png|thumb|none|upright=4|Информация о сервере — вкладка Системный лог]]
[[File:Server info-3.png|thumb|none|upright=4|Информация о сервере — вкладка Системный журнал]]

== Лицензирование Svacer ==
Реализован механизм лицензирования. Просмотр и применение лицензии доступно в CLI, а также в UI, где добавлен раздел Лицензия. Просмотр лицензии доступен всем пользователям, а активация лицензии — пользователям с серверным доступом «Администрирование сервера».

[[File:Licence.png|thumb|none|upright=3.5]]

{{Note|type=info|text=''Функциональность добавлена для возможности будущего развития продукта. В дистрибутив Svacer v.12 лицензия встроена и не вносит никаких ограничений. Срок действия встроенной лицензии — до 31.12.2027.''}}

== Парольная политика ==
Реализована возможность задать парольную политику в конфигурационном файле:

1. Механизм установки минимальной сложности паролей.

Пример задания конфигурационных настроек:
auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"

В поле min_length — минимальная длина пароля. В поле complexity список регулярных выражений, задающих группу требуемых символов. В примере требуется наличие строчных, заглавных букв, цифр и спецсимволов <code>!#</code>.

2. Механизм блокировки учетной записи пользователя при нескольких неудачных попытках авторизации.

Пример задания конфигурационных настроек:

security:
login:
max_attempts: 5
lock_time: 2m

Т. е. учетная запись будет блокироваться на 2 минуты при 5 неудачных попытках авторизации.

Также реализована команда CLI для разблокировки учетной записи пользователя:
svacer user-proiver unlock -login user

Более подробно см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9D%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0_%D0%BF%D0%B0%D1%80%D0%BE%D0%BB%D1%8C%D0%BD%D0%BE%D0%B9_%D0%BF%D0%BE%D0%BB%D0%B8%D1%82%D0%B8%D0%BA%D0%B8_%D0%B2%D0%BD%D1%83%D1%82%D1%80%D0%B5%D0%BD%D0%BD%D0%B5%D0%B3%D0%BE_%D0%BC%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC%D0%B0_%D0%B0%D1%83%D1%82%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D0%B8_Svacer|Парольная политика Svacer]]

== Открытие вкладки LDAP по умолчанию ==
Добавлен параметр конфигурации default. Если он true, то на странице авторизации в пользовательском интерфейсе по умолчанию будет открываться вкладка Svacer, если false — то при наличии сконфигурированного LDAP по умолчанию будет открываться вкладка LDAP, иначе флаг default игнорируется.

Пример задания конфигурационных настроек:
auth:
svacer:
enabled: true
default: false

Более подробную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation|Вкладка LDAP в GUI Svacer]]

== Автоочистка снимков/веток/проектов ==
Расширены опции команды cleanup, вызываемой в CLI:

* cleanup-type — удалять пустые ветки и проекты;
* min-snapshots — нижняя граница по количеству снимков в ветке.

Подробное описание функции и ее опций: [[Help:CLI/cleanup]].

== Веб-хуки для нотификаций ==
Реализован механизм веб-хуков для отправки нотификаций по API во внешние системы. Механизм настраивается в конфигурационном файле в секции webhook.

Реализована отправка нотификаций по следующим событиям:

* разметка маркера / групповая разметка маркеров;
* добавление / обновление комментария маркера;
* добавление / копирование / изменение / удаление контейнеров (группа / проект / ветка);
* импорт / копирование / удаление / изменение снимков;
* копирование разметки.

Пример задания конфигурационных настроек:

webhook:
enabled: true
journalLength: 86400
targets:
- url: "<nowiki>https://swarm-mgr.home:8080/webhook</nowiki>"
workersCount: 1
enabled: true
filter: "Type == 1 and Payload.Status != 'Undecided'"
caCerts: ""
retryCount: 1
timeout: 500

Управление механизмом осуществляется в CLI с помощью команд:

* просмотра записей журнала отправки событий:

svacer server webhook journal

* просмотр статистики по работе службы:

svacer server webhook stat
Более детальную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9C%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC_%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8_%D1%81_%D0%B2%D0%BD%D0%B5%D1%88%D0%BD%D0%B8%D0%BC%D0%B8_%D1%81%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%B0%D0%BC%D0%B8_%D0%BF%D0%BE%D1%81%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B2%D0%BE%D0%BC_Webhook-%D0%BE%D0%B2|Настройка webhook]]

== Удаление неактуальных разделов интерфейса ==
В интерфейсе Svacer были удалены неиспользуемые и не поддерживаемые в актуальном состоянии разделы:

* '''Отчеты'''
* Настройки > '''Oauth Clients'''

Release notes 12-0-0

2025-11-18T14:04:26Z

Chernykov sv: /* Открытие вкладки LDAP по умолчанию */

== Разметка маркеров с помощью AI ==
Добавлена возможность разметки маркеров с помощью ассистента AI, который на основании модели, обученной на множестве размеченных данных, предсказывает статус разметки маркера False Positive или Confirmed.

Если пользователь применяет предсказанный статус маркера, то к маркеру автоматически добавляется комментарий с информацией о дате разметки, используемой модели AI и уровне доверия, также маркеру добавляется метка '''AI'''.

{{Note|type=info|text=''Прогнозируемый ассистентом AI статус разметки маркера носит рекомендательный характер. Окончательное решение о применении предсказанного моделью статуса остается за пользователем.''}}

Форма разметки с помощью AI открывается включением параметра '''Режим разметки с помощью AI''' на стандартных формах разметки маркера или групповой разметки маркера.

Если текущий статус разметки маркера совпадает со статусом, предсказанным моделью AI, то такой маркер повторно разметить с помощью AI нельзя.

[[File:Review marker-1.png|thumb|none|x250px|Форма разметки одного маркера]]

[[File:Review marker-2.png|thumb|none|x250px|Форма групповой разметки маркеров]]

== Изменения в пользовательских фильтрах ==
В пользовательских фильтрах реализованы дополнительные возможности фильтрации маркеров:

1. Атрибут «'''Период последнего изменения'''» для фильтрации маркеров по дате (периоду) актуальной разметки.

2. Поле ввода шаблона расширенного фильтра для фильтрации маркеров по сложным предикатам, таким как:

* поля маркера, его трассы, разметки и комментариев;
* информацию из контекста (имя проекта, ветки, снимка и т. п.);
* атрибуты снимка (включая пользовательские атрибуты, заданные при импорте);
* статусы разметки;
* текст и атрибуты комментариев.

Описание, как составить выражение для расширенного фильтра, можно получить, кликнув на [[File:icon_question_mark2.png|x25px]].
[[File:Custom filter v12.png|thumb|none|x450px]]

== Изменения в разделе '''Поиск''' ==
В разделе '''Поиск''' выполнены следующие доработки:

1. Реализована возможность просмотра информации о маркере непосредственно в разделе '''Поиск'''.
[[File:Search-1.png|thumb|none|upright=4]]

2. Поиск маркеров по полям расширен дополнительными атрибутами:

* Инвариант маркера;
* ID маркера.

[[File:Search-2.png|thumb|none|upright=4]]

== Изменения на вкладке с исходным кодом файла ==
1. Панель функций перенесена на верх вкладки с файлом исходного кода.

2. Реализована возможность добавления файла в фильтр по файлам, а также исключения файла из фильтра, если он был добавлен ранее.
[[File:Cove view.png|thumb|none|upright=4.5]]

== Сравнение маркеров при их сопоставлении ==
В процессе сопоставления маркеров реализована возможность сравнения маркеров. Это помогает определить причину, почему при импорте снимка маркеры не сопоставились автоматически.
[[File:Match markers-1.png|thumb|none|upright=3.5]]

Форма сравнения маркеров открывается в отдельном диалоговом окне.
[[File:Match markers-2.png|thumb|none|upright=3.5]]

== Просмотр JSON маркера ==
В дополнение к команде копирования JSON маркера добавлена команда просмотра JSON маркера в таблице маркеров и правой панели.
[[File:JSON-1.png|thumb|none|upright=3.5]]

Просмотр JSON осуществляется в отдельном диалоговом окне.
[[File:JSON-2.png|thumb|none|upright=3.5]]

== Изменения в разделе '''Проекты''' ==
1. Фокусировка на ветке master при создании нового проекта.

2. В действия над снимком в списке снимков добавлена команда экспорта кода с разметкой. Все команды экспорта снимка вынесены в отдельное меню.
[[File:Project 1.png|thumb|none|upright=4]]

== Редактирование маркеров при импорте ==

При импорте .svace-dir, SARIF или snap-файла добавлена возможность (опция) задать правила трансформации, пропуска и дедупликации маркеров. Правила задаются в JSON-формате.

При импорте в CLI данная опция называется edit-markers и позволяет указать путь к JSON-файлу с правилами. Подробнее здесь: [[Edit markers (command line)]].

В пользовательском интерфейсе при импорте .svace-dir или SARIF возможно задать данную опцию и в ней указать путь к JSON-файлу в архиве .svace-dir или SARIF. А при импорте snap-файла возможно как подгрузить JSON-файл, так и ввести выражение в формате JSON в поле ввода.

[[File:Edit markers svace-dir.png|thumb|none|upright=3|Форма импорта .svace-dir]]
[[File:Edit_markers_sarif.png|thumb|none|upright=3|Форма импорта SARIF]]
[[File:Edit markers snap.png|thumb|none|upright=3|Форма импорта snap-файла]]

== Добавлена форма управления асинхронными задачами ==
В разделе '''Настройки > Асинхронные задачи''', где доступен просмотр и управление (отмена и откат) следующими асинхронными операциями:

* Экспорт snap-файлов;
* Экспорт SARIF;
* Копирование снимков.

Пользователь с серверным доступом '''Администрирование сервера''' может просматривать и управлять запущенными или выполненными асинхронными задачами всех пользователей. Пользователю без данного доступа доступно управление только своими асинхронными задачами.

[[File:Async tasks.png|thumb|none|upright=4|Форма Асинхронные задачи]]

В следующем релизе планируем интегрировать в данный раздел оставшиеся асинхронные операции, которые запускаются пользователями, а именно:

* Импорт snapshot;
* Импорт svace-dir;
* Импорт SARIF;
* Копирование проекта;
* Копирование ветки.

== Изменения в разделе '''Информация о сервере''' ==
В разделе '''Настройки > Информация о сервере''', который доступен пользователям с серверным доступом '''Администрирование сервера''', представление информации разделено на три вкладки:

* Параметры;
* Системный лог;
* Системный журнал.

Т. к. системный лог может иметь большой размер, то вывод информации на форме ограничен последними 1Мб (значение регулируется переменной окружения SVACER_TAIL_LOG_SIZE). Скачивание лога позволяет выгрузить файл полностью.

[[File:Server info-1.png|thumb|none|upright=4|Информация о сервере — вкладка Параметры]]
[[File:Server info-2.png|thumb|none|upright=4|Информация о сервере — вкладка Системный лог]]
[[File:Server info-3.png|thumb|none|upright=4|Информация о сервере — вкладка Системный журнал]]

== Лицензирование Svacer ==
Реализован механизм лицензирования. Просмотр и применение лицензии доступно в CLI, а также в UI, где добавлен раздел Лицензия. Просмотр лицензии доступен всем пользователям, а активация лицензии — пользователям с серверным доступом «Администрирование сервера».

[[File:Licence.png|thumb|none|upright=3.5]]

{{Note|type=info|text=''Функциональность добавлена для возможности будущего развития продукта. В дистрибутив Svacer v.12 лицензия встроена и не вносит никаких ограничений. Срок действия встроенной лицензии — до 31.12.2027.''}}

== Парольная политика ==
Реализована возможность задать парольную политику в конфигурационном файле:

1. Механизм установки минимальной сложности паролей.

Пример задания конфигурационных настроек:
auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"

В поле min_length — минимальная длина пароля. В поле complexity список регулярных выражений, задающих группу требуемых символов. В примере требуется наличие строчных, заглавных букв, цифр и спецсимволов <code>!#</code>.

2. Механизм блокировки учетной записи пользователя при нескольких неудачных попытках авторизации.

Пример задания конфигурационных настроек:

security:
login:
max_attempts: 5
lock_time: 2m

Т. е. учетная запись будет блокироваться на 2 минуты при 5 неудачных попытках авторизации.

Также реализована команда CLI для разблокировки учетной записи пользователя:
svacer user-proiver unlock -login chernykov_sv

== Открытие вкладки LDAP по умолчанию ==
Добавлен параметр конфигурации default. Если он true, то на странице авторизации в пользовательском интерфейсе по умолчанию будет открываться вкладка Svacer, если false — то при наличии сконфигурированного LDAP по умолчанию будет открываться вкладка LDAP, иначе флаг default игнорируется.

Пример задания конфигурационных настроек:
auth:
svacer:
enabled: true
default: false

Более подробную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation|Вкладка LDAP в GUI Svacer]]

== Автоочистка снимков/веток/проектов ==
Расширены опции команды cleanup, вызываемой в CLI:

* cleanup-type — удалять пустые ветки и проекты;
* min-snapshots — нижняя граница по количеству снимков в ветке.

Подробное описание функции и ее опций: [[Help:CLI/cleanup]].

== Веб-хуки для нотификаций ==
Реализован механизм веб-хуков для отправки нотификаций по API во внешние системы. Механизм настраивается в конфигурационном файле в секции webhook.

Реализована отправка нотификаций по следующим событиям:

* разметка маркера / групповая разметка маркеров;
* добавление / обновление комментария маркера;
* добавление / копирование / изменение / удаление контейнеров (группа / проект / ветка);
* импорт / копирование / удаление / изменение снимков;
* копирование разметки.

Пример задания конфигурационных настроек:

webhook:
enabled: true
journalLength: 86400
targets:
- url: "<nowiki>https://swarm-mgr.home:8080/webhook</nowiki>"
workersCount: 1
enabled: true
filter: "Type == 1 and Payload.Status != 'Undecided'"
caCerts: ""
retryCount: 1
timeout: 500

Управление механизмом осуществляется в CLI с помощью команд:

* просмотра записей журнала отправки событий:

svacer server webhook journal

* просмотр статистики по работе службы:

svacer server webhook stat
Более детальную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9C%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC_%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8_%D1%81_%D0%B2%D0%BD%D0%B5%D1%88%D0%BD%D0%B8%D0%BC%D0%B8_%D1%81%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%B0%D0%BC%D0%B8_%D0%BF%D0%BE%D1%81%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B2%D0%BE%D0%BC_Webhook-%D0%BE%D0%B2|Настройка webhook]]

== Удаление неактуальных разделов интерфейса ==
В интерфейсе Svacer были удалены неиспользуемые и не поддерживаемые в актуальном состоянии разделы:

* '''Отчеты'''
* Настройки > '''Oauth Clients'''

Release notes 12-0-0

2025-11-18T14:03:11Z

Chernykov sv: /* Веб-хуки для нотификаций */

== Разметка маркеров с помощью AI ==
Добавлена возможность разметки маркеров с помощью ассистента AI, который на основании модели, обученной на множестве размеченных данных, предсказывает статус разметки маркера False Positive или Confirmed.

Если пользователь применяет предсказанный статус маркера, то к маркеру автоматически добавляется комментарий с информацией о дате разметки, используемой модели AI и уровне доверия, также маркеру добавляется метка '''AI'''.

{{Note|type=info|text=''Прогнозируемый ассистентом AI статус разметки маркера носит рекомендательный характер. Окончательное решение о применении предсказанного моделью статуса остается за пользователем.''}}

Форма разметки с помощью AI открывается включением параметра '''Режим разметки с помощью AI''' на стандартных формах разметки маркера или групповой разметки маркера.

Если текущий статус разметки маркера совпадает со статусом, предсказанным моделью AI, то такой маркер повторно разметить с помощью AI нельзя.

[[File:Review marker-1.png|thumb|none|x250px|Форма разметки одного маркера]]

[[File:Review marker-2.png|thumb|none|x250px|Форма групповой разметки маркеров]]

== Изменения в пользовательских фильтрах ==
В пользовательских фильтрах реализованы дополнительные возможности фильтрации маркеров:

1. Атрибут «'''Период последнего изменения'''» для фильтрации маркеров по дате (периоду) актуальной разметки.

2. Поле ввода шаблона расширенного фильтра для фильтрации маркеров по сложным предикатам, таким как:

* поля маркера, его трассы, разметки и комментариев;
* информацию из контекста (имя проекта, ветки, снимка и т. п.);
* атрибуты снимка (включая пользовательские атрибуты, заданные при импорте);
* статусы разметки;
* текст и атрибуты комментариев.

Описание, как составить выражение для расширенного фильтра, можно получить, кликнув на [[File:icon_question_mark2.png|x25px]].
[[File:Custom filter v12.png|thumb|none|x450px]]

== Изменения в разделе '''Поиск''' ==
В разделе '''Поиск''' выполнены следующие доработки:

1. Реализована возможность просмотра информации о маркере непосредственно в разделе '''Поиск'''.
[[File:Search-1.png|thumb|none|upright=4]]

2. Поиск маркеров по полям расширен дополнительными атрибутами:

* Инвариант маркера;
* ID маркера.

[[File:Search-2.png|thumb|none|upright=4]]

== Изменения на вкладке с исходным кодом файла ==
1. Панель функций перенесена на верх вкладки с файлом исходного кода.

2. Реализована возможность добавления файла в фильтр по файлам, а также исключения файла из фильтра, если он был добавлен ранее.
[[File:Cove view.png|thumb|none|upright=4.5]]

== Сравнение маркеров при их сопоставлении ==
В процессе сопоставления маркеров реализована возможность сравнения маркеров. Это помогает определить причину, почему при импорте снимка маркеры не сопоставились автоматически.
[[File:Match markers-1.png|thumb|none|upright=3.5]]

Форма сравнения маркеров открывается в отдельном диалоговом окне.
[[File:Match markers-2.png|thumb|none|upright=3.5]]

== Просмотр JSON маркера ==
В дополнение к команде копирования JSON маркера добавлена команда просмотра JSON маркера в таблице маркеров и правой панели.
[[File:JSON-1.png|thumb|none|upright=3.5]]

Просмотр JSON осуществляется в отдельном диалоговом окне.
[[File:JSON-2.png|thumb|none|upright=3.5]]

== Изменения в разделе '''Проекты''' ==
1. Фокусировка на ветке master при создании нового проекта.

2. В действия над снимком в списке снимков добавлена команда экспорта кода с разметкой. Все команды экспорта снимка вынесены в отдельное меню.
[[File:Project 1.png|thumb|none|upright=4]]

== Редактирование маркеров при импорте ==

При импорте .svace-dir, SARIF или snap-файла добавлена возможность (опция) задать правила трансформации, пропуска и дедупликации маркеров. Правила задаются в JSON-формате.

При импорте в CLI данная опция называется edit-markers и позволяет указать путь к JSON-файлу с правилами. Подробнее здесь: [[Edit markers (command line)]].

В пользовательском интерфейсе при импорте .svace-dir или SARIF возможно задать данную опцию и в ней указать путь к JSON-файлу в архиве .svace-dir или SARIF. А при импорте snap-файла возможно как подгрузить JSON-файл, так и ввести выражение в формате JSON в поле ввода.

[[File:Edit markers svace-dir.png|thumb|none|upright=3|Форма импорта .svace-dir]]
[[File:Edit_markers_sarif.png|thumb|none|upright=3|Форма импорта SARIF]]
[[File:Edit markers snap.png|thumb|none|upright=3|Форма импорта snap-файла]]

== Добавлена форма управления асинхронными задачами ==
В разделе '''Настройки > Асинхронные задачи''', где доступен просмотр и управление (отмена и откат) следующими асинхронными операциями:

* Экспорт snap-файлов;
* Экспорт SARIF;
* Копирование снимков.

Пользователь с серверным доступом '''Администрирование сервера''' может просматривать и управлять запущенными или выполненными асинхронными задачами всех пользователей. Пользователю без данного доступа доступно управление только своими асинхронными задачами.

[[File:Async tasks.png|thumb|none|upright=4|Форма Асинхронные задачи]]

В следующем релизе планируем интегрировать в данный раздел оставшиеся асинхронные операции, которые запускаются пользователями, а именно:

* Импорт snapshot;
* Импорт svace-dir;
* Импорт SARIF;
* Копирование проекта;
* Копирование ветки.

== Изменения в разделе '''Информация о сервере''' ==
В разделе '''Настройки > Информация о сервере''', который доступен пользователям с серверным доступом '''Администрирование сервера''', представление информации разделено на три вкладки:

* Параметры;
* Системный лог;
* Системный журнал.

Т. к. системный лог может иметь большой размер, то вывод информации на форме ограничен последними 1Мб (значение регулируется переменной окружения SVACER_TAIL_LOG_SIZE). Скачивание лога позволяет выгрузить файл полностью.

[[File:Server info-1.png|thumb|none|upright=4|Информация о сервере — вкладка Параметры]]
[[File:Server info-2.png|thumb|none|upright=4|Информация о сервере — вкладка Системный лог]]
[[File:Server info-3.png|thumb|none|upright=4|Информация о сервере — вкладка Системный журнал]]

== Лицензирование Svacer ==
Реализован механизм лицензирования. Просмотр и применение лицензии доступно в CLI, а также в UI, где добавлен раздел Лицензия. Просмотр лицензии доступен всем пользователям, а активация лицензии — пользователям с серверным доступом «Администрирование сервера».

[[File:Licence.png|thumb|none|upright=3.5]]

{{Note|type=info|text=''Функциональность добавлена для возможности будущего развития продукта. В дистрибутив Svacer v.12 лицензия встроена и не вносит никаких ограничений. Срок действия встроенной лицензии — до 31.12.2027.''}}

== Парольная политика ==
Реализована возможность задать парольную политику в конфигурационном файле:

1. Механизм установки минимальной сложности паролей.

Пример задания конфигурационных настроек:
auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"

В поле min_length — минимальная длина пароля. В поле complexity список регулярных выражений, задающих группу требуемых символов. В примере требуется наличие строчных, заглавных букв, цифр и спецсимволов <code>!#</code>.

2. Механизм блокировки учетной записи пользователя при нескольких неудачных попытках авторизации.

Пример задания конфигурационных настроек:

security:
login:
max_attempts: 5
lock_time: 2m

Т. е. учетная запись будет блокироваться на 2 минуты при 5 неудачных попытках авторизации.

Также реализована команда CLI для разблокировки учетной записи пользователя:
svacer user-proiver unlock -login chernykov_sv

== Открытие вкладки LDAP по умолчанию ==
Добавлен параметр конфигурации default. Если он true, то на странице авторизации в пользовательском интерфейсе по умолчанию будет открываться вкладка Svacer, если false — то при наличии сконфигурированного LDAP по умолчанию будет открываться вкладка LDAP, иначе флаг default игнорируется.

Пример задания конфигурационных настроек:
auth:
svacer:
enabled: true
default: false

== Автоочистка снимков/веток/проектов ==
Расширены опции команды cleanup, вызываемой в CLI:

* cleanup-type — удалять пустые ветки и проекты;
* min-snapshots — нижняя граница по количеству снимков в ветке.

Подробное описание функции и ее опций: [[Help:CLI/cleanup]].

== Веб-хуки для нотификаций ==
Реализован механизм веб-хуков для отправки нотификаций по API во внешние системы. Механизм настраивается в конфигурационном файле в секции webhook.

Реализована отправка нотификаций по следующим событиям:

* разметка маркера / групповая разметка маркеров;
* добавление / обновление комментария маркера;
* добавление / копирование / изменение / удаление контейнеров (группа / проект / ветка);
* импорт / копирование / удаление / изменение снимков;
* копирование разметки.

Пример задания конфигурационных настроек:

webhook:
enabled: true
journalLength: 86400
targets:
- url: "<nowiki>https://swarm-mgr.home:8080/webhook</nowiki>"
workersCount: 1
enabled: true
filter: "Type == 1 and Payload.Status != 'Undecided'"
caCerts: ""
retryCount: 1
timeout: 500

Управление механизмом осуществляется в CLI с помощью команд:

* просмотра записей журнала отправки событий:

svacer server webhook journal

* просмотр статистики по работе службы:

svacer server webhook stat
Более детальную информацию см. [[https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation#%D0%9C%D0%B5%D1%85%D0%B0%D0%BD%D0%B8%D0%B7%D0%BC_%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8_%D1%81_%D0%B2%D0%BD%D0%B5%D1%88%D0%BD%D0%B8%D0%BC%D0%B8_%D1%81%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%B0%D0%BC%D0%B8_%D0%BF%D0%BE%D1%81%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B2%D0%BE%D0%BC_Webhook-%D0%BE%D0%B2|Настройка webhook]]

== Удаление неактуальных разделов интерфейса ==
В интерфейсе Svacer были удалены неиспользуемые и не поддерживаемые в актуальном состоянии разделы:

* '''Отчеты'''
* Настройки > '''Oauth Clients'''

Release notes 12-0-0

2025-11-18T14:01:20Z

Chernykov sv: /* Парольная политика */

== Разметка маркеров с помощью AI ==
Добавлена возможность разметки маркеров с помощью ассистента AI, который на основании модели, обученной на множестве размеченных данных, предсказывает статус разметки маркера False Positive или Confirmed.

Если пользователь применяет предсказанный статус маркера, то к маркеру автоматически добавляется комментарий с информацией о дате разметки, используемой модели AI и уровне доверия, также маркеру добавляется метка '''AI'''.

{{Note|type=info|text=''Прогнозируемый ассистентом AI статус разметки маркера носит рекомендательный характер. Окончательное решение о применении предсказанного моделью статуса остается за пользователем.''}}

Форма разметки с помощью AI открывается включением параметра '''Режим разметки с помощью AI''' на стандартных формах разметки маркера или групповой разметки маркера.

Если текущий статус разметки маркера совпадает со статусом, предсказанным моделью AI, то такой маркер повторно разметить с помощью AI нельзя.

[[File:Review marker-1.png|thumb|none|x250px|Форма разметки одного маркера]]

[[File:Review marker-2.png|thumb|none|x250px|Форма групповой разметки маркеров]]

== Изменения в пользовательских фильтрах ==
В пользовательских фильтрах реализованы дополнительные возможности фильтрации маркеров:

1. Атрибут «'''Период последнего изменения'''» для фильтрации маркеров по дате (периоду) актуальной разметки.

2. Поле ввода шаблона расширенного фильтра для фильтрации маркеров по сложным предикатам, таким как:

* поля маркера, его трассы, разметки и комментариев;
* информацию из контекста (имя проекта, ветки, снимка и т. п.);
* атрибуты снимка (включая пользовательские атрибуты, заданные при импорте);
* статусы разметки;
* текст и атрибуты комментариев.

Описание, как составить выражение для расширенного фильтра, можно получить, кликнув на [[File:icon_question_mark2.png|x25px]].
[[File:Custom filter v12.png|thumb|none|x450px]]

== Изменения в разделе '''Поиск''' ==
В разделе '''Поиск''' выполнены следующие доработки:

1. Реализована возможность просмотра информации о маркере непосредственно в разделе '''Поиск'''.
[[File:Search-1.png|thumb|none|upright=4]]

2. Поиск маркеров по полям расширен дополнительными атрибутами:

* Инвариант маркера;
* ID маркера.

[[File:Search-2.png|thumb|none|upright=4]]

== Изменения на вкладке с исходным кодом файла ==
1. Панель функций перенесена на верх вкладки с файлом исходного кода.

2. Реализована возможность добавления файла в фильтр по файлам, а также исключения файла из фильтра, если он был добавлен ранее.
[[File:Cove view.png|thumb|none|upright=4.5]]

== Сравнение маркеров при их сопоставлении ==
В процессе сопоставления маркеров реализована возможность сравнения маркеров. Это помогает определить причину, почему при импорте снимка маркеры не сопоставились автоматически.
[[File:Match markers-1.png|thumb|none|upright=3.5]]

Форма сравнения маркеров открывается в отдельном диалоговом окне.
[[File:Match markers-2.png|thumb|none|upright=3.5]]

== Просмотр JSON маркера ==
В дополнение к команде копирования JSON маркера добавлена команда просмотра JSON маркера в таблице маркеров и правой панели.
[[File:JSON-1.png|thumb|none|upright=3.5]]

Просмотр JSON осуществляется в отдельном диалоговом окне.
[[File:JSON-2.png|thumb|none|upright=3.5]]

== Изменения в разделе '''Проекты''' ==
1. Фокусировка на ветке master при создании нового проекта.

2. В действия над снимком в списке снимков добавлена команда экспорта кода с разметкой. Все команды экспорта снимка вынесены в отдельное меню.
[[File:Project 1.png|thumb|none|upright=4]]

== Редактирование маркеров при импорте ==

При импорте .svace-dir, SARIF или snap-файла добавлена возможность (опция) задать правила трансформации, пропуска и дедупликации маркеров. Правила задаются в JSON-формате.

При импорте в CLI данная опция называется edit-markers и позволяет указать путь к JSON-файлу с правилами. Подробнее здесь: [[Edit markers (command line)]].

В пользовательском интерфейсе при импорте .svace-dir или SARIF возможно задать данную опцию и в ней указать путь к JSON-файлу в архиве .svace-dir или SARIF. А при импорте snap-файла возможно как подгрузить JSON-файл, так и ввести выражение в формате JSON в поле ввода.

[[File:Edit markers svace-dir.png|thumb|none|upright=3|Форма импорта .svace-dir]]
[[File:Edit_markers_sarif.png|thumb|none|upright=3|Форма импорта SARIF]]
[[File:Edit markers snap.png|thumb|none|upright=3|Форма импорта snap-файла]]

== Добавлена форма управления асинхронными задачами ==
В разделе '''Настройки > Асинхронные задачи''', где доступен просмотр и управление (отмена и откат) следующими асинхронными операциями:

* Экспорт snap-файлов;
* Экспорт SARIF;
* Копирование снимков.

Пользователь с серверным доступом '''Администрирование сервера''' может просматривать и управлять запущенными или выполненными асинхронными задачами всех пользователей. Пользователю без данного доступа доступно управление только своими асинхронными задачами.

[[File:Async tasks.png|thumb|none|upright=4|Форма Асинхронные задачи]]

В следующем релизе планируем интегрировать в данный раздел оставшиеся асинхронные операции, которые запускаются пользователями, а именно:

* Импорт snapshot;
* Импорт svace-dir;
* Импорт SARIF;
* Копирование проекта;
* Копирование ветки.

== Изменения в разделе '''Информация о сервере''' ==
В разделе '''Настройки > Информация о сервере''', который доступен пользователям с серверным доступом '''Администрирование сервера''', представление информации разделено на три вкладки:

* Параметры;
* Системный лог;
* Системный журнал.

Т. к. системный лог может иметь большой размер, то вывод информации на форме ограничен последними 1Мб (значение регулируется переменной окружения SVACER_TAIL_LOG_SIZE). Скачивание лога позволяет выгрузить файл полностью.

[[File:Server info-1.png|thumb|none|upright=4|Информация о сервере — вкладка Параметры]]
[[File:Server info-2.png|thumb|none|upright=4|Информация о сервере — вкладка Системный лог]]
[[File:Server info-3.png|thumb|none|upright=4|Информация о сервере — вкладка Системный журнал]]

== Лицензирование Svacer ==
Реализован механизм лицензирования. Просмотр и применение лицензии доступно в CLI, а также в UI, где добавлен раздел Лицензия. Просмотр лицензии доступен всем пользователям, а активация лицензии — пользователям с серверным доступом «Администрирование сервера».

[[File:Licence.png|thumb|none|upright=3.5]]

{{Note|type=info|text=''Функциональность добавлена для возможности будущего развития продукта. В дистрибутив Svacer v.12 лицензия встроена и не вносит никаких ограничений. Срок действия встроенной лицензии — до 31.12.2027.''}}

== Парольная политика ==
Реализована возможность задать парольную политику в конфигурационном файле:

1. Механизм установки минимальной сложности паролей.

Пример задания конфигурационных настроек:
auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"

В поле min_length — минимальная длина пароля. В поле complexity список регулярных выражений, задающих группу требуемых символов. В примере требуется наличие строчных, заглавных букв, цифр и спецсимволов <code>!#</code>.

2. Механизм блокировки учетной записи пользователя при нескольких неудачных попытках авторизации.

Пример задания конфигурационных настроек:

security:
login:
max_attempts: 5
lock_time: 2m

Т. е. учетная запись будет блокироваться на 2 минуты при 5 неудачных попытках авторизации.

Также реализована команда CLI для разблокировки учетной записи пользователя:
svacer user-proiver unlock -login chernykov_sv

== Открытие вкладки LDAP по умолчанию ==
Добавлен параметр конфигурации default. Если он true, то на странице авторизации в пользовательском интерфейсе по умолчанию будет открываться вкладка Svacer, если false — то при наличии сконфигурированного LDAP по умолчанию будет открываться вкладка LDAP, иначе флаг default игнорируется.

Пример задания конфигурационных настроек:
auth:
svacer:
enabled: true
default: false

== Автоочистка снимков/веток/проектов ==
Расширены опции команды cleanup, вызываемой в CLI:

* cleanup-type — удалять пустые ветки и проекты;
* min-snapshots — нижняя граница по количеству снимков в ветке.

Подробное описание функции и ее опций: [[Help:CLI/cleanup]].

== Веб-хуки для нотификаций ==
Реализован механизм веб-хуков для отправки нотификаций по API во внешние системы. Механизм настраивается в конфигурационном файле в секции webhook.

Реализована отправка нотификаций по следующим событиям:

* разметка маркера / групповая разметка маркеров;
* добавление / обновление комментария маркера;
* добавление / копирование / изменение / удаление контейнеров (группа / проект / ветка);
* импорт / копирование / удаление / изменение снимков;
* копирование разметки.

Пример задания конфигурационных настроек:

webhook:
enabled: true
journalLength: 86400
targets:
- url: "<nowiki>https://swarm-mgr.home:8080/webhook</nowiki>"
workersCount: 1
enabled: true
filter: "Type == 1 and Payload.Status != 'Undecided'"
caCerts: ""
retryCount: 1
timeout: 500

Управление механизмом осуществляется в CLI с помощью команд:

* просмотра записей журнала отправки событий:

svacer server webhook journal

* просмотр статистики по работе службы:

svacer server webhook stat
Более детальную информацию см. [[Help:Installation|Настройка внутреннего механизма аутентификации Svacer]]

== Удаление неактуальных разделов интерфейса ==
В интерфейсе Svacer были удалены неиспользуемые и не поддерживаемые в актуальном состоянии разделы:

* '''Отчеты'''
* Настройки > '''Oauth Clients'''

Help:Installation

2025-11-18T13:35:25Z

Chernykov sv: /* Модель поддерживамых событий */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помозью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настривается в конфигурационном файле в секции webhook. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см.Модель поддерживаемых событий) и отправляется на обработку в каждую из настроеных целей, которыми являются http обработчики. Отправкой занимаются работники (их количествово настраивается в конфигурационном файле в параметре workers_count). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр ca_certs конфигурационного файла. Работникам можно указать таймаут соединения с webhook сервером (в мс, по умолчанию 1000мс, параметр timeout) и количество попыток отправки (по умолчанию - одна попытка, параметр retry_count).

В настройках можно указать фильтр на отправляемые события (параметр filter). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр journal_length). По умолчанию он равен 86400 штук записей - по 1 штуку на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.<br />
Для настройки аутентификации работника можно использовать параметр headers, который представляет собой список значений вида key:value. Данные пары будут добавлены в заголовки каждого http запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer serever webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (осообенно интересными могут быть поля sendError и skip)

Пример вывода для первой команды (с флагом --humanize; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]
}
==== Модель поддерживамых событий ====
<pre class="plaintext">
syntax = "proto3";
import "google/protobuf/any.proto";
option go_package="svacer/proto/webhook";
package webhook;

enum EventType {
EventNone = 0;
EventTest = 1;
EventReviewMarker = 2;
EventPurgeReview = 3;
EventGroupReview = 4;
EventImportSnapshot = 5;
EventCopySnapshot = 6;
EventNewComment = 7;
EventUpdateComment = 8;
EventNewContainer = 9;
EventDeleteContainer = 10;
EventUpdateContainer =11;
EventImportMarkup = 12;
EventDeleteSnapshot = 13;
UpdateSnapshot = 14;
}

message MarkerDetails {
string id = 1;
string file = 2;
string line = 3;
string lang = 4;
}

message Event {
uint64 timestamp = 1;
EventType type = 2;
string created_by = 3;
google.protobuf.Any payload = 4;
}

message PayloadMarkerReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
repeated MarkerDetails markers = 7;
string comment = 8;
string severity = 9;
string action = 10;
string status = 11;
bool group_review = 12;
string created_by_id = 13;
string created_by_login = 14;
}

message PayloadPurgeReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string created_by_id = 5;
string created_by_login = 6;
}

message PayloadImportSnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
}

message PayloadMarkerComment {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
MarkerDetails marker = 7;
string comment = 8;
string created_by_id = 9;
string created_by_login = 10;
}

message PayloadCopySnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
string created_by_id = 7;
string created_by_login = 8;
}

message Container {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
Container source = 5;

}

message PayloadNewContainer {
repeated Container containers = 1;
}

message PayloadDeleteContainer {
repeated Container projects = 1;
repeated Container branches = 2;
}

message PayloadUpdateContainer {
Container container = 1;
}

message CopyResult {
uint64 total = 1;
uint64 applied_reviews = 2;
uint64 applied_comments = 3;
uint64 skipped_reviews = 4;
uint64 duplicate_reviews = 5;
uint64 duplicate_comments = 6;
}

message PayloadImportMarkup {
Container source=1;
Container target=2;
CopyResult copy_result =3;

}

message Snapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}
message PayloadDeleteSnapshots {
repeated Snapshot snapshots = 1;
}

message PayloadUpdateSnapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}</pre>

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Help:Installation

2025-11-18T13:35:09Z

Chernykov sv: /* Модель поддерживамых событий */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помозью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настривается в конфигурационном файле в секции webhook. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см.Модель поддерживаемых событий) и отправляется на обработку в каждую из настроеных целей, которыми являются http обработчики. Отправкой занимаются работники (их количествово настраивается в конфигурационном файле в параметре workers_count). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр ca_certs конфигурационного файла. Работникам можно указать таймаут соединения с webhook сервером (в мс, по умолчанию 1000мс, параметр timeout) и количество попыток отправки (по умолчанию - одна попытка, параметр retry_count).

В настройках можно указать фильтр на отправляемые события (параметр filter). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр journal_length). По умолчанию он равен 86400 штук записей - по 1 штуку на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.<br />
Для настройки аутентификации работника можно использовать параметр headers, который представляет собой список значений вида key:value. Данные пары будут добавлены в заголовки каждого http запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer serever webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (осообенно интересными могут быть поля sendError и skip)

Пример вывода для первой команды (с флагом --humanize; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]
}
==== Модель поддерживамых событий ====
<pre class="plaintext">
syntax = "proto3";
import "google/protobuf/any.proto";
option go_package="svacer/proto/webhook";
package webhook;

enum EventType {
EventNone = 0;
EventTest = 1;
EventReviewMarker = 2;
EventPurgeReview = 3;
EventGroupReview = 4;
EventImportSnapshot = 5;
EventCopySnapshot = 6;
EventNewComment = 7;
EventUpdateComment = 8;
EventNewContainer = 9;
EventDeleteContainer = 10;
EventUpdateContainer =11;
EventImportMarkup = 12;
EventDeleteSnapshot = 13;
UpdateSnapshot = 14;
}

message MarkerDetails {
string id = 1;
string file = 2;
string line = 3;
string lang = 4;
}

message Event {
uint64 timestamp = 1;
EventType type = 2;
string created_by = 3;
google.protobuf.Any payload = 4;
}

message PayloadMarkerReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
repeated MarkerDetails markers = 7;
string comment = 8;
string severity = 9;
string action = 10;
string status = 11;
bool group_review = 12;
string created_by_id = 13;
string created_by_login = 14;
}

message PayloadPurgeReview {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string created_by_id = 5;
string created_by_login = 6;
}

message PayloadImportSnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
}

message PayloadMarkerComment {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
MarkerDetails marker = 7;
string comment = 8;
string created_by_id = 9;
string created_by_login = 10;
}

message PayloadCopySnapshot {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
string snapshot_id = 5;
string snapshot_name = 6;
string created_by_id = 7;
string created_by_login = 8;
}

message Container {
string project_id = 1;
string project_name = 2;
string branch_id = 3;
string branch_name = 4;
Container source = 5;

}

message PayloadNewContainer {
repeated Container containers = 1;
}

message PayloadDeleteContainer {
repeated Container projects = 1;
repeated Container branches = 2;
}

message PayloadUpdateContainer {
Container container = 1;
}

message CopyResult {
uint64 total = 1;
uint64 applied_reviews = 2;
uint64 applied_comments = 3;
uint64 skipped_reviews = 4;
uint64 duplicate_reviews = 5;
uint64 duplicate_comments = 6;
}

message PayloadImportMarkup {
Container source=1;
Container target=2;
CopyResult copy_result =3;

}

message Snapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}
message PayloadDeleteSnapshots {
repeated Snapshot snapshots = 1;
}

message PayloadUpdateSnapshot {
string snapshot_id = 1;
string snapshot_name = 2;
Container container = 3;
}</pre>

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Help:Installation

2025-11-18T13:33:21Z

Chernykov sv: /* Механизм интеграции с внешними системами посредством Webhook-ов */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помозью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настривается в конфигурационном файле в секции webhook. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см.Модель поддерживаемых событий) и отправляется на обработку в каждую из настроеных целей, которыми являются http обработчики. Отправкой занимаются работники (их количествово настраивается в конфигурационном файле в параметре workers_count). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр ca_certs конфигурационного файла. Работникам можно указать таймаут соединения с webhook сервером (в мс, по умолчанию 1000мс, параметр timeout) и количество попыток отправки (по умолчанию - одна попытка, параметр retry_count).

В настройках можно указать фильтр на отправляемые события (параметр filter). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр journal_length). По умолчанию он равен 86400 штук записей - по 1 штуку на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.<br />
Для настройки аутентификации работника можно использовать параметр headers, который представляет собой список значений вида key:value. Данные пары будут добавлены в заголовки каждого http запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer serever webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (осообенно интересными могут быть поля sendError и skip)

Пример вывода для первой команды (с флагом --humanize; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]
}
==== Модель поддерживамых событий ====

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Help:Installation

2025-11-18T13:32:29Z

Chernykov sv: /* Механизм интеграции с внешними системами посредством Webhook-ов */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помозью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настривается в конфигурационном файле в секции webhook. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см.Модель поддерживаемых событий) и отправляется на обработку в каждую из настроеных целей, которыми являются http обработчики. Отправкой занимаются работники (их количествово настраивается в конфигурационном файле в параметре workers_count). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр ca_certs конфигурационного файла. Работникам можно указать таймаут соединения с webhook сервером (в мс, по умолчанию 1000мс, параметр timeout) и количество попыток отправки (по умолчанию - одна попытка, параметр retry_count).

В настройках можно указать фильтр на отправляемые события (параметр filter). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр journal_length). По умолчанию он равен 86400 штук записей - по 1 штуку на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.<br />
Для настройки аутентификации работника можно использовать параметр headers, который представляет собой список значений вида key:value. Данные пары будут добавлены в заголовки каждого http запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer serever webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (осообенно интересными могут быть поля sendError и skip)

Пример вывода для первой команды (с флагом --humanize; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]
==== Модель поддерживамых событий ====

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Help:Installation

2025-11-18T13:31:35Z

Chernykov sv: /* Конфигурация */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помозью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настривается в конфигурационном файле в секции webhook. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см.Модель поддерживаемых событий) и отправляется на обработку в каждую из настроеных целей, которыми являются http обработчики. Отправкой занимаются работники (их количествово настраивается в конфигурационном файле в параметре workers_count). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр ca_certs конфигурационного файла. Работникам можно указать таймаут соединения с webhook сервером (в мс, по умолчанию 1000мс, параметр timeout) и количество попыток отправки (по умолчанию - одна попытка, параметр retry_count).

В настройках можно указать фильтр на отправляемые события (параметр filter). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр journal_length). По умолчанию он равен 86400 штук записей - по 1 штуку на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.<br />
Для настройки аутентификации работника можно использовать параметр headers, который представляет собой список значений вида key:value. Данные пары будут добавлены в заголовки каждого http запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer serever webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (осообенно интересными могут быть поля sendError и skip)

Пример вывода для первой команды (с флагом --humanize; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

<source lang="json">{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]</source>
==== Модель поддерживамых событий ====

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Help:Installation

2025-11-18T13:31:13Z

Chernykov sv: /* Конфигурация */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помозью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настривается в конфигурационном файле в секции webhook. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см.Модель поддерживаемых событий) и отправляется на обработку в каждую из настроеных целей, которыми являются http обработчики. Отправкой занимаются работники (их количествово настраивается в конфигурационном файле в параметре workers_count). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр ca_certs конфигурационного файла. Работникам можно указать таймаут соединения с webhook сервером (в мс, по умолчанию 1000мс, параметр timeout) и количество попыток отправки (по умолчанию - одна попытка, параметр retry_count).

В настройках можно указать фильтр на отправляемые события (параметр filter). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр journal_length). По умолчанию он равен 86400 штук записей - по 1 штуку на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.<br />
Для настройки аутентификации работника можно использовать параметр headers, который представляет собой список значений вида key:value. Данные пары будут добавлены в заголовки каждого http запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "

==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer serever webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (осообенно интересными могут быть поля sendError и skip)

Пример вывода для первой команды (с флагом --humanize; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

<source lang="json">{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]</source>
==== Модель поддерживамых событий ====

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Help:Installation

2025-11-18T13:30:10Z

Chernykov sv:

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помозью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Механизм интеграции с внешними системами посредством Webhook-ов ===

==== Общий принцип работы ====

Механизм webhook-ов настривается в конфигурационном файле в секции webhook. Механизм срабатывает при получении по внутренней шине одного из поддерживаемых событий Svacer. Каждое из внутренних событий преобразуется в событие вызова webhook-а (см.Модель поддерживаемых событий) и отправляется на обработку в каждую из настроеных целей, которыми являются http обработчики. Отправкой занимаются работники (их количествово настраивается в конфигурационном файле в параметре workers_count). У каждой цели есть общая очередь, размер которой составляет 500 событий. Если очередь переполняется, будет выдаваться соответствующее сообщение в лог файле Svacer.

Работники поддерживают протокол https (в том числе самоподписанные сертификаты). Для указания корневого сертификата можно использовать параметр ca_certs конфигурационного файла. Работникам можно указать таймаут соединения с webhook сервером (в мс, по умолчанию 1000мс, параметр timeout) и количество попыток отправки (по умолчанию - одна попытка, параметр retry_count).

В настройках можно указать фильтр на отправляемые события (параметр filter). Фильтр указывается посредством задания выражения. В выражениях используется синтаксис go-expr (см https://github.com/expr-lang/expr ). Фильтр возможно указать в количестве одной штуки на одну цель. Если фильтр после вычисления дает значение true, событие будет отправлено в цель.

Также реализован журнал событий отправки webhook-ов, размер которого может быть указан в конфигурационном файле (параметр journal_length). По умолчанию он равен 86400 штук записей - по 1 штуку на каждую секунду суток. Журнал может быть использован для отладки механизма отправки событий в цель. Содержимое журнала хранится в памяти. При достижении журналом максимального размера, самые старые записи заменяются новыми.<br />
Для настройки аутентификации работника можно использовать параметр headers, который представляет собой список значений вида key:value. Данные пары будут добавлены в заголовки каждого http запроса, выполняемого работником.

==== Конфигурация ====

Возможный пример конфигурационного файла, в котором указана отправка на сервер test-host.local событий, связанных с разметкой маркера.

<source lang="yaml">webhook:
enabled: true
journal_length: 86400
targets:
- url: "https://test-host.local:8080/webhook"
workers_count: 1
enabled: true
filter: "Type == EventReviewMarker and Payload.Status != 'Undecided'"
ca_certs: "/etc/ssl/certs/ca.crt"
retry_count: 3
timeout: 1000
headers:
- "password:12345"
- "Authorization: Bearer eyJh .... "</source>
==== CLI ====

Для взаимодействия с механизмом webhook реализованы две cli команды:

<pre class="plaintext">svacer server webhook journal
svacer serever webhook stat</pre>
Первая команда позволяет посмотреть записи журнала отправки событий. Вторая команда позволяет вывести статистику по работе службы (осообенно интересными могут быть поля sendError и skip)

Пример вывода для первой команды (с флагом --humanize; если флага нет - то будет вывод в формате json):

<pre class="plaintext">==================== #1 ======================
Time: 2025-07-01 12:25:52.25343534 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 6 ms
==================== #2 ======================
Time: 2025-07-01 12:25:54.202850322 +0300 MSK
Created by: admin
Error:
Success: true
SvacerKind: UpdateMarkerReview
EventType: EventReviewMarker
TargetURL: https://swarm-mgr.home:8080/webhook
ProcessTime: 3 ms
[01_07_2025-12:26:13] user@gp-6</pre>
Пример вывода команды статистики:

<source lang="json">{
"enabled": true,
"targets": [
{
"enabled": true,
"url": "https://swarm-mgr.home:8080/webhook",
"filtered": 0,
"sendSuccess": 3,
"sentError": 0,
"submitted": 3,
"skip": 0
}
]</source>
==== Модель поддерживамых событий ====

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Help:Installation

2025-11-18T12:41:54Z

Chernykov sv: /* Расширенная конфигурация */

== Установка и запуск ==
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''', или установить [[Help:Installation#Svacer|deb/rpm пакет]].

Сервер Svacer можно запустить в [[Help:Installation#docker compose|докере]] или из [[Help:Installation#deb/rpm|deb/rpm пакета]].

=== docker compose ===
Рекомендуемый и самый простой способ деплоя — развернуть сервер Svacer в докер-контейнерах, воспользовавшиcь [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] файлом:

<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose.yml</nowiki>
docker compose up -d

После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.

Для указания других параметров сервера можете [[Help:Installation#Дополнительные параметры при запуске в docker-контейнере|переопределить команду запуска]] в docker-compose файле.

=== deb/rpm ===
==== PostgreSQL ====
{{Note|type=info|text=Disclaimer
* Рекомендуемая версия PostgreSQL — 15 и выше. С более старыми версиями корректная работа Svacer не гарантируется.
* Svacer требует эксклюзивного доступа к базе. Использование одной и той же базы для нескольких экземпляров Svacer может приводить к порче данных.}}

Для работы сервера Svacer установите PostgreSQL, следуя [https://www.postgresql.org/download/linux документации postgres]. Для RedHat-based OS нужно дополнительно установить пакет postgresql-contrib соответствующей версии.

Пример для Ubuntu 22:

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install -y postgresql-17

Пример для Rocky Linux 9.4:

<nowiki>sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm</nowiki>
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

==== Браузер для PDF-отчетов ====
Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer. Рекомендуется устанавливать из официального репозитория, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].

{{Note|type=info|text=Рекомендуемые системные требования при генерации PDF-отчетов для больших проектов с использованием HTML-генератора: Intel Core i9, 64 GB RAM, SSD, видеокарта Nvidia}}

При запуске Svacer проверит доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>. В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

==== Svacer ====
На Debian-based OS добавьте apt-репозиторий и установите Svacer из него.

<nowiki>echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list</nowiki>
<nowiki>curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg</nowiki>
sudo apt update
sudo apt install -y svacer

На RedHat-based OS добавьте dnf-репозиторий и установите Svacer из него

<nowiki>curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo</nowiki>
sudo dnf install -y svacer

Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres'''

sudo su -l postgres
psql

И выполните следующие запросы:
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;

В данном примере создается БД svace и права на нее выдаются пользователю svace с паролем svace. Также этому пользователю выдаются права суперюзера, что необходимо для создания расширений в PostgreSQL. При использовании этих значений по умолчанию дальнейшая конфигурация не требуется и можно переходить к запуску.

При использовании других значений нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида

error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

После чего проверить успешность запуска командой

systemctl status svacer

После запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

=== Установка и запуск на Windows ===
PostgreSQL нужен только для сервера Svacer, для клиента не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
cd c:\Program Files\PostgreSQL\15\bin
psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
create database svace;
create user svace with encrypted password 'svace';
grant all privileges on database svace to svace;
alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup|делать резервные копии]]'''}}

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}

=== Upgrade notes ===
==== 12-x-x ====
Рекомендуем обновить PostgreSQL до версии 15 или выше. С более старыми версиями корректная работа Svacer не гарантируется.

==== 11-x-x ====
Нет специфических рекомендаций по обновлению.

==== 10-x-x ====
Нет специфических рекомендаций по обновлению.

==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

'''1.'''

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].

'''2.'''

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при [[Help:Installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.

'''3.'''

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например:

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

== Расширенная конфигурация ==

=== Настройки аутентификации в Svacer ===
В Svacer возможны три способа аутентификации пользователей

# Встроенный
# С помощью LDAP сервера
# Через утилиту oauth_proxy (по протоколу OIDC)
# Посредством Personal Access Token (PAT)

Ниже рассматривается настройка аутентификации посредством внутреннего механизма аутентификации. Для настройки LDAP, PAT или OIDC аутентификации см соответствующие разделы документации.

==== Настройка внутреннего механизма аутентификации Svacer ====

===== Настройка парольной политики внутреннего механизма аутентификации Svacer =====
Настройки параметров встроенного механизма аутентификации возможны посредством секции auth.svacer конфигурационного файла svacer. Ниже приведен пример настроек:<pre class="">auth:
svacer:
password:
min_length: 10
complexity:
- "[a-z]"
- "[A-Z]"
- "[0-9]"
- "[!#]"</pre>Параметр min_length задает минимальную возможную длину пароля в системе. Данный критерий используется при смене пароля пользователя и не влияет на текущие пароли пользователей.

Параметр complexity содержит набор регулярных выражений, задающих требования к паролю с точки зрения наличия в нем определенных символов. При задании такого списка выражений Svacer будет проверять задаваемый пользователем новый пароль на предмет удовлетворения всем этим требованиям. Каждое выражение в списке - полноценное выражение, поддерживаемое языком golang.

Указанные выше настройки применяются только к внутренним учетным записям пользователей Svacer. По умолчанию данные настройки отключены (нет требований на минимальную длину и сложность пароля)

===== Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer) =====
В случае интеграции Svacer с LDAP, можно указать Svacer какую вкладку Svacer или LDAP использовать по умолчанию. Для этого используется параметр auth.svacer.default. Если данный параметр установлен в значение true, то вкладкой по умолчанию - будет вкладка Svacer, иначе - вкладка LDAP.

Также возможно полностью отключить механизм внутренней аутентификации Svacer с помозью параметра auth.svacer.enabled.

Ниже приведен пример конфигурационного файла svacer для задания вкладки LDAP по умолчанию (в случае наличие интеграции с LDAP сервером)<pre class="plaintext">auth:
svacer:
enabled: true
default: false</pre>

==== Настройка защиты от перебора паролей пользователей ====
Для случаев аутентификации с помощью LDAP сервера и с помощью встроенного механизма аутентификации реализован механизм блокировки учетных записей пользователей в том, случае если количество неудачных попыток входа превышает заданное в настройках число. По умолчанию защита отключена. Ниже приведен пример секции конфигурационного файла Svacer, задающего правила блокировки:<pre class="plaintext">security:
login:
max_attempts: 5
lock_time: 2m</pre>Время, на которое происходит блокировка учетной записи пользователя, указывается в формате golang/time: (1s,1m,60m и т.д.) .

В случае активации защиты данный механизм также защищает аутентификацию посредством вызовов соответствующих точек входа public API.

Блокировка не влияет на работу уже зарегистрированных пользователей.

Для принудительной разблокировки пользователей можно использовать команды cli (требуются права управления сервером):<pre class="">svacer user-provider unlock</pre>

=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
listen 443 ssl;
listen [::]:443 ssl;

server_name svacer.ispras.ru;

# for large data transfers and continuous connections
client_max_body_size 0;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;

# path to ssl-certificate and key
ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

location / {
include proxy_params;

# to make WebSockets work
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# svacer HTTP URL
proxy_pass http://127.0.0.1:8080;
}
}

# proxy gRPC port if required
server {
listen 13002 http2;
underscores_in_headers on;

location / {
grpc_pass grpc://127.0.0.1:3002;
}
}
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].

===== Apache =====
Включите нужные модули в Apache
sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
SSLEngine On
ProxyPreserveHost On
ProxyTimeout 600

# path to ssl-certificate and key
SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key

# svacer HTTP URL
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

# to make WebSockets work
ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
RewriteEngine on
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

ServerName svacer.ispras.ru
ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
systemctl restart apache2

==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED

Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.

* '''show''' — отображает текущий используемый сертификат

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>

* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>

* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.

:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>

:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

В конфигурационном файле Svacer можно указать минимальную и максимальные версии TLS, поддерживаемые сервером. Для этого необходимо в конфигурационом файле указать параметры <code>minVersion</code> и <code>maxVersion</code> в разделе security.tls.

<pre>
security:
tls:
minVersion: tls11
maxVersion: tls12
</pre>

=== Интеграция с хранилищем секретов Infisical ===
В Svacer реализована поддержка получения секретов из хранилища секретов [https://infisical.com/ Infisical]. Подробную информацию об интеграции см. в статье [[Infisical|Интеграция с хранилищем секретов Infisical]].

=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.

svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

При попытке запуска на порту < 1024 от непривилегированного пользователя (например, от пользователя svacer при установке из deb/rpm пакета), сервер Svacer не запустится с ошибкой

ERROR: port 443 is privileged, please check current user permissions or set another rest api port

В таком случае надо выдать capabilities на открытие привилегированных портов файлу сервера Svacer. Это нужно будет делать при каждом обновлении версии сервера

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/svacer-server

=== Увеличение лимита открытых файлов ===
Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:

$ ulimit -Sn
1024
$ ulimit -Hn
1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.

Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
ulimit -Sn 16384

* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить

* soft nofile 16384

* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен

[Service]
LimitNOFILE=16384

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Установка пути к директории для кэша ===
Если запускаете Svacer под пользователем без домашней директории, рекомендуется установить путь к директории для кэша через переменную окружения SVACER_CACHE_DIR в файле описания сервиса systemd

[Service]
Environment="SVACER_CACHE_DIR=/path/to/some/dir"

После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer

sudo systemctl daemon-reload
sudo systemctl restart svacer.service

=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг [[Help:CLI#Хуки|хуков]].

Для этого переопределите команду запуска сервера Svacer в docker-compose файле и допишите туда нужные параметры:

command: /svacer/bin/svacer-server run --store /data/store --pg postgres://svace:svace@postgresql:5432/svace --hooks /svacer/hooks.json

Конфигурационный файл с описанием хуков примонтируйте как volume:

volumes:
- ./hooks.json:/svacer/hooks.json

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как shell-команду, чтобы в контейнере подставились значения переменных

environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- STORE=/data/store
- HOOKS_FILE=/svacer/hooks.json
volumes:
- ./hooks.json:/svacer/hooks.json
command: sh -c "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --hooks $$HOOKS_FILE"

Для более комплексных сценариев можете собрать свой образ с сервером Svacer, использовав наш [[Dockerfile]] как референс.

== Обновление детекторов ==
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:

svacer checkers --upload </path/to/svace>

{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.

== Генерация PDF на основе HTML ==
В релиз 10.х.х включена генерация PDF на основе рендеринга HTML с последующим запуском headless chrome/chromium для генерации PDF. Этот подход позволяет упростить формирование шаблонов для генерации PDF, но требует существенно больше вычислительных ресурсов. Для тюнинга числа параллельных процессов при генерации используется переменная окружения

SVACER_PDF_GEN_LIMITS=<pdf tool limit>:<chrome limit>

Первое значение <code><pdf tool limit></code> определяет число одновременных процессов pdfmerge для сборки отдельных секций в единый PDF документ; второе значение <code><chrome limit></code> определяет одновременное число процессов chrome/chromium для генерации PDF из HTML. Не рекомендуется ставить значения, сильно превышающие число ядер в сервере.

== Полнотекстовый поиск ==
Для поддержки полнотекстового поиска Svacer строит индекс. По умолчанию директория для индекса создается в <code>$HOME/.cache/svacer</code>, для указания иной директории можно использовать переменную окружения <code>SVACER_SEARCH_INDEX_DIR</code>

В ряде случаев (падение и рестарт сервера, ошибки и т. п.) кэш может быть в некорректном состоянии. Для переиндексации данных администратор может использовать CLI команду

svacer search --host <nowiki>http://some_host:port</nowiki> --user <login> --password <pwd> --drop-cache

Используемая при этом учетная запись должна быть с правами на <code>Server administration</code>

== Указание public-url ==
В некоторых случаях необходимо явно указывать серверу Svacer его URL-адрес. Например, это нужно для корректной генерации коротких ссылок на предупреждения и ссылок в [[Notifications|уведомлениях]]. Используйте параметр <code>--public-url</code> при запуске сервера
<nowiki>svacer-server run --public-url http://svacer.intra.net:8080</nowiki>

Notifications

2025-09-01T07:19:31Z

Chernykov sv: /* Описание параметров конфигурации */

== Механизм подписок на внутренние события Svacer ==

=== Общие принципы ===

В Svacer реализован механизм оповещения пользователей на некоторые классы событий, возникающих в Svacer в результате работы пользователей в системе. Оповещение пользователей возможны с использованием следующих сервисов:

* Электронная почта
* Индивидуальный чат пользователя мессенджера telegram с ботом

Существует три класса внутренних событий, на которые возможно получение оповещения:

* разметка маркера(ов), в том числе групповая (REVIEW)
* создание/редактирование и удаление комментария к маркеру (COMMENT)
* добавление/удаление снимков (SNAPSHOT)
* удаление контейнеров (веток, проектов)

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

* Цель
* Класс события
* Флаг
* Тип подписки

'''Цель''' – определяет объект, в отношении которого должно произойти событие, чтобы пользователь получил оповещение. Возможна подписка на проекты и ветки<br />
'''Класс события''' – определяет один из трех классов события, описанных выше (кроме удаления контейнеров)<br />
'''Флаг''' – дополнительное условие к активации подписки. Возможны следующие значения:<br />
:''Участие'' – подписка приведет к созданию сообщения пользователю только в том случае, если в указанной цели есть какая-либо активность пользователя (разметка или комментарий), кому подписка принадлежит<br />
'''Тип подписки''' – подписка может иметь "исключающее" свойство, когда она подавляет создание сообщений. Полезно при исключении некоторых целей из списка срабатывания (например, когда есть подписка на проект, но некоторые ветки не требуют внимания)

Пользователи могут настраивать каналы оповещения (почта или telegram) посредством изменения своего '''профиля подписок'''. Профиль подписок не включает в себя сами подписки, а позволяет контролировать только механизм доставки создаваемых подписками сообщений. Профиль можно изменять как в GUI, так и через команды CLI.

==== Некоторые детали работы механизма подписок ====

Механизм подписок может удерживать некоторые сообщения, накапливая их в очереди, для минимизации числа соединений с сервером (почтовым или telegram). Отправка сообщений происходит 1 раз в 30 секунд, в связи с чем могут быть задержки с получением сообщений.

Кроме того, действия по разметке маркера могут быть аккумулированы в одно сообщение, если они происходят достаточно быстро (несколько событий на одном маркере для одной подписки в пределах 20 секунд).

В некоторых случаях, при активности большого количества пользователей со средней суммарной активностью пользователей приблизительно в 3072 события разметки в минуту, сообщения могут быть отброшены системой, чтобы не приводить к спаму.

Для предотвращения создания большого количества соединений с почтовым сервером (при активной работе пользователей или средств автоматизации) возможно использование специального флага в конфигурации – saveConection, который позволяет переиспользовать уже созданное ранее соединение с почтовым сервером. Соединение закрывается автоматически через 10 секунд простоя.

Для отправки сообщений через мессенджер telegram сервер Svacer требует идентификатор заранее созданного бота. При этом бот используется только для отправки сообщений и не находится в запущенном состоянии постоянно (нет постоянного соединения с серверами telegram).

=== Конфигурация ===

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

<pre class="">subscription:
enabled: true
trace: false
advanced:
transport_queue_len: 256
transport_worker_period: 30000000000
trace_dir: /tmp
telegram:
enabled: true
botID: "7865.........."
mail:
enabled: true
smtpAddress: "smtp.local"
smtpPort: 25
smtpUsername: ""
smtpPassword: ""
caCerts: ""
smtpAuth: "noauth"
from: "mailer@local"
tls: true
saveConnection: false
debug: false</pre>

{{Note|type=reminder|text=При конфигурировании службы необходимо явно указать значение advanced.transport_worker_period для избежания проблемы повышенной загрузки CPU. Значение указывается в наносекундах}}

==== Описание параметров конфигурации ====

{|
| subscription.enabled
| Состояние службы при старте сервера Svacer
|-
| subscription.trace
| Позволяет фиксировать работу службы в виде набора файлов, создаваемых во временной папке ОС (/tmp/ для ОС Linux)
|-
| telegram.enabled
| Состояние канала доставки сообщений посредством мессенджера telegram при запуске сервера
|-
| telegram.botID
| Идентификатор бота, который будет использован для отправки сообщений
|-
| mail.enabled
| Состояние канала доставки сообщений с помощью электронной почты при запуске сервера
|-
| mail.smtpAddress
| Адрес почтового сервера, который будет использован для отправки сообщений
|-
| mail.smtpPort
| Параметр, задающий порт на котором работает почтовый сервер. По умолчанию используется значение 25
|-
| mail.smtpAuth
| Параметр, задающий тип аутентификации, используемой клиентом. Возможны варианты: noauth, plain, login
|-
| mail.smtpUsername (mail.smtpPassword)
| Параметры, задающие учетную запись от имени которой будет происходить рассылка сообщений. В случае аутентификации noauth, должны быть указаны пустые значения
|-
| mail.caCerts
| Параметр, задающий сертификаты CA. Значения поля аналогичны значениям соответствующего поля из конфигурации сервера для работы по протоколу TLS (нативный режим). Если указано пустое значение, то поддержка TLS будет сконфигурирована в небезопасном режиме с доверием любому сертификату сервера
|-
| mail.from
| Поле, указывающее почтовый адрес, от имени которого будет осуществлять рассылка
|-
| mail.tls
| Использовать или нет tls для соединения с сервером
|-
| mail.debug
| Выводить отладочную информацию протокола взаимодействия с почтовым сервером
|-
| saveConnection
| Сохранять уже установленное соединение с почтовым сервером (в течении 10 секунд после последней активности)
|-
|advanced.transport_queue_len
|Значение по умолчанию — 256. Определяет максимальный размер буфера накапливаемых сообщений. Если буфер полный, новые сообщения будут игнорироваться (о чем будет сообщение в логах сервера)
|-
|advanced.transport_worker_period
|Значение по умолчанию — 30. Определяет период срабатывания очереди сообщения в наносекундах.
|-
|advanced.trace_dir
|Значение по умолчанию определяется типом системы (Для Linux — /tmp). Позволяет указать папку, в которой будут размещаться отладочные файлы работы службы оповещений
|}

{{Note|type=reminder|text=Для работы службы необходимо запускать Svacer с опцией '''[[Help:Installation#Указание_public-url|public-url]]'''. Без указания этой опции служба не будет активирована, так как создаваемые в процессе ее работы ссылки должны содержать правильные URL}}

==== Особенности работы почтового клиента, используемого Svacer ====

''Поддержка TLS''. Если флаг mail.tls установлен, то соединение с сервером изначально будет установлено по протоколу TLS. В противном случае, изначально будет установлено обычное TCP соединение, и уже после команды STARTTLS стороны перейдут на протокол TLS. В случае если TLS соединение не сможет быть установлено, клиент будет пытаться работать без TLS соединения.

Для облегчения проверки конфигурации сервера Svacer для отправки почтовых сообщений можно использовать команду cli (см. подробнее ниже):

svacer subscription transport mail test --config mail.yaml

=== Команды CLI для работы с механизмом подписок ===

Все команды собраны в группу ''svacer subscription''. Доступны следующие подкоманды:

* <code>transport</code> – функции по работе (конфигурации) используемых механизмов доставки сообщений (mail, tg)
* <code>profile</code> – управление профилем подписки пользователя
* <code>admin</code> – управление службой подписок
* <code>create</code> – cоздание новой подписки
* <code>list</code> – просмотр списка подписок
* <code>delete</code> – удаление подписок
* <code>update</code> – обновление существующей подписки

==== Команды управления подписками ====

Для управления подписками пользователя используются следующие команды:

* <code>create</code> – создание подписки
* <code>list</code> – перечесление подписок пользователя
* <code>delete</code> – удаление подписки
* <code>update</code> – редактирование подписки

{{Note|text=Во всех командах присутствуют стандартные для CLI Svacer флаги подключения к серверу (--host, --port, --grpc, --user, --password, --ssl и другие). Группа этих флагов в дальнейшем будет обозначаться как [svacer_conn]}}

===== Создание подписки (команда 'create') =====

Общий формат команды:

svacer subscription create [svacer_conn] [опции]

'''Опции:'''

* <code>project</code> – имя или ID проекта
* <code>branch</code> – имя или ID ветки
* <code>marker</code> – ID маркера
* <code>exclude</code> – подписка имеет исключающий характер (по умолчанию <code>false</code>)
* <code>my-activities</code> – оповещение только в случае событий на маркерах, где была собственная активность (разметка, комментарий) (по умолчанию <code>false</code>)
* <code>review</code> – подписаться на события REVIEW
* <code>snapshot</code> – подписаться на события SNAPSHOT
* <code>comment</code> – подписаться на события COMMENT
* <code>all-events</code> – подписаться на все классы событий

{{Note}} При создании подписки важно указывать имена или ID одновременно во всех требуемых флагах. Например, команда:

svacer subscription create --project darpa --branch 1111-2222-333333333

не будет корректно обработана. При использовании ID цели можно не указывать родительские сущности (например, проект для ветки)

'''Пример использования:'''

Подписаться на события REVIEW в проекте "MyProject" и ветке "MyBranch":

<pre class="">svacer subscription create --project MyProject --branch MyBranch --review</pre>
Подписаться на все события в проекте "MyProject":

<pre class="">svacer subscription create --project MyProject --all-events</pre>

===== Получение списка подписок (команда list) =====

Общий формат команды:

svacer subscription list [svacer_conn] [опции]

'''Опции:'''

* <code>all</code> – вывести все подписки всех пользователей (требуется роль admin)
* <code>humanize</code> – вывести в удобном для чтения виде

'''Пример использования:'''

Вывести все подписки пользователя 'user' в формате JSON (по умолчанию):

<pre class="">svacer subscription list --user user --password 1234</pre>
Вывести все подписки пользователя 'user' в удобном формате

<pre class="">svacer subscription list --user user --password 1234 --humanize</pre>
Вывести все подписки всех пользователей

<pre class="">svacer subscription list --user admin --password admin --all --humanize</pre>

===== Удаление подписки (команда delete) =====

Общий формат команды:

svacer subscription delete [svacer_conn] [опции]

'''Опции:'''

* <code>all</code> – удаление всех подписок пользователя
* <code>id</code> – удаление конкретной подписки

'''Пример использования:'''

Удалить подписку пользователя user1

svacer subscription delete --user user1 --password 1234 --id 1234

Полный ID можно не указывать, достаточно указать несколько первых символов идентификатора, достаточных для однозначной идентификации подписки

===== Обновление подписки (команда update) =====

Общий формат команды:

svacer subscription update [svacer_conn] [опции]

'''Опции:'''

* <code>id</code> – ID подписки для обновления
* <code>only-my-activities</code> – установка флага my-activities для подписки (по умолчанию <code>false</code>)

'''Пример использования:'''

Установить флаг my-activities для подписки, ID которой начинается с символов f1f2

<pre class="">svacer subscription update --id f1f2 --only-my-activities true</pre>

==== Команды настройки и управления каналами доставки сообщений ====

В Svacer поддерживаются два канала доставки сообщений — электронная почта и мессенджер Telegram. Для облегчения конфигурации данных каналов используются подкоманды команды <code>svacer subscription transport</code>

* <code>mail</code>

'''Подкоманда 'mail''''

Предназначена для облегчения конфигурации почтового клиента Svacer. Общий формат команды:

svacer subscription transport mail [опции]

'''Опции:'''

* <code>--to</code> — почтовый адрес для отправки тестового сообщения
* <code>--config</code> — секция mail конфигурационного файла в формате YAML

В качестве параметра обязательно передать файл в формате yaml, содержимое которого соответствует секции mail конфигурационного файла для службы. Содержимое такого файла может следующим:

<pre class=""> enabled: true
smtpAddress: "smtp.mail.local"
smtpPort: 25
smtpUsername: ""
smtpPassword: ""
smtpAuth: "noauth"
from: "sender@mail.local"
debug: true</pre>

'''Пример использования:'''

Отправить тестовое письмо на адрес <code>admin@mail.org</code>, используя конфигурацию <code>test.yaml</code>

<pre class="">svacer subscription transport mail test --config test.yaml --to admin@mail.org</pre>

==== Группа команд администрирования службы (admin) ====

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

* <code>service</code> – управление службой подписок<br />
Общий формат команды:

svacer subscription admin service [svacer_conn] [опции]

'''Опции'''

* <code>enable</code> – включение/выключение службы
* <code>use-mail</code> – включение/выключение канала передачи сообщений через электронную почту
* <code>use-tg</code> – включение/выключение канала передачи сообщений через Telegram

Если запускать команду без указания флагов, то будет выведена информация о текущем состоянии службы с рядом параметров.

{{Note|text=При использовании флагов use-mail, use-tg не происходит повторное считывание конфигурационного файла. Для того, чтобы флаги use-mail и use-tg корректно применились их необходимо запускать одновременно с флагом --enable true, предварительно отключив службу с помощью флага --enable false}}

==== Группа команд управления профилем пользователя (profile) ====

Команда предназначена для управление профилем пользователя и имеет следующий формат:

svacer subscription profile [svacer_conn] [update] [опции]

'''Опции (актуальны для подкоманды update):'''

* <code>use-mail</code> – использовать канал передачи сообщений через электронную почту
* <code>use-tg</code> – использовать канал передачи сообщений через Telegram
* <code>mail</code> – изменить почтовый адрес
* <code>tg-chat-id</code> – установить ID чата для сообщений Telegram
* <code>tg-user-id</code> – установить ID пользователя для сообщений Telegram
* <code>enable</code> – включение/отключение механизма оповещения для конкретного пользователя

Если опции и подкоманда <code>update</code> не указаны, то будет выведен текущий профиль пользователя.

=== Пример скрипта для создания подписок пользователей ===

<pre class="">#!/bin/bash -x
#Общие параметры подключения к Svacer
HOST="--host 10.0.0.10 --port 8888"
#Тестовые проекты
PROJECT1="NET6"
PROJECT2="darpa"
PROJECT3="large"
PROJECT3_BRANCH1="master"
#Параметры аутентификации пользователей
USER1="--user admin_1 --password password"
USER2="--user admin_2 --password password"
USER3="--user admin_3 --password password"
USER4="--user admin_4 --password password"
USER5="--user admin_5 --password password"
USER6="--user admin_6 --password password"
USER7="--user admin_7 --password password"
#ID пользователя в Telegram
TG_USER_ID=721941843
TG_CHAT_ID=$TG_USER_ID

#Команда создания подписки
CREATE_SN="./svacer subscription create"

#User1 - подписка на все, но с флагом myactivities
$CREATE_SN $HOST $USER1 --all-events --my-activities
#User2 - подписка на проект1, только снимки
$CREATE_SN $HOST $USER2 --project $PROJECT1 --snapshot
#User2 - подписка на проект2, только разметка
$CREATE_SN $HOST $USER2 --project $PROJECT2 --review
#User2 - подписка на проект3, только комментарии
$CREATE_SN $HOST $USER2 --project $PROJECT3 --comment
#User3 - подписка на проект3, исключая ветку1, все события
$CREATE_SN $HOST $USER3 --project $PROJECT3 --all-events
$CREATE_SN $HOST $USER3 --project $PROJECT3 --branch $PROJECT3_BRANCH1 --exclude
#User4 - подписка на проект2, все события
$CREATE_SN $HOST $USER4 --project $PROJECT2 --all-events
#User5 - подписка на проект3, все события
$CREATE_SN $HOST $USER5 --project $PROJECT3 --all-events
#User6 - подписка на все проекты, все события
$CREATE_SN $HOST $USER6 --all-events
#User7 - подписка на все проекты, все события
$CREATE_SN $HOST $USER7 --all-events

#Команда работы с профилем
ENABLE_NTFY_MAIL="./svacer subscription profile"
#User1, включить получение сообщений по почте, по Telegram, установить адрес электронной почты для сообщений, указать ID пользователя для получения сообщений в Telegram
$ENABLE_NTFY_MAIL $HOST $USER1 update --enable true --use-mail true --mail user1@mb1lo.ru --use-tg true --tg-user-id $TG_USER_ID --tg-chat-id $TG_CHAT_ID
#User2, отключить получение всех сообщений (подписки останутся)
$ENABLE_NTFY_MAIL $HOST $USER2 update --enable false
#User3, отключить получение собщений по Telegram
$ENABLE_NTFY_MAIL $HOST $USER3 update --use-tg false
#User4, изменить параметры канала Telegram
$ENABLE_NTFY_MAIL $HOST $USER4 update --tg-user-id $TG_USER_ID --tg-chat-id $TG_CHAT_ID</pre>

=== Пример конфигурационного файла для активации службы уведомлений при запуске Svacer ===

<pre class="">subscription:
enabled: true
telegram:
enabled: true
botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
mail:
enabled: true
smtpAddress: "mail-server.ispras.ru"
smtpPort: 25
smtpUsername: ""
smtpPassword: ""
smtpAuth: "noauth"
from: "relay@ispras.ru"</pre>

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

<pre class="">subscription:
enabled: true
telegram:
enabled: true
botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
mail:
enabled: true
smtpAddress: "mail.ispras.ru"
smtpPort: 25
smtpUsername: "user@ispras.ru"
smtpPassword: "abrakadabra"
smtpAuth: "plain"
from: "user@ispras.ru"</pre>

В следующем примере устанавливается соединение TLS с почтовым сервером

<pre class="">subscription:
enabled: true
telegram:
enabled: true
botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
mail:
enabled: true
smtpAddress: "mail.ispras.ru"
smtpPort: 465
smtpUsername: "user@ispras.ru"
smtpPassword: "abrakadabra"
smtpAuth: "plain"
from: "user@ispras.ru"
tls: true</pre>

В следующем примере устанавливается соединение TLS с помощью команды STARTTLS с почтовым сервером (в консоль будут также выведены отладочные сообщения почтового клиента)

<pre class="">subscription:
enabled: true
telegram:
enabled: true
botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
mail:
enabled: true
smtpAddress: "mail.ispras.ru"
smtpPort: 587
smtpUsername: "user@ispras.ru"
smtpPassword: "abrakadabra"
smtpAuth: "plain"
from: "user@ispras.ru"
tls: false
debug: true</pre>

При этом сервер mail.ispras.ru работает на всех портах: на 465 принимаются только TLS соединения, на 587 — обычные соединения с переходом на TLS впоследствии, на 25 — обычные соединения (без TLS)

=== Пример конфигурации службы с запуском ее вручную через команду cli ===

<pre class="">subscription:
enabled: false
telegram:
enabled: true
botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
mail:
enabled: true
smtpAddress: "mail.ispras.ru"
smtpPort: 587
smtpUsername: "user@ispras.ru"
smtpPassword: "abrakadabra"
smtpAuth: "plain"
from: "user@ispras.ru"
tls: false</pre>
После запуска сервера Svacer можно активировать службу с помощью команды

<pre class="">svacer subscription admin service --user admin --password admin --enable true</pre>

OIDC

2025-05-20T07:52:24Z

Chernykov sv: /* Автоназначение ролей пользователю на основе содержимого Claims токена */

== Основные концепции ==

Аутентификация с помощью протокола ''OpenID Connect'' (далее ''OIDC'') реализована с помощью утилиты [https://oauth2-proxy.github.io/oauth2-proxy/ oauth2-proxy]. Общая схема аутентификации представлена на рисунке ниже:

[[File:Image-20240531112418954.png|thumb|none]]

Пояснения к картинке указаны в таблице.

{| class="wikitable"
! Шаг
! Описание
|-
| 1. Запрос ресурса
| Если запрос включен в список запросов без аутентификации (см. skip_auth_routes), то он перенаправляется к серверу Svacer (Входа на сервер Svacer при этом не происходит. Будут доступны только те ресурсы, которые не требуют аутентификации). Если запроса нет в списке, то переходим к шагу 2
|-
| 2. Проверка необходимости аутентификации OAuth2
| Утилита oAuth2-proxy, на основе имеющихся в куках данных, определяет необходимость перенаправления пользователя на сервер OAuth2. Если аутентификация необходима, то по URL, который был указан в параметре oidc_issuer_url, прокси запросит точки входа в соответствии с протоколом OIDC. После получения нужной точки входа, пользователь будет перенаправлен на нее (шаг 3), при этом в параметре redirect этого запроса будет указано значение параметра конфигурации прокси redirect_url. Если аутентификация не нужна (уже есть действительный токен от OIDC сервера), то запрос перенаправляется на сервер Svacer с токеном доступа (Access Token) от сервера OAuth2 в заголовке X-Forwarded-Access-Token — шаг 1* на рисунке
|-
| 3. Аутентификация пользователя на OAuth2 сервере
| Если в куках сервера OAuth2 есть данные об активной сессии аутентификации, то пользователь будет перенаправлен обратно на прокси сервер по указанному в параметре запроса URL. При этом, в параметрах URL будет передан Authorization Code для дальнейшего использования клиентом OAuth2 (в терминологии OAuth2 клиентом является oauth2-proxy). Если активной сессии нет, то будет отображена форма для логина и пароля пользователя. После успешного входа, OAuth2 сервер запомнит сессию пользователя, сформирует Authorization Code и перенаправит пользователя обратно на прокси, передав в URL значение Authorization Code
|-
| 4. Получение AccessToken
| Прокси осуществляет получение Access Token от сервера OAuth2, используя полученный Authorization Code и точку входа сервера OAuth2 для получения токенов, которую он получил ранее на шаге 2
|-
| 5. Отправка запроса к Svacer
| Первоначальный запрос (из шага 1), отправляется серверу Svacer. При этом в заголовки этого запроса добавляется Access Token от OAuth сервера, а также другие специфичные для oauth2-proxy заголовки. Состав дополнительной информации, передаваемой в заголовках, определяется конфигурацией oauth2-proxy
|-
| 6. Выпуск токена Svacer
| Svacer определяет наличие заголовка X-Forwarded-Access-Token в запросе. Если конфигурация сервера подразумевает использование OIDC протокола, то полученный токен проверяется и на его основе создается токен Svacer, после чего выполняется вход в систему и создается пользователь Svacer (если еще не создан), соответствующий пользователю, указанному в токене доступа от OAuth2 сервера
|}

== Конфигурация Svacer для поддержки протокола OIDC ==

Для конфигурации Svacer необходимо использовать секцию ''auth'' стандартного конфигурационного файла Svacer, указываемого через опцию ''--config'' при его запуске.

svacer-server run --config config.yaml

Пример секции ''auth'' конфигурационного файла представлен ниже
oidc:
enabled: true
debug: true
oauth_proxy:
enabled: true
clock: 1
sign_in: "<nowiki>http://keycloak:12800/realms/svacer/protocol/openid-connect/token</nowiki>"
sign_out: "<nowiki>http://oauth_proxy:4180/oauth2/sign_out?rd=/oauth2/sign_in</nowiki>"
tokens:
- claims:
subject: preferred_username
role: svacer_role
sync_roles: svacer_roles
first_name: given_name
second_name: second_name
last_name: family_name
email: email
sign:
- key: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvR/zIW/acyWFVSuSD/8iDM3epguHljKZkaB4ITojRwisXNcn6S0ArlI8v69qV1tBFi+RH3Ys4L5Pj+xDFlemlml6wPp5X0tcD2Gax51KHqQcFjViBGVSqJUdts/bkvfiIfZLkurybkhR0ALToWvbNyD7>
name: rsa
В секции используются следующие поля:

{| class="wikitable"
! Название
! Описание
|-
| '''''enabled'''''
| Использовать ''OIDC'' провайдер. Значение ''false'' отключает данный функционал
|-
| '''''debug'''''
| Выводить в логи сервера дополнительные отладочные сообщения. Полезно при первичной настройке, в дальнейшем желательно установить в значение ''false''
|-
| '''''oauth_proxy.enabled'''''
| Использовать утилиту ''oauth2-proxy'' в качестве механизма поддержки протокола OIDC. На текущий момент это единственная реализация поддержки ''OIDC'' протокола
|-
| '''''oauth_proxy.clock'''''
| Допускаемая погрешность расхождения времени между сервером аутентификации и клиентом. Указывается значение в минутах
|-
| '''''oauth_proxy.sign_in'''''
| Точка входа сервера OAuth2 для получения токена. Используется в Svacer только для работы CLI команд и сервисной учетной записи. При некорректном значении работа клиента Svacer с сервером Svacer через ''OIDC'' будет невозможна, но при правильной настройке других параметров, в GUI пользователи работать смогут
|-
| '''''oauth_proxy.sign_out'''''
| Ссылка, которая будет использована при выходе пользователя из системы (logout в GUI). Более подробно см. [[OIDC#Выход пользователя из системы|Выход пользователя из системы]]
|-
| '''''oauth_proxy.tokens'''''
| Массив объектов (''token''), описывающих структуру ''JWT'' токена ''OIDC'' сервера и данные, необходимые для проверки выпускаемого им токена
|-
| '''''token.claims'''''
| Описывает структуру токена. Поля этой сущности определяют свойства создаваемого внутреннего пользователя Svacer и его права
|-
| '''''token.claims.subject'''''
| Название поля из Claims токена, значение которого будет использовано для заполнения свойства ''Логин'' у созданного пользователя Svacer
|-
| '''''token.claims.first_name'''''
| Название поля из Claims токена, значение которого будет использовано для заполнения свойства ''Имя'' у созданного пользователя Svacer
|-
| '''''token.claims.second_name'''''
| Название поля из Claims токена, значение которого будет использовано для заполнения свойства ''Отчество'' у созданного пользователя Svacer
|-
| '''''token.claims.last_name'''''
| Название поля из Claims токена, значение которого будет использовано для заполнения свойства ''Фамилия'' у созданного пользователя Svacer
|-
| '''''token.claims.email'''''
| Название поля из Claims токена, значение которого будет использовано для заполнения свойства ''E-Mail'' у созданного пользователя Svacer
|-
| '''''token.claims.role'''''
| Название поля из Claims токена, значение которого будет использовано для добавления роли пользователю Svacer. Значение должно быть именем уже существующей роли или значением "admin" для добавления роли администратора. Автоматическое назначение роли происходит только при первом создании пользователя
|-
|'''''token.claims.sync_roles'''''
|Название поля из Claims токена, которое содержит полный список доступных ролей Svacer для механизма автоназначения ролей
|-
| '''''token.sign'''''
| Содержит данные, необходимые для проверки подписи ''JWT'' токена
|-
| '''''token.sign.key'''''
| Открытый ключ, используемый OIDC сервером для проверки токена. Формат: BASE64(ASN1.DER)
|-
| '''''token.sign.name'''''
| Имя алгоритма ЭЦП. Поддерживаются: RSA, ECDSA
|-
|
|
|}

== Конфигурация OAuth2-proxy ==

Конфигурация OAauth2-proxy может выполнятся через параметры CLI, через указание параметров в конфигурационном файле, а также через переменные окружения. Названия параметров, передаваемых в CLI, в конфигурационном файле и через переменные окружения находятся в следующем соответствии друг с другом (на примере параметра ''client_secret''):

{| class="wikitable"
! Конфигурационный файл
! CLI
! Переменная окружения
|-
| client_secret
| --client-secret
| OAUTH2_PROXY_CLIENT_SECRET
|}

'''Для нормальной работы желательно наличие DNS имен для хостов (OAuth2-proxy использует Cookies для хранения там информации о сессии аутентификации пользователя а также для хранения csrf токена).'''

Ниже приводится пример конфигурации oauth2-proxy для подключения Svacer сервера к OAuth2 серверу Keycloak
<pre class="">standard_logging = true
standard_logging_format = "[{{.Timestamp}}] [{{.File}}] {{.Message}}"
auth_logging = true
auth_logging_format = "{{.Client}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}"
pass_user_headers = true
pass_host_header = true
email_domains = [
"*"
]
client_id = "svacer-auth-proxy"
client_secret = "q2rNKGofxpw7FzmZDstSIyNNyzkW1BsW"
pass_access_token = true
cookie_name = "_oauth2_proxy2"
cookie_secret = "2-W9DDrnlfBEK75F3zGpszuwTSqwBcUFQm6OQa3dHgU="
cookie_expire = "11m"
cookie_refresh = "10m"
cookie_secure = false
provider = "keycloak-oidc"
show_debug_on_error = true
cookie_csrf_per_request = true
cookie_csrf_expire = "36h"
skip_auth_routes = ["GET=/static/.*","/api/public/*","GET=/api/auth_settings"]
</pre>
В файле выше указаны не все требуемые параметры для нормальной работы OAuth2-proxy. Ниже приведены наиболее важные параметры конфигурационного файла OAuth2-proxy с пояснениями

{| class="wikitable"
! Название
! Описание
|-
| client_id
| Название клиента (в терминах OAuth2), от имени которого пользователь будет аутентифицироваться на сервере OAuth
|-
| client_secret
| Секрет клиента (в терминах OAuth2)
|-
| pass_access_token
| Передавать токен доступа от Oauth2 сервера в Svacer (через заголовки). Данный токен будет использован сервером Svacer для идентификации и аутентификации пользователя, а также для получения первоначальной информации о нем
|-
| provider
| Имя провайдера OAuth2
|-
| cookie_csrf_per_request
| Возможность отправки нескольких запросов одновременно
|-
| skip_auth_routes
| Указывается список запросов, которые не требуют аутентификации. Для корректной работы Svacer необходимо указать значения из примера выше
|-
| http_address
| Имя хоста, на котором будет работать OAuth2-proxy, см. пример в разделе [[OIDC#Конфигурация в Docker|Конфигурация в Docker]]
|-
| upstreams
| Хост, на котором работает Svacer, см. пример в разделе [[OIDC#Конфигурация в Docker|Конфигурация в Docker]]
|-
| redirect_url
| URL на который будет осуществлено перенаправление после успешной аутентификации на OAuth2 сервере, см. пример в разделе [[OIDC#Конфигурация в Docker|Конфигурация в Docker]]
|-
| oidc_issuer_url
| URL сервера OAuth2 для начала аутентификации, см. пример в разделе [[OIDC#Конфигурация в Docker|Конфигурация в Docker]]. С помощью данного URL будет получен список точек входа для поддержки разных потоков аутентификации (в терминах OAuth2)
|}

=== Детали работы OAuth2-proxy с куками и токенами ===

Для корректной настройки OAuth2-proxy полезно понимать детали работы OAath2-proxy. На шаге 2 прокси определяет необходимость выполнения аутентификации пользователя. Прокси проверяет наличие куки ''_oauth2_proxy'' и его срок действия. Срок действия создаваемых кук указывается в поле ''cookie_expire''. Если срок действия куки закончен, то пользователь будут перенаправлен на точку входа прокси: ''/oauth2/sign_in''.

Важным полем конфигурации является поле ''cookie_refresh''. При каждом запросе прокси обновляет свои куки с периодичностью, указанной в ''cookie_refresh''. Вместе с обновлением своих куки прокси проверяет состояние сессии на OAuth2 сервере и получает новый токен доступа. То есть, если в поле ''cookie_refresh'' стоит значение 1 минута, 1 раз в минуту (если пользователь отправляет запросы 1 раз в 10 секунд, то каждый 6 запрос будет обновлять куки прокси) OAuth2-proxy будет обновлять свои куки ''_oauth2_proxy'' и обновлять состоянии сессии аутентификации на сервере OAuth2 с получением токена доступа. Если сессия OAuth2 завершена, пользователь будет перенаправлен на точку входа аутентификации сервера OAuth2.

== Выход пользователя из системы ==

Процедура выхода пользователя из Svacer состоит из двух этапов. На первом этапе производится инвалидация токена Svacer, далее осуществляется переход по ссылке указанной в параметре ''oauth_proxy.sign_out'' с тем, чтобы прокси сервер или/и OAuth2 сервер смогли выполнить инвалидацию сущностей аутентификации, выданных пользователю. Явным признаком корректной работы выхода пользователя из системы является отсутствие данных аутентификации в куках сервера OAuth2 (и/или прокси) после выхода пользователя из системы.

== Работа со Svacer через CLI ==
Для работы в Svacer через CLI необходимо создать Personal Token в графическом интерфейсе и передавать его каким-либо предусмотренным способом (например, через переменную окружения SVACER_AUTH_TOKEN).

== Автоназначение ролей пользователю на основе содержимого Claims токена ==
В Svacer реализован механизм автоназначения ролей пользователю на основе получаемого от провайдера аутентификации (например KeyCloak) токена. Для работы этого механизма необходимо:

# В Svacer создать необходимые роли (доступные для автоназначения)
# Посредством настройки провайдера аутентификации добавить в Claims пользователя два поля. Первое поле (token.claims.sync_roles) - содержит список администрируемых ролей. Второе поле содержит список ролей, доступных в текущий момент пользователю (token.claims.role).
# Указать название полей из пункта 2 в полях конфигурации token.claims.role и token.claims.sync_roles

Механизм автоназначения ролей будет обеспечивать наличие у пользователя ролей, получаемых по следующей формуле: <code>haveSet.Sub(syncSet).Add(tokenSet.Mul(syncSet))</code>

Где:
* haveSet — текущее множество ролей пользователя
* syncSet — роли из списка sync_roles
* token_set — роли из списка role
* Sub, Add, Mul — соответствующие операции над множествами

{{Note|text=С версии 11 в поле Claims, указанном в конфигурации в '''token.Claims.role''', должен находится массив ролей, а не единcтвенное значение}}

== Возможные проблемы при настройке ==

=== Сообщение 'Cookies not found' ===

Проблема в DNS имена хоста Keycloak. Проблема встречается когда хост Keycloak имеет разные имена или в некоторых случаях обращение к нему происходит по IP адресу.

=== Сообщение 'Invalid parameter: redirect_url' ===

[[File:Image-20240529151256529.png|thumb|none]]

При перенаправлении пользователя на Keycloak сервер, OAuth2-proxy передал неверное значение в параметре ''redirect_uri''. Необходимо проверить, что в настройках Keycloak и в параметре ''redirect_uri'' OAauth2-proxy находятся одинаковые значения

[[File:Image-20240529152158450.png|thumb|none]]

=== Сообщение 'CSRF cookie failed validation' ===
Данная ошибка появляется по следующим причинам:
* ''csrf'' токен не найден в куках; Можно открыть консоль разработчика и убедится, что в куках для хоста oauth2-proxy есть кука: ''_oauth2_proxy_csrf_XXXXX''
* ''csrf'' токен истек; Для решения проблемы можно увеличить время действия ''csrf'' токена (см. [[OIDC#Конфигурация OAuth2-proxy|Конфигурация OAuth2-proxy]])
* был произведен перезапуск oauth2-proxy, а строка адреса в URL осталась от предыдущего запуска; Попробовать начать процедуру входа снова, перейдя на главную страницу OAuth2-proxy

=== Строка переключения языка GUI Svacer и белый экран. ===

Сервер Svacer недоступен.

=== При работе с CLI возникает ошибка: 'Failed to query server. Details: server response error: 403' ===

Не прописано исключение для запроса: /''api/public/server/info''

=== При работе с CLI возникает ошибка: 'Cannot get authentication settings from server StatusCode: 403' ===

Не прописано исключение для запроса: ''/api/auth_settings''

=== При работе с CLI возникает ошибка: 'ERROR: invalid character '<' looking for beginning of value' ===

Не прописано исключение для запроса: ''/api/public/oidc/login''

== Конфигурация в Docker ==

Ниже приводятся примеры конфигурации контейнеров для запуска Svacer в тестовом режиме с целью понимания логики работы oauth2-proxy совместно со Svacer и сервером Keycloak.

=== Образы Docker ===

==== Svacer ====

Файл Dockerfile:

<pre class="">FROM ubuntu:22.04

LABEL maintainer="akuzmin@ispras.ru"

ARG DEBIAN_FRONTEND=noninteractive

RUN apt update && apt install -y --no-install-recommends curl \
&& rm -rf /var/cache/apt/archives /var/lib/apt/lists/* \
&& mkdir -p /svacer/bin && mkdir -p /svacer/store

COPY svacer/bin/svacer-server /svacer/bin/
COPY svacer/bin/svacer /svacer/bin/

WORKDIR /svacer/bin

ENV STORE=/svacer/store
ENV SVACER_PG_URL=postgres://svace:svace@127.0.0.1:5432/svace
ENV MEMSETTINGS=default
ENV PATH=/svacer/bin:$PATH

EXPOSE 8080

CMD /svacer/bin/svacer-server --memsettings=${MEMSETTINGS} run --store $STORE --pg $SVACER_PG_URL --config /config/config.yaml
</pre>

==== OAuth2-proxy ====

Файл Dockerfile:

<pre class="">FROM ubuntu:22.04
LABEL maintainer="chernykov_sv@ispras.ru"
RUN mkdir /config
RUN mkdir /logs
#COPY oauth.cfg oauth.cfg
WORKDIR /oauth
COPY oauth2-proxy oauth2-proxy
COPY start.sh start.sh
RUN apt update && apt install curl -y
ENTRYPOINT ["/bin/bash", "-c", "/oauth/start.sh"]
</pre>
Скрипт start.sh (полезен для определения факта запуска Keycloak контейнера):

<pre class="">#!/bin/bash
exit='no'
start='no'
tmt=60
echo "Using $KEYCLOAK_HOST"
until [[ $exit == 'yes' ]]; do
sleep 5
tmt=$(($tmt-5))
if [[ $tmt == 0 ]]; then
exit='yes'
fi

resp=`curl --head -fsS http://$KEYCLOAK_HOST/health/ready`
if [[ $? == 0 ]]; then
exit='yes'
start='yes'
fi

done
if [[ $start == 'yes' ]]; then
echo 'Starting oauth...'
./oauth2-proxy --config /config/oauth.cfg --logging-filename /logs/oauth.log
else
echo "Keycloak is not ready ...Can not start oauth2_proxy"
fi
</pre>

=== Docker-compose ===
Файл docker-compose.yml

<pre class="">version: "3.6"
services:
oauth_proxy:
image: oauth_proxy
container_name: oauth_proxy
environment:
- OAUTH2_PROXY_HTTP_ADDRESS=http://oauth_proxy:8080
- OAUTH2_PROXY_UPSTREAMS=http://svacer:8080
- OAUTH2_PROXY_REDIRECT_URL=http://oauth_proxy:4180/oauth2/callback
- OAUTH2_PROXY_OIDC_ISSUER_URL=http://keycloak:8888/realms/svacer
- KEYCLOAK_HOST=keycloak:8888
volumes:
- ./config/proxy:/config
- ./logs:/logs

depends_on:
svacer:
condition: service_healthy
ports:
- "4180:8080"
networks:
svacer_oauth:
ipv4_address: 10.10.10.2

postgresql:
image: postgres:12.16
container_name: oauth_postgres
restart: always
shm_size: 1g
environment:
- POSTGRES_DB=svace
- POSTGRES_USER=svace
- POSTGRES_PASSWORD=svace
- POSTGRES_ROOT_PASSWORD=svace
expose:
- "5432"
volumes:
- ./postgres_data:/var/lib/postgresql/data
networks:
svacer_oauth:
ipv4_address: 10.10.10.3
healthcheck:
test: pg_isready -U svace
interval: 8s
start_period: 16s
timeout: 4s
retries: 4

keycloak:
image: keycloak:latest
container_name: oauth_keycloak
environment:
- KEYCLOAK_ADMIN=admin
- KEYCLOAK_ADMIN_PASSWORD=1234
- KEYCLOAK_LOGLEVEL=TRACE
- KC_HEALTH_ENABLED=true
command:
- start-dev
- --import-realm
- --http-port=8888
volumes:
- ./keycloak_realm:/opt/keycloak/data/import
ports:
- "8888:8888"
expose:
- "8888"
networks:
svacer_oauth:
ipv4_address: 10.10.10.3
healthcheck:
test: pg_isready -U svace
interval: 8s
start_period: 16s
timeout: 4s
retries: 4

svacer:
image: oauth_svacer:latest
container_name: oauth_svacer
restart: always
shm_size: 1g
depends_on:
postgresql:
condition: service_healthy
ports:
- "3002:3002"
- "18080:8080"
volumes:
- ./svacer_data:/data
- ./config/svacer/:/config
environment:
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
- SVACER_DEBUG=true
- SVACER_OPT='--config /config/oidc3.yaml'
- STORE=/data/store
networks:
svacer_oauth:
ipv4_address: 10.10.10.5
healthcheck:
test: curl --fail http://localhost:8080/api/health || exit 1
interval: 8s
start_period: 16s
timeout: 4s
retries: 4

networks:
svacer_oauth:
driver: bridge
ipam:
config:
- subnet: 10.10.10.0/24
gateway: 10.10.10.1
</pre>

Help:CLI

2025-05-16T13:30:20Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены. <code>svacer server token create --name token_name --ttl day_to_live --details more_info</code> TTL указывается в днях. Параметры name, ttl - обязательны
* Просмотреть список созданных токенов. <code>svacer server token list</code>
* Удалить токен <code>svacer server token delete --id token_id</code>
* Управлять токенами других пользователей <code>svacer server token admin delete --id token_id</code> - удаление токена. <code>svacer server token list --user user_id_or_login</code>. Требуется наличие прав по управлению пользователями.

Сейчас наложено единственное ограничение на создаваемые токены - нельзя с помощью такого токена создавать другие токены. Каждый пользователь может создавать токены также через public api: /api/public/personal_token. См. описание swagger.

Созданные токены можно в дальнейшем использовать в качестве значения переменной окружения SVACER_AUTH_TOKEN

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:28:37Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены. <code>svacer server token create --name token_name --ttl day_to_live --details more_info</code> TTL указывается в днях. Параметры name, ttl - обязательны
* Просмотреть список созданных токенов. <code>svacer server token list</code>
* Удалить токен <code>svacer server token delete --id token_id</code>
* Управлять токенами других пользователей <code>svacer server token admin delete --id token_id</code> - удаление токена. <code>svacer server token list --user user_id_or_login</code>. Требуется наличие прав по управлению пользователями.

Сейчас наложено единственное ограничение на создаваемые токены - нельзя с помощью такого токена создавать другие токены. Каждый пользователь может создавать токены также через public api: /api/public/personal_token. См. описание swagger.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:28:05Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены. <code>svacer server token create --name token_name --ttl day_to_live --details more_info</code> TTL указывается в днях. Параметры name, ttl - обязательны
* Просмотреть список созданных токенов. <code>svacer server token list</code>
* Удалить токен <code>svacer server token delete --id token_id</code>
* Управлять токенами других пользователей <code>svacer server token admin delete --id token_id</code> - удаление токена. <code>svacer server token list --user user_id_or_login</code>. Требуется наличие прав по управлению пользователями.

Сейчас наложено единственное ограничение на создаваемые токены - нельзя с помощью такого токена создавать другие токены. Каждый пользователь может создавать токены также через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:27:23Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены. <code>svacer server token create --name token_name --ttl day_to_live --details more_info</code> TTL указывается в днях. Параметры name, ttl - обязательны
* Просмотреть список созданных токенов. <code>svacer server token list</code>
* Удалить токен <code>svacer server token delete --id token_id</code>
* Управлять токенами других пользователей <code>svacer server token admin delete --id token_id</code> - удаление токена. <code>svacer server token list --user user_id_or_login</code>. Требуется наличие прав по управлению пользователями.

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:27:08Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены. <code>svacer server token create --name token_name --ttl day_to_live --details more_info</code> TTL указывается в днях. Параметры name, ttl - обязательны
* Просмотреть список созданных токенов. <code>svacer server token list</code>
* Удалить токен <code>svacer server token delete --id token_id</code>
* Управлять токенами других пользователей <code>svacer server token admin delete --id token_id</code> - удаление токена. <code>svacer server token list --user user_id_or_login</code>Требуется наличие прав по управлению пользователями.

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:24:55Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены. <code>svacer server token create --name token_name --ttl day_to_live --details more_info</code> TTL указывается в днях. Параметры name, ttl - обязательны
* Просмотреть список созданных токенов. <code>svacer server token list</code>
* Удалить токен <code>svacer server token delete --id token_id</code>
* Управлять токенами других пользователей <code>svacer server token admin [list,delete] --id token_id --user user</code>. Требуется наличие прав по управлению пользователями.

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:23:24Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены. <code>svacer server token create --name token_name --ttl day_to_live --details more_info</code> TTL указывается в днях. Параметры name, ttl - обязательны
* Просмотреть список созданных токенов. <code>svacer server token list</code>
* Удалить токен <code>svacer server token delete --id token_id</code>
* Управлять токенами других пользователей <code>aaaa</code>. Требуется наличие прав по управлению пользователями.
* Создавать токены <code>aaaa</code>

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:20:41Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены. <code>svacer server token create --name token_name --ttl day_to_live --details more_info</code> TTL указывается в днях. Параметры name, ttl - обязательны
* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:19:47Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены svacer server token create --name token_name --ttl day_to_live --details more_info
* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:18:37Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>
* Создавать токены <code>aaaa</code>

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:18:12Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены <code></code>
* Создавать токены <code></code>
* Создавать токены <code></code>
* Создавать токены <code></code>
* Создавать токены <code></code>
* Создавать токены <code></code>

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:17:50Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>. Команда позволяет:

* Создавать токены

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:16:22Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда <code>svacer server token</code>

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:16:02Z

Chernykov sv: /* Аутентификация с использование Personal Token */

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Svacer поддерживает работу с Personal Token для аутентификации. Для этого используется команда

Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Help:CLI

2025-05-16T13:14:30Z

Chernykov sv:

== CLI features ==
=== Перенос снимков ===
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и [[Help:UI manual#Работа со снимками|веб-интерфейса]]. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.

Экспорт и импорт снимков из командной строки доступен пользователям с [[Help:UI manual#Описание ролевой модели|соответствующими правами]] для выбранного проекта/ветки.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Создание PDF отчета ===
Для создания PDF отчета по проекту из интерфейса командной строки используется команда '''pdfgen'''.

Общий вид команды следующий:
svacer pdfgen --cmp-mode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--target-project [name|id] --target-branch [name|id] --target-snapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --out-file report_name --tz time_zone --lang report_lang

* '''cmpMode''' — параметры сравнения. Возможные значения: '''none''' — без сравнения, '''new''' — новые, '''missing''' — отсутствующие, '''matched''' — сопоставленные, '''same''' — одинаковые
* '''project, branch, snapshot''' — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
* '''target-project, target-branch, target-snapshot''' — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
* '''file, checker, severity, review''' — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
* '''out-file''' — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
* '''tz''' — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
* '''lang''' — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).

Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: target-project, target-branch, target-snapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> target-project, branch -> target-branch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно использовать public API:
:URL — /api/public/exportPDF
:Метод — POST

Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

=== Импорт разметки из исходного кода ===
Импорт разметки из исходного кода на сервер истории возможен с помощью команды '''svacer markup import''', или с помощью CLI/REST API [[Markup2]].

Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--exclude-paths <path1, path2, ..., pathN> --from-build-object]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в который будет произведен импорт разметки
* branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
* snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
* exclude-paths — исключает файлы, соответствующие регулярным выражениям
* template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
* from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.

Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде

//svacer_review: -<warn class>[|-<warn class>]+

Пример:

if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд '''import --upload''' и '''upload''' следует указывать флаг '''--template <template>'''. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

==== Шаблон разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии прав доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через [[Help:UI manual#Экспорт кода с разметкой|выгрузку кода]] с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.

Пример:

//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);

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

=== Изменение инвариантов (--path-prefix) ===
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг '''--path-prefix''', то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду '''svacer markup update'''.

Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --path-prefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:
* user, password — пользователь и пароль учетной записи на сервере
* project — проект на сервере, в котором будет обновлена разметка
* branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
* path-prefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в '''Settings > Server information''').

=== Подавление предупреждений ===
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:

Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list

Пример
svacer markup --user admin --password admin --project tree-command suppress list

Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af

Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3

Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af

Убрать все подавления
svacer markup [auth/selection] suppress remove

Пример
svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

=== Автомиграция разметки ===
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).

svacer server automigrate [command] [flags]

Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг '''pattern''', применяется для команд <code><add|delete|show_config|log></code>

* Для '''add''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:regEx — в [https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP формате как для PostgreSQL]

* Для '''delete''': Паттерн автомиграции в формате: <code>srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}</code>
:Паттерн должен быть точно таким же, как он записан в Config Table

* Для '''show_config''': Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>

* Для '''log''': Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном

Флаг '''id''', применяется для command <code><delete|show_automigrate></code> в формате uuid

* Для '''delete''': id для удаления автомиграции (из Config Table)

* Для '''show_automigrate''': id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг '''format''' — формат вывода таблицы. Применяется для command <code><show_config|show_automigrate|log></code>

* Для '''show_config''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:* no-id — вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию — table.

* Для '''show_automigrate|log''':
:* table — вывод в виде таблицы
:* json — вывод в виде json
:По умолчанию — table.

Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и в CLI.

Принцип работы сервиса:
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* '''Может''' копировать разметку с нескольких веток на одну, а также поддерживает цепочки и циклы автомиграций (например 1->2->3->1)

* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.

* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
* Копируется последняя примененная разметка

=== Аутентификация из переменных окружения ===
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password
SVACER_AUTH_TOKEN=token
В качестве токена нужно использовать токен, получаемый через REST endpoint <code>/api/public/login</code>

Также пользователь может задать переменную окружения SVACER_APP_KEY или передать в CLI ключ <code>--app-key</code> для указания ключа подписи выдаваемых сервером Bearer токенов. Это позволит избежать необходимости повторого логина в веб интерфейсе Svacer после его перезапуска. Кроме того, сторонее приложение также сможет выдавать Bearer токены для сервера Svacer, которые сервер будет рассматривать как подлинные.

=== Аутентификация с использование Personal Token ===
Сейчас наложено единственное ограничение на токены - нельзя с помощью такого токена создавать другие. Но этот вопрос (ограничения), мне кажется надо отдельно обсудить, так как Андрей Кузьмин упоминал, что их использование ограничено.
Каждый пользователь может создавать токены через public api: /api/public/private_token. Swagger по нему добавлен
Пользователи могут управлять токенами через cli. Для этого есть команда svacer server token.

=== Вывод списка предупреждений ===
Пользователь может получить таблицу предупреждений с сервера, используя команду

svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id

Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.

При указании флага <code>--out-format=json</code> вывод будет произведен в JSON формате:

[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"

=== Слияние снимков из CLI (экспериментальная опция) ===
Пользователь может объединить несколько снимков в один используя команду
svacer container snapshot merge --host host --user user --password password --branch target_branch --name target_snapshot_name --snapshot val1 --snapshot val2 --snapshot val3 ...
При указании снимков для слияния и целевой ветки, пользователь может использовать либо UUID объектов либо формат
целевая ветка: <project name>:::<branch name>
снимок: <project name>:::<branch name>:::<snapshot name>
При слиянии можно использовать снимки из разных проектов и веток. Пользователь должен иметь доступ на чтение ко всем снимкам и на запись для целевой ветки

=== Управление контейнерами ===
См. [[Help:CLI/management/containers]]

=== Управление пользователями и ролями ===
См. [[User Management (command line)]]

=== Автоматическое удаление снимков ===
См. [[Help:CLI/cleanup]]

== Svacer server features ==

=== Запуск с конфиг-файлом ===
svacer-server run --config config.yml

'''--config <value>''' — путь к файлу конфигураций в формате YAML (по умолчанию svacer.cfg)

=== Поддержка сквозной аутентификации ===
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси '''Authorization Basic ...''', откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

svacer-server run --proxy-mode

=== Хуки ===
Для использования хуков при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.

Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}

'''Параметры хуков '''
{| class="wikitable"
| style="width:100px;" | ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. <br/>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице [[Примеры использования хуков]].

=== Ограничение числа запросов ===
Чтобы ограничить число запросов на сервер Svacer, перед запуском сервера определите переменную окружения со следующими параметрами

SVACER_SERVER_THROTTLE_PARAMS=limit,backlogLimit,timeout

* limit — число одновременных запросов
* backlogLimit — размер бэклога для запросов, которые нельзя обработать сейчас
* timeout — время ожидания запроса в бэклоге (формат 1m12s — duration)

Changelog

2025-05-16T11:12:17Z

Chernykov sv:

=== Release 11-0-0 ===
май 2025

* Убраны излишние сообщения в логе сервера о login/logout операциях. Они будут выводиться только при запуске сервера с опцией <code>--debug</code>
* Команды CLI <code>svacer sarif *</code> были убраны, для импорта и экспорта следует использовать <code>svacer sarif2 *</code>
* Экспорт SARIF теперь включает все комментарии как отдельные объекты в <code>Properties</code>
* При экспорте в SARIF теперь экспортируются поля <code>Labels, Orig function</code>
* Импорт SARIF теперь корректным образом учитывает relatedLocations и формирует трассу
* Импорт SARIF теперь автоматически импортирует исходники, если они включены в сам SARIF файл
* Добавлена возможность указания мэппинга severity детекторов при импорте из SARIF
* Добавлен механизм указания правил резолвинга путей при импортировании исходного кода вместе с SARIF файлом
* Экспорт исходников из снимка будет доступен только при наличии исходников на сервере
* Добавлен [[Help:Match#Классический режим генерации инвариантов|режим работы]] сервера где генерация инвариантов для переноса разметки соответствует режиму Svacer <=8.x.x. Режим включается через опции <code>--classic-inv-mode</code> или переменную окружения <code>SVACER_CLASSIC_INV_MODE=true|false</code>
* Добавлены флаги <code>--autoclean</code>, <code>--autoclean-svace</code> в команду <code>svacer import</code> для автоматического удаления <code>.svace-dir / .svacer-dir</code> после успешного импорта и загрузки данных на сервер
* Улучшена поддержка OIDC
* Улучшена поддержка LDAP
* Добавлена интеграция с хранилищем секретов Infisical
* Добавлена служба нотификаций пользователей через почтовые сообщения и мессенджер telegram
* Добавлен механизм аутентификации через Personal Token
* Добавлен механизм упоминания пользователей через специальную конструкцию @login в комментариях к разметке
* Добавлены дополнительные метрики в разделе Статистика

=== Release 10-0-1 ===
17.02.2025

* Исправлена ошибка с временной таблицей при обработке планов автомиграции разметки при импорте результатов (ERROR: relation "loaded_review" already exists)

=== Release 10-0-0 ===
16.01.2025

* Множество изменений в UI, смотрите [[Release notes 10-0-0]]
* Сделали [[Help:Installation#rpm|dnf/yum репозиторий]] для RPM-пакетов Svacer
* Реализована возможность [[Markup2|экспорта, импорта и копирования разметки посредством Public REST API и CLI]]
* Реализован дополнительный экспериментальный механизм [[Help:UI manual#Настройка интерфейса|генерации PDF на основе HTML]]. Генерация PDF переведена на асинхронный режим с показом нотификации пользователю
* Добавлена возможность очистки всей разметки и/или комментариев на ветке проекта
* Улучшения функциональности просмотра маркеров в встроенном IDE Theia
* Добавлена функциональность по [[Help:UI manual#Глобальный поиск|глобальному поиску]] маркеров, комментариев и снимков по различным атрибутам
* Добавлена возможность [[Help:UI manual#Просмотр статистики|получения статистики]] по маркерам и активностям пользователей при разметке
* В API fullmarkers добавлен параметр <code>labels: true/false</code> для выгрузки меток маркера
* Реализован Public API для получения/добавления/удаления меток маркеров
* Настройки LDAP и прочие настройки аутентификации добавлены в единый конфигурационный файл
* Добавлена возможность удаления кода из снимка при частичном импорте в Svacer
* Добавлена опция minVersion, maxVersion для TLS при запуске сервера Svacer
* Добавлена поддержка групп проектов при импорте снимков в CLI
* При импорте снимков реализована поддержка автоматического определения пути префикса для переноса разметки
* Исправлен ряд ошибок в импорте и генерации [[Help:Sarif|SARIF]]
* Исправлены ошибки в копировании разметки между ветками, клонировании проектов и веток
* Добавлена возможность отключения бэкграунд задач по очистке мусора
* Добавлено экспериментальное CLI API для просмотра асинхронных задач на генерацию PDF
* Добавлена возможность визуализации производительности сервера на основе [https://github.com/arl/statsviz statsviz]
* Добавлена поддержка относительных путей в svres файле
* Добавлена возможность ожидания завершения операций по очистки мусора при выполнении операций по импорту результатов анализа
* Добавлена поддержка CWE таксономий при экспорте [[Help:Sarif|SARIF]]
* Добавлена переменная окружения SVACER_TOKEN_LIFETIME для управления временем жизни токена аутентификации
* Добавлена переменная окружения SVACER_RESET_ADMIN_PASSWORD для явного указания желаемого пароля при операции по сбросу пароля администратора
* Добавлен [[Notifications|механизм нотификаций пользователей]] о внутренних событиях Svacer (экспериментальный функционал)

=== Release 9-0-2 ===
22.07.2024

* Еще некоторые исправления, связанные с миграцией данных
* Исправлена проблема с навигацией по Go to Definition

=== Release 9-0-1 ===
15.07.2024

* Исправлены ошибки в клонировании проектов, приводящие к размножению записей в некоторых внутренних таблицах
* Различные исправления, связанные с миграцией данных
* Исправлена работа ряда CLI команд с включенным TLS на сервере
* Исправлен ряд ошибок в генерации PDF

=== Release 9-0-0 ===
04.06.2024

* Множество изменений в UI, смотрите [[Release notes 9-0-0]]
* Svacer разделен на два исполняемых файла: <code>svacer-server</code> — сервер и <code>svacer</code> — клиент
* {{Note}}Object store заменен на другую реализацию. Конвертация данных запускается автоматически при апгрейде и требует примерно 2х-2.2х дискового пространства, после конвертации старый object store будет удален. Время конвертации зависит от объема данных и скорости диска
* {{Note}}Изменен [[Help:Match|алгоритм сопоставления предупреждений]]. При старте сервера будет произведена регенерация всех инвариантов во всех ветках. Это может занять продолжительное время (зависит от мощности сервера и объемов данных)
* Добавлена возможность [[Help:Match#Ручное сопоставление предупреждений (экспериментальная возможность)|ручного сопоставления предупреждений]] для переноса разметки
* Добавлена экспериментальная поддержка [[OIDC|OpenID]] протокола для аутентификации
* Добавлена экспериментальная возможность [[Help:CLI#Слияние снимков из CLI (экспериментальная опция)|слияния снимков через CLI]]
* Исправлены баги в [[Help:Sarif|импорте Sarif]], добавлена поддержка импорта с относительными путями к файлам (флаг <code>--base-dir</code>)
* Лог сервера работает в режиме append, прежние данные не затираются
* Добавлена возможность передачи токена аутентификации в клиент Svacer через переменную окружения <code>SVACER_AUTH_TOKEN=token</code>
* Добавлена возможность передачи логина и пароля в клиент Svacer через переменную окружения <code>SVACER_AUTH_CREDS=login:password</code>
* Добавлен public REST endpoint для импорта <code>.svace-dir</code> на стороне сервера
* Добавлена возможность импорта <code>.svace-dir</code> из веб-интерфейса
* Добавлены [[Metrics|метрики]] для Prometheus, доступны при запуске сервера с переменной окружения <code>SVACER_TRACE_OPTIONS=prom_metrics_on</code> на <code>/api/metrics</code>
* Добавлена очистка БД от мусора с возможностью настройки периодичности данной операции через переменную окружения <code>SVACER_GC_PERIOD=val</code> где val — duration в формате <code>hhmmss</code> или [https://en.wikipedia.org/wiki/Cron Cron]
* Добавлена возможность клонирования проектов
* Добавлен импорт <code>*warn, *.err</code> файлов из <code>.svace-dir</code>, которые содержат диагностические сообщения от Svace
* Добавлена возможность [[Help:CLI#Ограничение числа запросов|ограничения числа запросов]] на сервер с указанием параметров в переменной окружения <code>SVACER_SERVER_THROTTLE_PARAMS</code>
* Добавлен шаблон для импорта разметки из кода на Go: <code>DEFAULT_GO</code>
* Добавлена возможность [[Help:CLI#Аутентификация из файла|аутентификации из файла]]
* Исправлены проблемы безопасности
* Добавлена возможность просмотра исходного кода снимка с предупреждениями анализатора во внешней IDE собранной на базе [https://theia-ide.org/ Theia IDE]
* К команде automigrate add в CLI добавлен флаг <code>skip-exist</code>, чтобы при добавлении паттерна, который уже существует, не выдавало ошибки
* К команде upload (import с флагом upload) с указанием флага <code>quality-gate</code> теперь можно добавить флаг <code>quality-gate-verbose</code>. Если его указать, то также будет выведен результат успешных проверок quality-gate
* Улучшения в поддержке протокола LDAP

=== Release 8-0-1 ===
22.01.2024

* Исправлена работа в изолированной от сети среде. Загрузка Web UI больше не требует доступа к публичным CDN
* Добавлена поддержка функций при указании пользовательского фильтра
* Добавлено API для управления пользовательскими фильтрами. Детали и пример использования можно найти здесь: https://gitlab.ispras.ru/svacer-public/api-go-examples/-/tree/master/api-ui-settings
* Исправлено отображение Checker Severity при экспорте в SARIF. Теперь Critical -> error; Major, Normal -> warning; Minor -> note; any other -> warning

=== Release 8-0-0 ===
21.11.2023

* Множество изменений в UI. Смотрите обзор в [[Release notes 8-0-0]]
* Добавлен новый импорт и экспорт из SARIF в command line с поддержкой исходного кода в SARIF файлах и импортом описания детекторов из SARIF
* Добавлены группы проектов
* Переделана модель ролей и доступов. Добавлен CLI для управления ролями и доступами
* Добавлена возможность настройки автопереноса разметки между ветками, в том числе в разных проектах
* Импорт/экспорт снимков включает информацию о детекторах
* Исправлена работа интерфейса с Undefined детекторами (т. е. детекторами, информация о которых отсутствует в Svacer)
* Добавлено экспериментальное API по управлению детекторами и конфигурациями детекторов
* Добавлена очистка исходного кода от Svacer-specific комментариев перед экспортом разметки в код
* Добавлена возможность включения режима обязательного комментария при разметке кода. Комментарий будет сгруппирован с операцией разметки и будет иметь ссылку на нее
* Утилита миграции со старого svace-сервера больше не поддерживается. При необходимости миграции используйте утилиту из прошлых релизов Svacer
* Добавлена Swagger документация на API
* Добавлено хранение истории изменений комментариев
* Опция <code>--pathPrefix</code> поддерживает файлы в JSON формате вида: <code>[{ "prefix": "/some/path", "replace": "/test" }, ...]</code>
* При использовании операции по обновлению <code>pathPrefix</code> на сервере, данные о прежнем <code>pathPrefix</code> запоминаются в мета-информации о снимке
* Добавлена возможность переименования снимков в UI
* Sensitive информация (детали подключения к БД с данными аутентификации) убрана из UI и API
* ОС в docker-образе Svacer обновлена с Ubuntu 18 до Ubuntu 22
* Улучшена логика автоопределения портов и протоколов при соединении с сервером из Svacer CLI

=== Release 7-0-1 ===
23.05.2023

* Исправлена проблема с фильтрацией предупреждений для C# проектов

=== Release 7-0-0 ===
16.05.2023

* Убрана зависимость от PostgreSQL из .deb и .rpm пакетов, чтобы проще было ставить Svacer только как клиент
* Сделан пакет для Windows (.msi) и документация по установке и запуску на Windows
* Теперь, если при svacer import и svacer sarif не указан путь к проекту, им считается текущая директория
* Информация о разметке и блокировках теперь обновляется автоматически при изменении в другом браузере (табе) или другим пользователем
* UI для пользовательских фильтров улучшен и перенесен в правую верхнюю часть экрана
* UI для выбора проекта, ветки и снимка теперь находится на одном уровне
* Улучшен UI для режима сравнения снимков
* Добавлена возможность работать одновременно с несколькими открытыми файлами в режиме Code, это поведение можно изменить в настройках профиля пользователя
* В левой навигационной панели детекторы теперь по умолчанию группируются по серьезности, это поведение можно изменить в настройках профиля пользователя
* Профиль текущего пользователя теперь можно смотреть/редактировать только через меню в правом верхнем углу
* Добавлена возможность копирования в системном логе и журнале
* Для пользователя теперь запоминается последний контекст (проект/ветка/снимок), с которым он работал, он автоматически открывается при старте новой сессии
* Групповая разметка теперь делается единой транзакцией, в случае ошибок или отмены все изменения откатываются
* Добавлено предупреждение при использовании некорректных путей при использовании REST API с префиксом /api
* Поддержка указания паролей из файла или pipe-а при использование Svacer CLI
* Добавлена поддержка multi-tab code view для режима просмотра кода объекта сборки
* Добавлена поддержка сохранения информации об удаленных детекторах при загрузке информации о детекторах из новой версии Svace
* Исправлен импорт результатов анализа, если сборка проводилась с опцией --disable-dxr
* Исправлены проблемы при импорте и прикреплении нескольких файлов к снимку
* Исправлены ошибки с входом в систему пользователей LDAP (специальные символы в пароле, вход по атрибуту mail)
* Добавлена возможность использования резервных серверов LDAP
* Добавлена возможность автоматического назначения пользователям LDAP роли Svacer, в зависимости от принадлежности пользователя к LDAP группе
* Добавлены новые public запросы на получение маркеров/снимков/проектов с учетом заданных параметров фильтрации
* Добавлена поддержка TLS при работе сервера по протоколам HTTP и gRPC
* Добавлена возможность загрузки статистики по общему количеству предупреждений и по количеству размеченных предупреждений для проектов и веток через REST API
* Добавлена вкладка выбора проектов в расширении VSCode
* Убрана возможность использовать всплывающее окно в VScode для добавления/редактирования/удаления комментариев, установки ревью-статусов, локов и т.д.

=== Release 6-0-3 ===
25.01.2023

* RPM-пакет теперь при сборке упаковывается в gzip вместо zstd для обратной совместимости со старыми дистрибутивами
* Если short url некорректен, то Svacer теперь будет возвращать корректный http error NotFound
* Если путь к лог файлу явно не указан, то svacer.log будет создаваться во временной директории. Это решает проблемы при запуске Svacer из директорий с запретом на запись. Путь к лог файлу будет печататься в stdout
* Лог файлы не будут создаваться, когда используется опция --help
* Исправлены проблемы при миграции схемы данных, когда в PostgreSQL используется SSL подключение
* Добавлены описания детекторов из последнего релиза Svace, которые были пропущены в релизе 6-0-2
* Исправлена работа Svacer за proxy-сервером, где выставляется Header "X-Content-Type-Options nosniff"
* Добавлены кнопки для скачивания системного лога и журнала из web-интерфейса
* Поправлен ряд ошибок валидации схемы при экспорте в SARIF
* Исправлено поведение при наличии нескольких хуков в конфигурационном файле
* В информацию о маркере для хуков добавлены checker severity и reliability
* Исправлен случайный порядок URL для маркеров при использовании public API для получения URL-ов
* На главную страницу добавлена кнопка "Помощь", которая открывает документацию
* При использовании команд навигации в режиме "Browse code" текущий файл теперь корректно подсвечивается в дереве файлов
* В диалоге групповой разметки убран индикатор изменений в виде кружочка, наличие изменений можно определить по активности кнопок "Apply" и "Reset"
* Кнопка обновления в верхнем меню теперь корректно обновляет информацию на странице Settings/Project
* Различные небольшие исправления в пользовательском интерфейсе

=== Release 6-0-2 ===
16.12.2022

* Исправлена проблема в UI с сохраненными пользовательскими фильтрами

=== Release 6-0-1 ===
13.12.2022

* Добавлено описание ряда детекторов, которые есть в последнем релизе Svace 3.3.2 но были пропущены в Svacer
* Исправлено вылетание в Login Screen при удалении нотификации из панели нотификаций
* Исправлено появление белого экрана при клике на детектор, информация о котором отсутствует
* Ряд различных небольших исправлений в UI
* Промежуточное хранилище будет очищаться по умолчанию при использовании команды import

=== Release 6-0-0 ===
30.11.2022

* Добавлено копирование комментариев при копировании разметки
* Комментарии добавлены к отчету в формате csv
* Добавлена возможность вводить пароль с клавиатуры для консольных команд
* Добавлена возможность импортировать разметку из объекта сборки (из ранее загруженных данных)
* Добавлена возможность импортировать разметку сразу после загрузки на сервер (опция для команды svacer upload)
* Добавлена возможность загружать исходный код не из папки .svace-dir
* Добавлена возможность бэкапа и восстановление объектного хранилища в сервер PostgresSQL
* Добавлена возможность создания отчета по проекту в формате PDF через интерфейс командной строки и посредством REST API
* Добавлена возможность подавления предупреждений через inline комментарии в коде
* Добавлена возможность подавления предупреждений по идентификатору предупреждения через command line и REST API
* Добавлена возможность ассоциировать организацию с пользователем и реестр организаций
* Добавлена фильтрация списка комментариев по пользователю в правой панели веб-интерфейса
* Добавлен поиск пользователей по его атрибутам в панели управления пользователями
* Добавлена возможность заполнения данных профиля LDAP пользователя данными, полученными от LDAP сервера
* Добавлена возможность прикреплять файлы к снимкам при импорте результатов (данные файлы составляют часть экспортируемых данных при экспорте снимков)
* Добавлена возможность ассоциировать пользовательские атрибуты типа "строка" или массив строк со снимком при импорте данных (данные атрибуты составляют часть экспортируемых данных при экспорте снимков)
* Добавлены command line операции по получению прикрепленных файлов и пользовательских атрибутов со снимков
* Добавлена возможность группового добавления комментариев
* Добавлена возможность указания сетевого интерфейса для работы WEB и GRPC серверов
* Добавлен вывод краткой статистики по загруженному снимку при команде upload. Поддерживается текстовой и JSON форматы вывода
* Существенно расширены возможности по интеграции Visual Studio Code с сервером Svacer
* Добавлен флаг --git в команду import. При наличии такого флага, ищется ближайший git репозиторий содержащий .svace-dir и при наличии такого - используется путь к гит репозиторию для замены путей на префикс .build.
* Portable PostgreSQL больше не входит в поставку. Вместо него поставляется docker-compose.yml файл для запуска PostgreSQL в докер-контейнере
* Добавлено больше данных и информации об ошибках в вывод команды svacer import
* Изменение Public API: добавлена точка входа /api/public/login
* Операции по импорту и экспорту снимков доступны теперь обычным пользователям (не администраторам) при использовании command line интерфейса
* Операция по экспорту снимков доступна обычному пользователю из веб-интерфейса (импорт все еще требует роль администратора для веб-интерфейса)
* Операции по экспорту снимков переведены на асинхронный режим. Нотификация о готовности будет показана пользователю и доступна в панели нотификаций
* Обновлено описание детекторов в соответствии с релизом Svace 3.3.2
* Исправлена ошибка обработки корневых сертификатов при подключении к LDAP серверу по протоколу ldaps
* Исправлено ошибочное создание дубликатов локальных учетных записей LDAP пользователей (case sensitive login)
* Различные исправления в пользовательском интерфейсе с целью оптимизации производительности
* Добавлены пропущенные проверки ролей при работе с веб-интерфейсом
* Svacer больше не создает временные файлы в директории с исполняемым файлом
* Устаранены задержки при удалении веток и проектов

Changelog

2025-05-16T11:09:09Z

Chernykov sv:

=== Release 11-0-0 ===
май 2025

* Убраны излишние сообщения в логе сервера о login/logout операциях. Они будут выводиться только при запуске сервера с опцией <code>--debug</code>
* Команды CLI <code>svacer sarif *</code> были убраны, для импорта и экспорта следует использовать <code>svacer sarif2 *</code>
* Экспорт SARIF теперь включает все комментарии как отдельные объекты в <code>Properties</code>
* При экспорте в SARIF теперь экспортируются поля <code>Labels, Orig function</code>
* Импорт SARIF теперь корректным образом учитывает relatedLocations и формирует трассу
* Импорт SARIF теперь автоматически импортирует исходники, если они включены в сам SARIF файл
* Добавлена возможность указания мэппинга severity детекторов при импорте из SARIF
* Добавлен механизм указания правил резолвинга путей при импортировании исходного кода вместе с SARIF файлом
* Экспорт исходников из снимка будет доступен только при наличии исходников на сервере
* Добавлен [[Help:Match#Классический режим генерации инвариантов|режим работы]] сервера где генерация инвариантов для переноса разметки соответствует режиму Svacer <=8.x.x. Режим включается через опции <code>--classic-inv-mode</code> или переменную окружения <code>SVACER_CLASSIC_INV_MODE=true|false</code>
* Добавлены флаги <code>--autoclean</code>, <code>--autoclean-svace</code> в команду <code>svacer import</code> для автоматического удаления <code>.svace-dir / .svacer-dir</code> после успешного импорта и загрузки данных на сервер
* Улучшена поддержка OIDC
* Улучшена поддержка LDAP
* Добавлена интеграция с хранилищем секретов Infisical

=== Release 10-0-1 ===
17.02.2025

* Исправлена ошибка с временной таблицей при обработке планов автомиграции разметки при импорте результатов (ERROR: relation "loaded_review" already exists)

=== Release 10-0-0 ===
16.01.2025

* Множество изменений в UI, смотрите [[Release notes 10-0-0]]
* Сделали [[Help:Installation#rpm|dnf/yum репозиторий]] для RPM-пакетов Svacer
* Реализована возможность [[Markup2|экспорта, импорта и копирования разметки посредством Public REST API и CLI]]
* Реализован дополнительный экспериментальный механизм [[Help:UI manual#Настройка интерфейса|генерации PDF на основе HTML]]. Генерация PDF переведена на асинхронный режим с показом нотификации пользователю
* Добавлена возможность очистки всей разметки и/или комментариев на ветке проекта
* Улучшения функциональности просмотра маркеров в встроенном IDE Theia
* Добавлена функциональность по [[Help:UI manual#Глобальный поиск|глобальному поиску]] маркеров, комментариев и снимков по различным атрибутам
* Добавлена возможность [[Help:UI manual#Просмотр статистики|получения статистики]] по маркерам и активностям пользователей при разметке
* В API fullmarkers добавлен параметр <code>labels: true/false</code> для выгрузки меток маркера
* Реализован Public API для получения/добавления/удаления меток маркеров
* Настройки LDAP и прочие настройки аутентификации добавлены в единый конфигурационный файл
* Добавлена возможность удаления кода из снимка при частичном импорте в Svacer
* Добавлена опция minVersion, maxVersion для TLS при запуске сервера Svacer
* Добавлена поддержка групп проектов при импорте снимков в CLI
* При импорте снимков реализована поддержка автоматического определения пути префикса для переноса разметки
* Исправлен ряд ошибок в импорте и генерации [[Help:Sarif|SARIF]]
* Исправлены ошибки в копировании разметки между ветками, клонировании проектов и веток
* Добавлена возможность отключения бэкграунд задач по очистке мусора
* Добавлено экспериментальное CLI API для просмотра асинхронных задач на генерацию PDF
* Добавлена возможность визуализации производительности сервера на основе [https://github.com/arl/statsviz statsviz]
* Добавлена поддержка относительных путей в svres файле
* Добавлена возможность ожидания завершения операций по очистки мусора при выполнении операций по импорту результатов анализа
* Добавлена поддержка CWE таксономий при экспорте [[Help:Sarif|SARIF]]
* Добавлена переменная окружения SVACER_TOKEN_LIFETIME для управления временем жизни токена аутентификации
* Добавлена переменная окружения SVACER_RESET_ADMIN_PASSWORD для явного указания желаемого пароля при операции по сбросу пароля администратора
* Добавлен [[Notifications|механизм нотификаций пользователей]] о внутренних событиях Svacer (экспериментальный функционал)

=== Release 9-0-2 ===
22.07.2024

* Еще некоторые исправления, связанные с миграцией данных
* Исправлена проблема с навигацией по Go to Definition

=== Release 9-0-1 ===
15.07.2024

* Исправлены ошибки в клонировании проектов, приводящие к размножению записей в некоторых внутренних таблицах
* Различные исправления, связанные с миграцией данных
* Исправлена работа ряда CLI команд с включенным TLS на сервере
* Исправлен ряд ошибок в генерации PDF

=== Release 9-0-0 ===
04.06.2024

* Множество изменений в UI, смотрите [[Release notes 9-0-0]]
* Svacer разделен на два исполняемых файла: <code>svacer-server</code> — сервер и <code>svacer</code> — клиент
* {{Note}}Object store заменен на другую реализацию. Конвертация данных запускается автоматически при апгрейде и требует примерно 2х-2.2х дискового пространства, после конвертации старый object store будет удален. Время конвертации зависит от объема данных и скорости диска
* {{Note}}Изменен [[Help:Match|алгоритм сопоставления предупреждений]]. При старте сервера будет произведена регенерация всех инвариантов во всех ветках. Это может занять продолжительное время (зависит от мощности сервера и объемов данных)
* Добавлена возможность [[Help:Match#Ручное сопоставление предупреждений (экспериментальная возможность)|ручного сопоставления предупреждений]] для переноса разметки
* Добавлена экспериментальная поддержка [[OIDC|OpenID]] протокола для аутентификации
* Добавлена экспериментальная возможность [[Help:CLI#Слияние снимков из CLI (экспериментальная опция)|слияния снимков через CLI]]
* Исправлены баги в [[Help:Sarif|импорте Sarif]], добавлена поддержка импорта с относительными путями к файлам (флаг <code>--base-dir</code>)
* Лог сервера работает в режиме append, прежние данные не затираются
* Добавлена возможность передачи токена аутентификации в клиент Svacer через переменную окружения <code>SVACER_AUTH_TOKEN=token</code>
* Добавлена возможность передачи логина и пароля в клиент Svacer через переменную окружения <code>SVACER_AUTH_CREDS=login:password</code>
* Добавлен public REST endpoint для импорта <code>.svace-dir</code> на стороне сервера
* Добавлена возможность импорта <code>.svace-dir</code> из веб-интерфейса
* Добавлены [[Metrics|метрики]] для Prometheus, доступны при запуске сервера с переменной окружения <code>SVACER_TRACE_OPTIONS=prom_metrics_on</code> на <code>/api/metrics</code>
* Добавлена очистка БД от мусора с возможностью настройки периодичности данной операции через переменную окружения <code>SVACER_GC_PERIOD=val</code> где val — duration в формате <code>hhmmss</code> или [https://en.wikipedia.org/wiki/Cron Cron]
* Добавлена возможность клонирования проектов
* Добавлен импорт <code>*warn, *.err</code> файлов из <code>.svace-dir</code>, которые содержат диагностические сообщения от Svace
* Добавлена возможность [[Help:CLI#Ограничение числа запросов|ограничения числа запросов]] на сервер с указанием параметров в переменной окружения <code>SVACER_SERVER_THROTTLE_PARAMS</code>
* Добавлен шаблон для импорта разметки из кода на Go: <code>DEFAULT_GO</code>
* Добавлена возможность [[Help:CLI#Аутентификация из файла|аутентификации из файла]]
* Исправлены проблемы безопасности
* Добавлена возможность просмотра исходного кода снимка с предупреждениями анализатора во внешней IDE собранной на базе [https://theia-ide.org/ Theia IDE]
* К команде automigrate add в CLI добавлен флаг <code>skip-exist</code>, чтобы при добавлении паттерна, который уже существует, не выдавало ошибки
* К команде upload (import с флагом upload) с указанием флага <code>quality-gate</code> теперь можно добавить флаг <code>quality-gate-verbose</code>. Если его указать, то также будет выведен результат успешных проверок quality-gate
* Улучшения в поддержке протокола LDAP

=== Release 8-0-1 ===
22.01.2024

* Исправлена работа в изолированной от сети среде. Загрузка Web UI больше не требует доступа к публичным CDN
* Добавлена поддержка функций при указании пользовательского фильтра
* Добавлено API для управления пользовательскими фильтрами. Детали и пример использования можно найти здесь: https://gitlab.ispras.ru/svacer-public/api-go-examples/-/tree/master/api-ui-settings
* Исправлено отображение Checker Severity при экспорте в SARIF. Теперь Critical -> error; Major, Normal -> warning; Minor -> note; any other -> warning

=== Release 8-0-0 ===
21.11.2023

* Множество изменений в UI. Смотрите обзор в [[Release notes 8-0-0]]
* Добавлен новый импорт и экспорт из SARIF в command line с поддержкой исходного кода в SARIF файлах и импортом описания детекторов из SARIF
* Добавлены группы проектов
* Переделана модель ролей и доступов. Добавлен CLI для управления ролями и доступами
* Добавлена возможность настройки автопереноса разметки между ветками, в том числе в разных проектах
* Импорт/экспорт снимков включает информацию о детекторах
* Исправлена работа интерфейса с Undefined детекторами (т. е. детекторами, информация о которых отсутствует в Svacer)
* Добавлено экспериментальное API по управлению детекторами и конфигурациями детекторов
* Добавлена очистка исходного кода от Svacer-specific комментариев перед экспортом разметки в код
* Добавлена возможность включения режима обязательного комментария при разметке кода. Комментарий будет сгруппирован с операцией разметки и будет иметь ссылку на нее
* Утилита миграции со старого svace-сервера больше не поддерживается. При необходимости миграции используйте утилиту из прошлых релизов Svacer
* Добавлена Swagger документация на API
* Добавлено хранение истории изменений комментариев
* Опция <code>--pathPrefix</code> поддерживает файлы в JSON формате вида: <code>[{ "prefix": "/some/path", "replace": "/test" }, ...]</code>
* При использовании операции по обновлению <code>pathPrefix</code> на сервере, данные о прежнем <code>pathPrefix</code> запоминаются в мета-информации о снимке
* Добавлена возможность переименования снимков в UI
* Sensitive информация (детали подключения к БД с данными аутентификации) убрана из UI и API
* ОС в docker-образе Svacer обновлена с Ubuntu 18 до Ubuntu 22
* Улучшена логика автоопределения портов и протоколов при соединении с сервером из Svacer CLI

=== Release 7-0-1 ===
23.05.2023

* Исправлена проблема с фильтрацией предупреждений для C# проектов

=== Release 7-0-0 ===
16.05.2023

* Убрана зависимость от PostgreSQL из .deb и .rpm пакетов, чтобы проще было ставить Svacer только как клиент
* Сделан пакет для Windows (.msi) и документация по установке и запуску на Windows
* Теперь, если при svacer import и svacer sarif не указан путь к проекту, им считается текущая директория
* Информация о разметке и блокировках теперь обновляется автоматически при изменении в другом браузере (табе) или другим пользователем
* UI для пользовательских фильтров улучшен и перенесен в правую верхнюю часть экрана
* UI для выбора проекта, ветки и снимка теперь находится на одном уровне
* Улучшен UI для режима сравнения снимков
* Добавлена возможность работать одновременно с несколькими открытыми файлами в режиме Code, это поведение можно изменить в настройках профиля пользователя
* В левой навигационной панели детекторы теперь по умолчанию группируются по серьезности, это поведение можно изменить в настройках профиля пользователя
* Профиль текущего пользователя теперь можно смотреть/редактировать только через меню в правом верхнем углу
* Добавлена возможность копирования в системном логе и журнале
* Для пользователя теперь запоминается последний контекст (проект/ветка/снимок), с которым он работал, он автоматически открывается при старте новой сессии
* Групповая разметка теперь делается единой транзакцией, в случае ошибок или отмены все изменения откатываются
* Добавлено предупреждение при использовании некорректных путей при использовании REST API с префиксом /api
* Поддержка указания паролей из файла или pipe-а при использование Svacer CLI
* Добавлена поддержка multi-tab code view для режима просмотра кода объекта сборки
* Добавлена поддержка сохранения информации об удаленных детекторах при загрузке информации о детекторах из новой версии Svace
* Исправлен импорт результатов анализа, если сборка проводилась с опцией --disable-dxr
* Исправлены проблемы при импорте и прикреплении нескольких файлов к снимку
* Исправлены ошибки с входом в систему пользователей LDAP (специальные символы в пароле, вход по атрибуту mail)
* Добавлена возможность использования резервных серверов LDAP
* Добавлена возможность автоматического назначения пользователям LDAP роли Svacer, в зависимости от принадлежности пользователя к LDAP группе
* Добавлены новые public запросы на получение маркеров/снимков/проектов с учетом заданных параметров фильтрации
* Добавлена поддержка TLS при работе сервера по протоколам HTTP и gRPC
* Добавлена возможность загрузки статистики по общему количеству предупреждений и по количеству размеченных предупреждений для проектов и веток через REST API
* Добавлена вкладка выбора проектов в расширении VSCode
* Убрана возможность использовать всплывающее окно в VScode для добавления/редактирования/удаления комментариев, установки ревью-статусов, локов и т.д.

=== Release 6-0-3 ===
25.01.2023

* RPM-пакет теперь при сборке упаковывается в gzip вместо zstd для обратной совместимости со старыми дистрибутивами
* Если short url некорректен, то Svacer теперь будет возвращать корректный http error NotFound
* Если путь к лог файлу явно не указан, то svacer.log будет создаваться во временной директории. Это решает проблемы при запуске Svacer из директорий с запретом на запись. Путь к лог файлу будет печататься в stdout
* Лог файлы не будут создаваться, когда используется опция --help
* Исправлены проблемы при миграции схемы данных, когда в PostgreSQL используется SSL подключение
* Добавлены описания детекторов из последнего релиза Svace, которые были пропущены в релизе 6-0-2
* Исправлена работа Svacer за proxy-сервером, где выставляется Header "X-Content-Type-Options nosniff"
* Добавлены кнопки для скачивания системного лога и журнала из web-интерфейса
* Поправлен ряд ошибок валидации схемы при экспорте в SARIF
* Исправлено поведение при наличии нескольких хуков в конфигурационном файле
* В информацию о маркере для хуков добавлены checker severity и reliability
* Исправлен случайный порядок URL для маркеров при использовании public API для получения URL-ов
* На главную страницу добавлена кнопка "Помощь", которая открывает документацию
* При использовании команд навигации в режиме "Browse code" текущий файл теперь корректно подсвечивается в дереве файлов
* В диалоге групповой разметки убран индикатор изменений в виде кружочка, наличие изменений можно определить по активности кнопок "Apply" и "Reset"
* Кнопка обновления в верхнем меню теперь корректно обновляет информацию на странице Settings/Project
* Различные небольшие исправления в пользовательском интерфейсе

=== Release 6-0-2 ===
16.12.2022

* Исправлена проблема в UI с сохраненными пользовательскими фильтрами

=== Release 6-0-1 ===
13.12.2022

* Добавлено описание ряда детекторов, которые есть в последнем релизе Svace 3.3.2 но были пропущены в Svacer
* Исправлено вылетание в Login Screen при удалении нотификации из панели нотификаций
* Исправлено появление белого экрана при клике на детектор, информация о котором отсутствует
* Ряд различных небольших исправлений в UI
* Промежуточное хранилище будет очищаться по умолчанию при использовании команды import

=== Release 6-0-0 ===
30.11.2022

* Добавлено копирование комментариев при копировании разметки
* Комментарии добавлены к отчету в формате csv
* Добавлена возможность вводить пароль с клавиатуры для консольных команд
* Добавлена возможность импортировать разметку из объекта сборки (из ранее загруженных данных)
* Добавлена возможность импортировать разметку сразу после загрузки на сервер (опция для команды svacer upload)
* Добавлена возможность загружать исходный код не из папки .svace-dir
* Добавлена возможность бэкапа и восстановление объектного хранилища в сервер PostgresSQL
* Добавлена возможность создания отчета по проекту в формате PDF через интерфейс командной строки и посредством REST API
* Добавлена возможность подавления предупреждений через inline комментарии в коде
* Добавлена возможность подавления предупреждений по идентификатору предупреждения через command line и REST API
* Добавлена возможность ассоциировать организацию с пользователем и реестр организаций
* Добавлена фильтрация списка комментариев по пользователю в правой панели веб-интерфейса
* Добавлен поиск пользователей по его атрибутам в панели управления пользователями
* Добавлена возможность заполнения данных профиля LDAP пользователя данными, полученными от LDAP сервера
* Добавлена возможность прикреплять файлы к снимкам при импорте результатов (данные файлы составляют часть экспортируемых данных при экспорте снимков)
* Добавлена возможность ассоциировать пользовательские атрибуты типа "строка" или массив строк со снимком при импорте данных (данные атрибуты составляют часть экспортируемых данных при экспорте снимков)
* Добавлены command line операции по получению прикрепленных файлов и пользовательских атрибутов со снимков
* Добавлена возможность группового добавления комментариев
* Добавлена возможность указания сетевого интерфейса для работы WEB и GRPC серверов
* Добавлен вывод краткой статистики по загруженному снимку при команде upload. Поддерживается текстовой и JSON форматы вывода
* Существенно расширены возможности по интеграции Visual Studio Code с сервером Svacer
* Добавлен флаг --git в команду import. При наличии такого флага, ищется ближайший git репозиторий содержащий .svace-dir и при наличии такого - используется путь к гит репозиторию для замены путей на префикс .build.
* Portable PostgreSQL больше не входит в поставку. Вместо него поставляется docker-compose.yml файл для запуска PostgreSQL в докер-контейнере
* Добавлено больше данных и информации об ошибках в вывод команды svacer import
* Изменение Public API: добавлена точка входа /api/public/login
* Операции по импорту и экспорту снимков доступны теперь обычным пользователям (не администраторам) при использовании command line интерфейса
* Операция по экспорту снимков доступна обычному пользователю из веб-интерфейса (импорт все еще требует роль администратора для веб-интерфейса)
* Операции по экспорту снимков переведены на асинхронный режим. Нотификация о готовности будет показана пользователю и доступна в панели нотификаций
* Обновлено описание детекторов в соответствии с релизом Svace 3.3.2
* Исправлена ошибка обработки корневых сертификатов при подключении к LDAP серверу по протоколу ldaps
* Исправлено ошибочное создание дубликатов локальных учетных записей LDAP пользователей (case sensitive login)
* Различные исправления в пользовательском интерфейсе с целью оптимизации производительности
* Добавлены пропущенные проверки ролей при работе с веб-интерфейсом
* Svacer больше не создает временные файлы в директории с исполняемым файлом
* Устаранены задержки при удалении веток и проектов