Svacer Wiki - User contributions [en]

Help:XSvacer:AIAssistant

2025-12-01T08:59:49Z

M.vinogradov: Remove description of old (separate) AI-assistant version. Add deployment manual

{{Note|type=warn|text='''Disclaimer'''
* Это экспериментальная Proof of Concept версия, предоставляемая для ознакомления по принципу "как есть".
* Данная функциональность не связана с [https://svace.pages.ispras.ru/svace-website/2025/02/21/ai-assistant.html AI-ассистентом из анализатора Svace]. Функционал AI-ассистента из анализатора Svace будет интегрирован в Svacer в будущих версиях сервера.}}

== Поддержка ИИ-ассистента для разметки предупреждений ==
Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.

ИИ-ассистент предназначен для разметки предупреждений статусами <code style="white-space: pre;">Confirmed</code> и <code style="white-space: pre;">False Positive</code>, которые были предсказаны моделью машинного обучения.

Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.

== Активация и запуск ИИ-ассистента ==

ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его работы необходимо:

# Запустить docker-контейнер с моделью машинного обучения
# При необходимости: развернуть PostgreSQL-сервер для хранения базы данных ИИ-ассистента
# Запустить сервис ИИ-ассистента
# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-ассистенту

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

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

=== deb/rpm ===
Если Svacer установлен из deb/rpm пакета:

1. Запустите docker-контейнер с моделью машинного обучения

docker run --rm -d --name svacerai-model -p 8000:8000 ispras/svacerai-model:latest

2. В PostgreSQL создайте отдельную БД для ИИ-сервера, запустив psql-консоль и выполнив команды:

sudo su -l postgres
psql
postgres=# create database svacerai;
postgres=# grant all privileges on database svacerai to svace;

(предполагается, что пользователь <code>svace</code> уже [[Help:Installation#deb/rpm|был создан]] для сервера Svacer)

3. В конфиг-файле ИИ-сервера <code>/etc/default/svacerai</code> укажите аргументы запуска

<pre>
# URL подключения к БД из второго шага
SVACERAI_PG_URL="postgres://svace:svace@127.0.0.1:5432/svacerai?sslmode=disable"

# адрес и порт модели из первого шага
SVACERAI_MODEL_URL="server-status:http://localhost:8000"

# интерфейс и порт, на котором будет запущен ИИ-сервер
SVACERAI_HOST="0.0.0.0:7001"

# URL сервера Svacer, который будет подключен к ИИ-серверу
SVACER_HOST="http://localhost:8080"
</pre>

4. Запустите systemd-сервис ИИ-сервера

systemctl start svacerai

5. В конфиг-файле сервера Svacer <code>/etc/default/svacer</code> включите фичу ИИ-ассистента, добавив флаг <code>--xsvacer.features aiAssistant</code> и укажите URL ИИ-сервера

<pre>
SVACER_ARGS="--pg ... --store ... --xsvacer.features aiAssistant"

# соответствует переменной SVACERAI_HOST из шага 3
XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://localhost:7001/
</pre>

6. Перезапустите сервер Svacer

systemctl restart svacer

== Дополнительная конфигурация ==
=== Подключение к серверу ИИ-ассистента ===
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code>. Изменить этот адрес можно одним из способов:

# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистента}:{порт}/</nowiki></code>
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел

<pre style="white-space: pre;">
...
xsvacer:
...
aiAssistant:
assistantHostUrl: http://{адрес ИИ-ассистента}:{порт}/
...
</pre>

==== Запуск docker-контейнера с моделью машинного обучения ====
При запуске докер-контейнера с ИИ-моделью, можно создать и примонтировать вольюмы для постоянного хранения базы данных и кэша:

docker volume create svacer-ai-cache
docker volume create svacer-ai-pgdata
docker run --rm -d --name svacerai-model -p 8000:8000 -v svacer-ai-pgdata:/var/lib/postgresql/data -v svacer-ai-cache:/root/.cache ispras/svacerai-model:latest

* Вольюм <code style="white-space: pre;">cache</code> будет содержать кэш сервиса взаимодействия с моделью машинного обучения
* Вольюм <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ PostgreSQL

=== Флаги команды запуска ИИ-ассистента ===

Глобальные флаги <code>svacerai-server help</code>

NAME:
svacerai-server - Svace AI server

USAGE:
svacerai-server [global options] command [command options] [arguments...]

COMMANDS:
run
help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:
--debug (default: false) [$SVACER_AI_DEBUG]
--log-level value Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]
--log value Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.
--config value Define path to file with config in YAML format (by default svacer-ai.cfg).
--help, -h show help

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
|-
|debug
|bool
|Отладочный режим логирования
|-
|log-level
|string
|Уровень логирования
|-
|log
|string
|Путь к файлу с логами
|-
|config
|string
|Путь к [[#Конфигурация по умолчанию|конфигурационному файлу]]
|}

Флаги запуска ИИ-ассистента <code>svacerai-server run help</code>

NAME:
svacerai-server run

USAGE:
svacerai-server run [command options] [arguments...]

OPTIONS:
--pg value Defines PostgreSQL connection URL
--host value Defines host name for the server
--svacer-host value Defines remote Svacer host
--ai-host value [ --ai-host value ] Specify the address of the service with AI models in the format <nowiki>{host id}:{http://{host address}}</nowiki>
--help, -h show help

{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Формат
|-
|style="width: 80px"|pg
|string
|Строка подключения к базе данных ИИ-ассистента
|https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS
|-
|host
|string
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент
|<code>{ip адрес}:{порт}</code>
|-
|svacer-host
|string
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент
|https://en.wikipedia.org/wiki/URL#Syntax
|-
|ai-host
|[]string
|Список адресов сервисов с моделями машинного обучения. <code>host-id</code> — идентификатор сервиса моделей в [[#Конфигурация по умолчанию|конфигурации]]
|<code><nowiki>{host id}:{url сервиса моделей}</nowiki></code>
|}

{{Note|text=При использовании [[#Конфигурация по умолчанию|конфигурации по умолчанию]], <code>{host id}</code> должен быть равен <code>server-status</code>}}

Пример:
<nowiki>svacerai-server run --pg postgres://svace:svace@127.0.0.1:5432/svacer_ai --host localhost:8095 --svacer-host http://localhost:8094 --ai-host server-status:http://localhost:7000</nowiki>

=== Конфигурация ИИ-ассистента ===

Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|db/url
|string
|Строка подключения к базе данных ИИ-ассистента
|<code>postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable</code>
|-
|http/host
|string
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент
|<code>localhost:8081</code>
|-
|http/svacerHostUrl

ai/svacerHostUrl
|string
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент
|<code><nowiki>http://localhost:8080/</nowiki></code>
|-
|http/svacerClientTlsCfg?

ai/svacerClientTlsCfg
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]
|Настройки безопасного подключения к Svacer
|<pre style="white-space: pre;">
svacerClientTlsCfg:
insecureSkipVerify: true
</pre>
|-
|ai/svacerReviewCommentTemplate
|string
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code>
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]
|-
|ai/svacerReviewTags
|[]string
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента
|<code>[AI]</code>
|-
|hosts
|map[string]object
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент
|<pre style="white-space: pre;">
{id сервиса моделей}:
{параметры подключения}
(см. описание ниже)
</pre>
|}

=== Параметры подключения сервиса модели машинного обучения ===

Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|url
|string
|Url сервиса с моделями машинного обучения
|<code><nowiki>http://localhost:7000</nowiki></code>
|-
|settings/requestBatchSize
|int
|Количество предупреждений, отправляемых для анализа моделью за раз
|<code>512</code>
|-
|settings/httpMultipartParameterName

settings/httpMultipartFileName

settings/httpMultipartContentType
|string
|Параметра multipart-запроса вызова модели
|<pre style="white-space: pre;">
httpMultipartParameterName: "file"
httpMultipartFileName: "file.csv"
httpMultipartContentType: "application/vnd.ms-excel"
</pre>
|-
|resources/modelList

resources/modelInference

resources/logs
|string
|Сопоставление названий ресурсов сервиса моделей
|<pre style="white-space: pre;">
modelList: "/models_info"

modelInference: "/use_model_for_file"

logs: "/log_file"
</pre>
|-
|defaults/dataCollector/csvSeparator
|string
|Разделитель csv-файла, который отправляется в сервис моделей
|<code>","</code>
|-
|defaults/dataCollector/additionalLineNumber
|int
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей
|<code>0</code>
|-
|defaults/dataCollector/csvColumns
|[]string
|Названия столбцов csv-файла, который отправляется в сервис моделей
|<code>[id, warnClass, code]</code>
|-
|defaults/interpretation/defaultValue

defaults/interpretation/defaultValue

defaults/interpretation/defaultValue
|string
|Названия статусов, которые присваиваются результату вызова модели
|<pre style="white-space: pre;">
defaultValue: "Undecided"

leftClassValue: "False Positive"

rightClassValue: "Confirmed"
</pre>
|}

=== Конфигурация по умолчанию ===

Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.

{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}

<pre style="white-space: pre;">
varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"
varSvacerClientTlsCfg: &svacerClientTlsCfg
insecureSkipVerify: true
db:
url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"
http:
host: "localhost:8081"
svacerHostUrl: *svacerHostUrl
svacerClientTlsCfg: *svacerClientTlsCfg
ai:
svacerHostUrl: *svacerHostUrl
svacerClientTlsCfg: *svacerClientTlsCfg
svacerReviewCommentTemplate: |+
`Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`

`AI model: {{.Pipeline.Name}}`

`Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`

svacerReviewTags:
- AI
hosts:
server-status:
url: "http://localhost:7000"
settings:
requestBatchSize: 512
httpMultipartParameterName: "file"
httpMultipartFileName: "file.csv"
httpMultipartContentType: "application/vnd.ms-excel"
resources:
modelList: "/models_info"
modelInference: "/use_model_for_file"
logs: "/log_file"
defaults:
dataCollector:
csvSeparator: ","
additionalLinesNumber: 0
csvColumns:
- "id"
- "warnClass"
- "code"
interpretation:
defaultValue: "Undecided"
leftClassValue: "False Positive"
rightClassValue: "Confirmed"
</pre>

== Описание модели xgb.joblib ИИ-ассистента ==

Модель обучена на базе 50000+ размеченных предупреждений.

Для предсказания статуса разметки нами используются:
# языковая модель codebert-base для получения эмбеддингов кода;
# метод градиентного бустинга (xgboost) для решения задачи классификации.

Changelog

2025-11-27T14:14:01Z

M.vinogradov: changelog 12-0-0 add AI assistant and new Webide deployment description

=== Release 12-0-0 ===
* API методы на fullmarkers позволяют указать фильтр с полем фильтрации по checker reliability
* В функциональность полнотекстового поиска добавлен поиск маркеров под id и инварианту.
* Промежуточное хранилище при импорте результатов командой <code>svacer import / svacer sarif2 import</code> теперь использует новый формат представления (должно снизить использование памяти при импорте)
* Сериализация JSON переведена на jsonv2 библиотеку в Go
* Импорт 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 при удалении снимков
* Добавлена возможность создания сложных пользовательских фильтров по условиям выраженным предикатом [[Afilters]]
* Проведена работа по предотвращению зависаний при исчерпывании доступных соединений с 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)|вкладку по умолчанию]] для страницы входа в систему
* Исправлена ошибка, приводящая к разрастанию базы данных
* Исправлена ошибка, связанная с невозможностью в ряде случаев использовать механизм подписок
* Форма разметки с помощью [[Help:XSvacer:AIAssistant:Deploy|ИИ-ассистента]] реализована в основном интерфейсе 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#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:XSvacer:Webide

2025-11-14T14:38:32Z

M.vinogradov: start IDE from Svacer in docker container

{{Note|text=Данная функциональность входит в набор расширений XSvacer}}

= Поддержка среды разработки Theia IDE =

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

По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].

== Активация функциональности ==

Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске Svacer.

Функциональность запуска IDE основана на управлении docker-контейнерами с IDE. Поэтому при запуске функциональности Webide также будет запущена функциональность [[Help:XSvacer:Docker|управления docker-контейнерами]].

При активации функциональности:
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов
* в пользовательском интерфейсе на вкладке "Информация о снимке" появляется кнопка "Открыть в IDE"
* устанавливается подключение к хосту docker, на котором будут запускаться контейнеры с экземплярами IDE

=== Запуск функциональности при использовании docker compose ===

В случае запуска Svacer [[Help:Installation#docker_compose|с помощью docker compose]], функциональность Webide будет активирована по умолчанию. При этом в docker-контейнер содержащий Svacer по умолчанию будет проброшен (примонтирован) unix-сокет файл <code style="white-space: pre;">/var/run/docker.sock</code>, доступ к которому будет использоваться для управления контейнерами c IDE. При запуске контейнеры с IDE будут подключаться к docker-сети <code>svacer</code>, которая будет создана при вызове <code>docker compose up</code>.

=== Запуск функциональности в Svacer с настройками по умолчанию ===

Для того, чтобы начать пользоваться функциональностью запуска IDE без изменения конфигурационных параметров Svacer, нужно выполнить следующие действия:
# Настройка доступа к docker-хосту:
## Запустить docker со настройками по умолчанию (dockerd должен слушать unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option) на том же хосте, что и Svacer;
## Проверить, что у пользователя под которым будет запускаться Svacer есть доступ к unix-сокету docker-хоста <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/engine/install/linux-postinstall
# Настроить права доступа у пользователей, которые смогут запускать IDE: требуются разрешения на проект/ветку "Просмотр маркеров" и "Экспорт разметки"
# Перезапустить Svacer с флагом <code style="white-space: pre;">--xsvacer.features webide</code>
# ''Опционально.'' Для ускорения первого запуска IDE:
## Скачать архив с docker-образом для соответствующей версии Svacer: [https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz 11+], [https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz 10+], [https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar 9+]
## Загрузить docker-образ из архива на docker-хост: <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint...</code>

После этого у пользователей с указанными правами должна появиться кнопка "Открыть в IDE" на панели с информацией о снимке.

{{Note}} IDE с исходным кодом снимков будут запускаться в новых вкладках браузера. Обычно все браузеры блокируют автоматическое открытие вкладки и показывают соответствующее предупреждение.

Например, в Firefox:

[[File:Firefox popup notification ru.png]]

В таком случае нужно дать разрешение на открытие вкладки с IDE:

[[File:Firefox popup notification expanded ru.png|x150px]]

При необходимости изменения настроек подключения к docker-хосту:
# Скопировать [[Help:XSvacer:Docker#Конфигурация_по_умолчанию|конфигурацию docker по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/docker</code>

При необходимости изменения настроек запуска IDE:
# Скопировать [[#Конфигурация_по_умолчанию|конфигурацию webide по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/webide</code>

== Принцип работы ==

Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:
# Функциональность активна: при запуске Svacer указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;
# В [[Help:XSvacer:Webide#Конфигурация|конфигурации]] функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE
# У пользователя Svacer имеются разрешения "Просмотр маркеров" и "Экспорт разметки" на проект, в котором находится снимок, для которого нужно запустить IDE

В противном случае в пользовательском интерфейсе будет отсутствовать кнопка "Открыть в IDE".

=== Запуск IDE ===

Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>

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

# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):
#** Если IDE доступна: действие не требуется. Процесс запуска завершается
#** Если IDE недоступна: продолжается процесс запуска. IDE будет перезапущена
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code>xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code>
# Исходный код снимка скачивается в "корневую папку снимка"
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sarif/filenametemplate</code>
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>. Если docker-образ отсутствует, он будет загружен на хост
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:
##* Если docker-контейнер не существует, то он будет создан и запущен
##* Если docker-контейнер существует и находится:
##** в статусе <code>running</code> — процесс запуска IDE продолжается
##** в статусе <code>created</code>, <code>exited</code> или <code>paused</code> — контейнер будет запущен
##** в других статусах — вернётся соответствующая ошибка и процесс запуска IDE прервётся
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>
#* Если за отведённое время ответ от IDE получен — процесс запуска завершается
#* Если ответ не получен — вернётся ошибка <code>ide not ready</code>

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

{{Note|type=reminder|text=Причиной возникновения ошибки "ide not ready" может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>. В этом случае рекомендуется попробовать повторно запустить IDE через короткий промежуток времени}}

Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется проверить:
# Сетевую доступность docker-хоста
# Настройки фаервола на docker-хосте
# Настройки биндинга docker-контейнера c IDE
::<code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code>
::Контейнер должен быть подключён к доступному сетевому интерфейсу

=== Использование IDE: проксирование запросов ===

После успешного запуска docker-контейнера IDE станут доступны ресурсы с префиксом <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code>

Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.

Например, если docker-контейнер c IDE <code style="white-space: pre;">theia__default</code> для снимка <code style="white-space: pre;">xxx</code> запущен и слушает порт <code style="white-space: pre;">35353</code> на хосте <code style="white-space: pre;">docker-host</code>, то будет происходить проксирование:
:<code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> ⇒ <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code>
:<code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> ⇒ <code style="white-space: pre;"><nowiki>POST http://docker-host:35353/socket.io/?...</nowiki></code>
:<code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> ⇒ <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code>

Для запуска IDE в окне браузера нужно указать адрес

:<code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code>

{{Note}} Завершающий слеш обязателен!

=== Перезапуск IDE ===

В процессе работы Svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.

Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.

Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].

Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.

Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.

=== Остановка IDE ===

Запуск производится путём вызова http-метода
DELETE /api/snapshots/{snapshot_id}/ide
с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>. В ходе обработки запроса останавливается docker-контейнер IDE.

По умолчанию установлен параметр конфигурации

xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true

Это означает, что после остановки docker-контейнер будет автоматически удалён.

Чтобы изменить это поведение, настройка
xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove

должна быть установлена в <code>false</code> на момент запуска docker-контейнера IDE. Это можно сделать, например, установив значение переменной окружения

XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false

{{Note|type=error|text=При использовании версии Svacer 9.0.0 установка <code>autoremove: false</code> вызывает ошибку запуска. Исправлено в версии [[Svacer#Релизы|9.0.1]].'''}}

При корректной остановке (например SIGTERM) Svacer автоматически остановит все запущенные docker-контейнеры IDE.

=== Подключение к IDE после некорректного завершения Svacer ===

При запуске Svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах. При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке Svacer все docker-контейнеры IDE будут остановлены.

== REST API для работы с IDE ==

{{Note|text=На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!}}

После активации функциональности становятся доступны http-ресурсы для управления IDE:

{| class="mw-collapsible mw-collapsed wikitable"
|+ style=white-space:nowrap | REST API управления IDE
|-
!Ресурс
!Описание
|-
|<pre style="white-space: pre;">
GET /xsvacer/webide/api/ide
</pre>
|Получение списка доступных для запуска IDE.
'''Ответ:'''
<pre style="white-space: pre;">
[
{
"id": "string",
"name": "string",
"order": 0
}
]
</pre>
:<code style="white-space: pre;">id</code> — идентификатор IDE
:<code style="white-space: pre;">name</code> — название IDE
:<code style="white-space: pre;">order</code> — порядковый номер IDE в списке
|-
|<pre style="white-space: pre;">
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}
</pre>
|Запрос описания экземпляра IDE, запущенного для снимка.
'''Параметры:'''
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка
:<code style="white-space: pre;">ide_id</code> — идентификатор IDE
'''Ответ:'''
<pre style="white-space: pre;">
{
"id": {
"ide_id": {
"ide_type": "string"
"config_id": "string",
},
"snapshot_id": "string"
},
"properties": {
"url": "string"
},
"start_args": {
"snapshot_id": "string",
"user": "string",
"user_id": "string"
}
}
</pre>
|-
|<pre style="white-space: pre;">
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide
</pre>
|Запуск IDE для просмотра исходных кодов снимка
'''Параметры:'''
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка
'''Запрос:'''
<pre style="white-space: pre;">
{
"ideId": "string"
}
</pre>
:<code style="white-space: pre;">ideId</code> — идентификатор IDE
'''Ответ:'''
<pre style="white-space: pre;">
{
"ideId": "string"
}
</pre>
:<code style="white-space: pre;">ideId</code> — идентификатор IDE
|-
|<pre style="white-space: pre;">
PUT /api/snapshots/{snapshot_id}/ide
</pre>
|Команда управления экземпляром IDE снимка
'''Параметры:'''
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка
'''Запрос:'''
<pre style="white-space: pre;">
{
"action": "string",
"ideId": "string"
}
</pre>
:<code style="white-space: pre;">action</code> — действие
:<code style="white-space: pre;">ideId</code> — идентификатор IDE
'''Доступные действия:'''
* <code style="white-space: pre;">update_markup</code> — обновление предупреждений и разметки (sarif-файла)
'''Ответ:''' пустой
|-
|<pre style="white-space: pre;">
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide
</pre>
|Остановка экземпляра IDE снимка
'''Параметры:'''
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка
'''Запрос:'''
<pre style="white-space: pre;">
{
"ideId": "string"
}
</pre>
:<code style="white-space: pre;">ideId</code> — идентификатор IDE
'''Ответ:''' пустой
|-
|<pre style="white-space: pre;">
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*
</pre>
|Прокси для запросов экземпляра IDE снимка
|}

=== Формат идентификатора IDE ===

<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code>

Например, для default-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code>

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

Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code>

Раздел конфигурации для управления функциональностью — <code style="white-space: pre;">xsvacer/webide</code>

Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.

xsvacer:
webide:
theia:
config1:
...
config2:
...

Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому необходимо также [[Help:XSvacer:Docker|настроить доступ к docker-хосту]] в разделе <code style="white-space: pre;">xsvacer/docker</code>, иначе функциональность WebIDE не сможет работать корректно.

В случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]].

=== Конфигурация запуска Theia IDE ===

{{Note|text=На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!}}

Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:

xsvacer:
webide:
theia:
1-46-0:
name: Theia blueprint web IDE (v1.46.0)
...

==== Базовые параметры конфигурации запуска ====

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|disabled
|bool
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE
|true (переопределяется в конфигурации default)
|-
|order
|int
|Порядковый номер в списке выбора конфигурации запуска
|0
|-
|name
|string
|Название конфигурации
|Theia blueprint web IDE (v1.46.0)
|-
|sourcesroot
|string
|Путь к папке, содержащей исходные коды снимков на машине со Svacer
|${USER_CACHE_DIR}/svacer-snapshot-sources
|-
|dockerhostsourcesroot
|string
|Путь к папке, содержащей исходные коды снимков на хосте docker. Нужен при использовании удалённого docker-хоста, т. к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code>
|
|-
|dockerhostpathseparator
|string
|Разделитель пути на хосте docker. По умолчанию <code style="white-space: pre;">"/"</code>
|
|-
|sariffiletemplate
|golang template string
|{{Note|text=В версии 10.0.0 заменён на [[Help:XSvacer:Webide#Параметры_экспорта_sarif-файла_с_разметкой_предупреждений|sarif]]}}
Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]
|<nowiki>"{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"</nowiki>
|}

==== Параметры экспорта sarif-файла с разметкой предупреждений ====

Данные параметры используются для настройки экспорта sarif-файлов с разметкой предупреждений, выполненной в Svacer.

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|sarif
|map
|Настройки экспорта sarif-файла
|
|-
|sarif/filenametemplate
|golang template string
|Шаблон для формирования названия sarif-файла. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]
|<nowiki>"warnings.sarif"</nowiki>
|-
|sarif/commenttemplate
|golang template string
|{{Note|text=Удалён в версии 11.0.0}}
Шаблон для формирования элемента списка комментариев предупреждения при экспорте в sarif-файл. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|Comment]]
|<nowiki>"{{if trim .Text}}`[{{.CreateTs.Local.Format \"02.01.2006 15:04\"}}] {{.CreatedBy}}:`\n\n{{trim .Text}}{{end}}"</nowiki>
|}

==== Параметры менеджера запуска IDE ====

Конфигурация менеджера запуска IDE. На данный момент доступен только стандартный менеджер (<code style="white-space: pre;">type: default</code>)

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|manager
|map
|Конфигурация менеджера запуска IDE
|
|-
|manager/type
|enum: default
|Тип менеджера запуска IDE
|default
|}

==== Параметры запуска docker-контейнеров с IDE ====

Данные параметры используются для настройки запуска docker-контейнеров с IDE

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|docker/
|map
|Настройки создания docker-контейнера с IDE
|
|-
|docker/hostid
|string
|Идентификатор хоста docker, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте
|default
|-
|docker/containernametemplate
|golang template string
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]
|<nowiki>"theia-1-46-{{.StartArgs.SnapshotID}}"</nowiki>
|-
|docker/containerconfiglabels
|[]map
|Список меток docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code>
|
- "com.docker.compose.project": svacer
|-
|docker/image/
|map
|Параметры docker-образа из которого будет запущен контейнер
|
|-
|docker/image/name
|string
|Название образа
|theia-blueprint
|-
|docker/image/tag
|string
|Тег образа
|Svacer 11+: 1.46.0.sarif.clang.11.0.0.1
Svacer 10+: 1.46.0.sarif.clang.10.0.0

Svacer 9+: 1.46.0.sarif.clang
|-
|docker/image/sourcetype
|enum: repository/file
|Тип источника для загрузки образа в docker-хост
* repository — будет вызван docker pull образа <code>{image/name}:{image/tag}</code>
* file — будет вызван docker load с URL <code>image/sourcefileurl</code>
|file
|-
|docker/image/sourcefileurl
|url
|URL откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code>
URL может содержать:
* путь к локальному файлу: схема <code>file://</code>
* http/https-адрес: схема <code>http://</code> или <code>https://</code>
|Svacer 11+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz
Svacer 10+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz

Svacer 9+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar
|-
|docker/container/
|map
|Свойства docker-контейнера
|
|-
|docker/container/config
|map
|Конфигурация контейнера. Соответствует структуре Config https://github.com/moby/moby/blob/v28.5.1/api/types/container/config.go#L44
|
|-
|docker/container/config/env
|[]string
|Список переменных среды, которые будут установлены в контейнере
|
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki>
|-
|docker/container/hostconfig/
|map
|Параметры хостинга контейнера. Соответствует структуре HostConfig https://github.com/moby/moby/blob/v28.5.1/api/types/container/hostconfig.go#L429
|
|-
|docker/container/hostconfig/autoremove
|bool
|
|true
|-
|docker/container/hostconfig/portbindings/
|map
|
|
"3000/tcp":
:- hostport: 0
|-
|docker/container/networkconfig/
|map
|Сетевые настройки контейнера. Соответствуют структуре NetworkingConfig https://github.com/moby/moby/blob/v28.5.1/api/types/network/network.go#L140
|
|-
|docker/containerhostconfigmounts/
|map
|{{Note|text=Добавлен в версии 12.0.0}}
Именованные настройки точек монтирования контейнера. Соответствуют структуре [[Help:XSvacer:Webide#Структуры_применяемые_в_конфигурации_функциональности|MountMap]]
|
|-
|docker/containernetworkingconfigendpoints/
|map
|{{Note|text=Добавлен в версии 12.0.0}}
Именованные настройки подключённых сетевых интерфейсов контейнера контейнера. Соответствуют структуре [[Help:XSvacer:Webide#Структуры_применяемые_в_конфигурации_функциональности|EndpointsMap]]
|
|}

==== Параметры проверки доступности healthcheck ====

Данные параметры используются для проверки доступности IDE после запуска docker-контейнера

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|healthcheck
|map
|Параметры проверки доступности IDE
|
|-
|healthcheck/starttoreadyretries
|int
|Количества попыток проверки до ошибки доступности
|10
|-
|healthcheck/starttoreadyperiod
|golang duration string
|Интервал проверки
|200ms
|}

==== Структуры передаваемые в поля с golang-шаблонами строк ====

sarifFileContext {
Time time.Time
Context: {
ProjectID *string
BranchID *string
SnapshotID *string
MarkerID *string

ProjectName *string
BranchName *string
SnapshotName *string
MarkerName *string
CreatedBy null.String
CreatedByID null.String
CreateTs null.Time
}
}

TheiaDockerContainerStartContext {
IdeID: {
IdeType string
ConfigID string
},
StartArgs: {
SnapshotID string
UserID string
User string
},
Context: {
ProjectID *string
BranchID *string
SnapshotID *string
MarkerID *string

ProjectName *string
BranchName *string
SnapshotName *string
MarkerName *string
CreatedBy null.String
CreatedByID null.String
CreateTs null.Time
}
}

Comment {
ID string
Text string
Ref string
CreatedBy string
CreatedByID string
CreateTs time.Time
UpdateTs *time.Time
UpdatedBy string
UpdatedByID string
}

==== Структуры применяемые в конфигурации функциональности ====

type Mount struct {
Disabled bool
mount.Mount https://github.com/moby/moby/blob/v28.5.1/api/types/mount/mount.go#L27
}

type MountMap map[string]Mount

type EndpointSettings struct {
Name string
Disabled bool
*network.EndpointSettings https://github.com/moby/moby/blob/v28.5.1/api/types/network/endpoint.go#L10
}

type EndpointsMap map[string]*EndpointSettings

=== Конфигурация по умолчанию ===

Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code>

<pre style="white-space: pre;">
xsvacer:
webide:
theia:
1-46-0: &1-46-0
disabled: true
order: 0
name: Theia blueprint web IDE (v1.46.0)
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources
sarif:
filenametemplate: "warnings.sarif"
manager:
type: default
docker:
hostid: default # идентификатор используемого docker-хоста
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"
image:
name: theia-blueprint
tag: 1.46.0.sarif.clang.11.0.0.1
sourcetype: file
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz
containerconfiglabels:
- "com.docker.compose.project": svacer
containerhostconfigmounts:
"projectrootbind":
disabled: false
mount:
type: bind
target: "/home/project"
readonly: true
"projectrootvolume":
disabled: true
mount:
type: volume
source: svacer-snapshot-sources
target: "/home/project"
readonly: true
containernetworkingconfigendpoints:
"svacer":
name: svacer
disabled: true
container:
config:
env:
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki>
hostconfig:
autoremove: true
portbindings:
"3000/tcp":
# - hostport: 0 # not required since version 12.0.0
networkconfig:
healthcheck:
starttoreadyretries: 10
starttoreadyperiod: 200ms
default:
<<: *1-46-0
order: 0
disabled: false
</pre>

По умолчанию используется docker-хост с идентификатором <code>default</code>. Согласно настройке этого хоста, по умолчанию предполагается взаимодействие с докером через unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code>. Соответственно пользователь, под которым запускается Svacer, должен иметь доступ к этому сокету (https://docs.docker.com/engine/install/linux-postinstall/).

{{Note|text=При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы}}

=== Изменение конфигурационных параметров с помощью переменных окружения ===

Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения

XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code>

Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске Svacer:

XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local

== Очистка системы: удаление артефактов функциональности ==

В процессе использования функциональности IDE создаются следующие артефакты:
# Исходные файлы снимков скачиваются в корневые папки, заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code>
# Артефакты docker:
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code>
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code>
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code>
#* наборы меток doker-контейнеров будут содержать:
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code>
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code>
#*: метки с названиями <code style="white-space: pre;">svacer.service.id</code>, <code style="white-space: pre;">svacer.service.type</code>, <code style="white-space: pre;">svacer.theia.start_args</code>
# При использовании rootless-хоста docker будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста|настройкам]]

== Рекомендации ==

=== Предварительная загрузка docker-образа с IDE ===

По умолчанию параметр

xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl

Содержит значение

Svacer 11+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz
Svacer 10+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz
Svacer 9+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar

По этому адресу находится архив с docker-образом для Theia IDE.

Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т. к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго.

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

# Скачать файл архива
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint...</code>

== Информация о docker-образе Theia IDE ==

Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0 1.46.0].

При этом была изменена компоновка расширений Theia. Результат выполнения <code>git diff</code>:

<pre style="white-space: pre;">
diff --git a/browser.Dockerfile b/browser.Dockerfile
index efe591e..a4ebb6a 100644
--- a/browser.Dockerfile
+++ b/browser.Dockerfile
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \
RUN apt-get update && apt-get install -y wget apt-transport-https && \
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \
echo "deb [signed-by=/usr/share/keyrings/adoptium.asc] https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | tee /etc/apt/sources.list.d/adoptium.list && \
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \
apt-get purge -y wget && \
apt-get clean

diff --git a/package.json b/package.json
index 9044595..9d0dcc8 100644
--- a/package.json
+++ b/package.json
@@ -54,10 +54,8 @@
"theiaPluginsDir": "plugins",
"theiaPlugins": {
"eclipse-theia.builtin-extension-pack": "https://open-vsx.org/api/eclipse-theia/builtin-extension-pack/1.83.1/file/eclipse-theia.builtin-extension-pack-1.83.1.vsix",
- "ms-vscode.js-debug": "https://open-vsx.org/api/ms-vscode/js-debug/1.83.1/file/ms-vscode.js-debug-1.83.1.vsix",
- "ms-vscode.js-debug-companion": "https://open-vsx.org/api/ms-vscode/js-debug-companion/1.1.2/file/ms-vscode.js-debug-companion-1.1.2.vsix",
- "vscjava.vscode-java-pack": "https://open-vsx.org/api/vscjava/vscode-java-pack/0.25.11/file/vscjava.vscode-java-pack-0.25.11.vsix",
- "vscjava.vscode-java-dependency": "https://open-vsx.org/api/vscjava/vscode-java-dependency/0.21.2/file/vscjava.vscode-java-dependency-0.21.2.vsix"
+ "llvm-vs-code-extensions.vscode-clangd": "https://open-vsx.org/api/llvm-vs-code-extensions/vscode-clangd/0.1.26/file/llvm-vs-code-extensions.vscode-clangd-0.1.26.vsix",
+ "ms-sarifvscode.sarif-viewer": "https://open-vsx.org/api/MS-SarifVSCode/sarif-viewer/3.4.4/file/MS-SarifVSCode.sarif-viewer-3.4.4.vsix"
},
"theiaPluginsExcludeIds": [
"ms-vscode.js-debug-companion",
</pre>

Команда построения docker-образа:
docker build -t theia-blueprint:1.46.0.sarif.clang... -f browser.Dockerfile .

Команда экспорта docker-образа:
docker image save theia-blueprint:1.46.0.sarif.clang... | gzip > /path/to/tar/theia-blueprint.1.46.0.sarif.clang....tar.gz

== Известные проблемы ==

=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===

Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.

В Theia IDE для открытия webview применяется [https://developer.mozilla.org/en_US/docs/Web/API/Service_Worker_API Service Worker API]. В целях обеспечения безопасности применение Service Worker API [https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#setting_up_to_play_with_service_workers требует], чтобы доступ к web-приложению осуществлялся по HTTPS, либо приложение размещалось на localhost.

Поэтому для решения данной проблемы Svacer должен открываться по HTTPS или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code>

Help:XSvacer:AIAssistant:Deploy

2025-06-23T11:46:25Z

M.vinogradov: --ai-host description improvement

== Активация и запуск функциональности ==

ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:

# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-ассистенту;
# Развернуть и запустить сервис ИИ-ассистента;

=== Активация функциональности <code style="white-space: pre;">xsvacer</code> при запуске Svacer ===

Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features aiAssistant</code> при запуске Svacer.

==== Настройка доступа к ИИ-ассистенту в Svacer ====

По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code>

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

# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистента}:{порт}/</nowiki></code>
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел

<pre style="white-space: pre;">
...
xsvacer:
...
aiAssistant:
assistantHostUrl: http://{адрес ИИ-ассистента}:{порт}/
...
</pre>

==== Настройка значения флага <code>--public-url</code> ====

В связи с тем, что ИИ-ассистент использует REST API Svacer, необходимо добавить url ИИ-ассистента в список публичных url Svacer. Это можно сделать, добавив при запуске Svacer флаг:

--public-url {url ИИ-ассистента}

Пример:

<nowiki>--xsvacer.features aiAssistant --public-url https://svacer-ai-demo.ispras.ru</nowiki>

{{Note|text=Данная настройка связана с функциональностью генерации коротких ссылок}}

=== Развёртывание и запуск ИИ-ассистента ===

При развёртывании ИИ-ассистента необходимо выполнить следующие действия:

# Запустить docker-контейнер с моделью машинного обучения;
# При необходимости: развернуть postresql-сервер для хранения базы данных ИИ-ассистента;
# Запустить сервис ИИ-ассистента.

==== Запуск docker-контейнера с моделью машинного обучения ====

Docker-образ контейнера с моделью можно скачать по ссылке: https://svacer.ispras.ru/docker/images/svacer-ai-model-host.1.0.0.tar.gz (3.3GB)

Далее docker-образ необходимо загрузить на docker-хост с помощью команды

docker image load -i /path/to/svacer-ai-model-host.1.0.0.tar.gz

После этого docker-контейнер может быть запущен следующей командой

docker volume create svacer-ai-cache
docker volume create svacer-ai-pgdata
docker run -d --name svacer-ai-model-host -p 7000:8000 -v svacer-ai-pgdata:/var/lib/postgresql/data -v svacer-ai-cache:/root/.cache svacer-ai-model-host:1.0.0

Том <code style="white-space: pre;">cache</code> будет содержать кэш сервиса взаимодействия с моделью машинного обучения.

Том <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ postgres'а.

Порт <code>7000</code> будет использоваться по умолчанию, если не были изменены [[#Параметры подключения сервиса модели машинного обучения|параметры подключения сервиса машинного обучения]]

==== Запуск ИИ-ассистента ====

Исполняемый файл ИИ-ассистента можно скачать по ссылке: https://svacer.ispras.ru/releases/svacer-ai/svacer-ai-1-0-0-linux.tar.gz (53MB)

После этого ИИ-ассистент может быть запущен командой <code>svacerai-server run</code>

===== Флаги команды запуска ИИ-ассистента =====

Глобальные флаги <code>svacerai-server help</code>

NAME:
svacerai-server - Svace AI server

USAGE:
svacerai-server [global options] command [command options] [arguments...]

COMMANDS:
run
help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:
--debug (default: false) [$SVACER_AI_DEBUG]
--log-level value Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]
--log value Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.
--config value Define path to file with config in YAML format (by default svacer-ai.cfg).
--help, -h show help

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
|-
|debug
|bool
|Отладочный режим логирования
|-
|log-level
|string
|Уровень логирования
|-
|log
|string
|Путь к файлу с логами
|-
|config
|string
|Путь к [[#Конфигурация по умолчанию|конфигурационному файлу]]
|}

Флаги запуска ИИ-ассистента <code>svacerai-server run help</code>

NAME:
svacerai-server run

USAGE:
svacerai-server run [command options] [arguments...]

OPTIONS:
--pg value Defines PostgreSQL connection URL
--host value Defines host name for the server
--svacer-host value Defines remote Svacer host
--ai-host value [ --ai-host value ] Specify the address of the service with AI models in the format <nowiki>{host id}:{http://{host address}}</nowiki>
--help, -h show help

{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Формат
|-
|style="width: 80px"|pg
|string
|Строка подключения к базе данных ИИ-ассистента
|https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS
|-
|host
|string
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент
|<code>{ip адрес}:{порт}</code>
|-
|svacer-host
|string
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент
|https://en.wikipedia.org/wiki/URL#Syntax
|-
|ai-host
|[]string
|Список адресов сервисов с моделями машинного обучения. <code>host-id</code> - идентификатор сервиса моделей в [[#Конфигурация по умолчанию|конфигурации]]
|<code><nowiki>{host id}:{url сервиса моделей}</nowiki></code>
|}

{{Note|text=При использовании [[#Конфигурация по умолчанию|конфигурации по умолчанию]], <code>{host id}</code> должен быть равен <code>server-status</code>}}

Пример:
<nowiki>svacerai-server run --pg postgres://svace:svace@127.0.0.1:5432/svacer_ai --host localhost:8095 --svacer-host http://localhost:8094 --ai-host server-status:http://localhost:7000</nowiki>

=== Конфигурация ИИ-ассистента ===

Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|db/url
|string
|Строка подключения к базе данных ИИ-ассистента
|<code>postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable</code>
|-
|http/host
|string
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент
|<code>localhost:8081</code>
|-
|http/svacerHostUrl

ai/svacerHostUrl
|string
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент
|<code><nowiki>http://localhost:8080/</nowiki></code>
|-
|http/svacerClientTlsCfg?

ai/svacerClientTlsCfg
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]
|Настройки безопасного подключения к Svacer
|<pre style="white-space: pre;">
svacerClientTlsCfg:
insecureSkipVerify: true
</pre>
|-
|ai/svacerReviewCommentTemplate
|string
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code>
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]
|-
|ai/svacerReviewTags
|[]string
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента
|<code>[AI]</code>
|-
|hosts
|map[string]object
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент
|<pre style="white-space: pre;">
{id сервиса моделей}:
{параметры подключения}
(см. описание ниже)
</pre>
|}

==== Параметры подключения сервиса модели машинного обучения ====

Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|url
|string
|Url сервиса с моделями машинного обучения
|<code><nowiki>http://localhost:7000</nowiki></code>
|-
|settings/requestBatchSize
|int
|Количество предупреждений, отправляемых для анализа моделью за раз
|<code>512</code>
|-
|settings/httpMultipartParameterName

settings/httpMultipartFileName

settings/httpMultipartContentType
|string
|Параметра multipart-запроса вызова модели
|<pre style="white-space: pre;">
httpMultipartParameterName: "file"
httpMultipartFileName: "file.csv"
httpMultipartContentType: "application/vnd.ms-excel"
</pre>
|-
|resources/modelList

resources/modelInference

resources/logs
|string
|Сопоставление названий ресурсов сервиса моделей
|<pre style="white-space: pre;">
modelList: "/models_info"

modelInference: "/use_model_for_file"

logs: "/log_file"
</pre>
|-
|defaults/dataCollector/csvSeparator
|string
|Разделитель csv-файла, который отправляется в сервис моделей
|<code>","</code>
|-
|defaults/dataCollector/additionalLineNumber
|int
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей
|<code>0</code>
|-
|defaults/dataCollector/csvColumns
|[]string
|Названия столбцов csv-файла, который отправляется в сервис моделей
|<code>[id, warnClass, code]</code>
|-
|defaults/interpretation/defaultValue

defaults/interpretation/defaultValue

defaults/interpretation/defaultValue
|string
|Названия статусов, которые присваиваются результату вызова модели
|<pre style="white-space: pre;">
defaultValue: "Undecided"

leftClassValue: "False Positive"

rightClassValue: "Confirmed"
</pre>
|}

=== Конфигурация по умолчанию ===

Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.

{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}

<pre style="white-space: pre;">
varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"
varSvacerClientTlsCfg: &svacerClientTlsCfg
insecureSkipVerify: true
db:
url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"
http:
host: "localhost:8081"
svacerHostUrl: *svacerHostUrl
svacerClientTlsCfg: *svacerClientTlsCfg
ai:
svacerHostUrl: *svacerHostUrl
svacerClientTlsCfg: *svacerClientTlsCfg
svacerReviewCommentTemplate: |+
`Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`

`AI model: {{.Pipeline.Name}}`

`Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`

svacerReviewTags:
- AI
hosts:
server-status:
url: "http://localhost:7000"
settings:
requestBatchSize: 512
httpMultipartParameterName: "file"
httpMultipartFileName: "file.csv"
httpMultipartContentType: "application/vnd.ms-excel"
resources:
modelList: "/models_info"
modelInference: "/use_model_for_file"
logs: "/log_file"
defaults:
dataCollector:
csvSeparator: ","
additionalLinesNumber: 0
csvColumns:
- "id"
- "warnClass"
- "code"
interpretation:
defaultValue: "Undecided"
leftClassValue: "False Positive"
rightClassValue: "Confirmed"
</pre>

Help:XSvacer

2025-06-04T12:42:24Z

M.vinogradov: Add AI assistant link

= XSvacer — расширение функциональности Svacer =
{{Note|text=На данный момент расширенные функции находятся на стадии внедрения. В последующих релизах возможно изменение форматов конфигурации и API взаимодействия с указанными функциями}}

Начиная с релиза [[Changelog#Release_9-0-0|9.0.0]] в Svacer появились расширенные функции, которые могут быть активированы по требованию. По умолчанию данные функции неактивны.

Доступные функции:
* [[Help:XSvacer:Webide|Webide]] — среда разработки на базе [https://theia-ide.org/ Theia IDE], с помощью которой можно просматривать исходный код снимка, предупреждения анализатора и разметку.
* [[Help:XSvacer:AIAssistant|AIAssistant]] — ИИ-ассистент, позволяющий использовать модель машинного обучения для помощи при разметке предупреждений.

== Активация функций ==

Активировать функции можно, указав флаг <code>--xsvacer.features feature_name</code> при запуске Svacer. Флаг можно указать несколько раз, чтобы активировать несколько функций.

Также список активных функций можно настроить в конфигурационном yaml-файле <code>svacer.cfg</code> в разделе <code>xsvacer.features</code>.
Значением данного ключа является список строк с названиями активируемых функций:
...
xsvacer:
features:
- webide
- aiAssistant
...

При установке флага <code>--xsvacer.features</code> список функций, указанный в конфигурационном файле <code>svacer.cfg</code>, будет проигнорирован.

Help:XSvacer:AIAssistant

2025-06-04T05:48:16Z

M.vinogradov: AI-model short description

2025-03-11T08:24:08Z

M.vinogradov:

File:Comp-svacer-in-container-webide-hosting.png

2025-03-11T08:22:06Z

M.vinogradov: M.vinogradov uploaded a new version of File:Comp-svacer-in-container-webide-hosting.png

Диаграмма развёртывания компонентов функциональности запуска IDE если Svacer запущен в docker-контейнере

File:Comp-svacer-webide-default-hosting.png

2025-03-11T08:21:46Z

M.vinogradov: M.vinogradov uploaded a new version of File:Comp-svacer-webide-default-hosting.png

Диаграмма стандартного развёртывания компонентов функциональности запуска IDE

File:Comp-svacer-in-container-webide-hosting.png

2025-03-11T08:15:30Z

M.vinogradov:

Диаграмма развёртывания компонентов функциональности запуска IDE если Svacer запущен в docker-контейнере

File:Comp-svacer-webide-default-hosting.png

2025-03-11T08:10:50Z

M.vinogradov:

Диаграмма стандартного развёртывания компонентов функциональности запуска IDE

Help:XSvacer:Webide:SvacerAsDockerContainer

2025-03-11T07:16:53Z

M.vinogradov:

2024-06-05T12:58:42Z

M.vinogradov:

Help:XSvacer:Webide

2024-06-05T10:02:57Z

M.vinogradov:

Help:XSvacer:Docker

2024-06-05T07:06:44Z

M.vinogradov:

= Управление docker-контейнерами =
'''Примечание:''' данная функциональность входит в набор расширений XSvacer.

Данная функциональность предназначена для управления docker-контейнерами содержащими компоненты XSvacer.

Управление docker-контейнерами осуществляется с помощью взаимодействия с docker-хостом с использованием [https://docs.docker.com/engine/api/latest/ REST API].

Возможны два сценария использования docker'а:
# Подключение к существующему ("внешнему") docker-хосту;
# Запуск управляемого svacer'ом [https://docs.docker.com/go/rootless/ rootless-хоста].

== Активация функциональности ==
Для активации функциональности необходимо указать флаг <code>--xsvacer.features docker</code> при запуске svacer'а.

'''Примечание:''' на базе данной функциональности осуществляется запуск компонентов других расширений XSvacer. В таком случае её не обязательно запускать явно: она будет запущена, если будет запущена зависимая функциональность.

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

Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code>.

Раздел конфигурации для управления функциональностью - <code>xsvacer/docker</code>.

Раздел содержит перечисление настроек подключаемых хостов docker'а <code>xsvacer/docker/hosts</code>, на которые в дальнейшем будут ссылаться зависимые функциональности. Каждое поле/свойство в <code>xsvacer/docker/hosts/...</code> является идентификатором подключения и содержит его конфигурацию.

xsvacer:
docker:
hosts:
dockerhost1:
type: ...
host: ...
disabled: false
...
dockerhost2:
...

dependentFeature1:
...
docker:
hostid: dockerhost1
...
dependentFeature2:
...
docker:
hostid: dockerhost2
...

'''Примечание:''' в случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code>xsvacer/docker</code>, будет использоваться конфигурация по умолчанию (см. ниже)

=== Общие параметры docker-хостов ===
{| class="wikitable"
|+
!Название
!Тип данных
!Описание
|-
|<code>type</code>
|enum: <code>external</code>, <code>managed</code>, <code>remote</code>
|Тип подключаемого docker-хоста:

* <code>external</code> - "внешний" docker-хост
* <code>managed</code> - "управляемый" rootless-хост
* <code>remote</code> - аналогичен <code>external</code>, но <code>host</code> должен быть задан
|-
|<code>hostd</code>
|url
|Строка содержащая url docker-хоста
|-
|<code>disabled</code>
|bool
|Конфигурация хоста неактивна
Неактивная конфигурация не может использоваться в других функциональностях
|}

=== Использование существующего ("внешнего") docker-хоста ===
Данный способ взаимодействия предполагает подключение к существующему хосту docker'а.

Доступные варианты подключения:

# К локальному хосту через unix-сокет;
# К удалённому хосту по ssh;
# К удалённому хосту по http;
# К к удалённому хосту по https.

Для использования "внешнего" хоста docker'а в конфигурационном файле нужно указать <code>type: external</code>, а также задать адрес хоста, соответствующий типу подключения:
docker:
hosts:
default:
type: external
host: "unix:///path/to/docker.sock"
remote1:
type: external
host: "<nowiki>ssh://docker-user@docker-host</nowiki>"
remote2:
type: external
host: "<nowiki>http://docker-host-ip-address:2375</nowiki>"
remote3:
type: external
host: "<nowiki>https://docker-host-ip-address:2376</nowiki>"
clienttls: ...
Если параметр <code>host</code> не задан, то по умолчанию будет использоваться unix-сокет.

==== Подключение к локальному хосту через unix-сокет ====
При обычном запуске демона <code>dockerd</code>, взаимодействие с хостом осуществляется с помощью unix-сокета <code>unix:///var/run/docker.sock</code>.

Доступ к сокету может получить либо пользователь с правами <code>root</code>, либо обычный пользователь, входящий в группу <code>docker</code> (https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option).

Пользователь, под которым запускается svacer, должен иметь права доступа к указанному unix-сокету docker'а (https://docs.docker.com/engine/install/linux-postinstall/).
'''Внимание!''' При отсутствии прав доступа к unix-сокету у пользователя, под которым запускается svacer, использование данной функциональности зависимыми функциональностями будет приводить к ошибке.
В таком случае можно воспользоваться rootless-хостом (см. ниже).

Если для взаимодействия с хостом docker'а используется дефолтный unix-сокет <code>unix:///var/run/docker.sock</code>, то в конфигурации поле <code>host</code> можно не указывать:
docker:
hosts:
default:
type: external

==== Подключение к удалённому хосту по ssh ====

Чтобы подключиться к удалённому хосту docker'а по ssh, необходимо в поле <code>host</code> указать схему <code>ssh://</code>, реквизиты пользователя и название/адрес docker-хоста:

docker:
hosts:
default:
type: external
host: "<nowiki>ssh://docker-user@docker-host</nowiki>"

Указанный пользователь должен иметь возможность подключения по ssh к указанному хосту, а также иметь права доступа к unix-сокету docker'а на удалённом хосте (https://docs.docker.com/engine/security/protect-access/#use-ssh-to-protect-the-docker-daemon-socket)

==== Подключение к удалённому хосту по http ====

Чтобы подключиться к удалённому хосту docker'а по http, необходимо в поле <code>host</code> указать схему <code>http://</code> и адрес docker-хоста:
docker:
hosts:
default:
type: external
host: "<nowiki>http://docker-host-ip-address:port</nowiki>"

'''Внимание!''' Данный тип подключения является *небезопасным*, т.к. при использовании API docker'а не производится шифрование сетевого трафика и аутентификация клиента при доступе к docker'у. Чтобы создать безопасное сетевое соединение необходимо использовать подключение по https (tls) (см. ниже)

==== Подключение к удалённому хосту по https (tls) ====

Docker-хост может предоставлять доступ по https (https://docs.docker.com/engine/security/protect-access/#use-tls-https-to-protect-the-docker-daemon-socket).

В таком случае для доступа к API необходимо иметь сертификат удостоверяющего центра, клиентский ключ и сертификат.

В конфигурационном файле пути к ключам указываются в поле <code>xsvacer/docker/{docker-host-id}/clienttls</code>:
docker:
hosts:
default:
type: external
host: "<nowiki>https://docker-host-ip-address:2376</nowiki>"
clienttls:
ca: "/path/to/ca.pem"
cert: "/path/to/cert.pem"
key: "/path/to/key.pem"

===== Специфичные настройки для подключения к https хосту =====

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
|-
|clienttls/
|map
|Настройки TLS
|-
|clienttls/ca
|url
|Путь к файлу сертификата удостоверяющего центра
|-
|clienttls/cert
|url
|Путь к клиентскому сертификату
|-
|clienttls/key
|url
|Путь к клиентскому ключу
|}

==== Памятка при использовании подключения к удалённым хостам ====

NOTE: при использовании подключения к удалённому хосту docker'а, при настройке биндингов создаваемых контейнеров необходимо указывать ip-адрес сетевого интерфейса хоста, т.к. при привязке контейнера к 0.0.0.0 на машине хоста, контейнеры будут недоступны снаружи.

=== Запуск "управляемого" rootless-хоста ===

При отсутствии доступного docker-хоста, либо если не хочется его загромождать контейнерами svacer'а, предусмотрена возможность запуска "управляемого" rootless-хоста, не требующего настройки дополнительных прав для пользователя, под которым запускается svacer (https://docs.docker.com/engine/security/rootless/).

Управление (запуск и остановка) rootless-хостом будет осуществлять svacer.

'''Внимание!''' Доступно только для linux'а.

Для использования данного rootless-хоста в конфигурационном файле для хоста нужно указать <code>type: managed</code>.
docker:
hosts:
local:
type: managed
...

==== Специфичные настройки для rootless-хоста ====

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
|-
|managed/
|map
|параметры запуска rootless-хоста
|-
|managed/executable
|string
|исполняемый файл. Должен быть доступен в $PATH или содержать абсолютный путь
''формат'': имя исполняемого фала, доступного через переменную <code>$PATH</code>

''или'': абсолютный путь до исполняемого файла
|-
|managed/env
|[]string
|список переменных окружения для процесса rootless-хоста
формат: <code>"НАЗВАНИЕ_ПЕРЕМЕННОЙ=значение переменной"</code>
|-
|managed/args
|[]string
|список аргументов запуска rootless-хоста
''формат'': <code>"--название-аргумента=значение-аргумента"</code>

''или'': <code>"--название-аргумента", "значение-аргумента"</code>

''или'': <code>"--название-флага"</code>
|-
|managed/loglevel
|string
|уровень логирования, на котором будут записываться stdout и stderr процесса rootless-хоста
|-
|managed/logprefix
|string
|префикс в логе, которым будут помечаться записи из stdout и stderr процесса rootless-хоста
|-
|managed/healthcheck
|map
|параметры проверки доступности rootless-хоста
|-
|managed/healthcheck/interval
|golang duration string
|интервал проверки
|-
|managed/healthcheck/retries
|int
|количество попыток проверки до ошибки доступности
|}

В значениях <code>managed/env</code> и <code>managed/args</code> можно использовать имена переменных окружения в формате <code>${НАЗВАНИЕ_ПЕРЕМЕННОЙ}</code>

==== Рекомендуемая конфигурация rootless-хоста ====

При запуске <code>dockerd-rootless.sh</code> без параметров папки с артефактами docker'а создаются во вложенных папках внутри <code>/run/user/$UID/</code>.
Для лучшей локализации артефактов svacer'а рекомендуется использовать следующие настройки для rootless-хоста:
docker:
hosts:
local:
type: managed
host: "unix://${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.sock"

managed:
executable: "dockerd-rootless.sh"
env:
- "DOCKERD_ROOTLESS_ROOTLESSKIT_STATE_DIR=${USER_CACHE_DIR}/svacer-docker-host/state-dir/"
args:
- "--data-root=${USER_CACHE_DIR}/svacer-docker-host/data-root/"
- "--exec-root=${USER_CACHE_DIR}/svacer-docker-host/exec-root/"
- "--pidfile=${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.pid"
logLevel: info
logPrefix: "DOCKER HOST: "
healthCheck:
interval: 1s
retries: 10

Здесь вместо <code>${USER_CACHE_DIR}</code> будет подставлен путь <code>$HOME/.cache</code> на unix-подобных системах или <code>%LocalAppData%</code> на windows.

При таких настройках все артефакты хоста docker'а будут храниться внутри папки <code>${USER_CACHE_DIR}/svacer-docker-host</code>.

=== Использование "неуправляемого" rootless-хоста ===

В случае необходимости иметь возможность управления временем жизни rootless-хоста без участия svacer'а, его можно запустить отдельно от svacer'а. Например командой:
DOCKERD_ROOTLESS_ROOTLESSKIT_STATE_DIR=/home/$USER/.cache/svacer-docker-host/state-dir/ dockerd-rootless.sh --host unix:///home/$USER/.cache/svacer-docker-host/svacer-docker.sock --data-root=/home/$USER/.cache/svacer-docker-host/data-root/ --exec-root=/home/$USER/.cache/svacer-docker-host/exec-root/ --pidfile=/home/$USER/.cache/svacer-docker-host/svacer-docker.pid

В таком случае подключиться к данному хосту можно как к "внешнему" (<code>type: external</code>) с указанием адреса unix-сокета. Например:
docker:
hosts:
unmanaged:
type: external
host: "unix:///home/${USER}/.cache/svacer-docker-host/svacer-docker.sock"

=== Конфигурация по умолчанию ===

Данная конфигурация применяется по умолчанию, если в конфигурационном файле svacer.cfg отсутствует раздел <code>xsvacer/docker</code>:
docker:
hosts:
default:
type: external
local:
type: managed
host: "unix://${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.sock"
disabled: true

managed:
executable: "dockerd-rootless.sh"
env:
- "DOCKERD_ROOTLESS_ROOTLESSKIT_STATE_DIR=${USER_CACHE_DIR}/svacer-docker-host/state-dir/"
args:
- "--data-root=${USER_CACHE_DIR}/svacer-docker-host/data-root/"
- "--exec-root=${USER_CACHE_DIR}/svacer-docker-host/exec-root/"
- "--pidfile=${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.pid"
logLevel: info
logPrefix: "DOCKER HOST: "
healthCheck:
interval: 1s
retries: 10

'''Внимание!''' При наличии раздела <code>xsvacer/docker</code> в конфигурационном файле <code>svacer.cfg</code>, будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.

=== Изменение конфигурационных параметров с помощью переменных окружения ===

Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения <code>XSVACER_DOCKER_HOSTS_{id хоста}[_параметр]={значение параметра}</code>

Например, для активации rootless-хоста <code>xsvacer/hosts/local</code> можно указать такие значения переменных окружения при запуске svacer'а:
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false

== Известные проблемы ==

Список известных проблем и их решение

=== rootless-хост продолжает работать при некорректной остановке svacer'а ===

При некорректном завершении работы svacer'а (например, при получении сигнала <code>SIGKILL</code>), процесс rootless-хоста останется в запущенным в системе.

При этом svacer потеряет возможность управления (запуска/остановки) этого процесса.

При последующем запуске svacer попробует повторно запустить rootless-хост и получит сообщение типа <code>[rootlesskit:parent] error: failed to lock /path/to/svacer-docker-host/state-dir/lock, another RootlessKit is running with the same state directory?</code>

При этом, если настройки не менялись, зависимые функциональности смогут получить доступ к "неконтролируемому" rootless-хосту, т.к. адрес unix-сокета хоста известен.

При остановке svacer не будет останавливать "неконтролируемый" rootless-хост.

Процесс rootless-хоста при необходимости может быть остановлен, например, отправкой ему сигнала <code>SIGTERM</code>.

Help:XSvacer:Webide

2024-06-05T07:04:13Z

M.vinogradov:

= Поддержка среды разработки Theia IDE =
'''Примечание:''' данная функциональность входит в набор расширений XSvacer.

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

По умолчанию запускается IDE собранная на основе Theia IDE (https://theia-ide.org/).

== Активация функциональности ==
Для активации функциональности необходимо указать флаг <code>--xsvacer.features webide</code> при запуске svacer'а.

'''Примечание:''' при запуске функциональности <code>webide</code> также будет запущена функциональность <code>docker</code>, с использованием которой осуществляется доступ к хосту docker'а, на котором будут запускаться контейнеры с IDE.

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

Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code>.

Раздел конфигурации для управления функциональностью - <code>xsvacer/webide</code>.

Раздел содержит перечисление настроек доступных конфигураций для запуска экземпляров Theia IDE <code>xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций запуска Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.

xsvacer:
webide:
theia:
config1:
...
config2:
...

'''Внимание!''' Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому помимо настройки функциональности в разделе <code>xsvacer/webide</code> необходимо также настроить доступ к docker-хосту в разделе <code>xsvacer/docker</code> ([[Help:XSvacer:Docker]]). В противном случае функциональность webide не сможет работать корректно.

'''Примечание:''' в случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code>xsvacer/webide</code>, будет использоваться конфигурация по умолчанию (см. ниже)

=== Конфигурация запуска Theia IDE ===

'''Внимание!''' На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!

Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code>xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например идентификатор по номеру используемой версии IDE:
xsvacer:
webide:
theia:
1-46-0:
name: Theia blueprint web IDE (v1.46.0)
...

==== Базовые параметры конфигурации запуска ====

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|disabled
|bool
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE
|true (переопределяется в конфигурации <code>default</code>)
|-
|order
|int
|Порядковый номер в списке выбора конфигурации запуска
|0
|-
|name
|string
|Название конфигурации
|Theia blueprint web IDE (v1.46.0)
|-
|sourcesroot
|string
|Путь к папке содержащей исходные коды снимков на машине со svacer'ом
|${USER_CACHE_DIR}/svacer-snapshot-sources
|-
|dockerhostsourcesroot
|string
|Путь к папке содержащей исходные коды снимков на хосте docker'а. Нужен при использовании удалённого docker-хоста, т.к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code>sourcesroot</code>
|
|-
|dockerhostpathseparator
|string
|Разделитель пути на хосте docker'а. По умолчанию <code>"/"</code>.
|
|-
|sariffiletemplate
|golang template string
|Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура <code>sarifFileContext</code>
|"<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif"
|}

==== Параметры менеджера запуска IDE ====

Конфигурация менеджера запуска IDE. На данный момент доступен только "стандартный" менеджер (<code>type: default</code>)

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|manager
|map
|Конфигурация менеджера запуска IDE
|
|-
|manager/type
|enum: default
|Тип менеджера запуска IDE
|default
|}

==== Параметры запуска docker-контейнеров с IDE ====

Данные параметры используются для настройки запуска docker-контейнеров с IDE

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|docker/
|map
|Настройки создания docker-контейнера с IDE
|
|-
|docker/hostid
|string
|Идентификатор хоста docker'а, описанного в <code>xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте
|default
|-
|docker/containernametemplate
|golang template string
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура <code>TheiaDockerContainerStartContext</code> (см. ниже)
|"theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"
|-
|docker/containerconfiglabels
|[]map
|Список "меток" docker-контейнера. Дополняет список меток в <code>docker/container/config/labels</code>
|
- "com.docker.compose.project": svacer
|-
|docker/image/
|map
|Параметры docker-образа из которого будет запущен контейнер
|
|-
|docker/image/name
|string
|Название образа
|theia-blueprint
|-
|docker/image/tag
|string
|Тег образа
|1.46.0.sarif.clang
|-
|docker/image/sourcetype
|enum: repository/file
|Тип источника для загрузки образа в docker-хост.
* <code>repository</code> - будет вызван <code>docker pull</code> образа <code>{image/name}:{image/tag}</code>
* <code>file</code> - будет вызван <code>docker load</code> с url'ом <code>image/sourcefileurl</code>
|file
|-
|docker/image/sourcefileurl
|url
|Url откуда будет загружен docker-образ если <code>image/sourcetype == "file"</code>
Url может содержать:
- путь к локальному файлу: схема <code>file://</code>
- http/https-адрес: схема <code>http://</code> или <code>https://</code>
|https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar
|-
|docker/container/
|map
|Свойства docker-контейнера
|
|-
|docker/container/config
|map
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70
|
|-
|docker/container/config/env
|[]string
|Список переменных среды, которые будут установлены в контейнере
|
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki>
|-
|docker/container/hostconfig/
|map
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379
|
|-
|docker/container/hostconfig/autoremove
|bool
|
|true
|-
|docker/container/hostconfig/portbindings
|map
|
|
"3000/tcp":
- hostport: 0
|-
|docker/container/networkconfig/
|map
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104
|
|}

==== Параметры проверки доступности healthcheck ====

Данные параметры используются для проверки доступности IDE после запуска docker-контейнера

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|healthcheck
|map
|Параметры проверки доступности IDE
|
|-
|healthcheck/starttoreadyretries
|int
|Количества попыток проверки до ошибки доступности
|10
|-
|healthcheck/starttoreadyperiod
|golang duration string
|Интервал проверки
|200ms
|}

==== Структуры передаваемые в поля с golang-шаблонами строк ====

sarifFileContext {
Time time.Time
Context: {
ProjectID *string
BranchID *string
SnapshotID *string
MarkerID *string

ProjectName *string
BranchName *string
SnapshotName *string
MarkerName *string
CreatedBy null.String
CreatedByID null.String
CreateTs null.Time
}
}

TheiaDockerContainerStartContext {
IdeID: {
IdeType string
ConfigID string
},
StartArgs: {
SnapshotID string
UserID string
User string
},
Context: {
ProjectID *string
BranchID *string
SnapshotID *string
MarkerID *string

ProjectName *string
BranchName *string
SnapshotName *string
MarkerName *string
CreatedBy null.String
CreatedByID null.String
CreateTs null.Time
}
}

=== Конфигурация по умолчанию используемая в svacer ===

Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code>xsvacer/webide</code>:

xsvacer:
docker:
hosts:
default: # конфигурация docker-хоста, действующая по умолчанию
type: external
...

webide:
theia:
1-46-0: &1-46-0
disabled: true
order: 0
name: Theia blueprint web IDE (v1.46.0)
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources
sariffiletemplate: "<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif"
manager:
type: default
docker:
hostid: default # идентификатор используемого docker-хоста
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"
image:
name: theia-blueprint
tag: 1.46.0.sarif.clang
sourcetype: file
sourcefileurl: https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar
containerconfiglabels:
- "com.docker.compose.project": svacer
container:
config:
env:
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki>
hostconfig:
autoremove: true
portbindings:
"3000/tcp":
- hostport: 0
networkconfig:
healthcheck:
starttoreadyretries: 10
starttoreadyperiod: 200ms
default:
<<: *1-46-0
order: 0
disabled: false

'''Внимание!''' По умолчанию используется docker-хост с идентификатором <code>default</code>. Согласно настройке этого хоста, по умолчанию предполагается взаимодействие с докером через unix-сокет <code>unix:///var/run/docker.sock</code>. Соответственно пользователь, под которым запускается svacer должен иметь доступ к этому сокету (https://docs.docker.com/engine/install/linux-postinstall/).

'''Внимание!''' При наличии раздела <code>xsvacer/webide</code> в конфигурационном файле <code>svacer.cfg</code>, будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.

=== Изменение конфигурационных параметров с помощью переменных окружения ===

Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения <code>XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code>

Например, для активации rootless-хоста <code>xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code>default</code> на этот хост, можно указать такие значения переменных окружения при запуске svacer'а:
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local

== Рекомендации ==

=== Предварительная загрузка docker-образа с IDE ===

По умолчанию параметр <code>xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl</code> содержит значение <code>https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar</code>. По этому адресу находится архив с docker-образом для Theia IDE.

Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т.к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго.

Для ускорения первого запуска IDE, докер образ можно загрузить в хост docker'а вручную. Для этого необходимо:
# Скачать файл архива;
# Выполнить команду <code>docker image load -i /path/to/tar/theia-blueprint.1.46.0.sarif.clang.tag</code>;