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

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

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

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

Начните с 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.
!
git push по SSH падает с «Internal Server Connection Error» после апгрейда на Gitea 1.27+
gitea serv (запускается на каждый ssh-запрос) зовёт внутренний API Gitea через [server] LOCAL_ROOT_URL. Без явного значения он выводится как https://localhost:<порт>/; на инсталляции https-acme или https-manual сертификат привязан к реальному домену, а не к localhost, поэтому этот внутренний TLS-хендшейк отваливается — ищите no certificate available for 'localhost' в journalctl -u gitea. Gitea 1.26 терпела такое расхождение, 1.27 ужесточила внутренний TLS-путь. Исправление: gtcnsl config set server.LOCAL_ROOT_URL <ваш ROOT_URL> --yes (например, https://git.example.com/). Свежие https-установки и gitea enable-https теперь проставляют его автоматически; gtcnsl doctor предупреждает об этом на инсталляциях, сделанных до этого исправления.
i
Пустая или устаревшая загрузка
Сверьте скачанное с подписанным checksums.txt (см. «Установка»). Собственный self-update у gtcnsl проверяет SHA-256 автоматически и откатывается при несовпадении.

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

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