9 мин

13

В домашней инфраструктуре у меня крутится десяток сервисов: Grafana, Zabbix, n8n, Navidrome, ollama, БД, пара дашбордов и тестовых API. Каждый раз, когда нужно было выставить новый сервис наружу, я открывал дашборд Cloudflare и руками проходил один и тот же путь: создать туннель, прописать ingress‑правило, добавить DNS записи, настроить Zero Trust Access. Минут пятнадцать, если без ошибок. С ошибками — больше, потому что один неверно скопированный tunnel ID ломает всю цепочку и приходится откатывать вручную.

На какой‑то раз стало понятно, что это рутина, которую можно свернуть в одну команду. Так появился cfzt — CLI на Go, который сейчас умеет:

zt up grafana 3000

И через несколько секунд grafana.domain.com смотрит на localhost:3000 через Cloudflare Tunnel, с настроенным Zero Trust Access и systemd сервисом, который переживет ребут.

В статье — архитектура, конкретные грабли при реализации и отдельно — история про баг в самом cloudflared, из‑за которого пришлось писать собственный вотчдог‑процесс.

Почему не Tailscale или обычный реверс‑прокси? Перед тем как писать своё, я смотрел на альтернативы.

Tailscale — отличная вещь для приватной mesh‑сети между своими устройствами, но не решает задачу опубликовать сервис для конкретных лиц с навешанной авторизацией, да и сама модель другая: это VPN, а не публичный реверс с контролем доступа на уровне HTTP.

Обычный nginx или caddy + dns — требует открытого порта 80/443 наружу, статического адреса или DDNS и ручной настройки сертификатов. Для домашнего сервера за NAT без белого айпишника это или не работает, или требует прокидывания портов на роутере, чего я стараюсь избегать.

Cloudflare Tunnel через cloudflared — снимает обе проблемы: исходящее соединение от сервера к edge Cloudflare, никаких открытых портов, TLS из коробки, плюс Zero Trust Access как слой авторизации перед самим сервисом. Минус один — UX. cloudflared tunnel create, cloudflared tunnel route dns, отдельная настройка access через wrangler или дашборд — это десяток разрозненных команд и кликов, которые мало того, что нужно вспомнить, так еще и легко перепутать местами.

cfzt — это просто склейка всего этого в один workflow с откатом при ошибке на любом шаге.

Архитектура: что происходит за один zt up

Под капотом zt up <service_name> <port> последовательность вызовов к Cloudflare API и локальной файловой системе, каждый шаг которой может откатить предыдущие шаги при ошибке. Вот сокращённая версия основной функции:

func createTunnel(opts tunnelOpts) error {
    cfg, _ := config.Load()
    store, _ := state.LoadStore()
    cf := cloudflare.NewClient(cfg.APIToken, cfg.AccountID)
    hostname := opts.name + "." + cfg.Domain

    zoneID, _ := cf.GetZoneID(cfg.Domain)

    // создаем туннель
    tunnelID, credJSON, _ := cf.CreateTunnel(opts.name)

    rollback := func(dnsRecordID, accessAppID string) {
        if accessAppID != "" { cf.DeleteAccessApp(accessAppID) }
        if dnsRecordID != "" { cf.DeleteDNSRecord(zoneID, dnsRecordID) }
        cf.DeleteTunnel(tunnelID)
        cloudflared.CleanTunnelFiles(opts.name)
        service.Uninstall(opts.name)
    }

    // настраиваем ингресс
    if err := cf.ConfigureTunnel(tunnelID, hostname, opts.port); err != nil {
        rollback("", "")
        return err
    }

    // пишем cname
    dnsRecordID, _ := cf.UpsertCNAME(zoneID, hostname, tunnelID)

    // если не --public, создаём zero trust access app + bypass policy
    var accessAppID string
    if !opts.public {
        accessAppID, _ = cf.UpsertAccessApp(hostname, opts.name)
        cf.CreateBypassPolicy(accessAppID, opts.emails)
    }

    // пишем локальный config.yml для cloudflared
    cfgPath, _ := cloudflared.WriteTunnelConfig(tunnelID, opts.name, hostname, opts.port, opts.protocol, credJSON)

    // ставим systemd user unit
    service.Install(opts.name, cfgPath, logPath)

    // сохраняем состояние в ~/.zt-state.json
    store.Set(&state.Tunnel{Name: opts.name, TunnelID: tunnelID, ...})
    store.Save()

    return nil
}

Важная деталь — роллбэк. Если, например, шаг 4 падает из‑за невалидного email в ‑allow, откатываются уже созданные DNS‑запись и сам туннель, а не остаются висеть полусозданным мусором в аккаунте. Без этого после нескольких неудачных попыток в дашборде накапливаются туннели без DNS и DNS‑записи без туннелей, отлаживать такое и чистить потом руками то еще удовольствие.

Локальный игресс‑конфиг — обычный yaml, который cloudflared понимает нативно:

tunnel: <tunnel-id>
credentials-file: /home/user/.zt/tunnels/grafana/<tunnel-id>.json

ingress:
  - hostname: grafana.domain.com
    service: http://localhost:3000
  - service: http_status:404

Состояние хранится локально в ~/.zt‑state.json — плоском jsone с маппингом имя туннеля, метаданные (айди, порт, протокол, статус). Это то, что позволяет zt down grafana найти все связанные ресурсы и снести их без повторных запросов в API на поиск.

Грабли номер 1: build tags и кросс‑компиляция

Проект собирается под Linux, macOS и Windows (хотя на Windows часть функциональности это заглушки, cloudflared там без демонизации). Для platform‑specific кода используется стандартный подход с суффиксами файлов и //go:build тегами.

В какой‑то момент я забыл добавить тег!windows в runner при рефакторинге. Локально на Linux все собиралось нормально — runner_windows.go просто не подхватывался при обычной сборке. А вот CI, который кросс‑компилирует под все три платформы из одного раннера, упал с ошибкой:

internal/cloudflared/runner_windows.go:7:6: Start redeclared in this block
    internal/cloudflared/runner.go:12:6: other declaration of Start
internal/cloudflared/runner.go:26:41: unknown field Setsid in struct literal of type syscall.SysProcAttr

Вторая ошибка интереснее первой. syscall.SysProcAttr.Stesid — это поле, специфичное для unix (используется чтобы посадить дочерний процесс cloudflared в новую сессию, отвязав от родительского терминала). На винде такого поля в структуре нет вообще, поэтому даже если бы не было конфликта имен, код всё равно не скомпилировался бы. Build tags — это не формальность, это единственный способ держать platform‑specific системные вызовы в одном бинаре без ifdef‑подобной магии.

Фикс — буквально одна строчка, но показательный пример того, что успешный go build на твоей машине не значит, что CI для всех таргетов будет успешным.

Грабли номер 2: secrets в Terraform state против декларативного формата без кредов.

Когда я думал над функцией бэкапа конфигурации (zt export / zt apply), первая идея была экспортировать в Terraform, благо у Cloudflare есть официальный провайдер. Но довольно быстро всплыла проблема: cloudflared tunnel create через API возвращает tunnel_secret — кред, который должен попасть либо в Terraform state (а это значит, что секрет лежит в файле, который часто коммитят или хранят в S3 без шифрования), либо его нужно выносить в отдельную сенситив‑переменную с дополнительной инфраструктурой для хранения.

Для домашнего проекта это избыточная сложность. Вместо Terraform я сделал свой плоский yaml‑формат, который намеренно не включает креды и туннель айди:

services:
  grafana:
    port: 3000
  portainer:
    docker: true
    allow:
      - mail@domain.com
  api:
    port: 8080
    public: true

Креды остаются в ~/.zt‑config.json (создаются через zt init на каждой машине отдельно), а сам zt.yaml безопасно коммитить в гит — там нет ничего секретного, только намерение, какой сервис, на каком порту, с каким уровнем доступа.

zt apply zt.yaml на новой машине делает дифф между манифестом и локальным состоянием и создаёт только то, чего не хватает, но никогда не удаляет и не модифицирует существующее автоматически:

for _, name := range toCreate {
    svc := m.Services[name]
    port, err := resolveApplyPort(name, svc)
    ...
    createTunnel(tunnelOpts{
        name: name, port: port, protocol: protocol,
        public: svc.Public, emails: svc.Allow, docker: svc.Docker,
    })
}

Решение проще, чем казалось вначале, но потребовало явно решить вопрос «что является источником правды»: локальный state.Tunnel или лайв‑запрос в Cloudflare API. Выбрал первое — state.Tunnel уже хранит всё нужное (порт, протокол, public/allow), просто два этих поля раньше нигде не сохранялись, использовались один раз при создании и терялись. Расширение модели на два json‑поля решило это без миграции — старые ~/.zt‑state.json без новых полей десериализуются нормально, поля просто становятся zero‑value.

Грабли номер 3: cloudflared не возвращается на quic после сбоя. Пришлось писать вотчдог.

Самая интересная часть. cloudflared поддерживает два транспортных протокола для соединения с edge Cloudflare: QUIC (поверх UDP, быстрее, поддерживает приватный DNS) и HTTP/2 (поверх TCP, fallback для случаев когда UDP заблокирован — частая ситуация у некоторых провайдеров и в корп. сетях). По дефолту используется ‑protocol auto, который сам решает, какой транспорт использовать.

Логика фоллбэка действительно работает, если cloudflared не может установить udp‑соединение, он молча переключается на HTTP/2. Проблема в обратном направлении — назад на quic он не переключается никогда, даже если сеть восстановилась через минуту. Это открытый баг в самом cloudflared [issue #1534], висящий с 2022 года: один раз упав на HTTP/2, процесс будет сидеть на нём до посинения и явного рестарта, сколько бы времени ни прошло.

Если сервак ночью на полминуты словил udp‑затык, туннель навсегда остаётся на менее производительном протоколе, пока кто‑то руками не сделает systemctl restart. Сам cloudflared об этом никак не сигналит (лишь роняет в лог маленькую строчку) и просто тихо живёт на HTTP/2.

Раз пацаны из Cloudflare эту проблему за три года не решили, пришлось закрывать на уровне cfzt. План был таков:

1. Отслеживать в логе cloudflared появление строки Switching to fallback protocol http2 — это стабильная, не меняющаяся годами фраза (чекнул в исходниках от версии 2022.4 до 2025.9, текст идентичен).

2. При обнаружении не дергать рестарт сразу (туннель и так работает, просто на HTTP/2), а ждать бэкофф‑интервал и затем перезапускать сервис, заставляя cloudflared заново начать с попытки quic.

3. Бэкофф экспоненциальный на каждый туннель отдельно: 10 минут, 20, 40, 60, чтобы не долбить рестартами туннель, у которого udp сломан стабильно (например, провайдер режет его постоянно) — такой туннель всё равно будет получать шанс на восстановление раз в час, а не зафлапан до дыр.

Реализация — отдельный долгоживущий процесс, не разовая проверка внутри zt doctor. Ключевая часть — инкрементальное сканирование лога, чтобы не перечитывать весь файл на каждый тик:

func scanLogTail(path string, fromOffset int64) (scanResult, error) {
    f, err := os.Open(path)
    ...
    info, _ := f.Stat()

    if info.Size() < fromOffset {
        fromOffset = 0
    }

    f.Seek(fromOffset, 0)
    found := false
    scanner := bufio.NewScanner(f)
    for scanner.Scan() {
        if strings.Contains(scanner.Text(), "Switching to fallback protocol http2") {
            found = true
        }
    }
    return scanResult{fallbackDetected: found, newOffset: info.Size()}, nil
}

Решение о рестарте отделено от самого сканирования — чистая функция, которую легко покрыть тестами без реального файла лога на каждый кейс:

func Evaluate(ts *TunnelState, logPath string, now time.Time) (Decision, error) {
    result, _ := scanLogTail(logPath, ts.LastLogOffset)
    ts.LastLogOffset = result.newOffset

    if !result.fallbackDetected {
        resetBackoff(ts)
        return Decision{}, nil
    }

    backoff := ts.CurrentBackoff
    if backoff <= 0 { backoff = MinBackoff }

    if !ts.LastRestartAt.IsZero() && now.Sub(ts.LastRestartAt) < backoff {
        return Decision{Reason: "fallback detected but within backoff window"}, nil
    }

    return Decision{ShouldRestart: true, Reason: "QUIC fallback detected — restarting"}, nil
}

Отдельный нюанс — где хранить состояние самого вотчдога. Основной ~/.zt‑state.json читается и пишется интерактивными командами (up, down, list) без файловых блоков. Если вотчдог‑процесс, тикающий каждые 30 секунд, начнёт писать туда же — появляется гонка между двумя процессами за один файл. Решением стал отдельный ~/.zt‑watchdog‑state.json, который трогает только сам вотчдог, никто больше. Простое разделение ответственности вместо файловых локов или более тяжелой синхронизации.

Сам вотчдог‑процесс запускается как ещё один systemd user unit (zt‑watchdog.service), общий на все туннели сразу — не по процессу на каждый, чтобы не плодить лишних systemd сервисов:

zt watchdog enable   # ставит и стартует systemd unit, чек каждые 30 сек
zt watchdog status   # running / stopped
zt watchdog disable  # снимает unit

Реальный тест механизма: блокируем исходящий udp на порт 7844 (iptables -A OUTPUT -p udp --dport 7844 -j DROP), смотрим как туннель падает на HTTP/2 в логе, снимаем блок и через какое‑то время (до 10 минут по дефолту) вотчдог дергает туннель и в логе снова появляется успешное quic‑соединение.

Что дальше.

Из того, что осознанно отложил: явная поддержка IPv6 для origin‑сервиса (сейчас жёстко зашит localhost, что плохо подходит для сервисов в IPv6-only docker сетях), и шэринг одного cloudflared‑процесса на несколько сервисов через единый туннель с множественными ингресс‑правилами вместо текущей модели «один сервис — один туннель — один процесс». Второе решил пока не делать — это меняет модель данных довольно ощутимо ради экономии нескольких systemd‑юнитов, а профита на масштабах хоум лабы немного.

Пощупать можно в репозитории на Гитхабе, написан на Go, собирается под Linux/macOS/Windows, релизы с чексуммами на каждый таргет.

Буду рад обратной связи!