https://svacer.ispras.ru/mediawiki/api.php?action=feedcontributions&feedformat=atom&user=M.vinogradovSvacer Wiki - User contributions [en]2026-07-09T07:29:51ZUser contributionsMediaWiki 1.40.1https://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_deploy&diff=3573Help:13-alpha deploy2026-05-26T12:07:10Z<p>M.vinogradov: mcp link</p>
<hr />
<div>== Демонстрационная сборка ==<br />
<br />
Установка демонстрационной версии Svacer с поддержкой [[Help:13-alpha introduction|описанных функций]] доступна только в докере с использованием docker compose<br />
<br />
== docker compose ==<br />
<br />
Для установки демонстрационной версии подготовлен специальный файл [https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml docker-compose-with-ai-llm-mcp.yml]<br />
<br />
<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml</nowiki><br />
<br />
При запуске Svacer с использованием данного compose-файла доступны профили:<br />
<br />
{| class="wikitable"<br />
! Профиль !! Описание<br />
|-<br />
| Без профиля || Запуск Svacer без поддержки ИИ-ассистента и MCP<br />
|-<br />
| <code>ai</code> || Запуск Svacer с поддержкой ИИ-ассистента со встроенной моделью<br />
|-<br />
| <code>llm</code> || Запуск Svacer с поддержкой ИИ-ассистента и возможностью подключения к нему внешних LLM для разметки предупреждений<br />
|-<br />
| <code>mcp</code> || Запуск Svacer с [[Help:13-alpha MCP|MCP-сервером]]<br />
|-<br />
| <code>"*"</code> || Запуск Svacer со всеми доступными профилями<br />
|}<br />
<br />
Для запуска с использованием одного или нескольких профилей используется команда<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml ... --profile llm --profile mcp ... up -d<br />
<br />
При этом необходимо учитывать, что<br />
<br />
* при запуске Svacer без профилей или только с профилем <code>mcp</code> функциональность разметки предупреждений с помощью ИИ будет возвращать ошибку;<br />
<!-- * Профиль <code>no-ai</code> не может быть использован одновременно с другими профилями; --><br />
* запуск с профилями <code>llm</code> и <code>mcp</code> требует настройки переменных окружения (см. ниже).<br />
<br />
Для удобства настройки переменных окружения может использоваться env-файл [https://svacer.ispras.ru/extra/llm-mcp.env llm-mcp.env], который после установки необходимых значений может быть передан команде запуска<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --env-file ./llm-mcp.env ... --profile llm --profile mcp ... up -d<br />
<br />
== <code>--profile ai</code> ==<br />
Данный профиль не требует дополнительной конфигурации для запуска<br />
<br />
== <code>--profile llm</code> ==<br />
Запуск Svacer с данным профилем даёт возможность подключить к ИИ-ассистенту внешний сервис моделей, поддерживающий OpenAI API. После успешного подключения ИИ-ассистент сможет использовать LLM для разметки и комментирования предупреждений. В списке разметки с помощью ИИ появятся модели доступные пользователю, чей ключ был передан при запуске.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>LLM_URL</code> значение url, по которому контейнер <code>svacer-validation-server</code> сможет подключиться к сервису моделей, совместимому с OpenAI API;<br />
* установить в переменную окружения <code>LLM_TOKEN</code> значение ключа авторизации в сервис моделей;<br />
* при необходимости установить значения переменных <code>REG_TOKEN</code> или <code>REG_LOGIN</code> и <code>REG_PASSWORD</code> содержащих, соответственно, токен авторизации или логин и пароль администратора. Эти данные нужны для запуска компонентов поддержки LLM в ИИ-ассистенте. По умолчанию будут использоваться логин и пароль <code>admin:admin</code>;<br />
* при желании изменить отображаемое название сервиса в интерфейсе выбора моделей, можно установить значение переменной <code>REG_NAME</code>. По умолчанию <code>llm</code>;<br />
* при необходимости ограничения списка доступных моделей, в переменную <code>MODEL_WHITELIST</code> нужно передать список названий моделей разделённых запятыми;<br />
* если производительность сервиса моделей позволяет параллельно обрабатывать несколько предупреждений, то можно установить значение переменной <code>MAX_PARALLEL_REQUESTS</code> в значение больше единицы;<br />
* если производительность модели не позволяет обрабатывать одно предупреждение в минуту, то результаты обработки не будут получены. Чтобы увеличить время ожидания новых результатов модели, можно установить значение переменной <code>MODEL_VALIDATION_MAXATTEMPTS</code> в значение кратное 12 (двенадцати). Например, значение 60 == 5 минут.<br />
<br />
Значения данных переменных могут быть сохранены в <code>.env</code> файл и переданы при запуске с помощью аргумента <code>docker compose --env-file ./.env ... up -d</code><br />
<br />
Описание переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# URL of the OpenAI API-compatible LLM model service<br />
LLM_URL=<br />
<br />
# LLM model service authorization token<br />
LLM_TOKEN=<br />
<br />
# Svacer admin authorization token for the operation of AI-assistant components <br />
# Or with REG_LOGIN and REG_PASSWORD, if token is not set<br />
# REG_TOKEN=<br />
<br />
# Svacer admin login and password for the operation of AI-assistant components<br />
# REG_LOGIN=admin<br />
# REG_PASSWORD=admin<br />
<br />
# ID of the service in the AI-assistant<br />
# REG_ID=llm<br />
<br />
# The name of the service displayed in the AI-assistant<br />
# REG_NAME=llm<br />
<br />
# Service description<br />
# REG_DESCRIPTION="LLM model service"<br />
<br />
# Comma-separated list of available models. If not specified, all models available to the LLM model service user will be available.<br />
# MODEL_WHITELIST=<br />
<br />
# Maximum number of simultaneous requests to the LLM model service<br />
# MAX_PARALLEL_REQUESTS=1<br />
<br />
# Maximum number of 5s attempts to get single warning result from LLM<br />
# MODEL_VALIDATION_MAXATTEMPTS=12<br />
</pre><br />
<br />
== <code>--profile mcp</code> ==<br />
При запуске с данным профилем стартует контейнер с MCP-сервером, подключённый к текущему экземпляру Svacer.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>MCP_PORT</code> номер сетевого порта на котором будет доступен MCP-сервер. По умолчанию будет назначен порт <code>8002</code>;<br />
* установить в переменную окружения <code>SVACER_MPC_TOKEN</code> строку с токеном авторизации, который необходимо будет указать в клиенте MCP-сервера;<br />
* при необходимости доступа к MCP-серверу по адресу отличному от <code>localhost</code> (<code>127.0.0.1</code>) или при использовании DNS необходимо:<br />
** указать необходимый адрес/dns-имя в переменной <code>MCP_ALLOWED_HOSTS</code> в виде <code>172.17.0.1:*</code>/<code>some.domain:*</code>;<br />
** указать необходимый адрес/dns-имя в переменной <code><nowiki>MCP_ALLOWED_ORIGINS</nowiki></code> в виде <code><nowiki>http://172.17.0.1:*</nowiki></code>/<code><nowiki>http://some.domain:*</nowiki></code>;<br />
* при необходимости можно настроить логин и пароль пользователя, от имени которого MCP-сервер будет выполнять запросы к Svacer. По умолчанию <code>admin:admin</code>.<br />
<br />
После запуска mcp-сервер будет доступен по адресу <code><nowiki>http://localhost:{MCP_PORT}/mcp</nowiki></code><br />
<br />
Описание других переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# Bearer token for /mcp clients in HTTP mode. Generate: openssl rand -hex 32<br />
SVACER_MCP_TOKEN=<br />
<br />
# Svacer admin login and password<br />
# SVACER_LOGIN=admin<br />
# SVACER_PASSWORD=admin<br />
<br />
# External port that will be mapped by docker to the internal port 8000<br />
# MCP_PORT=8002<br />
<br />
# DNS rebinding protection for FastMCP<br />
# MCP_ENABLE_DNS_REBINDING_PROTECTION=false<br />
# MCP_ALLOWED_HOSTS=svacer-mcp:*<br />
# MCP_ALLOWED_ORIGINS=http://svacer-mcp:*<br />
<br />
# HTTP timeout for requests to Svacer, seconds<br />
# SVACER_TIMEOUT=30<br />
<br />
# Public URL of this MCP server (used for WWW-Authenticate, RFC 9728).<br />
# Defaults to http://localhost:<SVACER_HTTP_PORT>. Set when running behind a reverse proxy.<br />
# SVACER_MCP_RESOURCE_URL=https://mcp.example.com<br />
<br />
# Subset of tools to register (comma-separated). Unset = all 8 tools.<br />
# Available: get_projects, get_snapshots, get_warnings, get_markers,<br />
# get_project_stats, get_project_groups, get_advanced_file_preview, get_diff<br />
# SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
</pre><br />
<br />
== Удаление демонстрационной версии == <br />
<br />
В процессе запуска демонстрационной версии в docker будут созданы контейнеры, тома, сеть с префиксом <code>svacer-13</code>. Чтобы из удалить, выполните последовательно следующие шаги:<br />
# Остановите и удалите все docker-контейнеры Svacer;<br />
# Удалите тома с данными Svacer;<br />
# Удалите docker-образы демонстрационной версии Svacer;<br />
<br />
=== Остановка и удаление docker-контейнеров Svacer ===<br />
<br />
<pre><br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --profile "*" down<br />
</pre><br />
<br />
После остановки и удаления docker-контейнеров с компонентами Svacer, данные продолжат храниться в docker-томах. Поэтому при повторном запуске демонстрационной версии они будут доступны.<br />
<br />
=== Удаление томов с данными БД, объектного и файлового хранилищ ===<br />
<br />
После выполнения следующей команды все данные накопленные за время работы демонстрационной версии Svacer будут удалены. При повторном запуске будет развёрнута чистая версия системы.<br />
<br />
<pre><br />
docker volume rm svacer-13-ai-postgres svacer-13-object-store svacer-13-postgres svacer-13-snapshot-sources<br />
</pre><br />
<br />
Удаление томов также можно выполнить одновременно с остановкой и удалением docker-контейнеров Svacer<br />
<br />
<pre><br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --profile "*" down -v<br />
</pre><br />
<br />
=== Удаление docker-образов ===<br />
<br />
После удаления docker-образов компонентов демонстрационной версии Svacer, при повторном запуске они снова будут загружены из репозитория https://hub.docker.com.<br />
<br />
<pre><br />
docker image rm ispras/svacer:13-alpha ispras/svacerai:13-alpha ispras/svacer-mcp:13-alpha ispras/validation-server:13-alpha<br />
</pre><br />
<br />
Удаление томов также можно выполнить одновременно с остановкой и удалением docker-контейнеров Svacer и томов с данными<br />
<br />
<pre><br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --profile "*" down -v --rmi all<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_MCP&diff=3569Help:13-alpha MCP2026-05-26T10:07:41Z<p>M.vinogradov: Удалена плашка со ссылкой на деморелиз</p>
<hr />
<div>== Архитектура ==<br />
[https://modelcontextprotocol.io/docs/getting-started/intro MCP] — открытый стандарт, через который LLM-клиенты (Claude Desktop, Cursor, VS Code, OpenWebUI и др.) вызывают внешние инструменты. <br />
Svacer MCP соединяет одно с другим: 8 инструментов поверх публичного REST API Svacer, которые LLM выбирает и вызывает в ответ на обычный текстовый запрос. Вместо ручной последовательности «открыть UI, найти проект, выбрать снимок, применить фильтр» достаточно сформулировать вопрос в чате, например, «сколько критических предупреждений в последнем снимке bash?», и получить ответ. Необходимые вызовы инструментов модель выполняет самостоятельно.<br />
<br />
[[File:Архитектура MCP.png|thumb|none|x800px|alt=architectureMCP|Архитектура MCP-сервера]]<br />
<br />
Поток запроса: LLM-клиент отправляет MCP-вызов через STDIO или Streamable HTTP → <code>server.py</code> передаёт его в выбранный инструмент из <code>tools/</code> → инструмент проверяет параметры и обращается к <code>api_client.py</code> → клиент получает JWT от <code>auth.py</code> (модуль автоматически обновляет токен по истечении срока действия или при ответе 401) → запрос отправляется в Svacer REST API.<br />
<br />
== Установка ==<br />
<br />
Svacer MCP может быть подключён к любому серверу Svacer версии 12 и выше. В данном разделе описывается установка Svacer MCP, подключение клиентов и конфигурация.<br />
<br />
=== Требования ===<br />
<br />
* Python 3.10+<br />
* Доступ к серверу Svacer: URL + логин/пароль<br />
<br />
=== Режим STDIO ===<br />
Подходит для настольных клиентов: Claude Desktop, Claude Code, Cursor, VS Code.<br />
git clone <nowiki>https://gitlab.ispras.ru/svacerai/mcp.git</nowiki> && cd mcp<br />
<br />
python3 -m venv .venv<br />
.venv/bin/pip install -e .<br />
<br />
cp .env.example .env<br />
# Отредактировать .env — указать URL и учётные данные Svacer<br />
<br />
# Проверить запуск (сервер ожидает данные на stdin; для выхода — Ctrl+C)<br />
.venv/bin/svacer-mcp<br />
<br />
После <code>pip install -e .</code> в окружении становится доступна команда <code>svacer-mcp</code> — её указывают в конфигурации клиентов ниже.<br />
<br />
=== Режим HTTP (Docker) ===<br />
Подходит для веб-клиентов (OpenWebUI) и удалённого доступа.<br />
<br />
'''Требования:''' Docker, Docker Compose.<br />
cp .env.example .env<br />
<br />
# В .env обязательно задать SVACER_MCP_TOKEN — без него сервер не запускается<br />
echo "SVACER_MCP_TOKEN=$(openssl rand -hex 32)" >> .env<br />
<br />
docker compose up -d<br />
<br />
# MCP endpoint: <nowiki>http://localhost:8002/mcp</nowiki><br />
# Клиенты передают заголовок: Authorization: Bearer <SVACER_MCP_TOKEN><br />
<br />
Внешний порт хоста задаётся переменной <code>MCP_PORT</code> (по умолчанию <code>8002</code>), внутри контейнера сервер всегда слушает порт <code>8000</code>.<br />
<br />
=== Подключение клиентов ===<br />
<br />
==== Claude Desktop ====<br />
Файл конфигурации: <code>~/.config/Claude/claude_desktop_config.json</code> (Linux) или <code>%APPDATA%\Claude\claude_desktop_config.json</code> (Windows).<br />
<br />
Укажите '''абсолютный путь''' к <code>svacer-mcp</code> из вашего venv (<code>which svacer-mcp</code> в активированном venv или <code>/path/to/mcp/.venv/bin/svacer-mcp</code>).<br />
<br />
{<br />
"mcpServers": {<br />
"svacer": {<br />
"command": "/path/to/mcp/.venv/bin/svacer-mcp",<br />
"env": {<br />
"SVACER_URL": "<nowiki>https://your-svacer.example.com</nowiki>",<br />
"SVACER_LOGIN": "your-login",<br />
"SVACER_PASSWORD": "your-password"<br />
}<br />
}<br />
}<br />
}<br />
<br />
==== Claude Code ====<br />
claude mcp add svacer \<br />
-e SVACER_URL=<nowiki>https://your-svacer.example.com</nowiki> \<br />
-e SVACER_LOGIN=your-login \<br />
-e SVACER_PASSWORD=your-password \<br />
-- /path/to/mcp/.venv/bin/svacer-mcp<br />
<br />
==== VS Code ====<br />
Файл <code>.vscode/mcp.json</code> в корне рабочей директории:<br />
<br />
{<br />
"servers": {<br />
"svacer": {<br />
"type": "stdio",<br />
"command": "/path/to/mcp/.venv/bin/svacer-mcp",<br />
"env": {<br />
"SVACER_URL": "<nowiki>https://your-svacer.example.com</nowiki>",<br />
"SVACER_LOGIN": "your-login",<br />
"SVACER_PASSWORD": "your-password"<br />
}<br />
}<br />
}<br />
}<br />
<br />
==== Cursor ====<br />
Файл <code>.cursor/mcp.json</code> в корне проекта или глобально:<br />
<br />
{<br />
"mcpServers": {<br />
"svacer": {<br />
"command": "/path/to/mcp/.venv/bin/svacer-mcp",<br />
"env": {<br />
"SVACER_URL": "<nowiki>https://your-svacer.example.com</nowiki>",<br />
"SVACER_LOGIN": "your-login",<br />
"SVACER_PASSWORD": "your-password"<br />
}<br />
}<br />
}<br />
}<br />
<br />
==== OpenWebUI ====<br />
# Развернуть через Docker (см. [[#Режим HTTP (Docker)|Режим HTTP]]).<br />
# Открыть '''Settings → Tools''' (или '''Admin Panel → Settings → Tools''').<br />
# Добавить сервер:<br />
#* <code><nowiki>http://localhost:8002/mcp</nowiki></code> — если OpenWebUI работает на хосте, снаружи Docker.<br />
#* <code><nowiki>http://svacer-mcp:8000/mcp</nowiki></code> — если OpenWebUI развёрнут в той же compose-сети, что и <code>svacer-mcp</code> (имя берётся из <code>docker-compose.yml</code> → service name, порт 8000 — внутренний порт контейнера).<br />
# Тип подключения: '''MCP (Streamable HTTP)'''.<br />
# В настройках инструмента указать заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code> (значение — то же, что в <code>.env</code> сервера).<br />
# Сохранить — инструменты появятся в чате.<br />
<br />
=== Конфигурация ===<br />
{| class="wikitable"<br />
!Переменная<br />
!По умолчанию<br />
!Описание<br />
|-<br />
|SVACER_URL<br />
|<nowiki>https://svacer-demo.ispras.ru</nowiki><br />
|URL сервера Svacer<br />
|-<br />
|SVACER_LOGIN<br />
|admin<br />
|Логин<br />
|-<br />
|SVACER_PASSWORD<br />
|admin<br />
|Пароль<br />
|-<br />
|SVACER_TIMEOUT<br />
|30<br />
|Тайм-аут HTTP-запросов к Svacer, секунды<br />
|-<br />
|SVACER_TRANSPORT<br />
|stdio<br />
|Режим транспорта: <code>stdio</code> или <code>http</code><br />
|-<br />
|SVACER_HTTP_PORT<br />
|8000<br />
|TCP-порт сервера в режиме HTTP (внутри контейнера)<br />
|-<br />
|SVACER_MCP_TOKEN<br />
|''(не задано)''<br />
|Bearer-токен для клиентов <code>/mcp</code>. Обязателен при <code>SVACER_TRANSPORT=http</code>, в режиме STDIO игнорируется. Генерация: <code>openssl rand -hex 32</code><br />
|-<br />
|SVACER_MCP_RESOURCE_URL<br />
|<nowiki>http://localhost</nowiki>:<HTTP_PORT><br />
|Публичный URL MCP-сервера для заголовка <code>WWW-Authenticate</code> (<nowiki>RFC 9728</nowiki>). Задаётся при работе за обратным прокси<br />
|-<br />
|SVACER_TOOLS<br />
|''(не задано)''<br />
|Список инструментов через запятую. Если не задано, регистрируются все 8<br />
|-<br />
|MCP_PORT<br />
|8002<br />
|Внешний порт хоста при запуске через <code>docker compose</code> (отображается на внутренний <code>SVACER_HTTP_PORT</code>)<br />
|}<br />
Переменные читаются из <code>.env</code> или из окружения. Для STDIO-клиентов их можно указать в секции <code>env</code> конфигурации клиента.<br />
<br />
==== Ограничение набора инструментов ====<br />
Чтобы запустить сервер с подмножеством инструментов (например, для уменьшения объёма контекста у модели или разграничения доступа), задайте <code>SVACER_TOOLS</code>:<br />
SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
Допустимые имена: <code>get_projects</code>, <code>get_snapshots</code>, <code>get_warnings</code>, <code>get_markers</code>, <code>get_project_stats</code>, <code>get_project_groups</code>, <code>get_advanced_file_preview</code>, <code>get_diff</code>. Неизвестное имя в списке приводит к ошибке при запуске. Если переменная пустая или не задана, регистрируются все 8 инструментов.<br />
<br />
==== Несколько экземпляров сервера ====<br />
Параллельный запуск нескольких MCP-серверов поддерживается без ограничений.<br />
<br />
* В режиме STDIO каждая запись в конфигурации клиента описывает отдельный процесс — несколько подключений к разным экземплярам Svacer задаются простым перечислением.<br />
* В режиме HTTP запускаются независимые контейнеры на разных хост-портах: например, <code>MCP_PORT=8002</code> для одного экземпляра и <code>MCP_PORT=8003</code> для другого. Для каждого контейнера задаётся собственный <code>SVACER_MCP_TOKEN</code>.<br />
<br />
=== Безопасность ===<br />
<br />
* '''STDIO''': сервер не открывает сетевых портов и обменивается данными через стандартные потоки ввода/вывода процесса.<br />
* '''Streamable HTTP''': эндпоинт <code>/mcp</code> требует заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code>. Запросы без токена или с неверным значением получают ответ <code>401</code> и заголовок <code>WWW-Authenticate: Bearer ...</code>. Токен является разделяемым секретом и не заменяет TLS, а дополняет его: при работе за обратным прокси необходимо использовать HTTPS, а сам токен передавать только по защищённому каналу.<br />
* Без <code>SVACER_MCP_TOKEN</code> HTTP-сервер не запускается.<br />
* Учётные данные <code>admin/admin</code> предназначены только для тестового стенда. В рабочем окружении необходимо задать собственные логин и пароль через переменные окружения.<br />
* Файл <code>.env</code> не должен добавляться в систему контроля версий.<br />
<br />
==== Передача токена клиентом ====<br />
Большинство HTTP-клиентов MCP (OpenWebUI и др.) позволяют задать произвольный заголовок <code>Authorization</code> в настройках инструмента — указывается значение <code>Bearer <токен></code>. Для ручной проверки:<br />
curl -H "Authorization: Bearer $SVACER_MCP_TOKEN" \<br />
<nowiki> </nowiki> -H 'Content-Type: application/json' \<br />
<nowiki> </nowiki> -H 'Accept: application/json, text/event-stream' \<br />
<nowiki> </nowiki> -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \<br />
<nowiki> </nowiki> <nowiki>http://localhost:8002/mcp</nowiki><br />
<br />
== Инструменты ==<br />
Справочник по 8 инструментам Svacer MCP. Типичный порядок вызовов: <code>get_projects</code> → <code>get_snapshots</code> → любой из аналитических инструментов.<br />
{| class="wikitable"<br />
!Инструмент<br />
!Назначение<br />
|-<br />
|get_projects<br />
|Список проектов с ветками — точка входа<br />
|-<br />
|get_snapshots<br />
|Снимки конкретной ветки, от нового к старому<br />
|-<br />
|get_project_stats<br />
|Агрегированные метрики снимка: severity / review / checker<br />
|-<br />
|get_markers<br />
|Компактный список маркеров с серверной фильтрацией<br />
|-<br />
|get_warnings<br />
|Полные предупреждения с трассами и историей разметки<br />
|-<br />
|get_diff<br />
|Сравнение двух снимков: new / missing / modified / matched<br />
|-<br />
|get_advanced_file_preview<br />
|Фрагмент исходного кода вокруг строки<br />
|-<br />
|get_project_groups<br />
|Группа проектов по имени или UUID<br />
|}<br />
<br />
=== get_projects ===<br />
Список всех проектов с ветками. Точка входа: с этого вызова начинается практически любой сценарий — он возвращает <code>project_id</code> и <code>branch_id</code>, необходимые для последующих запросов.<br />
<br />
'''Параметров нет.'''<br />
<br />
'''Вызов:'''<br />
get_projects()<br />
<br />
'''Ответ:'''<br />
[<br />
{<br />
"project_id": "91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
"project_name": "bash",<br />
"created": "2021-12-13T13:22:42.122456Z",<br />
"created_by": "admin",<br />
"branches": [<br />
{<br />
"branch_id": "77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
"branch_name": "master",<br />
"created": "2021-12-13T13:22:42.394812Z"<br />
}<br />
]<br />
}<br />
]<br />
----<br />
<br />
=== get_snapshots ===<br />
Список снимков для конкретной ветки проекта, от нового к старому.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|name_filter<br />
|string<br />
|нет<br />
|Подстрока или regex для фильтра по имени снимка<br />
|}<br />
<br />
'''Вызов:'''<br />
get_snapshots(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4"<br />
)<br />
<br />
'''Ответ:'''<br />
[<br />
{<br />
"snapshot_id": "b42cb563-86f4-4f96-900a-7782163327c9",<br />
"name": "Snapshot 2020-03-25 09:09:41 +0300",<br />
"import_time": "2020-03-25T09:09:41.837296Z",<br />
"commit_hash": null,<br />
"markers_count": 297,<br />
"link": "<nowiki>https://svacer-demo.ispras.ru/</nowiki>..."<br />
}<br />
]<br />
----<br />
<br />
=== get_project_stats ===<br />
Агрегированные метрики по снимку: общее количество предупреждений, распределение по критичности, по статусу разметки, по детекторам. Наиболее быстрый способ получить общую картину по проекту.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_snapshots</code><br />
|}<br />
<br />
'''Вызов:'''<br />
get_project_stats(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9"<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"total_warnings": 771,<br />
"by_severity": {<br />
"Critical": 1,<br />
"Major": 1,<br />
"Unspecified": 769<br />
},<br />
"by_review_status": {<br />
"Confirmed": 1,<br />
"False Positive": 1,<br />
"Undecided": 767,<br />
"Unclear": 1,<br />
"Won't fix": 1<br />
},<br />
"by_checker": {<br />
"PROC_USE.VULNERABLE": 337,<br />
"UNUSED_FUNC_RES.REWRITE.MINOR": 44,<br />
"UNREACHABLE_CODE": 28,<br />
"DEREF_AFTER_NULL.EX": 27,<br />
"NULL_AFTER_DEREF": 27<br />
}<br />
}<br />
----<br />
<br />
=== get_markers ===<br />
Компактный список маркеров с серверной фильтрацией. Основной инструмент для перечисления и обзора: его следует предпочитать <code>get_warnings</code>, когда не требуются развёрнутые поля — трассы и история разметки.<br />
<br />
По умолчанию ответ ограничен 30 маркерами и содержит компактный набор полей. Подробнее об ограничении объёма см. раздел [[#Про объём ответа|Про объём ответа]].<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_snapshots</code><br />
|-<br />
|severity<br />
|string[]<br />
|нет<br />
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code> применяется на стороне коннектора<br />
|-<br />
|review<br />
|string[]<br />
|нет<br />
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code><br />
|-<br />
|warnClass<br />
|string[]<br />
|нет<br />
|Идентификатор детектора (<code>DEREF_AFTER_NULL</code>, …)<br />
|-<br />
|file<br />
|string[]<br />
|нет<br />
|Подстрока пути к файлу<br />
|-<br />
|traces<br />
|bool<br />
|нет<br />
|Включить трассы маркеров<br />
|-<br />
|checker_info<br />
|bool<br />
|нет<br />
|Включить метаданные детектора (CWE, описание)<br />
|-<br />
|review_history<br />
|bool<br />
|нет<br />
|Включить историю изменений разметки<br />
|-<br />
|comment_history<br />
|bool<br />
|нет<br />
|Включить комментарии к маркеру<br />
|-<br />
|custom_filter<br />
|string<br />
|нет<br />
|Имя или идентификатор сохранённого фильтра из веб-интерфейса Svacer<br />
|-<br />
|limit<br />
|int<br />
|нет<br />
|Максимальное количество маркеров в ответе (по умолчанию 30). Значение 0 снимает ограничение<br />
|-<br />
|fields<br />
|string[]<br />
|нет<br />
|Список разрешённых полей маркера верхнего уровня. По умолчанию — компактный набор <code>id, warnClass, file, line, msg, function, review</code>. Значение <code>["*"]</code> возвращает все поля коннектора (<code>id, warnClass, file, line, msg, tool, function, mtid, review</code>, а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены). Допустим и произвольный список, например <code>["id","warnClass"]</code><br />
|}<br />
<br />
'''Вызов:'''<br />
get_markers(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
warnClass=["PROC_USE.VULNERABLE"]<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"total_count": 341,<br />
"returned_count": 30,<br />
"truncated": true,<br />
"filters_applied": {"warnClass": ["PROC_USE.VULNERABLE"]},<br />
"markers": [<br />
{<br />
"id": "e05bb35b-a95e-4eb2-85ae-3101b788f07d",<br />
"warnClass": "PROC_USE.VULNERABLE.TEMP",<br />
"file": "/.build/lib/sh/tmpfile.c",<br />
"line": 160,<br />
"msg": "Use of vulnerable function 'mktemp' at tmpfile.c:160. ...",<br />
"function": "sh_mktmpname",<br />
"review": null<br />
}<br />
]<br />
}<br />
<br />
<code>total_count</code> отражает количество маркеров, удовлетворяющих фильтру до применения ограничения; <code>returned_count</code> — количество маркеров, фактически содержащихся в <code>markers</code>. При <code>truncated: true</code> следует либо сузить фильтры (<code>severity</code>, <code>warnClass</code>, <code>file</code>), либо передать <code>limit=0</code> для получения полного списка. Поля <code>tool</code> и <code>mtid</code> возвращаются только при <code>fields=["*"]</code>.<br />
----<br />
<br />
=== get_warnings ===<br />
Полные предупреждения с детальной разметкой. Ответ значительно объёмнее, чем у <code>get_markers</code>, поэтому инструмент следует использовать только тогда, когда нужны поля, отсутствующие в компактной форме: <code>traces</code>, <code>review_history</code>, <code>checker_info</code>, <code>comment_history</code>.<br />
<br />
Лимит по умолчанию — 30; при включённых <code>traces</code>, <code>review_history</code> или <code>comment_history</code> он автоматически снижается до 8, поскольку такие предупреждения существенно объёмнее.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_snapshots</code><br />
|-<br />
|severity<br />
|string[]<br />
|нет<br />
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code>, применяется на стороне коннектора<br />
|-<br />
|review<br />
|string[]<br />
|нет<br />
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code><br />
|-<br />
|warnClass<br />
|string[]<br />
|нет<br />
|Идентификатор детектора<br />
|-<br />
|file<br />
|string[]<br />
|нет<br />
|Подстрока пути к файлу<br />
|-<br />
|traces<br />
|bool<br />
|нет<br />
|Включить трассы. Активирует режим расширенных полей (лимит по умолчанию — 8)<br />
|-<br />
|checker_info<br />
|bool<br />
|нет<br />
|Включить метаданные детектора (CWE, описание)<br />
|-<br />
|review_history<br />
|bool<br />
|нет<br />
|Включить историю разметки. Режим расширенных полей<br />
|-<br />
|comment_history<br />
|bool<br />
|нет<br />
|Включить комментарии. Режим расширенных полей<br />
|-<br />
|custom_filter<br />
|string<br />
|нет<br />
|Имя или идентификатор сохранённого фильтра<br />
|-<br />
|limit<br />
|int<br />
|нет<br />
|Максимальное количество предупреждений в ответе. По умолчанию — 30, в режиме расширенных полей — 8. Значение 0 снимает ограничение. Явно заданное <code>limit</code> отменяет автоматическое снижение<br />
|-<br />
|fields<br />
|string[]<br />
|нет<br />
|См. описание в <code>get_markers</code><br />
|}<br />
'''Вызов:'''<br />
get_warnings(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
severity=["Critical"],<br />
review_history=True,<br />
traces=True<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"total_count": 1,<br />
"returned_count": 1,<br />
"truncated": false,<br />
"filters_applied": {"severity": ["Critical"], "traces": true, "review_history": true},<br />
"warnings": [<br />
{<br />
"id": "a3f21c90-1d4e-4b82-9f63-7c8e5d2a1b09",<br />
"warnClass": "DEREF_AFTER_NULL.LOOP",<br />
"file": "/.build/execute_cmd.c",<br />
"line": 3327,<br />
"msg": "Possible null pointer dereference of 'l' after loop exit.",<br />
"function": "select_query",<br />
"review": {"status": "Confirmed", "severity": "Critical"},<br />
"review_history": [{"status": "Confirmed", "changed_by": "admin", "changed_at": "2021-12-13T14:00:00Z"}],<br />
"traces": [{"file": "/.build/execute_cmd.c", "line": 3320, "msg": "Loop starts here; 'l' may exhaust the list."}]<br />
}<br />
]<br />
}<br />
----<br />
<br />
=== get_diff ===<br />
Сравнение двух снимков. Категории располагаются под ключом <code>markers</code>: <code>new_markers</code> (появилось в новом снимке), <code>missing_markers</code> (исчезло из нового), <code>modified_markers</code> (тот же идентификатор, изменился контекст), <code>matched_markers</code> (совпало в обоих). Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно UUID снимков.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|base_snapshot_id<br />
|string (UUID)<br />
|да<br />
|Старый снимок<br />
|-<br />
|head_snapshot_id<br />
|string (UUID)<br />
|нет<br />
|Новый снимок; если не указан, сравнение выполняется с предыдущим по времени<br />
|-<br />
|level<br />
|int<br />
|нет<br />
|0 — только статистика; 1 — статистика и идентификаторы маркеров; 2 — полные маркеры по категориям<br />
|-<br />
|checker_info<br />
|bool<br />
|нет<br />
|Метаданные детекторов для маркеров (только при <code>level >= 2</code>)<br />
|-<br />
|limit<br />
|int<br />
|нет<br />
|Максимальное количество маркеров '''на каждую категорию''' при <code>level >= 2</code>. По умолчанию — 20, значение 0 снимает ограничение. Параметр игнорируется при <code>level < 2</code><br />
|-<br />
|fields<br />
|string[]<br />
|нет<br />
|См. описание в <code>get_markers</code>. Применяется к маркерам внутри категорий при <code>level >= 2</code><br />
|}<br />
<br />
'''Вызов (<code>level=0</code>):'''<br />
get_diff(<br />
base_snapshot_id="72b3df7b-c15a-4e3d-8f92-a041dc6e5b87",<br />
head_snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
level=0<br />
)<br />
<br />
'''Ответ (<code>level=0</code>):'''<br />
{<br />
"stats": {<br />
"context1": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-20 ..."},<br />
"context2": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-25 ..."},<br />
"scope": ["NEW", "MISSING", "MATCHED", "MODIFIED"],<br />
"new": 9,<br />
"missing": 12,<br />
"modified": 98,<br />
"matched": 187<br />
}<br />
}<br />
<br />
'''Ответ (<code>level=2</code>)''' — каждая категория внутри <code>markers</code> оформляется и ограничивается независимо:<br />
{<br />
"stats": {"new": 50, "missing": 5, "modified": 0, "matched": 187},<br />
"markers": {<br />
"new_markers": {<br />
"total_count": 50,<br />
"returned_count": 20,<br />
"truncated": true,<br />
"markers": [<br />
{"id": "a3f21c90-...", "warnClass": "DEREF_AFTER_NULL.LOOP", "file": "...", "line": 3327, "msg": "...", "function": "select_query", "review": null}<br />
]<br />
},<br />
"missing_markers": {"total_count": 5, "returned_count": 5, "truncated": false, "markers": [...]},<br />
"modified_markers": {"total_count": 0, "returned_count": 0, "truncated": false, "markers": []},<br />
"matched_markers": {"total_count": 187, "returned_count": 20, "truncated": true, "markers": [...]}<br />
}<br />
}<br />
<br />
Если требуется полное содержимое категории, следует увеличить <code>limit</code>, либо запросить нужные идентификаторы отдельным вызовом <code>get_markers</code>. Маркеры внутри категорий проходят ту же компактную обработку, что и в <code>get_warnings</code>: значение <code>fields=["*"]</code> возвращает фиксированный набор полей коннектора, а не произвольные «сырые» поля API.<br />
----<br />
<br />
=== get_advanced_file_preview ===<br />
Фрагмент исходного кода из снимка вокруг указанной строки. Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно идентификатора снимка и пути к файлу.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|UUID снимка<br />
|-<br />
|file_path<br />
|string<br />
|да<br />
|Путь к файлу в том виде, в котором его возвращают <code>get_markers</code> и <code>get_warnings</code><br />
|-<br />
|line<br />
|int<br />
|нет<br />
|Центральная строка, нумерация с 1 (по умолчанию 1)<br />
|-<br />
|before<br />
|int<br />
|нет<br />
|Количество строк до центральной (по умолчанию 0)<br />
|-<br />
|after<br />
|int<br />
|нет<br />
|Количество строк после центральной (по умолчанию 99999 — до конца файла)<br />
|}<br />
<br />
'''Вызов:'''<br />
get_advanced_file_preview(<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
file_path="/.build/execute_cmd.c",<br />
line=3327,<br />
before=10,<br />
after=10<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"line": 3327,<br />
"content": " for (l = list; l && --reply; l = l->next)\n\t;\n return (l->word->word);\n",<br />
"total_lines": 6082<br />
}<br />
----<br />
<br />
=== get_project_groups ===<br />
Получить группу проектов по имени или UUID. Группы объединяют проекты в логические блоки — например, по команде или продукту.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|name_or_id<br />
|string<br />
|да<br />
|Имя группы или её UUID<br />
|}<br />
<br />
'''Вызов:'''<br />
get_project_groups(name_or_id="Linux Tools")<br />
<br />
'''Ответ:'''<br />
{<br />
"project_group_id": "c4f8a2d1-3b7e-4f90-82ac-1d5e8f2b6c04",<br />
"project_group_name": "Linux Tools",<br />
"projects": [<br />
{"id": "91630e84-db2f-4d8c-8716-68b7fdf17a66", "name": "bash"},<br />
{"id": "d3a17f52-...", "name": "coreutils"}<br />
]<br />
}<br />
<br />
<code>projects[].id</code> — это <code>project_id</code>, который далее передаётся в <code>get_snapshots</code>. Группы и проекты — разные сущности; идентификатор группы и идентификатор проекта не взаимозаменяемы.<br />
<br />
== Примеры сценариев ==<br />
Приведённые ниже запросы выполнены на демонстрационном стенде <code>svacer-demo.ispras.ru</code> с использованием OpenWebUI и модели <code>qwen3-coder:30b</code>. В любом другом MCP-клиенте с моделью достаточной мощности порядок вызовов будет аналогичным.<br />
<br />
=== Про объём ответа ===<br />
<code>get_markers</code>, <code>get_warnings</code> и <code>get_diff(level=2)</code> по умолчанию ограничивают объём ответа, чтобы не перегружать контекст модели:<br />
<br />
* <code>get_markers</code> и <code>get_warnings</code> — 30 маркеров по умолчанию. Если у <code>get_warnings</code> включены <code>traces</code>, <code>review_history</code> или <code>comment_history</code>, лимит снижается до 8, поскольку такие маркеры значительно объёмнее.<br />
* <code>get_diff(level=2)</code> — 20 маркеров на каждую категорию внутри <code>markers</code> (<code>new_markers</code>/<code>missing_markers</code>/<code>modified_markers</code>/<code>matched_markers</code>).<br />
<br />
В ответе присутствуют поля <code>total_count</code>, <code>returned_count</code>, <code>truncated</code>. При <code>truncated: true</code> есть два варианта действий: сузить фильтр (<code>severity</code>, <code>warnClass</code>, <code>file</code>) либо явно увеличить <code>limit</code> (значение <code>limit=0</code> полностью снимает ограничение).<br />
<br />
Поле <code>fields</code> определяет, какие ключи маркера возвращаются. По умолчанию применяется компактный набор <code>id, warnClass, file, line, msg, function, review</code> (а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены логическими флагами и пришли с сервера). Для полного маркера со всеми служебными ключами — <code>fields=["*"]</code>. Для произвольной выборки — список полей верхнего уровня, например <code>fields=["id","warnClass"]</code>. Поле <code>review</code> — объект <code>{status, severity, action}</code>; вложенные ключи в <code>fields</code> не поддерживаются, поэтому объект <code>review</code> запрашивается целиком.<br />
<br />
=== Перечислить все проекты ===<br />
<blockquote>Какие проекты есть в Svacer?</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>В Svacer доступно 6 проектов: bash, openssl, paho.mqtt.c, coturn, zstd, darpa. У каждого — одна ветка <code>master</code>.</blockquote><br />
<br />
=== Посмотреть снимки проекта ===<br />
<blockquote>Какие снимки есть у paho.mqtt.c? Самый свежий когда?</blockquote>'''Цепочка вызовов:'''<br />
<br />
# <code>get_projects()</code> — найти <code>project_id</code> и <code>branch_id</code><br />
# <code>get_snapshots(project_id=..., branch_id=...)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>У paho.mqtt.c 3 снимка. Самый свежий — «Snapshot 2020-03-25 09:09:41 +0300» (297 маркеров). Предыдущий — 20 марта (306 маркеров).</blockquote>Поле <code>commit_hash</code> может принимать значение <code>null</code>, если проект не сохраняет хэш коммита в <code>custom_properties</code>. Имена снимков произвольны: одни проекты записывают в имя дату, другие — коммит, третьи — свободный текст.<br />
<br />
=== Сводка по проекту ===<br />
<blockquote>Что в bash в последнем снимке? Сколько всего предупреждений, есть ли критические, какие топ-детекторы?</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
# <code>get_snapshots(project_id, branch_id)</code> — взять последний снимок<br />
# <code>get_project_stats(project_id, branch_id, snapshot_id)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>В последнем снимке bash содержится 771 предупреждение:<br />
<br />
* Критических: 1 (Confirmed)<br />
* Major: 1 (Won't fix)<br />
* Остальные: 769 (Unspecified — не размечались)<br />
<br />
Топ-детекторы по количеству:<br />
<br />
# <code>PROC_USE.VULNERABLE</code> — 337<br />
# <code>UNUSED_FUNC_RES.REWRITE.MINOR</code> — 44<br />
# <code>UNREACHABLE_CODE</code> — 28<br />
# <code>DEREF_AFTER_NULL.EX</code> — 27<br />
# <code>NULL_AFTER_DEREF</code> — 27<br />
</blockquote><br />
<br />
<code>Unspecified</code> в <code>by_severity</code> — маркеры без ручной разметки, а не «низкий приоритет». Поле <code>by_checker</code> не сортируется, на большом снимке оно может содержать более 100 ключей — чтобы получить именно топ-N, следует явно сформулировать запрос: «топ-5 детекторов».<br />
<br />
=== Тренд по нескольким снимкам ===<br />
<blockquote>Как у openssl менялось число предупреждений за последние пять снимков? Покажи таблицей.</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
<br />
# <code>get_projects()</code><br />
# <code>get_snapshots()</code> — взять список<br />
# <code>get_project_stats()</code> × 5 — по каждому из последних пяти снимков<br />
<br />
'''Ответ модели:'''<br />
<blockquote><br />
{| class="wikitable"<br />
|+<br />
!Снимок<br />
!Дата<br />
!Всего<br />
|-<br />
|2020-04-30 05:49<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 05:29<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 05:08<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 04:48<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 04:22<br />
|30.04.2020<br />
|1252<br />
|}<br />
</blockquote><br />
<br />
На демонстрационном стенде указанные пять снимков openssl импортированы с интервалом в 20 минут одного дня и полностью идентичны — поэтому динамика отсутствует. На реальном проекте с историей релизов значения будут изменяться.<br />
<br />
=== Найти срабатывания конкретного детектора ===<br />
<blockquote>Где в bash срабатывает PROC_USE.VULNERABLE? Покажи список — файл, строка, что именно ругается. Достаточно первых десяти.</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
# <code>get_snapshots()</code><br />
# <code>get_markers(warnClass=["PROC_USE.VULNERABLE"])</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote><br />
# <code>/.build/lib/sh/tmpfile.c:160</code> — <code>mktemp()</code>, race condition. Рекомендуется <code>mkstemp()</code>.<br />
# <code>/.build/lib/readline/shell.c:151</code> — <code>getenv()</code>, значение может быть подменено.<br />
# <code>/.build/shell.c:415</code> — <code>getenv()</code> в <code>main()</code>.<br />
# <code>/.build/lib/readline/complete.c:1516</code> — <code>getenv()</code>.<br />
# <code>/.build/lib/sh/eaccess.c:115</code> — <code>strcat()</code>, рекомендуется <code>strncat()</code>.<br />
</blockquote><br />
<br />
Фильтр <code>warnClass=["PROC_USE.VULNERABLE"]</code> охватывает все подклассы: <code>PROC_USE.VULNERABLE.TEMP</code>, <code>.GETENV</code>, <code>.STRCAT</code> и т. д. — всего 341 маркер. Несколько значений в одном параметре трактуются как логическое «ИЛИ»: <code>severity=["Critical","Major"]</code> возвращает маркеры обеих категорий.<br />
<br />
В ответе будет <code>total_count: 341, returned_count: 30, truncated: true</code> — это ожидаемое поведение. Модель видит общий объём по <code>total_count</code> и при необходимости сужает запрос или вызывает <code>get_markers(..., limit=0)</code>, чтобы получить полный список.<br />
<br />
=== Сравнить два снимка ===<br />
<blockquote>Возьми два последних снимка paho.mqtt.c — что между ними изменилось? Сколько новых предупреждений, сколько починили?</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
# <code>get_snapshots()</code> — два последних<br />
# <code>get_diff(base_snapshot_id="72b3df7b-...", head_snapshot_id="b42cb563-...", level=0)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>Между двумя последними снимками paho.mqtt.c:<br />
<br />
* Новых: 12<br />
* Удалённых: 13<br />
* Изменённых: 99<br />
* Совпадающих: 185<br />
<br />
Удалено несколько больше, чем добавлено — общая картина практически не изменилась.</blockquote><br />
<br />
Категория <code>modified</code> — маркер, присутствующий в обоих снимках, у которого изменилось окружение (номер строки, контекст функции). Это не новая ошибка. На больших проектах рекомендуется начинать с <code>level=0</code> для получения статистики, при необходимости использовать <code>level=1</code> (только идентификаторы маркеров) и затем точечно вызывать <code>get_markers</code> с нужными фильтрами.<br />
<br />
<code>level=2</code> возвращает полные маркеры по категориям, причём каждая категория по умолчанию ограничена 20 маркерами. Категории располагаются внутри <code>markers</code>: <code>new_markers</code>, <code>missing_markers</code>, <code>modified_markers</code>, <code>matched_markers</code>. Структура ответа в JSON: <code><nowiki>{"markers": {"new_markers": {"total_count": N, "returned_count": ..., "truncated": ..., "markers": [...]}, ...}}</nowiki></code>. Если требуется полное содержимое категории, следует увеличить <code>limit</code> или выполнить отдельный вызов <code>get_markers</code> по нужным идентификаторам.<br />
<br />
=== Разобрать конкретное предупреждение ===<br />
<blockquote>В bash есть один подтверждённый критикал — что-то про разыменование указателя. Покажи код вокруг этого места и объясни в чём проблема.</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code> → <code>get_snapshots()</code> — найти снимок bash<br />
# <code>get_markers(severity=["Critical"], review=["Confirmed"])</code><br />
# <code>get_advanced_file_preview(file_path="/.build/execute_cmd.c", line=3327, before=10, after=10)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>Маркер <code>DEREF_AFTER_NULL.LOOP</code> в функции <code>select_query()</code>, строка 3327:<br />
<code>for (l = list; l && --reply; l = l->next)<br />
<br />
;<br />
<br />
return (l->word->word); /* l может быть NULL после выхода из цикла */</code><br />
<br />
Если список заканчивается раньше, чем <code>reply</code> обнуляется, <code>l</code> станет <code>NULL</code> на последнем <code>l->next</code>, и следующий <code>l->word->word</code> — разыменование нулевого указателя.</blockquote><code>file_path</code> должен точно совпадать со значением, возвращённым маркером, включая ведущий префикс <code>/.build/...</code>. Это путь внутри сборочной директории Svacer, а не путь в исходном репозитории; соответствие в репозитории определяется по имени файла.<br />
<br />
Для одиночной разметки удобно сразу запрашивать полный маркер с трассами: <code>get_markers(..., severity=["Critical"], review=["Confirmed"], traces=True, checker_info=True)</code>. Флаги <code>traces</code> и <code>checker_info</code> указывают серверу включить соответствующие поля в ответ; в выдаче они сохраняются и при значении <code>fields</code> по умолчанию. Значение <code>fields=["*"]</code> требуется лишь в том случае, когда дополнительно нужны <code>tool</code> и <code>mtid</code> — служебные ключи, исключённые из компактного набора.</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_MCP&diff=3568Help:13-alpha MCP2026-05-26T08:49:46Z<p>M.vinogradov: </p>
<hr />
<div>== Архитектура ==<br />
[https://modelcontextprotocol.io/docs/getting-started/intro MCP] — открытый стандарт, через который LLM-клиенты (Claude Desktop, Cursor, VS Code, OpenWebUI и др.) вызывают внешние инструменты. <br />
Svacer MCP соединяет одно с другим: 8 инструментов поверх публичного REST API Svacer, которые LLM выбирает и вызывает в ответ на обычный текстовый запрос. Вместо ручной последовательности «открыть UI, найти проект, выбрать снимок, применить фильтр» достаточно сформулировать вопрос в чате, например, «сколько критических предупреждений в последнем снимке bash?», и получить ответ. Необходимые вызовы инструментов модель выполняет самостоятельно.<br />
<br />
[[File:Архитектура MCP.png|thumb|none|x800px|alt=architectureMCP|Архитектура MCP-сервера]]<br />
<br />
Поток запроса: LLM-клиент отправляет MCP-вызов через STDIO или Streamable HTTP → <code>server.py</code> передаёт его в выбранный инструмент из <code>tools/</code> → инструмент проверяет параметры и обращается к <code>api_client.py</code> → клиент получает JWT от <code>auth.py</code> (модуль автоматически обновляет токен по истечении срока действия или при ответе 401) → запрос отправляется в Svacer REST API.<br />
<br />
{{Note|text=Поддержка MCP включена в [[Help:13-alpha introduction|демонстрационный релиз]], который может быть развёрнут с помощью docker compose [[Help:13-alpha deploy|согласно инструкции]]}}<br />
<br />
== Установка ==<br />
Установка Svacer MCP, подключение клиентов и конфигурация.<br />
<br />
=== Требования ===<br />
<br />
* Python 3.10+<br />
* Доступ к серверу Svacer: URL + логин/пароль<br />
<br />
=== Режим STDIO ===<br />
Подходит для настольных клиентов: Claude Desktop, Claude Code, Cursor, VS Code.<br />
git clone <nowiki>https://gitlab.ispras.ru/svacerai/mcp.git</nowiki> && cd mcp<br />
<br />
python3 -m venv .venv<br />
.venv/bin/pip install -e .<br />
<br />
cp .env.example .env<br />
# Отредактировать .env — указать URL и учётные данные Svacer<br />
<br />
# Проверить запуск (сервер ожидает данные на stdin; для выхода — Ctrl+C)<br />
.venv/bin/svacer-mcp<br />
<br />
После <code>pip install -e .</code> в окружении становится доступна команда <code>svacer-mcp</code> — её указывают в конфигурации клиентов ниже.<br />
<br />
=== Режим HTTP (Docker) ===<br />
Подходит для веб-клиентов (OpenWebUI) и удалённого доступа.<br />
<br />
'''Требования:''' Docker, Docker Compose.<br />
cp .env.example .env<br />
<br />
# В .env обязательно задать SVACER_MCP_TOKEN — без него сервер не запускается<br />
echo "SVACER_MCP_TOKEN=$(openssl rand -hex 32)" >> .env<br />
<br />
docker compose up -d<br />
<br />
# MCP endpoint: <nowiki>http://localhost:8002/mcp</nowiki><br />
# Клиенты передают заголовок: Authorization: Bearer <SVACER_MCP_TOKEN><br />
<br />
Внешний порт хоста задаётся переменной <code>MCP_PORT</code> (по умолчанию <code>8002</code>), внутри контейнера сервер всегда слушает порт <code>8000</code>.<br />
<br />
=== Подключение клиентов ===<br />
<br />
==== Claude Desktop ====<br />
Файл конфигурации: <code>~/.config/Claude/claude_desktop_config.json</code> (Linux) или <code>%APPDATA%\Claude\claude_desktop_config.json</code> (Windows).<br />
<br />
Укажите '''абсолютный путь''' к <code>svacer-mcp</code> из вашего venv (<code>which svacer-mcp</code> в активированном venv или <code>/path/to/mcp/.venv/bin/svacer-mcp</code>).<br />
<br />
{<br />
"mcpServers": {<br />
"svacer": {<br />
"command": "/path/to/mcp/.venv/bin/svacer-mcp",<br />
"env": {<br />
"SVACER_URL": "<nowiki>https://your-svacer.example.com</nowiki>",<br />
"SVACER_LOGIN": "your-login",<br />
"SVACER_PASSWORD": "your-password"<br />
}<br />
}<br />
}<br />
}<br />
<br />
==== Claude Code ====<br />
claude mcp add svacer \<br />
-e SVACER_URL=<nowiki>https://your-svacer.example.com</nowiki> \<br />
-e SVACER_LOGIN=your-login \<br />
-e SVACER_PASSWORD=your-password \<br />
-- /path/to/mcp/.venv/bin/svacer-mcp<br />
<br />
==== VS Code ====<br />
Файл <code>.vscode/mcp.json</code> в корне рабочей директории:<br />
<br />
{<br />
"servers": {<br />
"svacer": {<br />
"type": "stdio",<br />
"command": "/path/to/mcp/.venv/bin/svacer-mcp",<br />
"env": {<br />
"SVACER_URL": "<nowiki>https://your-svacer.example.com</nowiki>",<br />
"SVACER_LOGIN": "your-login",<br />
"SVACER_PASSWORD": "your-password"<br />
}<br />
}<br />
}<br />
}<br />
<br />
==== Cursor ====<br />
Файл <code>.cursor/mcp.json</code> в корне проекта или глобально:<br />
<br />
{<br />
"mcpServers": {<br />
"svacer": {<br />
"command": "/path/to/mcp/.venv/bin/svacer-mcp",<br />
"env": {<br />
"SVACER_URL": "<nowiki>https://your-svacer.example.com</nowiki>",<br />
"SVACER_LOGIN": "your-login",<br />
"SVACER_PASSWORD": "your-password"<br />
}<br />
}<br />
}<br />
}<br />
<br />
==== OpenWebUI ====<br />
# Развернуть через Docker (см. [[#Режим HTTP (Docker)|Режим HTTP]]).<br />
# Открыть '''Settings → Tools''' (или '''Admin Panel → Settings → Tools''').<br />
# Добавить сервер:<br />
#* <code><nowiki>http://localhost:8002/mcp</nowiki></code> — если OpenWebUI работает на хосте, снаружи Docker.<br />
#* <code><nowiki>http://svacer-mcp:8000/mcp</nowiki></code> — если OpenWebUI развёрнут в той же compose-сети, что и <code>svacer-mcp</code> (имя берётся из <code>docker-compose.yml</code> → service name, порт 8000 — внутренний порт контейнера).<br />
# Тип подключения: '''MCP (Streamable HTTP)'''.<br />
# В настройках инструмента указать заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code> (значение — то же, что в <code>.env</code> сервера).<br />
# Сохранить — инструменты появятся в чате.<br />
<br />
=== Конфигурация ===<br />
{| class="wikitable"<br />
!Переменная<br />
!По умолчанию<br />
!Описание<br />
|-<br />
|SVACER_URL<br />
|<nowiki>https://svacer-demo.ispras.ru</nowiki><br />
|URL сервера Svacer<br />
|-<br />
|SVACER_LOGIN<br />
|admin<br />
|Логин<br />
|-<br />
|SVACER_PASSWORD<br />
|admin<br />
|Пароль<br />
|-<br />
|SVACER_TIMEOUT<br />
|30<br />
|Тайм-аут HTTP-запросов к Svacer, секунды<br />
|-<br />
|SVACER_TRANSPORT<br />
|stdio<br />
|Режим транспорта: <code>stdio</code> или <code>http</code><br />
|-<br />
|SVACER_HTTP_PORT<br />
|8000<br />
|TCP-порт сервера в режиме HTTP (внутри контейнера)<br />
|-<br />
|SVACER_MCP_TOKEN<br />
|''(не задано)''<br />
|Bearer-токен для клиентов <code>/mcp</code>. Обязателен при <code>SVACER_TRANSPORT=http</code>, в режиме STDIO игнорируется. Генерация: <code>openssl rand -hex 32</code><br />
|-<br />
|SVACER_MCP_RESOURCE_URL<br />
|<nowiki>http://localhost</nowiki>:<HTTP_PORT><br />
|Публичный URL MCP-сервера для заголовка <code>WWW-Authenticate</code> (<nowiki>RFC 9728</nowiki>). Задаётся при работе за обратным прокси<br />
|-<br />
|SVACER_TOOLS<br />
|''(не задано)''<br />
|Список инструментов через запятую. Если не задано, регистрируются все 8<br />
|-<br />
|MCP_PORT<br />
|8002<br />
|Внешний порт хоста при запуске через <code>docker compose</code> (отображается на внутренний <code>SVACER_HTTP_PORT</code>)<br />
|}<br />
Переменные читаются из <code>.env</code> или из окружения. Для STDIO-клиентов их можно указать в секции <code>env</code> конфигурации клиента.<br />
<br />
==== Ограничение набора инструментов ====<br />
Чтобы запустить сервер с подмножеством инструментов (например, для уменьшения объёма контекста у модели или разграничения доступа), задайте <code>SVACER_TOOLS</code>:<br />
SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
Допустимые имена: <code>get_projects</code>, <code>get_snapshots</code>, <code>get_warnings</code>, <code>get_markers</code>, <code>get_project_stats</code>, <code>get_project_groups</code>, <code>get_advanced_file_preview</code>, <code>get_diff</code>. Неизвестное имя в списке приводит к ошибке при запуске. Если переменная пустая или не задана, регистрируются все 8 инструментов.<br />
<br />
==== Несколько экземпляров сервера ====<br />
Параллельный запуск нескольких MCP-серверов поддерживается без ограничений.<br />
<br />
* В режиме STDIO каждая запись в конфигурации клиента описывает отдельный процесс — несколько подключений к разным экземплярам Svacer задаются простым перечислением.<br />
* В режиме HTTP запускаются независимые контейнеры на разных хост-портах: например, <code>MCP_PORT=8002</code> для одного экземпляра и <code>MCP_PORT=8003</code> для другого. Для каждого контейнера задаётся собственный <code>SVACER_MCP_TOKEN</code>.<br />
<br />
=== Безопасность ===<br />
<br />
* '''STDIO''': сервер не открывает сетевых портов и обменивается данными через стандартные потоки ввода/вывода процесса.<br />
* '''Streamable HTTP''': эндпоинт <code>/mcp</code> требует заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code>. Запросы без токена или с неверным значением получают ответ <code>401</code> и заголовок <code>WWW-Authenticate: Bearer ...</code>. Токен является разделяемым секретом и не заменяет TLS, а дополняет его: при работе за обратным прокси необходимо использовать HTTPS, а сам токен передавать только по защищённому каналу.<br />
* Без <code>SVACER_MCP_TOKEN</code> HTTP-сервер не запускается.<br />
* Учётные данные <code>admin/admin</code> предназначены только для тестового стенда. В рабочем окружении необходимо задать собственные логин и пароль через переменные окружения.<br />
* Файл <code>.env</code> не должен добавляться в систему контроля версий.<br />
<br />
==== Передача токена клиентом ====<br />
Большинство HTTP-клиентов MCP (OpenWebUI и др.) позволяют задать произвольный заголовок <code>Authorization</code> в настройках инструмента — указывается значение <code>Bearer <токен></code>. Для ручной проверки:<br />
curl -H "Authorization: Bearer $SVACER_MCP_TOKEN" \<br />
<nowiki> </nowiki> -H 'Content-Type: application/json' \<br />
<nowiki> </nowiki> -H 'Accept: application/json, text/event-stream' \<br />
<nowiki> </nowiki> -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \<br />
<nowiki> </nowiki> <nowiki>http://localhost:8002/mcp</nowiki><br />
<br />
== Инструменты ==<br />
Справочник по 8 инструментам Svacer MCP. Типичный порядок вызовов: <code>get_projects</code> → <code>get_snapshots</code> → любой из аналитических инструментов.<br />
{| class="wikitable"<br />
!Инструмент<br />
!Назначение<br />
|-<br />
|get_projects<br />
|Список проектов с ветками — точка входа<br />
|-<br />
|get_snapshots<br />
|Снимки конкретной ветки, от нового к старому<br />
|-<br />
|get_project_stats<br />
|Агрегированные метрики снимка: severity / review / checker<br />
|-<br />
|get_markers<br />
|Компактный список маркеров с серверной фильтрацией<br />
|-<br />
|get_warnings<br />
|Полные предупреждения с трассами и историей разметки<br />
|-<br />
|get_diff<br />
|Сравнение двух снимков: new / missing / modified / matched<br />
|-<br />
|get_advanced_file_preview<br />
|Фрагмент исходного кода вокруг строки<br />
|-<br />
|get_project_groups<br />
|Группа проектов по имени или UUID<br />
|}<br />
<br />
=== get_projects ===<br />
Список всех проектов с ветками. Точка входа: с этого вызова начинается практически любой сценарий — он возвращает <code>project_id</code> и <code>branch_id</code>, необходимые для последующих запросов.<br />
<br />
'''Параметров нет.'''<br />
<br />
'''Вызов:'''<br />
get_projects()<br />
<br />
'''Ответ:'''<br />
[<br />
{<br />
"project_id": "91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
"project_name": "bash",<br />
"created": "2021-12-13T13:22:42.122456Z",<br />
"created_by": "admin",<br />
"branches": [<br />
{<br />
"branch_id": "77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
"branch_name": "master",<br />
"created": "2021-12-13T13:22:42.394812Z"<br />
}<br />
]<br />
}<br />
]<br />
----<br />
<br />
=== get_snapshots ===<br />
Список снимков для конкретной ветки проекта, от нового к старому.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|name_filter<br />
|string<br />
|нет<br />
|Подстрока или regex для фильтра по имени снимка<br />
|}<br />
<br />
'''Вызов:'''<br />
get_snapshots(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4"<br />
)<br />
<br />
'''Ответ:'''<br />
[<br />
{<br />
"snapshot_id": "b42cb563-86f4-4f96-900a-7782163327c9",<br />
"name": "Snapshot 2020-03-25 09:09:41 +0300",<br />
"import_time": "2020-03-25T09:09:41.837296Z",<br />
"commit_hash": null,<br />
"markers_count": 297,<br />
"link": "<nowiki>https://svacer-demo.ispras.ru/</nowiki>..."<br />
}<br />
]<br />
----<br />
<br />
=== get_project_stats ===<br />
Агрегированные метрики по снимку: общее количество предупреждений, распределение по критичности, по статусу разметки, по детекторам. Наиболее быстрый способ получить общую картину по проекту.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_snapshots</code><br />
|}<br />
<br />
'''Вызов:'''<br />
get_project_stats(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9"<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"total_warnings": 771,<br />
"by_severity": {<br />
"Critical": 1,<br />
"Major": 1,<br />
"Unspecified": 769<br />
},<br />
"by_review_status": {<br />
"Confirmed": 1,<br />
"False Positive": 1,<br />
"Undecided": 767,<br />
"Unclear": 1,<br />
"Won't fix": 1<br />
},<br />
"by_checker": {<br />
"PROC_USE.VULNERABLE": 337,<br />
"UNUSED_FUNC_RES.REWRITE.MINOR": 44,<br />
"UNREACHABLE_CODE": 28,<br />
"DEREF_AFTER_NULL.EX": 27,<br />
"NULL_AFTER_DEREF": 27<br />
}<br />
}<br />
----<br />
<br />
=== get_markers ===<br />
Компактный список маркеров с серверной фильтрацией. Основной инструмент для перечисления и обзора: его следует предпочитать <code>get_warnings</code>, когда не требуются развёрнутые поля — трассы и история разметки.<br />
<br />
По умолчанию ответ ограничен 30 маркерами и содержит компактный набор полей. Подробнее об ограничении объёма см. раздел [[#Про объём ответа|Про объём ответа]].<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_snapshots</code><br />
|-<br />
|severity<br />
|string[]<br />
|нет<br />
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code> применяется на стороне коннектора<br />
|-<br />
|review<br />
|string[]<br />
|нет<br />
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code><br />
|-<br />
|warnClass<br />
|string[]<br />
|нет<br />
|Идентификатор детектора (<code>DEREF_AFTER_NULL</code>, …)<br />
|-<br />
|file<br />
|string[]<br />
|нет<br />
|Подстрока пути к файлу<br />
|-<br />
|traces<br />
|bool<br />
|нет<br />
|Включить трассы маркеров<br />
|-<br />
|checker_info<br />
|bool<br />
|нет<br />
|Включить метаданные детектора (CWE, описание)<br />
|-<br />
|review_history<br />
|bool<br />
|нет<br />
|Включить историю изменений разметки<br />
|-<br />
|comment_history<br />
|bool<br />
|нет<br />
|Включить комментарии к маркеру<br />
|-<br />
|custom_filter<br />
|string<br />
|нет<br />
|Имя или идентификатор сохранённого фильтра из веб-интерфейса Svacer<br />
|-<br />
|limit<br />
|int<br />
|нет<br />
|Максимальное количество маркеров в ответе (по умолчанию 30). Значение 0 снимает ограничение<br />
|-<br />
|fields<br />
|string[]<br />
|нет<br />
|Список разрешённых полей маркера верхнего уровня. По умолчанию — компактный набор <code>id, warnClass, file, line, msg, function, review</code>. Значение <code>["*"]</code> возвращает все поля коннектора (<code>id, warnClass, file, line, msg, tool, function, mtid, review</code>, а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены). Допустим и произвольный список, например <code>["id","warnClass"]</code><br />
|}<br />
<br />
'''Вызов:'''<br />
get_markers(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
warnClass=["PROC_USE.VULNERABLE"]<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"total_count": 341,<br />
"returned_count": 30,<br />
"truncated": true,<br />
"filters_applied": {"warnClass": ["PROC_USE.VULNERABLE"]},<br />
"markers": [<br />
{<br />
"id": "e05bb35b-a95e-4eb2-85ae-3101b788f07d",<br />
"warnClass": "PROC_USE.VULNERABLE.TEMP",<br />
"file": "/.build/lib/sh/tmpfile.c",<br />
"line": 160,<br />
"msg": "Use of vulnerable function 'mktemp' at tmpfile.c:160. ...",<br />
"function": "sh_mktmpname",<br />
"review": null<br />
}<br />
]<br />
}<br />
<br />
<code>total_count</code> отражает количество маркеров, удовлетворяющих фильтру до применения ограничения; <code>returned_count</code> — количество маркеров, фактически содержащихся в <code>markers</code>. При <code>truncated: true</code> следует либо сузить фильтры (<code>severity</code>, <code>warnClass</code>, <code>file</code>), либо передать <code>limit=0</code> для получения полного списка. Поля <code>tool</code> и <code>mtid</code> возвращаются только при <code>fields=["*"]</code>.<br />
----<br />
<br />
=== get_warnings ===<br />
Полные предупреждения с детальной разметкой. Ответ значительно объёмнее, чем у <code>get_markers</code>, поэтому инструмент следует использовать только тогда, когда нужны поля, отсутствующие в компактной форме: <code>traces</code>, <code>review_history</code>, <code>checker_info</code>, <code>comment_history</code>.<br />
<br />
Лимит по умолчанию — 30; при включённых <code>traces</code>, <code>review_history</code> или <code>comment_history</code> он автоматически снижается до 8, поскольку такие предупреждения существенно объёмнее.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_snapshots</code><br />
|-<br />
|severity<br />
|string[]<br />
|нет<br />
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code>, применяется на стороне коннектора<br />
|-<br />
|review<br />
|string[]<br />
|нет<br />
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code><br />
|-<br />
|warnClass<br />
|string[]<br />
|нет<br />
|Идентификатор детектора<br />
|-<br />
|file<br />
|string[]<br />
|нет<br />
|Подстрока пути к файлу<br />
|-<br />
|traces<br />
|bool<br />
|нет<br />
|Включить трассы. Активирует режим расширенных полей (лимит по умолчанию — 8)<br />
|-<br />
|checker_info<br />
|bool<br />
|нет<br />
|Включить метаданные детектора (CWE, описание)<br />
|-<br />
|review_history<br />
|bool<br />
|нет<br />
|Включить историю разметки. Режим расширенных полей<br />
|-<br />
|comment_history<br />
|bool<br />
|нет<br />
|Включить комментарии. Режим расширенных полей<br />
|-<br />
|custom_filter<br />
|string<br />
|нет<br />
|Имя или идентификатор сохранённого фильтра<br />
|-<br />
|limit<br />
|int<br />
|нет<br />
|Максимальное количество предупреждений в ответе. По умолчанию — 30, в режиме расширенных полей — 8. Значение 0 снимает ограничение. Явно заданное <code>limit</code> отменяет автоматическое снижение<br />
|-<br />
|fields<br />
|string[]<br />
|нет<br />
|См. описание в <code>get_markers</code><br />
|}<br />
'''Вызов:'''<br />
get_warnings(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
severity=["Critical"],<br />
review_history=True,<br />
traces=True<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"total_count": 1,<br />
"returned_count": 1,<br />
"truncated": false,<br />
"filters_applied": {"severity": ["Critical"], "traces": true, "review_history": true},<br />
"warnings": [<br />
{<br />
"id": "a3f21c90-1d4e-4b82-9f63-7c8e5d2a1b09",<br />
"warnClass": "DEREF_AFTER_NULL.LOOP",<br />
"file": "/.build/execute_cmd.c",<br />
"line": 3327,<br />
"msg": "Possible null pointer dereference of 'l' after loop exit.",<br />
"function": "select_query",<br />
"review": {"status": "Confirmed", "severity": "Critical"},<br />
"review_history": [{"status": "Confirmed", "changed_by": "admin", "changed_at": "2021-12-13T14:00:00Z"}],<br />
"traces": [{"file": "/.build/execute_cmd.c", "line": 3320, "msg": "Loop starts here; 'l' may exhaust the list."}]<br />
}<br />
]<br />
}<br />
----<br />
<br />
=== get_diff ===<br />
Сравнение двух снимков. Категории располагаются под ключом <code>markers</code>: <code>new_markers</code> (появилось в новом снимке), <code>missing_markers</code> (исчезло из нового), <code>modified_markers</code> (тот же идентификатор, изменился контекст), <code>matched_markers</code> (совпало в обоих). Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно UUID снимков.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|base_snapshot_id<br />
|string (UUID)<br />
|да<br />
|Старый снимок<br />
|-<br />
|head_snapshot_id<br />
|string (UUID)<br />
|нет<br />
|Новый снимок; если не указан, сравнение выполняется с предыдущим по времени<br />
|-<br />
|level<br />
|int<br />
|нет<br />
|0 — только статистика; 1 — статистика и идентификаторы маркеров; 2 — полные маркеры по категориям<br />
|-<br />
|checker_info<br />
|bool<br />
|нет<br />
|Метаданные детекторов для маркеров (только при <code>level >= 2</code>)<br />
|-<br />
|limit<br />
|int<br />
|нет<br />
|Максимальное количество маркеров '''на каждую категорию''' при <code>level >= 2</code>. По умолчанию — 20, значение 0 снимает ограничение. Параметр игнорируется при <code>level < 2</code><br />
|-<br />
|fields<br />
|string[]<br />
|нет<br />
|См. описание в <code>get_markers</code>. Применяется к маркерам внутри категорий при <code>level >= 2</code><br />
|}<br />
<br />
'''Вызов (<code>level=0</code>):'''<br />
get_diff(<br />
base_snapshot_id="72b3df7b-c15a-4e3d-8f92-a041dc6e5b87",<br />
head_snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
level=0<br />
)<br />
<br />
'''Ответ (<code>level=0</code>):'''<br />
{<br />
"stats": {<br />
"context1": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-20 ..."},<br />
"context2": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-25 ..."},<br />
"scope": ["NEW", "MISSING", "MATCHED", "MODIFIED"],<br />
"new": 9,<br />
"missing": 12,<br />
"modified": 98,<br />
"matched": 187<br />
}<br />
}<br />
<br />
'''Ответ (<code>level=2</code>)''' — каждая категория внутри <code>markers</code> оформляется и ограничивается независимо:<br />
{<br />
"stats": {"new": 50, "missing": 5, "modified": 0, "matched": 187},<br />
"markers": {<br />
"new_markers": {<br />
"total_count": 50,<br />
"returned_count": 20,<br />
"truncated": true,<br />
"markers": [<br />
{"id": "a3f21c90-...", "warnClass": "DEREF_AFTER_NULL.LOOP", "file": "...", "line": 3327, "msg": "...", "function": "select_query", "review": null}<br />
]<br />
},<br />
"missing_markers": {"total_count": 5, "returned_count": 5, "truncated": false, "markers": [...]},<br />
"modified_markers": {"total_count": 0, "returned_count": 0, "truncated": false, "markers": []},<br />
"matched_markers": {"total_count": 187, "returned_count": 20, "truncated": true, "markers": [...]}<br />
}<br />
}<br />
<br />
Если требуется полное содержимое категории, следует увеличить <code>limit</code>, либо запросить нужные идентификаторы отдельным вызовом <code>get_markers</code>. Маркеры внутри категорий проходят ту же компактную обработку, что и в <code>get_warnings</code>: значение <code>fields=["*"]</code> возвращает фиксированный набор полей коннектора, а не произвольные «сырые» поля API.<br />
----<br />
<br />
=== get_advanced_file_preview ===<br />
Фрагмент исходного кода из снимка вокруг указанной строки. Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно идентификатора снимка и пути к файлу.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|UUID снимка<br />
|-<br />
|file_path<br />
|string<br />
|да<br />
|Путь к файлу в том виде, в котором его возвращают <code>get_markers</code> и <code>get_warnings</code><br />
|-<br />
|line<br />
|int<br />
|нет<br />
|Центральная строка, нумерация с 1 (по умолчанию 1)<br />
|-<br />
|before<br />
|int<br />
|нет<br />
|Количество строк до центральной (по умолчанию 0)<br />
|-<br />
|after<br />
|int<br />
|нет<br />
|Количество строк после центральной (по умолчанию 99999 — до конца файла)<br />
|}<br />
<br />
'''Вызов:'''<br />
get_advanced_file_preview(<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
file_path="/.build/execute_cmd.c",<br />
line=3327,<br />
before=10,<br />
after=10<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"line": 3327,<br />
"content": " for (l = list; l && --reply; l = l->next)\n\t;\n return (l->word->word);\n",<br />
"total_lines": 6082<br />
}<br />
----<br />
<br />
=== get_project_groups ===<br />
Получить группу проектов по имени или UUID. Группы объединяют проекты в логические блоки — например, по команде или продукту.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|name_or_id<br />
|string<br />
|да<br />
|Имя группы или её UUID<br />
|}<br />
<br />
'''Вызов:'''<br />
get_project_groups(name_or_id="Linux Tools")<br />
<br />
'''Ответ:'''<br />
{<br />
"project_group_id": "c4f8a2d1-3b7e-4f90-82ac-1d5e8f2b6c04",<br />
"project_group_name": "Linux Tools",<br />
"projects": [<br />
{"id": "91630e84-db2f-4d8c-8716-68b7fdf17a66", "name": "bash"},<br />
{"id": "d3a17f52-...", "name": "coreutils"}<br />
]<br />
}<br />
<br />
<code>projects[].id</code> — это <code>project_id</code>, который далее передаётся в <code>get_snapshots</code>. Группы и проекты — разные сущности; идентификатор группы и идентификатор проекта не взаимозаменяемы.<br />
<br />
== Примеры сценариев ==<br />
Приведённые ниже запросы выполнены на демонстрационном стенде <code>svacer-demo.ispras.ru</code> с использованием OpenWebUI и модели <code>qwen3-coder:30b</code>. В любом другом MCP-клиенте с моделью достаточной мощности порядок вызовов будет аналогичным.<br />
<br />
=== Про объём ответа ===<br />
<code>get_markers</code>, <code>get_warnings</code> и <code>get_diff(level=2)</code> по умолчанию ограничивают объём ответа, чтобы не перегружать контекст модели:<br />
<br />
* <code>get_markers</code> и <code>get_warnings</code> — 30 маркеров по умолчанию. Если у <code>get_warnings</code> включены <code>traces</code>, <code>review_history</code> или <code>comment_history</code>, лимит снижается до 8, поскольку такие маркеры значительно объёмнее.<br />
* <code>get_diff(level=2)</code> — 20 маркеров на каждую категорию внутри <code>markers</code> (<code>new_markers</code>/<code>missing_markers</code>/<code>modified_markers</code>/<code>matched_markers</code>).<br />
<br />
В ответе присутствуют поля <code>total_count</code>, <code>returned_count</code>, <code>truncated</code>. При <code>truncated: true</code> есть два варианта действий: сузить фильтр (<code>severity</code>, <code>warnClass</code>, <code>file</code>) либо явно увеличить <code>limit</code> (значение <code>limit=0</code> полностью снимает ограничение).<br />
<br />
Поле <code>fields</code> определяет, какие ключи маркера возвращаются. По умолчанию применяется компактный набор <code>id, warnClass, file, line, msg, function, review</code> (а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены логическими флагами и пришли с сервера). Для полного маркера со всеми служебными ключами — <code>fields=["*"]</code>. Для произвольной выборки — список полей верхнего уровня, например <code>fields=["id","warnClass"]</code>. Поле <code>review</code> — объект <code>{status, severity, action}</code>; вложенные ключи в <code>fields</code> не поддерживаются, поэтому объект <code>review</code> запрашивается целиком.<br />
<br />
=== Перечислить все проекты ===<br />
<blockquote>Какие проекты есть в Svacer?</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>В Svacer доступно 6 проектов: bash, openssl, paho.mqtt.c, coturn, zstd, darpa. У каждого — одна ветка <code>master</code>.</blockquote><br />
<br />
=== Посмотреть снимки проекта ===<br />
<blockquote>Какие снимки есть у paho.mqtt.c? Самый свежий когда?</blockquote>'''Цепочка вызовов:'''<br />
<br />
# <code>get_projects()</code> — найти <code>project_id</code> и <code>branch_id</code><br />
# <code>get_snapshots(project_id=..., branch_id=...)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>У paho.mqtt.c 3 снимка. Самый свежий — «Snapshot 2020-03-25 09:09:41 +0300» (297 маркеров). Предыдущий — 20 марта (306 маркеров).</blockquote>Поле <code>commit_hash</code> может принимать значение <code>null</code>, если проект не сохраняет хэш коммита в <code>custom_properties</code>. Имена снимков произвольны: одни проекты записывают в имя дату, другие — коммит, третьи — свободный текст.<br />
<br />
=== Сводка по проекту ===<br />
<blockquote>Что в bash в последнем снимке? Сколько всего предупреждений, есть ли критические, какие топ-детекторы?</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
# <code>get_snapshots(project_id, branch_id)</code> — взять последний снимок<br />
# <code>get_project_stats(project_id, branch_id, snapshot_id)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>В последнем снимке bash содержится 771 предупреждение:<br />
<br />
* Критических: 1 (Confirmed)<br />
* Major: 1 (Won't fix)<br />
* Остальные: 769 (Unspecified — не размечались)<br />
<br />
Топ-детекторы по количеству:<br />
<br />
# <code>PROC_USE.VULNERABLE</code> — 337<br />
# <code>UNUSED_FUNC_RES.REWRITE.MINOR</code> — 44<br />
# <code>UNREACHABLE_CODE</code> — 28<br />
# <code>DEREF_AFTER_NULL.EX</code> — 27<br />
# <code>NULL_AFTER_DEREF</code> — 27<br />
</blockquote><br />
<br />
<code>Unspecified</code> в <code>by_severity</code> — маркеры без ручной разметки, а не «низкий приоритет». Поле <code>by_checker</code> не сортируется, на большом снимке оно может содержать более 100 ключей — чтобы получить именно топ-N, следует явно сформулировать запрос: «топ-5 детекторов».<br />
<br />
=== Тренд по нескольким снимкам ===<br />
<blockquote>Как у openssl менялось число предупреждений за последние пять снимков? Покажи таблицей.</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
<br />
# <code>get_projects()</code><br />
# <code>get_snapshots()</code> — взять список<br />
# <code>get_project_stats()</code> × 5 — по каждому из последних пяти снимков<br />
<br />
'''Ответ модели:'''<br />
<blockquote><br />
{| class="wikitable"<br />
|+<br />
!Снимок<br />
!Дата<br />
!Всего<br />
|-<br />
|2020-04-30 05:49<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 05:29<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 05:08<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 04:48<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 04:22<br />
|30.04.2020<br />
|1252<br />
|}<br />
</blockquote><br />
<br />
На демонстрационном стенде указанные пять снимков openssl импортированы с интервалом в 20 минут одного дня и полностью идентичны — поэтому динамика отсутствует. На реальном проекте с историей релизов значения будут изменяться.<br />
<br />
=== Найти срабатывания конкретного детектора ===<br />
<blockquote>Где в bash срабатывает PROC_USE.VULNERABLE? Покажи список — файл, строка, что именно ругается. Достаточно первых десяти.</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
# <code>get_snapshots()</code><br />
# <code>get_markers(warnClass=["PROC_USE.VULNERABLE"])</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote><br />
# <code>/.build/lib/sh/tmpfile.c:160</code> — <code>mktemp()</code>, race condition. Рекомендуется <code>mkstemp()</code>.<br />
# <code>/.build/lib/readline/shell.c:151</code> — <code>getenv()</code>, значение может быть подменено.<br />
# <code>/.build/shell.c:415</code> — <code>getenv()</code> в <code>main()</code>.<br />
# <code>/.build/lib/readline/complete.c:1516</code> — <code>getenv()</code>.<br />
# <code>/.build/lib/sh/eaccess.c:115</code> — <code>strcat()</code>, рекомендуется <code>strncat()</code>.<br />
</blockquote><br />
<br />
Фильтр <code>warnClass=["PROC_USE.VULNERABLE"]</code> охватывает все подклассы: <code>PROC_USE.VULNERABLE.TEMP</code>, <code>.GETENV</code>, <code>.STRCAT</code> и т. д. — всего 341 маркер. Несколько значений в одном параметре трактуются как логическое «ИЛИ»: <code>severity=["Critical","Major"]</code> возвращает маркеры обеих категорий.<br />
<br />
В ответе будет <code>total_count: 341, returned_count: 30, truncated: true</code> — это ожидаемое поведение. Модель видит общий объём по <code>total_count</code> и при необходимости сужает запрос или вызывает <code>get_markers(..., limit=0)</code>, чтобы получить полный список.<br />
<br />
=== Сравнить два снимка ===<br />
<blockquote>Возьми два последних снимка paho.mqtt.c — что между ними изменилось? Сколько новых предупреждений, сколько починили?</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
# <code>get_snapshots()</code> — два последних<br />
# <code>get_diff(base_snapshot_id="72b3df7b-...", head_snapshot_id="b42cb563-...", level=0)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>Между двумя последними снимками paho.mqtt.c:<br />
<br />
* Новых: 12<br />
* Удалённых: 13<br />
* Изменённых: 99<br />
* Совпадающих: 185<br />
<br />
Удалено несколько больше, чем добавлено — общая картина практически не изменилась.</blockquote><br />
<br />
Категория <code>modified</code> — маркер, присутствующий в обоих снимках, у которого изменилось окружение (номер строки, контекст функции). Это не новая ошибка. На больших проектах рекомендуется начинать с <code>level=0</code> для получения статистики, при необходимости использовать <code>level=1</code> (только идентификаторы маркеров) и затем точечно вызывать <code>get_markers</code> с нужными фильтрами.<br />
<br />
<code>level=2</code> возвращает полные маркеры по категориям, причём каждая категория по умолчанию ограничена 20 маркерами. Категории располагаются внутри <code>markers</code>: <code>new_markers</code>, <code>missing_markers</code>, <code>modified_markers</code>, <code>matched_markers</code>. Структура ответа в JSON: <code><nowiki>{"markers": {"new_markers": {"total_count": N, "returned_count": ..., "truncated": ..., "markers": [...]}, ...}}</nowiki></code>. Если требуется полное содержимое категории, следует увеличить <code>limit</code> или выполнить отдельный вызов <code>get_markers</code> по нужным идентификаторам.<br />
<br />
=== Разобрать конкретное предупреждение ===<br />
<blockquote>В bash есть один подтверждённый критикал — что-то про разыменование указателя. Покажи код вокруг этого места и объясни в чём проблема.</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code> → <code>get_snapshots()</code> — найти снимок bash<br />
# <code>get_markers(severity=["Critical"], review=["Confirmed"])</code><br />
# <code>get_advanced_file_preview(file_path="/.build/execute_cmd.c", line=3327, before=10, after=10)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>Маркер <code>DEREF_AFTER_NULL.LOOP</code> в функции <code>select_query()</code>, строка 3327:<br />
<code>for (l = list; l && --reply; l = l->next)<br />
<br />
;<br />
<br />
return (l->word->word); /* l может быть NULL после выхода из цикла */</code><br />
<br />
Если список заканчивается раньше, чем <code>reply</code> обнуляется, <code>l</code> станет <code>NULL</code> на последнем <code>l->next</code>, и следующий <code>l->word->word</code> — разыменование нулевого указателя.</blockquote><code>file_path</code> должен точно совпадать со значением, возвращённым маркером, включая ведущий префикс <code>/.build/...</code>. Это путь внутри сборочной директории Svacer, а не путь в исходном репозитории; соответствие в репозитории определяется по имени файла.<br />
<br />
Для одиночной разметки удобно сразу запрашивать полный маркер с трассами: <code>get_markers(..., severity=["Critical"], review=["Confirmed"], traces=True, checker_info=True)</code>. Флаги <code>traces</code> и <code>checker_info</code> указывают серверу включить соответствующие поля в ответ; в выдаче они сохраняются и при значении <code>fields</code> по умолчанию. Значение <code>fields=["*"]</code> требуется лишь в том случае, когда дополнительно нужны <code>tool</code> и <code>mtid</code> — служебные ключи, исключённые из компактного набора.</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_MCP&diff=3567Help:13-alpha MCP2026-05-26T08:49:14Z<p>M.vinogradov: Добавлена ссылка на демонстрационный релиз и инструкцию запуска с помощью docker compose</p>
<hr />
<div>== Архитектура ==<br />
[https://modelcontextprotocol.io/docs/getting-started/intro MCP] — открытый стандарт, через который LLM-клиенты (Claude Desktop, Cursor, VS Code, OpenWebUI и др.) вызывают внешние инструменты. <br />
Svacer MCP соединяет одно с другим: 8 инструментов поверх публичного REST API Svacer, которые LLM выбирает и вызывает в ответ на обычный текстовый запрос. Вместо ручной последовательности «открыть UI, найти проект, выбрать снимок, применить фильтр» достаточно сформулировать вопрос в чате, например, «сколько критических предупреждений в последнем снимке bash?», и получить ответ. Необходимые вызовы инструментов модель выполняет самостоятельно.<br />
<br />
[[File:Архитектура MCP.png|thumb|none|x800px|alt=architectureMCP|Архитектура MCP-сервера]]<br />
<br />
Поток запроса: LLM-клиент отправляет MCP-вызов через STDIO или Streamable HTTP → <code>server.py</code> передаёт его в выбранный инструмент из <code>tools/</code> → инструмент проверяет параметры и обращается к <code>api_client.py</code> → клиент получает JWT от <code>auth.py</code> (модуль автоматически обновляет токен по истечении срока действия или при ответе 401) → запрос отправляется в Svacer REST API.<br />
<br />
{{Note|text=Поддержка MCP включена в [[Help:13-alpha introduction|тестовый релиз]], который может быть развёрнут с помощью docker compose [[Help:13-alpha deploy|согласно инструкции]]}}<br />
<br />
== Установка ==<br />
Установка Svacer MCP, подключение клиентов и конфигурация.<br />
<br />
=== Требования ===<br />
<br />
* Python 3.10+<br />
* Доступ к серверу Svacer: URL + логин/пароль<br />
<br />
=== Режим STDIO ===<br />
Подходит для настольных клиентов: Claude Desktop, Claude Code, Cursor, VS Code.<br />
git clone <nowiki>https://gitlab.ispras.ru/svacerai/mcp.git</nowiki> && cd mcp<br />
<br />
python3 -m venv .venv<br />
.venv/bin/pip install -e .<br />
<br />
cp .env.example .env<br />
# Отредактировать .env — указать URL и учётные данные Svacer<br />
<br />
# Проверить запуск (сервер ожидает данные на stdin; для выхода — Ctrl+C)<br />
.venv/bin/svacer-mcp<br />
<br />
После <code>pip install -e .</code> в окружении становится доступна команда <code>svacer-mcp</code> — её указывают в конфигурации клиентов ниже.<br />
<br />
=== Режим HTTP (Docker) ===<br />
Подходит для веб-клиентов (OpenWebUI) и удалённого доступа.<br />
<br />
'''Требования:''' Docker, Docker Compose.<br />
cp .env.example .env<br />
<br />
# В .env обязательно задать SVACER_MCP_TOKEN — без него сервер не запускается<br />
echo "SVACER_MCP_TOKEN=$(openssl rand -hex 32)" >> .env<br />
<br />
docker compose up -d<br />
<br />
# MCP endpoint: <nowiki>http://localhost:8002/mcp</nowiki><br />
# Клиенты передают заголовок: Authorization: Bearer <SVACER_MCP_TOKEN><br />
<br />
Внешний порт хоста задаётся переменной <code>MCP_PORT</code> (по умолчанию <code>8002</code>), внутри контейнера сервер всегда слушает порт <code>8000</code>.<br />
<br />
=== Подключение клиентов ===<br />
<br />
==== Claude Desktop ====<br />
Файл конфигурации: <code>~/.config/Claude/claude_desktop_config.json</code> (Linux) или <code>%APPDATA%\Claude\claude_desktop_config.json</code> (Windows).<br />
<br />
Укажите '''абсолютный путь''' к <code>svacer-mcp</code> из вашего venv (<code>which svacer-mcp</code> в активированном venv или <code>/path/to/mcp/.venv/bin/svacer-mcp</code>).<br />
<br />
{<br />
"mcpServers": {<br />
"svacer": {<br />
"command": "/path/to/mcp/.venv/bin/svacer-mcp",<br />
"env": {<br />
"SVACER_URL": "<nowiki>https://your-svacer.example.com</nowiki>",<br />
"SVACER_LOGIN": "your-login",<br />
"SVACER_PASSWORD": "your-password"<br />
}<br />
}<br />
}<br />
}<br />
<br />
==== Claude Code ====<br />
claude mcp add svacer \<br />
-e SVACER_URL=<nowiki>https://your-svacer.example.com</nowiki> \<br />
-e SVACER_LOGIN=your-login \<br />
-e SVACER_PASSWORD=your-password \<br />
-- /path/to/mcp/.venv/bin/svacer-mcp<br />
<br />
==== VS Code ====<br />
Файл <code>.vscode/mcp.json</code> в корне рабочей директории:<br />
<br />
{<br />
"servers": {<br />
"svacer": {<br />
"type": "stdio",<br />
"command": "/path/to/mcp/.venv/bin/svacer-mcp",<br />
"env": {<br />
"SVACER_URL": "<nowiki>https://your-svacer.example.com</nowiki>",<br />
"SVACER_LOGIN": "your-login",<br />
"SVACER_PASSWORD": "your-password"<br />
}<br />
}<br />
}<br />
}<br />
<br />
==== Cursor ====<br />
Файл <code>.cursor/mcp.json</code> в корне проекта или глобально:<br />
<br />
{<br />
"mcpServers": {<br />
"svacer": {<br />
"command": "/path/to/mcp/.venv/bin/svacer-mcp",<br />
"env": {<br />
"SVACER_URL": "<nowiki>https://your-svacer.example.com</nowiki>",<br />
"SVACER_LOGIN": "your-login",<br />
"SVACER_PASSWORD": "your-password"<br />
}<br />
}<br />
}<br />
}<br />
<br />
==== OpenWebUI ====<br />
# Развернуть через Docker (см. [[#Режим HTTP (Docker)|Режим HTTP]]).<br />
# Открыть '''Settings → Tools''' (или '''Admin Panel → Settings → Tools''').<br />
# Добавить сервер:<br />
#* <code><nowiki>http://localhost:8002/mcp</nowiki></code> — если OpenWebUI работает на хосте, снаружи Docker.<br />
#* <code><nowiki>http://svacer-mcp:8000/mcp</nowiki></code> — если OpenWebUI развёрнут в той же compose-сети, что и <code>svacer-mcp</code> (имя берётся из <code>docker-compose.yml</code> → service name, порт 8000 — внутренний порт контейнера).<br />
# Тип подключения: '''MCP (Streamable HTTP)'''.<br />
# В настройках инструмента указать заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code> (значение — то же, что в <code>.env</code> сервера).<br />
# Сохранить — инструменты появятся в чате.<br />
<br />
=== Конфигурация ===<br />
{| class="wikitable"<br />
!Переменная<br />
!По умолчанию<br />
!Описание<br />
|-<br />
|SVACER_URL<br />
|<nowiki>https://svacer-demo.ispras.ru</nowiki><br />
|URL сервера Svacer<br />
|-<br />
|SVACER_LOGIN<br />
|admin<br />
|Логин<br />
|-<br />
|SVACER_PASSWORD<br />
|admin<br />
|Пароль<br />
|-<br />
|SVACER_TIMEOUT<br />
|30<br />
|Тайм-аут HTTP-запросов к Svacer, секунды<br />
|-<br />
|SVACER_TRANSPORT<br />
|stdio<br />
|Режим транспорта: <code>stdio</code> или <code>http</code><br />
|-<br />
|SVACER_HTTP_PORT<br />
|8000<br />
|TCP-порт сервера в режиме HTTP (внутри контейнера)<br />
|-<br />
|SVACER_MCP_TOKEN<br />
|''(не задано)''<br />
|Bearer-токен для клиентов <code>/mcp</code>. Обязателен при <code>SVACER_TRANSPORT=http</code>, в режиме STDIO игнорируется. Генерация: <code>openssl rand -hex 32</code><br />
|-<br />
|SVACER_MCP_RESOURCE_URL<br />
|<nowiki>http://localhost</nowiki>:<HTTP_PORT><br />
|Публичный URL MCP-сервера для заголовка <code>WWW-Authenticate</code> (<nowiki>RFC 9728</nowiki>). Задаётся при работе за обратным прокси<br />
|-<br />
|SVACER_TOOLS<br />
|''(не задано)''<br />
|Список инструментов через запятую. Если не задано, регистрируются все 8<br />
|-<br />
|MCP_PORT<br />
|8002<br />
|Внешний порт хоста при запуске через <code>docker compose</code> (отображается на внутренний <code>SVACER_HTTP_PORT</code>)<br />
|}<br />
Переменные читаются из <code>.env</code> или из окружения. Для STDIO-клиентов их можно указать в секции <code>env</code> конфигурации клиента.<br />
<br />
==== Ограничение набора инструментов ====<br />
Чтобы запустить сервер с подмножеством инструментов (например, для уменьшения объёма контекста у модели или разграничения доступа), задайте <code>SVACER_TOOLS</code>:<br />
SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
Допустимые имена: <code>get_projects</code>, <code>get_snapshots</code>, <code>get_warnings</code>, <code>get_markers</code>, <code>get_project_stats</code>, <code>get_project_groups</code>, <code>get_advanced_file_preview</code>, <code>get_diff</code>. Неизвестное имя в списке приводит к ошибке при запуске. Если переменная пустая или не задана, регистрируются все 8 инструментов.<br />
<br />
==== Несколько экземпляров сервера ====<br />
Параллельный запуск нескольких MCP-серверов поддерживается без ограничений.<br />
<br />
* В режиме STDIO каждая запись в конфигурации клиента описывает отдельный процесс — несколько подключений к разным экземплярам Svacer задаются простым перечислением.<br />
* В режиме HTTP запускаются независимые контейнеры на разных хост-портах: например, <code>MCP_PORT=8002</code> для одного экземпляра и <code>MCP_PORT=8003</code> для другого. Для каждого контейнера задаётся собственный <code>SVACER_MCP_TOKEN</code>.<br />
<br />
=== Безопасность ===<br />
<br />
* '''STDIO''': сервер не открывает сетевых портов и обменивается данными через стандартные потоки ввода/вывода процесса.<br />
* '''Streamable HTTP''': эндпоинт <code>/mcp</code> требует заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code>. Запросы без токена или с неверным значением получают ответ <code>401</code> и заголовок <code>WWW-Authenticate: Bearer ...</code>. Токен является разделяемым секретом и не заменяет TLS, а дополняет его: при работе за обратным прокси необходимо использовать HTTPS, а сам токен передавать только по защищённому каналу.<br />
* Без <code>SVACER_MCP_TOKEN</code> HTTP-сервер не запускается.<br />
* Учётные данные <code>admin/admin</code> предназначены только для тестового стенда. В рабочем окружении необходимо задать собственные логин и пароль через переменные окружения.<br />
* Файл <code>.env</code> не должен добавляться в систему контроля версий.<br />
<br />
==== Передача токена клиентом ====<br />
Большинство HTTP-клиентов MCP (OpenWebUI и др.) позволяют задать произвольный заголовок <code>Authorization</code> в настройках инструмента — указывается значение <code>Bearer <токен></code>. Для ручной проверки:<br />
curl -H "Authorization: Bearer $SVACER_MCP_TOKEN" \<br />
<nowiki> </nowiki> -H 'Content-Type: application/json' \<br />
<nowiki> </nowiki> -H 'Accept: application/json, text/event-stream' \<br />
<nowiki> </nowiki> -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \<br />
<nowiki> </nowiki> <nowiki>http://localhost:8002/mcp</nowiki><br />
<br />
== Инструменты ==<br />
Справочник по 8 инструментам Svacer MCP. Типичный порядок вызовов: <code>get_projects</code> → <code>get_snapshots</code> → любой из аналитических инструментов.<br />
{| class="wikitable"<br />
!Инструмент<br />
!Назначение<br />
|-<br />
|get_projects<br />
|Список проектов с ветками — точка входа<br />
|-<br />
|get_snapshots<br />
|Снимки конкретной ветки, от нового к старому<br />
|-<br />
|get_project_stats<br />
|Агрегированные метрики снимка: severity / review / checker<br />
|-<br />
|get_markers<br />
|Компактный список маркеров с серверной фильтрацией<br />
|-<br />
|get_warnings<br />
|Полные предупреждения с трассами и историей разметки<br />
|-<br />
|get_diff<br />
|Сравнение двух снимков: new / missing / modified / matched<br />
|-<br />
|get_advanced_file_preview<br />
|Фрагмент исходного кода вокруг строки<br />
|-<br />
|get_project_groups<br />
|Группа проектов по имени или UUID<br />
|}<br />
<br />
=== get_projects ===<br />
Список всех проектов с ветками. Точка входа: с этого вызова начинается практически любой сценарий — он возвращает <code>project_id</code> и <code>branch_id</code>, необходимые для последующих запросов.<br />
<br />
'''Параметров нет.'''<br />
<br />
'''Вызов:'''<br />
get_projects()<br />
<br />
'''Ответ:'''<br />
[<br />
{<br />
"project_id": "91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
"project_name": "bash",<br />
"created": "2021-12-13T13:22:42.122456Z",<br />
"created_by": "admin",<br />
"branches": [<br />
{<br />
"branch_id": "77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
"branch_name": "master",<br />
"created": "2021-12-13T13:22:42.394812Z"<br />
}<br />
]<br />
}<br />
]<br />
----<br />
<br />
=== get_snapshots ===<br />
Список снимков для конкретной ветки проекта, от нового к старому.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|name_filter<br />
|string<br />
|нет<br />
|Подстрока или regex для фильтра по имени снимка<br />
|}<br />
<br />
'''Вызов:'''<br />
get_snapshots(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4"<br />
)<br />
<br />
'''Ответ:'''<br />
[<br />
{<br />
"snapshot_id": "b42cb563-86f4-4f96-900a-7782163327c9",<br />
"name": "Snapshot 2020-03-25 09:09:41 +0300",<br />
"import_time": "2020-03-25T09:09:41.837296Z",<br />
"commit_hash": null,<br />
"markers_count": 297,<br />
"link": "<nowiki>https://svacer-demo.ispras.ru/</nowiki>..."<br />
}<br />
]<br />
----<br />
<br />
=== get_project_stats ===<br />
Агрегированные метрики по снимку: общее количество предупреждений, распределение по критичности, по статусу разметки, по детекторам. Наиболее быстрый способ получить общую картину по проекту.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_snapshots</code><br />
|}<br />
<br />
'''Вызов:'''<br />
get_project_stats(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9"<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"total_warnings": 771,<br />
"by_severity": {<br />
"Critical": 1,<br />
"Major": 1,<br />
"Unspecified": 769<br />
},<br />
"by_review_status": {<br />
"Confirmed": 1,<br />
"False Positive": 1,<br />
"Undecided": 767,<br />
"Unclear": 1,<br />
"Won't fix": 1<br />
},<br />
"by_checker": {<br />
"PROC_USE.VULNERABLE": 337,<br />
"UNUSED_FUNC_RES.REWRITE.MINOR": 44,<br />
"UNREACHABLE_CODE": 28,<br />
"DEREF_AFTER_NULL.EX": 27,<br />
"NULL_AFTER_DEREF": 27<br />
}<br />
}<br />
----<br />
<br />
=== get_markers ===<br />
Компактный список маркеров с серверной фильтрацией. Основной инструмент для перечисления и обзора: его следует предпочитать <code>get_warnings</code>, когда не требуются развёрнутые поля — трассы и история разметки.<br />
<br />
По умолчанию ответ ограничен 30 маркерами и содержит компактный набор полей. Подробнее об ограничении объёма см. раздел [[#Про объём ответа|Про объём ответа]].<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_snapshots</code><br />
|-<br />
|severity<br />
|string[]<br />
|нет<br />
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code> применяется на стороне коннектора<br />
|-<br />
|review<br />
|string[]<br />
|нет<br />
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code><br />
|-<br />
|warnClass<br />
|string[]<br />
|нет<br />
|Идентификатор детектора (<code>DEREF_AFTER_NULL</code>, …)<br />
|-<br />
|file<br />
|string[]<br />
|нет<br />
|Подстрока пути к файлу<br />
|-<br />
|traces<br />
|bool<br />
|нет<br />
|Включить трассы маркеров<br />
|-<br />
|checker_info<br />
|bool<br />
|нет<br />
|Включить метаданные детектора (CWE, описание)<br />
|-<br />
|review_history<br />
|bool<br />
|нет<br />
|Включить историю изменений разметки<br />
|-<br />
|comment_history<br />
|bool<br />
|нет<br />
|Включить комментарии к маркеру<br />
|-<br />
|custom_filter<br />
|string<br />
|нет<br />
|Имя или идентификатор сохранённого фильтра из веб-интерфейса Svacer<br />
|-<br />
|limit<br />
|int<br />
|нет<br />
|Максимальное количество маркеров в ответе (по умолчанию 30). Значение 0 снимает ограничение<br />
|-<br />
|fields<br />
|string[]<br />
|нет<br />
|Список разрешённых полей маркера верхнего уровня. По умолчанию — компактный набор <code>id, warnClass, file, line, msg, function, review</code>. Значение <code>["*"]</code> возвращает все поля коннектора (<code>id, warnClass, file, line, msg, tool, function, mtid, review</code>, а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены). Допустим и произвольный список, например <code>["id","warnClass"]</code><br />
|}<br />
<br />
'''Вызов:'''<br />
get_markers(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
warnClass=["PROC_USE.VULNERABLE"]<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"total_count": 341,<br />
"returned_count": 30,<br />
"truncated": true,<br />
"filters_applied": {"warnClass": ["PROC_USE.VULNERABLE"]},<br />
"markers": [<br />
{<br />
"id": "e05bb35b-a95e-4eb2-85ae-3101b788f07d",<br />
"warnClass": "PROC_USE.VULNERABLE.TEMP",<br />
"file": "/.build/lib/sh/tmpfile.c",<br />
"line": 160,<br />
"msg": "Use of vulnerable function 'mktemp' at tmpfile.c:160. ...",<br />
"function": "sh_mktmpname",<br />
"review": null<br />
}<br />
]<br />
}<br />
<br />
<code>total_count</code> отражает количество маркеров, удовлетворяющих фильтру до применения ограничения; <code>returned_count</code> — количество маркеров, фактически содержащихся в <code>markers</code>. При <code>truncated: true</code> следует либо сузить фильтры (<code>severity</code>, <code>warnClass</code>, <code>file</code>), либо передать <code>limit=0</code> для получения полного списка. Поля <code>tool</code> и <code>mtid</code> возвращаются только при <code>fields=["*"]</code>.<br />
----<br />
<br />
=== get_warnings ===<br />
Полные предупреждения с детальной разметкой. Ответ значительно объёмнее, чем у <code>get_markers</code>, поэтому инструмент следует использовать только тогда, когда нужны поля, отсутствующие в компактной форме: <code>traces</code>, <code>review_history</code>, <code>checker_info</code>, <code>comment_history</code>.<br />
<br />
Лимит по умолчанию — 30; при включённых <code>traces</code>, <code>review_history</code> или <code>comment_history</code> он автоматически снижается до 8, поскольку такие предупреждения существенно объёмнее.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|project_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|branch_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_projects</code><br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|Из <code>get_snapshots</code><br />
|-<br />
|severity<br />
|string[]<br />
|нет<br />
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code>, применяется на стороне коннектора<br />
|-<br />
|review<br />
|string[]<br />
|нет<br />
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code><br />
|-<br />
|warnClass<br />
|string[]<br />
|нет<br />
|Идентификатор детектора<br />
|-<br />
|file<br />
|string[]<br />
|нет<br />
|Подстрока пути к файлу<br />
|-<br />
|traces<br />
|bool<br />
|нет<br />
|Включить трассы. Активирует режим расширенных полей (лимит по умолчанию — 8)<br />
|-<br />
|checker_info<br />
|bool<br />
|нет<br />
|Включить метаданные детектора (CWE, описание)<br />
|-<br />
|review_history<br />
|bool<br />
|нет<br />
|Включить историю разметки. Режим расширенных полей<br />
|-<br />
|comment_history<br />
|bool<br />
|нет<br />
|Включить комментарии. Режим расширенных полей<br />
|-<br />
|custom_filter<br />
|string<br />
|нет<br />
|Имя или идентификатор сохранённого фильтра<br />
|-<br />
|limit<br />
|int<br />
|нет<br />
|Максимальное количество предупреждений в ответе. По умолчанию — 30, в режиме расширенных полей — 8. Значение 0 снимает ограничение. Явно заданное <code>limit</code> отменяет автоматическое снижение<br />
|-<br />
|fields<br />
|string[]<br />
|нет<br />
|См. описание в <code>get_markers</code><br />
|}<br />
'''Вызов:'''<br />
get_warnings(<br />
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",<br />
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
severity=["Critical"],<br />
review_history=True,<br />
traces=True<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"total_count": 1,<br />
"returned_count": 1,<br />
"truncated": false,<br />
"filters_applied": {"severity": ["Critical"], "traces": true, "review_history": true},<br />
"warnings": [<br />
{<br />
"id": "a3f21c90-1d4e-4b82-9f63-7c8e5d2a1b09",<br />
"warnClass": "DEREF_AFTER_NULL.LOOP",<br />
"file": "/.build/execute_cmd.c",<br />
"line": 3327,<br />
"msg": "Possible null pointer dereference of 'l' after loop exit.",<br />
"function": "select_query",<br />
"review": {"status": "Confirmed", "severity": "Critical"},<br />
"review_history": [{"status": "Confirmed", "changed_by": "admin", "changed_at": "2021-12-13T14:00:00Z"}],<br />
"traces": [{"file": "/.build/execute_cmd.c", "line": 3320, "msg": "Loop starts here; 'l' may exhaust the list."}]<br />
}<br />
]<br />
}<br />
----<br />
<br />
=== get_diff ===<br />
Сравнение двух снимков. Категории располагаются под ключом <code>markers</code>: <code>new_markers</code> (появилось в новом снимке), <code>missing_markers</code> (исчезло из нового), <code>modified_markers</code> (тот же идентификатор, изменился контекст), <code>matched_markers</code> (совпало в обоих). Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно UUID снимков.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|base_snapshot_id<br />
|string (UUID)<br />
|да<br />
|Старый снимок<br />
|-<br />
|head_snapshot_id<br />
|string (UUID)<br />
|нет<br />
|Новый снимок; если не указан, сравнение выполняется с предыдущим по времени<br />
|-<br />
|level<br />
|int<br />
|нет<br />
|0 — только статистика; 1 — статистика и идентификаторы маркеров; 2 — полные маркеры по категориям<br />
|-<br />
|checker_info<br />
|bool<br />
|нет<br />
|Метаданные детекторов для маркеров (только при <code>level >= 2</code>)<br />
|-<br />
|limit<br />
|int<br />
|нет<br />
|Максимальное количество маркеров '''на каждую категорию''' при <code>level >= 2</code>. По умолчанию — 20, значение 0 снимает ограничение. Параметр игнорируется при <code>level < 2</code><br />
|-<br />
|fields<br />
|string[]<br />
|нет<br />
|См. описание в <code>get_markers</code>. Применяется к маркерам внутри категорий при <code>level >= 2</code><br />
|}<br />
<br />
'''Вызов (<code>level=0</code>):'''<br />
get_diff(<br />
base_snapshot_id="72b3df7b-c15a-4e3d-8f92-a041dc6e5b87",<br />
head_snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
level=0<br />
)<br />
<br />
'''Ответ (<code>level=0</code>):'''<br />
{<br />
"stats": {<br />
"context1": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-20 ..."},<br />
"context2": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-25 ..."},<br />
"scope": ["NEW", "MISSING", "MATCHED", "MODIFIED"],<br />
"new": 9,<br />
"missing": 12,<br />
"modified": 98,<br />
"matched": 187<br />
}<br />
}<br />
<br />
'''Ответ (<code>level=2</code>)''' — каждая категория внутри <code>markers</code> оформляется и ограничивается независимо:<br />
{<br />
"stats": {"new": 50, "missing": 5, "modified": 0, "matched": 187},<br />
"markers": {<br />
"new_markers": {<br />
"total_count": 50,<br />
"returned_count": 20,<br />
"truncated": true,<br />
"markers": [<br />
{"id": "a3f21c90-...", "warnClass": "DEREF_AFTER_NULL.LOOP", "file": "...", "line": 3327, "msg": "...", "function": "select_query", "review": null}<br />
]<br />
},<br />
"missing_markers": {"total_count": 5, "returned_count": 5, "truncated": false, "markers": [...]},<br />
"modified_markers": {"total_count": 0, "returned_count": 0, "truncated": false, "markers": []},<br />
"matched_markers": {"total_count": 187, "returned_count": 20, "truncated": true, "markers": [...]}<br />
}<br />
}<br />
<br />
Если требуется полное содержимое категории, следует увеличить <code>limit</code>, либо запросить нужные идентификаторы отдельным вызовом <code>get_markers</code>. Маркеры внутри категорий проходят ту же компактную обработку, что и в <code>get_warnings</code>: значение <code>fields=["*"]</code> возвращает фиксированный набор полей коннектора, а не произвольные «сырые» поля API.<br />
----<br />
<br />
=== get_advanced_file_preview ===<br />
Фрагмент исходного кода из снимка вокруг указанной строки. Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно идентификатора снимка и пути к файлу.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|snapshot_id<br />
|string (UUID)<br />
|да<br />
|UUID снимка<br />
|-<br />
|file_path<br />
|string<br />
|да<br />
|Путь к файлу в том виде, в котором его возвращают <code>get_markers</code> и <code>get_warnings</code><br />
|-<br />
|line<br />
|int<br />
|нет<br />
|Центральная строка, нумерация с 1 (по умолчанию 1)<br />
|-<br />
|before<br />
|int<br />
|нет<br />
|Количество строк до центральной (по умолчанию 0)<br />
|-<br />
|after<br />
|int<br />
|нет<br />
|Количество строк после центральной (по умолчанию 99999 — до конца файла)<br />
|}<br />
<br />
'''Вызов:'''<br />
get_advanced_file_preview(<br />
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",<br />
file_path="/.build/execute_cmd.c",<br />
line=3327,<br />
before=10,<br />
after=10<br />
)<br />
<br />
'''Ответ:'''<br />
{<br />
"line": 3327,<br />
"content": " for (l = list; l && --reply; l = l->next)\n\t;\n return (l->word->word);\n",<br />
"total_lines": 6082<br />
}<br />
----<br />
<br />
=== get_project_groups ===<br />
Получить группу проектов по имени или UUID. Группы объединяют проекты в логические блоки — например, по команде или продукту.<br />
<br />
'''Параметры.'''<br />
{| class="wikitable"<br />
!Имя<br />
!Тип<br />
!Обязательный<br />
!Описание<br />
|-<br />
|name_or_id<br />
|string<br />
|да<br />
|Имя группы или её UUID<br />
|}<br />
<br />
'''Вызов:'''<br />
get_project_groups(name_or_id="Linux Tools")<br />
<br />
'''Ответ:'''<br />
{<br />
"project_group_id": "c4f8a2d1-3b7e-4f90-82ac-1d5e8f2b6c04",<br />
"project_group_name": "Linux Tools",<br />
"projects": [<br />
{"id": "91630e84-db2f-4d8c-8716-68b7fdf17a66", "name": "bash"},<br />
{"id": "d3a17f52-...", "name": "coreutils"}<br />
]<br />
}<br />
<br />
<code>projects[].id</code> — это <code>project_id</code>, который далее передаётся в <code>get_snapshots</code>. Группы и проекты — разные сущности; идентификатор группы и идентификатор проекта не взаимозаменяемы.<br />
<br />
== Примеры сценариев ==<br />
Приведённые ниже запросы выполнены на демонстрационном стенде <code>svacer-demo.ispras.ru</code> с использованием OpenWebUI и модели <code>qwen3-coder:30b</code>. В любом другом MCP-клиенте с моделью достаточной мощности порядок вызовов будет аналогичным.<br />
<br />
=== Про объём ответа ===<br />
<code>get_markers</code>, <code>get_warnings</code> и <code>get_diff(level=2)</code> по умолчанию ограничивают объём ответа, чтобы не перегружать контекст модели:<br />
<br />
* <code>get_markers</code> и <code>get_warnings</code> — 30 маркеров по умолчанию. Если у <code>get_warnings</code> включены <code>traces</code>, <code>review_history</code> или <code>comment_history</code>, лимит снижается до 8, поскольку такие маркеры значительно объёмнее.<br />
* <code>get_diff(level=2)</code> — 20 маркеров на каждую категорию внутри <code>markers</code> (<code>new_markers</code>/<code>missing_markers</code>/<code>modified_markers</code>/<code>matched_markers</code>).<br />
<br />
В ответе присутствуют поля <code>total_count</code>, <code>returned_count</code>, <code>truncated</code>. При <code>truncated: true</code> есть два варианта действий: сузить фильтр (<code>severity</code>, <code>warnClass</code>, <code>file</code>) либо явно увеличить <code>limit</code> (значение <code>limit=0</code> полностью снимает ограничение).<br />
<br />
Поле <code>fields</code> определяет, какие ключи маркера возвращаются. По умолчанию применяется компактный набор <code>id, warnClass, file, line, msg, function, review</code> (а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены логическими флагами и пришли с сервера). Для полного маркера со всеми служебными ключами — <code>fields=["*"]</code>. Для произвольной выборки — список полей верхнего уровня, например <code>fields=["id","warnClass"]</code>. Поле <code>review</code> — объект <code>{status, severity, action}</code>; вложенные ключи в <code>fields</code> не поддерживаются, поэтому объект <code>review</code> запрашивается целиком.<br />
<br />
=== Перечислить все проекты ===<br />
<blockquote>Какие проекты есть в Svacer?</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>В Svacer доступно 6 проектов: bash, openssl, paho.mqtt.c, coturn, zstd, darpa. У каждого — одна ветка <code>master</code>.</blockquote><br />
<br />
=== Посмотреть снимки проекта ===<br />
<blockquote>Какие снимки есть у paho.mqtt.c? Самый свежий когда?</blockquote>'''Цепочка вызовов:'''<br />
<br />
# <code>get_projects()</code> — найти <code>project_id</code> и <code>branch_id</code><br />
# <code>get_snapshots(project_id=..., branch_id=...)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>У paho.mqtt.c 3 снимка. Самый свежий — «Snapshot 2020-03-25 09:09:41 +0300» (297 маркеров). Предыдущий — 20 марта (306 маркеров).</blockquote>Поле <code>commit_hash</code> может принимать значение <code>null</code>, если проект не сохраняет хэш коммита в <code>custom_properties</code>. Имена снимков произвольны: одни проекты записывают в имя дату, другие — коммит, третьи — свободный текст.<br />
<br />
=== Сводка по проекту ===<br />
<blockquote>Что в bash в последнем снимке? Сколько всего предупреждений, есть ли критические, какие топ-детекторы?</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
# <code>get_snapshots(project_id, branch_id)</code> — взять последний снимок<br />
# <code>get_project_stats(project_id, branch_id, snapshot_id)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>В последнем снимке bash содержится 771 предупреждение:<br />
<br />
* Критических: 1 (Confirmed)<br />
* Major: 1 (Won't fix)<br />
* Остальные: 769 (Unspecified — не размечались)<br />
<br />
Топ-детекторы по количеству:<br />
<br />
# <code>PROC_USE.VULNERABLE</code> — 337<br />
# <code>UNUSED_FUNC_RES.REWRITE.MINOR</code> — 44<br />
# <code>UNREACHABLE_CODE</code> — 28<br />
# <code>DEREF_AFTER_NULL.EX</code> — 27<br />
# <code>NULL_AFTER_DEREF</code> — 27<br />
</blockquote><br />
<br />
<code>Unspecified</code> в <code>by_severity</code> — маркеры без ручной разметки, а не «низкий приоритет». Поле <code>by_checker</code> не сортируется, на большом снимке оно может содержать более 100 ключей — чтобы получить именно топ-N, следует явно сформулировать запрос: «топ-5 детекторов».<br />
<br />
=== Тренд по нескольким снимкам ===<br />
<blockquote>Как у openssl менялось число предупреждений за последние пять снимков? Покажи таблицей.</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
<br />
# <code>get_projects()</code><br />
# <code>get_snapshots()</code> — взять список<br />
# <code>get_project_stats()</code> × 5 — по каждому из последних пяти снимков<br />
<br />
'''Ответ модели:'''<br />
<blockquote><br />
{| class="wikitable"<br />
|+<br />
!Снимок<br />
!Дата<br />
!Всего<br />
|-<br />
|2020-04-30 05:49<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 05:29<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 05:08<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 04:48<br />
|30.04.2020<br />
|1252<br />
|-<br />
|2020-04-30 04:22<br />
|30.04.2020<br />
|1252<br />
|}<br />
</blockquote><br />
<br />
На демонстрационном стенде указанные пять снимков openssl импортированы с интервалом в 20 минут одного дня и полностью идентичны — поэтому динамика отсутствует. На реальном проекте с историей релизов значения будут изменяться.<br />
<br />
=== Найти срабатывания конкретного детектора ===<br />
<blockquote>Где в bash срабатывает PROC_USE.VULNERABLE? Покажи список — файл, строка, что именно ругается. Достаточно первых десяти.</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
# <code>get_snapshots()</code><br />
# <code>get_markers(warnClass=["PROC_USE.VULNERABLE"])</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote><br />
# <code>/.build/lib/sh/tmpfile.c:160</code> — <code>mktemp()</code>, race condition. Рекомендуется <code>mkstemp()</code>.<br />
# <code>/.build/lib/readline/shell.c:151</code> — <code>getenv()</code>, значение может быть подменено.<br />
# <code>/.build/shell.c:415</code> — <code>getenv()</code> в <code>main()</code>.<br />
# <code>/.build/lib/readline/complete.c:1516</code> — <code>getenv()</code>.<br />
# <code>/.build/lib/sh/eaccess.c:115</code> — <code>strcat()</code>, рекомендуется <code>strncat()</code>.<br />
</blockquote><br />
<br />
Фильтр <code>warnClass=["PROC_USE.VULNERABLE"]</code> охватывает все подклассы: <code>PROC_USE.VULNERABLE.TEMP</code>, <code>.GETENV</code>, <code>.STRCAT</code> и т. д. — всего 341 маркер. Несколько значений в одном параметре трактуются как логическое «ИЛИ»: <code>severity=["Critical","Major"]</code> возвращает маркеры обеих категорий.<br />
<br />
В ответе будет <code>total_count: 341, returned_count: 30, truncated: true</code> — это ожидаемое поведение. Модель видит общий объём по <code>total_count</code> и при необходимости сужает запрос или вызывает <code>get_markers(..., limit=0)</code>, чтобы получить полный список.<br />
<br />
=== Сравнить два снимка ===<br />
<blockquote>Возьми два последних снимка paho.mqtt.c — что между ними изменилось? Сколько новых предупреждений, сколько починили?</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code><br />
# <code>get_snapshots()</code> — два последних<br />
# <code>get_diff(base_snapshot_id="72b3df7b-...", head_snapshot_id="b42cb563-...", level=0)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>Между двумя последними снимками paho.mqtt.c:<br />
<br />
* Новых: 12<br />
* Удалённых: 13<br />
* Изменённых: 99<br />
* Совпадающих: 185<br />
<br />
Удалено несколько больше, чем добавлено — общая картина практически не изменилась.</blockquote><br />
<br />
Категория <code>modified</code> — маркер, присутствующий в обоих снимках, у которого изменилось окружение (номер строки, контекст функции). Это не новая ошибка. На больших проектах рекомендуется начинать с <code>level=0</code> для получения статистики, при необходимости использовать <code>level=1</code> (только идентификаторы маркеров) и затем точечно вызывать <code>get_markers</code> с нужными фильтрами.<br />
<br />
<code>level=2</code> возвращает полные маркеры по категориям, причём каждая категория по умолчанию ограничена 20 маркерами. Категории располагаются внутри <code>markers</code>: <code>new_markers</code>, <code>missing_markers</code>, <code>modified_markers</code>, <code>matched_markers</code>. Структура ответа в JSON: <code><nowiki>{"markers": {"new_markers": {"total_count": N, "returned_count": ..., "truncated": ..., "markers": [...]}, ...}}</nowiki></code>. Если требуется полное содержимое категории, следует увеличить <code>limit</code> или выполнить отдельный вызов <code>get_markers</code> по нужным идентификаторам.<br />
<br />
=== Разобрать конкретное предупреждение ===<br />
<blockquote>В bash есть один подтверждённый критикал — что-то про разыменование указателя. Покажи код вокруг этого места и объясни в чём проблема.</blockquote><br />
<br />
'''Цепочка вызовов:'''<br />
# <code>get_projects()</code> → <code>get_snapshots()</code> — найти снимок bash<br />
# <code>get_markers(severity=["Critical"], review=["Confirmed"])</code><br />
# <code>get_advanced_file_preview(file_path="/.build/execute_cmd.c", line=3327, before=10, after=10)</code><br />
<br />
'''Ответ модели:'''<br />
<blockquote>Маркер <code>DEREF_AFTER_NULL.LOOP</code> в функции <code>select_query()</code>, строка 3327:<br />
<code>for (l = list; l && --reply; l = l->next)<br />
<br />
;<br />
<br />
return (l->word->word); /* l может быть NULL после выхода из цикла */</code><br />
<br />
Если список заканчивается раньше, чем <code>reply</code> обнуляется, <code>l</code> станет <code>NULL</code> на последнем <code>l->next</code>, и следующий <code>l->word->word</code> — разыменование нулевого указателя.</blockquote><code>file_path</code> должен точно совпадать со значением, возвращённым маркером, включая ведущий префикс <code>/.build/...</code>. Это путь внутри сборочной директории Svacer, а не путь в исходном репозитории; соответствие в репозитории определяется по имени файла.<br />
<br />
Для одиночной разметки удобно сразу запрашивать полный маркер с трассами: <code>get_markers(..., severity=["Critical"], review=["Confirmed"], traces=True, checker_info=True)</code>. Флаги <code>traces</code> и <code>checker_info</code> указывают серверу включить соответствующие поля в ответ; в выдаче они сохраняются и при значении <code>fields</code> по умолчанию. Значение <code>fields=["*"]</code> требуется лишь в том случае, когда дополнительно нужны <code>tool</code> и <code>mtid</code> — служебные ключи, исключённые из компактного набора.</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_deploy&diff=3566Help:13-alpha deploy2026-05-26T08:45:01Z<p>M.vinogradov: Добавлены однострочники для удаления docker-артефактов</p>
<hr />
<div>== Демонстрационная сборка ==<br />
<br />
Установка демонстрационной версии Svacer с поддержкой [[Help:13-alpha introduction|описанных функций]] доступна только в докере с использованием docker compose<br />
<br />
== docker compose ==<br />
<br />
Для установки демонстрационной версии подготовлен специальный файл [https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml docker-compose-with-ai-llm-mcp.yml]<br />
<br />
<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml</nowiki><br />
<br />
При запуске Svacer с использованием данного compose-файла доступны профили:<br />
<br />
{| class="wikitable"<br />
! Профиль !! Описание<br />
|-<br />
| Без профиля || Запуск Svacer без поддержки ИИ-ассистента и MCP<br />
|-<br />
| <code>ai</code> || Запуск Svacer с поддержкой ИИ-ассистента со встроенной моделью<br />
|-<br />
| <code>llm</code> || Запуск Svacer с поддержкой ИИ-ассистента и возможностью подключения к нему внешних LLM для разметки предупреждений<br />
|-<br />
| <code>mcp</code> || Запуск Svacer с MCP-сервером <br />
|-<br />
| <code>"*"</code> || Запуск Svacer со всеми доступными профилями<br />
|}<br />
<br />
Для запуска с использованием одного или нескольких профилей используется команда<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml ... --profile llm --profile mcp ... up -d<br />
<br />
При этом необходимо учитывать, что<br />
<br />
* при запуске Svacer без профилей или только с профилем <code>mcp</code> функциональность разметки предупреждений с помощью ИИ будет возвращать ошибку;<br />
<!-- * Профиль <code>no-ai</code> не может быть использован одновременно с другими профилями; --><br />
* запуск с профилями <code>llm</code> и <code>mcp</code> требует настройки переменных окружения (см. ниже).<br />
<br />
Для удобства настройки переменных окружения может использоваться env-файл [https://svacer.ispras.ru/extra/llm-mcp.env llm-mcp.env], который после установки необходимых значений может быть передан команде запуска<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --env-file ./llm-mcp.env ... --profile llm --profile mcp ... up -d<br />
<br />
== <code>--profile ai</code> ==<br />
Данный профиль не требует дополнительной конфигурации для запуска<br />
<br />
== <code>--profile llm</code> ==<br />
Запуск Svacer с данным профилем даёт возможность подключить к ИИ-ассистенту внешний сервис моделей, поддерживающий OpenAI API. После успешного подключения ИИ-ассистент сможет использовать LLM для разметки и комментирования предупреждений. В списке разметки с помощью ИИ появятся модели доступные пользователю, чей ключ был передан при запуске.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>LLM_URL</code> значение url, по которому контейнер <code>svacer-validation-server</code> сможет подключиться к сервису моделей, совместимому с OpenAI API;<br />
* установить в переменную окружения <code>LLM_TOKEN</code> значение ключа авторизации в сервис моделей;<br />
* при необходимости установить значения переменных <code>REG_TOKEN</code> или <code>REG_LOGIN</code> и <code>REG_PASSWORD</code> содержащих, соответственно, токен авторизации или логин и пароль администратора. Эти данные нужны для запуска компонентов поддержки LLM в ИИ-ассистенте. По умолчанию будут использоваться логин и пароль <code>admin:admin</code>;<br />
* при желании изменить отображаемое название сервиса в интерфейсе выбора моделей, можно установить значение переменной <code>REG_NAME</code>. По умолчанию <code>llm</code>;<br />
* при необходимости ограничения списка доступных моделей, в переменную <code>MODEL_WHITELIST</code> нужно передать список названий моделей разделённых запятыми;<br />
* если производительность сервиса моделей позволяет параллельно обрабатывать несколько предупреждений, то можно установить значение переменной <code>MAX_PARALLEL_REQUESTS</code> в значение больше единицы;<br />
* если производительность модели не позволяет обрабатывать одно предупреждение в минуту, то результаты обработки не будут получены. Чтобы увеличить время ожидания новых результатов модели, можно установить значение переменной <code>MODEL_VALIDATION_MAXATTEMPTS</code> в значение кратное 12 (двенадцати). Например, значение 60 == 5 минут.<br />
<br />
Значения данных переменных могут быть сохранены в <code>.env</code> файл и переданы при запуске с помощью аргумента <code>docker compose --env-file ./.env ... up -d</code><br />
<br />
Описание переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# URL of the OpenAI API-compatible LLM model service<br />
LLM_URL=<br />
<br />
# LLM model service authorization token<br />
LLM_TOKEN=<br />
<br />
# Svacer admin authorization token for the operation of AI-assistant components <br />
# Or with REG_LOGIN and REG_PASSWORD, if token is not set<br />
# REG_TOKEN=<br />
<br />
# Svacer admin login and password for the operation of AI-assistant components<br />
# REG_LOGIN=admin<br />
# REG_PASSWORD=admin<br />
<br />
# ID of the service in the AI-assistant<br />
# REG_ID=llm<br />
<br />
# The name of the service displayed in the AI-assistant<br />
# REG_NAME=llm<br />
<br />
# Service description<br />
# REG_DESCRIPTION="LLM model service"<br />
<br />
# Comma-separated list of available models. If not specified, all models available to the LLM model service user will be available.<br />
# MODEL_WHITELIST=<br />
<br />
# Maximum number of simultaneous requests to the LLM model service<br />
# MAX_PARALLEL_REQUESTS=1<br />
<br />
# Maximum number of 5s attempts to get single warning result from LLM<br />
# MODEL_VALIDATION_MAXATTEMPTS=12<br />
</pre><br />
<br />
== <code>--profile mcp</code> ==<br />
При запуске с данным профилем стартует контейнер с MCP-сервером, подключённый к текущему экземпляру Svacer.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>MCP_PORT</code> номер сетевого порта на котором будет доступен MCP-сервер. По умолчанию будет назначен порт <code>8002</code>;<br />
* установить в переменную окружения <code>SVACER_MPC_TOKEN</code> строку с токеном авторизации, который необходимо будет указать в клиенте MCP-сервера;<br />
* при необходимости доступа к MCP-серверу по адресу отличному от <code>localhost</code> (<code>127.0.0.1</code>) или при использовании DNS необходимо:<br />
** указать необходимый адрес/dns-имя в переменной <code>MCP_ALLOWED_HOSTS</code> в виде <code>172.17.0.1:*</code>/<code>some.domain:*</code>;<br />
** указать необходимый адрес/dns-имя в переменной <code><nowiki>MCP_ALLOWED_ORIGINS</nowiki></code> в виде <code><nowiki>http://172.17.0.1:*</nowiki></code>/<code><nowiki>http://some.domain:*</nowiki></code>;<br />
* при необходимости можно настроить логин и пароль пользователя, от имени которого MCP-сервер будет выполнять запросы к Svacer. По умолчанию <code>admin:admin</code>.<br />
<br />
После запуска mcp-сервер будет доступен по адресу <code><nowiki>http://localhost:{MCP_PORT}/mcp</nowiki></code><br />
<br />
Описание других переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# Bearer token for /mcp clients in HTTP mode. Generate: openssl rand -hex 32<br />
SVACER_MCP_TOKEN=<br />
<br />
# Svacer admin login and password<br />
# SVACER_LOGIN=admin<br />
# SVACER_PASSWORD=admin<br />
<br />
# External port that will be mapped by docker to the internal port 8000<br />
# MCP_PORT=8002<br />
<br />
# DNS rebinding protection for FastMCP<br />
# MCP_ENABLE_DNS_REBINDING_PROTECTION=false<br />
# MCP_ALLOWED_HOSTS=svacer-mcp:*<br />
# MCP_ALLOWED_ORIGINS=http://svacer-mcp:*<br />
<br />
# HTTP timeout for requests to Svacer, seconds<br />
# SVACER_TIMEOUT=30<br />
<br />
# Public URL of this MCP server (used for WWW-Authenticate, RFC 9728).<br />
# Defaults to http://localhost:<SVACER_HTTP_PORT>. Set when running behind a reverse proxy.<br />
# SVACER_MCP_RESOURCE_URL=https://mcp.example.com<br />
<br />
# Subset of tools to register (comma-separated). Unset = all 8 tools.<br />
# Available: get_projects, get_snapshots, get_warnings, get_markers,<br />
# get_project_stats, get_project_groups, get_advanced_file_preview, get_diff<br />
# SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
</pre><br />
<br />
== Удаление демонстрационной версии == <br />
<br />
В процессе запуска демонстрационной версии в docker будут созданы контейнеры, тома, сеть с префиксом <code>svacer-13</code>. Чтобы из удалить, выполните последовательно следующие шаги:<br />
# Остановите и удалите все docker-контейнеры Svacer;<br />
# Удалите тома с данными Svacer;<br />
# Удалите docker-образы демонстрационной версии Svacer;<br />
<br />
=== Остановка и удаление docker-контейнеров Svacer ===<br />
<br />
<pre><br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --profile "*" down<br />
</pre><br />
<br />
После остановки и удаления docker-контейнеров с компонентами Svacer, данные продолжат храниться в docker-томах. Поэтому при повторном запуске демонстрационной версии они будут доступны.<br />
<br />
=== Удаление томов с данными БД, объектного и файлового хранилищ ===<br />
<br />
После выполнения следующей команды все данные накопленные за время работы демонстрационной версии Svacer будут удалены. При повторном запуске будет развёрнута чистая версия системы.<br />
<br />
<pre><br />
docker volume rm svacer-13-ai-postgres svacer-13-object-store svacer-13-postgres svacer-13-snapshot-sources<br />
</pre><br />
<br />
Удаление томов также можно выполнить одновременно с остановкой и удалением docker-контейнеров Svacer<br />
<br />
<pre><br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --profile "*" down -v<br />
</pre><br />
<br />
=== Удаление docker-образов ===<br />
<br />
После удаления docker-образов компонентов демонстрационной версии Svacer, при повторном запуске они снова будут загружены из репозитория https://hub.docker.com.<br />
<br />
<pre><br />
docker image rm ispras/svacer:13-alpha ispras/svacerai:13-alpha ispras/svacer-mcp:13-alpha ispras/validation-server:13-alpha<br />
</pre><br />
<br />
Удаление томов также можно выполнить одновременно с остановкой и удалением docker-контейнеров Svacer и томов с данными<br />
<br />
<pre><br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --profile "*" down -v --rmi all<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_deploy&diff=3565Help:13-alpha deploy2026-05-26T08:27:50Z<p>M.vinogradov: Добавлена инструкция для удаления демонстрационной версии</p>
<hr />
<div>== Демонстрационная сборка ==<br />
<br />
Установка демонстрационной версии Svacer с поддержкой [[Help:13-alpha introduction|описанных функций]] доступна только в докере с использованием docker compose<br />
<br />
== docker compose ==<br />
<br />
Для установки демонстрационной версии подготовлен специальный файл [https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml docker-compose-with-ai-llm-mcp.yml]<br />
<br />
<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml</nowiki><br />
<br />
При запуске Svacer с использованием данного compose-файла доступны профили:<br />
<br />
{| class="wikitable"<br />
! Профиль !! Описание<br />
|-<br />
| Без профиля || Запуск Svacer без поддержки ИИ-ассистента и MCP<br />
|-<br />
| <code>ai</code> || Запуск Svacer с поддержкой ИИ-ассистента со встроенной моделью<br />
|-<br />
| <code>llm</code> || Запуск Svacer с поддержкой ИИ-ассистента и возможностью подключения к нему внешних LLM для разметки предупреждений<br />
|-<br />
| <code>mcp</code> || Запуск Svacer с MCP-сервером <br />
|-<br />
| <code>"*"</code> || Запуск Svacer со всеми доступными профилями<br />
|}<br />
<br />
Для запуска с использованием одного или нескольких профилей используется команда<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml ... --profile llm --profile mcp ... up -d<br />
<br />
При этом необходимо учитывать, что<br />
<br />
* при запуске Svacer без профилей или только с профилем <code>mcp</code> функциональность разметки предупреждений с помощью ИИ будет возвращать ошибку;<br />
<!-- * Профиль <code>no-ai</code> не может быть использован одновременно с другими профилями; --><br />
* запуск с профилями <code>llm</code> и <code>mcp</code> требует настройки переменных окружения (см. ниже).<br />
<br />
Для удобства настройки переменных окружения может использоваться env-файл [https://svacer.ispras.ru/extra/llm-mcp.env llm-mcp.env], который после установки необходимых значений может быть передан команде запуска<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --env-file ./llm-mcp.env ... --profile llm --profile mcp ... up -d<br />
<br />
== <code>--profile ai</code> ==<br />
Данный профиль не требует дополнительной конфигурации для запуска<br />
<br />
== <code>--profile llm</code> ==<br />
Запуск Svacer с данным профилем даёт возможность подключить к ИИ-ассистенту внешний сервис моделей, поддерживающий OpenAI API. После успешного подключения ИИ-ассистент сможет использовать LLM для разметки и комментирования предупреждений. В списке разметки с помощью ИИ появятся модели доступные пользователю, чей ключ был передан при запуске.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>LLM_URL</code> значение url, по которому контейнер <code>svacer-validation-server</code> сможет подключиться к сервису моделей, совместимому с OpenAI API;<br />
* установить в переменную окружения <code>LLM_TOKEN</code> значение ключа авторизации в сервис моделей;<br />
* при необходимости установить значения переменных <code>REG_TOKEN</code> или <code>REG_LOGIN</code> и <code>REG_PASSWORD</code> содержащих, соответственно, токен авторизации или логин и пароль администратора. Эти данные нужны для запуска компонентов поддержки LLM в ИИ-ассистенте. По умолчанию будут использоваться логин и пароль <code>admin:admin</code>;<br />
* при желании изменить отображаемое название сервиса в интерфейсе выбора моделей, можно установить значение переменной <code>REG_NAME</code>. По умолчанию <code>llm</code>;<br />
* при необходимости ограничения списка доступных моделей, в переменную <code>MODEL_WHITELIST</code> нужно передать список названий моделей разделённых запятыми;<br />
* если производительность сервиса моделей позволяет параллельно обрабатывать несколько предупреждений, то можно установить значение переменной <code>MAX_PARALLEL_REQUESTS</code> в значение больше единицы;<br />
* если производительность модели не позволяет обрабатывать одно предупреждение в минуту, то результаты обработки не будут получены. Чтобы увеличить время ожидания новых результатов модели, можно установить значение переменной <code>MODEL_VALIDATION_MAXATTEMPTS</code> в значение кратное 12 (двенадцати). Например, значение 60 == 5 минут.<br />
<br />
Значения данных переменных могут быть сохранены в <code>.env</code> файл и переданы при запуске с помощью аргумента <code>docker compose --env-file ./.env ... up -d</code><br />
<br />
Описание переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# URL of the OpenAI API-compatible LLM model service<br />
LLM_URL=<br />
<br />
# LLM model service authorization token<br />
LLM_TOKEN=<br />
<br />
# Svacer admin authorization token for the operation of AI-assistant components <br />
# Or with REG_LOGIN and REG_PASSWORD, if token is not set<br />
# REG_TOKEN=<br />
<br />
# Svacer admin login and password for the operation of AI-assistant components<br />
# REG_LOGIN=admin<br />
# REG_PASSWORD=admin<br />
<br />
# ID of the service in the AI-assistant<br />
# REG_ID=llm<br />
<br />
# The name of the service displayed in the AI-assistant<br />
# REG_NAME=llm<br />
<br />
# Service description<br />
# REG_DESCRIPTION="LLM model service"<br />
<br />
# Comma-separated list of available models. If not specified, all models available to the LLM model service user will be available.<br />
# MODEL_WHITELIST=<br />
<br />
# Maximum number of simultaneous requests to the LLM model service<br />
# MAX_PARALLEL_REQUESTS=1<br />
<br />
# Maximum number of 5s attempts to get single warning result from LLM<br />
# MODEL_VALIDATION_MAXATTEMPTS=12<br />
</pre><br />
<br />
== <code>--profile mcp</code> ==<br />
При запуске с данным профилем стартует контейнер с MCP-сервером, подключённый к текущему экземпляру Svacer.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>MCP_PORT</code> номер сетевого порта на котором будет доступен MCP-сервер. По умолчанию будет назначен порт <code>8002</code>;<br />
* установить в переменную окружения <code>SVACER_MPC_TOKEN</code> строку с токеном авторизации, который необходимо будет указать в клиенте MCP-сервера;<br />
* при необходимости доступа к MCP-серверу по адресу отличному от <code>localhost</code> (<code>127.0.0.1</code>) или при использовании DNS необходимо:<br />
** указать необходимый адрес/dns-имя в переменной <code>MCP_ALLOWED_HOSTS</code> в виде <code>172.17.0.1:*</code>/<code>some.domain:*</code>;<br />
** указать необходимый адрес/dns-имя в переменной <code><nowiki>MCP_ALLOWED_ORIGINS</nowiki></code> в виде <code><nowiki>http://172.17.0.1:*</nowiki></code>/<code><nowiki>http://some.domain:*</nowiki></code>;<br />
* при необходимости можно настроить логин и пароль пользователя, от имени которого MCP-сервер будет выполнять запросы к Svacer. По умолчанию <code>admin:admin</code>.<br />
<br />
После запуска mcp-сервер будет доступен по адресу <code><nowiki>http://localhost:{MCP_PORT}/mcp</nowiki></code><br />
<br />
Описание других переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# Bearer token for /mcp clients in HTTP mode. Generate: openssl rand -hex 32<br />
SVACER_MCP_TOKEN=<br />
<br />
# Svacer admin login and password<br />
# SVACER_LOGIN=admin<br />
# SVACER_PASSWORD=admin<br />
<br />
# External port that will be mapped by docker to the internal port 8000<br />
# MCP_PORT=8002<br />
<br />
# DNS rebinding protection for FastMCP<br />
# MCP_ENABLE_DNS_REBINDING_PROTECTION=false<br />
# MCP_ALLOWED_HOSTS=svacer-mcp:*<br />
# MCP_ALLOWED_ORIGINS=http://svacer-mcp:*<br />
<br />
# HTTP timeout for requests to Svacer, seconds<br />
# SVACER_TIMEOUT=30<br />
<br />
# Public URL of this MCP server (used for WWW-Authenticate, RFC 9728).<br />
# Defaults to http://localhost:<SVACER_HTTP_PORT>. Set when running behind a reverse proxy.<br />
# SVACER_MCP_RESOURCE_URL=https://mcp.example.com<br />
<br />
# Subset of tools to register (comma-separated). Unset = all 8 tools.<br />
# Available: get_projects, get_snapshots, get_warnings, get_markers,<br />
# get_project_stats, get_project_groups, get_advanced_file_preview, get_diff<br />
# SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
</pre><br />
<br />
== Удаление демонстрационной версии == <br />
<br />
В процессе запуска демонстрационной версии в docker будут созданы контейнеры, тома, сеть с префиксом <code>svacer-13</code>. Чтобы из удалить, выполните последовательно следующие шаги:<br />
# Остановите и удалите все docker-контейнеры Svacer;<br />
# Удалите тома с данными Svacer;<br />
# Удалите docker-образы демонстрационной версии Svacer;<br />
<br />
=== Остановка и удаление docker-контейнеров Svacer ===<br />
<br />
<pre><br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --profile "*" down<br />
</pre><br />
<br />
После остановки и удаления docker-контейнеров с компонентами Svacer, данные продолжат храниться в docker-томах. Поэтому при повторном запуске демонстрационной версии они будут доступны.<br />
<br />
=== Удаление томов с данными БД, объектного и файлового хранилищ ===<br />
<br />
После выполнения следующей команды все данные накопленные за время работы демонстрационной версии Svacer будут удалены. При повторном запуске будет развёрнута чистая версия системы.<br />
<br />
<pre><br />
docker volume rm svacer-13-ai-postgres svacer-13-object-store svacer-13-postgres svacer-13-snapshot-sources<br />
</pre><br />
<br />
=== Удаление docker-образов ===<br />
<br />
После удаления docker-образов компонентов демонстрационной версии Svacer, при повторном запуске они снова будут загружены из репозитория https://hub.docker.com.<br />
<br />
<pre><br />
docker image rm ispras/svacer:13-alpha ispras/svacerai:13-alpha ispras/svacer-mcp:13-alpha ispras/validation-server:13-alpha<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_deploy&diff=3564Help:13-alpha deploy2026-05-25T10:11:03Z<p>M.vinogradov: Дополнительные уточнения</p>
<hr />
<div>== Демонстрационная сборка ==<br />
<br />
Установка демонстрационной версии Svacer с поддержкой [[Help:13-alpha introduction|описанных функций]] доступна только в докере с использованием docker compose<br />
<br />
== docker compose ==<br />
<br />
Для установки демонстрационной версии подготовлен специальный файл [https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml docker-compose-with-ai-llm-mcp.yml]<br />
<br />
<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml</nowiki><br />
<br />
При запуске Svacer с использованием данного compose-файла доступны профили:<br />
<br />
{| class="wikitable"<br />
! Профиль !! Описание<br />
|-<br />
| Без профиля || Запуск Svacer без поддержки ИИ-ассистента и MCP<br />
|-<br />
| <code>ai</code> || Запуск Svacer с поддержкой ИИ-ассистента со встроенной моделью<br />
|-<br />
| <code>llm</code> || Запуск Svacer с поддержкой ИИ-ассистента и возможностью подключения к нему внешних LLM для разметки предупреждений<br />
|-<br />
| <code>mcp</code> || Запуск Svacer с MCP-сервером <br />
|-<br />
| <code>"*"</code> || Запуск Svacer со всеми доступными профилями<br />
|}<br />
<br />
Для запуска с использованием одного или нескольких профилей используется команда<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml ... --profile llm --profile mcp ... up -d<br />
<br />
При этом необходимо учитывать, что<br />
<br />
* при запуске Svacer без профилей или только с профилем <code>mcp</code> функциональность разметки предупреждений с помощью ИИ будет возвращать ошибку;<br />
<!-- * Профиль <code>no-ai</code> не может быть использован одновременно с другими профилями; --><br />
* запуск с профилями <code>llm</code> и <code>mcp</code> требует настройки переменных окружения (см. ниже).<br />
<br />
Для удобства настройки переменных окружения может использоваться env-файл [https://svacer.ispras.ru/extra/llm-mcp.env llm-mcp.env], который после установки необходимых значений может быть передан команде запуска<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --env-file ./llm-mcp.env ... --profile llm --profile mcp ... up -d<br />
<br />
== <code>--profile ai</code> ==<br />
Данный профиль не требует дополнительной конфигурации для запуска<br />
<br />
== <code>--profile llm</code> ==<br />
Запуск Svacer с данным профилем даёт возможность подключить к ИИ-ассистенту внешний сервис моделей, поддерживающий OpenAI API. После успешного подключения ИИ-ассистент сможет использовать LLM для разметки и комментирования предупреждений. В списке разметки с помощью ИИ появятся модели доступные пользователю, чей ключ был передан при запуске.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>LLM_URL</code> значение url, по которому контейнер <code>svacer-validation-server</code> сможет подключиться к сервису моделей, совместимому с OpenAI API;<br />
* установить в переменную окружения <code>LLM_TOKEN</code> значение ключа авторизации в сервис моделей;<br />
* при необходимости установить значения переменных <code>REG_TOKEN</code> или <code>REG_LOGIN</code> и <code>REG_PASSWORD</code> содержащих, соответственно, токен авторизации или логин и пароль администратора. Эти данные нужны для запуска компонентов поддержки LLM в ИИ-ассистенте. По умолчанию будут использоваться логин и пароль <code>admin:admin</code>;<br />
* при желании изменить отображаемое название сервиса в интерфейсе выбора моделей, можно установить значение переменной <code>REG_NAME</code>. По умолчанию <code>llm</code>;<br />
* при необходимости ограничения списка доступных моделей, в переменную <code>MODEL_WHITELIST</code> нужно передать список названий моделей разделённых запятыми;<br />
* если производительность сервиса моделей позволяет параллельно обрабатывать несколько предупреждений, то можно установить значение переменной <code>MAX_PARALLEL_REQUESTS</code> в значение больше единицы;<br />
* если производительность модели не позволяет обрабатывать одно предупреждение в минуту, то результаты обработки не будут получены. Чтобы увеличить время ожидания новых результатов модели, можно установить значение переменной <code>MODEL_VALIDATION_MAXATTEMPTS</code> в значение кратное 12 (двенадцати). Например, значение 60 == 5 минут.<br />
<br />
Значения данных переменных могут быть сохранены в <code>.env</code> файл и переданы при запуске с помощью аргумента <code>docker compose --env-file ./.env ... up -d</code><br />
<br />
Описание переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# URL of the OpenAI API-compatible LLM model service<br />
LLM_URL=<br />
<br />
# LLM model service authorization token<br />
LLM_TOKEN=<br />
<br />
# Svacer admin authorization token for the operation of AI-assistant components <br />
# Or with REG_LOGIN and REG_PASSWORD, if token is not set<br />
# REG_TOKEN=<br />
<br />
# Svacer admin login and password for the operation of AI-assistant components<br />
# REG_LOGIN=admin<br />
# REG_PASSWORD=admin<br />
<br />
# ID of the service in the AI-assistant<br />
# REG_ID=llm<br />
<br />
# The name of the service displayed in the AI-assistant<br />
# REG_NAME=llm<br />
<br />
# Service description<br />
# REG_DESCRIPTION="LLM model service"<br />
<br />
# Comma-separated list of available models. If not specified, all models available to the LLM model service user will be available.<br />
# MODEL_WHITELIST=<br />
<br />
# Maximum number of simultaneous requests to the LLM model service<br />
# MAX_PARALLEL_REQUESTS=1<br />
<br />
# Maximum number of 5s attempts to get single warning result from LLM<br />
# MODEL_VALIDATION_MAXATTEMPTS=12<br />
</pre><br />
<br />
== <code>--profile mcp</code> ==<br />
При запуске с данным профилем стартует контейнер с MCP-сервером, подключённый к текущему экземпляру Svacer.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>MCP_PORT</code> номер сетевого порта на котором будет доступен MCP-сервер. По умолчанию будет назначен порт <code>8002</code>;<br />
* установить в переменную окружения <code>SVACER_MPC_TOKEN</code> строку с токеном авторизации, который необходимо будет указать в клиенте MCP-сервера;<br />
* при необходимости доступа к MCP-серверу по адресу отличному от <code>localhost</code> (<code>127.0.0.1</code>) или при использовании DNS необходимо:<br />
** указать необходимый адрес/dns-имя в переменной <code>MCP_ALLOWED_HOSTS</code> в виде <code>172.17.0.1:*</code>/<code>some.domain:*</code>;<br />
** указать необходимый адрес/dns-имя в переменной <code><nowiki>MCP_ALLOWED_ORIGINS</nowiki></code> в виде <code><nowiki>http://172.17.0.1:*</nowiki></code>/<code><nowiki>http://some.domain:*</nowiki></code>;<br />
* при необходимости можно настроить логин и пароль пользователя, от имени которого MCP-сервер будет выполнять запросы к Svacer. По умолчанию <code>admin:admin</code>.<br />
<br />
После запуска mcp-сервер будет доступен по адресу <code><nowiki>http://localhost:{MCP_PORT}/mcp</nowiki></code><br />
<br />
Описание других переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# Bearer token for /mcp clients in HTTP mode. Generate: openssl rand -hex 32<br />
SVACER_MCP_TOKEN=<br />
<br />
# Svacer admin login and password<br />
# SVACER_LOGIN=admin<br />
# SVACER_PASSWORD=admin<br />
<br />
# External port that will be mapped by docker to the internal port 8000<br />
# MCP_PORT=8002<br />
<br />
# DNS rebinding protection for FastMCP<br />
# MCP_ENABLE_DNS_REBINDING_PROTECTION=false<br />
# MCP_ALLOWED_HOSTS=svacer-mcp:*<br />
# MCP_ALLOWED_ORIGINS=http://svacer-mcp:*<br />
<br />
# HTTP timeout for requests to Svacer, seconds<br />
# SVACER_TIMEOUT=30<br />
<br />
# Public URL of this MCP server (used for WWW-Authenticate, RFC 9728).<br />
# Defaults to http://localhost:<SVACER_HTTP_PORT>. Set when running behind a reverse proxy.<br />
# SVACER_MCP_RESOURCE_URL=https://mcp.example.com<br />
<br />
# Subset of tools to register (comma-separated). Unset = all 8 tools.<br />
# Available: get_projects, get_snapshots, get_warnings, get_markers,<br />
# get_project_stats, get_project_groups, get_advanced_file_preview, get_diff<br />
# SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_deploy&diff=3561Help:13-alpha deploy2026-05-25T07:45:08Z<p>M.vinogradov: удалена лишняя строка</p>
<hr />
<div>== Демонстрационная сборка ==<br />
<br />
Установка демонстрационной версии Svacer с поддержкой [[Help:13-alpha introduction|описанных функций]] доступна только в докере с использованием docker compose<br />
<br />
== docker compose ==<br />
<br />
Для установки демонстрационной версии подготовлен специальный файл [https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml docker-compose-with-ai-llm-mcp.yml]<br />
<br />
<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml</nowiki><br />
<br />
При запуске Svacer с использованием данного compose-файла доступны профили:<br />
<br />
{| class="wikitable"<br />
! Профиль !! Описание<br />
|-<br />
| Без профиля || Запуск Svacer без поддержки ИИ-ассистента и MCP<br />
|-<br />
| <code>ai</code> || Запуск Svacer с поддержкой ИИ-ассистента со встроенной моделью<br />
|-<br />
| <code>llm</code> || Запуск Svacer с поддержкой ИИ-ассистента и возможностью подключения к нему внешних LLM для разметки предупреждений<br />
|-<br />
| <code>mcp</code> || Запуск Svacer с MCP-сервером <br />
|}<br />
<br />
Для запуска с использованием одного или нескольких профилей используется команда<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml ... --profile llm --profile mcp ... up -d<br />
<br />
При этом необходимо учитывать, что<br />
<br />
* при запуске Svacer без профилей или только с профилем <code>mcp</code> функциональность разметки предупреждений с помощью ИИ будет возвращать ошибку;<br />
<!-- * Профиль <code>no-ai</code> не может быть использован одновременно с другими профилями; --><br />
* запуск с профилями <code>llm</code> и <code>mcp</code> требует настройки переменных окружения (см. ниже).<br />
<br />
Для удобства настройки переменных окружения может использоваться env-файл [https://svacer.ispras.ru/extra/llm-mcp.env llm-mcp.env], который после установки необходимых значений может быть передан команде запуска<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --env-file ./llm-mcp.env ... --profile llm --profile mcp ... up -d<br />
<br />
<!-- == <code>--profile no-ai</code> == --><br />
<!-- Данный профиль не требует дополнительной конфигурации для запуска --><br />
== <code>--profile llm</code> ==<br />
Запуск Svacer с данным профилем даёт возможность подключить к ИИ-ассистенту внешний сервис моделей, поддерживающий OpenAI API. После успешного подключения ИИ-ассистент сможет использовать LLM для разметки и комментирования предупреждений. В списке разметки с помощью ИИ появятся модели доступные пользователю, чей ключ был передан при запуске.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>LLM_URL</code> значение url, по которому контейнер <code>svacer-validation-server</code> сможет подключиться к сервису моделей, совместимому с OpenAI API;<br />
* установить в переменную окружения <code>LLM_TOKEN</code> значение ключа авторизации в сервис моделей;<br />
* при необходимости установить значения переменных <code>REG_TOKEN</code> или <code>REG_LOGIN</code> и <code>REG_PASSWORD</code> содержащих, соответственно, токен авторизации или логин и пароль администратора. Эти данные нужны для запуска компонентов поддержки LLM в ИИ-ассистенте. По умолчанию будут использоваться логин и пароль <code>admin:admin</code>;<br />
* при желании изменить отображаемое название сервиса в интерфейсе выбора моделей, можно установить значение переменной <code>REG_NAME</code>. По умолчанию: <code>llm</code>;<br />
* при необходимости ограничения списка доступных моделей, в переменную <code>MODEL_WHITELIST</code> нужно передать список названий моделей разделённых запятыми;<br />
* если производительность сервиса моделей позволяет параллельно обрабатывать несколько предупреждений, то можно установить значение переменной <code>MAX_PARALLEL_REQUESTS</code> в значение больше единицы;<br />
* если производительность модели не позволяет обрабатывать одно предупреждение в минуту, то результаты обработки не будут получены. Чтобы увеличить время ожидания новых результатов модели, можно установить значение переменной <code>MODEL_VALIDATION_MAXATTEMPTS</code> в значение кратное 12 (двенадцати). Например, значение 60 == 5 минут.<br />
<br />
Значения данных переменных могут быть сохранены в <code>.env</code> файл и переданы при запуске с помощью аргумента <code>docker compose --env-file ./.env ... up -d</code><br />
<br />
Описание переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# URL of the OpenAI API-compatible LLM hosting service<br />
LLM_URL=<br />
<br />
# LLM hosting service authorization token<br />
LLM_TOKEN=<br />
<br />
# Svacer admin authorization token, which will be used to perform LLM service registration requests in the AI assistant. <br />
# Or with REG_LOGIN and REG_PASSWORD, if token is not set<br />
# REG_TOKEN=<br />
<br />
# Svacer admin login and password<br />
# REG_LOGIN=admin<br />
# REG_PASSWORD=admin<br />
<br />
# ID of the service in the AI assistant<br />
# REG_ID=llm<br />
<br />
# The name of the service displayed in the AI assistant<br />
# REG_NAME=llm<br />
<br />
# Service description<br />
# REG_DESCRIPTION="LLM hosting service"<br />
<br />
# Comma-separated list of available models. If not specified, all models available to the LLM hosting service user will be available.<br />
# MODEL_WHITELIST=<br />
<br />
# Maximum number of simultaneous requests to process warning with LLM<br />
# MAX_PARALLEL_REQUESTS=1<br />
<br />
# Maximum number of 5s attempts to get single warning result from LLM<br />
# MODEL_VALIDATION_MAXATTEMPTS=12<br />
</pre><br />
<br />
== <code>--profile mcp</code> ==<br />
При запуске с данным профилем стартует контейнер с MCP-сервером, подключённый к текущему экземпляру Svacer.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>MCP_PORT</code> номер сетевого порта на котором будет доступен MCP-сервер. По умолчанию будет назначен порт <code>8002</code><br />
* установить в переменную окружения <code>SVACER_MPC_TOKEN</code> строку с токеном авторизации, который необходимо будет указать в клиенте MCP-сервера;<br />
* при необходимости доступа к MCP-серверу по адресу отличному от <code>localhost</code> (<code>127.0.0.1</code>) или при использовании DNS необходимо:<br />
** указать необходимый адрес/dns-имя в переменной <code>MCP_ALLOWED_HOSTS</code> в виде <code>172.17.0.1:*</code>/<code>some.domain:*</code><br />
** указать необходимый адрес/dns-имя в переменной <code><nowiki>MCP_ALLOWED_ORIGINS</nowiki></code> в виде <code><nowiki>http://172.17.0.1:*</nowiki></code>/<code><nowiki>http://some.domain:*</nowiki></code><br />
* при необходимости можно настроить логин и пароль пользователя, от имени которого MCP-сервер будет выполнять запросы к Svacer. По умолчанию: <code>admin:admin</code><br />
После запуска mcp-сервер будет доступен по адресу <code><nowiki>http://localhost:{MCP_PORT}/mcp</nowiki></code><br />
<br />
Описание других переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# Bearer token for /mcp clients in HTTP mode. Generate: openssl rand -hex 32<br />
SVACER_MCP_TOKEN=<br />
<br />
# Svacer admin login and password<br />
SVACER_LOGIN=admin<br />
SVACER_PASSWORD=admin<br />
<br />
# External port that will be mapped by docker to the internal port 8000<br />
MCP_PORT=8002<br />
<br />
MCP_ALLOWED_HOSTS=172.17.0.1:*<br />
MCP_ALLOWED_ORIGINS=http://172.17.0.1:*<br />
<br />
# Svacer server (container) URL<br />
# SVACER_URL=http://svacer:8080<br />
<br />
# HTTP timeout for requests to Svacer, seconds<br />
# SVACER_TIMEOUT=30<br />
<br />
# Public URL of this MCP server (used for WWW-Authenticate, RFC 9728).<br />
# Defaults to http://localhost:<SVACER_HTTP_PORT>. Set when running behind a reverse proxy.<br />
# SVACER_MCP_RESOURCE_URL=https://mcp.example.com<br />
<br />
# Subset of tools to register (comma-separated). Unset = all 8 tools.<br />
# Available: get_projects, get_snapshots, get_warnings, get_markers,<br />
# get_project_stats, get_project_groups, get_advanced_file_preview, get_diff<br />
# SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_deploy&diff=3557Help:13-alpha deploy2026-05-25T06:48:39Z<p>M.vinogradov: initial version</p>
<hr />
<div>== Демонстрационная сборка ==<br />
<br />
Установка демонстрационной версии Svacer с поддержкой [[Help:13-alpha_introduction|описанных функций]] доступна только в докере с использованием docker compose<br />
<br />
== docker compose ==<br />
<br />
Для установки демонстрационной версии подготовлен специальный файл [https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml docker-compose-with-ai-llm-mcp.yml]<br />
<br />
<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml</nowiki><br />
<br />
При запуске Svacer с использованием данного compose-файла доступны профили:<br />
<br />
{| class="wikitable"<br />
! Профиль !! Описание<br />
|-<br />
| Без профиля || Запуск Svacer без поддержки ИИ-ассистента и MCP<br />
|-<br />
| <code>ai</code> || Запуск Svacer с поддержкой ИИ-ассистента со встроенной моделью<br />
|-<br />
| <code>llm</code> || Запуск Svacer с поддержкой ИИ-ассистента и возможностью подключения к нему внешних LLM для разметки предупреждений<br />
|-<br />
| <code>mcp</code> || Запуск Svacer с MCP-сервером <br />
|}<br />
<br />
Для запуска с использованием одного или нескольких профилей используется команда<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml ... --profile llm --profile mcp ... up -d<br />
<br />
При этом необходимо учитывать, что<br />
<br />
* при запуске Svacer без профилей или только с профилем <code>mcp</code> функциональность разметки предупреждений с помощью ИИ будет возвращать ошибку;<br />
<!-- * Профиль <code>no-ai</code> не может быть использован одновременно с другими профилями; --><br />
* запуск с профилями <code>llm</code> и <code>mcp</code> требует настройки переменных окружения (см. ниже).<br />
<br />
Для удобства настройки переменных окружения может использоваться env-файл [https://svacer.ispras.ru/extra/llm-mcp.env llm-mcp.env], который после установки необходимых значений может быть передан команде запуска<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --env-file ./llm-mcp.env ... --profile llm --profile mcp ... up -d<br />
<br />
<!-- == <code>--profile no-ai</code> == --><br />
<!-- Данный профиль не требует дополнительной конфигурации для запуска --><br />
== <code>--profile llm</code> ==<br />
Запуск Svacer с данным профилем даёт возможность подключить к ИИ-ассистенту внешний сервис моделей, поддерживающий OpenAI API. После успешного подключения ИИ-ассистент сможет использовать LLM для разметки и комментирования предупреждений. В списке разметки с помощью ИИ появятся модели доступные пользователю, чей ключ был передан при запуске.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>LLM_URL</code> значение url по которому контейнер <code>svacer-validation-server</code> сможет подключиться к сервису моделей, совместимому с OpenAI API;<br />
* установить в переменную окружения <code>LLM_TOKEN</code> значение ключа авторизации в сервис моделей;<br />
* при необходимости установить значения переменных <code>REG_TOKEN</code> или <code>REG_LOGIN</code> и <code>REG_PASSWORD</code> содержащих, соответственно, токен авторизации или логин и пароль администратора. Эти данные нужны для запуска компонентов поддержки LLM в ИИ-ассистенте. По умолчанию будут использоваться логин и пароль <code>admin:admin</code>;<br />
* при желании изменить отображаемое название сервиса в интерфейсе выбора моделей, можно установить значение переменной <code>REG_NAME</code>. По умолчанию: <code>llm</code>;<br />
* при необходимости ограничения списка доступных моделей, в переменную <code>MODEL_WHITELIST</code> нужно передать список названий моделей разделённых запятыми;<br />
* если производительность сервиса моделей позволяет параллельно обрабатывать несколько предупреждений, то можно установить значение переменной <code>MAX_PARALLEL_REQUESTS</code> в значение больше единицы;<br />
* если производительность модели не позволяет обрабатывать одно предупреждение в минуту, то результаты обработки не будут получены. Чтобы увеличить время ожидания новых результатов модели, можно установить значение переменной <code>MODEL_VALIDATION_MAXATTEMPTS</code> в значение кратное 12 (двенадцати). Например: значение 60 == 5 минут.<br />
<br />
В процессе обработки набора маркеров с помощью LLM ИИ-ассистент ожидает, что за минуту будет обрабатываться хотя бы один маркер. Если в течение минуты не появятся новы<br />
<br />
Значения данных переменных могут быть сохранены в <code>.env</code> файл и переданы при запуске с помощью аргумента <code>docker compose --env-file ./.env ... up -d</code><br />
<br />
Описание переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# URL of the OpenAI API-compatible LLM hosting service<br />
LLM_URL=<br />
<br />
# LLM hosting service authorization token<br />
LLM_TOKEN=<br />
<br />
# Svacer admin authorization token, which will be used to perform LLM service registration requests in the AI assistant. <br />
# Or with REG_LOGIN and REG_PASSWORD, if token is not set<br />
# REG_TOKEN=<br />
<br />
# Svacer admin login and password<br />
# REG_LOGIN=admin<br />
# REG_PASSWORD=admin<br />
<br />
# ID of the service in the AI assistant<br />
# REG_ID=llm<br />
<br />
# The name of the service displayed in the AI assistant<br />
# REG_NAME=llm<br />
<br />
# Service description<br />
# REG_DESCRIPTION="LLM hosting service"<br />
<br />
# Comma-separated list of available models. If not specified, all models available to the LLM hosting service user will be available.<br />
# MODEL_WHITELIST=<br />
<br />
# Maximum number of simultaneous requests to process warning with LLM<br />
# MAX_PARALLEL_REQUESTS=1<br />
<br />
# Maximum number of 5s attempts to get single warning result from LLM<br />
# MODEL_VALIDATION_MAXATTEMPTS=12<br />
</pre><br />
<br />
== <code>--profile mcp</code> ==<br />
При запуске с данным профилем стартует контейнер с MCP-сервером подключённый к текущему экземпляру Svacer.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>MCP_PORT</code> номер сетевого порта на котором будет доступен MCP-сервер. По умолчанию будет назначен порт <code>8002</code>.<br />
* установить в переменную окружения <code>SVACER_MPC_TOKEN</code> строку с токеном авторизации, который необходимо будет указать в клиенте MCP-сервера;<br />
* при необходимости доступа к MCP-серверу по адресу отличному от <code>localhost</code> (<code>127.0.0.1</code>) или при использовании DNS необходимо:<br />
** указать необходимый адрес/dns-имя в переменной <code>MCP_ALLOWED_HOSTS</code> в виде <code>172.17.0.1:*</code>/<code>some.domain:*</code><br />
** указать необходимый адрес/dns-имя в переменной <code><nowiki>MCP_ALLOWED_ORIGINS</nowiki></code> в виде <code><nowiki>http://172.17.0.1:*</nowiki></code>/<code><nowiki>http://some.domain:*</nowiki></code><br />
* При необходимости можно настроить логин и пароль пользователя, от имени которого mcp-сервер будет выполнять запросы к Svacer. По умолчанию: <code>admin:admin</code><br />
<br />
После запуска mcp-сервер будет доступен по адресу <code><nowiki>http://localhost:{MCP_PORT}/mcp</nowiki></code><br />
<br />
Описание других переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# Bearer token for /mcp clients in HTTP mode. Generate: openssl rand -hex 32<br />
SVACER_MCP_TOKEN=<br />
<br />
# Svacer admin login and password<br />
SVACER_LOGIN=admin<br />
SVACER_PASSWORD=admin<br />
<br />
# External port that will be mapped by docker to the internal port 8000<br />
MCP_PORT=8002<br />
<br />
MCP_ALLOWED_HOSTS=172.17.0.1:*<br />
MCP_ALLOWED_ORIGINS=http://172.17.0.1:*<br />
<br />
# Svacer server (container) URL<br />
# SVACER_URL=http://svacer:8080<br />
<br />
# HTTP timeout for requests to Svacer, seconds<br />
# SVACER_TIMEOUT=30<br />
<br />
# Public URL of this MCP server (used for WWW-Authenticate, RFC 9728).<br />
# Defaults to http://localhost:<SVACER_HTTP_PORT>. Set when running behind a reverse proxy.<br />
# SVACER_MCP_RESOURCE_URL=https://mcp.example.com<br />
<br />
# Subset of tools to register (comma-separated). Unset = all 8 tools.<br />
# Available: get_projects, get_snapshots, get_warnings, get_markers,<br />
# get_project_stats, get_project_groups, get_advanced_file_preview, get_diff<br />
# SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_installation&diff=3556Help:13-alpha installation2026-05-25T06:47:52Z<p>M.vinogradov: initial version</p>
<hr />
<div>== Демонстрационная сборка ==<br />
<br />
Установка демонстрационной версии Svacer с поддержкой [[Help:13-alpha_introduction|описанных функций]] доступна только в докере с использованием docker compose<br />
<br />
== docker compose ==<br />
<br />
Для установки демонстрационной версии подготовлен специальный файл [https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml docker-compose-with-ai-llm-mcp.yml]<br />
<br />
<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose-with-ai-llm-mcp.yml</nowiki><br />
<br />
При запуске Svacer с использованием данного compose-файла доступны профили:<br />
<br />
{| class="wikitable"<br />
! Профиль !! Описание<br />
|-<br />
| Без профиля || Запуск Svacer без поддержки ИИ-ассистента и MCP<br />
|-<br />
| <code>ai</code> || Запуск Svacer с поддержкой ИИ-ассистента со встроенной моделью<br />
|-<br />
| <code>llm</code> || Запуск Svacer с поддержкой ИИ-ассистента и возможностью подключения к нему внешних LLM для разметки предупреждений<br />
|-<br />
| <code>mcp</code> || Запуск Svacer с MCP-сервером <br />
|}<br />
<br />
Для запуска с использованием одного или нескольких профилей используется команда<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml ... --profile llm --profile mcp ... up -d<br />
<br />
При этом необходимо учитывать, что<br />
<br />
* при запуске Svacer без профилей или только с профилем <code>mcp</code> функциональность разметки предупреждений с помощью ИИ будет возвращать ошибку;<br />
<!-- * Профиль <code>no-ai</code> не может быть использован одновременно с другими профилями; --><br />
* запуск с профилями <code>llm</code> и <code>mcp</code> требует настройки переменных окружения (см. ниже).<br />
<br />
Для удобства настройки переменных окружения может использоваться env-файл [https://svacer.ispras.ru/extra/llm-mcp.env llm-mcp.env], который после установки необходимых значений может быть передан команде запуска<br />
<br />
docker compose -f docker-compose-with-ai-llm-mcp.yml --env-file ./llm-mcp.env ... --profile llm --profile mcp ... up -d<br />
<br />
<!-- == <code>--profile no-ai</code> == --><br />
<!-- Данный профиль не требует дополнительной конфигурации для запуска --><br />
== <code>--profile llm</code> ==<br />
Запуск Svacer с данным профилем даёт возможность подключить к ИИ-ассистенту внешний сервис моделей, поддерживающий OpenAI API. После успешного подключения ИИ-ассистент сможет использовать LLM для разметки и комментирования предупреждений. В списке разметки с помощью ИИ появятся модели доступные пользователю, чей ключ был передан при запуске.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>LLM_URL</code> значение url по которому контейнер <code>svacer-validation-server</code> сможет подключиться к сервису моделей, совместимому с OpenAI API;<br />
* установить в переменную окружения <code>LLM_TOKEN</code> значение ключа авторизации в сервис моделей;<br />
* при необходимости установить значения переменных <code>REG_TOKEN</code> или <code>REG_LOGIN</code> и <code>REG_PASSWORD</code> содержащих, соответственно, токен авторизации или логин и пароль администратора. Эти данные нужны для запуска компонентов поддержки LLM в ИИ-ассистенте. По умолчанию будут использоваться логин и пароль <code>admin:admin</code>;<br />
* при желании изменить отображаемое название сервиса в интерфейсе выбора моделей, можно установить значение переменной <code>REG_NAME</code>. По умолчанию: <code>llm</code>;<br />
* при необходимости ограничения списка доступных моделей, в переменную <code>MODEL_WHITELIST</code> нужно передать список названий моделей разделённых запятыми;<br />
* если производительность сервиса моделей позволяет параллельно обрабатывать несколько предупреждений, то можно установить значение переменной <code>MAX_PARALLEL_REQUESTS</code> в значение больше единицы;<br />
* если производительность модели не позволяет обрабатывать одно предупреждение в минуту, то результаты обработки не будут получены. Чтобы увеличить время ожидания новых результатов модели, можно установить значение переменной <code>MODEL_VALIDATION_MAXATTEMPTS</code> в значение кратное 12 (двенадцати). Например: значение 60 == 5 минут.<br />
<br />
В процессе обработки набора маркеров с помощью LLM ИИ-ассистент ожидает, что за минуту будет обрабатываться хотя бы один маркер. Если в течение минуты не появятся новы<br />
<br />
Значения данных переменных могут быть сохранены в <code>.env</code> файл и переданы при запуске с помощью аргумента <code>docker compose --env-file ./.env ... up -d</code><br />
<br />
Описание переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# URL of the OpenAI API-compatible LLM hosting service<br />
LLM_URL=<br />
<br />
# LLM hosting service authorization token<br />
LLM_TOKEN=<br />
<br />
# Svacer admin authorization token, which will be used to perform LLM service registration requests in the AI assistant. <br />
# Or with REG_LOGIN and REG_PASSWORD, if token is not set<br />
# REG_TOKEN=<br />
<br />
# Svacer admin login and password<br />
# REG_LOGIN=admin<br />
# REG_PASSWORD=admin<br />
<br />
# ID of the service in the AI assistant<br />
# REG_ID=llm<br />
<br />
# The name of the service displayed in the AI assistant<br />
# REG_NAME=llm<br />
<br />
# Service description<br />
# REG_DESCRIPTION="LLM hosting service"<br />
<br />
# Comma-separated list of available models. If not specified, all models available to the LLM hosting service user will be available.<br />
# MODEL_WHITELIST=<br />
<br />
# Maximum number of simultaneous requests to process warning with LLM<br />
# MAX_PARALLEL_REQUESTS=1<br />
<br />
# Maximum number of 5s attempts to get single warning result from LLM<br />
# MODEL_VALIDATION_MAXATTEMPTS=12<br />
</pre><br />
<br />
== <code>--profile mcp</code> ==<br />
При запуске с данным профилем стартует контейнер с MCP-сервером подключённый к текущему экземпляру Svacer.<br />
<br />
При запуске Svacer с профилем <code>llm</code> необходимо:<br />
* установить в переменную окружения <code>MCP_PORT</code> номер сетевого порта на котором будет доступен MCP-сервер. По умолчанию будет назначен порт <code>8002</code>.<br />
* установить в переменную окружения <code>SVACER_MPC_TOKEN</code> строку с токеном авторизации, который необходимо будет указать в клиенте MCP-сервера;<br />
* при необходимости доступа к MCP-серверу по адресу отличному от <code>localhost</code> (<code>127.0.0.1</code>) или при использовании DNS необходимо:<br />
** указать необходимый адрес/dns-имя в переменной <code>MCP_ALLOWED_HOSTS</code> в виде <code>172.17.0.1:*</code>/<code>some.domain:*</code><br />
** указать необходимый адрес/dns-имя в переменной <code><nowiki>MCP_ALLOWED_ORIGINS</nowiki></code> в виде <code><nowiki>http://172.17.0.1:*</nowiki></code>/<code><nowiki>http://some.domain:*</nowiki></code><br />
* При необходимости можно настроить логин и пароль пользователя, от имени которого mcp-сервер будет выполнять запросы к Svacer. По умолчанию: <code>admin:admin</code><br />
<br />
После запуска mcp-сервер будет доступен по адресу <code><nowiki>http://localhost:{MCP_PORT}/mcp</nowiki></code><br />
<br />
Описание других переменных доступных для конфигурации запуска ИИ-ассистента с поддержкой внешнего сервиса моделей:<br />
<pre><br />
# Bearer token for /mcp clients in HTTP mode. Generate: openssl rand -hex 32<br />
SVACER_MCP_TOKEN=<br />
<br />
# Svacer admin login and password<br />
SVACER_LOGIN=admin<br />
SVACER_PASSWORD=admin<br />
<br />
# External port that will be mapped by docker to the internal port 8000<br />
MCP_PORT=8002<br />
<br />
MCP_ALLOWED_HOSTS=172.17.0.1:*<br />
MCP_ALLOWED_ORIGINS=http://172.17.0.1:*<br />
<br />
# Svacer server (container) URL<br />
# SVACER_URL=http://svacer:8080<br />
<br />
# HTTP timeout for requests to Svacer, seconds<br />
# SVACER_TIMEOUT=30<br />
<br />
# Public URL of this MCP server (used for WWW-Authenticate, RFC 9728).<br />
# Defaults to http://localhost:<SVACER_HTTP_PORT>. Set when running behind a reverse proxy.<br />
# SVACER_MCP_RESOURCE_URL=https://mcp.example.com<br />
<br />
# Subset of tools to register (comma-separated). Unset = all 8 tools.<br />
# Available: get_projects, get_snapshots, get_warnings, get_markers,<br />
# get_project_stats, get_project_groups, get_advanced_file_preview, get_diff<br />
# SVACER_TOOLS=get_projects,get_snapshots,get_markers<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&diff=3424Help:XSvacer:AIAssistant2025-12-01T08:59:49Z<p>M.vinogradov: Remove description of old (separate) AI-assistant version. Add deployment manual</p>
<hr />
<div>{{Note|type=warn|text='''Disclaimer'''<br />
* Это экспериментальная Proof of Concept версия, предоставляемая для ознакомления по принципу "как есть". <br />
* Данная функциональность не связана с [https://svace.pages.ispras.ru/svace-website/2025/02/21/ai-assistant.html AI-ассистентом из анализатора Svace]. Функционал AI-ассистента из анализатора Svace будет интегрирован в Svacer в будущих версиях сервера.}}<br />
<br />
== Поддержка ИИ-ассистента для разметки предупреждений ==<br />
Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.<br />
<br />
ИИ-ассистент предназначен для разметки предупреждений статусами <code style="white-space: pre;">Confirmed</code> и <code style="white-space: pre;">False Positive</code>, которые были предсказаны моделью машинного обучения.<br />
<br />
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.<br />
<br />
== Активация и запуск ИИ-ассистента ==<br />
<br />
ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его работы необходимо:<br />
<br />
# Запустить docker-контейнер с моделью машинного обучения<br />
# При необходимости: развернуть PostgreSQL-сервер для хранения базы данных ИИ-ассистента<br />
# Запустить сервис ИИ-ассистента<br />
# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-ассистенту<br />
<br />
=== docker compose ===<br />
Самый простой способ деплоя — развернуть всё в докер-контейнерах, воспользовавшиcь подготовленным нами [https://svacer.ispras.ru/extra/docker-compose-with-ai.yml docker-compose] файлом:<br />
<br />
<nowiki>curl -LO https://svacer.ispras.ru/extra/docker-compose-with-ai.yml</nowiki><br />
docker compose -f docker-compose-with-ai.yml up -d<br />
<br />
=== deb/rpm ===<br />
Если Svacer установлен из deb/rpm пакета:<br />
<br />
1. Запустите docker-контейнер с моделью машинного обучения<br />
<br />
docker run --rm -d --name svacerai-model -p 8000:8000 ispras/svacerai-model:latest<br />
<br />
2. В PostgreSQL создайте отдельную БД для ИИ-сервера, запустив psql-консоль и выполнив команды:<br />
<br />
sudo su -l postgres<br />
psql<br />
postgres=# create database svacerai;<br />
postgres=# grant all privileges on database svacerai to svace;<br />
<br />
(предполагается, что пользователь <code>svace</code> уже [[Help:Installation#deb/rpm|был создан]] для сервера Svacer)<br />
<br />
3. В конфиг-файле ИИ-сервера <code>/etc/default/svacerai</code> укажите аргументы запуска<br />
<br />
<pre><br />
# URL подключения к БД из второго шага<br />
SVACERAI_PG_URL="postgres://svace:svace@127.0.0.1:5432/svacerai?sslmode=disable"<br />
<br />
# адрес и порт модели из первого шага<br />
SVACERAI_MODEL_URL="server-status:http://localhost:8000"<br />
<br />
# интерфейс и порт, на котором будет запущен ИИ-сервер<br />
SVACERAI_HOST="0.0.0.0:7001"<br />
<br />
# URL сервера Svacer, который будет подключен к ИИ-серверу<br />
SVACER_HOST="http://localhost:8080"<br />
</pre><br />
<br />
4. Запустите systemd-сервис ИИ-сервера<br />
<br />
systemctl start svacerai<br />
<br />
5. В конфиг-файле сервера Svacer <code>/etc/default/svacer</code> включите фичу ИИ-ассистента, добавив флаг <code>--xsvacer.features aiAssistant</code> и укажите URL ИИ-сервера<br />
<br />
<pre><br />
SVACER_ARGS="--pg ... --store ... --xsvacer.features aiAssistant"<br />
<br />
# соответствует переменной SVACERAI_HOST из шага 3<br />
XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://localhost:7001/<br />
</pre><br />
<br />
6. Перезапустите сервер Svacer<br />
<br />
systemctl restart svacer<br />
<br />
== Дополнительная конфигурация ==<br />
=== Подключение к серверу ИИ-ассистента ===<br />
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code>. Изменить этот адрес можно одним из способов:<br />
<br />
# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистента}:{порт}/</nowiki></code><br />
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел<br />
<br />
<pre style="white-space: pre;"><br />
...<br />
xsvacer:<br />
...<br />
aiAssistant:<br />
assistantHostUrl: http://{адрес ИИ-ассистента}:{порт}/<br />
...<br />
</pre><br />
<br />
==== Запуск docker-контейнера с моделью машинного обучения ====<br />
При запуске докер-контейнера с ИИ-моделью, можно создать и примонтировать вольюмы для постоянного хранения базы данных и кэша:<br />
<br />
docker volume create svacer-ai-cache<br />
docker volume create svacer-ai-pgdata<br />
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<br />
<br />
* Вольюм <code style="white-space: pre;">cache</code> будет содержать кэш сервиса взаимодействия с моделью машинного обучения<br />
* Вольюм <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ PostgreSQL<br />
<br />
=== Флаги команды запуска ИИ-ассистента ===<br />
<br />
Глобальные флаги <code>svacerai-server help</code><br />
<br />
NAME:<br />
svacerai-server - Svace AI server<br />
<br />
USAGE:<br />
svacerai-server [global options] command [command options] [arguments...]<br />
<br />
COMMANDS:<br />
run<br />
help, h Shows a list of commands or help for one command<br />
<br />
GLOBAL OPTIONS:<br />
--debug (default: false) [$SVACER_AI_DEBUG]<br />
--log-level value Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]<br />
--log value Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.<br />
--config value Define path to file with config in YAML format (by default svacer-ai.cfg).<br />
--help, -h show help<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|debug<br />
|bool<br />
|Отладочный режим логирования<br />
|-<br />
|log-level<br />
|string<br />
|Уровень логирования<br />
|-<br />
|log<br />
|string<br />
|Путь к файлу с логами<br />
|-<br />
|config<br />
|string<br />
|Путь к [[#Конфигурация по умолчанию|конфигурационному файлу]]<br />
|}<br />
<br />
Флаги запуска ИИ-ассистента <code>svacerai-server run help</code><br />
<br />
NAME:<br />
svacerai-server run<br />
<br />
USAGE:<br />
svacerai-server run [command options] [arguments...]<br />
<br />
OPTIONS:<br />
--pg value Defines PostgreSQL connection URL<br />
--host value Defines host name for the server<br />
--svacer-host value Defines remote Svacer host<br />
--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><br />
--help, -h show help<br />
<br />
{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Формат<br />
|-<br />
|style="width: 80px"|pg<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS<br />
|-<br />
|host<br />
|string<br />
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент<br />
|<code>{ip адрес}:{порт}</code><br />
|-<br />
|svacer-host<br />
|string<br />
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент<br />
|https://en.wikipedia.org/wiki/URL#Syntax<br />
|-<br />
|ai-host<br />
|[]string<br />
|Список адресов сервисов с моделями машинного обучения. <code>host-id</code> — идентификатор сервиса моделей в [[#Конфигурация по умолчанию|конфигурации]]<br />
|<code><nowiki>{host id}:{url сервиса моделей}</nowiki></code><br />
|}<br />
<br />
{{Note|text=При использовании [[#Конфигурация по умолчанию|конфигурации по умолчанию]], <code>{host id}</code> должен быть равен <code>server-status</code>}}<br />
<br />
Пример:<br />
<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><br />
<br />
=== Конфигурация ИИ-ассистента ===<br />
<br />
Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|db/url<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|<code>postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable</code><br />
|-<br />
|http/host<br />
|string<br />
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент<br />
|<code>localhost:8081</code><br />
|-<br />
|http/svacerHostUrl<br />
<br />
ai/svacerHostUrl<br />
|string<br />
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент<br />
|<code><nowiki>http://localhost:8080/</nowiki></code><br />
|-<br />
|http/svacerClientTlsCfg?<br />
<br />
ai/svacerClientTlsCfg<br />
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]<br />
|Настройки безопасного подключения к Svacer<br />
|<pre style="white-space: pre;"><br />
svacerClientTlsCfg:<br />
insecureSkipVerify: true<br />
</pre><br />
|-<br />
|ai/svacerReviewCommentTemplate<br />
|string<br />
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code><br />
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]<br />
|-<br />
|ai/svacerReviewTags<br />
|[]string<br />
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента<br />
|<code>[AI]</code><br />
|-<br />
|hosts<br />
|map[string]object<br />
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент<br />
|<pre style="white-space: pre;"><br />
{id сервиса моделей}:<br />
{параметры подключения}<br />
(см. описание ниже)<br />
</pre><br />
|}<br />
<br />
=== Параметры подключения сервиса модели машинного обучения ===<br />
<br />
Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|url<br />
|string<br />
|Url сервиса с моделями машинного обучения<br />
|<code><nowiki>http://localhost:7000</nowiki></code><br />
|-<br />
|settings/requestBatchSize<br />
|int<br />
|Количество предупреждений, отправляемых для анализа моделью за раз<br />
|<code>512</code><br />
|-<br />
|settings/httpMultipartParameterName<br />
<br />
settings/httpMultipartFileName<br />
<br />
settings/httpMultipartContentType<br />
|string<br />
|Параметра multipart-запроса вызова модели<br />
|<pre style="white-space: pre;"><br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
</pre><br />
|-<br />
|resources/modelList<br />
<br />
resources/modelInference<br />
<br />
resources/logs<br />
|string<br />
|Сопоставление названий ресурсов сервиса моделей<br />
|<pre style="white-space: pre;"><br />
modelList: "/models_info"<br />
<br />
modelInference: "/use_model_for_file"<br />
<br />
logs: "/log_file"<br />
</pre><br />
|-<br />
|defaults/dataCollector/csvSeparator<br />
|string<br />
|Разделитель csv-файла, который отправляется в сервис моделей<br />
|<code>","</code><br />
|-<br />
|defaults/dataCollector/additionalLineNumber<br />
|int<br />
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей<br />
|<code>0</code><br />
|-<br />
|defaults/dataCollector/csvColumns<br />
|[]string<br />
|Названия столбцов csv-файла, который отправляется в сервис моделей<br />
|<code>[id, warnClass, code]</code><br />
|-<br />
|defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
|string<br />
|Названия статусов, которые присваиваются результату вызова модели<br />
|<pre style="white-space: pre;"><br />
defaultValue: "Undecided"<br />
<br />
leftClassValue: "False Positive"<br />
<br />
rightClassValue: "Confirmed"<br />
</pre><br />
|}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.<br />
<br />
{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}<br />
<br />
<pre style="white-space: pre;"><br />
varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"<br />
varSvacerClientTlsCfg: &svacerClientTlsCfg<br />
insecureSkipVerify: true<br />
db:<br />
url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"<br />
http:<br />
host: "localhost:8081"<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
ai:<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
svacerReviewCommentTemplate: |+<br />
`Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`<br />
<br />
`AI model: {{.Pipeline.Name}}`<br />
<br />
`Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`<br />
<br />
svacerReviewTags:<br />
- AI<br />
hosts:<br />
server-status:<br />
url: "http://localhost:7000"<br />
settings:<br />
requestBatchSize: 512<br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
resources:<br />
modelList: "/models_info"<br />
modelInference: "/use_model_for_file"<br />
logs: "/log_file"<br />
defaults:<br />
dataCollector:<br />
csvSeparator: ","<br />
additionalLinesNumber: 0<br />
csvColumns:<br />
- "id"<br />
- "warnClass"<br />
- "code"<br />
interpretation: <br />
defaultValue: "Undecided"<br />
leftClassValue: "False Positive"<br />
rightClassValue: "Confirmed"<br />
</pre><br />
<br />
== Описание модели xgb.joblib ИИ-ассистента ==<br />
<br />
Модель обучена на базе 50000+ размеченных предупреждений.<br />
<br />
Для предсказания статуса разметки нами используются:<br />
# языковая модель codebert-base для получения эмбеддингов кода;<br />
# метод градиентного бустинга (xgboost) для решения задачи классификации.</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Changelog&diff=3398Changelog2025-11-27T14:14:01Z<p>M.vinogradov: changelog 12-0-0 add AI assistant and new Webide deployment description</p>
<hr />
<div>=== Release 12-0-0 ===<br />
* API методы на fullmarkers позволяют указать фильтр с полем фильтрации по checker reliability<br />
* В функциональность полнотекстового поиска добавлен поиск маркеров под id и инварианту.<br />
* Промежуточное хранилище при импорте результатов командой <code>svacer import / svacer sarif2 import</code> теперь использует новый формат представления (должно снизить использование памяти при импорте)<br />
* Сериализация JSON переведена на jsonv2 библиотеку в Go<br />
* Импорт SARIF теперь более устойчив к пропускам в файле (отсутствие таких полей как location)<br />
* Добавлены переменные окружения <code>SVACER_TIMEOUT_IMPORT_RESULTS</code> для контроля таймаута на ожидание возможности начала операции импорта результатов (формат Go Duration string) и <code>SVACER_NUM_PARALLEL_IMPORTS</code> на ограничение числа параллельных импортов (задачи на импорт выстраиваются в очередь). По умолчанию значения 15 минут и (<code>максимальное число коннектов к БД) / 2</code>. Ограничение необходимы для предотвращения бесконечных ожиданий и зависаний при импорте данных.<br />
* Убраны лишние сообщения об устаревших детекторах при старте сервера или импорте снимков<br />
* В prometheus метрики добавлен ряд показателей размеров object store<br />
* Размер лога сервера, показываемого в WEB интерфейсе, ограничен. Размер задается переменной окружения SVACER_TAIL_LOG_SIZE (по умолчанию 1Мб). Показывается последний кусок не более SVACER_TAIL_LOG_SIZE. Сам лог файл не ограничивается в размерах и кнопка выгрузки лога выгружает полный лог. <br />
* ['''Экспериментально'''] Можно указать формат лог файла в JSON посредством параметра <code>svacer-server --log-format=json ...</code>, так же формат может быть указан через переменную окружения <code>SVACER_LOG_FORMAT=json</code>. Опции так же работают для CLI клиента <code>svacer</code><br />
* При запуске сервера можно указать флаг <code>--force-invariant-refresh</code> для принудительной регенерации инвариантов (может решить проблему с переносом разметки)<br />
* Добавлена переменная окружения SVACER_INV_GEN_JOBS для контроля числа параллельных job-ов при регенарации инвариантов. При ограниченных ресурсах машины рекомендуем ставить значение 2. По умолчанию значение ставится в 70% от <code>runtime.GOMAXPROCS</code><br />
* Добавлена функциональность по чистке object store при удалении снимков<br />
* Добавлена возможность создания сложных пользовательских фильтров по условиям выраженным предикатом [[Afilters]]<br />
* Проведена работа по предотвращению зависаний при исчерпывании доступных соединений с PostgreSQL сервером<br />
* Добавлен файл с чексуммой бинарника сервера <code>svacer-server</code> и проверка чексуммы при запуске<br />
* Упростили [[Help:XSvacer:AIAssistant:Deploy|деплой ИИ-ассистента]]: добавили его сервис в docker-compose и deb/rpm пакеты<br />
* Расширили возможности конфигурации при запуске сервера через [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose]: теперь можно включить debug, указать конфиг LDAP и параметр public-url<br />
* Добавлена возможность указания минимального количества снимков, которое необходимо оставлять в ветке, тип очистки и период удаления в [[Help:CLI/cleanup|автоматическом удалении снимков]]<br />
* ['''Экспериментально'''] Добавлена возможность [[Edit markers (command line)|автоматически обрабатывать маркеры]] при импорте данных. Также обработка маркеров доступна через [[Help:UI manual#Работа со снимками|UI]]<br />
* Добавлен флаг <code>diff-url</code> для команды <code>quickdiff</code> в CLI, также как и для команд <code>import</code>, <code>upload</code>, <code>sarif2 import</code> с указанием опции quick-stat. Данный флаг позволяет получать ссылку на diff снимков<br />
* Добавлены предупреждения если в командах <code>import</code>, <code>sarif2 import</code> используются флаги, которые используются флагом <code>upload</code>, но флаг <code>upload</code> не установлен <br />
* Добавлена интеграциия с внешними системами посредством механизма [[Help:Installation#Механизм интеграции с внешними системами посредством Webhook-ов|Webhook-ов]]<br />
* Добавлена [[Help:Installation#Настройка защиты от перебора паролей пользователей|Защита от перебора пароля пользователя]]<br />
* Добавлена возможность задать [[Help:Installation#Настройка парольной политики внутреннего механизма аутентификации Svacer|Парольную политику безопасности]] для пользователей, использующих встроенный мханизм аутентификации Svacer <br />
* Добавлена возможность задать [[Help:Installation#Задание вкладки по умолчанию на странице входа в GUI Svacer (а также отключение внутренного механизма аутентификации Svacer)|вкладку по умолчанию]] для страницы входа в систему <br />
* Исправлена ошибка, приводящая к разрастанию базы данных<br />
* Исправлена ошибка, связанная с невозможностью в ряде случаев использовать механизм подписок<br />
* Форма разметки с помощью [[Help:XSvacer:AIAssistant:Deploy|ИИ-ассистента]] реализована в основном интерфейсе Svacer<br />
* [[Help:XSvacer:Webide#Запуск функциональности при использовании docker compose|Упрощён запуск функциональности Webide]] при запуске сервера через [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose]<br />
<br />
=== Release 11-2-0 ===<br />
22.07.2025<br />
<br />
* Исправлены зависания сервера<br />
* Добавлено автоматическое удаление архивов и прочих временных файлов при импорте .svace-dir и SARIF-файлов через REST API<br />
<br />
=== Release 11-1-0 ===<br />
08.07.2025<br />
<br />
* Команды <code>--project-group, --if-no-group, --autoclean, --autoclean-svace</code> можно использовать в REST API для импорта svace-dir<br />
* При использовании REST API для импорта svace-dir сервер будет автоматически удалять директории <code>.svace-dir</code> и <code>.svacer</code> если не указаны явные опции <code>--autoclean=false, --autoclean-svace=false</code><br />
* Добавлена опция запуска сервера <code>--classic-inv-mode</code> для включения режима совместимости по генерации инвариантов с версией <= 8.x.x<br />
* Исправлены ошибки в работе <code>--quality-gate</code>, добавлена возможность учета статусов разметки. Добавлена возможность [[Help:Import from Svace#Флаг --baseline|указания baseline]] для сравнений при использовании опции <code>--quality-gate</code><br />
* Исправлены ошибки при подключении к PostgreSQL в SSL-режиме<br />
* Исправлен ряд ошибок при работе с LDAP<br />
* Команда <code>quickdiff</code> в CLI теперь выдает информацию также о Same и Matched предупреждениях<br />
<br />
=== Release 11-0-0 ===<br />
19.05.2025<br />
<br />
* Убраны излишние сообщения в логе сервера о login/logout операциях. Они будут выводиться только при запуске сервера с опцией <code>--debug</code><br />
* Команды CLI <code>svacer sarif *</code> были убраны, для [[Help:Sarif|импорта и экспорта]] следует использовать <code>svacer sarif2 *</code><br />
* Экспорт SARIF теперь включает все комментарии как отдельные объекты в <code>Properties</code><br />
* При экспорте в SARIF теперь экспортируются поля <code>Labels, Orig function</code><br />
* Импорт SARIF теперь корректным образом учитывает relatedLocations и формирует трассу<br />
* Импорт SARIF теперь автоматически импортирует исходники, если они включены в сам SARIF файл<br />
* Добавлена возможность указания [[Help:Sarif#Мэппинг severity|мэппинга severity]] детекторов при импорте из SARIF<br />
* Добавлен механизм указания правил резолвинга путей при импортировании исходного кода вместе с SARIF файлом<br />
* Экспорт исходников из снимка будет доступен только при наличии исходников на сервере<br />
* Добавлены флаги <code>--autoclean</code>, <code>--autoclean-svace</code> в команду <code>svacer import</code> для автоматического удаления <code>.svace-dir / .svacer-dir</code> после успешного импорта и загрузки данных на сервер<br />
* Улучшена поддержка [[OIDC]]<br />
* Улучшена поддержка [[LDAP configuration|LDAP]]<br />
* Добавлена интеграция с хранилищем секретов [[Infisical]]<br />
* Добавлена [[Notifications|служба нотификаций]] пользователей через почтовые сообщения и мессенджер telegram<br />
* Добавлен механизм аутентификации и [[Help:UI manual#Управление токенами доступа|управления]] персональными токенами доступа<br />
* Добавлен механизм упоминания пользователей через специальную конструкцию @login в комментариях к разметке<br />
* В разделе Статистика добавлен дашборд с [[Release notes 11-0-0#Изменения в разделе Статистика|Общей статистикой]], содержащей метрики по последним импортированным снимкам в ветках проектов<br />
* В статистике по активности пользователей добавлена возможность просмотра панели с актуальной информацией о маркере и опция показа только действий с актуальной разметкой<br />
* Большинство CLI команд, работающих с сервером, теперь делают явный logout после завершения<br />
* Svacer при импорте результатов Svace автоматически импортирует файлы <code>*.warn, *.err</code> с предупреждениями от самого анализатора Svace. Автоматический импорт не будет происходить при размере этих файлов более 30Мб (большой размер может свидетельствовать о проблемах в ходе анализа)<br />
* Переменная окружения <code>SVACER_CACHE_DIR</code> теперь учитывается во всех местах (ранее в ряде случаев мог неявно использоваться <code>$HOME/.cache</code>)<br />
* Добавлена возможность [[Help:CLI/cleanup|автоматического удаления снимков]]<br />
<br />
=== Release 10-0-1 ===<br />
17.02.2025<br />
<br />
* Исправлена ошибка с временной таблицей при обработке планов автомиграции разметки при импорте результатов (ERROR: relation "loaded_review" already exists)<br />
<br />
=== Release 10-0-0 ===<br />
16.01.2025<br />
<br />
* Множество изменений в UI, смотрите [[Release notes 10-0-0]]<br />
* Сделали [[Help:Installation#rpm|dnf/yum репозиторий]] для RPM-пакетов Svacer<br />
* Реализована возможность [[Markup2|экспорта, импорта и копирования разметки посредством Public REST API и CLI]]<br />
* Реализован дополнительный экспериментальный механизм [[Help:UI manual#Настройка интерфейса|генерации PDF на основе HTML]]. Генерация PDF переведена на асинхронный режим с показом нотификации пользователю<br />
* Добавлена возможность очистки всей разметки и/или комментариев на ветке проекта<br />
* Улучшения функциональности просмотра маркеров в встроенном IDE Theia<br />
* Добавлена функциональность по [[Help:UI manual#Глобальный поиск|глобальному поиску]] маркеров, комментариев и снимков по различным атрибутам<br />
* Добавлена возможность [[Help:UI manual#Просмотр статистики|получения статистики]] по маркерам и активностям пользователей при разметке<br />
* В API fullmarkers добавлен параметр <code>labels: true/false</code> для выгрузки меток маркера<br />
* Реализован Public API для получения/добавления/удаления меток маркеров<br />
* Настройки LDAP и прочие настройки аутентификации добавлены в единый конфигурационный файл<br />
* Добавлена возможность удаления кода из снимка при частичном импорте в Svacer<br />
* Добавлена опция minVersion, maxVersion для TLS при запуске сервера Svacer<br />
* Добавлена поддержка групп проектов при импорте снимков в CLI<br />
* При импорте снимков реализована поддержка автоматического определения пути префикса для переноса разметки<br />
* Исправлен ряд ошибок в импорте и генерации [[Help:Sarif|SARIF]]<br />
* Исправлены ошибки в копировании разметки между ветками, клонировании проектов и веток<br />
* Добавлена возможность отключения бэкграунд задач по очистке мусора<br />
* Добавлено экспериментальное CLI API для просмотра асинхронных задач на генерацию PDF<br />
* Добавлена возможность визуализации производительности сервера на основе [https://github.com/arl/statsviz statsviz]<br />
* Добавлена поддержка относительных путей в svres файле<br />
* Добавлена возможность ожидания завершения операций по очистки мусора при выполнении операций по импорту результатов анализа<br />
* Добавлена поддержка CWE таксономий при экспорте [[Help:Sarif|SARIF]]<br />
* Добавлена переменная окружения SVACER_TOKEN_LIFETIME для управления временем жизни токена аутентификации<br />
* Добавлена переменная окружения SVACER_RESET_ADMIN_PASSWORD для явного указания желаемого пароля при операции по сбросу пароля администратора<br />
* Добавлен [[Notifications|механизм нотификаций пользователей]] о внутренних событиях Svacer (экспериментальный функционал)<br />
<br />
=== Release 9-0-2 ===<br />
22.07.2024<br />
<br />
* Еще некоторые исправления, связанные с миграцией данных<br />
* Исправлена проблема с навигацией по Go to Definition<br />
<br />
=== Release 9-0-1 ===<br />
15.07.2024<br />
<br />
* Исправлены ошибки в клонировании проектов, приводящие к размножению записей в некоторых внутренних таблицах<br />
* Различные исправления, связанные с миграцией данных<br />
* Исправлена работа ряда CLI команд с включенным TLS на сервере<br />
* Исправлен ряд ошибок в генерации PDF<br />
<br />
=== Release 9-0-0 ===<br />
04.06.2024<br />
<br />
* Множество изменений в UI, смотрите [[Release notes 9-0-0]]<br />
* Svacer разделен на два исполняемых файла: <code>svacer-server</code> — сервер и <code>svacer</code> — клиент<br />
* {{Note}}Object store заменен на другую реализацию. Конвертация данных запускается автоматически при апгрейде и требует примерно 2х-2.2х дискового пространства, после конвертации старый object store будет удален. Время конвертации зависит от объема данных и скорости диска<br />
* {{Note}}Изменен [[Help:Match|алгоритм сопоставления предупреждений]]. При старте сервера будет произведена регенерация всех инвариантов во всех ветках. Это может занять продолжительное время (зависит от мощности сервера и объемов данных)<br />
* Добавлена возможность [[Help:Match#Ручное сопоставление предупреждений (экспериментальная возможность)|ручного сопоставления предупреждений]] для переноса разметки<br />
* Добавлена экспериментальная поддержка [[OIDC|OpenID]] протокола для аутентификации<br />
* Добавлена экспериментальная возможность [[Help:CLI#Слияние снимков из CLI (экспериментальная опция)|слияния снимков через CLI]]<br />
* Исправлены баги в [[Help:Sarif|импорте Sarif]], добавлена поддержка импорта с относительными путями к файлам (флаг <code>--base-dir</code>)<br />
* Лог сервера работает в режиме append, прежние данные не затираются<br />
* Добавлена возможность передачи токена аутентификации в клиент Svacer через переменную окружения <code>SVACER_AUTH_TOKEN=token</code><br />
* Добавлена возможность передачи логина и пароля в клиент Svacer через переменную окружения <code>SVACER_AUTH_CREDS=login:password</code><br />
* Добавлен public REST endpoint для импорта <code>.svace-dir</code> на стороне сервера<br />
* Добавлена возможность импорта <code>.svace-dir</code> из веб-интерфейса<br />
* Добавлены [[Metrics|метрики]] для Prometheus, доступны при запуске сервера с переменной окружения <code>SVACER_TRACE_OPTIONS=prom_metrics_on</code> на <code>/api/metrics</code><br />
* Добавлена очистка БД от мусора с возможностью настройки периодичности данной операции через переменную окружения <code>SVACER_GC_PERIOD=val</code> где val — duration в формате <code>hhmmss</code> или [https://en.wikipedia.org/wiki/Cron Cron]<br />
* Добавлена возможность клонирования проектов<br />
* Добавлен импорт <code>*warn, *.err</code> файлов из <code>.svace-dir</code>, которые содержат диагностические сообщения от Svace<br />
* Добавлена возможность [[Help:CLI#Ограничение числа запросов|ограничения числа запросов]] на сервер с указанием параметров в переменной окружения <code>SVACER_SERVER_THROTTLE_PARAMS</code><br />
* Добавлен шаблон для импорта разметки из кода на Go: <code>DEFAULT_GO</code><br />
* Добавлена возможность [[Help:CLI#Аутентификация из файла|аутентификации из файла]]<br />
* Исправлены проблемы безопасности<br />
* Добавлена возможность просмотра исходного кода снимка с предупреждениями анализатора во внешней IDE собранной на базе [https://theia-ide.org/ Theia IDE]<br />
* К команде automigrate add в CLI добавлен флаг <code>skip-exist</code>, чтобы при добавлении паттерна, который уже существует, не выдавало ошибки <br />
* К команде upload (import с флагом upload) с указанием флага <code>quality-gate</code> теперь можно добавить флаг <code>quality-gate-verbose</code>. Если его указать, то также будет выведен результат успешных проверок quality-gate<br />
* Улучшения в поддержке протокола LDAP<br />
<br />
=== Release 8-0-1 ===<br />
22.01.2024<br />
<br />
* Исправлена работа в изолированной от сети среде. Загрузка Web UI больше не требует доступа к публичным CDN<br />
* Добавлена поддержка функций при указании пользовательского фильтра<br />
* Добавлено API для управления пользовательскими фильтрами. Детали и пример использования можно найти здесь: https://gitlab.ispras.ru/svacer-public/api-go-examples/-/tree/master/api-ui-settings<br />
* Исправлено отображение Checker Severity при экспорте в SARIF. Теперь Critical -> error; Major, Normal -> warning; Minor -> note; any other -> warning<br />
<br />
=== Release 8-0-0 ===<br />
21.11.2023<br />
<br />
* Множество изменений в UI. Смотрите обзор в [[Release notes 8-0-0]]<br />
* Добавлен новый импорт и экспорт из SARIF в command line с поддержкой исходного кода в SARIF файлах и импортом описания детекторов из SARIF<br />
* Добавлены группы проектов<br />
* Переделана модель ролей и доступов. Добавлен CLI для управления ролями и доступами<br />
* Добавлена возможность настройки автопереноса разметки между ветками, в том числе в разных проектах<br />
* Импорт/экспорт снимков включает информацию о детекторах<br />
* Исправлена работа интерфейса с Undefined детекторами (т. е. детекторами, информация о которых отсутствует в Svacer)<br />
* Добавлено экспериментальное API по управлению детекторами и конфигурациями детекторов<br />
* Добавлена очистка исходного кода от Svacer-specific комментариев перед экспортом разметки в код<br />
* Добавлена возможность включения режима обязательного комментария при разметке кода. Комментарий будет сгруппирован с операцией разметки и будет иметь ссылку на нее<br />
* Утилита миграции со старого svace-сервера больше не поддерживается. При необходимости миграции используйте утилиту из прошлых релизов Svacer<br />
* Добавлена Swagger документация на API<br />
* Добавлено хранение истории изменений комментариев<br />
* Опция <code>--pathPrefix</code> поддерживает файлы в JSON формате вида: <code>[{ "prefix": "/some/path", "replace": "/test" }, ...]</code><br />
* При использовании операции по обновлению <code>pathPrefix</code> на сервере, данные о прежнем <code>pathPrefix</code> запоминаются в мета-информации о снимке<br />
* Добавлена возможность переименования снимков в UI<br />
* Sensitive информация (детали подключения к БД с данными аутентификации) убрана из UI и API<br />
* ОС в docker-образе Svacer обновлена с Ubuntu 18 до Ubuntu 22<br />
* Улучшена логика автоопределения портов и протоколов при соединении с сервером из Svacer CLI<br />
<br />
=== Release 7-0-1 ===<br />
23.05.2023<br />
<br />
* Исправлена проблема с фильтрацией предупреждений для C# проектов<br />
<br />
=== Release 7-0-0 ===<br />
16.05.2023<br />
<br />
* Убрана зависимость от PostgreSQL из .deb и .rpm пакетов, чтобы проще было ставить Svacer только как клиент<br />
* Сделан пакет для Windows (.msi) и документация по установке и запуску на Windows<br />
* Теперь, если при svacer import и svacer sarif не указан путь к проекту, им считается текущая директория<br />
* Информация о разметке и блокировках теперь обновляется автоматически при изменении в другом браузере (табе) или другим пользователем<br />
* UI для пользовательских фильтров улучшен и перенесен в правую верхнюю часть экрана<br />
* UI для выбора проекта, ветки и снимка теперь находится на одном уровне<br />
* Улучшен UI для режима сравнения снимков<br />
* Добавлена возможность работать одновременно с несколькими открытыми файлами в режиме Code, это поведение можно изменить в настройках профиля пользователя<br />
* В левой навигационной панели детекторы теперь по умолчанию группируются по серьезности, это поведение можно изменить в настройках профиля пользователя<br />
* Профиль текущего пользователя теперь можно смотреть/редактировать только через меню в правом верхнем углу<br />
* Добавлена возможность копирования в системном логе и журнале<br />
* Для пользователя теперь запоминается последний контекст (проект/ветка/снимок), с которым он работал, он автоматически открывается при старте новой сессии<br />
* Групповая разметка теперь делается единой транзакцией, в случае ошибок или отмены все изменения откатываются<br />
* Добавлено предупреждение при использовании некорректных путей при использовании REST API с префиксом /api<br />
* Поддержка указания паролей из файла или pipe-а при использование Svacer CLI<br />
* Добавлена поддержка multi-tab code view для режима просмотра кода объекта сборки<br />
* Добавлена поддержка сохранения информации об удаленных детекторах при загрузке информации о детекторах из новой версии Svace<br />
* Исправлен импорт результатов анализа, если сборка проводилась с опцией --disable-dxr<br />
* Исправлены проблемы при импорте и прикреплении нескольких файлов к снимку<br />
* Исправлены ошибки с входом в систему пользователей LDAP (специальные символы в пароле, вход по атрибуту mail)<br />
* Добавлена возможность использования резервных серверов LDAP<br />
* Добавлена возможность автоматического назначения пользователям LDAP роли Svacer, в зависимости от принадлежности пользователя к LDAP группе<br />
* Добавлены новые public запросы на получение маркеров/снимков/проектов с учетом заданных параметров фильтрации<br />
* Добавлена поддержка TLS при работе сервера по протоколам HTTP и gRPC<br />
* Добавлена возможность загрузки статистики по общему количеству предупреждений и по количеству размеченных предупреждений для проектов и веток через REST API<br />
* Добавлена вкладка выбора проектов в расширении VSCode<br />
* Убрана возможность использовать всплывающее окно в VScode для добавления/редактирования/удаления комментариев, установки ревью-статусов, локов и т.д.<br />
<br />
=== Release 6-0-3 ===<br />
25.01.2023<br />
<br />
* RPM-пакет теперь при сборке упаковывается в gzip вместо zstd для обратной совместимости со старыми дистрибутивами<br />
* Если short url некорректен, то Svacer теперь будет возвращать корректный http error NotFound<br />
* Если путь к лог файлу явно не указан, то svacer.log будет создаваться во временной директории. Это решает проблемы при запуске Svacer из директорий с запретом на запись. Путь к лог файлу будет печататься в stdout<br />
* Лог файлы не будут создаваться, когда используется опция --help<br />
* Исправлены проблемы при миграции схемы данных, когда в PostgreSQL используется SSL подключение<br />
* Добавлены описания детекторов из последнего релиза Svace, которые были пропущены в релизе 6-0-2<br />
* Исправлена работа Svacer за proxy-сервером, где выставляется Header "X-Content-Type-Options nosniff"<br />
* Добавлены кнопки для скачивания системного лога и журнала из web-интерфейса<br />
* Поправлен ряд ошибок валидации схемы при экспорте в SARIF<br />
* Исправлено поведение при наличии нескольких хуков в конфигурационном файле<br />
* В информацию о маркере для хуков добавлены checker severity и reliability<br />
* Исправлен случайный порядок URL для маркеров при использовании public API для получения URL-ов<br />
* На главную страницу добавлена кнопка "Помощь", которая открывает документацию<br />
* При использовании команд навигации в режиме "Browse code" текущий файл теперь корректно подсвечивается в дереве файлов<br />
* В диалоге групповой разметки убран индикатор изменений в виде кружочка, наличие изменений можно определить по активности кнопок "Apply" и "Reset"<br />
* Кнопка обновления в верхнем меню теперь корректно обновляет информацию на странице Settings/Project<br />
* Различные небольшие исправления в пользовательском интерфейсе<br />
<br />
=== Release 6-0-2 ===<br />
16.12.2022<br />
<br />
* Исправлена проблема в UI с сохраненными пользовательскими фильтрами<br />
<br />
=== Release 6-0-1 === <br />
13.12.2022<br />
<br />
* Добавлено описание ряда детекторов, которые есть в последнем релизе Svace 3.3.2 но были пропущены в Svacer<br />
* Исправлено вылетание в Login Screen при удалении нотификации из панели нотификаций<br />
* Исправлено появление белого экрана при клике на детектор, информация о котором отсутствует<br />
* Ряд различных небольших исправлений в UI<br />
* Промежуточное хранилище будет очищаться по умолчанию при использовании команды import<br />
<br />
=== Release 6-0-0 === <br />
30.11.2022<br />
<br />
* Добавлено копирование комментариев при копировании разметки<br />
* Комментарии добавлены к отчету в формате csv<br />
* Добавлена возможность вводить пароль с клавиатуры для консольных команд<br />
* Добавлена возможность импортировать разметку из объекта сборки (из ранее загруженных данных)<br />
* Добавлена возможность импортировать разметку сразу после загрузки на сервер (опция для команды svacer upload)<br />
* Добавлена возможность загружать исходный код не из папки .svace-dir<br />
* Добавлена возможность бэкапа и восстановление объектного хранилища в сервер PostgresSQL<br />
* Добавлена возможность создания отчета по проекту в формате PDF через интерфейс командной строки и посредством REST API<br />
* Добавлена возможность подавления предупреждений через inline комментарии в коде<br />
* Добавлена возможность подавления предупреждений по идентификатору предупреждения через command line и REST API<br />
* Добавлена возможность ассоциировать организацию с пользователем и реестр организаций<br />
* Добавлена фильтрация списка комментариев по пользователю в правой панели веб-интерфейса<br />
* Добавлен поиск пользователей по его атрибутам в панели управления пользователями<br />
* Добавлена возможность заполнения данных профиля LDAP пользователя данными, полученными от LDAP сервера<br />
* Добавлена возможность прикреплять файлы к снимкам при импорте результатов (данные файлы составляют часть экспортируемых данных при экспорте снимков)<br />
* Добавлена возможность ассоциировать пользовательские атрибуты типа "строка" или массив строк со снимком при импорте данных (данные атрибуты составляют часть экспортируемых данных при экспорте снимков)<br />
* Добавлены command line операции по получению прикрепленных файлов и пользовательских атрибутов со снимков<br />
* Добавлена возможность группового добавления комментариев<br />
* Добавлена возможность указания сетевого интерфейса для работы WEB и GRPC серверов<br />
* Добавлен вывод краткой статистики по загруженному снимку при команде upload. Поддерживается текстовой и JSON форматы вывода<br />
* Существенно расширены возможности по интеграции Visual Studio Code с сервером Svacer<br />
* Добавлен флаг --git в команду import. При наличии такого флага, ищется ближайший git репозиторий содержащий .svace-dir и при наличии такого - используется путь к гит репозиторию для замены путей на префикс .build.<br />
* Portable PostgreSQL больше не входит в поставку. Вместо него поставляется docker-compose.yml файл для запуска PostgreSQL в докер-контейнере<br />
* Добавлено больше данных и информации об ошибках в вывод команды svacer import<br />
* Изменение Public API: добавлена точка входа /api/public/login<br />
* Операции по импорту и экспорту снимков доступны теперь обычным пользователям (не администраторам) при использовании command line интерфейса<br />
* Операция по экспорту снимков доступна обычному пользователю из веб-интерфейса (импорт все еще требует роль администратора для веб-интерфейса)<br />
* Операции по экспорту снимков переведены на асинхронный режим. Нотификация о готовности будет показана пользователю и доступна в панели нотификаций<br />
* Обновлено описание детекторов в соответствии с релизом Svace 3.3.2<br />
* Исправлена ошибка обработки корневых сертификатов при подключении к LDAP серверу по протоколу ldaps<br />
* Исправлено ошибочное создание дубликатов локальных учетных записей LDAP пользователей (case sensitive login)<br />
* Различные исправления в пользовательском интерфейсе с целью оптимизации производительности<br />
* Добавлены пропущенные проверки ролей при работе с веб-интерфейсом<br />
* Svacer больше не создает временные файлы в директории с исполняемым файлом<br />
* Устаранены задержки при удалении веток и проектов</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=3305Help:XSvacer:Webide2025-11-14T14:38:32Z<p>M.vinogradov: start IDE from Svacer in docker container</p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
= Поддержка среды разработки Theia IDE =<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске Svacer.<br />
<br />
Функциональность запуска IDE основана на управлении docker-контейнерами с IDE. Поэтому при запуске функциональности Webide также будет запущена функциональность [[Help:XSvacer:Docker|управления docker-контейнерами]].<br />
<br />
При активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов<br />
* в пользовательском интерфейсе на вкладке "Информация о снимке" появляется кнопка "Открыть в IDE"<br />
* устанавливается подключение к хосту docker, на котором будут запускаться контейнеры с экземплярами IDE<br />
<br />
=== Запуск функциональности при использовании docker compose ===<br />
<br />
В случае запуска 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>.<br />
<br />
=== Запуск функциональности в Svacer с настройками по умолчанию ===<br />
<br />
Для того, чтобы начать пользоваться функциональностью запуска IDE без изменения конфигурационных параметров Svacer, нужно выполнить следующие действия:<br />
# Настройка доступа к docker-хосту:<br />
## Запустить 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;<br />
## Проверить, что у пользователя под которым будет запускаться Svacer есть доступ к unix-сокету docker-хоста <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/engine/install/linux-postinstall<br />
# Настроить права доступа у пользователей, которые смогут запускать IDE: требуются разрешения на проект/ветку "Просмотр маркеров" и "Экспорт разметки"<br />
# Перезапустить Svacer с флагом <code style="white-space: pre;">--xsvacer.features webide</code><br />
# ''Опционально.'' Для ускорения первого запуска IDE:<br />
## Скачать архив с 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+]<br />
## Загрузить docker-образ из архива на docker-хост: <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint...</code><br />
<br />
После этого у пользователей с указанными правами должна появиться кнопка "Открыть в IDE" на панели с информацией о снимке.<br />
<br />
{{Note}} IDE с исходным кодом снимков будут запускаться в новых вкладках браузера. Обычно все браузеры блокируют автоматическое открытие вкладки и показывают соответствующее предупреждение.<br />
<br />
Например, в Firefox:<br />
<br />
[[File:Firefox popup notification ru.png]]<br />
<br />
В таком случае нужно дать разрешение на открытие вкладки с IDE:<br />
<br />
[[File:Firefox popup notification expanded ru.png|x150px]]<br />
<br />
При необходимости изменения настроек подключения к docker-хосту:<br />
# Скопировать [[Help:XSvacer:Docker#Конфигурация_по_умолчанию|конфигурацию docker по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/docker</code><br />
<br />
При необходимости изменения настроек запуска IDE:<br />
# Скопировать [[#Конфигурация_по_умолчанию|конфигурацию webide по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/webide</code><br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске Svacer указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В [[Help:XSvacer:Webide#Конфигурация|конфигурации]] функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE<br />
# У пользователя Svacer имеются разрешения "Просмотр маркеров" и "Экспорт разметки" на проект, в котором находится снимок, для которого нужно запустить IDE<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка "Открыть в IDE".<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code><br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается<br />
#** Если IDE недоступна: продолжается процесс запуска. IDE будет перезапущена<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code>xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code><br />
# Исходный код снимка скачивается в "корневую папку снимка"<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sarif/filenametemplate</code><br />
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>. Если docker-образ отсутствует, он будет загружен на хост<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code>running</code> — процесс запуска IDE продолжается<br />
##** в статусе <code>created</code>, <code>exited</code> или <code>paused</code> — контейнер будет запущен<br />
##** в других статусах — вернётся соответствующая ошибка и процесс запуска IDE прервётся<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code><br />
#* Если за отведённое время ответ от IDE получен — процесс запуска завершается<br />
#* Если ответ не получен — вернётся ошибка <code>ide not ready</code><br />
<br />
При возникновении ошибки на одном из этапов запуска IDE артефакты, созданные на предыдущих этапах, останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
{{Note|type=reminder|text=Причиной возникновения ошибки "ide not ready" может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>. В этом случае рекомендуется попробовать повторно запустить IDE через короткий промежуток времени}}<br />
<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется проверить:<br />
# Сетевую доступность docker-хоста<br />
# Настройки фаервола на docker-хосте<br />
# Настройки биндинга docker-контейнера c IDE<br />
::<code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code><br />
::Контейнер должен быть подключён к доступному сетевому интерфейсу<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с префиксом <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code><br />
<br />
Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
:<code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>POST http://docker-host:35353/socket.io/?...</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
Для запуска IDE в окне браузера нужно указать адрес<br />
<br />
:<code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code><br />
<br />
{{Note}} Завершающий слеш обязателен!<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы Svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода<br />
DELETE /api/snapshots/{snapshot_id}/ide<br />
с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>. В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
По умолчанию установлен параметр конфигурации<br />
<br />
xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true<br />
<br />
Это означает, что после остановки docker-контейнер будет автоматически удалён.<br />
<br />
Чтобы изменить это поведение, настройка<br />
xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove<br />
<br />
должна быть установлена в <code>false</code> на момент запуска docker-контейнера IDE. Это можно сделать, например, установив значение переменной окружения<br />
<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false<br />
<br />
{{Note|type=error|text=При использовании версии Svacer 9.0.0 установка <code>autoremove: false</code> вызывает ошибку запуска. Исправлено в версии [[Svacer#Релизы|9.0.1]].'''}}<br />
<br />
При корректной остановке (например SIGTERM) Svacer автоматически остановит все запущенные docker-контейнеры IDE.<br />
<br />
=== Подключение к IDE после некорректного завершения Svacer ===<br />
<br />
При запуске Svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах. При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке Svacer все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!}}<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> — идентификатор IDE<br />
:<code style="white-space: pre;">name</code> — название IDE<br />
:<code style="white-space: pre;">order</code> — порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка.<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> — действие<br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Доступные действия:'''<br />
* <code style="white-space: pre;">update_markup</code> — обновление предупреждений и разметки (sarif-файла)<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например, для default-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code><br />
<br />
Раздел конфигурации для управления функциональностью — <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому необходимо также [[Help:XSvacer:Docker|настроить доступ к docker-хосту]] в разделе <code style="white-space: pre;">xsvacer/docker</code>, иначе функциональность WebIDE не сможет работать корректно.<br />
<br />
В случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]].<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!}}<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации default)<br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0<br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0)<br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на машине со Svacer<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources<br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на хосте docker. Нужен при использовании удалённого docker-хоста, т. к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
|<br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker. По умолчанию <code style="white-space: pre;">"/"</code><br />
|<br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|{{Note|text=В версии 10.0.0 заменён на [[Help:XSvacer:Webide#Параметры_экспорта_sarif-файла_с_разметкой_предупреждений|sarif]]}}<br />
Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"</nowiki><br />
|}<br />
<br />
==== Параметры экспорта sarif-файла с разметкой предупреждений ====<br />
<br />
Данные параметры используются для настройки экспорта sarif-файлов с разметкой предупреждений, выполненной в Svacer.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|sarif<br />
|map<br />
|Настройки экспорта sarif-файла<br />
|<br />
|-<br />
|sarif/filenametemplate<br />
|golang template string<br />
|Шаблон для формирования названия sarif-файла. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"warnings.sarif"</nowiki><br />
|-<br />
|sarif/commenttemplate<br />
|golang template string<br />
|{{Note|text=Удалён в версии 11.0.0}}<br />
Шаблон для формирования элемента списка комментариев предупреждения при экспорте в sarif-файл. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|Comment]]<br />
|<nowiki>"{{if trim .Text}}`[{{.CreateTs.Local.Format \"02.01.2006 15:04\"}}] {{.CreatedBy}}:`\n\n{{trim .Text}}{{end}}"</nowiki><br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только стандартный менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
|<br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default<br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
|<br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default<br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|<nowiki>"theia-1-46-{{.StartArgs.SnapshotID}}"</nowiki><br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список меток docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer<br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
|<br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint<br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|Svacer 11+: 1.46.0.sarif.clang.11.0.0.1<br />
Svacer 10+: 1.46.0.sarif.clang.10.0.0<br />
<br />
Svacer 9+: 1.46.0.sarif.clang<br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост<br />
* repository — будет вызван docker pull образа <code>{image/name}:{image/tag}</code><br />
* file — будет вызван docker load с URL <code>image/sourcefileurl</code><br />
|file<br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|URL откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
URL может содержать:<br />
* путь к локальному файлу: схема <code>file://</code><br />
* http/https-адрес: схема <code>http://</code> или <code>https://</code><br />
|Svacer 11+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz<br />
Svacer 10+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz<br />
<br />
Svacer 9+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
|<br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре Config https://github.com/moby/moby/blob/v28.5.1/api/types/container/config.go#L44<br />
|<br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре HostConfig https://github.com/moby/moby/blob/v28.5.1/api/types/container/hostconfig.go#L429<br />
|<br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true<br />
|-<br />
|docker/container/hostconfig/portbindings/<br />
|map<br />
|<br />
|<br />
"3000/tcp":<br />
:- hostport: 0<br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре NetworkingConfig https://github.com/moby/moby/blob/v28.5.1/api/types/network/network.go#L140<br />
|<br />
|-<br />
|docker/containerhostconfigmounts/<br />
|map<br />
|{{Note|text=Добавлен в версии 12.0.0}}<br />
Именованные настройки точек монтирования контейнера. Соответствуют структуре [[Help:XSvacer:Webide#Структуры_применяемые_в_конфигурации_функциональности|MountMap]]<br />
|<br />
|-<br />
|docker/containernetworkingconfigendpoints/<br />
|map<br />
|{{Note|text=Добавлен в версии 12.0.0}}<br />
Именованные настройки подключённых сетевых интерфейсов контейнера контейнера. Соответствуют структуре [[Help:XSvacer:Webide#Структуры_применяемые_в_конфигурации_функциональности|EndpointsMap]]<br />
|<br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
|<br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10<br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms<br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
Comment {<br />
ID string<br />
Text string<br />
Ref string<br />
CreatedBy string<br />
CreatedByID string<br />
CreateTs time.Time<br />
UpdateTs *time.Time<br />
UpdatedBy string<br />
UpdatedByID string<br />
}<br />
<br />
==== Структуры применяемые в конфигурации функциональности ====<br />
<br />
type Mount struct {<br />
Disabled bool<br />
mount.Mount https://github.com/moby/moby/blob/v28.5.1/api/types/mount/mount.go#L27<br />
}<br />
<br />
type MountMap map[string]Mount<br />
<br />
type EndpointSettings struct {<br />
Name string<br />
Disabled bool<br />
*network.EndpointSettings https://github.com/moby/moby/blob/v28.5.1/api/types/network/endpoint.go#L10<br />
}<br />
<br />
type EndpointsMap map[string]*EndpointSettings<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sarif:<br />
filenametemplate: "warnings.sarif"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang.11.0.0.1<br />
sourcetype: file<br />
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
containerhostconfigmounts:<br />
"projectrootbind": <br />
disabled: false<br />
mount:<br />
type: bind<br />
target: "/home/project"<br />
readonly: true<br />
"projectrootvolume": <br />
disabled: true<br />
mount:<br />
type: volume<br />
source: svacer-snapshot-sources<br />
target: "/home/project"<br />
readonly: true<br />
containernetworkingconfigendpoints:<br />
"svacer":<br />
name: svacer<br />
disabled: true<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
# - hostport: 0 # not required since version 12.0.0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
По умолчанию используется 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/).<br />
<br />
{{Note|text=При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы}}<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения<br />
<br />
XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code><br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске Svacer:<br />
<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в корневые папки, заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code><br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code><br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code><br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code><br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code><br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code><br />
#*: метки с названиями <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><br />
# При использовании rootless-хоста docker будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста|настройкам]]<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр<br />
<br />
xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl<br />
<br />
Содержит значение<br />
<br />
Svacer 11+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz<br />
Svacer 10+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz<br />
Svacer 9+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
<br />
По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т. к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго.<br />
<br />
Для ускорения первого запуска IDE докер образ можно загрузить на хост docker вручную. Для этого необходимо:<br />
<br />
# Скачать файл архива<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint...</code><br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0 1.46.0].<br />
<br />
При этом была изменена компоновка расширений Theia. Результат выполнения <code>git diff</code>:<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "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"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа:<br />
docker build -t theia-blueprint:1.46.0.sarif.clang... -f browser.Dockerfile .<br />
<br />
Команда экспорта docker-образа:<br />
docker image save theia-blueprint:1.46.0.sarif.clang... | gzip > /path/to/tar/theia-blueprint.1.46.0.sarif.clang....tar.gz<br />
<br />
== Известные проблемы ==<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.<br />
<br />
В 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.<br />
<br />
Поэтому для решения данной проблемы Svacer должен открываться по HTTPS или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant:Deploy&diff=3023Help:XSvacer:AIAssistant:Deploy2025-06-23T11:46:25Z<p>M.vinogradov: --ai-host description improvement</p>
<hr />
<div>== Активация и запуск функциональности ==<br />
<br />
ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:<br />
<br />
# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-ассистенту;<br />
# Развернуть и запустить сервис ИИ-ассистента;<br />
<br />
=== Активация функциональности <code style="white-space: pre;">xsvacer</code> при запуске Svacer ===<br />
<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features aiAssistant</code> при запуске Svacer.<br />
<br />
==== Настройка доступа к ИИ-ассистенту в Svacer ====<br />
<br />
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code><br />
<br />
Изменить адрес, по которому Svacer будет подключаться к ИИ-ассистенту, можно одним из способов:<br />
<br />
# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистента}:{порт}/</nowiki></code><br />
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел<br />
<br />
<pre style="white-space: pre;"><br />
...<br />
xsvacer:<br />
...<br />
aiAssistant:<br />
assistantHostUrl: http://{адрес ИИ-ассистента}:{порт}/<br />
...<br />
</pre><br />
<br />
==== Настройка значения флага <code>--public-url</code> ====<br />
<br />
В связи с тем, что ИИ-ассистент использует REST API Svacer, необходимо добавить url ИИ-ассистента в список публичных url Svacer. Это можно сделать, добавив при запуске Svacer флаг:<br />
<br />
--public-url {url ИИ-ассистента}<br />
<br />
Пример:<br />
<br />
<nowiki>--xsvacer.features aiAssistant --public-url https://svacer-ai-demo.ispras.ru</nowiki><br />
<br />
{{Note|text=Данная настройка связана с функциональностью генерации коротких ссылок}}<br />
<br />
=== Развёртывание и запуск ИИ-ассистента ===<br />
<br />
При развёртывании ИИ-ассистента необходимо выполнить следующие действия:<br />
<br />
# Запустить docker-контейнер с моделью машинного обучения;<br />
# При необходимости: развернуть postresql-сервер для хранения базы данных ИИ-ассистента;<br />
# Запустить сервис ИИ-ассистента.<br />
<br />
==== Запуск docker-контейнера с моделью машинного обучения ====<br />
<br />
Docker-образ контейнера с моделью можно скачать по ссылке: https://svacer.ispras.ru/docker/images/svacer-ai-model-host.1.0.0.tar.gz (3.3GB)<br />
<br />
Далее docker-образ необходимо загрузить на docker-хост с помощью команды<br />
<br />
docker image load -i /path/to/svacer-ai-model-host.1.0.0.tar.gz<br />
<br />
После этого docker-контейнер может быть запущен следующей командой<br />
<br />
docker volume create svacer-ai-cache<br />
docker volume create svacer-ai-pgdata<br />
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<br />
<br />
Том <code style="white-space: pre;">cache</code> будет содержать кэш сервиса взаимодействия с моделью машинного обучения.<br />
<br />
Том <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ postgres'а.<br />
<br />
Порт <code>7000</code> будет использоваться по умолчанию, если не были изменены [[#Параметры подключения сервиса модели машинного обучения|параметры подключения сервиса машинного обучения]]<br />
<br />
==== Запуск ИИ-ассистента ====<br />
<br />
Исполняемый файл ИИ-ассистента можно скачать по ссылке: https://svacer.ispras.ru/releases/svacer-ai/svacer-ai-1-0-0-linux.tar.gz (53MB)<br />
<br />
После этого ИИ-ассистент может быть запущен командой <code>svacerai-server run</code><br />
<br />
===== Флаги команды запуска ИИ-ассистента =====<br />
<br />
Глобальные флаги <code>svacerai-server help</code><br />
<br />
NAME:<br />
svacerai-server - Svace AI server<br />
<br />
USAGE:<br />
svacerai-server [global options] command [command options] [arguments...]<br />
<br />
COMMANDS:<br />
run<br />
help, h Shows a list of commands or help for one command<br />
<br />
GLOBAL OPTIONS:<br />
--debug (default: false) [$SVACER_AI_DEBUG]<br />
--log-level value Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]<br />
--log value Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.<br />
--config value Define path to file with config in YAML format (by default svacer-ai.cfg).<br />
--help, -h show help<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|debug<br />
|bool<br />
|Отладочный режим логирования<br />
|-<br />
|log-level<br />
|string<br />
|Уровень логирования<br />
|-<br />
|log<br />
|string<br />
|Путь к файлу с логами<br />
|-<br />
|config<br />
|string<br />
|Путь к [[#Конфигурация по умолчанию|конфигурационному файлу]]<br />
|}<br />
<br />
Флаги запуска ИИ-ассистента <code>svacerai-server run help</code><br />
<br />
NAME:<br />
svacerai-server run<br />
<br />
USAGE:<br />
svacerai-server run [command options] [arguments...]<br />
<br />
OPTIONS:<br />
--pg value Defines PostgreSQL connection URL<br />
--host value Defines host name for the server<br />
--svacer-host value Defines remote Svacer host<br />
--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><br />
--help, -h show help<br />
<br />
{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Формат<br />
|-<br />
|style="width: 80px"|pg<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS<br />
|-<br />
|host<br />
|string<br />
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент<br />
|<code>{ip адрес}:{порт}</code><br />
|-<br />
|svacer-host<br />
|string<br />
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент<br />
|https://en.wikipedia.org/wiki/URL#Syntax<br />
|-<br />
|ai-host<br />
|[]string<br />
|Список адресов сервисов с моделями машинного обучения. <code>host-id</code> - идентификатор сервиса моделей в [[#Конфигурация по умолчанию|конфигурации]]<br />
|<code><nowiki>{host id}:{url сервиса моделей}</nowiki></code><br />
|}<br />
<br />
{{Note|text=При использовании [[#Конфигурация по умолчанию|конфигурации по умолчанию]], <code>{host id}</code> должен быть равен <code>server-status</code>}}<br />
<br />
Пример:<br />
<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><br />
<br />
=== Конфигурация ИИ-ассистента ===<br />
<br />
Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|db/url<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|<code>postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable</code><br />
|-<br />
|http/host<br />
|string<br />
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент<br />
|<code>localhost:8081</code><br />
|-<br />
|http/svacerHostUrl<br />
<br />
ai/svacerHostUrl<br />
|string<br />
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент<br />
|<code><nowiki>http://localhost:8080/</nowiki></code><br />
|-<br />
|http/svacerClientTlsCfg?<br />
<br />
ai/svacerClientTlsCfg<br />
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]<br />
|Настройки безопасного подключения к Svacer<br />
|<pre style="white-space: pre;"><br />
svacerClientTlsCfg:<br />
insecureSkipVerify: true<br />
</pre><br />
|-<br />
|ai/svacerReviewCommentTemplate<br />
|string<br />
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code><br />
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]<br />
|-<br />
|ai/svacerReviewTags<br />
|[]string<br />
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента<br />
|<code>[AI]</code><br />
|-<br />
|hosts<br />
|map[string]object<br />
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент<br />
|<pre style="white-space: pre;"><br />
{id сервиса моделей}:<br />
{параметры подключения}<br />
(см. описание ниже)<br />
</pre><br />
|}<br />
<br />
==== Параметры подключения сервиса модели машинного обучения ====<br />
<br />
Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|url<br />
|string<br />
|Url сервиса с моделями машинного обучения<br />
|<code><nowiki>http://localhost:7000</nowiki></code><br />
|-<br />
|settings/requestBatchSize<br />
|int<br />
|Количество предупреждений, отправляемых для анализа моделью за раз<br />
|<code>512</code><br />
|-<br />
|settings/httpMultipartParameterName<br />
<br />
settings/httpMultipartFileName<br />
<br />
settings/httpMultipartContentType<br />
|string<br />
|Параметра multipart-запроса вызова модели<br />
|<pre style="white-space: pre;"><br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
</pre><br />
|-<br />
|resources/modelList<br />
<br />
resources/modelInference<br />
<br />
resources/logs<br />
|string<br />
|Сопоставление названий ресурсов сервиса моделей<br />
|<pre style="white-space: pre;"><br />
modelList: "/models_info"<br />
<br />
modelInference: "/use_model_for_file"<br />
<br />
logs: "/log_file"<br />
</pre><br />
|-<br />
|defaults/dataCollector/csvSeparator<br />
|string<br />
|Разделитель csv-файла, который отправляется в сервис моделей<br />
|<code>","</code><br />
|-<br />
|defaults/dataCollector/additionalLineNumber<br />
|int<br />
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей<br />
|<code>0</code><br />
|-<br />
|defaults/dataCollector/csvColumns<br />
|[]string<br />
|Названия столбцов csv-файла, который отправляется в сервис моделей<br />
|<code>[id, warnClass, code]</code><br />
|-<br />
|defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
|string<br />
|Названия статусов, которые присваиваются результату вызова модели<br />
|<pre style="white-space: pre;"><br />
defaultValue: "Undecided"<br />
<br />
leftClassValue: "False Positive"<br />
<br />
rightClassValue: "Confirmed"<br />
</pre><br />
|}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.<br />
<br />
{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}<br />
<br />
<pre style="white-space: pre;"><br />
varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"<br />
varSvacerClientTlsCfg: &svacerClientTlsCfg<br />
insecureSkipVerify: true<br />
db:<br />
url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"<br />
http:<br />
host: "localhost:8081"<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
ai:<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
svacerReviewCommentTemplate: |+<br />
`Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`<br />
<br />
`AI model: {{.Pipeline.Name}}`<br />
<br />
`Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`<br />
<br />
svacerReviewTags:<br />
- AI<br />
hosts:<br />
server-status:<br />
url: "http://localhost:7000"<br />
settings:<br />
requestBatchSize: 512<br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
resources:<br />
modelList: "/models_info"<br />
modelInference: "/use_model_for_file"<br />
logs: "/log_file"<br />
defaults:<br />
dataCollector:<br />
csvSeparator: ","<br />
additionalLinesNumber: 0<br />
csvColumns:<br />
- "id"<br />
- "warnClass"<br />
- "code"<br />
interpretation: <br />
defaultValue: "Undecided"<br />
leftClassValue: "False Positive"<br />
rightClassValue: "Confirmed"<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer&diff=3011Help:XSvacer2025-06-04T12:42:24Z<p>M.vinogradov: Add AI assistant link</p>
<hr />
<div>= XSvacer — расширение функциональности Svacer =<br />
{{Note|text=На данный момент расширенные функции находятся на стадии внедрения. В последующих релизах возможно изменение форматов конфигурации и API взаимодействия с указанными функциями}}<br />
<br />
Начиная с релиза [[Changelog#Release_9-0-0|9.0.0]] в Svacer появились расширенные функции, которые могут быть активированы по требованию. По умолчанию данные функции неактивны.<br />
<br />
Доступные функции:<br />
* [[Help:XSvacer:Webide|Webide]] — среда разработки на базе [https://theia-ide.org/ Theia IDE], с помощью которой можно просматривать исходный код снимка, предупреждения анализатора и разметку.<br />
* [[Help:XSvacer:AIAssistant|AIAssistant]] — ИИ-ассистент, позволяющий использовать модель машинного обучения для помощи при разметке предупреждений.<br />
<br />
== Активация функций ==<br />
<br />
Активировать функции можно, указав флаг <code>--xsvacer.features feature_name</code> при запуске Svacer. Флаг можно указать несколько раз, чтобы активировать несколько функций.<br />
<br />
Также список активных функций можно настроить в конфигурационном yaml-файле <code>svacer.cfg</code> в разделе <code>xsvacer.features</code>.<br />
Значением данного ключа является список строк с названиями активируемых функций:<br />
...<br />
xsvacer:<br />
features:<br />
- webide<br />
- aiAssistant<br />
...<br />
<br />
При установке флага <code>--xsvacer.features</code> список функций, указанный в конфигурационном файле <code>svacer.cfg</code>, будет проигнорирован.</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&diff=3010Help:XSvacer:AIAssistant2025-06-04T05:48:16Z<p>M.vinogradov: AI-model short description</p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
== Поддержка ИИ-ассистента для разметки предупреждений ==<br />
<br />
Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.<br />
<br />
ИИ-ассистент предназначен для разметки предупреждений статусами <code style="white-space: pre;">Confirmed</code> и <code style="white-space: pre;">False Positive</code>, которые были предсказаны моделью машинного обучения.<br />
<br />
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.<br />
<br />
{{Note|text=[[Help:XSvacer:AIAssistant:Deploy|Инструкция по активации и запуску функциональности]] ИИ-ассистента}}<br />
<br />
== Описание интерфейса ИИ-ассистента==<br />
=== Разметка одного маркера ===<br />
Чтобы разметить один маркер с помощью ИИ-ассистента:<br />
:1. Нажмите кнопку [[File:Icon AI.png|25px]] [[Help:UI manual#Функции правой панели|на правой панели]] или в виджете маркера на [[Help:UI manual#Вкладка с исходным кодом|вкладке с исходным кодом]].<br />
:[[File:221 Правая панель. Переход к ИИ-разметке.png|thumb|none|x200px|Правая панель. Переход к ИИ-разметке]]<br />
:[[File:222 Виджет элемента трассы. Переход к ИИ-разметке.png|thumb|none|x150px|Виджет маркера на вкладке с исходным кодом. Переход к ИИ-разметке]]<br />
:2. В открывшемся окне разметки:<br />
::а) Выберите модель AI, с помощью которой ИИ-ассистент рассчитает статус разметки.<br />
::Спрогнозированный статус и уровень доверия прогнозу отобразятся в этом же окне. <br />
::Если маркер уже размечен и его статус совпадает с прогнозным, то в окне отобразится сообщение об этом и дальнейшая разметка станет недоступна.<br />
::б) Введите комментарий.<br />
::в) Нажмите кнопку '''Применить'''.<br />
:<gallery mode="packed" heights="250px" style="float:left; clear:right; margin-right:1em; margin-left:1em"><br />
223 Окно ИИ-разметки.png|Окно ИИ-разметки<br />
224 Окно ИИ-разметки. Статус совпадает.png|Окно ИИ-разметки. Прогнозный статус совпадает с существующим<br />
</gallery><br />
<br clear=all /><br />
:Статус, установленный с помощью ИИ-ассистента, отобразится в верхней части правой панели и в виджете маркера на вкладке с исходным кодом с отметкой [[File:Icon AI 2.png|15px]]. Также этой иконкой будет отмечен статус в комментарии, добавленном при разметке, который дополнительно содержит информацию о проведенной разметке: время, имя модели машинного обучения, уровень доверия прогнозу.<br />
:Дополнительная информация также отображается при наведении курсора на иконку [[File:Icon AI 2.png|15px]].<br />
<gallery mode="packed" heights="250px" style="float:left; clear:right; margin-right:1em; margin-left:1em"><br />
225 Правая панель. Результат ИИ-разметки.png|Правая панель. Результат ИИ-разметки<br />
227 Правая панель. Комментарий об ИИ-разметке.png|Правая панель. Комментарий об ИИ-разметке<br />
</gallery><br />
<br clear=all /><br />
[[File:226 Виджет элемента трассы. Результат ИИ-разметки.png|thumb|none|x150px|Виджет элемента трассы. Результат ИИ-разметки]]<br />
<br />
=== Групповая разметка маркеров ===<br />
Чтобы разметить несколько маркеров с помощью ИИ-ассистента одновременно:<br />
:1. Если планируется разметить большое количество маркеров, то для ускорения составления прогноза запустите предварительный рассчет (опционально) – на вкладке [[Help:UI manual#Вкладка «Информация о снимке»|'''Информация о снимке''']] [[Help:UI manual#Функции центральной панели|центральной панели]] нажмите кнопку '''Проанализировать с AI'''.<br />
:Расчет прогнозируемого статуса для каждого маркера запустится в фоновом режиме. В это время на месте кнопки будет отображаться анимированная иконка ожидания.<br />
:[[File:228 Информация о снимке. Предварительный расчет.png|thumb|none|x200px|Информация о снимке. Кнопка перехода к предварительному расчету статусов маркеров]]<br />
:2. Выберите маркеры для разметки – установите флажки в строках [[Help:UI manual#Таблица маркеров|таблицы]].<br />
:3. Нажмите кнопку [[File:Icon AI.png|25px]] (доступна, если выбраны маркеры в таблице).<br />
:4. В открывшемся окне разметки:<br />
::а) Выберите модель AI, с помощью которой ИИ-ассистент рассчитает статус разметки.<br />
::Спрогнозированные статусы и уровни доверия прогнозу отобразятся в этом же окне в таблице маркеров. При этом размеченные ранее маркеры окрашены в цвет, соответствующий выставленному статусу. <br />
::В таблице доступна сортировка значений в столбцах '''Детектор''', '''Файл''', '''Строка''' и '''Уровень доверия''', а в столбце '''Статус разметки''' доступна фильтрация по значению прогнозируемого статуса.<br />
::б) Введите комментарий.<br />
::в) Выберите маркеры, которые требуется разметить, – установите флажки в столбце '''Статус разметки'''.<br />
::Если маркер уже размечен и его статус совпадает с прогнозным, то он недоступен для установки флажка.<br />
::г) Нажмите кнопку '''Применить'''.<br />
:[[File:229 Окно групповой ИИ-разметки.png|thumb|none|x300px|Окно групповой ИИ-разметки]]<br />
:Прогресс разметки отображается в соответствующем окне. Запущенный процесс можно полностью отменить нажатием кнопки '''Отмена'''.<br />
:[[File:56 Окно прогресса разметки.png|thumb|none|x100px|Окно прогресса разметки]]<br />
=== Фильтрация маркеров по режиму разметки ===<br />
По умолчанию в [[Help:UI manual#Таблица маркеров|таблице маркеров]] отображаются все маркеры: как размеченные вручную, так и размеченные с помощью ИИ-ассистента.<br />
Чтобы отобразить маркеры только с одним режимом разметки, воспользуйтесь [[Help:UI manual#Настройка и использование пользовательских фильтров|пользовательскими фильтрами]]:<br />
* для отображения только маркеров, размеченных вручную, выберите фильтр '''Режим разметки''' – '''Вручную''';<br />
* для отображения только маркеров, размеченных с помощью ИИ-ассистента, выберите фильтр '''Режим разметки''' – '''С помощью ИИ'''.<br />
[[File:230 Пользовательские фильтры. Режимы разметки.png|thumb|none|x400px|Пользовательские фильтры. Режимы разметки]]<br />
<br />
== Описание модели xgb.joblib ИИ-ассистента ==<br />
<br />
Модель обучена на базе 50000+ размеченных предупреждений.<br />
<br />
Для предсказания статуса разметки нами используются:<br />
# языковая модель codebert-base для получения эмбеддингов кода;<br />
# метод градиентного бустинга (xgboost) для решения задачи классификации.</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&diff=2989Help:XSvacer:AIAssistant2025-05-30T07:30:31Z<p>M.vinogradov: Separate deployment manual from common description</p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
== Поддержка ИИ-ассистента для разметки предупреждений ==<br />
<br />
Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.<br />
<br />
ИИ-ассистент предназначен для разметки предупреждений статусами <code style="white-space: pre;">Confirmed</code> и <code style="white-space: pre;">False Positive</code>, которые были предсказаны моделью машинного обучения.<br />
<br />
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.<br />
<br />
{{Note|text=[[Help:XSvacer:AIAssistant:Deploy|Инструкция по активации и запуску функциональности]] ИИ-ассистента}}<br />
<br />
== Описание интерфейса ИИ-ассистента==</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant:Deploy&diff=2988Help:XSvacer:AIAssistant:Deploy2025-05-30T07:27:08Z<p>M.vinogradov: Separate deployment manual from common description</p>
<hr />
<div>== Активация и запуск функциональности ==<br />
<br />
ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:<br />
<br />
# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-ассистенту;<br />
# Развернуть и запустить сервис ИИ-ассистента;<br />
<br />
=== Активация функциональности <code style="white-space: pre;">xsvacer</code> при запуске Svacer ===<br />
<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features aiAssistant</code> при запуске Svacer.<br />
<br />
==== Настройка доступа к ИИ-ассистенту в Svacer ====<br />
<br />
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code><br />
<br />
Изменить адрес, по которому Svacer будет подключаться к ИИ-ассистенту, можно одним из способов:<br />
<br />
# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистента}:{порт}/</nowiki></code><br />
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел<br />
<br />
<pre style="white-space: pre;"><br />
...<br />
xsvacer:<br />
...<br />
aiAssistant:<br />
assistantHostUrl: http://{адрес ИИ-ассистента}:{порт}/<br />
...<br />
</pre><br />
<br />
==== Настройка значения флага <code>--public-url</code> ====<br />
<br />
В связи с тем, что ИИ-ассистент использует REST API Svacer, необходимо добавить url ИИ-ассистента в список публичных url Svacer. Это можно сделать, добавив при запуске Svacer флаг:<br />
<br />
--public-url {url ИИ-ассистента}<br />
<br />
Пример:<br />
<br />
<nowiki>--xsvacer.features aiAssistant --public-url https://svacer-ai-demo.ispras.ru</nowiki><br />
<br />
{{Note|text=Данная настройка связана с функциональностью генерации коротких ссылок}}<br />
<br />
=== Развёртывание и запуск ИИ-ассистента ===<br />
<br />
При развёртывании ИИ-ассистента необходимо выполнить следующие действия:<br />
<br />
# Запустить docker-контейнер с моделью машинного обучения;<br />
# При необходимости: развернуть postresql-сервер для хранения базы данных ИИ-ассистента;<br />
# Запустить сервис ИИ-ассистента.<br />
<br />
==== Запуск docker-контейнера с моделью машинного обучения ====<br />
<br />
Docker-образ контейнера с моделью можно скачать по ссылке: https://svacer.ispras.ru/docker/images/svacer-ai-model-host.1.0.0.tar.gz (3.3GB)<br />
<br />
Далее docker-образ необходимо загрузить на docker-хост с помощью команды<br />
<br />
docker image load -i /path/to/svacer-ai-model-host.1.0.0.tar.gz<br />
<br />
После этого docker-контейнер может быть запущен следующей командой<br />
<br />
docker volume create svacer-ai-cache<br />
docker volume create svacer-ai-pgdata<br />
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<br />
<br />
Том <code style="white-space: pre;">cache</code> будет содержать кэш сервиса взаимодействия с моделью машинного обучения.<br />
<br />
Том <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ postgres'а.<br />
<br />
Порт <code>7000</code> будет использоваться по умолчанию, если не были изменены [[#Параметры подключения сервиса модели машинного обучения|параметры подключения сервиса машинного обучения]]<br />
<br />
==== Запуск ИИ-ассистента ====<br />
<br />
Исполняемый файл ИИ-ассистента можно скачать по ссылке: https://svacer.ispras.ru/releases/svacer-ai/svacer-ai-1-0-0-linux.tar.gz (53MB)<br />
<br />
После этого ИИ-ассистент может быть запущен командой <code>svacerai-server run</code><br />
<br />
===== Флаги команды запуска ИИ-ассистента =====<br />
<br />
Глобальные флаги <code>svacerai-server help</code><br />
<br />
NAME:<br />
svacerai-server - Svace AI server<br />
<br />
USAGE:<br />
svacerai-server [global options] command [command options] [arguments...]<br />
<br />
COMMANDS:<br />
run<br />
help, h Shows a list of commands or help for one command<br />
<br />
GLOBAL OPTIONS:<br />
--debug (default: false) [$SVACER_AI_DEBUG]<br />
--log-level value Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]<br />
--log value Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.<br />
--config value Define path to file with config in YAML format (by default svacer-ai.cfg).<br />
--help, -h show help<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|debug<br />
|bool<br />
|Отладочный режим логирования<br />
|-<br />
|log-level<br />
|string<br />
|Уровень логирования<br />
|-<br />
|log<br />
|string<br />
|Путь к файлу с логами<br />
|-<br />
|config<br />
|string<br />
|Путь к [[#Конфигурация по умолчанию|конфигурационному файлу]]<br />
|}<br />
<br />
Флаги запуска ИИ-ассистента <code>svacerai-server run help</code><br />
<br />
NAME:<br />
svacerai-server run<br />
<br />
USAGE:<br />
svacerai-server run [command options] [arguments...]<br />
<br />
OPTIONS:<br />
--pg value Defines PostgreSQL connection URL<br />
--host value Defines host name for the server<br />
--svacer-host value Defines remote Svacer host<br />
--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><br />
--help, -h show help<br />
<br />
{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Формат<br />
|-<br />
|style="width: 80px"|pg<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS<br />
|-<br />
|host<br />
|string<br />
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент<br />
|<code>{ip адрес}:{порт}</code><br />
|-<br />
|svacer-host<br />
|string<br />
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент<br />
|https://en.wikipedia.org/wiki/URL#Syntax<br />
|-<br />
|ai-host<br />
|[]string<br />
|Url сервиса с моделями машинного обучения<br />
|https://en.wikipedia.org/wiki/URL#Syntax<br />
|}<br />
<br />
Пример:<br />
<nowiki>svacerai-server run --pg postgres://svace:svace@127.0.0.1:5432/svacer_ai --host localhost:8095 --svacer-host http://localhost:8094</nowiki><br />
<br />
=== Конфигурация ИИ-ассистента ===<br />
<br />
Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|db/url<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|<code>postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable</code><br />
|-<br />
|http/host<br />
|string<br />
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент<br />
|<code>localhost:8081</code><br />
|-<br />
|http/svacerHostUrl<br />
<br />
ai/svacerHostUrl<br />
|string<br />
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент<br />
|<code><nowiki>http://localhost:8080/</nowiki></code><br />
|-<br />
|http/svacerClientTlsCfg?<br />
<br />
ai/svacerClientTlsCfg<br />
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]<br />
|Настройки безопасного подключения к Svacer<br />
|<pre style="white-space: pre;"><br />
svacerClientTlsCfg:<br />
insecureSkipVerify: true<br />
</pre><br />
|-<br />
|ai/svacerReviewCommentTemplate<br />
|string<br />
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code><br />
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]<br />
|-<br />
|ai/svacerReviewTags<br />
|[]string<br />
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента<br />
|<code>[AI]</code><br />
|-<br />
|hosts<br />
|map[string]object<br />
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент<br />
|<pre style="white-space: pre;"><br />
{id сервиса}:<br />
{параметры подключения}<br />
(см. описание ниже)<br />
</pre><br />
|}<br />
<br />
==== Параметры подключения сервиса модели машинного обучения ====<br />
<br />
Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|url<br />
|string<br />
|Url сервиса с моделями машинного обучения<br />
|<code><nowiki>http://localhost:7000</nowiki></code><br />
|-<br />
|settings/requestBatchSize<br />
|int<br />
|Количество предупреждений, отправляемых для анализа моделью за раз<br />
|<code>512</code><br />
|-<br />
|settings/httpMultipartParameterName<br />
<br />
settings/httpMultipartFileName<br />
<br />
settings/httpMultipartContentType<br />
|string<br />
|Параметра multipart-запроса вызова модели<br />
|<pre style="white-space: pre;"><br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
</pre><br />
|-<br />
|resources/modelList<br />
<br />
resources/modelInference<br />
<br />
resources/logs<br />
|string<br />
|Сопоставление названий ресурсов сервиса моделей<br />
|<pre style="white-space: pre;"><br />
modelList: "/models_info"<br />
<br />
modelInference: "/use_model_for_file"<br />
<br />
logs: "/log_file"<br />
</pre><br />
|-<br />
|defaults/dataCollector/csvSeparator<br />
|string<br />
|Разделитель csv-файла, который отправляется в сервис моделей<br />
|<code>","</code><br />
|-<br />
|defaults/dataCollector/additionalLineNumber<br />
|int<br />
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей<br />
|<code>0</code><br />
|-<br />
|defaults/dataCollector/csvColumns<br />
|[]string<br />
|Названия столбцов csv-файла, который отправляется в сервис моделей<br />
|<code>[id, warnClass, code]</code><br />
|-<br />
|defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
|string<br />
|Названия статусов, которые присваиваются результату вызова модели<br />
|<pre style="white-space: pre;"><br />
defaultValue: "Undecided"<br />
<br />
leftClassValue: "False Positive"<br />
<br />
rightClassValue: "Confirmed"<br />
</pre><br />
|}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.<br />
<br />
{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}<br />
<br />
<pre style="white-space: pre;"><br />
varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"<br />
varSvacerClientTlsCfg: &svacerClientTlsCfg<br />
insecureSkipVerify: true<br />
db:<br />
url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"<br />
http:<br />
host: "localhost:8081"<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
ai:<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
svacerReviewCommentTemplate: |+<br />
`Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`<br />
<br />
`AI model: {{.Pipeline.Name}}`<br />
<br />
`Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`<br />
<br />
svacerReviewTags:<br />
- AI<br />
hosts:<br />
server-status:<br />
url: "http://localhost:7000"<br />
settings:<br />
requestBatchSize: 512<br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
resources:<br />
modelList: "/models_info"<br />
modelInference: "/use_model_for_file"<br />
logs: "/log_file"<br />
defaults:<br />
dataCollector:<br />
csvSeparator: ","<br />
additionalLinesNumber: 0<br />
csvColumns:<br />
- "id"<br />
- "warnClass"<br />
- "code"<br />
interpretation: <br />
defaultValue: "Undecided"<br />
leftClassValue: "False Positive"<br />
rightClassValue: "Confirmed"<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&diff=2984Help:XSvacer:AIAssistant2025-05-27T09:49:14Z<p>M.vinogradov: --public-url description</p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
== Поддержка ИИ-ассистента для разметки предупреждений ==<br />
<br />
Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.<br />
<br />
ИИ-ассистент предназначен для разметки предупреждений статусами <code style="white-space: pre;">Confirmed</code> и <code style="white-space: pre;">False Positive</code>, которые были предсказаны моделью машинного обучения.<br />
<br />
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.<br />
<br />
== Активация и запуск функциональности ==<br />
<br />
ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:<br />
<br />
# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-ассистенту;<br />
# Развернуть и запустить сервис ИИ-ассистента;<br />
<br />
=== Активация функциональности <code style="white-space: pre;">xsvacer</code> при запуске Svacer ===<br />
<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features aiAssistant</code> при запуске Svacer.<br />
<br />
==== Настройка доступа к ИИ-ассистенту в Svacer ====<br />
<br />
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code><br />
<br />
Изменить адрес, по которому Svacer будет подключаться к ИИ-ассистенту, можно одним из способов:<br />
<br />
# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистента}:{порт}/</nowiki></code><br />
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел<br />
<br />
<pre style="white-space: pre;"><br />
...<br />
xsvacer:<br />
...<br />
aiAssistant:<br />
assistantHostUrl: http://{адрес ИИ-ассистента}:{порт}/<br />
...<br />
</pre><br />
<br />
==== Настройка значения флага <code>--public-url</code> ====<br />
<br />
В связи с тем, что ИИ-ассистент использует REST API Svacer, необходимо добавить url ИИ-ассистента в список публичных url Svacer. Это можно сделать, добавив при запуске Svacer флаг <code>--public-url {url ИИ-ассистента}</code>.<br />
<br />
{{Note|text=Данная настройка связана с функциональностью генерации коротких ссылок}}<br />
<br />
=== Развёртывание и запуск ИИ-ассистента ===<br />
<br />
При развёртывании ИИ-ассистента необходимо выполнить следующие действия:<br />
<br />
# Запустить docker-контейнер с моделью машинного обучения;<br />
# При необходимости: развернуть postresql-сервер для хранения базы данных ИИ-ассистента;<br />
# Запустить сервис ИИ-ассистента.<br />
<br />
==== Запуск docker-контейнера с моделью машинного обучения ====<br />
<br />
Docker-образ контейнера с моделью можно скачать по ссылке: https://svacer.ispras.ru/docker/images/svacer-ai-model-host.1.0.0.tar.gz (3.3GB)<br />
<br />
Далее docker-образ необходимо загрузить на docker-хост с помощью команды<br />
<br />
docker image load -i /path/to/svacer-ai-model-host.1.0.0.tar.gz<br />
<br />
После этого docker-контейнер может быть запущен следующей командой<br />
<br />
docker volume create svacer-ai-cache<br />
docker volume create svacer-ai-pgdata<br />
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<br />
<br />
Том <code style="white-space: pre;">cache</code> будет содержать кэш сервиса взаимодействия с моделью машинного обучения.<br />
<br />
Том <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ postgres'а.<br />
<br />
Порт <code>7000</code> будет использоваться по умолчанию, если не были изменены [[#Параметры подключения сервиса модели машинного обучения|параметры подключения сервиса машинного обучения]]<br />
<br />
==== Запуск ИИ-ассистента ====<br />
<br />
Исполняемый файл ИИ-ассистента можно скачать по ссылке: https://svacer.ispras.ru/releases/svacer-ai/svacer-ai-1-0-0-linux.tar.gz (53MB)<br />
<br />
После этого ИИ-ассистент может быть запущен командой <code>svacerai-server run</code><br />
<br />
===== Флаги команды запуска ИИ-ассистента =====<br />
<br />
Глобальные флаги <code>svacerai-server help</code><br />
<br />
NAME:<br />
svacerai-server - Svace AI server<br />
<br />
USAGE:<br />
svacerai-server [global options] command [command options] [arguments...]<br />
<br />
COMMANDS:<br />
run<br />
help, h Shows a list of commands or help for one command<br />
<br />
GLOBAL OPTIONS:<br />
--debug (default: false) [$SVACER_AI_DEBUG]<br />
--log-level value Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]<br />
--log value Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.<br />
--config value Define path to file with config in YAML format (by default svacer-ai.cfg).<br />
--help, -h show help<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|debug<br />
|bool<br />
|Отладочный режим логирования<br />
|-<br />
|log-level<br />
|string<br />
|Уровень логирования<br />
|-<br />
|log<br />
|string<br />
|Путь к файлу с логами<br />
|-<br />
|config<br />
|string<br />
|Путь к [[#Конфигурация по умолчанию|конфигурационному файлу]]<br />
|}<br />
<br />
Флаги запуска ИИ-ассистента <code>svacerai-server run help</code><br />
<br />
NAME:<br />
svacerai-server run<br />
<br />
USAGE:<br />
svacerai-server run [command options] [arguments...]<br />
<br />
OPTIONS:<br />
--pg value Defines PostgreSQL connection URL<br />
--host value Defines host name for the server<br />
--svacer-host value Defines remote Svacer host<br />
--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><br />
--help, -h show help<br />
<br />
{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Формат<br />
|-<br />
|style="width: 80px"|pg<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS<br />
|-<br />
|host<br />
|string<br />
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент<br />
|<code>{ip адрес}:{порт}</code><br />
|-<br />
|svacer-host<br />
|string<br />
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент<br />
|https://en.wikipedia.org/wiki/URL#Syntax<br />
|-<br />
|ai-host<br />
|[]string<br />
|Url сервиса с моделями машинного обучения<br />
|https://en.wikipedia.org/wiki/URL#Syntax<br />
|}<br />
<br />
=== Конфигурация ИИ-ассистента ===<br />
<br />
Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|db/url<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|<code>postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable</code><br />
|-<br />
|http/host<br />
|string<br />
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент<br />
|<code>localhost:8081</code><br />
|-<br />
|http/svacerHostUrl<br />
<br />
ai/svacerHostUrl<br />
|string<br />
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент<br />
|http://localhost:8080/<br />
|-<br />
|http/svacerClientTlsCfg?<br />
<br />
ai/svacerClientTlsCfg<br />
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]<br />
|Настройки безопасного подключения к Svacer<br />
|<pre style="white-space: pre;"><br />
svacerClientTlsCfg:<br />
insecureSkipVerify: true<br />
</pre><br />
|-<br />
|ai/svacerReviewCommentTemplate<br />
|string<br />
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code><br />
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]<br />
|-<br />
|ai/svacerReviewTags<br />
|[]string<br />
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента<br />
|<code>[AI]</code><br />
|-<br />
|hosts<br />
|map[string]object<br />
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент<br />
|<pre style="white-space: pre;"><br />
{id сервиса}:<br />
{параметры подключения}<br />
(см. описание ниже)<br />
</pre><br />
|}<br />
<br />
==== Параметры подключения сервиса модели машинного обучения ====<br />
<br />
Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|url<br />
|string<br />
|Url сервиса с моделями машинного обучения<br />
|<code>http://localhost:7000</code><br />
|-<br />
|settings/requestBatchSize<br />
|int<br />
|Количество предупреждений, отправляемых для анализа моделью за раз<br />
|<code>512</code><br />
|-<br />
|settings/httpMultipartParameterName<br />
<br />
settings/httpMultipartFileName<br />
<br />
settings/httpMultipartContentType<br />
|string<br />
|Параметра multipart-запроса вызова модели<br />
|<pre style="white-space: pre;"><br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
</pre><br />
|-<br />
|resources/modelList<br />
<br />
resources/modelInference<br />
<br />
resources/logs<br />
|string<br />
|Сопоставление названий ресурсов сервиса моделей<br />
|<pre style="white-space: pre;"><br />
modelList: "/models_info"<br />
<br />
modelInference: "/use_model_for_file"<br />
<br />
logs: "/log_file"<br />
</pre><br />
|-<br />
|defaults/dataCollector/csvSeparator<br />
|string<br />
|Разделитель csv-файла, который отправляется в сервис моделей<br />
|<code>","</code><br />
|-<br />
|defaults/dataCollector/additionalLineNumber<br />
|int<br />
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей<br />
|<code>0</code><br />
|-<br />
|defaults/dataCollector/csvColumns<br />
|[]string<br />
|Названия столбцов csv-файла, который отправляется в сервис моделей<br />
|<code>[id, warnClass, code]</code><br />
|-<br />
|defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
|string<br />
|Названия статусов, которые присваиваются результату вызова модели<br />
|<pre style="white-space: pre;"><br />
defaultValue: "Undecided"<br />
<br />
leftClassValue: "False Positive"<br />
<br />
rightClassValue: "Confirmed"<br />
</pre><br />
|}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.<br />
<br />
{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}<br />
<br />
<pre style="white-space: pre;"><br />
varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"<br />
varSvacerClientTlsCfg: &svacerClientTlsCfg<br />
insecureSkipVerify: true<br />
db:<br />
url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"<br />
http:<br />
host: "localhost:8081"<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
ai:<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
svacerReviewCommentTemplate: |+<br />
`Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`<br />
<br />
`AI model: {{.Pipeline.Name}}`<br />
<br />
`Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`<br />
<br />
svacerReviewTags:<br />
- AI<br />
hosts:<br />
server-status:<br />
url: "http://localhost:7000"<br />
settings:<br />
requestBatchSize: 512<br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
resources:<br />
modelList: "/models_info"<br />
modelInference: "/use_model_for_file"<br />
logs: "/log_file"<br />
defaults:<br />
dataCollector:<br />
csvSeparator: ","<br />
additionalLinesNumber: 0<br />
csvColumns:<br />
- "id"<br />
- "warnClass"<br />
- "code"<br />
interpretation: <br />
defaultValue: "Undecided"<br />
leftClassValue: "False Positive"<br />
rightClassValue: "Confirmed"<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&diff=2973Help:XSvacer:AIAssistant2025-05-26T09:02:28Z<p>M.vinogradov: port 7000 description</p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
= Поддержка ИИ-ассистента для разметки предупреждений =<br />
<br />
Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.<br />
<br />
ИИ-ассистент предназначен для разметки предупреждений статусами <code style="white-space: pre;">Confirmed</code> и <code style="white-space: pre;">False Positive</code>, которые были предсказаны моделью машинного обучения.<br />
<br />
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.<br />
<br />
= Активация и запуск функциональности =<br />
<br />
ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:<br />
<br />
# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-асстистенту;<br />
# Развернуть и запустить сервис ИИ-ассистента;<br />
<br />
== Активация функциональности <code style="white-space: pre;">xsvacer</code> при запуске Svacer ==<br />
<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features aiAssistant</code> при запуске Svacer.<br />
<br />
=== Настройка доступа к ИИ-ассистенту в Svacer ===<br />
<br />
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code><br />
<br />
Изменить адрес по которому Svacer будет подключаться к ИИ-ассистенту можно сделать одним из способов:<br />
<br />
# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистена}:{порт}/</nowiki></code><br />
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел<br />
<pre style="white-space: pre;"><br />
...<br />
xsvacer:<br />
...<br />
aiAssistant:<br />
assistantHostUrl: http://{адрес ИИ-ассистена}:{порт}/<br />
...<br />
</pre><br />
<br />
== Развёртывание и запуск ИИ-ассистента ==<br />
<br />
При развёртывании ИИ-ассистента необходимо выполнить следующие действия:<br />
<br />
# Запустить docker-контейнер с моделью машинного обучения;<br />
# При необходимости: развернуть postresql-сервер для хранения базы данных ИИ-ассистента;<br />
# Запустить сервис ИИ-ассистента.<br />
<br />
=== Запуск docker-контейнера с моделью машинного обучения ===<br />
<br />
Docker-образ контейнера с моделью можно скачать по ссылке - https://svacer.ispras.ru/docker/images/svacer-ai-model-host.1.0.0.tar.gz (3.3GB)<br />
<br />
Далее docker-образ необходимо загрузить на docker-хост с помощью команды<br />
<br />
docker image load -i /path/to/svacer-ai-model-host.1.0.0.tar.gz<br />
<br />
После этого docker-контейнер может быть запущен следующей командой<br />
<br />
docker volume create svacer-ai-cache<br />
docker volume create svacer-ai-pgdata<br />
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<br />
<br />
Том <code style="white-space: pre;">cache</code> будет содержать кеш сервиса взаимодействия с моделью машинного обучения.<br />
<br />
Том <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ postgres'а.<br />
<br />
Порт <code>7000</code> будет использоваться по умолчанию, если не были изменены [[#Параметры подключения сервиса модели машинного обучения|параметры подключения сервиса машинного обучения]]<br />
<br />
=== Запуск ИИ-ассистента ===<br />
<br />
Исполняемый файл ИИ-ассистента можно скачать по ссылке - https://svacer.ispras.ru/releases/svacer-ai/svacer-ai-1-0-0-linux.tar.gz (53MB)<br />
<br />
После этого ИИ-ассистент может быть запущен командой <code>svacerai-server run</code><br />
<br />
==== Флаги команды запуска ИИ-ассистента ====<br />
<br />
"Глобальные" флаги <code>svacerai-server help</code><br />
<br />
NAME:<br />
svacerai-server - Svace AI server<br />
<br />
USAGE:<br />
svacerai-server [global options] command [command options] [arguments...]<br />
<br />
COMMANDS:<br />
run<br />
help, h Shows a list of commands or help for one command<br />
<br />
GLOBAL OPTIONS:<br />
--debug (default: false) [$SVACER_AI_DEBUG]<br />
--log-level value Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]<br />
--log value Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.<br />
--config value Define path to file with config in YAML format (by default svacer-ai.cfg).<br />
--help, -h show help<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|debug<br />
|bool<br />
|Отладочный режим логирования<br />
|-<br />
|log-level<br />
|string<br />
|Уровень логирования<br />
|-<br />
|log<br />
|string<br />
|Путь к файлу с логами<br />
|-<br />
|config<br />
|string<br />
|Путь к [[#Конфигурация по молчанию|конфигурационному файлу]]<br />
|}<br />
<br />
Флаги запуска ИИ-ассистента <code>svacerai-server run help</code><br />
<br />
NAME:<br />
svacerai-server run<br />
<br />
USAGE:<br />
svacerai-server run [command options] [arguments...]<br />
<br />
OPTIONS:<br />
--pg value Defines PostgreSQL connection URL<br />
--host value Defines host name for the server<br />
--svacer-host value Defines remote Svacer host<br />
--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><br />
--help, -h show help<br />
<br />
{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|pg<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|-<br />
|host<br />
|string<br />
|Адрес сетевого интерфейса и порт на которых будет запущен ИИ-ассистент<br />
|-<br />
|svacer-host<br />
|string<br />
|Адрес сервиса Svacer к API которого будет обращаться ИИ-ассистент<br />
|-<br />
|ai-host<br />
|[]string<br />
|Адреса сервиса с моделями машинного обучения<br />
|}<br />
<br />
== Конфигурация ИИ-ассистента ==<br />
<br />
Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|db/url<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable<br />
|-<br />
|http/host<br />
|string<br />
|Адрес сетевого интерфейса и порт на которых будет запущен ИИ-ассистент<br />
|localhost:8081<br />
|-<br />
|http/svacerHostUrl<br />
<br />
ai/svacerHostUrl<br />
|string<br />
|Адрес сервиса Svacer к API которого будет обращаться ИИ-ассистент<br />
|http://localhost:8080/<br />
|-<br />
|http/svacerClientTlsCfg?<br />
<br />
ai/svacerClientTlsCfg<br />
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]<br />
|Настройки безопасного подключения к Svacer<br />
|<pre style="white-space: pre;"><br />
svacerClientTlsCfg:<br />
insecureSkipVerify: true<br />
</pre><br />
|-<br />
|ai/svacerReviewCommentTemplate<br />
|string<br />
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code><br />
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]<br />
|-<br />
|ai/svacerReviewTags<br />
|[]string<br />
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента<br />
|[AI]<br />
|-<br />
|hosts<br />
|map[string]object<br />
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент<br />
|<pre style="white-space: pre;"><br />
{id сервиса}:<br />
{параметры подключения}<br />
(см. описание ниже)<br />
</pre><br />
|}<br />
<br />
=== Параметры подключения сервиса модели машинного обучения ===<br />
<br />
Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|url<br />
|string<br />
|Адрес сервиса с моделями машинного обучения<br />
|http://localhost:7000<br />
|-<br />
|settings/requestBatchSize<br />
|int<br />
|Количество предупреждений отправляемых для анализа моделью за раз<br />
|512<br />
|-<br />
|settings/httpMultipartParameterName<br />
<br />
settings/httpMultipartFileName<br />
<br />
settings/httpMultipartContentType<br />
|string<br />
|Параметра multipart-запроса вызова модели<br />
|<pre style="white-space: pre;"><br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
</pre><br />
|-<br />
|resources/modelList<br />
<br />
resources/modelInference<br />
<br />
resources/logs<br />
|string<br />
|Сопоставление названий ресурсов сервиса моделей<br />
|<pre style="white-space: pre;"><br />
modelList: "/models_info"<br />
<br />
modelInference: "/use_model_for_file"<br />
<br />
logs: "/log_file"<br />
</pre><br />
|-<br />
|defaults/dataCollector/csvSeparator<br />
|string<br />
|Разделитель csv-файла, который отправляется в сервис моделей<br />
|","<br />
|-<br />
|defaults/dataCollector/additionalLineNumber<br />
|int<br />
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей<br />
|0<br />
|-<br />
|defaults/dataCollector/csvColumns<br />
|[]string<br />
|Названия столбцов csv-файла, который отправляется в сервис моделей<br />
|[id, warnClass, code]<br />
|-<br />
|defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
|string<br />
|Названия статусов, которые присваиваются результату вызова модели<br />
|<pre style="white-space: pre;"><br />
defaultValue: "Undecided"<br />
<br />
leftClassValue: "False Positive"<br />
<br />
rightClassValue: "Confirmed"<br />
</pre><br />
|}<br />
<br />
== Конфигурация по умолчанию ==<br />
<br />
Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.<br />
<br />
{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}<br />
<pre style="white-space: pre;"><br />
varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"<br />
varSvacerClientTlsCfg: &svacerClientTlsCfg<br />
insecureSkipVerify: true<br />
db:<br />
url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"<br />
http:<br />
host: "localhost:8081"<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
ai:<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
svacerReviewCommentTemplate: |+<br />
`Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`<br />
<br />
`AI model: {{.Pipeline.Name}}`<br />
<br />
`Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`<br />
<br />
svacerReviewTags:<br />
- AI<br />
hosts:<br />
server-status:<br />
url: "http://localhost:7000"<br />
settings:<br />
requestBatchSize: 512<br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
resources:<br />
modelList: "/models_info"<br />
modelInference: "/use_model_for_file"<br />
logs: "/log_file"<br />
defaults:<br />
dataCollector:<br />
csvSeparator: ","<br />
additionalLinesNumber: 0<br />
csvColumns:<br />
- "id"<br />
- "warnClass"<br />
- "code"<br />
interpretation: <br />
defaultValue: "Undecided"<br />
leftClassValue: "False Positive"<br />
rightClassValue: "Confirmed"<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&diff=2971Help:XSvacer:AIAssistant2025-05-26T08:29:20Z<p>M.vinogradov: svacer-ai-1.0.0-linux.tar.gz link</p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
= Поддержка ИИ-ассистента для разметки предупреждений =<br />
<br />
Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.<br />
<br />
ИИ-ассистент предназначен для разметки предупреждений статусами <code style="white-space: pre;">Confirmed</code> и <code style="white-space: pre;">False Positive</code>, которые были предсказаны моделью машинного обучения.<br />
<br />
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.<br />
<br />
= Активация и запуск функциональности =<br />
<br />
ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:<br />
<br />
# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-асстистенту;<br />
# Развернуть и запустить сервис ИИ-ассистента;<br />
<br />
== Активация функциональности <code style="white-space: pre;">xsvacer</code> при запуске Svacer ==<br />
<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features aiAssistant</code> при запуске Svacer.<br />
<br />
=== Настройка доступа к ИИ-ассистенту в Svacer ===<br />
<br />
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code><br />
<br />
Изменить адрес по которому Svacer будет подключаться к ИИ-ассистенту можно сделать одним из способов:<br />
<br />
# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистена}:{порт}/</nowiki></code><br />
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел<br />
<pre style="white-space: pre;"><br />
...<br />
xsvacer:<br />
...<br />
aiAssistant:<br />
assistantHostUrl: http://{адрес ИИ-ассистена}:{порт}/<br />
...<br />
</pre><br />
<br />
== Развёртывание и запуск ИИ-ассистента ==<br />
<br />
При развёртывании ИИ-ассистента необходимо выполнить следующие действия:<br />
<br />
# Запустить docker-контейнер с моделью машинного обучения;<br />
# При необходимости: развернуть postresql-сервер для хранения базы данных ИИ-ассистента;<br />
# Запустить сервис ИИ-ассистента.<br />
<br />
=== Запуск docker-контейнера с моделью машинного обучения ===<br />
<br />
Docker-образ контейнера с моделью можно скачать по ссылке - https://svacer.ispras.ru/docker/images/svacer-ai-model-host.1.0.0.tar.gz (3.3GB)<br />
<br />
Далее docker-образ необходимо загрузить на docker-хост с помощью команды<br />
<br />
docker image load -i /path/to/svacer-ai-model-host.1.0.0.tar.gz<br />
<br />
После этого docker-контейнер может быть запущен следующей командой<br />
<br />
docker volume create svacer-ai-cache<br />
docker volume create svacer-ai-pgdata<br />
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<br />
<br />
Том <code style="white-space: pre;">cache</code> будет содержать кеш сервиса взаимодействия с моделью машинного обучения.<br />
<br />
Том <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ postgres'а.<br />
<br />
=== Запуск ИИ-ассистента ===<br />
<br />
Исполняемый файл ИИ-ассистента можно скачать по ссылке - https://svacer.ispras.ru/releases/svacer-ai/svacer-ai-1-0-0-linux.tar.gz<br />
<br />
После этого ИИ-ассистент может быть запущен командой <code>svacerai-server run</code><br />
<br />
==== Флаги команды запуска ИИ-ассистента ====<br />
<br />
"Глобальные" флаги <code>svacerai-server help</code><br />
<br />
NAME:<br />
svacerai-server - Svace AI server<br />
<br />
USAGE:<br />
svacerai-server [global options] command [command options] [arguments...]<br />
<br />
COMMANDS:<br />
run<br />
help, h Shows a list of commands or help for one command<br />
<br />
GLOBAL OPTIONS:<br />
--debug (default: false) [$SVACER_AI_DEBUG]<br />
--log-level value Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]<br />
--log value Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.<br />
--config value Define path to file with config in YAML format (by default svacer-ai.cfg).<br />
--help, -h show help<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|debug<br />
|bool<br />
|Отладочный режим логирования<br />
|-<br />
|log-level<br />
|string<br />
|Уровень логирования<br />
|-<br />
|log<br />
|string<br />
|Путь к файлу с логами<br />
|-<br />
|config<br />
|string<br />
|Путь к [[#Конфигурация по молчанию|конфигурационному файлу]]<br />
|}<br />
<br />
Флаги запуска ИИ-ассистента <code>svacerai-server run help</code><br />
<br />
NAME:<br />
svacerai-server run<br />
<br />
USAGE:<br />
svacerai-server run [command options] [arguments...]<br />
<br />
OPTIONS:<br />
--pg value Defines PostgreSQL connection URL<br />
--host value Defines host name for the server<br />
--svacer-host value Defines remote Svacer host<br />
--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><br />
--help, -h show help<br />
<br />
{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|pg<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|-<br />
|host<br />
|string<br />
|Адрес сетевого интерфейса и порт на которых будет запущен ИИ-ассистент<br />
|-<br />
|svacer-host<br />
|string<br />
|Адрес сервиса Svacer к API которого будет обращаться ИИ-ассистент<br />
|-<br />
|ai-host<br />
|[]string<br />
|Адреса сервиса с моделями машинного обучения<br />
|}<br />
<br />
== Конфигурация ИИ-ассистента ==<br />
<br />
Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|db/url<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable<br />
|-<br />
|http/host<br />
|string<br />
|Адрес сетевого интерфейса и порт на которых будет запущен ИИ-ассистент<br />
|localhost:8081<br />
|-<br />
|http/svacerHostUrl<br />
<br />
ai/svacerHostUrl<br />
|string<br />
|Адрес сервиса Svacer к API которого будет обращаться ИИ-ассистент<br />
|http://localhost:8080/<br />
|-<br />
|http/svacerClientTlsCfg?<br />
<br />
ai/svacerClientTlsCfg<br />
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]<br />
|Настройки безопасного подключения к Svacer<br />
|<pre style="white-space: pre;"><br />
svacerClientTlsCfg:<br />
insecureSkipVerify: true<br />
</pre><br />
|-<br />
|ai/svacerReviewCommentTemplate<br />
|string<br />
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code><br />
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]<br />
|-<br />
|ai/svacerReviewTags<br />
|[]string<br />
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента<br />
|[AI]<br />
|-<br />
|hosts<br />
|map[string]object<br />
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент<br />
|<pre style="white-space: pre;"><br />
{id сервиса}:<br />
{параметры подключения}<br />
(см. описание ниже)<br />
</pre><br />
|}<br />
<br />
=== Параметры подключения сервиса модели машинного обучения ===<br />
<br />
Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|url<br />
|string<br />
|Адрес сервиса с моделями машинного обучения<br />
|http://localhost:7000<br />
|-<br />
|settings/requestBatchSize<br />
|int<br />
|Количество предупреждений отправляемых для анализа моделью за раз<br />
|512<br />
|-<br />
|settings/httpMultipartParameterName<br />
<br />
settings/httpMultipartFileName<br />
<br />
settings/httpMultipartContentType<br />
|string<br />
|Параметра multipart-запроса вызова модели<br />
|<pre style="white-space: pre;"><br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
</pre><br />
|-<br />
|resources/modelList<br />
<br />
resources/modelInference<br />
<br />
resources/logs<br />
|string<br />
|Сопоставление названий ресурсов сервиса моделей<br />
|<pre style="white-space: pre;"><br />
modelList: "/models_info"<br />
<br />
modelInference: "/use_model_for_file"<br />
<br />
logs: "/log_file"<br />
</pre><br />
|-<br />
|defaults/dataCollector/csvSeparator<br />
|string<br />
|Разделитель csv-файла, который отправляется в сервис моделей<br />
|","<br />
|-<br />
|defaults/dataCollector/additionalLineNumber<br />
|int<br />
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей<br />
|0<br />
|-<br />
|defaults/dataCollector/csvColumns<br />
|[]string<br />
|Названия столбцов csv-файла, который отправляется в сервис моделей<br />
|[id, warnClass, code]<br />
|-<br />
|defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
|string<br />
|Названия статусов, которые присваиваются результату вызова модели<br />
|<pre style="white-space: pre;"><br />
defaultValue: "Undecided"<br />
<br />
leftClassValue: "False Positive"<br />
<br />
rightClassValue: "Confirmed"<br />
</pre><br />
|}<br />
<br />
== Конфигурация по умолчанию ==<br />
<br />
Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.<br />
<br />
{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}<br />
<pre style="white-space: pre;"><br />
varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"<br />
varSvacerClientTlsCfg: &svacerClientTlsCfg<br />
insecureSkipVerify: true<br />
db:<br />
url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"<br />
http:<br />
host: "localhost:8081"<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
ai:<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
svacerReviewCommentTemplate: |+<br />
`Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`<br />
<br />
`AI model: {{.Pipeline.Name}}`<br />
<br />
`Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`<br />
<br />
svacerReviewTags:<br />
- AI<br />
hosts:<br />
server-status:<br />
url: "http://localhost:7000"<br />
settings:<br />
requestBatchSize: 512<br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
resources:<br />
modelList: "/models_info"<br />
modelInference: "/use_model_for_file"<br />
logs: "/log_file"<br />
defaults:<br />
dataCollector:<br />
csvSeparator: ","<br />
additionalLinesNumber: 0<br />
csvColumns:<br />
- "id"<br />
- "warnClass"<br />
- "code"<br />
interpretation: <br />
defaultValue: "Undecided"<br />
leftClassValue: "False Positive"<br />
rightClassValue: "Confirmed"<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&diff=2968Help:XSvacer:AIAssistant2025-05-25T20:43:29Z<p>M.vinogradov: initialization</p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
= Поддержка ИИ-ассистента для разметки предупреждений =<br />
<br />
Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.<br />
<br />
ИИ-ассистент предназначен для разметки предупреждений статусами <code style="white-space: pre;">Confirmed</code> и <code style="white-space: pre;">False Positive</code>, которые были предсказаны моделью машинного обучения.<br />
<br />
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.<br />
<br />
= Активация и запуск функциональности =<br />
<br />
ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:<br />
<br />
# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-асстистенту;<br />
# Развернуть и запустить сервис ИИ-ассистента;<br />
<br />
== Активация функциональности <code style="white-space: pre;">xsvacer</code> при запуске Svacer ==<br />
<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features aiAssistant</code> при запуске Svacer.<br />
<br />
=== Настройка доступа к ИИ-ассистенту в Svacer ===<br />
<br />
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code><br />
<br />
Изменить адрес по которому Svacer будет подключаться к ИИ-ассистенту можно сделать одним из способов:<br />
<br />
# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистена}:{порт}/</nowiki></code><br />
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел<br />
<pre style="white-space: pre;"><br />
...<br />
xsvacer:<br />
...<br />
aiAssistant:<br />
assistantHostUrl: http://{адрес ИИ-ассистена}:{порт}/<br />
...<br />
</pre><br />
<br />
== Развёртывание и запуск ИИ-ассистента ==<br />
<br />
При развёртывании ИИ-ассистента необходимо выполнить следующие действия:<br />
<br />
# Запустить docker-контейнер с моделью машинного обучения;<br />
# При необходимости: развернуть postresql-сервер для хранения базы данных ИИ-ассистента;<br />
# Запустить сервис ИИ-ассистента.<br />
<br />
=== Запуск docker-контейнера с моделью машинного обучения ===<br />
<br />
Docker-образ контейнера с моделью можно скачать по ссылке - https://svacer.ispras.ru/docker/images/svacer-ai-model-host.1.0.0.tar.gz (3.3GB)<br />
<br />
Далее docker-образ необходимо загрузить на docker-хост с помощью команды<br />
<br />
docker image load -i /path/to/svacer-ai-model-host.1.0.0.tar.gz<br />
<br />
После этого docker-контейнер может быть запущен следующей командой<br />
<br />
docker volume create svacer-ai-cache<br />
docker volume create svacer-ai-pgdata<br />
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<br />
<br />
Том <code style="white-space: pre;">cache</code> будет содержать кеш сервиса взаимодействия с моделью машинного обучения.<br />
<br />
Том <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ postgres'а.<br />
<br />
=== Запуск ИИ-ассистента ===<br />
<br />
Исполняемый файл ИИ-ассистента можно скачать по ссылке - TODO<br />
<br />
После этого ИИ-ассистент может быть запущен командой <code>svacerai-server run</code><br />
<br />
==== Флаги команды запуска ИИ-ассистента ====<br />
<br />
"Глобальные" флаги <code>svacerai-server help</code><br />
<br />
NAME:<br />
svacerai-server - Svace AI server<br />
<br />
USAGE:<br />
svacerai-server [global options] command [command options] [arguments...]<br />
<br />
COMMANDS:<br />
run<br />
help, h Shows a list of commands or help for one command<br />
<br />
GLOBAL OPTIONS:<br />
--debug (default: false) [$SVACER_AI_DEBUG]<br />
--log-level value Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]<br />
--log value Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.<br />
--config value Define path to file with config in YAML format (by default svacer-ai.cfg).<br />
--help, -h show help<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|debug<br />
|bool<br />
|Отладочный режим логирования<br />
|-<br />
|log-level<br />
|string<br />
|Уровень логирования<br />
|-<br />
|log<br />
|string<br />
|Путь к файлу с логами<br />
|-<br />
|config<br />
|string<br />
|Путь к [[#Конфигурация по молчанию|конфигурационному файлу]]<br />
|}<br />
<br />
Флаги запуска ИИ-ассистента <code>svacerai-server run help</code><br />
<br />
NAME:<br />
svacerai-server run<br />
<br />
USAGE:<br />
svacerai-server run [command options] [arguments...]<br />
<br />
OPTIONS:<br />
--pg value Defines PostgreSQL connection URL<br />
--host value Defines host name for the server<br />
--svacer-host value Defines remote Svacer host<br />
--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><br />
--help, -h show help<br />
<br />
{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|pg<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|-<br />
|host<br />
|string<br />
|Адрес сетевого интерфейса и порт на которых будет запущен ИИ-ассистент<br />
|-<br />
|svacer-host<br />
|string<br />
|Адрес сервиса Svacer к API которого будет обращаться ИИ-ассистент<br />
|-<br />
|ai-host<br />
|[]string<br />
|Адреса сервиса с моделями машинного обучения<br />
|}<br />
<br />
== Конфигурация ИИ-ассистента ==<br />
<br />
Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.j<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|db/url<br />
|string<br />
|Строка подключения к базе данных ИИ-ассистента<br />
|postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable<br />
|-<br />
|http/host<br />
|string<br />
|Адрес сетевого интерфейса и порт на которых будет запущен ИИ-ассистент<br />
|localhost:8081<br />
|-<br />
|http/svacerHostUrl<br />
<br />
ai/svacerHostUrl<br />
|string<br />
|Адрес сервиса Svacer к API которого будет обращаться ИИ-ассистент<br />
|http://localhost:8080/<br />
|-<br />
|http/svacerClientTlsCfg?<br />
<br />
ai/svacerClientTlsCfg<br />
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]<br />
|Настройки безопасного подключения к Svacer<br />
|<pre style="white-space: pre;"><br />
svacerClientTlsCfg:<br />
insecureSkipVerify: true<br />
</pre><br />
|-<br />
|ai/svacerReviewCommentTemplate<br />
|string<br />
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code><br />
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]<br />
|-<br />
|ai/svacerReviewTags<br />
|[]string<br />
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента<br />
|[AI]<br />
|-<br />
|hosts<br />
|map[string]object<br />
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент<br />
|<pre style="white-space: pre;"><br />
{id сервиса}:<br />
{параметры подключения}<br />
(см. описание ниже)<br />
</pre><br />
|}<br />
<br />
=== Параметры подключения сервиса модели машинного обучения ===<br />
<br />
Параметры подключения сервисов модели задаются в виде map'ы, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|url<br />
|string<br />
|Адрес сервиса с моделями машинного обучения<br />
|http://localhost:7000<br />
|-<br />
|settings/requestBatchSize<br />
|int<br />
|Количество предупреждений отправляемых для анализа моделью за раз<br />
|512<br />
|-<br />
|settings/httpMultipartParameterName<br />
<br />
settings/httpMultipartFileName<br />
<br />
settings/httpMultipartContentType<br />
|string<br />
|Параметра multipart-запроса вызова модели<br />
|<pre style="white-space: pre;"><br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
</pre><br />
|-<br />
|resources/modelList<br />
<br />
resources/modelInference<br />
<br />
resources/logs<br />
|string<br />
|Сопоставление названий ресурсов сервиса моделей<br />
|<pre style="white-space: pre;"><br />
modelList: "/models_info"<br />
<br />
modelInference: "/use_model_for_file"<br />
<br />
logs: "/log_file"<br />
</pre><br />
|-<br />
|defaults/dataCollector/csvSeparator<br />
|string<br />
|Разделитель csv-файла, который отправляется в сервис моделей<br />
|","<br />
|-<br />
|defaults/dataCollector/additionalLineNumber<br />
|int<br />
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей<br />
|0<br />
|-<br />
|defaults/dataCollector/csvColumns<br />
|[]string<br />
|Названия столбцов csv-файла, который отправляется в сервис моделей<br />
|[id, warnClass, code]<br />
|-<br />
|defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
<br />
defaults/interpretation/defaultValue<br />
|string<br />
|Названия статусов, которые присваиваются результату вызова модели<br />
|<pre style="white-space: pre;"><br />
defaultValue: "Undecided"<br />
<br />
leftClassValue: "False Positive"<br />
<br />
rightClassValue: "Confirmed"<br />
</pre><br />
|}<br />
<br />
== Конфигурация по умолчанию ==<br />
<br />
Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.<br />
<br />
{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}<br />
<pre style="white-space: pre;"><br />
varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"<br />
varSvacerClientTlsCfg: &svacerClientTlsCfg<br />
insecureSkipVerify: true<br />
db:<br />
url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"<br />
http:<br />
host: "localhost:8081"<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
ai:<br />
svacerHostUrl: *svacerHostUrl<br />
svacerClientTlsCfg: *svacerClientTlsCfg<br />
svacerReviewCommentTemplate: |+<br />
`Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`<br />
<br />
`AI model: {{.Pipeline.Name}}`<br />
<br />
`Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`<br />
<br />
svacerReviewTags:<br />
- AI<br />
hosts:<br />
server-status:<br />
url: "http://localhost:7000"<br />
settings:<br />
requestBatchSize: 512<br />
httpMultipartParameterName: "file"<br />
httpMultipartFileName: "file.csv"<br />
httpMultipartContentType: "application/vnd.ms-excel"<br />
resources:<br />
modelList: "/models_info"<br />
modelInference: "/use_model_for_file"<br />
logs: "/log_file"<br />
defaults:<br />
dataCollector:<br />
csvSeparator: ","<br />
additionalLinesNumber: 0<br />
csvColumns:<br />
- "id"<br />
- "warnClass"<br />
- "code"<br />
interpretation: <br />
defaultValue: "Undecided"<br />
leftClassValue: "False Positive"<br />
rightClassValue: "Confirmed"<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=2960Help:XSvacer:Webide2025-05-20T07:53:16Z<p>M.vinogradov: Релиз 11. Удалена настройка шаблона комментария sarif/commenttemplate</p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
= Поддержка среды разработки Theia IDE =<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске Svacer.<br />
<br />
При запуске функциональности Webide также будет запущена функциональность [[Help:XSvacer:Docker|docker]].<br />
<br />
При активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов<br />
* в пользовательском интерфейсе на вкладке "Информация о снимке" появляется кнопка "Открыть в IDE"<br />
* устанавливается подключение к хосту docker, на котором будут запускаться контейнеры с экземплярами IDE<br />
<br />
=== Быстрый запуск функциональности с настройками по умолчанию ===<br />
<br />
Для того, чтобы начать пользоваться функциональностью запуска IDE без изменения конфигурационных параметров, нужно выполнить следующие действия:<br />
# Настройка доступа к docker-хосту:<br />
## Запустить docker со настройками по умолчанию (dockerd должен слушать unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option)<br />
## Проверить, что у пользователя под которым будет запускаться Svacer есть доступ к unix-сокету docker-хоста <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/engine/install/linux-postinstall<br />
# Настроить права доступа у пользователей, которые смогут запускать IDE: требуются разрешения на проект/ветку "Просмотр маркеров" и "Экспорт разметки"<br />
# Перезапустить Svacer с флагом <code style="white-space: pre;">--xsvacer.features webide</code><br />
# ''Опционально.'' Для ускорения первого запуска IDE:<br />
## Скачать архив с 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+]<br />
## Загрузить docker-образ из архива на docker-хост: <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint...</code><br />
<br />
После этого у пользователей с указанными правами должна появиться кнопка "Открыть в IDE" на панели с информацией о снимке.<br />
<br />
{{Note}} IDE с исходным кодом снимков будут запускаться в новых вкладках браузера. Обычно все браузеры блокируют автоматическое открытие вкладки и показывают соответствующее предупреждение.<br />
<br />
Например, в Firefox:<br />
<br />
[[File:Firefox popup notification ru.png]]<br />
<br />
В таком случае нужно дать разрешение на открытие вкладки с IDE:<br />
<br />
[[File:Firefox popup notification expanded ru.png|x150px]]<br />
<br />
<br />
При необходимости изменения настроек подключения к docker-хосту:<br />
# Скопировать [[Help:XSvacer:Docker#Конфигурация_по_умолчанию|конфигурацию docker по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/docker</code><br />
<br />
При необходимости изменения настроек запуска IDE:<br />
# Скопировать [[#Конфигурация_по_умолчанию|конфигурацию webide по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/webide</code><br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске Svacer указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В [[Help:XSvacer:Webide#Конфигурация|конфигурации]] функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE<br />
# У пользователя Svacer имеются разрешения "Просмотр маркеров" и "Экспорт разметки" на проект, в котором находится снимок, для которого нужно запустить IDE<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка "Открыть в IDE".<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code><br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается<br />
#** Если IDE недоступна: продолжается процесс запуска. IDE будет перезапущена<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code>xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code><br />
# Исходный код снимка скачивается в "корневую папку снимка"<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sarif/filenametemplate</code><br />
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>. Если docker-образ отсутствует, он будет загружен на хост<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code>running</code> — процесс запуска IDE продолжается<br />
##** в статусе <code>created</code>, <code>exited</code> или <code>paused</code> — контейнер будет запущен<br />
##** в других статусах — вернётся соответствующая ошибка и процесс запуска IDE прервётся<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code><br />
#* Если за отведённое время ответ от IDE получен — процесс запуска завершается<br />
#* Если ответ не получен — вернётся ошибка <code>ide not ready</code><br />
<br />
При возникновении ошибки на одном из этапов запуска IDE артефакты, созданные на предыдущих этапах, останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
{{Note|type=reminder|text=Причиной возникновения ошибки "ide not ready" может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>. В этом случае рекомендуется попробовать повторно запустить IDE через короткий промежуток времени}}<br />
<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется проверить:<br />
# Сетевую доступность docker-хоста<br />
# Настройки фаервола на docker-хосте<br />
# Настройки биндинга docker-контейнера c IDE<br />
::<code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code><br />
::Контейнер должен быть подключён к доступному сетевому интерфейсу<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с префиксом <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code><br />
<br />
Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
:<code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>POST http://docker-host:35353/socket.io/?...</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
Для запуска IDE в окне браузера нужно указать адрес<br />
<br />
:<code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code><br />
<br />
{{Note}} Завершающий слеш обязателен!<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы Svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода<br />
DELETE /api/snapshots/{snapshot_id}/ide<br />
с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>. В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
По умолчанию установлен параметр конфигурации<br />
<br />
xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true<br />
<br />
Это означает, что после остановки docker-контейнер будет автоматически удалён.<br />
<br />
Чтобы изменить это поведение, настройка<br />
xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove<br />
<br />
должна быть установлена в <code>false</code> на момент запуска docker-контейнера IDE. Это можно сделать, например, установив значение переменной окружения<br />
<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false<br />
<br />
{{Note|type=error|text=При использовании версии Svacer 9.0.0 установка <code>autoremove: false</code> вызывает ошибку запуска. Исправлено в версии [[Svacer#Релизы|9.0.1]].'''}}<br />
<br />
При корректной остановке (например SIGTERM) Svacer автоматически остановит все запущенные docker-контейнеры IDE.<br />
<br />
=== Подключение к IDE после некорректного завершения Svacer ===<br />
<br />
При запуске Svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах. При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке Svacer все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!}}<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> — идентификатор IDE<br />
:<code style="white-space: pre;">name</code> — название IDE<br />
:<code style="white-space: pre;">order</code> — порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка.<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> — действие<br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Доступные действия:'''<br />
* <code style="white-space: pre;">update_markup</code> — обновление предупреждений и разметки (sarif-файла)<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например, для default-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code><br />
<br />
Раздел конфигурации для управления функциональностью — <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому необходимо также [[Help:XSvacer:Docker|настроить доступ к docker-хосту]] в разделе <code style="white-space: pre;">xsvacer/docker</code>, иначе функциональность WebIDE не сможет работать корректно.<br />
<br />
В случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]].<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!}}<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации default)<br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0<br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0)<br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на машине со Svacer<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources<br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на хосте docker. Нужен при использовании удалённого docker-хоста, т. к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
|<br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker. По умолчанию <code style="white-space: pre;">"/"</code><br />
|<br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|{{Note|text=В версии 10.0.0 заменён на [[Help:XSvacer:Webide#Параметры_экспорта_sarif-файла_с_разметкой_предупреждений|sarif]]}}<br />
Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"</nowiki><br />
|}<br />
<br />
==== Параметры экспорта sarif-файла с разметкой предупреждений ====<br />
<br />
Данные параметры используются для настройки экспорта sarif-файлов с разметкой предупреждений, выполненной в Svacer.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|sarif<br />
|map<br />
|Настройки экспорта sarif-файла<br />
|<br />
|-<br />
|sarif/filenametemplate<br />
|golang template string<br />
|Шаблон для формирования названия sarif-файла. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"warnings.sarif"</nowiki><br />
|-<br />
|sarif/commenttemplate<br />
|golang template string<br />
|{{Note|text=Удалён в версии 11.0.0}}<br />
Шаблон для формирования элемента списка комментариев предупреждения при экспорте в sarif-файл. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|Comment]]<br />
|<nowiki>"{{if trim .Text}}`[{{.CreateTs.Local.Format \"02.01.2006 15:04\"}}] {{.CreatedBy}}:`\n\n{{trim .Text}}{{end}}"</nowiki><br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только стандартный менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
|<br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default<br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
|<br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default<br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|<nowiki>"theia-1-46-{{.StartArgs.SnapshotID}}"</nowiki><br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список меток docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer<br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
|<br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint<br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|Svacer 11+: 1.46.0.sarif.clang.11.0.0.1<br />
Svacer 10+: 1.46.0.sarif.clang.10.0.0<br />
<br />
Svacer 9+: 1.46.0.sarif.clang<br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост<br />
* repository — будет вызван docker pull образа <code>{image/name}:{image/tag}</code><br />
* file — будет вызван docker load с URL <code>image/sourcefileurl</code><br />
|file<br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|URL откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
URL может содержать:<br />
* путь к локальному файлу: схема <code>file://</code><br />
* http/https-адрес: схема <code>http://</code> или <code>https://</code><br />
|Svacer 11+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz<br />
Svacer 10+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz<br />
<br />
Svacer 9+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
|<br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70<br />
|<br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379<br />
|<br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true<br />
|-<br />
|docker/container/hostconfig/portbindings<br />
|map<br />
|<br />
|<br />
"3000/tcp":<br />
:- hostport: 0<br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104<br />
|<br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
|<br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10<br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms<br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
Comment {<br />
ID string<br />
Text string<br />
Ref string<br />
CreatedBy string<br />
CreatedByID string<br />
CreateTs time.Time<br />
UpdateTs *time.Time<br />
UpdatedBy string<br />
UpdatedByID string<br />
}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sarif:<br />
filenametemplate: "warnings.sarif"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang.11.0.0.1<br />
sourcetype: file<br />
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
По умолчанию используется 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/).<br />
<br />
{{Note|text=При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы}}<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения<br />
<br />
XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code><br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске Svacer:<br />
<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в корневые папки, заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code><br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code><br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code><br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code><br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code><br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code><br />
#*: метки с названиями <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><br />
# При использовании rootless-хоста docker будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста|настройкам]]<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр<br />
<br />
xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl<br />
<br />
Содержит значение<br />
<br />
Svacer 11+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.11.0.0.1.tar.gz<br />
Svacer 10+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz<br />
Svacer 9+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
<br />
По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т. к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго.<br />
<br />
Для ускорения первого запуска IDE докер образ можно загрузить на хост docker вручную. Для этого необходимо:<br />
<br />
# Скачать файл архива<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint...</code><br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0 1.46.0].<br />
<br />
При этом была изменена компоновка расширений Theia. Результат выполнения <code>git diff</code>:<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "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"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа:<br />
docker build -t theia-blueprint:1.46.0.sarif.clang... -f browser.Dockerfile .<br />
<br />
Команда экспорта docker-образа:<br />
docker image save theia-blueprint:1.46.0.sarif.clang... | gzip > /path/to/tar/theia-blueprint.1.46.0.sarif.clang....tar.gz<br />
<br />
== Известные проблемы ==<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.<br />
<br />
В 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.<br />
<br />
Поэтому для решения данной проблемы Svacer должен открываться по HTTPS или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&diff=2561Help:XSvacer:Webide:SvacerAsDockerContainer2025-03-12T09:41:32Z<p>M.vinogradov: </p>
<hr />
<div>= Поддержка функциональности [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide webide] когда Svacer развёрнут в docker-контейнере =<br />
<br />
На данный момент функциональность запуска Theia IDE по умолчанию настроена на запуск Svacer с помощью исполняемого файла, "рядом" с docker'ом.<br />
<br />
Для поддержки функциональности <code>webide</code> когда Svacer развёрнут в docker-контейнере необходимо решить следующие задачи:<br />
<br />
# Предоставить docker-контейнеру Svacer доступ к управлению контейнерами IDE;<br />
# Активация функциональности <code style="white-space: pre;">webide</code> в docker-контейнере Svacer;<br />
# Организация сетевого доступа между контейнером Svacer и контейнерами IDE;<br />
# Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE;<br />
<br />
Детали каждой задачи и варианты решения приведены ниже.<br />
<br />
{{Note|type=info|text=Приведённые решения основаны на развёртывании Svacer с помощью файла [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml]}}<br />
<br />
== Предоставление контейнеру Svacer доступа к управлению контейнерами IDE ==<br />
<br />
Функциональность запуска IDE основана на том, что Svacer управляет контейнерами IDE с помощью API docker'а. Поэтому необходимо предоставить доступ к API docker'а из docker-контейнера Svacer.<br />
<br />
=== Решение ===<br />
<br />
Один из способов подключения к API docker'а является использование socket-файла <code>/var/run/docker.sock</code>. Чтобы Svacer получил доступ к этому файлу, его необходимо примонтировать к docker-контейнеру:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /var/run/docker.sock:/var/run/docker.sock:ro<br />
...<br />
</pre><br />
<br />
== Изменение настроек Svacer - <code>svacer.cfg</code> ==<br />
<br />
Дальнейшие шаги связаны с изменением настроек Svacer. В случае, когда Svacer развёрнут в docker-контейнере, это можно сделать следующим образом:<br />
# Создать конфигурационный файл <code>svacer.cfg</code>;<br />
# Перенести настройки функциональности <code>webide</code>;<br />
# Примонтировать файл к рабочей директории docker-контейнера Svacer;<br />
# Перезапустить контейнер Svacer;<br />
<br />
Чтобы примонтировать <code>svacer.cfg</code> к контейнеру Svacer нужно в файл <code>docker-compose.yml</code> добавить строку:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /path/to/svacer.cfg:/svacer/bin/svacer.cfg:ro<br />
...<br />
</pre><br />
<br />
=== Перенос настроек функциональности <code>webide</code> в <code>svacer.cfg</code> ===<br />
<br />
Скопировать секцию с [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.BF.D0.BE_.D1.83.D0.BC.D0.BE.D0.BB.D1.87.D0.B0.D0.BD.D0.B8.D1.8E настройками по умолчанию] в <code>svacer.cfg</code><br />
<br />
== Активация функциональности <code>webide</code> ==<br />
<br />
Варианты активации функциональности <code>webide</code>:<br />
# указать флаг <code>--xsvacer.features webide</code> при запуске Svacer;<br />
# в конфигурационном файле (<code>svacer.cfg</code>) добавить значение <code>webide</code> в список <code>/xsvacer/features</code>;<br />
<br />
=== Решение ===<br />
<br />
Второй вариант активации функциональности является более предпочтительным. В <code>svacer.cfg</code> необходимо добавить следующую настройку:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
features:<br />
- webide # активация функциональности webide<br />
...<br />
</pre><br />
<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<div style="font-weight:bold;line-height:1.6;">Альтернативное решение с использованием флага <code>--xsvacer.features webide</code></div><br />
<div class="mw-collapsible-content"><br />
В [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] используется docker-образ Svacer, собранный на основе [[Dockerfile]]. В данном файле содержится инструкция запуска Svacer<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
CMD /svacer/bin/svacer-server --memsettings=${MEMSETTINGS} run --store $STORE --pg $SVACER_PG_URL<br />
</pre><br />
<br />
Для активации функциональности IDE необходимо переопределить аргументы инструкции <code style="white-space: pre;">CMD</code> в файле <code>docker-compose.yml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
command: /bin/sh -c '/svacer/bin/svacer-server --memsettings=$${MEMSETTINGS} run --store $$STORE --pg $${SVACER_PG_URL} --xsvacer.features webide'<br />
</pre><br />
<br />
{{Note|type=info|text=Проверить актуальные значения аргументов инструкции <code>CMD</code> docker-образа можно с помощью команды <code>docker image inspect {имя образа}</code>}}<br />
</div></div><br />
<br />
== Организация сетевого доступа между контейнером Svacer и контейнерами IDE ==<br />
<br />
В текущей реализации при запуске docker-контейнер IDE публикует внутренний порт web-приложения Theia IDE на случайный порт всех сетевых интерфейсов (0.0.0.0) docker-хоста. Svacer хранит информацию на каком порте хоста развёрнуты соответствующие инстансы IDE и проксирует запросы к ним.<br />
<br />
Необходимо организовать доступ контейнера Svacer к портам docker-хоста, на которых опубликованы контейнеры IDE.<br />
<br />
=== Решение ===<br />
<br />
Чтобы предоставить доступ контейнера Svacer к контейнеру IDE нужно:<br />
# Определить ip-адрес интерфейса docker-хоста <code>docker0</code>;<br />
# Изменить настройку публикации портов контейнеров IDE на значение ip-адреса <code>docker0</code>.<br />
<br />
''' Определение ip-адреса <code>docker0</code>'''<br />
<br />
На docker-хосте выполнить команду <code>ip a</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
$ ip a<br />
...<br />
6: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default<br />
link/ether 82:70:b5:24:50:e4 brd ff:ff:ff:ff:ff:ff<br />
inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0<br />
valid_lft forever preferred_lft forever<br />
</pre><br />
<br />
В данном случае искомый ip-адрес - <code>172.17.0.1</code><br />
<br />
''' Изменение настроек публикации портов контейнеров IDE '''<br />
<br />
Настройки публикации порта контейнера IDE заданы в [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0_Theia_IDE конфигурации запуска IDE]. Настройки по умолчанию должны быть предварительно [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&action=submit#.D0.9F.D0.B5.D1.80.D0.B5.D0.BD.D0.BE.D1.81_.D0.BD.D0.B0.D1.81.D1.82.D1.80.D0.BE.D0.B5.D0.BA_.D1.84.D1.83.D0.BD.D0.BA.D1.86.D0.B8.D0.BE.D0.BD.D0.B0.D0.BB.D1.8C.D0.BD.D0.BE.D1.81.D1.82.D0.B8_webide_.D0.B2_svacer.cfg перенесены в <code>svacer.cfg</code>].<br />
<br />
В файле <code>svacer.cfg</code> нужно добавить параметр <code>hostip</code> со значением ip-адреса интерфейса <code>docker0</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
docker:<br />
...<br />
container:<br />
...<br />
hostconfig:<br />
...<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
hostip: 172.17.0.1 # новый параметр<br />
...<br />
</pre><br />
<br />
<br />
== Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE ==<br />
<br />
При запуске IDE для просмотра снимка, Svacer экспортирует исходный код снимка в папку на docker-хосте. Далее эта папка монтируется к контейнеру IDE, к пути <code>/home/project</code>, который использует Theia IDE в качестве папки проекта.<br />
<br />
При развёртывании Svacer в docker-контейнере необходимо настроить экспорт исходников в папку, которая может быть примонтирована к контейнеру IDE.<br />
<br />
=== Решение ===<br />
<br />
Путь к корневой папке, в которую будут экспортироваться исходники снимков, задаётся в конфигурационном параметре [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.91.D0.B0.D0.B7.D0.BE.D0.B2.D1.8B.D0.B5_.D0.BF.D0.B0.D1.80.D0.B0.D0.BC.D0.B5.D1.82.D1.80.D1.8B_.D0.BA.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D0.B8_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0 <code>sourcesroot</code>]. Так как этот же параметр используется для настройки пути к корневой папке на docker-хосте, которая будет примонтирована к контейнеру IDE, то пути к папке с исходным кодом снимков должны совпадать в контейнере Svacer и на docker-хосте.<br />
<br />
''' Пример конфигурации '''<br />
<br />
<code>svacer.cfg</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
sourcesroot: /data/snapshot-sources<br />
...<br />
</pre><br />
<br />
<code>docker-compose.yml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /data/snapshot-sources:/data/snapshot-sources # привязка с разрешением на запись<br />
...<br />
</pre><br />
<br />
== Примеры файлов с описанными изменениями ==<br />
<br />
Ниже приведены версии конфигурационных файлов, с изменениями которые были описаны выше. Изменённые строки содежат комментарии.<br />
<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<div style="font-weight:bold;line-height:1.6;"><code>svacer.cfg</code></div><br />
<div class="mw-collapsible-content"><br />
{{Note|type=info|text=Ниже приведён файл <code>svacer.cfg</code> содержащий только секцию <code>xsvacer</code>. Если файл <code>svacer.cfg</code> создан и содержит другие настройки, то приведённые ниже настройки должны быть перенесены в существующий файл}}<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
features:<br />
- webide # активация функциональности webide<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: /data/snapshot-sources # путь к базовой папке с исходным кодом снимков<br />
sarif:<br />
filenametemplate: "warnings.sarif"<br />
commenttemplate: "{{if trim .Text}}`[{{.CreateTs.Local.Format \"02.01.2006 15:04\"}}] {{.CreatedBy}}:`\n\n{{trim .Text}}{{end}}"<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
docker:<br />
hostid: default<br />
containernametemplate: "theia-1-46-{{.StartArgs.SnapshotID}}"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang.10.0.0<br />
sourcetype: file<br />
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT={{hostname}}<br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
hostip: 172.17.0.1 # ip-адрес интерфейса хоста docker0<br />
manager:<br />
type: default<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
{{Note|type=info|text=Проверить актуальные значения аргументов инструкции <code>CMD</code> docker-образа можно с помощью команды <code>docker image inspect {имя образа}</code>}}<br />
</div></div><br />
</div></div><br />
<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<div style="font-weight:bold;line-height:1.6;"><code>docker-compose.yml</code></div><br />
<div class="mw-collapsible-content"><br />
{{Note|type=info|text=Изменены внесены в файл [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml]}}<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
postgresql:<br />
image: postgres:17.0-bullseye<br />
container_name: svacer-postgres<br />
restart: always<br />
shm_size: 1g<br />
environment:<br />
- POSTGRES_DB=svace<br />
- POSTGRES_USER=svace<br />
- POSTGRES_PASSWORD=svace<br />
- POSTGRES_ROOT_PASSWORD=svace<br />
volumes:<br />
- svacer-postgres:/var/lib/postgresql/data<br />
networks:<br />
svacer:<br />
healthcheck:<br />
test: pg_isready -U svace<br />
interval: 8s<br />
start_period: 16s<br />
timeout: 4s<br />
retries: 4<br />
<br />
svacer:<br />
image: ispras/svacer:10-0-0<br />
container_name: svacer<br />
restart: always<br />
shm_size: 1g<br />
depends_on:<br />
postgresql:<br />
condition: service_healthy<br />
ports:<br />
- "3002:3002"<br />
- "8080:8080"<br />
environment:<br />
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace<br />
- STORE=/data/store<br />
volumes:<br />
- svacer-object-store:/data/store<br />
- /var/run/docker.sock:/var/run/docker.sock:ro # доступ к API docker'а из контейнера Svacer<br />
- ./svacer.cfg:/svacer/bin/svacer.cfg:ro # привязка конфигурационного файла svacer.cfg<br />
- /data/snapshot-sources:/data/snapshot-sources # writable привязка коневой папки с исходниками снимков. Пути до и после ":" должны совпадать.<br />
networks:<br />
svacer:<br />
healthcheck:<br />
test: curl --fail http://localhost:8080/api/health || exit 1<br />
interval: 8s<br />
start_period: 16s<br />
timeout: 4s<br />
retries: 4<br />
<br />
volumes:<br />
svacer-postgres:<br />
svacer-object-store:<br />
<br />
networks:<br />
svacer:<br />
</pre><br />
</div></div><br />
<br />
== Схемы компонентов ==<br />
<br />
Ниже приведены концептуальные схемы компонентов, на базе которых основана функциональность запуска IDE. Данные схемы могут быть использованы для поиска других решений приведённых выше задач.<br />
<br />
=== Стандартный запуск Svacer в виде сервиса ===<br />
<br />
[[File:Comp-svacer-webide-default-hosting.png]]<br />
<br />
=== Запуск Svacer внутри docker-контейнера ===<br />
<br />
[[File:Comp-svacer-in-container-webide-hosting.png]]</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=File:Comp-svacer-in-container-webide-hosting.png&diff=2560File:Comp-svacer-in-container-webide-hosting.png2025-03-11T11:12:39Z<p>M.vinogradov: M.vinogradov uploaded a new version of File:Comp-svacer-in-container-webide-hosting.png</p>
<hr />
<div>Диаграмма развёртывания компонентов функциональности запуска IDE если Svacer запущен в docker-контейнере</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&diff=2559Help:XSvacer:Webide:SvacerAsDockerContainer2025-03-11T11:10:08Z<p>M.vinogradov: </p>
<hr />
<div>= Поддержка функциональности [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide webide] когда Svacer развёрнут в docker-контейнере =<br />
<br />
На данный момент функциональность запуска Theia IDE по умолчанию настроена на запуск Svacer с помощью исполняемого файла, "рядом" с docker'ом.<br />
<br />
Для поддержки функциональности <code>webide</code> когда Svacer развёрнут в docker-контейнере необходимо решить следующие задачи:<br />
<br />
# Предоставить docker-контейнеру Svacer доступ к управлению контейнерами IDE;<br />
# Активация функциональности <code style="white-space: pre;">webide</code> в docker-контейнере Svacer;<br />
# Организация сетевого доступа между контейнером Svacer и контейнерами IDE;<br />
# Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE;<br />
<br />
Детали каждой задачи и варианты решения приведены ниже.<br />
<br />
{{Note|type=info|text=Приведённые решения основаны на развёртывании Svacer с помощью файла [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml]}}<br />
<br />
== Предоставление контейнеру Svacer доступа к управлению контейнерами IDE ==<br />
<br />
Функциональность запуска IDE основана на том, что Svacer управляет контейнерами IDE с помощью API docker'а. Поэтому необходимо предоставить доступ к API docker'а из docker-контейнера Svacer.<br />
<br />
=== Решение ===<br />
<br />
Один из способов подключения к API docker'а является использование socket-файла <code>/var/run/docker.sock</code>. Чтобы Svacer получил доступ к этому файлу, его необходимо примонтировать к docker-контейнеру:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /var/run/docker.sock:/var/run/docker.sock:ro<br />
...<br />
</pre><br />
<br />
== Изменение настроек Svacer - <code>svacer.cfg</code> ==<br />
<br />
Дальнейшие шаги связаны с изменением настроек Svacer. В случае, когда Svacer развёрнут в docker-контейнере, это можно сделать следующим образом:<br />
# Создать конфигурационный файл <code>svacer.cfg</code>;<br />
# Перенести настройки функциональности <code>webide</code>;<br />
# Примонтировать файл к рабочей директории docker-контейнера Svacer;<br />
# Перезапустить контейнер Svacer;<br />
<br />
Чтобы примонтировать <code>svacer.cfg</code> к контейнеру Svacer нужно в файл <code>docker-compose.yaml</code> добавить строку:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /path/to/svacer.cfg:/svacer/bin/svacer.cfg:ro<br />
...<br />
</pre><br />
<br />
=== Перенос настроек функциональности <code>webide</code> в <code>svacer.cfg</code> ===<br />
<br />
Скопировать секцию с [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.BF.D0.BE_.D1.83.D0.BC.D0.BE.D0.BB.D1.87.D0.B0.D0.BD.D0.B8.D1.8E настройками по умолчанию] в <code>svacer.cfg</code><br />
<br />
== Активация функциональности <code>webide</code> ==<br />
<br />
Варианты активации функциональности <code>webide</code>:<br />
# указать флаг <code>--xsvacer.features webide</code> при запуске Svacer;<br />
# в конфигурационном файле (<code>svacer.cfg</code>) добавить значение <code>webide</code> в список <code>/xsvacer/features</code>;<br />
<br />
=== Решение ===<br />
<br />
Второй вариант активации функциональности является более предпочтительным. В <code>svacer.cfg</code> необходимо добавить следующую настройку:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
features:<br />
- webide # активация функциональности webide<br />
...<br />
</pre><br />
<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<div style="font-weight:bold;line-height:1.6;">Альтернативное решение с использованием флага <code>--xsvacer.features webide</code></div><br />
<div class="mw-collapsible-content"><br />
В [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] используется docker-образ Svacer, собранный на основе [[Dockerfile]]. В данном файле содержится инструкция запуска Svacer<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
CMD /svacer/bin/svacer-server --memsettings=${MEMSETTINGS} run --store $STORE --pg $SVACER_PG_URL<br />
</pre><br />
<br />
Для активации функциональности IDE необходимо переопределить аргументы инструкции <code style="white-space: pre;">CMD</code> в файле <code>docker-compose.yml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
command: /bin/sh -c '/svacer/bin/svacer-server --memsettings=$${MEMSETTINGS} run --store $$STORE --pg $${SVACER_PG_URL} --xsvacer.features webide'<br />
</pre><br />
<br />
{{Note|type=info|text=Проверить актуальные значения аргументов инструкции <code>CMD</code> docker-образа можно с помощью команды <code>docker image inspect {имя образа}</code>}}<br />
</div></div><br />
<br />
== Организация сетевого доступа между контейнером Svacer и контейнерами IDE ==<br />
<br />
В текущей реализации при запуске docker-контейнер IDE публикует внутренний порт web-приложения Theia IDE на случайный порт всех сетевых интерфейсов (0.0.0.0) docker-хоста. Svacer хранит информацию на каком порте хоста развёрнуты соответствующие инстансы IDE и проксирует запросы к ним.<br />
<br />
Необходимо организовать доступ контейнера Svacer к портам docker-хоста, на которых опубликованы контейнеры IDE.<br />
<br />
=== Решение ===<br />
<br />
Чтобы предоставить доступ контейнера Svacer к контейнеру IDE нужно:<br />
# Определить ip-адрес интерфейса docker-хоста <code>docker0</code>;<br />
# Изменить настройку публикации портов контейнеров IDE на значение ip-адреса <code>docker0</code>.<br />
<br />
''' Определение ip-адреса <code>docker0</code>'''<br />
<br />
На docker-хосте выполнить команду <code>ip a</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
$ ip a<br />
...<br />
6: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default<br />
link/ether 82:70:b5:24:50:e4 brd ff:ff:ff:ff:ff:ff<br />
inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0<br />
valid_lft forever preferred_lft forever<br />
</pre><br />
<br />
В данном случае искомый ip-адрес - <code>172.17.0.1</code><br />
<br />
''' Изменение настроек публикации портов контейнеров IDE '''<br />
<br />
Настройки публикации порта контейнера IDE заданы в [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0_Theia_IDE конфигурации запуска IDE]. Настройки по умолчанию должны быть предварительно [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&action=submit#.D0.9F.D0.B5.D1.80.D0.B5.D0.BD.D0.BE.D1.81_.D0.BD.D0.B0.D1.81.D1.82.D1.80.D0.BE.D0.B5.D0.BA_.D1.84.D1.83.D0.BD.D0.BA.D1.86.D0.B8.D0.BE.D0.BD.D0.B0.D0.BB.D1.8C.D0.BD.D0.BE.D1.81.D1.82.D0.B8_webide_.D0.B2_svacer.cfg перенесены в <code>svacer.cfg</code>].<br />
<br />
В файле <code>svacer.cfg</code> нужно добавить параметр <code>hostip</code> со значением ip-адреса интерфейса <code>docker0</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
docker:<br />
...<br />
container:<br />
...<br />
hostconfig:<br />
...<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
hostip: 172.17.0.1 # новый параметр<br />
...<br />
</pre><br />
<br />
<br />
== Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE ==<br />
<br />
При запуске IDE для просмотра снимка, Svacer экспортирует исходный код снимка в папку на docker-хосте. Далее эта папка монтируется к контейнеру IDE, к пути <code>/home/project</code>, который использует Theia IDE в качестве папки проекта.<br />
<br />
При развёртывании Svacer в docker-контейнере необходимо настроить экспорт исходников в папку, которая может быть примонтирована к контейнеру IDE.<br />
<br />
=== Решение ===<br />
<br />
Путь к корневой папке, в которую будут экспортироваться исходники снимков, задаётся в конфигурационном параметре [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.91.D0.B0.D0.B7.D0.BE.D0.B2.D1.8B.D0.B5_.D0.BF.D0.B0.D1.80.D0.B0.D0.BC.D0.B5.D1.82.D1.80.D1.8B_.D0.BA.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D0.B8_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0 <code>sourcesroot</code>]. Так как этот же параметр используется для настройки пути к корневой папке на docker-хосте, которая будет примонтирована к контейнеру IDE, то пути к папке с исходным кодом снимков должны совпадать в контейнере Svacer и на docker-хосте.<br />
<br />
''' Пример конфигурации '''<br />
<br />
<code>svacer.cfg</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
sourcesroot: /data/snapshot-sources<br />
...<br />
</pre><br />
<br />
<code>docker-compose.yaml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /data/snapshot-sources:/data/snapshot-sources # привязка с разрешением на запись<br />
...<br />
</pre><br />
<br />
== Примеры файлов с описанными изменениями ==<br />
<br />
Ниже приведены версии конфигурационных файлов, с изменениями которые были описаны выше. Изменённые строки содежат комментарии.<br />
<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<div style="font-weight:bold;line-height:1.6;"><code>svacer.cfg</code></div><br />
<div class="mw-collapsible-content"><br />
{{Note|type=info|text=Ниже приведён файл <code>svacer.cfg</code> содержащий только секцию <code>xsvacer</code>. Если файл <code>svacer.cfg</code> создан и содержит другие настройки, то приведённые ниже настройки должны быть перенесены в существующий файл}}<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
features:<br />
- webide # активация функциональности webide<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: /data/snapshot-sources # путь к базовой папке с исходным кодом снимков<br />
sarif:<br />
filenametemplate: "warnings.sarif"<br />
commenttemplate: "{{if trim .Text}}`[{{.CreateTs.Local.Format \"02.01.2006 15:04\"}}] {{.CreatedBy}}:`\n\n{{trim .Text}}{{end}}"<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
docker:<br />
hostid: default<br />
containernametemplate: "theia-1-46-{{.StartArgs.SnapshotID}}"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang.10.0.0<br />
sourcetype: file<br />
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT={{hostname}}<br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
hostip: 172.17.0.1 # ip-адрес интерфейса хоста docker0<br />
manager:<br />
type: default<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
{{Note|type=info|text=Проверить актуальные значения аргументов инструкции <code>CMD</code> docker-образа можно с помощью команды <code>docker image inspect {имя образа}</code>}}<br />
</div></div><br />
</div></div><br />
<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<div style="font-weight:bold;line-height:1.6;"><code>docker-compose.yaml</code></div><br />
<div class="mw-collapsible-content"><br />
{{Note|type=info|text=Изменены внесены в файл [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml]}}<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
postgresql:<br />
image: postgres:17.0-bullseye<br />
container_name: svacer-postgres<br />
restart: always<br />
shm_size: 1g<br />
environment:<br />
- POSTGRES_DB=svace<br />
- POSTGRES_USER=svace<br />
- POSTGRES_PASSWORD=svace<br />
- POSTGRES_ROOT_PASSWORD=svace<br />
volumes:<br />
- svacer-postgres:/var/lib/postgresql/data<br />
networks:<br />
svacer:<br />
healthcheck:<br />
test: pg_isready -U svace<br />
interval: 8s<br />
start_period: 16s<br />
timeout: 4s<br />
retries: 4<br />
<br />
svacer:<br />
image: ispras/svacer:10-0-0<br />
container_name: svacer<br />
restart: always<br />
shm_size: 1g<br />
depends_on:<br />
postgresql:<br />
condition: service_healthy<br />
ports:<br />
- "3002:3002"<br />
- "8080:8080"<br />
environment:<br />
- SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace<br />
- STORE=/data/store<br />
volumes:<br />
- svacer-object-store:/data/store<br />
- /var/run/docker.sock:/var/run/docker.sock:ro # доступ к API docker'а из контейнера Svacer<br />
- ./svacer.cfg:/svacer/bin/svacer.cfg:ro # привязка конфигурационного файла svacer.cfg<br />
- /data/snapshot-sources:/data/snapshot-sources # writable привязка коневой папки с исходниками снимков. Пути до и после ":" должны совпадать.<br />
networks:<br />
svacer:<br />
healthcheck:<br />
test: curl --fail http://localhost:8080/api/health || exit 1<br />
interval: 8s<br />
start_period: 16s<br />
timeout: 4s<br />
retries: 4<br />
<br />
volumes:<br />
svacer-postgres:<br />
svacer-object-store:<br />
<br />
networks:<br />
svacer:<br />
</pre><br />
</div></div><br />
<br />
== Схемы компонентов ==<br />
<br />
Ниже приведены концептуальные схемы компонентов, на базе которых основана функциональность запуска IDE. Данные схемы могут быть использованы для поиска других решений приведённых выше задач.<br />
<br />
=== Стандартный запуск Svacer в виде сервиса ===<br />
<br />
[[File:Comp-svacer-webide-default-hosting.png]]<br />
<br />
=== Запуск Svacer внутри docker-контейнера ===<br />
<br />
[[File:Comp-svacer-in-container-webide-hosting.png]]</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&diff=2558Help:XSvacer:Webide:SvacerAsDockerContainer2025-03-11T08:24:08Z<p>M.vinogradov: </p>
<hr />
<div>= Поддержка функциональности [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide webide] когда Svacer развёрнут в docker-контейнере =<br />
<br />
На данный момент функциональность запуска Theia IDE по умолчанию настроена на запуск Svacer с помощью исполняемого файла, "рядом" с docker'ом.<br />
<br />
Для поддержки функциональности <code>webide</code> когда Svacer развёрнут в docker-контейнере необходимо решить следующие задачи:<br />
<br />
# Активация функциональности <code style="white-space: pre;">webide</code> в docker-контейнере Svacer;<br />
# Предоставить docker-контейнеру Svacer доступ к управлению контейнерами IDE;<br />
# Организация сетевого доступа между контейнером Svacer и контейнерами IDE;<br />
# Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE;<br />
<br />
Детали каждой задачи и варианты решения приведены ниже.<br />
<br />
{{Note|type=info|text=Приведённые решения основаны на развёртывании Svacer с помощью файла [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml]}}<br />
<br />
== Активация функциональности <code>webide</code> ==<br />
<br />
Для активации функциональности <code>webide</code> необходимо при запуске Svacer указать флаг <code>--xsvacer.features webide</code><br />
<br />
=== Решение ===<br />
<br />
В [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] используется docker-образ Svacer, собранный на основе [[Dockerfile]]. В данном файле содержится инструкция запуска Svacer<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
CMD /svacer/bin/svacer-server --memsettings=${MEMSETTINGS} run --store $STORE --pg $SVACER_PG_URL<br />
</pre><br />
<br />
Для активации функциональности IDE необходимо переопределить аргументы инструкции <code style="white-space: pre;">CMD</code> в файле <code>docker-compose.yml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
command: /bin/sh -c '/svacer/bin/svacer-server --memsettings=$${MEMSETTINGS} run --store $$STORE --pg $${SVACER_PG_URL} --xsvacer.features webide'<br />
</pre><br />
<br />
{{Note|type=info|text=Проверить актуальные значения аргументов инструкции <code>CMD</code> docker-образа можно с помощью команды <code>docker image inspect {имя образа}</code>}}<br />
<br />
== Предоставление контейнеру Svacer доступа к управлению контейнерами IDE ==<br />
<br />
Функциональность запуска IDE основана на том, что Svacer управляет контейнерами IDE с помощью API docker'а. Поэтому необходимо предоставить доступ к API docker'а из docker-контейнера Svacer.<br />
<br />
=== Решение ===<br />
<br />
Один из способов подключения к API docker'а является использование socket-файла <code>/var/run/docker.sock</code>. Чтобы Svacer получил доступ к этому файлу, его необходимо примонтировать к docker-контейнеру:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /var/run/docker.sock:/var/run/docker.sock:ro<br />
...<br />
</pre><br />
<br />
== Изменение настроек Svacer - <code>svacer.cfg</code> ==<br />
<br />
Дальнейшие шаги связаны с изменением настроек Svacer. В случае, когда Svacer развёрнут в docker-контейнере, это можно сделать следующим образом:<br />
# Создать конфигурационный файл <code>svacer.cfg</code>;<br />
# Примонтировать файл к рабочей директории docker-контейнера Svacer;<br />
# Перезапустить контейнер Svacer;<br />
<br />
Чтобы примонтировать <code>svacer.cfg</code> к контейнеру Svacer нужно в файл <code>docker-compose.yaml</code> добавить строку:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /path/to/svacer.cfg:/svacer/bin/svacer.cfg:ro<br />
...<br />
</pre><br />
<br />
=== Перенос настроек функциональности <code>webide</code> в <code>svacer.cfg</code> ===<br />
<br />
Скопировать секцию с [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.BF.D0.BE_.D1.83.D0.BC.D0.BE.D0.BB.D1.87.D0.B0.D0.BD.D0.B8.D1.8E настройками по умолчанию] в <code>svacer.cfg</code><br />
<br />
== Организация сетевого доступа между контейнером Svacer и контейнерами IDE ==<br />
<br />
В текущей реализации при запуске docker-контейнер IDE публикует внутренний порт web-приложения Theia IDE на случайный порт всех сетевых интерфейсов (0.0.0.0) docker-хоста. Svacer хранит информацию на каком порте хоста развёрнуты соответствующие инстансы IDE и проксирует запросы к ним.<br />
<br />
Необходимо организовать доступ контейнера Svacer к портам docker-хоста, на которых опубликованы контейнеры IDE.<br />
<br />
=== Решение ===<br />
<br />
Чтобы предоставить доступ контейнера Svacer к контейнеру IDE нужно:<br />
# Определить ip-адрес интерфейса docker-хоста <code>docker0</code>;<br />
# Изменить настройку публикации портов контейнеров IDE на значение ip-адреса <code>docker0</code>.<br />
<br />
''' Определение ip-адреса <code>docker0</code>'''<br />
<br />
На docker-хосте выполнить команду <code>ip a</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
$ ip a<br />
...<br />
6: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default<br />
link/ether 82:70:b5:24:50:e4 brd ff:ff:ff:ff:ff:ff<br />
inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0<br />
valid_lft forever preferred_lft forever<br />
</pre><br />
<br />
В данном случае искомый ip-адрес - <code>172.17.0.1</code><br />
<br />
''' Изменение настроек публикации портов контейнеров IDE '''<br />
<br />
Настройки публикации порта контейнера IDE заданы в [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0_Theia_IDE конфигурации запуска IDE]. Настройки по умолчанию должны быть предварительно [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&action=submit#.D0.9F.D0.B5.D1.80.D0.B5.D0.BD.D0.BE.D1.81_.D0.BD.D0.B0.D1.81.D1.82.D1.80.D0.BE.D0.B5.D0.BA_.D1.84.D1.83.D0.BD.D0.BA.D1.86.D0.B8.D0.BE.D0.BD.D0.B0.D0.BB.D1.8C.D0.BD.D0.BE.D1.81.D1.82.D0.B8_webide_.D0.B2_svacer.cfg перенесены в <code>svacer.cfg</code>].<br />
<br />
В файле <code>svacer.cfg</code> нужно добавить параметр <code>hostip</code> со значением ip-адреса интерфейса <code>docker0</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
docker:<br />
...<br />
container:<br />
...<br />
hostconfig:<br />
...<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
hostip: 172.17.0.1 # новый параметр<br />
...<br />
</pre><br />
<br />
<br />
== Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE ==<br />
<br />
При запуске IDE для просмотра снимка, Svacer экспортирует исходный код снимка в папку на docker-хосте. Далее эта папка монтируется к контейнеру IDE, к пути <code>/home/project</code>, который использует Theia IDE в качестве папки проекта.<br />
<br />
При развёртывании Svacer в docker-контейнере необходимо настроить экспорт исходников в папку, которая может быть примонтирована к контейнеру IDE.<br />
<br />
=== Решение ===<br />
<br />
Путь к корневой папке, в которую будут экспортироваться исходники снимков, задаётся в конфигурационном параметре [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.91.D0.B0.D0.B7.D0.BE.D0.B2.D1.8B.D0.B5_.D0.BF.D0.B0.D1.80.D0.B0.D0.BC.D0.B5.D1.82.D1.80.D1.8B_.D0.BA.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D0.B8_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0 <code>sourcesroot</code>]. Так как этот же параметр используется для настройки пути к корневой папке на docker-хосте, которая будет примонтирована к контейнеру IDE, то пути к папке с исходным кодом снимков должны совпадать в контейнере Svacer и на docker-хосте.<br />
<br />
''' Пример конфигурации '''<br />
<br />
<code>svacer.cfg</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
sourcesroot: /data/snapshot-sources<br />
...<br />
</pre><br />
<br />
<code>docker-compose.yaml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /data/snapshot-sources:/data/snapshot-sources<br />
...<br />
</pre><br />
<br />
== Схемы компонентов ==<br />
<br />
Ниже приведены концептуальные схемы компонентов, на базе которых основана функциональность запуска IDE. Данные схемы могут быть использованы для поиска других решений приведённых выше задач.<br />
<br />
=== Стандартный запуск Svacer в виде сервиса ===<br />
<br />
[[File:Comp-svacer-webide-default-hosting.png]]<br />
<br />
=== Запуск Svacer внутри docker-контейнера ===<br />
<br />
[[File:Comp-svacer-in-container-webide-hosting.png]]</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=File:Comp-svacer-in-container-webide-hosting.png&diff=2557File:Comp-svacer-in-container-webide-hosting.png2025-03-11T08:22:06Z<p>M.vinogradov: M.vinogradov uploaded a new version of File:Comp-svacer-in-container-webide-hosting.png</p>
<hr />
<div>Диаграмма развёртывания компонентов функциональности запуска IDE если Svacer запущен в docker-контейнере</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=File:Comp-svacer-webide-default-hosting.png&diff=2556File:Comp-svacer-webide-default-hosting.png2025-03-11T08:21:46Z<p>M.vinogradov: M.vinogradov uploaded a new version of File:Comp-svacer-webide-default-hosting.png</p>
<hr />
<div>Диаграмма стандартного развёртывания компонентов функциональности запуска IDE</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=File:Comp-svacer-in-container-webide-hosting.png&diff=2555File:Comp-svacer-in-container-webide-hosting.png2025-03-11T08:15:30Z<p>M.vinogradov: </p>
<hr />
<div>Диаграмма развёртывания компонентов функциональности запуска IDE если Svacer запущен в docker-контейнере</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=File:Comp-svacer-webide-default-hosting.png&diff=2554File:Comp-svacer-webide-default-hosting.png2025-03-11T08:10:50Z<p>M.vinogradov: </p>
<hr />
<div>Диаграмма стандартного развёртывания компонентов функциональности запуска IDE</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&diff=2553Help:XSvacer:Webide:SvacerAsDockerContainer2025-03-11T07:16:53Z<p>M.vinogradov: </p>
<hr />
<div>= Поддержка функциональности [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide webide] когда Svacer развёрнут в docker-контейнере =<br />
<br />
На данный момент функциональность запуска Theia IDE по умолчанию настроена на запуск Svacer с помощью исполняемого файла, "рядом" с docker'ом.<br />
<br />
Для поддержки функциональности <code>webide</code> когда Svacer развёрнут в docker-контейнере необходимо решить следующие задачи:<br />
<br />
# Активация функциональности <code style="white-space: pre;">webide</code> в docker-контейнере Svacer;<br />
# Предоставить docker-контейнеру Svacer доступ к управлению контейнерами IDE;<br />
# Организация сетевого доступа между контейнером Svacer и контейнерами IDE;<br />
# Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE;<br />
<br />
Детали каждой задачи и варианты решения приведены ниже.<br />
<br />
{{Note|type=info|text=Приведённые решения основаны на развёртывании Svacer с помощью файла [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml]}}<br />
<br />
== Активация функциональности <code>webide</code> ==<br />
<br />
Для активации функциональности <code>webide</code> необходимо при запуске Svacer указать флаг <code>--xsvacer.features webide</code><br />
<br />
=== Решение ===<br />
<br />
В [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] используется docker-образ Svacer, собранный на основе [[Dockerfile]]. В данном файле содержится инструкция запуска Svacer<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
CMD /svacer/bin/svacer-server --memsettings=${MEMSETTINGS} run --store $STORE --pg $SVACER_PG_URL<br />
</pre><br />
<br />
Для активации функциональности IDE необходимо переопределить аргументы инструкции <code style="white-space: pre;">CMD</code> в файле <code>docker-compose.yml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
command: /bin/sh -c '/svacer/bin/svacer-server --memsettings=$${MEMSETTINGS} run --store $$STORE --pg $${SVACER_PG_URL} --xsvacer.features webide'<br />
</pre><br />
<br />
{{Note|type=info|text=Проверить актуальные значения аргументов инструкции <code>CMD</code> docker-образа можно с помощью команды <code>docker image inspect {имя образа}</code>}}<br />
<br />
== Предоставление контейнеру Svacer доступа к управлению контейнерами IDE ==<br />
<br />
Функциональность запуска IDE основана на том, что Svacer управляет контейнерами IDE с помощью API docker'а. Поэтому необходимо предоставить доступ к API docker'а из docker-контейнера Svacer.<br />
<br />
=== Решение ===<br />
<br />
Один из способов подключения к API docker'а является использование socket-файла <code>/var/run/docker.sock</code>. Чтобы Svacer получил доступ к этому файлу, его необходимо примонтировать к docker-контейнеру:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /var/run/docker.sock:/var/run/docker.sock:ro<br />
...<br />
</pre><br />
<br />
== Изменение настроек Svacer - <code>svacer.cfg</code> ==<br />
<br />
Дальнейшие шаги связаны с изменением настроек Svacer. В случае, когда Svacer развёрнут в docker-контейнере, это можно сделать следующим образом:<br />
# Создать конфигурационный файл <code>svacer.cfg</code>;<br />
# Примонтировать файл к рабочей директории docker-контейнера Svacer;<br />
# Перезапустить контейнер Svacer;<br />
<br />
Чтобы примонтировать <code>svacer.cfg</code> к контейнеру Svacer нужно в файл <code>docker-compose.yaml</code> добавить строку:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /path/to/svacer.cfg:/svacer/bin/svacer.cfg:ro<br />
...<br />
</pre><br />
<br />
=== Перенос настроек функциональности <code>webide</code> в <code>svacer.cfg</code> ===<br />
<br />
Скопировать секцию с [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.BF.D0.BE_.D1.83.D0.BC.D0.BE.D0.BB.D1.87.D0.B0.D0.BD.D0.B8.D1.8E настройками по умолчанию] в <code>svacer.cfg</code><br />
<br />
== Организация сетевого доступа между контейнером Svacer и контейнерами IDE ==<br />
<br />
В текущей реализации при запуске docker-контейнер IDE публикует внутренний порт web-приложения Theia IDE на случайный порт всех сетевых интерфейсов (0.0.0.0) docker-хоста. Svacer хранит информацию на каком порте хоста развёрнуты соответствующие инстансы IDE и проксирует запросы к ним.<br />
<br />
Необходимо организовать доступ контейнера Svacer к портам docker-хоста, на которых опубликованы контейнеры IDE.<br />
<br />
=== Решение ===<br />
<br />
Чтобы предоставить доступ контейнера Svacer к контейнеру IDE нужно:<br />
# Определить ip-адрес интерфейса docker-хоста <code>docker0</code>;<br />
# Изменить настройку публикации портов контейнеров IDE на значение ip-адреса <code>docker0</code>.<br />
<br />
''' Определение ip-адреса <code>docker0</code>'''<br />
<br />
На docker-хосте выполнить команду <code>ip a</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
$ ip a<br />
...<br />
6: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default<br />
link/ether 82:70:b5:24:50:e4 brd ff:ff:ff:ff:ff:ff<br />
inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0<br />
valid_lft forever preferred_lft forever<br />
</pre><br />
<br />
В данном случае искомый ip-адрес - <code>172.17.0.1</code><br />
<br />
''' Изменение настроек публикации портов контейнеров IDE '''<br />
<br />
Настройки публикации порта контейнера IDE заданы в [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0_Theia_IDE конфигурации запуска IDE]. Настройки по умолчанию должны быть предварительно [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&action=submit#.D0.9F.D0.B5.D1.80.D0.B5.D0.BD.D0.BE.D1.81_.D0.BD.D0.B0.D1.81.D1.82.D1.80.D0.BE.D0.B5.D0.BA_.D1.84.D1.83.D0.BD.D0.BA.D1.86.D0.B8.D0.BE.D0.BD.D0.B0.D0.BB.D1.8C.D0.BD.D0.BE.D1.81.D1.82.D0.B8_webide_.D0.B2_svacer.cfg перенесены в <code>svacer.cfg</code>].<br />
<br />
В файле <code>svacer.cfg</code> нужно добавить параметр <code>hostip</code> со значением ip-адреса интерфейса <code>docker0</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
docker:<br />
...<br />
container:<br />
...<br />
hostconfig:<br />
...<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
hostip: 172.17.0.1 # новый параметр<br />
...<br />
</pre><br />
<br />
<br />
== Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE ==<br />
<br />
При запуске IDE для просмотра снимка, Svacer экспортирует исходный код снимка в папку на docker-хосте. Далее эта папка монтируется к контейнеру IDE, к пути <code>/home/project</code>, который использует Theia IDE в качестве папки проекта.<br />
<br />
При развёртывании Svacer в docker-контейнере необходимо настроить экспорт исходников в папку, которая может быть примонтирована к контейнеру IDE.<br />
<br />
=== Решение ===<br />
<br />
Путь к корневой папке, в которую будут экспортироваться исходники снимков, задаётся в конфигурационном параметре [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.91.D0.B0.D0.B7.D0.BE.D0.B2.D1.8B.D0.B5_.D0.BF.D0.B0.D1.80.D0.B0.D0.BC.D0.B5.D1.82.D1.80.D1.8B_.D0.BA.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D0.B8_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0 <code>sourcesroot</code>]. Так как этот же параметр используется для настройки пути к корневой папке на docker-хосте, которая будет примонтирована к контейнеру IDE, то пути к папке с исходным кодом снимков должны совпадать в контейнере Svacer и на docker-хосте.<br />
<br />
''' Пример конфигурации '''<br />
<br />
<code>svacer.cfg</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
sourcesroot: /data/snapshot-sources<br />
...<br />
</pre><br />
<br />
<code>docker-compose.yaml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /data/snapshot-sources:/data/snapshot-sources<br />
...<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&diff=2552Help:XSvacer:Webide:SvacerAsDockerContainer2025-03-10T08:06:35Z<p>M.vinogradov: Created page with "= Поддержка функциональности [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide webide] когда Svacer развёрнут в docker-контейнере = На данный момент функциональность запуска Theia IDE по умолчанию настроена на запуск Svacer с помощью исполняемого файла, "рядом" с docker'ом. Для поддержки ф..."</p>
<hr />
<div>= Поддержка функциональности [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide webide] когда Svacer развёрнут в docker-контейнере =<br />
<br />
На данный момент функциональность запуска Theia IDE по умолчанию настроена на запуск Svacer с помощью исполняемого файла, "рядом" с docker'ом.<br />
<br />
Для поддержки функциональности <code>webide</code> когда Svacer развёрнут в docker-контейнере необходимо решить следующие задачи:<br />
<br />
# Активация функциональности <code style="white-space: pre;">webide</code> в docker-контейнере Svacer;<br />
# Предоставить docker-контейнеру Svacer доступ к управлению контейнерами IDE;<br />
# Организация сетевого доступа между контейнером Svacer и контейнерами IDE;<br />
# Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE;<br />
<br />
Детали каждой задачи и варианты решения приведены ниже.<br />
<br />
{{Note|type=info|text=Приведённые решения основаны на развёртывании Svacer с помощью файла [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml]}}<br />
<br />
== Активация функциональности <code>webide</code> ==<br />
<br />
Для активации функциональности <code>webide</code> необходимо при запуске Svacer указать флаг <code>--xsvacer.features webide</code><br />
<br />
=== Решение ===<br />
<br />
В [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml] используется docker-образ Svacer, собранный на основе [[Dockerfile]]. В данном файле содержится инструкция запуска Svacer<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
CMD /svacer/bin/svacer-server --memsettings=${MEMSETTINGS} run --store $STORE --pg $SVACER_PG_URL<br />
</pre><br />
<br />
Для активации функциональности IDE необходимо переопределить аргументы инструкции <code style="white-space: pre;">CMD</code> в файле <code>docker-compose.yml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
command: /bin/sh -c '/svacer/bin/svacer-server --memsettings=$${MEMSETTINGS} run --store $$STORE --pg $${SVACER_PG_URL} --xsvacer.features webide'<br />
</pre><br />
<br />
{{Note|type=info|text=Проверить актуальные значения аргументов инструкции <code>CMD</code> docker-образа можно с помощью команды <code>docker image inspect {имя образа}</code>}}<br />
<br />
== Предоставление контейнеру Svacer доступа к управлению контейнерами IDE ==<br />
<br />
Функциональность запуска IDE основана на том, что Svacer управляет контейнерами IDE с помощью API docker-хоста. Поэтому необходимо предоставить доступ к API docker-хоста из docker-контейнера Svacer.<br />
<br />
=== Решение ===<br />
<br />
Один из способов подключения к API docker-хоста является использование socket-файла <code>/var/run/docker.sock</code>. Чтобы Svacer получил доступ к этому файлу, его необходимо примонтировать к docker-контейнеру:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /var/run/docker.sock:/var/run/docker.sock:ro<br />
...<br />
</pre><br />
<br />
== Изменение настроек Svacer - <code>svacer.cfg</code> ==<br />
<br />
Дальнейшие шаги связаны с изменением настроек Svacer. В случае, когда Svacer развёрнут в docker-контейнере, это можно сделать следующим образом:<br />
# Создать конфигурационный файл <code>svacer.cfg</code>;<br />
# Примонтировать файл к рабочей директории docker-контейнера Svacer;<br />
# Перезапустить контейнер Svacer;<br />
<br />
Чтобы примонтировать <code>svacer.cfg</code> к контейнеру Svacer нужно в файл <code>docker-compose.yaml</code> добавить строку:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /path/to/svacer.cfg:/svacer/bin/svacer.cfg:ro<br />
...<br />
</pre><br />
<br />
=== Перенос настроек функциональности <code>webide</code> в <code>svacer.cfg</code> ===<br />
<br />
Скопировать секцию с [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.BF.D0.BE_.D1.83.D0.BC.D0.BE.D0.BB.D1.87.D0.B0.D0.BD.D0.B8.D1.8E настройками по умолчанию] в <code>svacer.cfg</code><br />
<br />
== Организация сетевого доступа между контейнером Svacer и контейнерами IDE ==<br />
<br />
В текущей реализации при запуске docker-контейнер IDE публикует внутренний порт web-приложения Theia IDE на случайный порт всех сетевых интерфейсов (0.0.0.0) docker-хоста. Svacer хранит информацию на каком порте хоста развёрнуты соответствующие инстансы IDE и проксирует запросы к ним.<br />
<br />
Необходимо организовать доступ контейнера Svacer к портам docker-хоста, на которых опубликованы контейнеры IDE.<br />
<br />
=== Решение ===<br />
<br />
Чтобы предоставить доступ контейнера Svacer к контейнеру IDE нужно:<br />
# Определить ip-адрес интерфейса docker-хоста <code>docker0</code>;<br />
# Изменить настройку публикации портов контейнеров IDE на значение ip-адреса <code>docker0</code>.<br />
<br />
''' Определение ip-адреса <code>docker0</code>'''<br />
<br />
На docker-хосте выполнить команду <code>ip a</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
$ ip a<br />
...<br />
6: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default<br />
link/ether 82:70:b5:24:50:e4 brd ff:ff:ff:ff:ff:ff<br />
inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0<br />
valid_lft forever preferred_lft forever<br />
</pre><br />
<br />
В данном случае искомый ip-адрес - <code>172.17.0.1</code><br />
<br />
''' Изменение настроек публикации портов контейнеров IDE '''<br />
<br />
Настройки публикации порта контейнера IDE заданы в [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.9A.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D1.8F_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0_Theia_IDE конфигурации запуска IDE]. Настройки по умолчанию должны быть предварительно [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide:SvacerAsDockerContainer&action=submit#.D0.9F.D0.B5.D1.80.D0.B5.D0.BD.D0.BE.D1.81_.D0.BD.D0.B0.D1.81.D1.82.D1.80.D0.BE.D0.B5.D0.BA_.D1.84.D1.83.D0.BD.D0.BA.D1.86.D0.B8.D0.BE.D0.BD.D0.B0.D0.BB.D1.8C.D0.BD.D0.BE.D1.81.D1.82.D0.B8_webide_.D0.B2_svacer.cfg перенесены в <code>svacer.cfg</code>].<br />
<br />
В файле <code>svacer.cfg</code> нужно добавить параметр <code>hostip</code> со значением ip-адреса интерфейса <code>docker0</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
docker:<br />
...<br />
container:<br />
...<br />
hostconfig:<br />
...<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
hostip: 172.17.0.1 # новый параметр<br />
...<br />
</pre><br />
<br />
<br />
== Настройка доступа к общему хранилищу с исходными файлами для контейнера Svacer и контейнеров IDE ==<br />
<br />
При запуске IDE для просмотра снимка, Svacer экспортирует исходный код снимка в папку на docker-хосте. Далее эта папка монтируется к контейнеру IDE, к пути <code>/home/project</code>, который использует Theia IDE в качестве папки проекта.<br />
<br />
При развёртывании Svacer в docker-контейнере необходимо настроить экспорт исходников в папку, которая может быть примонтирована к контейнеру IDE.<br />
<br />
=== Решение ===<br />
<br />
Путь к корневой папке, в которую будут экспортироваться исходники снимков, задаётся в конфигурационном параметре [https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide#.D0.91.D0.B0.D0.B7.D0.BE.D0.B2.D1.8B.D0.B5_.D0.BF.D0.B0.D1.80.D0.B0.D0.BC.D0.B5.D1.82.D1.80.D1.8B_.D0.BA.D0.BE.D0.BD.D1.84.D0.B8.D0.B3.D1.83.D1.80.D0.B0.D1.86.D0.B8.D0.B8_.D0.B7.D0.B0.D0.BF.D1.83.D1.81.D0.BA.D0.B0 <code>sourcesroot</code>]. Так как этот же параметр используется для настройки пути к корневой папке на docker-хосте, которая будет примонтирована к контейнеру IDE, то пути к папке с исходным кодом снимков должны совпадать в контейнере Svacer и на docker-хосте.<br />
<br />
''' Пример конфигурации '''<br />
<br />
<code>svacer.cfg</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
...<br />
sourcesroot: /data/snapshot-sources<br />
...<br />
</pre><br />
<br />
<code>docker-compose.yaml</code>:<br />
<br />
<pre style="font: 1em Courier New, monospace;"><br />
services:<br />
...<br />
svacer:<br />
...<br />
volumes:<br />
...<br />
- /data/snapshot-sources:/data/snapshot-sources<br />
...<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=2467Help:XSvacer:Webide2025-01-15T08:29:13Z<p>M.vinogradov: </p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
= Поддержка среды разработки Theia IDE =<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске Svacer.<br />
<br />
При запуске функциональности Webide также будет запущена функциональность [[Help:XSvacer:Docker|docker]].<br />
<br />
При активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов<br />
* в пользовательском интерфейсе на вкладке "Информация о снимке" появляется кнопка "Открыть в IDE"<br />
* устанавливается подключение к хосту docker, на котором будут запускаться контейнеры с экземплярами IDE<br />
<br />
=== Быстрый запуск функциональности с настройками по умолчанию ===<br />
<br />
Для того, чтобы начать пользоваться функциональностью запуска IDE без изменения конфигурационных параметров, нужно выполнить следующие действия:<br />
# Настройка доступа к docker-хосту:<br />
## Запустить docker со настройками по умолчанию (dockerd должен слушать unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option)<br />
## Проверить, что у пользователя под которым будет запускаться Svacer есть доступ к unix-сокету docker-хоста <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/engine/install/linux-postinstall<br />
# Настроить права доступа у пользователей, которые смогут запускать IDE: требуются разрешения на проект/ветку "Просмотр маркеров" и "Экспорт разметки"<br />
# Перезапустить Svacer с флагом <code style="white-space: pre;">--xsvacer.features webide</code><br />
# ''Опционально.'' Для ускорения первого запуска IDE:<br />
## Скачать архив с docker-образом для соответствующей версии Svacer: [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+]<br />
## Загрузить docker-образ из архива на docker-хост: <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint...</code><br />
<br />
После этого у пользователей с указанными правами должна появиться кнопка "Открыть в IDE" на панели с информацией о снимке.<br />
<br />
{{Note}} IDE с исходным кодом снимков будут запускаться в новых вкладках браузера. Обычно все браузеры блокируют автоматическое открытие вкладки и показывают соответствующее предупреждение.<br />
<br />
Например, в Firefox:<br />
<br />
[[File:Firefox popup notification ru.png]]<br />
<br />
В таком случае нужно дать разрешение на открытие вкладки с IDE:<br />
<br />
[[File:Firefox popup notification expanded ru.png|x150px]]<br />
<br />
<br />
При необходимости изменения настроек подключения к docker-хосту:<br />
# Скопировать [[Help:XSvacer:Docker#Конфигурация_по_умолчанию|конфигурацию docker по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/docker</code><br />
<br />
При необходимости изменения настроек запуска IDE:<br />
# Скопировать [[#Конфигурация_по_умолчанию|конфигурацию webide по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/webide</code><br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске Svacer указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В [[Help:XSvacer:Webide#Конфигурация|конфигурации]] функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE<br />
# У пользователя Svacer имеются разрешения "Просмотр маркеров" и "Экспорт разметки" на проект, в котором находится снимок, для которого нужно запустить IDE<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка "Открыть в IDE".<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code><br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается<br />
#** Если IDE недоступна: продолжается процесс запуска. IDE будет перезапущена<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code>xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code><br />
# Исходный код снимка скачивается в "корневую папку снимка"<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sarif/filenametemplate</code><br />
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>. Если docker-образ отсутствует, он будет загружен на хост<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code>running</code> — процесс запуска IDE продолжается<br />
##** в статусе <code>created</code>, <code>exited</code> или <code>paused</code> — контейнер будет запущен<br />
##** в других статусах — вернётся соответствующая ошибка и процесс запуска IDE прервётся<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code><br />
#* Если за отведённое время ответ от IDE получен — процесс запуска завершается<br />
#* Если ответ не получен — вернётся ошибка <code>ide not ready</code><br />
<br />
При возникновении ошибки на одном из этапов запуска IDE артефакты, созданные на предыдущих этапах, останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
{{Note|type=reminder|text=Причиной возникновения ошибки "ide not ready" может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>. В этом случае рекомендуется попробовать повторно запустить IDE через короткий промежуток времени}}<br />
<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется проверить:<br />
# Сетевую доступность docker-хоста<br />
# Настройки фаервола на docker-хосте<br />
# Настройки биндинга docker-контейнера c IDE<br />
::<code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code><br />
::Контейнер должен быть подключён к доступному сетевому интерфейсу<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с префиксом <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code><br />
<br />
Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
:<code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>POST http://docker-host:35353/socket.io/?...</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
Для запуска IDE в окне браузера нужно указать адрес<br />
<br />
:<code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code><br />
<br />
{{Note}} Завершающий слеш обязателен!<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы Svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода<br />
DELETE /api/snapshots/{snapshot_id}/ide<br />
с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>. В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
По умолчанию установлен параметр конфигурации<br />
<br />
xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true<br />
<br />
Это означает, что после остановки docker-контейнер будет автоматически удалён.<br />
<br />
Чтобы изменить это поведение, настройка<br />
xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove<br />
<br />
должна быть установлена в <code>false</code> на момент запуска docker-контейнера IDE. Это можно сделать, например, установив значение переменной окружения<br />
<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false<br />
<br />
{{Note|type=error|text=При использовании версии Svacer 9.0.0 установка <code>autoremove: false</code> вызывает ошибку запуска. Исправлено в версии [[Svacer#Релизы|9.0.1]].'''}}<br />
<br />
При корректной остановке (например SIGTERM) Svacer автоматически остановит все запущенные docker-контейнеры IDE.<br />
<br />
=== Подключение к IDE после некорректного завершения Svacer ===<br />
<br />
При запуске Svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах. При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке Svacer все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!}}<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> — идентификатор IDE<br />
:<code style="white-space: pre;">name</code> — название IDE<br />
:<code style="white-space: pre;">order</code> — порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка.<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> — действие<br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Доступные действия:'''<br />
* <code style="white-space: pre;">update_markup</code> — обновление предупреждений и разметки (sarif-файла)<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например, для default-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code><br />
<br />
Раздел конфигурации для управления функциональностью — <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому необходимо также [[Help:XSvacer:Docker|настроить доступ к docker-хосту]] в разделе <code style="white-space: pre;">xsvacer/docker</code>, иначе функциональность WebIDE не сможет работать корректно.<br />
<br />
В случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]].<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!}}<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации default)<br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0<br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0)<br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на машине со Svacer<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources<br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на хосте docker. Нужен при использовании удалённого docker-хоста, т. к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
|<br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker. По умолчанию <code style="white-space: pre;">"/"</code><br />
|<br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|{{Note|text=В версии 10.0.0 заменён на [[Help:XSvacer:Webide#Параметры_экспорта_sarif-файла_с_разметкой_предупреждений|sarif]]}}<br />
Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"</nowiki><br />
|}<br />
<br />
==== Параметры экспорта sarif-файла с разметкой предупреждений ====<br />
<br />
Данные параметры используются для настройки экспорта sarif-файлов с разметкой предупреждений, выполненной в Svacer'е.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|sarif<br />
|map<br />
|Настройки экспорта sarif-файла<br />
|<br />
|-<br />
|sarif/filenametemplate<br />
|golang template string<br />
|Шаблон для формирования названия sarif-файла. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"warnings.sarif"</nowiki><br />
|-<br />
|sarif/commenttemplate<br />
|golang template string<br />
|Шаблон для формирования элемента списка комментариев предупреждения при экспорте в sarif-файл. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|Comment]]<br />
|<nowiki>"{{if trim .Text}}`[{{.CreateTs.Local.Format \"02.01.2006 15:04\"}}] {{.CreatedBy}}:`\n\n{{trim .Text}}{{end}}"</nowiki><br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только стандартный менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
|<br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default<br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
|<br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default<br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|<nowiki>"theia-1-46-{{.StartArgs.SnapshotID}}"</nowiki><br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список меток docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer<br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
|<br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint<br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|Svacer 10+: 1.46.0.sarif.clang.10.0.0<br />
Svacer 9+: 1.46.0.sarif.clang<br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост<br />
* repository — будет вызван docker pull образа <code>{image/name}:{image/tag}</code><br />
* file — будет вызван docker load с URL <code>image/sourcefileurl</code><br />
|file<br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|URL откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
URL может содержать:<br />
* путь к локальному файлу: схема <code>file://</code><br />
* http/https-адрес: схема <code>http://</code> или <code>https://</code><br />
|Svacer 10+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz<br />
Svacer 9+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
|<br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70<br />
|<br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379<br />
|<br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true<br />
|-<br />
|docker/container/hostconfig/portbindings<br />
|map<br />
|<br />
|<br />
"3000/tcp":<br />
:- hostport: 0<br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104<br />
|<br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию<br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
|<br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10<br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms<br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
Comment {<br />
ID string<br />
Text string<br />
Ref string<br />
CreatedBy string<br />
CreatedByID string<br />
CreateTs time.Time<br />
UpdateTs *time.Time<br />
UpdatedBy string<br />
UpdatedByID string<br />
}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sarif:<br />
filenametemplate: "warnings.sarif"<br />
commenttemplate: "{{if trim .Text}}`[{{.CreateTs.Local.Format \"02.01.2006 15:04\"}}] {{.CreatedBy}}:`\n\n{{trim .Text}}{{end}}"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang.10.0.0<br />
sourcetype: file<br />
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
По умолчанию используется 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/).<br />
<br />
{{Note|text=При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы}}<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения<br />
<br />
XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code><br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске Svacer:<br />
<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в корневые папки, заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code><br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code><br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code><br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code><br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code><br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code><br />
#*: метки с названиями <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><br />
# При использовании rootless-хоста docker будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста|настройкам]]<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр<br />
<br />
xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl<br />
<br />
Содержит значение<br />
<br />
Svacer 10+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.10.0.0.tar.gz<br />
Svacer 9+: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
<br />
По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т. к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго.<br />
<br />
Для ускорения первого запуска IDE докер образ можно загрузить на хост docker вручную. Для этого необходимо:<br />
<br />
# Скачать файл архива<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint...</code><br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0 1.46.0].<br />
<br />
При этом была изменена компоновка расширений Theia. Результат выполнения <code>git diff</code>:<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "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"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа:<br />
docker build -t theia-blueprint:1.46.0.sarif.clang... -f browser.Dockerfile .<br />
<br />
Команда экспорта docker-образа:<br />
docker image save theia-blueprint:1.46.0.sarif.clang... | gzip > /path/to/tar/theia-blueprint.1.46.0.sarif.clang....tar.gz<br />
<br />
== Известные проблемы ==<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.<br />
<br />
В 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.<br />
<br />
Поэтому для решения данной проблемы Svacer должен открываться по HTTPS или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=2463Help:XSvacer:Webide2025-01-14T07:51:11Z<p>M.vinogradov: </p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
= Поддержка среды разработки Theia IDE =<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске Svacer.<br />
<br />
При запуске функциональности Webide также будет запущена функциональность [[Help:XSvacer:Docker|docker]].<br />
<br />
При активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов<br />
* в пользовательском интерфейсе на вкладке "Информация о снимке" появляется кнопка "Открыть в IDE"<br />
* устанавливается подключение к хосту docker, на котором будут запускаться контейнеры с экземплярами IDE<br />
<br />
=== Быстрый запуск функциональности с настройками по умолчанию ===<br />
<br />
Для того, чтобы начать пользоваться функциональностью запуска IDE без изменения конфигурационных параметров, нужно выполнить следующие действия:<br />
# Настройка доступа к docker-хосту:<br />
## Запустить docker со настройками по умолчанию (dockerd должен слушать unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option)<br />
## Проверить, что у пользователя под которым будет запускаться Svacer есть доступ к unix-сокету docker-хоста <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/engine/install/linux-postinstall<br />
# Настроить права доступа у пользователей, которые смогут запускать IDE: требуются разрешения на проект/ветку "Просмотр маркеров" и "Экспорт разметки"<br />
# Перезапустить Svacer с флагом <code style="white-space: pre;">--xsvacer.features webide</code><br />
# ''Опционально.'' Для ускорения первого запуска IDE:<br />
## Скачать [https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar архив с docker-образом]<br />
## Загрузить docker-образ из архива на docker-хост: <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code><br />
<br />
После этого у пользователей с указанными правами должна появиться кнопка "Открыть в IDE" на панели с информацией о снимке.<br />
<br />
{{Note}} IDE с исходным кодом снимков будут запускаться в новых вкладках браузера. Обычно все браузеры блокируют автоматическое открытие вкладки и показывают соответствующее предупреждение. <br />
<br />
Например, в Firefox:<br />
<br />
[[File:Firefox popup notification ru.png]]<br />
<br />
В таком случае нужно дать разрешение на открытие вкладки с IDE:<br />
<br />
[[File:Firefox popup notification expanded ru.png|x150px]]<br />
<br />
<br />
При необходимости изменения настроек подключения к docker-хосту:<br />
# Скопировать [[Help:XSvacer:Docker#Конфигурация_по_умолчанию|конфигурацию docker по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/docker</code><br />
<br />
При необходимости изменения настроек запуска IDE:<br />
# Скопировать [[#Конфигурация_по_умолчанию|конфигурацию webide по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/webide</code><br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске Svacer указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В [[Help:XSvacer:Webide#Конфигурация|конфигурации]] функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE<br />
# У пользователя Svacer имеются разрешения "Просмотр маркеров" и "Экспорт разметки" на проект, в котором находится снимок, для которого нужно запустить IDE<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка "Открыть в IDE".<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code><br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается<br />
#** Если IDE недоступна: продолжается процесс запуска. IDE будет перезапущена<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code>xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code><br />
# Исходный код снимка скачивается в "корневую папку снимка"<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sarif/filenametemplate</code><br />
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>. Если docker-образ отсутствует, он будет загружен на хост<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code>running</code> — процесс запуска IDE продолжается<br />
##** в статусе <code>created</code>, <code>exited</code> или <code>paused</code> — контейнер будет запущен<br />
##** в других статусах — вернётся соответствующая ошибка и процесс запуска IDE прервётся<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code><br />
#* Если за отведённое время ответ от IDE получен — процесс запуска завершается<br />
#* Если ответ не получен — вернётся ошибка <code>ide not ready</code><br />
<br />
При возникновении ошибки на одном из этапов запуска IDE артефакты, созданные на предыдущих этапах, останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
{{Note|type=reminder|text=Причиной возникновения ошибки "ide not ready" может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>. В этом случае рекомендуется попробовать повторно запустить IDE через короткий промежуток времени}}<br />
<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется проверить:<br />
# Сетевую доступность docker-хоста<br />
# Настройки фаервола на docker-хосте<br />
# Настройки биндинга docker-контейнера c IDE<br />
::<code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code> <br />
::Контейнер должен быть подключён к доступному сетевому интерфейсу<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с префиксом <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code><br />
<br />
Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
:<code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>POST http://docker-host:35353/socket.io/?...</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
Для запуска IDE в окне браузера нужно указать адрес<br />
<br />
:<code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code><br />
<br />
{{Note}} Завершающий слеш обязателен!<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы Svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода<br />
DELETE /api/snapshots/{snapshot_id}/ide<br />
с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>. В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
По умолчанию установлен параметр конфигурации <br />
<br />
xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true<br />
<br />
Это означает, что после остановки docker-контейнер будет автоматически удалён.<br />
<br />
Чтобы изменить это поведение, настройка <br />
xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove<br />
<br />
должна быть установлена в <code>false</code> на момент запуска docker-контейнера IDE. Это можно сделать, например, установив значение переменной окружения <br />
<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false<br />
<br />
{{Note|type=error|text=При использовании версии Svacer 9.0.0 установка <code>autoremove: false</code> вызывает ошибку запуска. Исправлено в версии [[Svacer#Релизы|9.0.1]].'''}}<br />
<br />
При корректной остановке (например SIGTERM) Svacer автоматически остановит все запущенные docker-контейнеры IDE.<br />
<br />
=== Подключение к IDE после некорректного завершения Svacer ===<br />
<br />
При запуске Svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах. При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке Svacer все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!}}<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание <br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> — идентификатор IDE<br />
:<code style="white-space: pre;">name</code> — название IDE<br />
:<code style="white-space: pre;">order</code> — порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка. <br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> — действие<br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Доступные действия:'''<br />
* <code style="white-space: pre;">update_markup</code> — обновление предупреждений и разметки (sarif-файла)<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например, для default-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code><br />
<br />
Раздел конфигурации для управления функциональностью — <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому необходимо также [[Help:XSvacer:Docker|настроить доступ к docker-хосту]] в разделе <code style="white-space: pre;">xsvacer/docker</code>, иначе функциональность WebIDE не сможет работать корректно.<br />
<br />
В случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]].<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!}}<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации default) <br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0 <br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0) <br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на машине со Svacer<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources <br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на хосте docker. Нужен при использовании удалённого docker-хоста, т. к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
| <br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker. По умолчанию <code style="white-space: pre;">"/"</code><br />
| <br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|{{Note|text=В версии 10.0.0 заменён на [[Help:XSvacer:Webide#Параметры_экспорта_sarif-файла_с_разметкой_предупреждений|sarif]]}}<br />
Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"</nowiki><br />
|}<br />
<br />
==== Параметры экспорта sarif-файла с разметкой предупреждений ====<br />
<br />
Данные параметры используются для настройки экспорта sarif-файлов с разметкой предупреждений, выполненной в Svacer'е.<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|sarif<br />
|map<br />
|Настройки экспорта sarif-файла<br />
| <br />
|-<br />
|sarif/filenametemplate<br />
|golang template string<br />
|Шаблон для формирования названия sarif-файла. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"warnings.sarif"</nowiki><br />
|-<br />
|sarif/commenttemplate<br />
|golang template string<br />
|Шаблон для формирования элемента списка комментариев предупреждения при экспорте в sarif-файл. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|Comment]]<br />
|<nowiki>"{{if trim .Text}}`[{{.CreateTs.Local.Format \"02.01.2006 15:04\"}}] {{.CreatedBy}}:`\n\n{{trim .Text}}{{end}}"</nowiki><br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только стандартный менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
| <br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default <br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
| <br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default <br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|<nowiki>"theia-1-46-{{.StartArgs.SnapshotID}}"</nowiki><br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список меток docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer <br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
| <br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint <br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|1.46.0.sarif.clang <br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост<br />
* repository — будет вызван docker pull образа <code>{image/name}:{image/tag}</code><br />
* file — будет вызван docker load с URL <code>image/sourcefileurl</code><br />
|file <br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|URL откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
URL может содержать:<br />
* путь к локальному файлу: схема <code>file://</code><br />
* http/https-адрес: схема <code>http://</code> или <code>https://</code><br />
|https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
| <br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70<br />
| <br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki> <br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379<br />
| <br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true <br />
|-<br />
|docker/container/hostconfig/portbindings<br />
|map<br />
|<br />
|<br />
"3000/tcp": <br />
:- hostport: 0 <br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104<br />
| <br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
| <br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10 <br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms <br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
Comment {<br />
ID string<br />
Text string<br />
Ref string<br />
CreatedBy string<br />
CreatedByID string<br />
CreateTs time.Time<br />
UpdateTs *time.Time<br />
UpdatedBy string<br />
UpdatedByID string<br />
}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sarif:<br />
filenametemplate: "warnings.sarif"<br />
commenttemplate: "{{if trim .Text}}`[{{.CreateTs.Local.Format \"02.01.2006 15:04\"}}] {{.CreatedBy}}:`\n\n{{trim .Text}}{{end}}"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang<br />
sourcetype: file<br />
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
По умолчанию используется 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/).<br />
<br />
{{Note|text=При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы}}<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения<br />
<br />
XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code><br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске Svacer:<br />
<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в корневые папки, заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code><br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code><br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code><br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code><br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code><br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code><br />
#*: метки с названиями <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><br />
# При использовании rootless-хоста docker будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста|настройкам]]<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр <br />
<br />
xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl<br />
<br />
Содержит значение <br />
<br />
https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
<br />
По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т. к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго. <br />
<br />
Для ускорения первого запуска IDE докер образ можно загрузить на хост docker вручную. Для этого необходимо:<br />
<br />
# Скачать файл архива<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code><br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0 1.46.0].<br />
<br />
При этом была изменена компоновка расширений Theia. Результат выполнения <code>git diff</code>:<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "ms-sarifvscode.sarif-viewer": "https://open-vsx.org/api/MS-SarifVSCode/sarif-viewer/3.4.2/file/MS-SarifVSCode.sarif-viewer-3.4.2.vsix"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа: <br />
docker build -t theia-blueprint:1.46.0.sarif.clang -f browser.Dockerfile .<br />
<br />
Команда экспорта docker-образа:<br />
docker image save theia-blueprint:1.46.0 > /path/to/tar/theia-blueprint.1.46.0.docker.command.tar<br />
<br />
== Известные проблемы ==<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.<br />
<br />
В 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.<br />
<br />
Поэтому для решения данной проблемы Svacer должен открываться по HTTPS или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:Public_API/management/containers&diff=2090Help:Public API/management/containers2024-10-16T10:05:41Z<p>M.vinogradov: /* = Примеры запросов управления составом групп */</p>
<hr />
<div>= Управление контейнерами (проектами, ветками, группами проектов) =<br />
<br />
В данном разделе содержится описание REST API управления контейнерами и их содержимым.<br />
<br />
Для выполнения операций получения списка контейнеров, их создания, изменения и удаления существует http-ресурс<br />
<br />
<pre style="white-space: pre;"><br />
POST /api/public/admin/server/containers<br />
</pre><br />
<br />
Для операций управления составом групп проектов существует http-ресурс <br />
<br />
<pre style="white-space: pre;"><br />
POST /api/public/admin/server/project-groups<br />
</pre><br />
<br />
Для операции переименования снимков существует http-ресурс<br />
<br />
<pre><br />
PUT /api/public/snapshots/{snapshot_id}/update<br />
</pre><br />
<br />
{{Note|type=warn|text=Для использования ресурсов необходимо использовать http-запросы с токеном пользователя имеющего соответствующие права}}<br />
<br />
== <code>POST /api/public/admin/server/containers</code> - управление набором проектов, веток, групп проектов ==<br />
<br />
Формат запроса:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"id": "string",<br />
"type": "string",<br />
"name": "string",<br />
"parent": "string",<br />
"review_with_comment": true<br />
}<br />
</pre><br />
<br />
Формат ответа:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"Containers": [<br />
{<br />
"action": "string",<br />
"id": "string",<br />
"name": "string",<br />
"parent": "string",<br />
"review_with_comment": true,<br />
"type": "string"<br />
}<br />
]<br />
}<br />
</pre><br />
<br />
Назначение полей запроса и установка значений полей ответа зависит от типа операции и определяется значением поля запроса <code>action</code>.<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Поддерживаемыe значения поля <code>action</code><br />
|-<br />
!Значение<br />
!Тип операции<br />
|-<br />
|<code>list</code><br />
|Получение списка контейнеров<br />
|-<br />
|<code>add</code><br />
|Создание контейнера<br />
|-<br />
|<code>update</code><br />
|Изменение контейнера<br />
|-<br />
|<code>remove</code><br />
|Удаление контейнера<br />
|}<br />
<br />
=== Получение списка контейнеров: "action": "list" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>list</code><br />
|-<br />
|<code>id</code><br />
|Если не пустое: идентификатор контейнера, для которого будут загружены "связанные" контейнеры:<br />
:- если передан id группы проектов - вернётся список проектов входящих в данную группу<br />
:- если передан id проекта - вернётся список групп проектов, в который входит проект + список его веток<br />
:- если передан id ветки - вернётся список снимков данной ветки<br />
|-<br />
|<code>type</code><br />
|Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
<br />
Если не пустое: отфильтровывает список контейнеров по типу<br />
<br />
Если пустое:<br />
:- если поле <code>id</code> пустое - возвращается объединённый список проектов и групп проектов<br />
|-<br />
|<code>name</code><br />
|Если не пустое:<br />
:- если поле <code>id</code> пустое - отфильтровывает список контейнеров по названию<br />
:- если поле <code>id</code> НЕ пустое - фильтр по названию НЕ применяется<br />
|-<br />
|<code>parent</code><br />
|Не используется<br />
|-<br />
|<code>review_with_comment</code><br />
|Не используется<br />
|}<br />
<br />
==== Примеры запросов с <code>"action": "list"</code> ====<br />
<pre><br />
$ curl --data '{"action": "list"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"20706313-6986-4c9d-9a4e-5e4908a11499","name":"projectGroupB","type":"project-group"},{"id":"a7e22042-96e5-4659-b21a-0615d434bed7","name":"bash","type":"project"},{"id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","name":"iptables","type":"project"},{"id":"d53b0b92-d0fb-429a-8f86-c8fe6ee50c0c","name":"proftpd","type":"project"}]}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "list", "type": "project-group"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"20706313-6986-4c9d-9a4e-5e4908a11499","name":"projectGroupB","type":"project-group"}]}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "list", "name": "bas"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"a7e22042-96e5-4659-b21a-0615d434bed7","name":"bash","type":"project"}]}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "list", "id":"a7e22042-96e5-4659-b21a-0615d434bed7"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"ef9210db-180b-4351-8a2f-7e8ceaa42ec6","name":"master","type":"branch","parent":"a7e22042-96e5-4659-b21a-0615d434bed7"}]}<br />
</pre><br />
<br />
=== Создание контейнера: "action": "add" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>add</code><br />
|-<br />
|<code>id</code><br />
|Не используется<br />
|-<br />
|<code>type</code><br />
|Тип нового контейнера. Обязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
|-<br />
|<code>name</code><br />
|Название нового контейнера. Обязательное<br />
|-<br />
|<code>parent</code><br />
|Название или идентификатор проекта, в котором будет создана новая ветка<br />
Если тип нового контейнера НЕ <code>branch</code>: не используется<br />
|-<br />
|<code>review_with_comment</code><br />
|Значение настройки проекта "Обязательный комментарий при разметке"<br />
Если тип нового контейнера НЕ <code>project</code>: не используется<br />
|}<br />
<br />
=== Изменение контейнера: "action": "update" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>update</code><br />
|-<br />
|<code>id</code><br />
|Идентификатор изменяемого контейнера. Обязательное<br />
|-<br />
|<code>type</code><br />
|Тип изменяемого контейнера. Используется для поиска контейнера вместе с id. Изменить тип контейнера нельзя. Необязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
|-<br />
|<code>name</code><br />
|Новое название контейнера. Обязательное<br />
|-<br />
|<code>parent</code><br />
|Не используется. Изменить проект в котором создана ветка нельзя<br />
|-<br />
|<code>review_with_comment</code><br />
|Новое значение настройки проекта "Обязательный комментарий при разметке"<br />
|}<br />
<br />
=== Удаление контейнера: "action": "remove" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>remove</code><br />
|-<br />
|<code>id</code><br />
|Идентификатор удаляемого контейнера. Обязательное<br />
|-<br />
|<code>type</code><br />
|Тип удаляемого контейнера. Используется для поиска контейнера вместе с id. Необязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
|-<br />
|<code>name</code><br />
|Не используется<br />
|-<br />
|<code>parent</code><br />
|Не используется<br />
|-<br />
|<code>review_with_comment</code><br />
|Не используется<br />
|}<br />
<br />
== <code>POST /api/public/admin/server/project-groups</code> - управление составом групп проектов ==<br />
<br />
Формат запроса:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"project_group_name_or_id": "string",<br />
"project_name_or_id": "string"<br />
}<br />
</pre><br />
<br />
Формат ответа:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"project_group_id": "string",<br />
"project_group_name": "string",<br />
"project_id": "string",<br />
"project_name": "string"<br />
}<br />
</pre><br />
<br />
Назначение полей запроса и ответа зависит от типа операции и определяется значением поля <code>action</code>.<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Поддерживаемыe значения поля <code>action</code><br />
|-<br />
!Значение<br />
!Тип операции<br />
|-<br />
|<code>get</code><br />
|Получение экземпляра группы проектов<br />
|-<br />
|<code>add-project-to-group</code><br />
|Добавление проекта в группу проектов<br />
|-<br />
|<code>remove-project-from-group</code><br />
|Исключение проекта из группы проектов<br />
|}<br />
<br />
=== Получение экземпляра группы проектов: "action": "get" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>get</code><br />
|-<br />
|<code>project_group_name_or_id</code><br />
|Название или идентификатор запрашиваемой группы проектов. {{Note|text= Поддержка названия добавлена ПОСЛЕ версии 9.0.2}}<br />
|-<br />
|<code>project_name_or_id</code><br />
|Не используется<br />
|}<br />
<br />
=== Добавление проекта в группу проектов: "action": "add-project-to-group" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>add-project-to-group</code><br />
|-<br />
|<code>project_group_name_or_id</code><br />
|Название или идентификатор изменяемой группы проектов<br />
|-<br />
|<code>project_name_or_id</code><br />
|Название или идентификатор добавляемого проекта<br />
|}<br />
<br />
=== Исключение проекта из группы проектов: "action": "remove-project-from-group" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>remove-project-from-group</code><br />
|-<br />
|<code>project_group_name_or_id</code><br />
|Название или идентификатор изменяемой группы проектов<br />
|-<br />
|<code>project_name_or_id</code><br />
|Название или идентификатор исключаемого проекта<br />
|}<br />
<br />
==== Примеры запросов управления составом групп ====<br />
<pre><br />
$ curl --data '{"action": "get", "project_group_name_or_id": "0f7da122-9c86-4384-b7bc-356bfb3b7f28"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"get","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA"}<br />
<br />
$ curl --data '{"action": "get", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"get","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA"}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "add-project-to-group", "project_name_or_id": "iptables", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"add-project-to-group","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA","project_id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","project_name":"iptables"}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "remove-project-from-group", "project_name_or_id": "iptables", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"remove-project-from-group","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA","project_id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","project_name":"iptables"}<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:Public_API/management/containers&diff=2089Help:Public API/management/containers2024-10-16T09:28:03Z<p>M.vinogradov: </p>
<hr />
<div>= Управление контейнерами (проектами, ветками, группами проектов) =<br />
<br />
В данном разделе содержится описание REST API управления контейнерами и их содержимым.<br />
<br />
Для выполнения операций получения списка контейнеров, их создания, изменения и удаления существует http-ресурс<br />
<br />
<pre style="white-space: pre;"><br />
POST /api/public/admin/server/containers<br />
</pre><br />
<br />
Для операций управления составом групп проектов существует http-ресурс <br />
<br />
<pre style="white-space: pre;"><br />
POST /api/public/admin/server/project-groups<br />
</pre><br />
<br />
Для операции переименования снимков существует http-ресурс<br />
<br />
<pre><br />
PUT /api/public/snapshots/{snapshot_id}/update<br />
</pre><br />
<br />
{{Note|type=warn|text=Для использования ресурсов необходимо использовать http-запросы с токеном пользователя имеющего соответствующие права}}<br />
<br />
== <code>POST /api/public/admin/server/containers</code> - управление набором проектов, веток, групп проектов ==<br />
<br />
Формат запроса:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"id": "string",<br />
"type": "string",<br />
"name": "string",<br />
"parent": "string",<br />
"review_with_comment": true<br />
}<br />
</pre><br />
<br />
Формат ответа:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"Containers": [<br />
{<br />
"action": "string",<br />
"id": "string",<br />
"name": "string",<br />
"parent": "string",<br />
"review_with_comment": true,<br />
"type": "string"<br />
}<br />
]<br />
}<br />
</pre><br />
<br />
Назначение полей запроса и установка значений полей ответа зависит от типа операции и определяется значением поля запроса <code>action</code>.<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Поддерживаемыe значения поля <code>action</code><br />
|-<br />
!Значение<br />
!Тип операции<br />
|-<br />
|<code>list</code><br />
|Получение списка контейнеров<br />
|-<br />
|<code>add</code><br />
|Создание контейнера<br />
|-<br />
|<code>update</code><br />
|Изменение контейнера<br />
|-<br />
|<code>remove</code><br />
|Удаление контейнера<br />
|}<br />
<br />
=== Получение списка контейнеров: "action": "list" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>list</code><br />
|-<br />
|<code>id</code><br />
|Если не пустое: идентификатор контейнера, для которого будут загружены "связанные" контейнеры:<br />
:- если передан id группы проектов - вернётся список проектов входящих в данную группу<br />
:- если передан id проекта - вернётся список групп проектов, в который входит проект + список его веток<br />
:- если передан id ветки - вернётся список снимков данной ветки<br />
|-<br />
|<code>type</code><br />
|Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
<br />
Если не пустое: отфильтровывает список контейнеров по типу<br />
<br />
Если пустое:<br />
:- если поле <code>id</code> пустое - возвращается объединённый список проектов и групп проектов<br />
|-<br />
|<code>name</code><br />
|Если не пустое:<br />
:- если поле <code>id</code> пустое - отфильтровывает список контейнеров по названию<br />
:- если поле <code>id</code> НЕ пустое - фильтр по названию НЕ применяется<br />
|-<br />
|<code>parent</code><br />
|Не используется<br />
|-<br />
|<code>review_with_comment</code><br />
|Не используется<br />
|}<br />
<br />
==== Примеры запросов с <code>"action": "list"</code> ====<br />
<pre><br />
$ curl --data '{"action": "list"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"20706313-6986-4c9d-9a4e-5e4908a11499","name":"projectGroupB","type":"project-group"},{"id":"a7e22042-96e5-4659-b21a-0615d434bed7","name":"bash","type":"project"},{"id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","name":"iptables","type":"project"},{"id":"d53b0b92-d0fb-429a-8f86-c8fe6ee50c0c","name":"proftpd","type":"project"}]}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "list", "type": "project-group"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"20706313-6986-4c9d-9a4e-5e4908a11499","name":"projectGroupB","type":"project-group"}]}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "list", "name": "bas"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"a7e22042-96e5-4659-b21a-0615d434bed7","name":"bash","type":"project"}]}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "list", "id":"a7e22042-96e5-4659-b21a-0615d434bed7"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"ef9210db-180b-4351-8a2f-7e8ceaa42ec6","name":"master","type":"branch","parent":"a7e22042-96e5-4659-b21a-0615d434bed7"}]}<br />
</pre><br />
<br />
=== Создание контейнера: "action": "add" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>add</code><br />
|-<br />
|<code>id</code><br />
|Не используется<br />
|-<br />
|<code>type</code><br />
|Тип нового контейнера. Обязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
|-<br />
|<code>name</code><br />
|Название нового контейнера. Обязательное<br />
|-<br />
|<code>parent</code><br />
|Название или идентификатор проекта, в котором будет создана новая ветка<br />
Если тип нового контейнера НЕ <code>branch</code>: не используется<br />
|-<br />
|<code>review_with_comment</code><br />
|Значение настройки проекта "Обязательный комментарий при разметке"<br />
Если тип нового контейнера НЕ <code>project</code>: не используется<br />
|}<br />
<br />
=== Изменение контейнера: "action": "update" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>update</code><br />
|-<br />
|<code>id</code><br />
|Идентификатор изменяемого контейнера. Обязательное<br />
|-<br />
|<code>type</code><br />
|Тип изменяемого контейнера. Используется для поиска контейнера вместе с id. Изменить тип контейнера нельзя. Необязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
|-<br />
|<code>name</code><br />
|Новое название контейнера. Обязательное<br />
|-<br />
|<code>parent</code><br />
|Не используется. Изменить проект в котором создана ветка нельзя<br />
|-<br />
|<code>review_with_comment</code><br />
|Новое значение настройки проекта "Обязательный комментарий при разметке"<br />
|}<br />
<br />
=== Удаление контейнера: "action": "remove" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>remove</code><br />
|-<br />
|<code>id</code><br />
|Идентификатор удаляемого контейнера. Обязательное<br />
|-<br />
|<code>type</code><br />
|Тип удаляемого контейнера. Используется для поиска контейнера вместе с id. Необязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
|-<br />
|<code>name</code><br />
|Не используется<br />
|-<br />
|<code>parent</code><br />
|Не используется<br />
|-<br />
|<code>review_with_comment</code><br />
|Не используется<br />
|}<br />
<br />
== <code>POST /api/public/admin/server/project-groups</code> - управление составом групп проектов ==<br />
<br />
Формат запроса:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"project_group_name_or_id": "string",<br />
"project_name_or_id": "string"<br />
}<br />
</pre><br />
<br />
Формат ответа:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"project_group_id": "string",<br />
"project_group_name": "string",<br />
"project_id": "string",<br />
"project_name": "string"<br />
}<br />
</pre><br />
<br />
Назначение полей запроса и ответа зависит от типа операции и определяется значением поля <code>action</code>.<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Поддерживаемыe значения поля <code>action</code><br />
|-<br />
!Значение<br />
!Тип операции<br />
|-<br />
|<code>get</code><br />
|Получение экземпляра группы проектов<br />
|-<br />
|<code>add-project-to-group</code><br />
|Добавление проекта в группу проектов<br />
|-<br />
|<code>remove-project-from-group</code><br />
|Исключение проекта из группы проектов<br />
|}<br />
<br />
=== Получение экземпляра группы проектов: "action": "get" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>get</code><br />
|-<br />
|<code>project_group_name_or_id</code><br />
|Название или идентификатор запрашиваемой группы проектов. {{Note|text= Поддержка названия добавлена ПОСЛЕ версии 9.0.2}}<br />
|-<br />
|<code>project_name_or_id</code><br />
|Не используется<br />
|}<br />
<br />
=== Добавление проекта в группу проектов: "action": "add-project-to-group" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>add-project-to-group</code><br />
|-<br />
|<code>project_group_name_or_id</code><br />
|Название или идентификатор изменяемой группы проектов<br />
|-<br />
|<code>project_name_or_id</code><br />
|Название или идентификатор добавляемого проекта<br />
|}<br />
<br />
=== Исключение проекта из группы проектов: "action": "remove-project-from-group" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>remove-project-from-group</code><br />
|-<br />
|<code>project_group_name_or_id</code><br />
|Название или идентификатор изменяемой группы проектов<br />
|-<br />
|<code>project_name_or_id</code><br />
|Название или идентификатор исключаемого проекта<br />
|}<br />
<br />
==== Примеры запросов управления составом групп ===<br />
<pre><br />
$ curl --data '{"action": "get", "project_group_name_or_id": "0f7da122-9c86-4384-b7bc-356bfb3b7f28"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"get","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA"}<br />
<br />
$ curl --data '{"action": "get", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"get","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA"}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "add-project-to-group", "project_name_or_id": "iptables", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"add-project-to-group","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA","project_id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","project_name":"iptables"}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "remove-project-from-group", "project_name_or_id": "iptables", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"remove-project-from-group","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA","project_id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","project_name":"iptables"}<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:Public_API/management/containers&diff=2088Help:Public API/management/containers2024-10-16T09:17:21Z<p>M.vinogradov: Created page with "= Управление контейнерами (проектами, ветками, группами проектов) = В данном разделе содержится описание REST API управления контейнерами и их содержимым. Для выполнения операций получения списка контейнеров, их создания, изменения и удаления существует http-ресу..."</p>
<hr />
<div>= Управление контейнерами (проектами, ветками, группами проектов) =<br />
<br />
В данном разделе содержится описание REST API управления контейнерами и их содержимым.<br />
<br />
Для выполнения операций получения списка контейнеров, их создания, изменения и удаления существует http-ресурс<br />
<br />
<pre style="white-space: pre;"><br />
POST /api/public/admin/server/containers<br />
</pre><br />
<br />
Для операций управления составом групп проектов существует http-ресурс <br />
<br />
<pre style="white-space: pre;"><br />
POST /api/public/admin/server/project-groups<br />
</pre><br />
<br />
{{Note|type=warn|text=Для использования ресурсов необходимо использовать http-запросы с токеном пользователя имеющего соответствующие права}}<br />
<br />
== <code>POST /api/public/admin/server/containers</code> - управление набором проектов, веток, групп проектов ==<br />
<br />
Формат запроса:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"id": "string",<br />
"type": "string",<br />
"name": "string",<br />
"parent": "string",<br />
"review_with_comment": true<br />
}<br />
</pre><br />
<br />
Формат ответа:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"Containers": [<br />
{<br />
"action": "string",<br />
"id": "string",<br />
"name": "string",<br />
"parent": "string",<br />
"review_with_comment": true,<br />
"type": "string"<br />
}<br />
]<br />
}<br />
</pre><br />
<br />
Назначение полей запроса и установка значений полей ответа зависит от типа операции и определяется значением поля запроса <code>action</code>.<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Поддерживаемыe значения поля <code>action</code><br />
|-<br />
!Значение<br />
!Тип операции<br />
|-<br />
|<code>list</code><br />
|Получение списка контейнеров<br />
|-<br />
|<code>add</code><br />
|Создание контейнера<br />
|-<br />
|<code>update</code><br />
|Изменение контейнера<br />
|-<br />
|<code>remove</code><br />
|Удаление контейнера<br />
|}<br />
<br />
=== Получение списка контейнеров: "action": "list" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>list</code><br />
|-<br />
|<code>id</code><br />
|Если не пустое: идентификатор контейнера, для которого будут загружены "связанные" контейнеры:<br />
:- если передан id группы проектов - вернётся список проектов входящих в данную группу<br />
:- если передан id проекта - вернётся список групп проектов, в который входит проект + список его веток<br />
:- если передан id ветки - вернётся список снимков данной ветки<br />
|-<br />
|<code>type</code><br />
|Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
<br />
Если не пустое: отфильтровывает список контейнеров по типу<br />
<br />
Если пустое:<br />
:- если поле <code>id</code> пустое - возвращается объединённый список проектов и групп проектов<br />
|-<br />
|<code>name</code><br />
|Если не пустое:<br />
:- если поле <code>id</code> пустое - отфильтровывает список контейнеров по названию<br />
:- если поле <code>id</code> НЕ пустое - фильтр по названию НЕ применяется<br />
|-<br />
|<code>parent</code><br />
|Не используется<br />
|-<br />
|<code>review_with_comment</code><br />
|Не используется<br />
|}<br />
<br />
==== Примеры запросов с <code>"action": "list"</code> ====<br />
<pre><br />
$ curl --data '{"action": "list"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"20706313-6986-4c9d-9a4e-5e4908a11499","name":"projectGroupB","type":"project-group"},{"id":"a7e22042-96e5-4659-b21a-0615d434bed7","name":"bash","type":"project"},{"id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","name":"iptables","type":"project"},{"id":"d53b0b92-d0fb-429a-8f86-c8fe6ee50c0c","name":"proftpd","type":"project"}]}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "list", "type": "project-group"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"20706313-6986-4c9d-9a4e-5e4908a11499","name":"projectGroupB","type":"project-group"}]}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "list", "name": "bas"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"a7e22042-96e5-4659-b21a-0615d434bed7","name":"bash","type":"project"}]}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "list", "id":"a7e22042-96e5-4659-b21a-0615d434bed7"}' -X POST http://localhost:8080/api/public/admin/server/containers<br />
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"ef9210db-180b-4351-8a2f-7e8ceaa42ec6","name":"master","type":"branch","parent":"a7e22042-96e5-4659-b21a-0615d434bed7"}]}<br />
</pre><br />
<br />
=== Создание контейнера: "action": "add" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>add</code><br />
|-<br />
|<code>id</code><br />
|Не используется<br />
|-<br />
|<code>type</code><br />
|Тип нового контейнера. Обязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
|-<br />
|<code>name</code><br />
|Название нового контейнера. Обязательное<br />
|-<br />
|<code>parent</code><br />
|Название или идентификатор проекта, в котором будет создана новая ветка<br />
Если тип нового контейнера НЕ <code>branch</code>: не используется<br />
|-<br />
|<code>review_with_comment</code><br />
|Значение настройки проекта "Обязательный комментарий при разметке"<br />
Если тип нового контейнера НЕ <code>project</code>: не используется<br />
|}<br />
<br />
=== Изменение контейнера: "action": "update" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>update</code><br />
|-<br />
|<code>id</code><br />
|Идентификатор изменяемого контейнера. Обязательное<br />
|-<br />
|<code>type</code><br />
|Тип изменяемого контейнера. Используется для поиска контейнера вместе с id. Изменить тип контейнера нельзя. Необязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
|-<br />
|<code>name</code><br />
|Новое название контейнера. Обязательное<br />
|-<br />
|<code>parent</code><br />
|Не используется. Изменить проект в котором создана ветка нельзя<br />
|-<br />
|<code>review_with_comment</code><br />
|Новое значение настройки проекта "Обязательный комментарий при разметке"<br />
|}<br />
<br />
=== Удаление контейнера: "action": "remove" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>remove</code><br />
|-<br />
|<code>id</code><br />
|Идентификатор удаляемого контейнера. Обязательное<br />
|-<br />
|<code>type</code><br />
|Тип удаляемого контейнера. Используется для поиска контейнера вместе с id. Необязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code><br />
|-<br />
|<code>name</code><br />
|Не используется<br />
|-<br />
|<code>parent</code><br />
|Не используется<br />
|-<br />
|<code>review_with_comment</code><br />
|Не используется<br />
|}<br />
<br />
== <code>POST /api/public/admin/server/project-groups</code> - управление составом групп проектов ==<br />
<br />
Формат запроса:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"project_group_name_or_id": "string",<br />
"project_name_or_id": "string"<br />
}<br />
</pre><br />
<br />
Формат ответа:<br />
<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"project_group_id": "string",<br />
"project_group_name": "string",<br />
"project_id": "string",<br />
"project_name": "string"<br />
}<br />
</pre><br />
<br />
Назначение полей запроса и ответа зависит от типа операции и определяется значением поля <code>action</code>.<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Поддерживаемыe значения поля <code>action</code><br />
|-<br />
!Значение<br />
!Тип операции<br />
|-<br />
|<code>get</code><br />
|Получение экземпляра группы проектов<br />
|-<br />
|<code>add-project-to-group</code><br />
|Добавление проекта в группу проектов<br />
|-<br />
|<code>remove-project-from-group</code><br />
|Исключение проекта из группы проектов<br />
|}<br />
<br />
=== Получение экземпляра группы проектов: "action": "get" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>get</code><br />
|-<br />
|<code>project_group_name_or_id</code><br />
|Название или идентификатор запрашиваемой группы проектов. {{Note|text= Поддержка названия добавлена ПОСЛЕ версии 9.0.2}}<br />
|-<br />
|<code>project_name_or_id</code><br />
|Не используется<br />
|}<br />
<br />
=== Добавление проекта в группу проектов: "action": "add-project-to-group" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>add-project-to-group</code><br />
|-<br />
|<code>project_group_name_or_id</code><br />
|Название или идентификатор изменяемой группы проектов<br />
|-<br />
|<code>project_name_or_id</code><br />
|Название или идентификатор добавляемого проекта<br />
|}<br />
<br />
=== Исключение проекта из группы проектов: "action": "remove-project-from-group" ===<br />
<br />
{| class="wikitable"<br />
|+ style=white-space:nowrap | Назначение полей запроса<br />
|-<br />
!Поле<br />
!Описание<br />
|-<br />
|<code>action</code><br />
|<code>remove-project-from-group</code><br />
|-<br />
|<code>project_group_name_or_id</code><br />
|Название или идентификатор изменяемой группы проектов<br />
|-<br />
|<code>project_name_or_id</code><br />
|Название или идентификатор исключаемого проекта<br />
|}<br />
<br />
==== Примеры запросов управления составом групп ===<br />
<pre><br />
$ curl --data '{"action": "get", "project_group_name_or_id": "0f7da122-9c86-4384-b7bc-356bfb3b7f28"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"get","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA"}<br />
<br />
$ curl --data '{"action": "get", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"get","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA"}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "add-project-to-group", "project_name_or_id": "iptables", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"add-project-to-group","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA","project_id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","project_name":"iptables"}<br />
</pre><br />
<pre><br />
$ curl --data '{"action": "remove-project-from-group", "project_name_or_id": "iptables", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups<br />
{"action":"remove-project-from-group","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA","project_id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","project_name":"iptables"}<br />
</pre></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=2055Help:XSvacer:Webide2024-07-15T11:53:47Z<p>M.vinogradov: </p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
= Поддержка среды разработки Theia IDE =<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске Svacer.<br />
<br />
При запуске функциональности Webide также будет запущена функциональность [[Help:XSvacer:Docker|docker]].<br />
<br />
При активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов<br />
* в пользовательском интерфейсе на вкладке "Информация о снимке" появляется кнопка "Открыть в IDE"<br />
* устанавливается подключение к хосту docker, на котором будут запускаться контейнеры с экземплярами IDE<br />
<br />
=== Быстрый запуск функциональности с настройками по умолчанию ===<br />
<br />
Для того, чтобы начать пользоваться функциональностью запуска IDE без изменения конфигурационных параметров, нужно выполнить следующие действия:<br />
# Настройка доступа к docker-хосту:<br />
## Запустить docker со настройками по умолчанию (dockerd должен слушать unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option)<br />
## Проверить, что у пользователя под которым будет запускаться Svacer есть доступ к unix-сокету docker-хоста <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/engine/install/linux-postinstall<br />
# Настроить права доступа у пользователей, которые смогут запускать IDE: требуются разрешения на проект/ветку "Просмотр маркеров" и "Экспорт разметки"<br />
# Перезапустить Svacer с флагом <code style="white-space: pre;">--xsvacer.features webide</code><br />
# ''Опционально.'' Для ускорения первого запуска IDE:<br />
## Скачать [https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar архив с docker-образом]<br />
## Загрузить docker-образ из архива на docker-хост: <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code><br />
<br />
После этого у пользователей с указанными правами должна появиться кнопка "Открыть в IDE" на панели с информацией о снимке.<br />
<br />
{{Note}} IDE с исходным кодом снимков будут запускаться в новых вкладках браузера. Обычно все браузеры блокируют автоматическое открытие вкладки и показывают соответствующее предупреждение. <br />
<br />
Например, в Firefox:<br />
<br />
[[File:Firefox popup notification ru.png]]<br />
<br />
В таком случае нужно дать разрешение на открытие вкладки с IDE:<br />
<br />
[[File:Firefox popup notification expanded ru.png|x150px]]<br />
<br />
<br />
При необходимости изменения настроек подключения к docker-хосту:<br />
# Скопировать [[Help:XSvacer:Docker#Конфигурация_по_умолчанию|конфигурацию docker по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/docker</code><br />
<br />
При необходимости изменения настроек запуска IDE:<br />
# Скопировать [[#Конфигурация_по_умолчанию|конфигурацию webide по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/webide</code><br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске Svacer указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В [[Help:XSvacer:Webide#Конфигурация|конфигурации]] функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE<br />
# У пользователя Svacer имеются разрешения "Просмотр маркеров" и "Экспорт разметки" на проект, в котором находится снимок, для которого нужно запустить IDE<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка "Открыть в IDE".<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code><br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается<br />
#** Если IDE недоступна: продолжается процесс запуска. IDE будет перезапущена<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code>xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code><br />
# Исходный код снимка скачивается в "корневую папку снимка"<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sariffiletemplate</code><br />
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>. Если docker-образ отсутствует, он будет загружен на хост<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code>running</code> — процесс запуска IDE продолжается<br />
##** в статусе <code>created</code>, <code>exited</code> или <code>paused</code> — контейнер будет запущен<br />
##** в других статусах — вернётся соответствующая ошибка и процесс запуска IDE прервётся<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code><br />
#* Если за отведённое время ответ от IDE получен — процесс запуска завершается<br />
#* Если ответ не получен — вернётся ошибка <code>ide not ready</code><br />
<br />
При возникновении ошибки на одном из этапов запуска IDE артефакты, созданные на предыдущих этапах, останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
{{Note|type=reminder|text=Причиной возникновения ошибки "ide not ready" может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>. В этом случае рекомендуется попробовать повторно запустить IDE через короткий промежуток времени}}<br />
<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется проверить:<br />
# Сетевую доступность docker-хоста<br />
# Настройки фаервола на docker-хосте<br />
# Настройки биндинга docker-контейнера c IDE<br />
::<code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code> <br />
::Контейнер должен быть подключён к доступному сетевому интерфейсу<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с префиксом <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code><br />
<br />
Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
:<code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>POST http://docker-host:35353/socket.io/?...</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
Для запуска IDE в окне браузера нужно указать адрес<br />
<br />
:<code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code><br />
<br />
{{Note}} Завершающий слеш обязателен!<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы Svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода<br />
DELETE /api/snapshots/{snapshot_id}/ide<br />
с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>. В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
По умолчанию установлен параметр конфигурации <br />
<br />
xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true<br />
<br />
Это означает, что после остановки docker-контейнер будет автоматически удалён.<br />
<br />
Чтобы изменить это поведение, настройка <br />
xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove<br />
<br />
должна быть установлена в <code>false</code> на момент запуска docker-контейнера IDE. Это можно сделать, например, установив значение переменной окружения <br />
<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false<br />
<br />
{{Note|type=error|text=При использовании версии Svacer 9.0.0 установка <code>autoremove: false</code> вызывает ошибку запуска. Исправлено в версии [[Svacer#Релизы|9.0.1]].'''}}<br />
<br />
При корректной остановке (например SIGTERM) Svacer автоматически остановит все запущенные docker-контейнеры IDE.<br />
<br />
=== Подключение к IDE после некорректного завершения Svacer ===<br />
<br />
При запуске Svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах. При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке Svacer все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!}}<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание <br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> — идентификатор IDE<br />
:<code style="white-space: pre;">name</code> — название IDE<br />
:<code style="white-space: pre;">order</code> — порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка. <br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> — действие<br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Доступные действия:'''<br />
* <code style="white-space: pre;">update_markup</code> — обновление предупреждений и разметки (sarif-файла)<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например, для default-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code><br />
<br />
Раздел конфигурации для управления функциональностью — <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому необходимо также [[Help:XSvacer:Docker|настроить доступ к docker-хосту]] в разделе <code style="white-space: pre;">xsvacer/docker</code>, иначе функциональность WebIDE не сможет работать корректно.<br />
<br />
В случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]].<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!}}<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации default) <br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0 <br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0) <br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на машине со Svacer<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources <br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на хосте docker. Нужен при использовании удалённого docker-хоста, т. к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
| <br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker. По умолчанию <code style="white-space: pre;">"/"</code><br />
| <br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"</nowiki><br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только стандартный менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
| <br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default <br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
| <br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default <br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|<nowiki>"theia-1-46-{{.StartArgs.SnapshotID}}"</nowiki><br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список меток docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer <br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
| <br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint <br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|1.46.0.sarif.clang <br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост<br />
* repository — будет вызван docker pull образа <code>{image/name}:{image/tag}</code><br />
* file — будет вызван docker load с URL <code>image/sourcefileurl</code><br />
|file <br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|URL откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
URL может содержать:<br />
* путь к локальному файлу: схема <code>file://</code><br />
* http/https-адрес: схема <code>http://</code> или <code>https://</code><br />
|https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
| <br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70<br />
| <br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki> <br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379<br />
| <br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true <br />
|-<br />
|docker/container/hostconfig/portbindings<br />
|map<br />
|<br />
|<br />
"3000/tcp": <br />
:- hostport: 0 <br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104<br />
| <br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
| <br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10 <br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms <br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sariffiletemplate: "<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang<br />
sourcetype: file<br />
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
По умолчанию используется 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/).<br />
<br />
{{Note|text=При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы}}<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения<br />
<br />
XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code><br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске Svacer:<br />
<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в корневые папки, заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code><br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code><br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code><br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code><br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code><br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code><br />
#*: метки с названиями <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><br />
# При использовании rootless-хоста docker будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста|настройкам]]<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр <br />
<br />
xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl<br />
<br />
Содержит значение <br />
<br />
https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
<br />
По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т. к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго. <br />
<br />
Для ускорения первого запуска IDE докер образ можно загрузить на хост docker вручную. Для этого необходимо:<br />
<br />
# Скачать файл архива<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code><br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0 1.46.0].<br />
<br />
При этом была изменена компоновка расширений Theia. Результат выполнения <code>git diff</code>:<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "ms-sarifvscode.sarif-viewer": "https://open-vsx.org/api/MS-SarifVSCode/sarif-viewer/3.4.2/file/MS-SarifVSCode.sarif-viewer-3.4.2.vsix"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа: <br />
docker build -t theia-blueprint:1.46.0.sarif.clang -f browser.Dockerfile .<br />
<br />
Команда экспорта docker-образа:<br />
docker image save theia-blueprint:1.46.0 > /path/to/tar/theia-blueprint.1.46.0.docker.command.tar<br />
<br />
== Известные проблемы ==<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.<br />
<br />
В 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.<br />
<br />
Поэтому для решения данной проблемы Svacer должен открываться по HTTPS или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=2054Help:XSvacer:Webide2024-07-15T11:52:57Z<p>M.vinogradov: </p>
<hr />
<div>{{Note|text=Данная функциональность входит в набор расширений XSvacer}}<br />
<br />
= Поддержка среды разработки Theia IDE =<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске Svacer.<br />
<br />
При запуске функциональности Webide также будет запущена функциональность [[Help:XSvacer:Docker|docker]].<br />
<br />
При активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов<br />
* в пользовательском интерфейсе на вкладке "Информация о снимке" появляется кнопка "Открыть в IDE"<br />
* устанавливается подключение к хосту docker, на котором будут запускаться контейнеры с экземплярами IDE<br />
<br />
=== Быстрый запуск функциональности с настройками по умолчанию ===<br />
<br />
Для того, чтобы начать пользоваться функциональностью запуска IDE без изменения конфигурационных параметров, нужно выполнить следующие действия:<br />
# Настройка доступа к docker-хосту:<br />
## Запустить docker со настройками по умолчанию (dockerd должен слушать unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option)<br />
## Проверить, что у пользователя под которым будет запускаться Svacer есть доступ к unix-сокету docker-хоста <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/engine/install/linux-postinstall<br />
# Настроить права доступа у пользователей, которые смогут запускать IDE: требуются разрешения на проект/ветку "Просмотр маркеров" и "Экспорт разметки"<br />
# Перезапустить Svacer с флагом <code style="white-space: pre;">--xsvacer.features webide</code><br />
# ''Опционально.'' Для ускорения первого запуска IDE:<br />
## Скачать [https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar архив с docker-образом]<br />
## Загрузить docker-образ из архива на docker-хост: <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code><br />
<br />
После этого у пользователей с указанными правами должна появиться кнопка "Открыть в IDE" на панели с информацией о снимке.<br />
<br />
{{Note}} IDE с исходным кодом снимков будут запускаться в новых вкладках браузера. Обычно все браузеры блокируют автоматическое открытие вкладки и показывают соответствующее предупреждение. <br />
<br />
Например, в Firefox:<br />
<br />
[[File:Firefox popup notification ru.png]]<br />
<br />
В таком случае нужно дать разрешение на открытие вкладки с IDE:<br />
<br />
[[File:Firefox popup notification expanded ru.png|x150px]]<br />
<br />
<br />
При необходимости изменения настроек подключения к docker-хосту:<br />
# Скопировать [[Help:XSvacer:Docker#Конфигурация_по_умолчанию|конфигурацию docker по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/docker</code><br />
<br />
При необходимости изменения настроек запуска IDE:<br />
# Скопировать [[#Конфигурация_по_умолчанию|конфигурацию webide по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/webide</code><br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске Svacer указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В [[Help:XSvacer:Webide#Конфигурация|конфигурации]] функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE<br />
# У пользователя Svacer имеются разрешения "Просмотр маркеров" и "Экспорт разметки" на проект, в котором находится снимок, для которого нужно запустить IDE<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка "Открыть в IDE".<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code><br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается<br />
#** Если IDE недоступна: продолжается процесс запуска. IDE будет перезапущена<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code>xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code><br />
# Исходный код снимка скачивается в "корневую папку снимка"<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sariffiletemplate</code><br />
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>. Если docker-образ отсутствует, он будет загружен на хост<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code>running</code> — процесс запуска IDE продолжается<br />
##** в статусе <code>created</code>, <code>exited</code> или <code>paused</code> — контейнер будет запущен<br />
##** в других статусах — вернётся соответствующая ошибка и процесс запуска IDE прервётся<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code><br />
#* Если за отведённое время ответ от IDE получен — процесс запуска завершается<br />
#* Если ответ не получен — вернётся ошибка <code>ide not ready</code><br />
<br />
При возникновении ошибки на одном из этапов запуска IDE артефакты, созданные на предыдущих этапах, останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
{{Note|type=reminder|text=Причиной возникновения ошибки "ide not ready" может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>. В этом случае рекомендуется попробовать повторно запустить IDE через короткий промежуток времени}}<br />
<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется проверить:<br />
# Сетевую доступность docker-хоста<br />
# Настройки фаервола на docker-хосте<br />
# Настройки биндинга docker-контейнера c IDE<br />
::<code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code> <br />
::Контейнер должен быть подключён к доступному сетевому интерфейсу<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с префиксом <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code><br />
<br />
Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
:<code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>POST http://docker-host:35353/socket.io/?...</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
Для запуска IDE в окне браузера нужно указать адрес<br />
<br />
:<code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code><br />
<br />
{{Note}} Завершающий слеш обязателен!<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы Svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода<br />
DELETE /api/snapshots/{snapshot_id}/ide<br />
с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>. В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
По умолчанию установлен параметр конфигурации <br />
<br />
xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true<br />
<br />
Это означает, что после остановки docker-контейнер будет автоматически удалён.<br />
<br />
Чтобы изменить это поведение, настройка <br />
xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove<br />
<br />
должна быть установлена в <code>false</code> на момент запуска docker-контейнера IDE. Это можно сделать, например, установив значение переменной окружения <br />
<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false<br />
<br />
{{Note|type=error|text=При использовании версии Svacer 9-0-0 установка <code>autoremove: false</code> вызывает ошибку запуска. Исправлено в версии [[Svacer#Релизы|9-0-1]].'''}}<br />
<br />
При корректной остановке (например SIGTERM) Svacer автоматически остановит все запущенные docker-контейнеры IDE.<br />
<br />
=== Подключение к IDE после некорректного завершения Svacer ===<br />
<br />
При запуске Svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах. При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке Svacer все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!}}<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание <br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> — идентификатор IDE<br />
:<code style="white-space: pre;">name</code> — название IDE<br />
:<code style="white-space: pre;">order</code> — порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка. <br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> — действие<br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Доступные действия:'''<br />
* <code style="white-space: pre;">update_markup</code> — обновление предупреждений и разметки (sarif-файла)<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например, для default-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code><br />
<br />
Раздел конфигурации для управления функциональностью — <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому необходимо также [[Help:XSvacer:Docker|настроить доступ к docker-хосту]] в разделе <code style="white-space: pre;">xsvacer/docker</code>, иначе функциональность WebIDE не сможет работать корректно.<br />
<br />
В случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]].<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
{{Note|text=На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!}}<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации default) <br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0 <br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0) <br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на машине со Svacer<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources <br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на хосте docker. Нужен при использовании удалённого docker-хоста, т. к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
| <br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker. По умолчанию <code style="white-space: pre;">"/"</code><br />
| <br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"</nowiki><br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только стандартный менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
| <br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default <br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
| <br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default <br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|<nowiki>"theia-1-46-{{.StartArgs.SnapshotID}}"</nowiki><br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список меток docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer <br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
| <br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint <br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|1.46.0.sarif.clang <br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост<br />
* repository — будет вызван docker pull образа <code>{image/name}:{image/tag}</code><br />
* file — будет вызван docker load с URL <code>image/sourcefileurl</code><br />
|file <br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|URL откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
URL может содержать:<br />
* путь к локальному файлу: схема <code>file://</code><br />
* http/https-адрес: схема <code>http://</code> или <code>https://</code><br />
|https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
| <br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70<br />
| <br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki> <br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379<br />
| <br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true <br />
|-<br />
|docker/container/hostconfig/portbindings<br />
|map<br />
|<br />
|<br />
"3000/tcp": <br />
:- hostport: 0 <br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104<br />
| <br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
| <br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10 <br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms <br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sariffiletemplate: "<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang<br />
sourcetype: file<br />
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
По умолчанию используется 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/).<br />
<br />
{{Note|text=При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы}}<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения<br />
<br />
XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code><br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске Svacer:<br />
<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в корневые папки, заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code><br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code><br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code><br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code><br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code><br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code><br />
#*: метки с названиями <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><br />
# При использовании rootless-хоста docker будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста|настройкам]]<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр <br />
<br />
xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl<br />
<br />
Содержит значение <br />
<br />
https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
<br />
По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т. к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго. <br />
<br />
Для ускорения первого запуска IDE докер образ можно загрузить на хост docker вручную. Для этого необходимо:<br />
<br />
# Скачать файл архива<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code><br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0 1.46.0].<br />
<br />
При этом была изменена компоновка расширений Theia. Результат выполнения <code>git diff</code>:<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "ms-sarifvscode.sarif-viewer": "https://open-vsx.org/api/MS-SarifVSCode/sarif-viewer/3.4.2/file/MS-SarifVSCode.sarif-viewer-3.4.2.vsix"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа: <br />
docker build -t theia-blueprint:1.46.0.sarif.clang -f browser.Dockerfile .<br />
<br />
Команда экспорта docker-образа:<br />
docker image save theia-blueprint:1.46.0 > /path/to/tar/theia-blueprint.1.46.0.docker.command.tar<br />
<br />
== Известные проблемы ==<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.<br />
<br />
В 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.<br />
<br />
Поэтому для решения данной проблемы Svacer должен открываться по HTTPS или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=2024Help:XSvacer:Webide2024-06-19T09:13:17Z<p>M.vinogradov: support#3391 docker image url changed</p>
<hr />
<div>= Поддержка среды разработки Theia IDE =<br />
<br />
Данная функциональность входит в набор расширений XSvacer<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске Svacer.<br />
<br />
При запуске функциональности Webide также будет запущена функциональность [[Help:XSvacer:Docker|docker]].<br />
<br />
При активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов<br />
* в пользовательском интерфейсе на вкладке "Информация о снимке" появляется кнопка "Открыть в IDE"<br />
* устанавливается подключение к хосту docker, на котором будут запускаться контейнеры с экземплярами IDE<br />
<br />
=== Быстрый запуск функциональности с настройками по умолчанию ===<br />
<br />
Для того, чтобы начать пользоваться функциональностью запуска IDE без изменения конфигурационных параметров, нужно выполнить следующие действия:<br />
# Настройка доступа к docker-хосту:<br />
## Запустить docker со настройками по умолчанию (dockerd должен слушать unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option)<br />
## Проверить, что у пользователя под которым будет запускаться Svacer есть доступ к unix-сокету docker-хоста <code style="white-space: pre;">unix:///var/run/docker.sock</code> — https://docs.docker.com/engine/install/linux-postinstall<br />
# Настроить права доступа у пользователей, которые смогут запускать IDE: требуются разрешения на проект/ветку "Просмотр маркеров" и "Экспорт разметки"<br />
# Перезапустить Svacer с флагом <code style="white-space: pre;">--xsvacer.features webide</code><br />
# ''Опционально.'' Для ускорения первого запуска IDE:<br />
## Скачать [https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar архив с docker-образом]<br />
## Загрузить docker-образ из архива на docker-хост: <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code><br />
<br />
После этого у пользователей с указанными правами должна появиться кнопка "Открыть в IDE" на панели с информацией о снимке.<br />
<br />
'''Внимание!''' IDE с исходным кодом снимков будут запускаться в новых вкладках браузера. Обычно все браузеры блокируют автоматическое открытие вкладки и показывают соответствующее предупреждение. <br />
<br />
Например, в Firefox:<br />
<br />
[[File:Firefox popup notification ru.png]]<br />
<br />
В таком случае нужно дать разрешение на открытие вкладки с IDE:<br />
<br />
[[File:Firefox popup notification expanded ru.png|x150px]]<br />
<br />
<br />
При необходимости изменения настроек подключения к docker-хосту:<br />
# Скопировать [[Help:XSvacer:Docker#Конфигурация_по_умолчанию|конфигурацию docker по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/docker</code><br />
<br />
При необходимости изменения настроек запуска IDE:<br />
# Скопировать [[#Конфигурация_по_умолчанию|конфигурацию webide по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла svacer.cfg<br />
# Внести требуемые изменения в конфигурацию раздела <code>xsvacer/webide</code><br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске Svacer указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В [[Help:XSvacer:Webide#Конфигурация|конфигурации]] функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE<br />
# У пользователя Svacer имеются разрешения "Просмотр маркеров" и "Экспорт разметки" на проект, в котором находится снимок, для которого нужно запустить IDE<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка "Открыть в IDE".<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code><br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается<br />
#** Если IDE недоступна: продолжается процесс запуска. IDE будет перезапущена<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code>xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code><br />
# Исходный код снимка скачивается в "корневую папку снимка"<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sariffiletemplate</code><br />
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>. Если docker-образ отсутствует, он будет загружен на хост<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code>running</code> — процесс запуска IDE продолжается<br />
##** в статусе <code>created</code>, <code>exited</code> или <code>paused</code> — контейнер будет запущен<br />
##** в других статусах — вернётся соответствующая ошибка и процесс запуска IDE прервётся<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code><br />
#* Если за отведённое время ответ от IDE получен — процесс запуска завершается<br />
#* Если ответ не получен — вернётся ошибка <code>ide not ready</code><br />
<br />
При возникновении ошибки на одном из этапов запуска IDE артефакты, созданные на предыдущих этапах, останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
Причиной возникновения ошибки "ide not ready" может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>. В этом случае рекомендуется попробовать повторно запустить IDE через короткий промежуток времени.<br />
<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется проверить:<br />
# Сетевую доступность docker-хоста<br />
# Настройки фаервола на docker-хосте<br />
# Настройки биндинга docker-контейнера c IDE<br />
::<code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code> <br />
::Контейнер должен быть подключён к доступному сетевому интерфейсу<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с префиксом <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code><br />
<br />
Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
:<code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>POST http://docker-host:35353/socket.io/?...</nowiki></code><br />
:<code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
Для запуска IDE в окне браузера нужно указать адрес<br />
<br />
<code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code><br />
<br />
'''Завершающий слеш обязателен!'''<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы Svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода<br />
DELETE /api/snapshots/{snapshot_id}/ide<br />
с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>. В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
По умолчанию установлен параметр конфигурации <br />
<br />
xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true<br />
<br />
Это означает, что после остановки docker-контейнер будет автоматически удалён.<br />
<br />
Чтобы изменить это поведение, настройка <br />
xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove<br />
<br />
должна быть установлена в <code>false</code> на момент запуска docker-контейнера IDE. Это можно сделать, например, установив значение переменной окружения <br />
<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false<br />
<br />
'''Сейчас установка <code>autoremove: false</code> вызывает ошибку запуска Svacer. Не используйте данную настройку до исправления.'''<br />
<br />
При корректной остановке (например SIGTERM) Svacer автоматически остановит все запущенные docker-контейнеры IDE.<br />
<br />
=== Подключение к IDE после некорректного завершения Svacer ===<br />
<br />
При запуске Svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах. При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке Svacer все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
'''Внимание!''' На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание <br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> — идентификатор IDE<br />
:<code style="white-space: pre;">name</code> — название IDE<br />
:<code style="white-space: pre;">order</code> — порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка. <br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> — действие<br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Доступные действия:'''<br />
* <code style="white-space: pre;">update_markup</code> — обновление предупреждений и разметки (sarif-файла)<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> — идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> — идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например, для default-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code><br />
<br />
Раздел конфигурации для управления функциональностью — <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому необходимо также [[Help:XSvacer:Docker|настроить доступ к docker-хосту]] в разделе <code style="white-space: pre;">xsvacer/docker</code>, иначе функциональность WebIDE не сможет работать корректно.<br />
<br />
В случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]].<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
'''Внимание!''' На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации default) <br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0 <br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0) <br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на машине со Svacer<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources <br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на хосте docker. Нужен при использовании удалённого docker-хоста, т. к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
| <br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker. По умолчанию <code style="white-space: pre;">"/"</code><br />
| <br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|<nowiki>"{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"</nowiki><br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только стандартный менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
| <br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default <br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
| <br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default <br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|<nowiki>"theia-1-46-{{.StartArgs.SnapshotID}}"</nowiki><br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список меток docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer <br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
| <br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint <br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|1.46.0.sarif.clang <br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост<br />
* repository — будет вызван docker pull образа <code>{image/name}:{image/tag}</code><br />
* file — будет вызван docker load с URL <code>image/sourcefileurl</code><br />
|file <br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|URL откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
URL может содержать:<br />
* путь к локальному файлу: схема <code>file://</code><br />
* http/https-адрес: схема <code>http://</code> или <code>https://</code><br />
|https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
| <br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70<br />
| <br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki> <br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379<br />
| <br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true <br />
|-<br />
|docker/container/hostconfig/portbindings<br />
|map<br />
|<br />
|<br />
"3000/tcp": <br />
:- hostport: 0 <br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104<br />
| <br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
| <br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10 <br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms <br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code><br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sariffiletemplate: "<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang<br />
sourcetype: file<br />
sourcefileurl: https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
По умолчанию используется 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/).<br />
<br />
При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения<br />
<br />
XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code><br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске Svacer:<br />
<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в корневые папки, заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code><br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code><br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code><br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code><br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code><br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code><br />
#*: метки с названиями <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><br />
# При использовании rootless-хоста docker будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста|настройкам]]<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр <br />
<br />
xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl<br />
<br />
Содержит значение <br />
<br />
https://svacer.ispras.ru/docker/images/theia-blueprint.1.46.0.sarif.clang.tar<br />
<br />
По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т. к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго. <br />
<br />
Для ускорения первого запуска IDE докер образ можно загрузить на хост docker вручную. Для этого необходимо:<br />
<br />
# Скачать файл архива<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code><br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0 1.46.0].<br />
<br />
При этом была изменена компоновка расширений Theia. Результат выполнения <code>git diff</code>:<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "ms-sarifvscode.sarif-viewer": "https://open-vsx.org/api/MS-SarifVSCode/sarif-viewer/3.4.2/file/MS-SarifVSCode.sarif-viewer-3.4.2.vsix"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа: <br />
docker build -t theia-blueprint:1.46.0.sarif.clang -f browser.Dockerfile .<br />
<br />
Команда экспорта docker-образа:<br />
docker image save theia-blueprint:1.46.0 > /path/to/tar/theia-blueprint.1.46.0.docker.command.tar<br />
<br />
== Известные проблемы ==<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.<br />
<br />
В 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.<br />
<br />
Поэтому для решения данной проблемы Svacer должен открываться по HTTPS или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Svacer&diff=1976Svacer2024-06-10T12:43:46Z<p>M.vinogradov: Добавлена ссылка на документацию XSvacer</p>
<hr />
<div>Svacer — сервер для хранения и обработки результатов статического анализа. Поддерживает импорт результатов анализа из [https://svace.ispras.ru Svace] напрямую и из прочих анализаторов через формат [[Help:Sarif|SARIF]].<br />
<br />
=== Техническая документация ===<br />
Version 9.0.0<br />
# [[Help:Introduction|Введение]]<br />
# [[Help:Installation|Установка и обновление]]<br />
# [[Help:Import from Svace|Импорт из Svace]]<br />
# [[Help:Backup|Резервное копирование]]<br />
# [[Help:UI manual|Использование веб-интерфейса]]<br />
# [[Help:Public API|Public REST API]]<br />
# [[Help:CLI|CLI]]<br />
# [[LDAP configuration|LDAP]]<br />
# [[OIDC|OpenID Connect]]<br />
# [[Help:Sarif|SARIF]]<br />
# [[Help:Statistics|Статистика]]<br />
# [[Help:Match|Механизмы сопоставления предупреждений и переноса разметки]]<br />
# [[Help:XSvacer|XSvacer - расширение функциональности svacer]]<br />
<br />
=== Релизы ===<br />
{| class="wikitable"<br />
! version !! zip !! linux !! windows !! deb/rpm !! doc<br />
|-<br />
| 9.0.0<br />
| [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer-9-0-0.zip svacer-9-0-0.zip]<br />
| [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer svacer]<br />[https://svacer.ispras.ru/releases/svacer-9-0-0/svacer-server svacer-server]<br />
| [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer.exe svacer.exe]<br />[https://svacer.ispras.ru/releases/svacer-9-0-0/svacer-server.exe svacer-server.exe]<br />
| [https://svacer.ispras.ru/releases/svacer-9-0-0/svacer_9.0-0_amd64.deb svacer_9.0-0_amd64.deb]<br />[https://svacer.ispras.ru/releases/svacer-9-0-0/svacer-9.0-0.x86_64.rpm svacer-9.0-0.x86_64.rpm]<br />
| [[Changelog#Release 9-0-0|Changelog]]<br />[[Release notes 9-0-0|Release notes]]<br />[[Help:Installation#9-0-0|Upgrade notes]]<br />
|-<br />
| 8.0.1 <br />
| [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer-8-0-1.zip svacer-8-0-1.zip]<br />
| [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer svacer]<br />
| [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer.exe svacer.exe]<br />
| [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer_8.0-1_amd64.deb svacer_8.0-1_amd64.deb]<br /> [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer-8.0-1.x86_64.rpm svacer-8.0-1.x86_64.rpm]<br /> [https://svacer.ispras.ru/releases/svacer-8-0-1/svacer-8.0.1.msi svacer-8.0.1.msi]<br />
| [[Changelog#Release 8-0-1|Changelog]]<br />
|-<br />
| 8.0.0 <br />
| [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer-8-0-0.zip svacer-8-0-0.zip]<br />
| [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer svacer]<br />
| [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer.exe svacer.exe]<br />
| [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer_8.0-0_amd64.deb svacer_8.0-0_amd64.deb]<br /> [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer-8.0-0.x86_64.rpm svacer-8.0-0.x86_64.rpm]<br /> [https://svacer.ispras.ru/releases/svacer-8-0-0/svacer-8.0.0.msi svacer-8.0.0.msi]<br />
| [[Changelog#Release 8-0-0|Changelog]]<br />[[Release notes 8-0-0|Release notes]]<br />
|}<br />
<br />
Также доступны в виде docker-образа на [https://hub.docker.com/r/ispras/svacer docker hub] и как пакеты в [[Help:Installation#.deb|apt-репозитории]].<br />
<br />
===== Предыдущие релизы =====<br />
{| class="wikitable"<br />
| [[Changelog#Release 7-0-1|7.0.1]]<br />
| [https://svacer.ispras.ru/releases/svacer-release-7-0-1/svacer_release-7-0-1.zip zip]([https://svacer.ispras.ru/releases/svacer-release-7-0-1/svacer_release-7-0-1.zip.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-7-0-1/svacer_7.0-1_amd64.deb deb]([https://svacer.ispras.ru/releases/svacer-release-7-0-1/svacer_7.0-1_amd64.deb.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-7-0-1/svacer-7.0-1.x86_64.rpm rpm]([https://svacer.ispras.ru/releases/svacer-release-7-0-1/svacer-7.0-1.x86_64.rpm.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-7-0-1/svacer-7.0.1.msi msi]([https://svacer.ispras.ru/releases/svacer-release-7-0-1/svacer-7.0.1.msi.md5 md5])<br />
|-<br />
| [[Changelog#Release 7-0-0|7.0.0]]<br />
| [https://svacer.ispras.ru/releases/svacer-release-7-0-0/svacer_release-7-0-0.zip zip]([https://svacer.ispras.ru/releases/svacer-release-7-0-0/svacer_release-7-0-0.zip.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-7-0-0/svacer_7.0-0_amd64.deb deb]([https://svacer.ispras.ru/releases/svacer-release-7-0-0/svacer_7.0-0_amd64.deb.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-7-0-0/svacer-7.0-0.x86_64.rpm rpm]([https://svacer.ispras.ru/releases/svacer-release-7-0-0/svacer-7.0-0.x86_64.rpm.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-7-0-0/svacer-7.0.0.msi msi]([https://svacer.ispras.ru/releases/svacer-release-7-0-0/svacer-7.0.0.msi.md5 md5])<br />
|-<br />
| [[Changelog#Release 6-0-3|6.0.3]]<br />
| [https://svacer.ispras.ru/releases/svacer-release-6-0-3/svacer_release-6-0-3.zip zip]([https://svacer.ispras.ru/releases/svacer-release-6-0-3/svacer_release-6-0-3.zip.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-6-0-3/svacer_6.0-3_amd64.deb deb]([https://svacer.ispras.ru/releases/svacer-release-6-0-3/svacer_6.0-3_amd64.deb.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-6-0-3/svacer-6.0-3.x86_64.rpm rpm]([https://svacer.ispras.ru/releases/svacer-release-6-0-3/svacer-6.0-3.x86_64.rpm.md5 md5])<br />
|-<br />
| [[Changelog#Release 6-0-2|6.0.2]]<br />
| [https://svacer.ispras.ru/releases/svacer-release-6-0-2/svacer_release-6-0-2.zip zip]([https://svacer.ispras.ru/releases/svacer-release-6-0-2/svacer_release-6-0-2.zip.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-6-0-2/svacer_6.0-2_amd64.deb deb]([https://svacer.ispras.ru/releases/svacer-release-6-0-2/svacer_6.0-2_amd64.deb.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-6-0-2/svacer-6.0-2.x86_64.rpm rpm]([https://svacer.ispras.ru/releases/svacer-release-6-0-2/svacer-6.0-2.x86_64.rpm.md5 md5])<br />
|-<br />
| [[Changelog#Release 6-0-1|6.0.1]]<br />
| [https://svacer.ispras.ru/releases/svacer-release-6-0-1/svacer_release-6-0-1.zip zip]([https://svacer.ispras.ru/releases/svacer-release-6-0-1/svacer_release-6-0-1.zip.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-6-0-1/svacer_6.0-1_amd64.deb deb]([https://svacer.ispras.ru/releases/svacer-release-6-0-1/svacer_6.0-1_amd64.deb.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-6-0-1/svacer-6.0-1.x86_64.rpm rpm]([https://svacer.ispras.ru/releases/svacer-release-6-0-1/svacer-6.0-1.x86_64.rpm.md5 md5])<br />
|-<br />
| [[Changelog#Release 6-0-0|6.0.0]]<br />
| [https://svacer.ispras.ru/releases/svacer-release-6-0-0/svacer_release-6-0-0.zip zip]([https://svacer.ispras.ru/releases/svacer-release-6-0-0/svacer_release-6-0-0.zip.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-6-0-0/svacer_6.0-0_amd64.deb deb]([https://svacer.ispras.ru/releases/svacer-release-6-0-0/svacer_6.0-0_amd64.deb.md5 md5]); [https://svacer.ispras.ru/releases/svacer-release-6-0-0/svacer-6.0-0.x86_64.rpm rpm]([https://svacer.ispras.ru/releases/svacer-release-6-0-0/svacer-6.0-0.x86_64.rpm.md5 md5])<br />
|}<br />
<br />
Более старые релизы — в [https://nextcloud.ispras.ru/index.php/s/x4r4cMJAMr5RZtd?path=%2F nextcloud]<br />
<br />
=== FAQ ===<br />
* [https://gitlab.ispras.ru/svace/svace-support/-/wikis/home Документация на статический анализатор Svace]<br />
* [[Help:Introduction#Системные требования|Системные требования]]<br />
* [[Примеры использования хуков#Создание кейсов в системах отслеживания ошибок|Создание из Svacer кейсов в Gitlab, Jira, Redmine]]<br />
* Public REST API <br />
:* [[Help:Public API#Примеры использования public REST API|Примеры использования]]<br />
:* [https://gitlab.ispras.ru/svacer-public Репозитории с примерами на Python и Go] <br />
:* [https://svacer-demo.ispras.ru/api/public/swagger/ Спецификация OpenAPI]<br />
* [https://t.me/+6pvgZ0oveNVhOTc6 Группа технической поддержки в Telegram]<br />
<br />
=== Демо ===<br />
Попробуйте Svacer в действии на демо-сервере: https://svacer-demo.ispras.ru<br />
* admin / svacer_admin_31415 — логин / пароль администратора<br />
* user / user — логин / пароль пользователя<br />
<br />
Можете делать там что угодно, каждую ночь сервер восстанавливается до изначального состояния.</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=1975Help:XSvacer:Webide2024-06-10T10:32:59Z<p>M.vinogradov: </p>
<hr />
<div>= Поддержка среды разработки Theia IDE =<br />
'''Примечание:''' данная функциональность входит в набор расширений XSvacer.<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске svacer'а.<br />
<br />
'''Примечание:''' при запуске функциональности <code style="white-space: pre;">webide</code> также будет запущена функциональность <code style="white-space: pre;">[[Help:XSvacer:Docker|docker]]</code>.<br />
<br />
При активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов;<br />
* в пользовательском интерфейсе на вкладке "Информация о снимке" появляется кнопка "Открыть в IDE";<br />
* устанавливается подключение к хосту docker'а, на котором будут запускаться контейнеры с экземплярами IDE.<br />
<br />
=== Быстрый запуск функциональности с настройками по умолчанию ===<br />
<br />
Для того, чтобы начать пользоваться функциональностью запуска IDE без изменения конфигурационных параметров, нужно выполнить следующие действия:<br />
# Настройка доступа к docker-хосту:<br />
## Запустить docker со настройками по умолчанию (dockerd должен слушать unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code> - https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option);<br />
## Проверить, что у пользователя под которым будет запускаться svacer есть доступ к unix-сокету docker-хоста <code style="white-space: pre;">unix:///var/run/docker.sock</code> - https://docs.docker.com/engine/install/linux-postinstall/;<br />
# Настроить права доступа у пользователей, которые смогут запускать IDE: требуются разрешения на проект/ветку <code style="white-space: pre;">"Просмотр маркеров"</code> и <code style="white-space: pre;">"Экспорт разметки"</code>;<br />
# Перезапустить svacer с флагом <code style="white-space: pre;">--xsvacer.features webide</code>.<br />
# ''Опционально.'' Для ускорения первого запуска IDE:<br />
## Скачать архив с docker-образом: https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar;<br />
## Загрузить docker-образ из архива на docker-хост: <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code>;<br />
<br />
После этого у пользователей с указанными правами должна появиться кнопка "Открыть в IDE" на панели с информацией о снимке.<br />
<br />
'''Внимание!''' IDE с исходным подом снимков будут запускаться в новых вкладках браузера.<br />
При этом зачастую все браузеры блокируют автоматическое открытие вкладки и показывают соответствующее предупреждение. Например, в firefox:<br />
[[File:Firefox popup notification ru.png|x25px]]<br />
В таком случае нужно дать разрешение на открытие вкладки с IDE:<br />
[[File:Firefox popup notification expanded ru.png|x106px]]<br />
<br />
При необходимости изменения настроек подключения к docker-хосту:<br />
# скопировать [[Help:XSvacer:Docker#Конфигурация_по_умолчанию|конфигурацию docker по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла <code>svacer.cfg</code>;<br />
# внести требуемые изменения в конфигурацию раздела <code>xsvacer/docker</code>.<br />
<br />
При необходимости изменения настроек запуска IDE:<br />
# скопировать [[#Конфигурация_по_умолчанию|конфигурацию webide по умолчанию]] в раздел <code>xsvacer</code> конфигурационного файла <code>svacer.cfg</code>;<br />
# внести требуемые изменения в конфигурацию раздела <code>xsvacer/webide</code>.<br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске svacer'а указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В конфигурации функциональности <code style="white-space: pre;">[[Help:XSvacer:Webide#Конфигурация|xsvacer/webide/theia]]</code> есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE;<br />
# У пользователя svacer имеются разрешения <code style="white-space: pre;">"Просмотр маркеров"</code> и <code style="white-space: pre;">"Экспорт разметки"</code> на проект, в котором находится снимок, для которого нужно запустить IDE.<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка <code style="white-space: pre;">"Открыть в IDE"</code> (<code style="white-space: pre;">"Open in IDE"</code>).<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>.<br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается;<br />
#** Если IDE недоступна: продолжается процесс запуска. IDE будет ''перезапущена'';<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code>;<br />
# Исходный код снимка скачивается в "корневую папку снимка";<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sariffiletemplate</code>;<br />
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>:<br />
##* Если docker-образ отсутствует - он будет загружен на хост;<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен;<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code style="white-space: pre;">running</code> - процесс запуска IDE продолжается;<br />
##** в статусе <code style="white-space: pre;">created</code>,<code style="white-space: pre;">exited</code> или <code style="white-space: pre;">paused</code> - контейнер будет запущен;<br />
##** в других статусах - вернётся соответствующая ошибка и процесс запуска IDE прервётся;<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>:<br />
#* Если за отведённое время ответ от IDE получен - процесс запуска завершается;<br />
#* Если ответ не получен - вернётся ошибка <code style="white-space: pre;">ide not ready</code>.<br />
<br />
'''Внимание!''' При возникновении ошибки на одном из этапов запуска IDE артефакты, созданные на предыдущих этапах, останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
'''Внимание!''' Причиной возникновения ошибки <code style="white-space: pre;">ide not ready</code> может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>.<br />
В случае возникновения ошибки <code style="white-space: pre;">ide not ready</code> рекомендуется попробовать повторно запустить IDE через короткий промежуток времени.<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется:<br />
1. проверить сетевую доступность docker-хоста;<br />
2. проверить настройки биндинга docker-контейнера c IDE - <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code>. Контейнер должен быть подключён к доступному сетевому интерфейсу;<br />
3. проверить настройки фаервола на docker-хосте.<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с "префиксом" <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code>.<br />
<br />
Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
: <code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
: <code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/socket.io/?...</nowiki></code><br />
: <code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
'''Примечание:''' для запуска IDE в окне браузера нужно указать адрес <code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code>. '''Завершающий слеш обязателен!'''<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">DELETE /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>.<br />
<br />
В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
'''Внимание!''' По умолчанию установлен параметр конфигурации <code style="white-space: pre;">xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true</code>. Это означает, что после остановки docker-контейнер будет автоматически удалён.<br />
Чтобы изменить это поведение, настройка <code style="white-space: pre;">xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove</code> должна быть установлена в <code style="white-space: pre;">false</code> '''на момент запуска docker-контейнера IDE'''. Это можно сделать, например, установив значение переменной окружения <code style="white-space: pre;">XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false</code>.<br />
'''!!!Сейчас установка <code style="white-space: pre;">autoremove: false</code> вызывает ошибку запуска svacer!!! Не используйте данную настройку до исправления.'''<br />
<br />
'''Примечание!''' При корректной остановке (например <code style="white-space: pre;">SIGTERM</code>) svacer автоматически остановит все запущенные docker-контейнеры IDE<br />
<br />
=== Подключение к IDE после некорректного завершениея svacer ===<br />
<br />
При запуске svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах.<br />
<br />
При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке svacer'а все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
'''Внимание!''' На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE снимками:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание <br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> - идентификатор IDE<br />
:<code style="white-space: pre;">name</code> - название IDE<br />
:<code style="white-space: pre;">order</code> - порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка. <br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> - идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
Доступные действия:<br />
* <code style="white-space: pre;">update_markup</code> - обновление предупреждений и разметки (sarif-файла)<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> - действие<br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например, для <code style="white-space: pre;">default</code>-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code style="white-space: pre;">svacer.cfg</code>.<br />
<br />
Раздел конфигурации для управления функциональностью - <code style="white-space: pre;">xsvacer/webide</code>.<br />
<br />
Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
'''Внимание!''' Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому помимо настройки функциональности в разделе <code style="white-space: pre;">xsvacer/webide</code> необходимо также настроить доступ к docker-хосту в разделе <code style="white-space: pre;">xsvacer/docker</code> ([[Help:XSvacer:Docker]]). В противном случае функциональность webide не сможет работать корректно.<br />
<br />
'''Примечание:''' в случае отсутствия файла <code style="white-space: pre;">svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]]<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
'''Внимание!''' На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации <code style="white-space: pre;">default</code>) <br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0 <br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0) <br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на машине со svacer'ом<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources <br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на хосте docker'а. Нужен при использовании удалённого docker-хоста, т.к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
| <br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker'а. По умолчанию <code style="white-space: pre;">"/"</code>.<br />
| <br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|"<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif" <br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только "стандартный" менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
| <br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default <br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
| <br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker'а, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default <br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|"theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>" <br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список "меток" docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer <br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
| <br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint <br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|1.46.0.sarif.clang <br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост.<br />
* <code style="white-space: pre;">repository</code> - будет вызван <code style="white-space: pre;">docker pull</code> образа <code style="white-space: pre;">{image/name}:{image/tag}</code><br />
* <code style="white-space: pre;">file</code> - будет вызван <code style="white-space: pre;">docker load</code> с url'ом <code style="white-space: pre;">image/sourcefileurl</code><br />
|file <br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|Url откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
Url может содержать:<br />
- путь к локальному файлу: схема <code style="white-space: pre;">file://</code><br />
- http/https-адрес: схема <code style="white-space: pre;">http://</code> или <code style="white-space: pre;">https://</code><br />
|https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar <br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
| <br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70<br />
| <br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki> <br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379<br />
| <br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true <br />
|-<br />
|docker/container/hostconfig/portbindings<br />
|map<br />
|<br />
|<br />
"3000/tcp": <br />
- hostport: 0 <br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104<br />
| <br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
| <br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10 <br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms <br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code>:<br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sariffiletemplate: "<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang<br />
sourcetype: file<br />
sourcefileurl: https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
'''Внимание!''' По умолчанию используется docker-хост с идентификатором <code style="white-space: pre;">default</code>. Согласно настройке этого хоста, по умолчанию предполагается взаимодействие с докером через unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code>. Соответственно пользователь, под которым запускается svacer должен иметь доступ к этому сокету (https://docs.docker.com/engine/install/linux-postinstall/).<br />
<br />
'''Внимание!''' При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле <code style="white-space: pre;">svacer.cfg</code> будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения <code style="white-space: pre;">XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code>.<br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске svacer'а:<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в "корневые папки", заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code>;<br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code>;<br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code>;<br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code>;<br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code>;<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code>;<br />
#*: метки с названиями <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>;<br />
# При использовании rootless-хоста docker'а будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста]].<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр <code style="white-space: pre;">xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl</code> содержит значение <code style="white-space: pre;">https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar</code>. По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т.к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго.<br />
<br />
Для ускорения первого запуска IDE докер образ можно загрузить на хост docker'а вручную. Для этого необходимо:<br />
# Скачать файл архива;<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code>;<br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [[https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0|1.46.0]]<br />
<br />
При этом была изменена компоновка расширений theia (результат выполнения <code style="white-space: pre;">git diff</code>):<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "ms-sarifvscode.sarif-viewer": "https://open-vsx.org/api/MS-SarifVSCode/sarif-viewer/3.4.2/file/MS-SarifVSCode.sarif-viewer-3.4.2.vsix"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа: <br />
<pre style="white-space: pre;"><br />
docker build -t theia-blueprint:1.46.0.sarif.clang -f browser.Dockerfile .<br />
</pre><br />
<br />
Команда экспорта docker-образа:<br />
<pre style="white-space: pre;"><br />
docker image save theia-blueprint:1.46.0 > /path/to/tar/theia-blueprint.1.46.0.docker.command.tar<br />
</pre><br />
<br />
== Известные проблемы ==<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.<br />
<br />
В 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, либо приложение размещалось на <code style="white-space: pre;">localhost</code>.<br />
<br />
Поэтому для решения данной проблемы svacer должен открываться по https или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=File:Firefox_popup_notification_ru.png&diff=1974File:Firefox popup notification ru.png2024-06-10T10:07:21Z<p>M.vinogradov: M.vinogradov uploaded a new version of File:Firefox popup notification ru.png</p>
<hr />
<div>Нотификация firefox если сайт пытается открыть новую вкладку</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=File:Firefox_popup_notification_expanded_ru.png&diff=1973File:Firefox popup notification expanded ru.png2024-06-10T10:01:49Z<p>M.vinogradov: </p>
<hr />
<div>Развёрнутая нотификация firefox если сайт пытается открыть новую вкладку</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=File:Firefox_popup_notification_ru.png&diff=1972File:Firefox popup notification ru.png2024-06-10T10:00:02Z<p>M.vinogradov: </p>
<hr />
<div>Нотификация firefox если сайт пытается открыть новую вкладку</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Docker&diff=1971Help:XSvacer:Docker2024-06-07T11:59:35Z<p>M.vinogradov: </p>
<hr />
<div>= Управление docker-контейнерами =<br />
'''Примечание:''' данная функциональность входит в набор расширений XSvacer.<br />
<br />
Данная функциональность предназначена для управления docker-контейнерами, содержащими компоненты XSvacer.<br />
<br />
Управление docker-контейнерами осуществляется с помощью взаимодействия с docker-хостом с использованием [https://docs.docker.com/engine/api/latest/ REST API].<br />
<br />
Возможны два сценария использования docker'а:<br />
# Подключение к существующему ("внешнему") docker-хосту;<br />
# Запуск управляемого svacer'ом [https://docs.docker.com/go/rootless/ rootless-хоста].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code>--xsvacer.features docker</code> при запуске svacer'а.<br />
<br />
'''Примечание:''' на базе данной функциональности осуществляется запуск компонентов других расширений XSvacer. В таком случае её необязательно запускать явно: она будет запущена, если будет запущена зависимая функциональность.<br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code>svacer.cfg</code>.<br />
<br />
Раздел конфигурации для управления функциональностью - <code>xsvacer/docker</code>.<br />
<br />
Раздел содержит перечисление настроек подключаемых хостов docker'а <code>xsvacer/docker/hosts</code>, на которые в дальнейшем будут ссылаться зависимые функциональности. Каждое поле в <code>xsvacer/docker/hosts/...</code> является идентификатором подключения и содержит его конфигурацию.<br />
<br />
xsvacer:<br />
docker:<br />
hosts:<br />
dockerhost1:<br />
type: ...<br />
host: ...<br />
disabled: false<br />
...<br />
dockerhost2:<br />
...<br />
<br />
dependentFeature1:<br />
...<br />
docker:<br />
hostid: dockerhost1<br />
...<br />
dependentFeature2:<br />
...<br />
docker:<br />
hostid: dockerhost2<br />
...<br />
<br />
'''Примечание:''' в случае отсутствия файла <code>svacer.cfg</code> или отсутствии раздела <code>xsvacer/docker</code> будет использоваться конфигурация по умолчанию (см. ниже)<br />
<br />
=== Общие параметры docker-хостов ===<br />
{| class="wikitable"<br />
|+<br />
!Название <br />
!Тип данных<br />
!Описание<br />
|-<br />
|<code>type</code><br />
|enum: <code>external</code>, <code>managed</code>, <code>remote</code><br />
|Тип подключаемого docker-хоста:<br />
<br />
* <code>external</code> - "внешний" docker-хост<br />
* <code>managed</code> - "управляемый" rootless-хост<br />
* <code>remote</code> - аналогичен <code>external</code>, но <code>host</code> должен быть задан<br />
|-<br />
|<code>hostd</code><br />
|url<br />
|Url docker-хоста<br />
|-<br />
|<code>disabled</code><br />
|bool<br />
|Конфигурация хоста неактивна<br />
Неактивная конфигурация не может использоваться в других функциональностях<br />
|}<br />
<br />
=== Использование существующего ("внешнего") docker-хоста ===<br />
Данный способ взаимодействия предполагает подключение к существующему хосту docker'а.<br />
<br />
Доступные варианты подключения:<br />
# К локальному хосту через unix-сокет;<br />
# К удалённому хосту по ssh;<br />
# К удалённому хосту по http;<br />
# К к удалённому хосту по https.<br />
<br />
Для использования "внешнего" хоста docker'а в конфигурационном файле нужно указать <code>type: external</code>, а также задать адрес хоста, соответствующий типу подключения:<br />
docker:<br />
hosts:<br />
default:<br />
type: external<br />
host: "unix:///path/to/docker.sock"<br />
remote1:<br />
type: external<br />
host: "<nowiki>ssh://docker-user@docker-host</nowiki>"<br />
remote2:<br />
type: external<br />
host: "<nowiki>http://docker-host-ip-address:2375</nowiki>"<br />
remote3:<br />
type: external<br />
host: "<nowiki>https://docker-host-ip-address:2376</nowiki>"<br />
clienttls: ...<br />
Если параметр <code>host</code> не задан, то по умолчанию будет использоваться unix-сокет.<br />
<br />
==== Подключение к локальному хосту через unix-сокет ====<br />
При обычном запуске процесса <code>dockerd</code> взаимодействие с хостом осуществляется с помощью unix-сокета <code>unix:///var/run/docker.sock</code>.<br />
<br />
Доступ к сокету может получить пользователь с правами <code>root</code> или обычный пользователь, входящий в группу <code>docker</code> (https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option).<br />
<br />
Пользователь, под которым запускается svacer, должен иметь права доступа к указанному unix-сокету docker'а (https://docs.docker.com/engine/install/linux-postinstall/).<br />
'''Внимание!''' При отсутствии прав доступа к unix-сокету использование данной функциональности будет приводить к ошибке.<br />
В таком случае можно воспользоваться rootless-хостом (см. ниже).<br />
<br />
Если для взаимодействия с хостом docker'а используется дефолтный unix-сокет <code>unix:///var/run/docker.sock</code>, то в конфигурации поле <code>host</code> можно не указывать:<br />
docker:<br />
hosts:<br />
default:<br />
type: external<br />
<br />
==== Подключение к удалённому хосту по ssh ====<br />
<br />
Чтобы подключиться к удалённому хосту docker'а по ssh, необходимо в поле <code>host</code> указать схему <code>ssh://</code>, реквизиты пользователя и название/адрес docker-хоста:<br />
<br />
docker:<br />
hosts:<br />
default:<br />
type: external<br />
host: "<nowiki>ssh://docker-user@docker-host</nowiki>"<br />
<br />
Указанный пользователь должен иметь возможность подключения по ssh к указанному хосту, а также иметь права доступа к unix-сокету docker'а на удалённом хосте (https://docs.docker.com/engine/security/protect-access/#use-ssh-to-protect-the-docker-daemon-socket)<br />
<br />
==== Подключение к удалённому хосту по http ====<br />
<br />
Чтобы подключиться к удалённому хосту docker'а по http, необходимо в поле <code>host</code> указать схему <code>http://</code> и адрес docker-хоста:<br />
docker:<br />
hosts:<br />
default:<br />
type: external<br />
host: "<nowiki>http://docker-host-ip-address:port</nowiki>"<br />
<br />
'''Внимание!''' Данный тип подключения является *небезопасным*, т.к. при использовании API docker'а не производится шифрование сетевого трафика и аутентификация клиента при доступе к docker'у. Чтобы создать безопасное сетевое соединение необходимо использовать подключение по https (tls) (см. ниже)<br />
<br />
==== Подключение к удалённому хосту по https (tls) ====<br />
<br />
Docker-хост может предоставлять доступ по https (https://docs.docker.com/engine/security/protect-access/#use-tls-https-to-protect-the-docker-daemon-socket).<br />
<br />
В таком случае для доступа к API необходимо иметь сертификат удостоверяющего центра, клиентский ключ и сертификат.<br />
<br />
В конфигурационном файле пути к ключам указываются в поле <code>xsvacer/docker/{docker-host-id}/clienttls</code>:<br />
docker:<br />
hosts:<br />
default:<br />
type: external<br />
host: "<nowiki>https://docker-host-ip-address:2376</nowiki>"<br />
clienttls:<br />
ca: "/path/to/ca.pem"<br />
cert: "/path/to/cert.pem"<br />
key: "/path/to/key.pem"<br />
<br />
===== Специфичные настройки для подключения к https хосту =====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|clienttls/<br />
|map<br />
|Настройки TLS <br />
|-<br />
|clienttls/ca<br />
|url<br />
|Путь к файлу сертификата удостоверяющего центра <br />
|-<br />
|clienttls/cert<br />
|url<br />
|Путь к клиентскому сертификату <br />
|-<br />
|clienttls/key<br />
|url<br />
|Путь к клиентскому ключу <br />
|}<br />
<br />
==== Памятка при использовании подключения к удалённым хостам ====<br />
<br />
'''Примечание:''' если используется подключения к удалённому хосту docker'а, в настройке биндингов контейнеров необходимо указывать ip-адрес доступного сетевого интерфейса хоста, т.к. при привязке контейнера к 0.0.0.0 на машине хоста контейнеры будут недоступны снаружи.<br />
<br />
=== Запуск "управляемого" rootless-хоста ===<br />
<br />
В случае отсутствия доступного docker-хоста, либо если не хочется его загромождать контейнерами svacer'а, предусмотрена возможность запуска "управляемого" rootless-хоста, не требующего настройки дополнительных прав для пользователя, под которым запускается svacer (https://docs.docker.com/engine/security/rootless/).<br />
<br />
Управление (запуск и остановка) rootless-хостом будет осуществлять svacer.<br />
<br />
'''Внимание!''' Доступно только для linux'а.<br />
<br />
Для использования данного rootless-хоста в конфигурационном файле для хоста нужно указать <code>type: managed</code>.<br />
docker:<br />
hosts:<br />
local:<br />
type: managed<br />
...<br />
<br />
==== Специфичные настройки для rootless-хоста ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
|-<br />
|managed/<br />
|map<br />
|параметры запуска rootless-хоста <br />
|-<br />
|managed/executable<br />
|string<br />
|исполняемый файл. Должен быть доступен в $PATH или содержать абсолютный путь <br />
''формат'': имя исполняемого фала, доступного через переменную <code>$PATH</code> <br />
<br />
''или'': абсолютный путь до исполняемого файла<br />
|-<br />
|managed/env<br />
|[]string<br />
|список переменных окружения для процесса rootless-хоста <br />
формат: <code>"НАЗВАНИЕ_ПЕРЕМЕННОЙ=значение переменной"</code> <br />
|-<br />
|managed/args<br />
|[]string<br />
|список аргументов запуска rootless-хоста <br />
''формат'': <code>"--название-аргумента=значение-аргумента"</code><br />
<br />
''или'': <code>"--название-аргумента", "значение-аргумента"</code> <br />
<br />
''или'': <code>"--название-флага"</code><br />
|-<br />
|managed/loglevel<br />
|string<br />
|уровень логирования, на котором будут записываться stdout и stderr процесса rootless-хоста <br />
|-<br />
|managed/logprefix<br />
|string<br />
|префикс в логе, которым будут помечаться записи из stdout и stderr процесса rootless-хоста <br />
|-<br />
|managed/healthcheck<br />
|map<br />
|параметры проверки доступности rootless-хоста <br />
|-<br />
|managed/healthcheck/interval<br />
|golang duration string<br />
|интервал проверки <br />
|-<br />
|managed/healthcheck/retries<br />
|int<br />
|количество попыток проверки до ошибки доступности <br />
|}<br />
<br />
В значениях <code>managed/env</code> и <code>managed/args</code> можно использовать имена переменных окружения в формате <code>${НАЗВАНИЕ_ПЕРЕМЕННОЙ}</code>.<br />
<br />
==== Рекомендуемая конфигурация rootless-хоста ====<br />
<br />
При запуске <code>dockerd-rootless.sh</code> без параметров папки с артефактами docker'а создаются во вложенных папках внутри <code>/run/user/$UID/</code>.<br />
Для лучшей локализации артефактов svacer'а рекомендуется использовать следующие настройки для rootless-хоста:<br />
docker:<br />
hosts:<br />
local:<br />
type: managed<br />
host: "unix://${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.sock"<br />
<br />
managed:<br />
executable: "dockerd-rootless.sh"<br />
env:<br />
- "DOCKERD_ROOTLESS_ROOTLESSKIT_STATE_DIR=${USER_CACHE_DIR}/svacer-docker-host/state-dir/"<br />
args:<br />
- "--data-root=${USER_CACHE_DIR}/svacer-docker-host/data-root/"<br />
- "--exec-root=${USER_CACHE_DIR}/svacer-docker-host/exec-root/"<br />
- "--pidfile=${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.pid"<br />
logLevel: info<br />
logPrefix: "DOCKER HOST: "<br />
healthCheck:<br />
interval: 1s<br />
retries: 10<br />
<br />
Здесь вместо <code>${USER_CACHE_DIR}</code> будет подставлен путь <code>$HOME/.cache</code> на unix-подобных системах или <code>%LocalAppData%</code> на windows.<br />
<br />
При таких настройках все артефакты хоста docker'а будут храниться внутри папки <code>${USER_CACHE_DIR}/svacer-docker-host</code>.<br />
<br />
=== Использование "неуправляемого" rootless-хоста ===<br />
<br />
В случае необходимости управления rootless-хостом без участия svacer'а, его можно запустить отдельно. Например, командой:<br />
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<br />
<br />
В таком случае подключиться к данному хосту можно как к "внешнему" (<code>type: external</code>), указав адрес unix-сокета. Например:<br />
docker:<br />
hosts:<br />
unmanaged:<br />
type: external<br />
host: "unix:///home/${USER}/.cache/svacer-docker-host/svacer-docker.sock"<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная конфигурация применяется по умолчанию, если в конфигурационном файле svacer.cfg отсутствует раздел <code>xsvacer/docker</code>:<br />
docker:<br />
hosts:<br />
default:<br />
type: external<br />
local:<br />
type: managed<br />
host: "unix://${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.sock"<br />
disabled: true<br />
<br />
managed:<br />
executable: "dockerd-rootless.sh"<br />
env:<br />
- "DOCKERD_ROOTLESS_ROOTLESSKIT_STATE_DIR=${USER_CACHE_DIR}/svacer-docker-host/state-dir/"<br />
args:<br />
- "--data-root=${USER_CACHE_DIR}/svacer-docker-host/data-root/"<br />
- "--exec-root=${USER_CACHE_DIR}/svacer-docker-host/exec-root/"<br />
- "--pidfile=${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.pid"<br />
logLevel: info<br />
logPrefix: "DOCKER HOST: "<br />
healthCheck:<br />
interval: 1s<br />
retries: 10<br />
<br />
'''Внимание!''' При наличии раздела <code>xsvacer/docker</code> в конфигурационном файле <code>svacer.cfg</code> будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения <code>XSVACER_DOCKER_HOSTS_{id хоста}[_параметр]={значение параметра}</code>.<br />
<br />
Например, для активации rootless-хоста <code>xsvacer/hosts/local</code> можно указать такие значения переменных окружения при запуске svacer'а:<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
<br />
== Известные проблемы ==<br />
<br />
=== rootless-хост продолжает работать при некорректной остановке svacer'а ===<br />
<br />
При некорректном завершении работы svacer'а (например, при получении сигнала <code>SIGKILL</code>) процесс rootless-хоста останется запущенным в системе.<br />
<br />
При этом svacer потеряет возможность управления (запуска/остановки) этого процесса.<br />
<br />
При последующем запуске 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><br />
<br />
При этом, если настройки не менялись, зависимые функциональности смогут получить доступ к "неконтролируемому" rootless-хосту, т.к. адрес unix-сокета хоста известен.<br />
<br />
Процесс "неконтролируемого" rootless-хоста при необходимости может быть остановлен вручную. Например с помощью отправки сигнала <code>SIGTERM</code>.</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=1970Help:XSvacer:Webide2024-06-07T11:58:57Z<p>M.vinogradov: </p>
<hr />
<div>= Поддержка среды разработки Theia IDE =<br />
'''Примечание:''' данная функциональность входит в набор расширений XSvacer.<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске svacer'а.<br />
<br />
'''Примечание:''' при запуске функциональности <code style="white-space: pre;">webide</code> также будет запущена функциональность <code style="white-space: pre;">[[Help:XSvacer:Docker|docker]]</code>.<br />
<br />
При активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра исходного кода снимков проектов;<br />
* в пользовательском интерфейсе появляется кнопка "Открыть в IDE";<br />
* устанавливается подключение к хосту docker'а, на котором будут запускаться контейнеры с экземплярами IDE.<br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске svacer'а указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В конфигурации функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> ([[Help:XSvacer:Webide#Конфигурация]]) есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE;<br />
# У пользователя svacer имеются разрешения <code style="white-space: pre;">"Просмотр маркеров"</code> (<code style="white-space: pre;">"Read markers"</code>) и <code style="white-space: pre;">"Экспорт разметки"</code> (<code style="white-space: pre;">"Export markup"</code>) на проект, в котором находится снимок, для которого нужно запустить IDE.<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка <code style="white-space: pre;">"Открыть в IDE"</code> (<code style="white-space: pre;">"Open in IDE"</code>).<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>.<br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступности IDE (отвечает на запросы):<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается;<br />
#** Если IDE недоступна: продолжается процесс запуска. IDE будет ''перезапущена'';<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code>;<br />
# Исходный код снимка скачивается в "корневую папку снимка";<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sariffiletemplate</code>;<br />
# Производится настройка и запуск docker-контейнера в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>:<br />
##* Если docker-образ отсутствует - он будет загружен на хост;<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен;<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code style="white-space: pre;">running</code> - процесс запуска IDE продолжается;<br />
##** в статусе <code style="white-space: pre;">created</code>,<code style="white-space: pre;">exited</code> или <code style="white-space: pre;">paused</code> - контейнер будет запущен;<br />
##** в других статусах - вернётся соответствующая ошибка и процесс запуска IDE прервётся;<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>:<br />
#* Если за отведённое время ответ от IDE получен - процесс запуска завершается;<br />
#* Если ответ не получен - вернётся ошибка <code style="white-space: pre;">ide not ready</code>.<br />
<br />
'''Внимание!''' При возникновении ошибки на одном из этапов запуска IDE артефакты, созданные на предыдущих этапах, останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
'''Внимание!''' Причиной возникновения ошибки <code style="white-space: pre;">ide not ready</code> может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>.<br />
В случае возникновения ошибки <code style="white-space: pre;">ide not ready</code> рекомендуется попробовать повторно запустить IDE через короткий промежуток времени.<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера при подключении к удалённому docker-хосту. В таком случае рекомендуется:<br />
1. проверить сетевую доступность docker-хоста;<br />
2. проверить настройки биндинга docker-контейнера c IDE - <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code>. Контейнер должен быть подключён к доступному сетевому интерфейсу;<br />
3. проверить настройки фаервола на docker-хосте.<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с "префиксом" <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code>.<br />
<br />
Все запросы, направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code>, будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
: <code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
: <code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/socket.io/?...</nowiki></code><br />
: <code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
'''Примечание:''' для запуска IDE в окне браузера нужно указать адрес <code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code>. '''Завершающий слеш обязателен!'''<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">DELETE /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>.<br />
<br />
В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
'''Внимание!''' По умолчанию установлен параметр конфигурации <code style="white-space: pre;">xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true</code>. Это означает, что после остановки docker-контейнер будет автоматически удалён.<br />
Чтобы изменить это поведение, настройка <code style="white-space: pre;">xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove</code> должна быть установлена в <code style="white-space: pre;">false</code> '''на момент запуска docker-контейнера IDE'''. Это можно сделать, например, установив значение переменной окружения <code style="white-space: pre;">XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false</code>.<br />
'''!!!Сейчас установка <code style="white-space: pre;">autoremove: false</code> вызывает ошибку запуска svacer!!! Не используйте данную настройку до исправления.'''<br />
<br />
'''Примечание!''' При корректной остановке (например <code style="white-space: pre;">SIGTERM</code>) svacer автоматически остановит все запущенные docker-контейнеры IDE<br />
<br />
=== Подключение к IDE после некорректного завершениея svacer ===<br />
<br />
При запуске svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах.<br />
<br />
При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке svacer'а все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
'''Внимание!''' На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE снимками:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание <br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> - идентификатор IDE<br />
:<code style="white-space: pre;">name</code> - название IDE<br />
:<code style="white-space: pre;">order</code> - порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка. <br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> - идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
Доступные действия:<br />
* <code style="white-space: pre;">update_markup</code> - обновление предупреждений и разметки (sarif-файла)<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> - действие<br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например, для <code style="white-space: pre;">default</code>-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code style="white-space: pre;">svacer.cfg</code>.<br />
<br />
Раздел конфигурации для управления функциональностью - <code style="white-space: pre;">xsvacer/webide</code>.<br />
<br />
Раздел содержит перечисление доступных конфигураций запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
'''Внимание!''' Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому помимо настройки функциональности в разделе <code style="white-space: pre;">xsvacer/webide</code> необходимо также настроить доступ к docker-хосту в разделе <code style="white-space: pre;">xsvacer/docker</code> ([[Help:XSvacer:Docker]]). В противном случае функциональность webide не сможет работать корректно.<br />
<br />
'''Примечание:''' в случае отсутствия файла <code style="white-space: pre;">svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code> будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]]<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
'''Внимание!''' На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например, идентификатор по номеру используемой версии IDE:<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации <code style="white-space: pre;">default</code>) <br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0 <br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0) <br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на машине со svacer'ом<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources <br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке, содержащей исходные коды снимков на хосте docker'а. Нужен при использовании удалённого docker-хоста, т.к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
| <br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker'а. По умолчанию <code style="white-space: pre;">"/"</code>.<br />
| <br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|"<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif" <br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только "стандартный" менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
| <br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default <br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
| <br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker'а, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default <br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|"theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>" <br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список "меток" docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer <br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
| <br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint <br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|1.46.0.sarif.clang <br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост.<br />
* <code style="white-space: pre;">repository</code> - будет вызван <code style="white-space: pre;">docker pull</code> образа <code style="white-space: pre;">{image/name}:{image/tag}</code><br />
* <code style="white-space: pre;">file</code> - будет вызван <code style="white-space: pre;">docker load</code> с url'ом <code style="white-space: pre;">image/sourcefileurl</code><br />
|file <br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|Url откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
Url может содержать:<br />
- путь к локальному файлу: схема <code style="white-space: pre;">file://</code><br />
- http/https-адрес: схема <code style="white-space: pre;">http://</code> или <code style="white-space: pre;">https://</code><br />
|https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar <br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
| <br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70<br />
| <br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki> <br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379<br />
| <br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true <br />
|-<br />
|docker/container/hostconfig/portbindings<br />
|map<br />
|<br />
|<br />
"3000/tcp": <br />
- hostport: 0 <br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104<br />
| <br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
| <br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10 <br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms <br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
=== Конфигурация по умолчанию ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code>:<br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
docker:<br />
hosts:<br />
default: # конфигурация docker-хоста<br />
type: external<br />
...<br />
<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sariffiletemplate: "<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang<br />
sourcetype: file<br />
sourcefileurl: https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
'''Внимание!''' По умолчанию используется docker-хост с идентификатором <code style="white-space: pre;">default</code>. Согласно настройке этого хоста, по умолчанию предполагается взаимодействие с докером через unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code>. Соответственно пользователь, под которым запускается svacer должен иметь доступ к этому сокету (https://docs.docker.com/engine/install/linux-postinstall/).<br />
<br />
'''Внимание!''' При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле <code style="white-space: pre;">svacer.cfg</code> будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения <code style="white-space: pre;">XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code>.<br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост можно указать такие значения переменных окружения при запуске svacer'а:<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в "корневые папки", заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code>;<br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code>;<br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code>;<br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code>;<br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code>;<br />
#*: метки, перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code>;<br />
#*: метки с названиями <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>;<br />
# При использовании rootless-хоста docker'а будут созданы папки согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста]].<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр <code style="white-space: pre;">xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl</code> содержит значение <code style="white-space: pre;">https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar</code>. По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т.к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго.<br />
<br />
Для ускорения первого запуска IDE докер образ можно загрузить на хост docker'а вручную. Для этого необходимо:<br />
# Скачать файл архива;<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/theia-blueprint.1.46.0.sarif.clang.tar</code>;<br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [[https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0|1.46.0]]<br />
<br />
При этом была изменена компоновка расширений theia (результат выполнения <code style="white-space: pre;">git diff</code>):<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "ms-sarifvscode.sarif-viewer": "https://open-vsx.org/api/MS-SarifVSCode/sarif-viewer/3.4.2/file/MS-SarifVSCode.sarif-viewer-3.4.2.vsix"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа: <br />
<pre style="white-space: pre;"><br />
docker build -t theia-blueprint:1.46.0.sarif.clang -f browser.Dockerfile .<br />
</pre><br />
<br />
Команда экспорта docker-образа:<br />
<pre style="white-space: pre;"><br />
docker image save theia-blueprint:1.46.0 > /path/to/tar/theia-blueprint.1.46.0.docker.command.tar<br />
</pre><br />
<br />
== Известные проблемы ==<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла, содержащего предупреждения анализатора и разметку, используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина со списком предупреждений анализатора.<br />
<br />
В 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, либо приложение размещалось на <code style="white-space: pre;">localhost</code>.<br />
<br />
Поэтому для решения данной проблемы svacer должен открываться по https или быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer&diff=1969Help:XSvacer2024-06-07T11:58:18Z<p>M.vinogradov: </p>
<hr />
<div>= XSvacer - расширение функциональности svacer =<br />
<br />
Начиная с релиза [[Changelog#Release_9-0-0|9.0.0]] в svacer'е появились "расширенные функции", которые могут быть активированы по требованию.<br />
<br />
Доступные функции:<br />
* [[Help:XSvacer:Webide|webide]] - Среда разработки на базе [https://theia-ide.org/ Theia IDE], с помощью которой можно просматривать исходный код снимка, предупреждения анализатора и разметку.<br />
* [[Help:XSvacer:Docker|docker]] - Вспомогательная функциональность для запуска других компонентов в docker-контейнерах.<br />
<br />
'''Примечание:''' по умолчанию данные функции неактивны. <br />
<br />
'''Примечание:''' функциональность docker будет активирована автоматически, при запуске зависящих от неё функций.<br />
<br />
'''Внимание!''' На данный момент расширенные функции находятся на стадии внедрения. В последующих релизах возможно изменение форматов конфигурации и API взаимодействия с указанными функциями.<br />
<br />
== Активация функций ==<br />
<br />
Активировать функции можно, указав флаг <code>--xsvacer.features feature_name</code> при запуске svacer'а. Флаг можно указать несколько раз, чтобы активировать несколько функций.<br />
<br />
Также список активных функций можно настроить в конфигурационном yaml-файле <code>svacer.cfg</code> в разделе <code>xsvacer.features</code>.<br />
Значением данного ключа является список строк с названиями активируемых функций:<br />
...<br />
xsvacer:<br />
features:<br />
- webide<br />
...<br />
<br />
'''Внимание!''' При установке флага <code>--xsvacer.features</code> список функций, указанный в конфигурационном файле <code>svacer.cfg</code>, будет проигнорирован.</div>M.vinogradovhttps://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Webide&diff=1968Help:XSvacer:Webide2024-06-07T09:01:50Z<p>M.vinogradov: </p>
<hr />
<div>= Поддержка среды разработки Theia IDE =<br />
'''Примечание:''' данная функциональность входит в набор расширений XSvacer.<br />
<br />
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.<br />
<br />
По умолчанию запускается IDE, [[#Информация_о_docker-образе_Theia_IDE|собранная]] на основе [https://theia-ide.org/ Theia IDE].<br />
<br />
== Активация функциональности ==<br />
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features webide</code> при запуске svacer'а.<br />
<br />
'''Примечание:''' при запуске функциональности <code style="white-space: pre;">webide</code> также будет запущена функциональность <code style="white-space: pre;">[[Help:XSvacer:Docker|docker]]</code>.<br />
<br />
Активации функциональности:<br />
* становится доступным REST API управления IDE для просмотра снимков проектов;<br />
* в пользовательском интерфейсе появляется кнопка "Открыть в IDE";<br />
* устанавливается подключение к хосту docker'а, на котором будут запускаться контейнеры с экземплярами IDE.<br />
<br />
== Принцип работы ==<br />
<br />
Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:<br />
# Функциональность активна: при запуске svacer'а указан флаг <code style="white-space: pre;">--xsvacer.features webide</code>;<br />
# В конфигурации функциональности <code style="white-space: pre;">xsvacer/webide/theia</code> ([[Help:XSvacer:Webide#Конфигурация]]) есть хотя бы одна активная (<code style="white-space: pre;">disabled: false</code>) конфигурация IDE;<br />
# У пользователя svacer имеются разрешения <code style="white-space: pre;">"Просмотр маркеров"</code> (<code style="white-space: pre;">"Read markers"</code>) и <code style="white-space: pre;">"Экспорт разметки"</code> (<code style="white-space: pre;">"Export markup"</code>) на проект, в котором находится снимок, для которого нужно запустить IDE.<br />
<br />
В противном случае в пользовательском интерфейсе будет отсутствовать кнопка <code style="white-space: pre;">"Открыть в IDE"</code> (<code style="white-space: pre;">"Open in IDE"</code>)<br />
<br />
=== Запуск IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">POST /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>.<br />
<br />
Последовательность действий, выполняемых при запуске IDE:<br />
<br />
# Производится проверка: была ли уже запущена указанная IDE для указанного снимка:<br />
#* Если запущена: производится проверка доступна ли IDE: отвечает на запросы;<br />
#** Если IDE доступна: действие не требуется. Процесс запуска завершается;<br />
#** Если IDE не доступна: продолжается процесс запуска. IDE будет ''перезапущена'';<br />
# Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot</code>;<br />
# Исходный код снимка скачивается в "корневую папку снимка";<br />
# Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/sariffiletemplate</code>;<br />
# Производится настройка и запуск docker-контейнера, в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker</code>:<br />
## Проверяется наличие на docker-хосте образа IDE, указанного в <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/image</code>:<br />
##* Если docker-образ отсутствует - он будет загружен на хост;<br />
## Проверяется наличие на docker-хосте контейнера с IDE для снимка:<br />
##* Если docker-контейнер не существует, то он будет создан и запущен;<br />
##* Если docker-контейнер существует и находится:<br />
##** в статусе <code style="white-space: pre;">running</code> - процесс запуска IDE продолжается;<br />
##** в статусе <code style="white-space: pre;">created</code>,<code style="white-space: pre;">exited</code> или <code style="white-space: pre;">paused</code> - контейнер будет запущен;<br />
##** в других статусах - вернётся соответствующая ошибка и процесс запуска IDE прервётся;<br />
# После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере, в соответствии с настройками <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>:<br />
#* Если за отведённое время ответ от IDE получен - процесс запуска завершается.<br />
#* Если ответ не получен - вернётся ошибка <code style="white-space: pre;">ide not ready</code>;<br />
<br />
'''Внимание!''' При возникновении ошибки на одном из этапов запуска IDE, артефакты созданные на предыдущих этапах останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.<br />
<br />
'''Внимание!''' Причиной возникновения ошибки <code style="white-space: pre;">ide not ready</code> может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим, процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck</code>.<br />
В случае возникновения ошибки <code style="white-space: pre;">ide not ready</code> рекомендуется попытаться повторно запустить IDE через короткий промежуток времени.<br />
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера, при подключении к удалённому docker-хосту. В таком случае рекомендуется:<br />
1. проверить сетевую доступность docker-хоста;<br />
2. проверить настройки биндинга docker-контейнера c IDE - <code style="white-space: pre;">xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings</code>. Контейнер должен быть подключён к доступному сетевому интерфейсу.<br />
3. проверить настройки фаервола на docker-хосте;<br />
<br />
=== Использование IDE: проксирование запросов ===<br />
<br />
После успешного запуска docker-контейнера IDE станут доступны ресурсы с "префиксом" <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/</code><br />
<br />
Все запросы направленные к ресурсам <code style="white-space: pre;">/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*</code> будут проксироваться в соответствующий контейнер IDE.<br />
<br />
Например, если 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>, то будет происходить проксирование:<br />
: <code style="white-space: pre;"><nowiki>GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/</nowiki></code><br />
: <code style="white-space: pre;"><nowiki>POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET http://docker-host:35353/socket.io/?...</nowiki></code><br />
: <code style="white-space: pre;"><nowiki>GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?...</nowiki></code> &rArr; <code style="white-space: pre;"><nowiki>GET ws://docker-host:35353/socket.io/?...</nowiki></code><br />
<br />
'''Примечание:''' для запуска IDE в окне браузера нужно указать адрес <code style="white-space: pre;"><nowiki>http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/</nowiki></code>. '''Завершающий слеш обязателен!'''<br />
<br />
=== Перезапуск IDE ===<br />
<br />
В процессе работы svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.<br />
<br />
Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.<br />
<br />
Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при [[Help:XSvacer:Webide#Запуск IDE|первоначальном запуске IDE]].<br />
<br />
Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.<br />
<br />
Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку, до устранения причин неработоспособности.<br />
<br />
=== Остановка IDE ===<br />
<br />
Запуск производится путём вызова http-метода <code style="white-space: pre;">DELETE /api/snapshots/{snapshot_id}/ide</code> с телом запроса <code style="white-space: pre;">{"ideId": "идентификатор IDE"}</code>.<br />
<br />
В ходе обработки запроса останавливается docker-контейнер IDE.<br />
<br />
'''Внимание!''' По умолчанию установлен параметр конфигурации <code style="white-space: pre;">xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true</code>. Это означает, что при после остановки docker-контейнер будет автоматически удалён.<br />
Чтобы изменить это поведение, настройка <code style="white-space: pre;">xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove</code> должна быть установлена в <code style="white-space: pre;">false</code> '''на момент запуска docker-контейнера IDE'''. Это можно сделать, например, установив значение переменной окружения <code style="white-space: pre;">XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false</code>.<br />
'''!!!Сейчас установка <code style="white-space: pre;">autoremove: false</code> вызывает ошибку запуска svacer!!! Не используйте данную настройку до исправления'''<br />
<br />
'''Примечание!''' При корректной остановке (например <code style="white-space: pre;">SIGTERM</code>) svacer автоматически остановит все запущенные docker-контейнеры IDE<br />
<br />
=== Подключение к IDE после некорректного завершениея svacer ===<br />
<br />
При запуске svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах.<br />
<br />
При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке svacer'а, все docker-контейнеры IDE будут остановлены.<br />
<br />
== REST API для работы с IDE ==<br />
<br />
'''Внимание!''' На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!<br />
<br />
После активации функциональности становятся доступны http-ресурсы для управления IDE снимками:<br />
<br />
{| class="mw-collapsible mw-collapsed wikitable"<br />
|+ style=white-space:nowrap | REST API управления IDE<br />
|-<br />
!Ресурс<br />
!Описание <br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/ide<br />
</pre><br />
|Получение списка доступных для запуска IDE.<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
[<br />
{<br />
"id": "string",<br />
"name": "string",<br />
"order": 0<br />
}<br />
]<br />
</pre><br />
:<code style="white-space: pre;">id</code> - идентификатор IDE<br />
:<code style="white-space: pre;">name</code> - название IDE<br />
:<code style="white-space: pre;">order</code> - порядковый номер IDE в списке<br />
|-<br />
|<pre style="white-space: pre;"><br />
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}<br />
</pre><br />
|Запрос описания экземпляра IDE, запущенного для снимка. <br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
:<code style="white-space: pre;">ide_id</code> - идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"id": {<br />
"ide_id": {<br />
"ide_type": "string"<br />
"config_id": "string",<br />
},<br />
"snapshot_id": "string"<br />
},<br />
"properties": {<br />
"url": "string"<br />
},<br />
"start_args": {<br />
"snapshot_id": "string",<br />
"user": "string",<br />
"user_id": "string"<br />
}<br />
}<br />
</pre><br />
|-<br />
|<pre style="white-space: pre;"><br />
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Запуск IDE для просмотра исходных кодов снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
'''Ответ:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
|-<br />
|<pre style="white-space: pre;"><br />
PUT /api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Команда управления экземпляром IDE снимка<br />
Доступные действия:<br />
* <code style="white-space: pre;">update_markup</code> - обновление предупреждений и разметки (sarif-файла)<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"action": "string",<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">action</code> - действие<br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide<br />
</pre><br />
|Остановка экземпляра IDE снимка<br />
'''Параметры:'''<br />
:<code style="white-space: pre;">snapshot_id</code> - идентификатор снимка<br />
'''Запрос:'''<br />
<pre style="white-space: pre;"><br />
{<br />
"ideId": "string"<br />
}<br />
</pre><br />
:<code style="white-space: pre;">ideId</code> - идентификатор IDE<br />
'''Ответ:''' пустой<br />
|-<br />
|<pre style="white-space: pre;"><br />
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*<br />
</pre><br />
|Прокси для запросов экземпляра IDE снимка<br />
|}<br />
<br />
=== Формат идентификатора IDE ===<br />
<br />
<code style="white-space: pre;">{тип ide}__{идентификатор конфигурации}</code><br />
<br />
Например для <code style="white-space: pre;">default</code>-конфигурации Theia IDE: <code style="white-space: pre;">theia__default</code><br />
<br />
== Конфигурация ==<br />
<br />
Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла <code style="white-space: pre;">svacer.cfg</code>.<br />
<br />
Раздел конфигурации для управления функциональностью - <code style="white-space: pre;">xsvacer/webide</code>.<br />
<br />
Раздел содержит перечисление настроек доступных конфигураций для запуска экземпляров Theia IDE <code style="white-space: pre;">xsvacer/webide/theia</code>. При наличии нескольких активных конфигураций запуска Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.<br />
<br />
xsvacer:<br />
webide:<br />
theia:<br />
config1:<br />
...<br />
config2:<br />
...<br />
<br />
'''Внимание!''' Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому помимо настройки функциональности в разделе <code style="white-space: pre;">xsvacer/webide</code> необходимо также настроить доступ к docker-хосту в разделе <code style="white-space: pre;">xsvacer/docker</code> ([[Help:XSvacer:Docker]]). В противном случае функциональность webide не сможет работать корректно.<br />
<br />
'''Примечание:''' в случае отсутствия файла <code style="white-space: pre;">svacer.cfg</code> или отсутствии раздела <code style="white-space: pre;">xsvacer/webide</code>, будет использоваться [[Help:XSvacer:Webide#Конфигурация_по_умолчанию_используемая_в_svacer|конфигурация по умолчанию]]<br />
<br />
=== Конфигурация запуска Theia IDE ===<br />
<br />
'''Внимание!''' На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!<br />
<br />
Конфигурации запуска Theia IDE добавляются в виде полей в разделе <code style="white-space: pre;">xsvacer/webide</code>. Название поля является идентификатором конфигурации запуска. Например идентификатор по номеру используемой версии IDE:<br />
xsvacer:<br />
webide:<br />
theia:<br />
1-46-0:<br />
name: Theia blueprint web IDE (v1.46.0)<br />
...<br />
<br />
==== Базовые параметры конфигурации запуска ====<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|disabled<br />
|bool<br />
|Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE<br />
|true (переопределяется в конфигурации <code style="white-space: pre;">default</code>) <br />
|-<br />
|order<br />
|int<br />
|Порядковый номер в списке выбора конфигурации запуска<br />
|0 <br />
|-<br />
|name<br />
|string<br />
|Название конфигурации<br />
|Theia blueprint web IDE (v1.46.0) <br />
|-<br />
|sourcesroot<br />
|string<br />
|Путь к папке содержащей исходные коды снимков на машине со svacer'ом<br />
|${USER_CACHE_DIR}/svacer-snapshot-sources <br />
|-<br />
|dockerhostsourcesroot<br />
|string<br />
|Путь к папке содержащей исходные коды снимков на хосте docker'а. Нужен при использовании удалённого docker-хоста, т.к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от <code style="white-space: pre;">sourcesroot</code><br />
| <br />
|-<br />
|dockerhostpathseparator<br />
|string<br />
|Разделитель пути на хосте docker'а. По умолчанию <code style="white-space: pre;">"/"</code>.<br />
| <br />
|-<br />
|sariffiletemplate<br />
|golang template string<br />
|Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|sarifFileContext]]<br />
|"<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif" <br />
|}<br />
<br />
==== Параметры менеджера запуска IDE ====<br />
<br />
Конфигурация менеджера запуска IDE. На данный момент доступен только "стандартный" менеджер (<code style="white-space: pre;">type: default</code>)<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|manager<br />
|map<br />
|Конфигурация менеджера запуска IDE<br />
| <br />
|-<br />
|manager/type<br />
|enum: default<br />
|Тип менеджера запуска IDE<br />
|default <br />
|}<br />
<br />
==== Параметры запуска docker-контейнеров с IDE ====<br />
<br />
Данные параметры используются для настройки запуска docker-контейнеров с IDE<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|docker/<br />
|map<br />
|Настройки создания docker-контейнера с IDE<br />
| <br />
|-<br />
|docker/hostid<br />
|string<br />
|Идентификатор хоста docker'а, описанного в <code style="white-space: pre;">xsvacer/docker/hosts</code>. Запуск docker-контейнера с IDE будет выполнен на этом хосте<br />
|default <br />
|-<br />
|docker/containernametemplate<br />
|golang template string<br />
|Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура [[Help:XSvacer:Webide#Структуры_передаваемые_в_поля_с_golang-шаблонами_строк|TheiaDockerContainerStartContext]]<br />
|"theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>" <br />
|-<br />
|docker/containerconfiglabels<br />
|[]map<br />
|Список "меток" docker-контейнера. Дополняет список меток в <code style="white-space: pre;">docker/container/config/labels</code><br />
|<br />
- "com.docker.compose.project": svacer <br />
|-<br />
|docker/image/<br />
|map<br />
|Параметры docker-образа из которого будет запущен контейнер<br />
| <br />
|-<br />
|docker/image/name<br />
|string<br />
|Название образа<br />
|theia-blueprint <br />
|-<br />
|docker/image/tag<br />
|string<br />
|Тег образа<br />
|1.46.0.sarif.clang <br />
|-<br />
|docker/image/sourcetype<br />
|enum: repository/file<br />
|Тип источника для загрузки образа в docker-хост.<br />
* <code style="white-space: pre;">repository</code> - будет вызван <code style="white-space: pre;">docker pull</code> образа <code style="white-space: pre;">{image/name}:{image/tag}</code><br />
* <code style="white-space: pre;">file</code> - будет вызван <code style="white-space: pre;">docker load</code> с url'ом <code style="white-space: pre;">image/sourcefileurl</code><br />
|file <br />
|-<br />
|docker/image/sourcefileurl<br />
|url<br />
|Url откуда будет загружен docker-образ если <code style="white-space: pre;">image/sourcetype == "file"</code><br />
Url может содержать:<br />
- путь к локальному файлу: схема <code style="white-space: pre;">file://</code><br />
- http/https-адрес: схема <code style="white-space: pre;">http://</code> или <code style="white-space: pre;">https://</code><br />
|https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar <br />
|-<br />
|docker/container/<br />
|map<br />
|Свойства docker-контейнера<br />
| <br />
|-<br />
|docker/container/config<br />
|map<br />
|Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70<br />
| <br />
|-<br />
|docker/container/config/env<br />
|[]string<br />
|Список переменных среды, которые будут установлены в контейнере<br />
|<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki> <br />
|-<br />
|docker/container/hostconfig/<br />
|map<br />
|Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379<br />
| <br />
|-<br />
|docker/container/hostconfig/autoremove<br />
|bool<br />
|<br />
|true <br />
|-<br />
|docker/container/hostconfig/portbindings<br />
|map<br />
|<br />
|<br />
"3000/tcp": <br />
- hostport: 0 <br />
|-<br />
|docker/container/networkconfig/<br />
|map<br />
|Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104<br />
| <br />
|}<br />
<br />
==== Параметры проверки доступности healthcheck ====<br />
<br />
Данные параметры используются для проверки доступности IDE после запуска docker-контейнера<br />
<br />
{| class="wikitable"<br />
|+<br />
!Название<br />
!Тип данных<br />
!Описание<br />
!Значение в конфигурации по умолчанию <br />
|-<br />
|healthcheck<br />
|map<br />
|Параметры проверки доступности IDE<br />
| <br />
|-<br />
|healthcheck/starttoreadyretries<br />
|int<br />
|Количества попыток проверки до ошибки доступности<br />
|10 <br />
|-<br />
|healthcheck/starttoreadyperiod<br />
|golang duration string<br />
|Интервал проверки<br />
|200ms <br />
|}<br />
<br />
==== Структуры передаваемые в поля с golang-шаблонами строк ====<br />
<br />
sarifFileContext {<br />
Time time.Time<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
TheiaDockerContainerStartContext {<br />
IdeID: {<br />
IdeType string<br />
ConfigID string<br />
},<br />
StartArgs: {<br />
SnapshotID string<br />
UserID string<br />
User string<br />
},<br />
Context: {<br />
ProjectID *string<br />
BranchID *string<br />
SnapshotID *string<br />
MarkerID *string<br />
<br />
ProjectName *string<br />
BranchName *string<br />
SnapshotName *string<br />
MarkerName *string<br />
CreatedBy null.String<br />
CreatedByID null.String<br />
CreateTs null.Time<br />
}<br />
}<br />
<br />
=== Конфигурация по умолчанию используемая в svacer ===<br />
<br />
Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел <code style="white-space: pre;">xsvacer/webide</code>:<br />
<br />
<pre style="white-space: pre;"><br />
xsvacer:<br />
docker:<br />
hosts:<br />
default: # конфигурация docker-хоста<br />
type: external<br />
...<br />
<br />
webide:<br />
theia:<br />
1-46-0: &1-46-0<br />
disabled: true<br />
order: 0<br />
name: Theia blueprint web IDE (v1.46.0)<br />
sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources<br />
sariffiletemplate: "<nowiki>{{.Context.ProjectName}}.{{.Context.BranchName}}</nowiki>.sarif"<br />
manager:<br />
type: default<br />
docker:<br />
hostid: default # идентификатор используемого docker-хоста<br />
containernametemplate: "theia-1-46-<nowiki>{{.StartArgs.SnapshotID}}</nowiki>"<br />
image:<br />
name: theia-blueprint<br />
tag: 1.46.0.sarif.clang<br />
sourcetype: file<br />
sourcefileurl: https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar<br />
containerconfiglabels:<br />
- "com.docker.compose.project": svacer<br />
container:<br />
config:<br />
env:<br />
- THEIA_WEBVIEW_EXTERNAL_ENDPOINT=<nowiki>{{hostname}}</nowiki><br />
hostconfig:<br />
autoremove: true<br />
portbindings:<br />
"3000/tcp":<br />
- hostport: 0<br />
networkconfig:<br />
healthcheck:<br />
starttoreadyretries: 10<br />
starttoreadyperiod: 200ms<br />
default:<br />
<<: *1-46-0<br />
order: 0<br />
disabled: false<br />
</pre><br />
<br />
'''Внимание!''' По умолчанию используется docker-хост с идентификатором <code style="white-space: pre;">default</code>. Согласно настройке этого хоста, по умолчанию предполагается взаимодействие с докером через unix-сокет <code style="white-space: pre;">unix:///var/run/docker.sock</code>. Соответственно пользователь, под которым запускается svacer должен иметь доступ к этому сокету (https://docs.docker.com/engine/install/linux-postinstall/).<br />
<br />
'''Внимание!''' При наличии раздела <code style="white-space: pre;">xsvacer/webide</code> в конфигурационном файле <code style="white-space: pre;">svacer.cfg</code>, будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.<br />
<br />
=== Изменение конфигурационных параметров с помощью переменных окружения ===<br />
<br />
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения <code style="white-space: pre;">XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}</code><br />
<br />
Например, для активации rootless-хоста <code style="white-space: pre;">xsvacer/hosts/local</code> и переключения запуска IDE с идентификатором <code style="white-space: pre;">default</code> на этот хост, можно указать такие значения переменных окружения при запуске svacer'а:<br />
XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false<br />
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local<br />
<br />
== Очистка системы: удаление артефактов функциональности ==<br />
<br />
В процессе использования функциональности IDE создаются следующие артефакты:<br />
# Исходные файлы снимков скачиваются в "корневые папки" заданные в параметре <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/sourcesroot</code><br />
# Артефакты docker:<br />
#* образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов, указанных в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/hostid</code><br />
#* названия docker-образов будут соответствовать параметрам в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/image</code><br />
#* названия docker-контейнеров будут соответствовать параметру <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate</code><br />
#* наборы меток doker-контейнеров будут содержать:<br />
#*: метки перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels</code><br />
#*: метки перечисленные в <code style="white-space: pre;">xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels</code><br />
#*: метки с названиями <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><br />
# При использовании rootless-хоста docker'а будут созданы папки, согласно [[Help:XSvacer:Docker#Специфичные настройки для rootless-хоста]]<br />
<br />
== Рекомендации ==<br />
<br />
=== Предварительная загрузка docker-образа с IDE ===<br />
<br />
По умолчанию параметр <code style="white-space: pre;">xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl</code> содержит значение <code style="white-space: pre;">https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar</code>. По этому адресу находится архив с docker-образом для Theia IDE.<br />
<br />
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т.к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго.<br />
<br />
Для ускорения первого запуска IDE, докер образ можно загрузить на хост docker'а вручную. Для этого необходимо:<br />
# Скачать файл архива;<br />
# Выполнить команду <code style="white-space: pre;">docker image load -i /path/to/tar/theia-blueprint.1.46.0.sarif.clang.tar</code>;<br />
<br />
== Информация о docker-образе Theia IDE ==<br />
<br />
Docker-образ, используемый по умолчанию, построен на базе [https://theia-ide.org/ Eclipse Theia IDE] версии [[https://github.com/eclipse-theia/theia-blueprint/tree/v1.46.0|1.46.0]]<br />
<br />
При этом была изменена компоновка расширений theia (результат выполнения <code style="white-space: pre;">git diff</code>):<br />
<br />
<pre style="white-space: pre;"><br />
diff --git a/browser.Dockerfile b/browser.Dockerfile<br />
index efe591e..a4ebb6a 100644<br />
--- a/browser.Dockerfile<br />
+++ b/browser.Dockerfile<br />
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \<br />
RUN apt-get update && apt-get install -y wget apt-transport-https && \<br />
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \<br />
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 && \<br />
- apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \<br />
+ apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \<br />
apt-get purge -y wget && \<br />
apt-get clean<br />
<br />
diff --git a/package.json b/package.json<br />
index 9044595..9d0dcc8 100644<br />
--- a/package.json<br />
+++ b/package.json<br />
@@ -54,10 +54,8 @@<br />
"theiaPluginsDir": "plugins",<br />
"theiaPlugins": {<br />
"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",<br />
- "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",<br />
- "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",<br />
- "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",<br />
- "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"<br />
+ "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",<br />
+ "ms-sarifvscode.sarif-viewer": "https://open-vsx.org/api/MS-SarifVSCode/sarif-viewer/3.4.2/file/MS-SarifVSCode.sarif-viewer-3.4.2.vsix"<br />
},<br />
"theiaPluginsExcludeIds": [<br />
"ms-vscode.js-debug-companion",<br />
</pre><br />
<br />
Команда построения docker-образа: <br />
<pre style="white-space: pre;"><br />
docker build -t theia-blueprint:1.46.0.sarif.clang -f browser.Dockerfile .<br />
</pre><br />
<br />
Команда экспорта docker-образа:<br />
<pre style="white-space: pre;"><br />
docker image save theia-blueprint:1.46.0 > /path/to/tar/theia-blueprint.1.46.0.docker.command.tar<br />
</pre><br />
<br />
== Известные проблемы ==<br />
<br />
Список известных проблем и их решение<br />
<br />
=== При открытии sarif-файла в IDE открывается пустая панель "SARIF Results" ===<br />
<br />
Для просмотра sarif-файла содержащего предупреждения анализатора и разметку используется плагин [https://open-vsx.org/extension/MS-SarifVSCode/sarif-viewer SARIF Viewer]. При просмотре sarif-файла открывается webview плагина, со списком предупреждений анализатора.<br />
<br />
В 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, либо приложение размещалось на <code style="white-space: pre;">localhost</code>.<br />
<br />
Поэтому для решения данной проблемы svacer должен открываться по https, либо быть доступен по адресу <code style="white-space: pre;"><nowiki>http://localhost:...</nowiki></code></div>M.vinogradov