К содержимому
gtcnsl
Доки Исходники
EN RU

Решение проблем и FAQ

Большинство проблем в одной команде от диагноза. Начните с doctor, прочитайте нужный лог и проверьте частые случаи ниже.

Актуально для v1.3.0

Начните с doctor

gtcnsl doctor          # PASS / WARN / FAIL по каждой проверке
gtcnsl doctor --fix --yes

doctor проверяет systemd, исходящий HTTPS, диск, привилегии, бинарники, app.ini, секреты и состояние юнитов. --fix пытается известные исправления (поставить ca-certificates, сгенерировать отсутствующий secrets.ini), затем перезапускает проверку.

Коды возврата и логи

  • Код 0 — успех (предупреждения для doctor тоже считаются успехом).
  • Код 1 — операция упала, либо doctor нашёл FAIL.
  • Логи Gitea: /var/log/gitea/. Состояние gtcnsl (бэкапы, кэш схемы, снапшоты self-update): /var/lib/gtcnsl/.
  • Логи сервисов: journalctl -u gitea и journalctl -u gitea-runner.

Частые случаи

[!NOTE] gtcnsl: command not found Бинарник в /usr/local/bin/gtcnsl, но оболочка ещё не подхватила /usr/local/bin — откройте новую сессию или вызовите по полному пути.

!
Регистрация runner-а падает
Домен инстанса должен сначала резолвиться на хост, а токены регистрации обычно одноразовые. Настройте DNS, возьмите свежий токен в настройках Gitea и повторите gtcnsl runner register --instance … --token ….
i
Изменение конфига откатилось само
config apply/set/toggle рестартят Gitea и проверяют здоровье; если она не поднялась, gtcnsl восстанавливает app.ini.bak и рестартит снова. Прочитайте journalctl -u gitea, чтобы понять, почему Gitea отвергла изменение, поправьте шаблон и примените заново — сначала с --dry-run.
i
CI-задачи не стартуют
Убедитесь, что runner зарегистрирован и активен (gtcnsl doctor, systemctl status gitea-runner) и что метки runs-on в вашем workflow совпадают с теми, с которыми вы регистрировались (--labels).
!
Ошибки HTTPS / сертификатов
На свежей машине могут отсутствовать CA-сертификаты. gtcnsl doctor --fix --yes ставит ca-certificates и перепроверяет доступность dl.gitea.com.
i
Пустая или устаревшая загрузка
Сверьте скачанное с подписанным checksums.txt (см. «Установка»). Собственный self-update у gtcnsl проверяет SHA-256 автоматически и откатывается при несовпадении.

Всё ещё застряли?

Откройте страницу контактов и пришлите упавшую команду плюс относящиеся строки journalctl — этого почти всегда достаточно, чтобы локализовать проблему.