Диагностика¶

Проверенные симптомы и решения для закрытого контура. Перед разбором полезно выполнить:

synth doctor --json
curl -fsS http://127.0.0.1:4300/health
curl -fsS http://127.0.0.1:4300/ready

Симптом	Раздел
Порт занят, сервис не стартует	Порты
`Permission denied` при чтении данных	Права
Ошибка TLS/CA при обращении к LLM или Keycloak	TLS/CA
Запросы к LLM не проходят через прокси	Прокси
Не работают git-инструменты или `execute_shell`	Git и rg
Keycloak возвращает `401` или все получают `USER`	Keycloak
Образ не найден или не запускается	Контейнеры
`synth update` не работает	Обновления
Сервис падает при старте	Старт сервиса

Порты¶

Порт по умолчанию — 4300 (standalone) или 5000 (backend). Проверьте, кто занимает порт.

Linux:

ss -ltnp | grep ':4300'
sudo lsof -nP -iTCP:4300 -sTCP:LISTEN

macOS:

lsof -nP -iTCP:4300 -sTCP:LISTEN

Windows:

Get-NetTCPConnection -LocalPort 4300 -ErrorAction SilentlyContinue |
  Select-Object LocalAddress, LocalPort, State, OwningProcess

netstat -ano | findstr :4300

Если порт занят другим процессом, освободите его или задайте другой: synth serve --port <port> / SYNTH_CORE_PORT. Не забудьте обновить unit, firewall и reverse proxy.

Права¶

Симптом: EACCES, Permission denied при чтении или записи каталога данных.

namei -l /var/lib/synth/data
ls -ld /var/lib/synth /var/lib/synth/data

Каталог должен принадлежать пользователю сервиса (synth в системной установке) и быть доступен на чтение/запись:

sudo chown -R synth:synth /var/lib/synth/data
sudo chmod 750 /var/lib/synth/data

Не используйте chmod 777

Это открывает данные и секреты всем пользователям хоста. Для пользовательской установки владелец — вы; для системной — отдельный системный пользователь.

Если сервис запущен от root, а данные принадлежат другому пользователю, исправьте unit (User=/Group=), а не права каталога. Для пользовательского systemd-сервиса проверьте, что --home/--data-dir указывают в доступный каталог.

TLS/CA¶

Симптом: UNABLE_TO_VERIFY_LEAF_SIGNATURE, self signed certificate, certificate has expired при запросе к LLM или Keycloak.

Проверьте цепочку вручную:

openssl s_client -connect llm.<domain>:443 -servername llm.<domain> \
  -CAfile /etc/synth/certs/ca.pem </dev/null

Проверьте HTTPS с тем же CA:

curl --cacert /etc/synth/certs/ca.pem -fsS https://llm.<domain>/v1/models

Убедитесь, что Synth видит файл:

ls -l /etc/synth/certs/ca.pem
echo "$SYNTH_TLS_CA_FILE"

После изменения security.tls/SYNTH_TLS_* перезапустите сервис: TLS применяется при старте.

Частые причины: указан промежуточный сертификат вместо CA; файл не читается пользователем сервиса; в PEM несколько сертификатов, но порядок неверный; истёк срок; в контейнер не смонтирован CA.

Не отключайте проверку TLS

rejectUnauthorized: false и curl -k — только временная диагностика. Рабочее решение — добавить правильный CA.

Прокси¶

Симптом: LLM-endpoint доступен из браузера, но Synth получает timeout; локальная Ollama перестала отвечать после включения прокси.

curl -x http://proxy.<domain>:3128 -I https://llm.<domain>
curl --noproxy '*' -I http://127.0.0.1:11434

Проверьте настройки:

SYNTH_PROXY_URL, SYNTH_PROXY_NO_PROXY;
раздел «Сеть» → «Прокси» в UI;
proxy в config.yaml.

Приоритет: SYNTH_PROXY_* → runtime UI → config.yaml → стандартные HTTP_PROXY/HTTPS_PROXY/NO_PROXY. После изменения в UI перезапустите сервис: настройка применяется при старте.

Для локальной Ollama добавьте 127.0.0.1,localhost в noProxy. Если прокси требует NTLM/Negotiate/Kerberos, Synth не выполняет доменную аутентификацию — используйте промежуточный egress-прокси, который её завершает. SOCKS5 поддерживается best-effort, без target CA/mTLS.

Git и rg¶

Симптом: execute_shell недоступен, git-инструменты отклоняются, grep_files не находит файлы.

git --version
rg --version

rg входит в бандл. Если команда не найдена, проверьте целостность распаковки (SHA256SUMS) и PATH.
Git не входит в Windows-бандл. Без Git для Windows execute_shell деградирует (нет POSIX-shell), git-тулы недоступны; интерфейс, чат, файлы и grep_files продолжают работать. Установите Git for Windows per-user и перезапустите Synth.
На Linux/macOS Git и rg должны быть доступны процессу сервиса. Проверьте PATH в unit-файле/LaunchAgent.

Подробнее о матрице возможностей — Windows.

Keycloak¶

Симптом: 401, редирект зацикливается, все пользователи получают USER.

Issuer доступен и совпадает:

curl -fsS https://<keycloak-host>/realms/<realm>/.well-known/openid-configuration

Поле issuer должно совпадать с настройкой Synth символ в символ.

Redirect URI в Keycloak — https://<synth-host>/auth/callback, ровно как в values/конфиге.
Роли: realm-роли admin, user, lead, auditor; мапперы включают id.token.claim и access.token.claim.
Время: проверьте часы на хосте Synth и Keycloak. Расхождение ломает проверку JWT.

date -u
timedatectl status

CA: если Keycloak подписан внутренним CA, настройте caCert в чарте или security.tls.caFile/SYNTH_TLS_CA_FILE.
Секрет клиента: SYNTH_OIDC_CLIENT_SECRET должен совпадать с Keycloak; после смены перезапустите backend.

Контейнеры¶

Симптом	Причина	Решение
`image not found` / `pull access denied`	Образ не загружен, Compose пытается pull	`docker load -i …`; `pull_policy: never`
`exec format error`	Архитектура архива не совпадает с хостом	Загрузить `amd64`/`arm64` под платформу
Pod в `ImagePullBackOff`	Образ не импортирован на узел	Импортировать на каждый узел или использовать внутренний registry
`synth` падает с `EACCES` на томе	Права на volume	Проверить владельца/права тома
`helm upgrade` не меняет образ	Тот же тег	Указать новый `<version>`

Проверка архитектуры:

docker image inspect gitverse.ru/itphx/synth:<version> \
  --format '{{.Os}}/{{.Architecture}}'
uname -m

Обновления¶

Симптом: synth update завершается ошибкой или висит.

Это ожидаемо в закрытом контуре: команда обращается к npm-реестру. Не лечите это настройкой прокси к npm — используйте замену бандла:

backup;
остановка сервиса;
распаковка новой версии;
synth migrate --dry-run → synth migrate --yes;
запуск и synth doctor.

Подробно — Эксплуатация. Флаг SYNTH_OFFLINE — планируемый; в текущей версии его нет.

Старт сервиса¶

Сервис не поднимается или сразу завершается.

sudo systemctl status synth
sudo journalctl -u synth -n 100 --no-pager

Для пользовательского сервиса — systemctl --user status synth и journalctl --user -u synth -n 100 --no-pager.

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

/opt/synth/bin/synth serve --host 127.0.0.1 --port 4300 \
  --data-dir /var/lib/synth/data

Частые причины:

занят порт;
нет прав на каталог данных;
синтаксическая ошибка в config.yaml;
схема данных новее бинарника — выполните synth migrate --dry-run;
SELinux блокирует чтение/запуск — см. ниже.

SELinux¶

getenforce
sudo ausearch -m avc -ts recent

Исправляйте контекст (semanage fcontext + restorecon), а не отключайте SELinux. Команды — в разделе Linux.

macOS и Windows¶

macOS: предупреждение Gatekeeper — проверьте SHA256 и одобрите конкретный артефакт; не отключайте Gatekeeper глобально. См. macOS.
Windows: предупреждение SmartScreen — проверьте хеш; в организации — allowlist WDAC/AppLocker. См. Windows.
Windows, нет git: см. Git и rg.

Диск и данные¶

Симптом: ошибки записи, backup не создаётся, сервис зависает.

df -h
du -sh /var/lib/synth/data
du -sh /var/backups/synth

Проверьте свободное место под данные, backup и логи. Не удаляйте файлы внутри каталога данных вручную — используйте API/UI и synth backup/synth restore.