ArchMapДокументация

Проверить состояние сервиса и прочитать журналы

Проверить, что сервис работает#

Чтобы проверить состояние ArchMap, выполните следующие действия:

  1. Запросите адрес /health:

    • на сервере: curl -s http://127.0.0.1:8000/health;
    • в Docker Compose: curl -s http://localhost:8080/health.

    Если процесс ArchMap жив, он ответит {"status":"ok"}.

  2. Запросите адрес /ready:

    • на сервере: curl -s http://127.0.0.1:8000/ready;
    • в Docker Compose: curl -s http://localhost:8080/ready.

    Если ArchMap готов к работе и база отвечает, он ответит {"status":"ok"}. Если база не отвечает, ArchMap ответит кодом 503.

Примечание

В Kubernetes эти адреса проверяет сам кластер: адрес /health опрашивают пробы запуска и живучести, а адрес /ready опрашивает проба готовности. Состояние пода показывает kubectl -n archmap get pods. На сервере состояние службы показывает systemctl status archmap.

Прочитать журналы#

Чтобы прочитать журнал ArchMap, выполните команду для своего способа установки:

  • сервер: journalctl -u archmap -f;
  • Docker Compose: docker compose logs -f archmap;
  • Kubernetes: kubectl -n archmap logs deploy/archmap.

Примечание

В журнале одна строка на каждый запрос (метод, путь, код ответа и адрес) и ошибки с трассировкой. Вызовы ИИ-агентов пишутся отдельными строками с меткой archmap.mcp: пользователь, название и начало токена, инструмент, проект, итог, длительность и адрес. Пароли, токены и содержимое документов в журнал не попадают.

Примечание

Своих файлов журнала у ArchMap нет. На сервере журнал службы хранит journald, а журналы nginx лежат в /var/log/nginx/. Чтобы журнал службы переживал перезагрузку и не разрастался, задайте настройки journald (например, в файле /etc/systemd/journald.conf.d/archmap.conf):

[Journal]
Storage=persistent
SystemMaxUse=1G
MaxRetentionSec=90day

Затем выполните sudo systemctl restart systemd-journald.

Примечание

Журнал установщика на сервере выводится только в терминал. Чтобы сохранить его, запустите установщик так: sudo ./deploy/install.sh 2>&1 | tee install.log.

Типовые неполадки#

На сервере#

  • nginx отвечает 502: служба ArchMap не работает. Посмотрите последние строки журнала: journalctl -u archmap -n 50.
  • Встроенный Python не запускается: папка поставки смонтирована с noexec, включена замкнутая программная среда (например, в Astra Linux SE она запускает только подписанные программы) или запуск запрещает политика SELinux (проверьте ausearch -m avc).
  • Установщик остановился на проверке базы: сообщение называет, что поправить (подключение, версию PostgreSQL, кодировку базы или права пользователя).

В Kubernetes#

  • Под в состоянии Init:Error или Init:CrashLoopBackOff: init-контейнер не прошёл проверку базы или миграции. Посмотрите его журнал: kubectl -n archmap logs <под> -c migrate. Сообщение «БАЗА: …» называет, что поправить.
  • ImagePullBackOff: неверный адрес образа (image.repository, image.tag) или у пространства имён нет доступа к реестру (imagePullSecrets).
  • CreateContainerConfigError: нет Secret из значения database.existingSecret или ключ в нём называется иначе, чем в database.existingSecretKey.

При любом способе установки#

  • Ввоз большого архива обрывается или отвечает 413: прокси перед ArchMap ограничивает размер запроса или время ответа. Поднимите предел до 64 МБ и тайм-аут до 300 секунд.
  • «Слишком много попыток входа» у всех пользователей сразу: ArchMap принимает запросы всех пользователей за запросы с одного адреса прокси. В Docker Compose и Kubernetes включите TRUST_FORWARDED_FOR (см. Справочник переменных окружения). На сервере nginx пропускает 10 попыток входа в минуту с адреса. Если все пользователи приходят через один прокси, поднимите rate в файле /etc/nginx/conf.d/archmap.conf и выполните sudo systemctl reload nginx.
  • ИИ-агент не подключается по адресу …/mcp: на сервере старой версии в nginx нет этого адреса (см. Подключить ИИ-агентов на сервере старой версии).