Развертывание Fiber-приложения

Начнём почти дословно с того, чем закончили: «двадцать третий урок — развертывание Fiber-приложения: сборка бинарника, Docker, nginx и переменные окружения. Структура, построенная сегодня, деплоится как есть: корень собирает слои, слои не знают про окружение, а весь хаос env читается в одном FromEnv — двадцатый урок подготовил это заранее». Это обещание не риторика, а прямая техническая смета. Композиционный корень cmd/api/main.go уже собирает repo, svc и h тремя конструкторами — значит, точка входа для прод-запуска существует. Конфиг из internal/config уже читает окружение одним вызовом FromEnv — значит, порт и таймауты приезжают из переменных окружения без правок кода. Регистрация маршрутов уже сидит на fiber.Router — значит, та же сборка работает и под systemd, и в контейнере, и за прокси. Отдельного «деплой-режима» в коде не будет: будут команды вокруг того же самого main. За урок мы поднимемся по четырём ступеням: артефакт — go build; контейнер — Dockerfile; фронт — reverse proxy nginx; служба — systemd и env. На каждой ступени канон курса — инстанс на :8080, маршрут /api/tasks, buildApp и страж requireAPIKey — остаётся неизменным, меняется только упаковка.

Слово деплой fiber означает превращение репозитория в работающий процесс на чужой машине, и у Go в этом пути есть преимущество, которое стоит проговорить до всяких инструментов: компиляция происходит заранее. Node или Python везут на сервер интерпретатор и исходники, Java — рантайм и байткод, а Go везёт один исполнимый файл, в котором уже лежит и HTTP-сервер, и весь ваш сервисный слой, и компилятор, который всё это склеил. На боевом сервере не нужен ни тулчейн Go, ни каталог с исходниками, ни менеджер пакетов: нужен файл, право его запускать и свободный порт. Отсюда весь урок — это управление двумя сущностями: артефактом (что мы собираем) и окружением (где и как он живёт). Запрос «деплой fiber» вбивают в поиск обычно тогда, когда localhost кончился: приложение держит состояние в памяти, слушает :8080, и нужно, чтобы оно пережило выход из сессии ssh, поднялось после перезагрузки и отвечало на доменное имя по TLS. Каждое из этих «нужно» закрывается отдельной ступенью урока, и важно, что порядок ступеней неслучаен: контейнер упаковывает бинарник, nginx прикрывает контейнер, systemd следит за процессом — на каждом уровне тот же принцип слоёв, что и в двадцать втором уроке, только не внутри программы, а вокруг неё.

Бинарник — артефакт, но «не работает» чаще всего означает «не работает среда»: другая версия glibc, отсутствующие сертификаты, чужие права на каталог, занятый порт. Контейнер лечит это радикально: образ упаковывает процесс вместе со всем, что ему нужно, и запускается одинаково на ноутбуке и в бою. По запросу fiber docker вы найдёте сотни Dockerfile, и почти все они собираются по одной схеме — multi-stage, многоступенчатая сборка, официальный паттерн руководства Docker для Go. Идея зеркалит канон двадцать второго урока: слои, которые нужны только для сборки, живут отдельно от слоёв, которые уезжают в прод. Первая сцена — builder: полноценный образ golang с тулчейном, где скачиваются зависимости и выполняется go build. Вторая сцена — доставка: пустой или почти пустой образ, куда COPY --from=build переносит единственный файл — готовый бинарник. В финальном образе нет ни Go, ни исходников, ни менеджера пакетов, ни шелла — только ваш API-сервер размером в мегабайты против гигабайтного builder-образа. Это одновременно и безопасность: в прод-контейнере просто нечем ковыряться, потому что инструментария там нет.

Выбор финального образа — три честных варианта с разными компромиссами. scratch — это вообще ничего: в образе лежит один ваш файл, и запуск возможен только потому, что бинарник статический; ни шелла для отладки, ни библиотек, ни сертификатов. Последнее — главная ловушка: если приложение само ходит по HTTPS наружу (клиент к чужому API, отправка почты), ему нужны корневые сертификаты — в scratch их нет, и первый же исходящий запрос по TLS упадёт с ошибкой проверки сертификата; лечится COPY /etc/ssl/certs/ca-certificates.crt из builder-сцены. distroless/static — та же минималистичность плюс уже уложенные сертификаты, часовые пояса и заготовленный непривилегированный пользователь nonroot; это дефолт, который мы взяли в каноническом Dockerfile. alpine — полноценный мини-дистрибутив с busybox-шеллом: удобен для отладки docker exec, но тащит musl вместо glibc — со статическим CGO_ENABLED=0-бинарником это безопасно, с динамическим — ловушка из прошлого блока. Отдельная строка экономики: образ на базе scratch или distroless весит порядка пятнадцати мегабайт и почти не несёт поверхности атаки — нечего обновлять, кроме вашего кода; сборка и доставка образа — это docker build -t api:1.0 . и docker run -p 8080:8080 api:1.0, и оба шага можно прогнать локально до всякого сервера.

Приложение собрано и упаковано, но дев и прод различаются не кодом, а окружением — и здесь долги прошлого возвращаются с процентами. Канон двадцатого урока: встроенной поддержки env в fiber.Config нет, конфигурация — ваш код между os.Getenv и литералом структуры; канон двадцать второго — этот код живёт в одном месте, internal/config.FromEnv, читает переменные один раз на старте и раздаёт значения вниз параметрами. Прод-запуск ложится на этот канон без единой правки: контейнер получает переменные флагами docker run -e APP_NAME=api -e FIBER_READ_TIMEOUT=5s, а из файла целиком — docker run --env-file api.env; docker compose делает то же директивами environment и env_file; systemd — директивами Environment и EnvironmentFile в юните. Заметим главное: ни один слой не изменился, потому что ни один слой не зовет os.Getenv сам. Добавим в FromEnv чтение PORT из двадцатого урока с дефолтом 8080 — и точка прослушивания станет конфигурируемой: buildApp получает Config, а main вызывает app.Listen(":"+cfg.Port). Переменные канона (APP_NAME, FIBER_READ_TIMEOUT, PORT) едут в прод в том же виде, в котором их проверяли t.Setenv-тестами из двадцать первого урока: окружение и код уже договорились.

Контейнер слушает :8080, но пользователи стучатся на 80 и 443 вашего домена, и между ними принято ставить reverse proxy — прокси, который принимает запросы от клиентов и от их имени ходит к бэкенду. Nginx в этой роли решает сразу пачку задач, каждая из которых — отдельная глава, если делать её внутри Go-процесса: терминация TLS (сертификат живёт в одном конфиге, а не в каждом приложении), много сервисов на одном IP по имени хоста (example.com → fiber, grafana.example.com → monitoring), отдача статики и сжатие, общие журналы доступа и базовая оборона от мусорных запросов. Есть и техническая причина: порты ниже 1024 — привилегированные, их слушают процессы с соответствующими правами; fiber-сервис работает под непривилегированным пользователем (nonroot 65532 в контейнере, свой пользователь в systemd), и пусть порт 8080 остаётся приватным, а общение с внешним миром берёт на себя прокси. Связка отзеркаливает канон урока про группы: клиент видит один домен, за ним дерево маршрутов делится между бэкендами. Настройка — один конфигурационный файл, который мы сейчас соберём; в него же войдут заголовки, о которых у fiber есть строгое мнение.

Заголовок X-Forwarded-For — штучка двусторонняя: его пишет прокси и его же может подделать любой клиент, дописав себе чужой IP. Исходники fiber v3.5.0 предупреждают в док-комментарии поля ProxyHeader дословно: headers are easily spoofed and the detected IP addresses are unreliable. Поэтому в v3 машина доверия работает в два такта. Первый такт — fiber.Config.TrustProxy: без него fiber вообще не смотрит в пересылаемые заголовки. Второй — TrustProxyConfig: список адресов, с которых можно верить, — Proxies (IP-адреса или CIDR-диапазоны) и флаги Loopback, LinkLocal, Private, UnixSocket для целых классов адресов. Если запрос пришёл с доверенного адреса и задан ProxyHeader, c.IP() идёт по цепочке X-Forwarded-For справа налево, пропуская доверенные прокси, и возвращает первый недоверенный адрес — так подделка слева цепочки игнорируется автоматически. Если запрос пришёл не с доверенного адреса, c.IP() возвращает RemoteIP — адрес TCP-соединения, то есть сам прокси. Заодно доверенные прокси открывают c.Scheme() из X-Forwarded-Proto и c.Host() из X-Forwarded-Host. Логика разложена в req.go: метод IP() проверяет IsProxyTrusted() и достаёт адрес из заголовка, только когда доверие подтверждено; EnableIPValidation добавляет валидацию строк и пусть стоит там, где цепочки длинные и странные.

WebSocket-ветка из шестнадцатого урока — эхо на /ws/chat/:room, комнаты и broadcast — упрётся в прокси первой. Рукопожатие начинается как обычный HTTP GET с заголовками Upgrade: websocket и Connection: Upgrade, но nginx по умолчанию их не пропускает, и документация nginx объясняет почему без обинутков: Upgrade — hop-by-hop заголовок, он относится к конкретному соединению, а не путешествует по цепочке прокси, поэтому от клиента к бэкенду его нужно передать явно. Вторая деталь ещё коварнее: по умолчанию nginx говорит с бэкендом по HTTP/1.0, где механизма смены протокола нет вовсе, — директива proxy_http_version 1.1 обязательна. После обеих правок nginx с версии 1.3.13 умеет туннель: получив от бэкенда 101 Switching Protocols, он перестаёт быть HTTP-прокси и прозрачно гоняет кадры в обе стороны, так что contrib-пакет с его hijack из шестнадцатого урока не замечает подмены. Практические мелочи: длинноживущие соединения обрывает proxy_read_timeout (дефолт — 60 секунд) — для пуш-каналов его поднимают или держат heartbeat ping/pong, о котором урок шестнадцатый уже рассказывал; изящный вариант Connection через map $http_upgrade $connection_upgrade апгрейдит только те запросы, что просят апгрейд, и не портит обычные.

Docker — не единственный честный путь: на классическом VPS-сервере со свежесобранным бинарником смотрит systemd, и это не «бедный родственник» контейнеров, а штатный способ держать долгоживущий процесс. Юнит — текстовый файл в /etc/systemd/system/api.service — декларирует то, что раньше говорил руками: что запускать, от кого, с каким окружением и что делать при смерти. Раздел [Unit] описывает зависимости — After=network.target заставляет ждать готовности сети; раздел [Service] несёт сам процесс: User=api — сервис не работает от root, WorkingDirectory и ExecStart — где и что запускать, EnvironmentFile — тот же файл окружения, что и docker run --env-file; Restart=always — политика выживания, о которой дальше отдельный блок. Раздел [Install] с WantedBy=multi-user.target включает юнит в обычную загрузку системы. Команды управления трёхшаговые: systemctl daemon-reload перечитывает юниты после правки файла, systemctl enable --now api включает автозапуск и стартует сразу, journalctl -u api -f показывает журнал — stdout и stderr приложения journald собирает в единый журнал с поиском по юниту, что закрывает потребность «посмотреть логи» без всякого logger-мидлвара, хотя читаемость строк — по-прежнему заслуга девятнадцатого урока.

Политика Restart — договор с systemd о том, что считать поводом для перезапуска. Restart=always поднимает процесс при любом завершении — и с кодом ошибки, и с кодом 0; Restart=on-failure — только при неуспехе: не-нулевой код выхода или смерть от сигнала; Restart=on-success — наоборот, только после чистого завершения; дефолт no — не перезапускать вовсе. Исключение для всех политик одно: systemctl stop — вы явно попросили остановить, и systemd послушно не лезет обратно. Пауза между попытками задаётся RestartSec, чтобы падающий по кругу сервис не рожал шторм перезапусков. Теперь сигнал, который связывает этот блок с двадцатым уроком: при остановке и systemd, и docker stop шлют процессу SIGTERM и дают время на graceful shutdown — ритуал, который мы выстроили в двадцатом уроке, повторять не будем; здесь важно следствие: таймауты остановки в окружении должны быть щедрее вашего shutdown-таймаута, иначе дренаж оборвут принудительно. Замыкает картинку иерархия: systemd следит за процессом и его выходом, Docker — за контейнером (docker run --restart=on-failure или политика restart в compose), а fiber внутри просто корректно обрабатывает SIGTERM — три уровня, один и тот же контракт.

Соберём маршрут, который прошли: go build с CGO_ENABLED=0 превращает проект двадцать второго урока в статический бинарник; multi-stage Dockerfile пакует его в образ, где тулчейн остался в builder-сцене, а в доставку уехал один файл; nginx принимает 80/443, переводит стрелки на 127.0.0.1:8080 и подписывает запросы заголовками X-Forwarded-For и X-Forwarded-Proto; systemd или docker --restart следят, чтобы процесс жил, а FromEnv из internal/config читала окружение ровно как в деве. Канон курса не изменился ни на строчку: инстанс на :8080, маршрут /api/tasks, buildApp, страж requireAPIKey — деплой оказался не отдельным режимом, а упаковкой того же кода. Для сравнения дисциплин: в плане курса gin деплой-урок стоит соседний по повестке — сборка, Docker, health-чеки и окружение, — у Fiber-версии в центре nginx-связка с WebSocket-туннелем, и это честное различие маршрутов, а не претензия на превосходство: health-чек вы и сами добавите маршрутом /healthz за пять минут. Честное слово про инструменты: песочница сайта ни docker, ни nginx, ни systemd не исполняет — runner-ов в уроках Fiber нет с первого урока, а интерактивы здесь quiz, predict, fill, order и флешкарты; весь материал урока требует локального тулчейна и тренировочного сервера, и это единственный урок курса, где без виртуалки не обойтись. Полный план — на странице курса Fiber.

Следующий, двадцать четвёртый урок — производительность Fasthttp: почему Fiber быстр, zero allocation и границы применимости. Логика прямая: сегодня мы поставили приложение на боевой сервер, завтра заглянем под капот движка, который этот сервер кормит — и поймём, за счёт чего fiber и выигрывает те самые бенчмарки, и на каких нагрузках быстрые пути fasthttp перестают помогать.