Развертывание: бинарник, Docker, graceful shutdown и reverse proxy

Тема «деплой echo» начинается с признания: пока приложение запускается командой go run на машине разработчика, у него нет ни версии, ни владельца, ни способа откатиться. Деплой — это переход от исходников к артефакту: куску, который собран один раз, помечен версией и запускается одинаково в любой среде. Для Go-приложения артефакт обязан радовать компилятор языка: статичный бинарник, в котором уже ничего не нужно ни доустанавливать, ни интерпретировать. Этим деплой echo отличается от многих экосистем: «сборка» — одна команда, «рантайм» — сам бинарник и ядро, а всё остальное — Docker-образ, systemd-юнит, окружение — упаковка одного и того же файла.

План урока следует за жизненным циклом выката: собрать (go build и флаги, которые делают бинарник пригодным для минимального образа), упаковать (multi-stage Dockerfile с HEALTHCHECK по /healthz из двадцать третьего урока), научить останавливаться (graceful shutdown — самая богатая механика урока), прокормить окружением (секрет и порт без пересборки) и поставить на границу сети (systemd на голом хосте или reverse proxy перед контейнером). Каждая ступень проверяется приборами, которые вы уже подключили: пробы, метрики и JSON-логи — это те глаза, без которых выкат не отличается от надежды.

Команда сборки канона выглядит так: CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=$(git describe --tags)" -o bin/server ./cmd/server. Разберём по флагам, потому что каждый решает конкретную деплой-задачу. CGO_ENABLED=0 запрещает компилятору связывать C-код: бинарник получается полностью статичным и работает в пустейшем образе (scratch, distroless/static), где нет ни glibc, ни bash; побочный бонус — кросс-компиляция в GOOS=linux GOARCH=amd64 с любой машины. Для канона на :1323, где все зависимости — чистый Go (echo, echo-jwt, echoprometheus, slog), ноль CGO ничего не отнимает. -trimpath вырезает локальные пути из бинарника: в стектрейсах падают чистые пути модуля вместо /home/z/... — меньше шума в логах и меньше информации наружу. -ldflags "-s -w" отбрасывает таблицу символов и DWARF-отладку: минус четверть веса файла; отладчик для прода не нужен — точную сборку всегда можно пересобрать.

Самое важное — -X main.version=..., которое вшивает значение в переменную пакета main при линковке. В cmd/server/main.go объявляется var version = "dev", логгер печатает её на старте, и вместе с echo-баннером, спрятанным HideBanner из двадцать второго урока, в журнале появляется честный «version=v1.4.0». Теперь на вопрос «а что вообще крутится на сервере» отвечает curl или slog-строка, а не опрос коллег. Канон собран; переезжаем в контейнер.

Docker-образ канона — multi-stage: в первой сцене компилятор, во второй — только артефакт. Builder стартует с golang:1.25-alpine, копирует go.mod/go.sum и качает модули (этот слой кэшируется и не переживает правки кода), копирует исходники и выполняет ту же команду сборки, что и выше. Финальная сцена — alpine или distroless/static: копирует bin/server, объявляет USER nonroot и EXPOSE 1323. Почему не один stage: компилятор весит гигабайты, рантайм — десятки мегабайт; образ-финал без компилятора быстрее качается, имеет меньше CVE и, главное, честно соответствует артефактной модели — в прод уезжает бинарник, а не исходники. USER nonroot — прямое требование безопасности: процесс, слушающий :1323 (порт выше 1024, привилегий не нужно), не обязан быть root в контейнере.

Специфично echo docker-дополнение — HEALTHCHECK, и здесь заходит наблюдаемость из двадцать третьего урока: докер сам опрашивает /healthz и помечает контейнер unhealthy, если проба перестала отвечать. В alpine есть busybox wget, в distroless нет ничего — выбор базового образа определяет синтаксис проверки. Для выходящего HTTPS-трафика (HTTP-клиент из двадцать второго урока зовёт внешние API) финальному образу нужен пакет ca-certificates: без корневых сертификатов TLS-рукопожатие падает, и это одна из самых частых ошибок первого выката — процесс жив, health-пробы зелёные, а исходящие запросы валятся по x509.

Внезапная смерть процесса рвёт все in-flight запросы: пользователь увидел ошибку на честном POST — потому, что вы переезжали с v1.3.0 на v1.4.0. Graceful shutdown — договорённость: при получении сигнала сервер перестаёт принимать новые соединения, дожидается завершения начатых и только потом выходит. Док-комментарий http.Server.Shutdown описывает протокол по шагам: «Shutdown works by first closing all open listeners, then closing all idle connections, and then waiting indefinitely for connections to return to idle and then shut down. If the provided context expires before the shutdown is complete, Shutdown returns the context's error». Словарь: листенеры закрываются — новые запросы не принимаются; idle-соединения закрываются; активные — дожидают своего завершения: платформа ждёт столько, сколько даёт контекст.

Echo оборачивает это одной строкой: e.Shutdown(ctx) — по исходнику echo.go v4.15.0 это «It internally calls http.Server#Shutdown()» на внутреннем Server, а e.Shutdown без аргумента-контекста не существует — контекст задаёт бюджет ожидания. И здесь же ловушка, из-за которой половина graceful-туториалов в интернете не работает: e.Start(":1323") возвращает значение http.ErrServerClosed, когда сервер остановлен через Shutdown — это штатный возврат, а не авария. Если main написан как e.Logger.Fatal(e.Start(":1323")), то штатная остановка упадёт фатальной ошибкой и процесс выйдет с кодом 1 — системы оркестрации считают это сбоем и на ровном месте поднимают тревогу. Правильный main отделяет запуск в горутину и сравнивает ошибку через errors.Is(err, http.ErrServerClosed).

Один образ обязан работать во всех средах — иначе артефактная модель ломается: собирать образ на каждую конфигурацию — дорога к дрейфу «на тесте работало». Двадцать второй урок уже задал канон: prod := os.Getenv("APP_ENV") == "production". Деплой добавляет два обязательных параметра и правило. Параметры: JWT_SECRET (секрет подписи токенов из пятнадцатого урока — его время жить равно времени жить пода, а не образа) и PORT, если :1323 занят или прокси требует другого. Правило: конфигурация читается только в composition root — cmd/server/main.go; слои из двадцать первого урока os.Getenv не зовут: тест передаёт всё параметрами, прод — теми же параметрами, но значения из окружения.

Способы передать: docker run --env-file prod.env (файл рядом с контейнером, в git не попадает), -e JWT_SECRET=... (виден в ps — только для локалки), в systemd — EnvironmentFile=/etc/tasksapp.env (ниже), в оркестраторах — секреты платформы. Запрет один: секреты не должны попадать в образ ни через RUN, ни через --build-arg — слои образа читаются любым, кто скачал его из реестра. Знакомая ситуация: секрет уехал в docker build --build-arg JWT_SECRET=..., слой с ARG остался в истории — образ в реестре теперь «сделан с секретом» навсегда, откати — не откатишь.

Далеко не каждый сервер имеет Kubernetes, и деплой echo обязан уметь жить по-простому: бинарник плюс systemd. Юнит описывает контракт службы: ExecStart=/usr/local/bin/tasksapp-server (тот самый артефакт), EnvironmentFile=/etc/tasksapp.env (тот же prod.env, что у Docker), User=www-data (nonroot не только в контейнере), Restart=on-failure (падение — поднять, остановку — уважить), After=network-online.target. systemd шлёт службе тот же SIGTERM, что и docker stop: graceful shutdown из середины урока работает один в один — это и есть выгода сигнал-контракта: механизм остановки не зависит от упаковки. systemctl enable --now tasksapp включает автозапуск, journalctl -u tasksapp читает stdout со slog-JSON — тот же поток, что собирает Docker.

Перед сервером почти всегда стоит reverse proxy: nginx терминирует TLS, раздаёт статику и держит внешний порт 443. Конфигурация коротка: location / { proxy_pass http://127.0.0.1:1323; } плюс заголовки X-Forwarded-For/Host и правила для длинных соединений — WebSocket из восемнадцатого урока требует Upgrade/Connection, SSE из девятнадцатого — отключённой буферизации. Сетевые тонкости nginx — отдельная вселенная, и повторять их здесь не будем: полный разбор proxy_pass, X-Forwarded-For и hop-by-hop заголовков сделан в уроке fiber о развертывании — механика proxy одинакова, а вашему echo-серверу важно одно: видеть прокси дружелюбно (таймауты http.Server из двадцать второго урока согласованы с proxy_read_timeout) и не доверять вслепую заголовкам клиента.

Канон на :1323 теперь артефакт, а не исходники. Сборка: CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=$(git describe)" — статичный бинарник с версией внутри; file подтверждает «statically linked». Упаковка: multi-stage Dockerfile с кэшем модулей, nonroot, ca-certificates для исходящих HTTPS и HEALTHCHECK по /healthz из двадцать третьего урока. Остановка: signal.NotifyContext по SIGTERM, 8-секундный контекст внутри 10-секундного бюджета, e.Shutdown дожидается завершения HTTP-запросов, hub.Close() закрывает hijacked WebSocket, а errors.Is(err, http.ErrServerClosed) отличает штатный выход от аварии. Окружение: JWT_SECRET и PORT через --env-file или EnvironmentFile, os.Getenv — только в main. Хост без Docker: systemd-юнит с Restart=on-failure и journalctl; перед контейнером — reverse proxy с правилами для Upgrade и SSE.

Про песочницу честно, как во всём курсе: у курса Echo её нет — код исполняется локально, поэтому runner-ов здесь не будет; соберите бинарник, поднимите образ, остановите контейнер под нагрузкой и почитайте логи: Shutdown должен дождаться in-flight запросов, а метрики — показать ноль обрывов на 5-хх.

Следующий, двадцать пятый урок курса echo — Итоговый проект: API на Echo с JWT, валидацией и тестами. Всё, что вы собрали за курс — маршруты, слои, ошибки, тесты, наблюдаемость, деплой, — склеится в один задачник, который можно отдать в портфолио. Навигация по курсу — на странице курса Echo; полный разбор nginx-прокси и заголовков X-Forwarded-For — в уроке fiber о развертывании; пробы и метрики, проверяющие выкат, — в уроке про мониторинг; таймауты http.Server, согласованные с proxy_read_timeout, — в уроке про производительность; composition root, где читается окружение, — в уроке про структуру проекта; hub WebSocket, закрывающий hijacked-соединения, — в уроке про WebSocket.