Конфигурация и настройка сервера

Восемнадцатый блок прошлого урока обещал ровно три вещи, и сегодня мы их исполняем. Первая: тег ${pid} из таблицы тегов перестанет быть диковинкой — с Prefork родительский процесс плодит воркеров, и в общем журнале строки легко разнести по процессам именно по PID. Вторая: graceful shutdown — это в том числе судьба последних строк журнала: слушатель закрыт, но запросы в полёте должны дописать свои записи, а буферы — дойти до потока. Третья: поток ошибок fiberlog на stderr и журнал запросов на stdout при настройке сервиса systemd получают буквальные пути — Stdout и Stdout-сосед Stderr в описании юнита, два файла, две судьбы.

Ключ «graceful shutdown fiber» ведёт поиск не к конфигу, а к сценарию остановки, и это не случайно: конфигурация сервера — это три biography-вопроса, заданные одному процессу. Как ты рождаешься: кто слушает порт и сколько тебя таких. Как ты живёшь: сколько байт читаешь, сколько секунд ждёшь, кого пускаешь. Как ты умираешь: успеваешь ли дописать журнал и ответить последним клиентам. Fiber v3 раскладывает эти вопросы по разным структурам, и путаница между ними — главный источник сломанных миграций с v2. Дальше по уроку: карта полей fiber.Config, таймауты по одному, механика Prefork с SO_REUSEPORT, канон сигналов и env-конфигурация — всё с цитатами из исходников.

Главное структурное знание урока: в v3 конфигурация живёт на двух этажах. Первый — fiber.Config, аргумент fiber.New: он описывает поведение приложения на уровне запросов — BodyLimit, таймауты, ErrorHandler, AppName; в документации v2 этот объект называли Settings, и старый термин до сих пор всплывает в поиске, хотя в исходниках v3 структура носит имя Config. Второй — fiber.ListenConfig, второй аргумент app.Listen: он описывает старт процесса — TLS, сеть, startup-сообщение, Prefork. И вот то, что ломает половину существующих гайдов: поля Prefork и DisableStartupMessage, которые в v2 были частью fiber.Config, в v3 из Config исчезли. В ListenConfig их преемники называются EnablePrefork и DisableStartupMessage — комментарий исходника формулирует назначение прямо: When set to true, this will spawn multiple Go processes listening on the same port. Логика переезда честная: всё, что касается слушателя и процессов, — это не «поведение приложения», а «способ запуска», поэтому место ему рядом с Listen.

Третий этаж — конфиги самих middleware: у logger.New и cache.New из прошлых уроков свои структуры Config, и они не имеют ничего общего с fiber.Config. Фабрики из шестого урока вы уже настраивали — порядок requestid → logger → recover задаётся порядком app.Use, а не полем конфига. Стало быть, «настроить Fiber» — это всегда три разных литерала структуры: fiber.Config, ListenConfig и конфиги слоёв. Часть полей fiber.Config мы уже невольно трогали: ErrorHandler из четырнадцатого урока — тоже поле этого конфига, как и Views из тринадцатого. Сегодня соберём всю карту целиком.

Три таймаута — единственные поля дефолтного конфига, которые нельзя оставить нетронутыми в продакшене, потому что их дефолт — unlimited, бесконечность. ReadTimeout — время, отведённое на чтение всего запроса, включая тело; комментарий исходника уточняет две вещи: дедлайн чтения выставляется в момент открытия соединения, и он сбрасывается, когда хендлер вернулся. Это защита от медленного клиента, который открывает TCP-соединение и тянет заголовки по байту в минуту — класс Slowloris-атаки: без ReadTimeout такие соединения копятся и съедают лимит Concurrency, который по умолчанию равен 256 * 1024 и потому кажется неисчерпаемым. WriteTimeout ограничивает запись ответа — от «клиент на модемном подключении читает файл час» до «противник тянет ответ, не подтверждая пакеты». IdleTimeout — самый коварный: это пауза между запросами внутри одного keep-alive-соединения, когда всё уже прочитано и записано, а клиент молчит, надеясь отправить следующий запрос по тому же соединению.

С IdleTimeout связана единственная в этой тройке неочевидная связка, зафиксированная в комментарии к полю дословно: If IdleTimeout is zero, the value of ReadTimeout is used — нулевой IdleTimeout наследует ReadTimeout. Это не баг, а конвенция: сервер, который ограничил чтение, но забыл про простой, всё равно не даст соединениям висеть вечно. Отдельно стоит ReadBufferSize — 4096 байт на соединение; он же ограничивает максимальный размер заголовков, и его приходится поднимать, когда клиенты шлют большие cookies или длинные RequestURI — комментарий предлагает именно этот сценарий.

Таймауты и graceful shutdown кажутся соседями по оглавлению, но не более того — пока не читаешь документацию ShutdownWithTimeout целиком. Последняя строка её описания в app.go — приговор наивной конфигурации: ShutdownWithTimeout does not close keepalive connections so its recommended to set ReadTimeout to something else than 0. Механика такая: при остановке сервер закрывает слушатель и ждёт, пока соединения вернутся в idle, но keep-alive-соединения он принудительно не рвёт — он ждёт, что клиент сам отправит следующий запрос или закроет соединение. Если ReadTimeout и IdleTimeout остались бесконечными, а браузер держит открытое соединение в фоне, дренаж рискует затянуться на всё время жизни чужого таба.

Отсюда практический вывод, который стоит записать в чек-лист любого сервиса: ShutdownWithTimeout задаёт потолок ожидания, а таймауты конфига делают этот потолок достижимым. Сервер с ReadTimeout 5 секунд и ShutdownWithTimeout 10 секунд гарантированно освободится: даже молчащее keep-alive-соединение умрёт по таймауту чтения и не удержит дренаж. Это же объясняет, почему нельзя «для надёжности» оставить таймауты нулевыми и положиться на shutdown-таймаут: вежливое завершение не должно зависеть от дисциплины чужих клиентов. Связка «таймауты в конфиге + дедлайн в shutdown» — пример того, как два несоседних поля конфигурации работают в паре.

Prefork — единственная настройка Fiber, которая меняет количество процессов. Включатель называется EnablePrefork и живёт в ListenConfig; исходник prefork.go описывает механику одной фразой: prefork manages child processes to make use of the OS REUSEPORT feature. Мастер-процесс запускает дочерние Go-процессы — не горутины, а настоящие exec-процессы, по одному на ядро: число процессов в стартовом сообщении равно runtime.GOMAXPROCS(0). Каждый ребёнок открывает собственный сокет на том же порту с флагом SO_REUSEPORT — это возможность ядра Linux, позволяющая многим сокетам слушать один адрес, — и ядро само распределяет входящие соединения между сокетами. Функция IsChild() из корневого пакета позволяет коду понять, кто он: мастер или воркер.

Когда Prefork нужен: CPU-загруженный сервис (тяжёлые вычисления, компрессия, криптография) на многоядерном хосте, где один процесс Go упирается в ядро. Когда вреден: на машинах с малым числом ядер, в контейнерах с жёсткими лимитами CPU, и всегда — когда приложение держит общее состояние в памяти, потому что состояние процесса локально. Отдельное ограничение сети зафиксировано в ListenConfig предупреждением: при prefork допустимы только сети tcp4 и tcp6 — Unix-сокеты не поддерживаются. Аварийность зашита в конфиг: PreforkRecoverInterval задаёт паузу перед перезапуском упавшего ребёнка (дефолт — мгновенно), PreforkRecoverThreshold — максимум рестартов, после которого мастер сдаётся (дефолт max(1, runtime.GOMAXPROCS(0) / 2)), а PreforkShutdownGracePeriod — сколько мастер ждёт детей после SIGTERM, прежде чем послать SIGKILL: по умолчанию 5 * time.Second.

Мост из прошлого урока исполняется здесь. Startup-сообщение fiber — тот самый ASCII-арт с адресом — печатает не только адрес и версию: prepareListenData в listen.go собирает ListenData с полями PID, ProcessCount, ChildPIDs и Prefork, и в сообщении видны строки PID (текущий процесс), Prefork: Enabled или Disabled и Total process count. У прошлого урока было объяснение, почему тег ${pid} есть в словаре logger: без Prefork он всегда печатает одно число и кажется балластом, с Prefork — это единственный способ в общем журнале понять, какой из воркеров написал строку. Журнал собирается с stdout всех процессов в один поток journald или docker logs, и PID — ключ группировки.

Startup-сообщение тоже настраивается, и не только DisableStartupMessage. Цвета гасятся знакомыми по девятнадцатому уроку переменными TERM=dumb и NO_COLOR=1 — тот же механизм isatty, что у access-лога. EnablePrintRoutes печатает таблицу всех маршрутов с методом, путём и хендлером — удобно на старте сверять развернутое с ожидаемым. И важно для контейнеров: в prefork-режиме сигнал остановки должен доставляться каждому процессу — оговорка из ListenConfig, к которой мы вернёмся в блоке про GracefulContext, гласит, что контекст гасит только тот процесс, в котором он отменён. Мастер и дети — отдельные адресаты сигналов, и systemd в этом случае видит дерево процессов, а не один PID.

Термин graceful shutdown fiber означает сценарий: сервер прекращает принимать новые запросы, дождывается тех, что в полёте, отпускает ресурсы и выходит — ничего не потеряно и ничего не оборвано. Это тот же инвариант, что в финальном проекте курса go-advanced, где канон graceful shutdown собирался на каналах: закрыть приём работы — дождаться бригады через WaitGroup — и только потом закрыть выход. Здесь роли другие, но последовательность та же: вместо закрытого канала — закрытый слушатель, вместо WaitGroup — дренаж inflight-хендлеров, вместо чтения остатков канала — дописанные строки журнала из прошлого урока.

API v3 умещается в три метода. app.Shutdown() — вежливая остановка без дедлайна, под капотом это ShutdownWithContext(context.Background()). app.ShutdownWithTimeout(timeout time.Duration) — тот же сценарий с потолком ожидания; документация описывает механику: сначала закрываются все открытые слушатели, затем сервер ждёт, пока соединения вернутся в idle. app.ShutdownWithContext(ctx) — общий случай: если дедлайн контекста истёк, сервер останавливается принудительно, включая force-закрытие. Три полезных факта из исходников. Первый: вызов shutdown на незапущенном сервере не паникует, а возвращает ErrNotRunning с текстом shutdown: server is not running. Второй: в error.go объявлена и ошибка дедлайна — ErrGracefulTimeout, shutdown: graceful timeout has been reached, exiting. Третий: у процедуры есть хуки — OnPreShutdown выполняются до дренажа, OnPostShutdown получают финальную ошибку после: места, чтобы закрыть базу и зафиксировать в логе итог остановки.

Ручная горутина с signal.Notify — универсальный путь, но у ListenConfig есть штатная кнопка: поле GracefulContext. Документация поля формулирует задачу прямо: поле нужно, чтобы гасить Fiber по данному контексту вежливо. Вы передаёте контекст, отменяете его из своего обработчика сигналов — и Listen сам заводит горутину graceful shutdown: в исходнике Listen видно stop-канал с defer close(stop) и вызов app.gracefulShutdown, который при отмене контекста вызывает ShutdownWithTimeout с значением поля ShutdownTimeout. Дефолт этого поля — 10 * time.Second; правило из комментария стоит запомнить дословно: Negative disables the timeout and waits indefinitely; zero applies the default — отрицательное значение отменяет потолок и ждёт бесконечно, ноль подставляет дефолт.

Экономия — в двух строках вместо горутины, но настоящая ценность — в prefork-оговорке, которую ListenConfig несёт в комментарии к тому же полю: With EnablePrefork the context stops only the process it is canceled in; deliver the signal to every process so each child drains its own connections. Контекст гасит только тот процесс, в котором его отменили: под Prefork сигнал нужно доставить каждому воркеру, чтобы каждый осушил собственные соединения. Ручная горутина в детях с IsChild() и адресная доставка сигналов дают контроль, которого у общего контекста нет. Для одиночного процесса GracefulContext — самый короткий корректный путь; для prefork-кластера — деталь, о которой нужно знать заранее, а не обнаруживать по оборванным журналам.

Одно и то же приложение в деве, стейджинге и проде должно получать разные лимиты и таймауты, и канонический способ — переменные окружения: их задают docker compose, Kubernetes и systemd через Environment или EnvironmentFile. Честный факт: встроенной поддержки env в fiber.Config нет — ни поле не читает os.Getenv само, ни fiber.New не принимает файл настроек. Это осознанная простота: конфигурация — это ваш код между env и fiber.Config, и он обычно занимает экран. Правила хорошей фабрики конфига три. Первое: читайте env явно и типизированно — strconv.Atoi для целых, strconv.ParseFloat для долей, time.ParseDuration для таймаутов, потому что 5 * time.Second в окружении живёт как строка «5s». Второе: мусор в env не должен ронять старт — неверное значение заменяется дефолтом, а решение записывается в журнал при старте. Третье: дефолты Fiber разумны, и поле BodyLimit тому пример — исходник прямо говорит, что ноль и отрицательные значения откатываются к дефолту, так что «ошибка парсинга → оставить ноль» безопасна не для всех полей, но для лимитов — да.

Тот же принцип работает для ListenConfig: EnablePrefork удобно вешать на строку «1» в FIBER_PREFORK, а порт — на PORT. Одна оговорка: не тащите в env то, что имеет смысл фиксировать в коде — ErrorHandler и маршруты не конфигурируются окружением, они часть программы.

Сервис под systemd — место, где все три темы урока встречаются в одном текстовом файле. Юнит запускает бинарник, и ExecStart получает процесс; когда администратор делает systemctl stop, systemd по умолчанию шлёт главному процессу SIGTERM — это настраивается директивой KillSignal, — ждёт TimeoutStopSec (дистрибутивные дефолты обычно 90 секунд) и затем убивает всё дерево SIGKILL. Сопоставьте с уроком: ваш ShutdownTimeout 10 секунд укладывается в любой разумный TimeoutStopSec, дренаж успевает, OnPostShutdown срабатывает, journalctl получает последнюю строку. Если же дренаж длиннее таймаута юнита, вы увидите статус timeout и killed — тот же сценарий, что в quiz про SIGKILL, только в форме systemd.

Два потока журнала из прошлого урока здесь получают адреса: StandardOutput=journal и StandardError=journal по умолчанию собирают stdout и stderr в один журнал, но их можно развести в файлы или сокеты — access-лог и события fiberlog окажутся в разных местах, как и обещал девятнадцатый урок. Для prefork-сервиса важно, что systemd по умолчанию следит за главным процессом; KillMode=control-group гасит всю группу — и воркеров тоже, каждый со своим дренажом, если сигнал доставлен каждому. Всё это — конфигурация вне Go, но именно она определяет, выполнится ли graceful shutdown, который вы написали в коде: код задаёт поведение остановки, окружение задаёт время на его исполнение.

Соберите канон урока: конфиг с таймаутами, logger.New, /api/tasks и горутина сигналов. Клиент — curl, сценарии три. Первый: в одном терминале curl -i http://localhost:8080/api/tasks, во втором kill -TERM $(pgrep tasks-api) — сервер допечатывает ответ, печатает строку журнала, Listen возвращается, main выводит финальную строку. Второй: добавьте хендлер с time.Sleep(3 * time.Second), запустите curl в фоне и сразу шлите SIGTERM — ответ всё равно уезжает целиком: inflight-запросы дожидаются внутри дренажа, в этом весь смысл graceful. Третий: проверьте таймаут конфига — curl с удавкой --max-time 1 на медленный хендлер даст клиентский таймаут раньше серверного, а хендлер, читающий тело дольше ReadTimeout, получит обрыв со стороны сервера.

Честное слово про инструментарий: песочница сайта сетевые сценарии не исполняет — runner-ов в уроках Fiber нет с первого урока, интерактивы здесь quiz, predict, fill, order и флешкарты; сигналы и prefork проверяются только локально, где у процесса есть настоящий PID и настоящие потоки. Материал держится на исходниках ветки main ядра fiber v3.5.0: app.go — Config и DefaultErrorHandler, listen.go — ListenConfig, startup-сообщение и gracefulShutdown, prefork.go — SO_REUSEPORT и восстановление детей, error.go — ErrNotRunning и ErrGracefulTimeout. Полный план курса — на странице курса Fiber.

Следующий, двадцать первый урок — тестирование Fiber-приложений: app.Test, httptest и юнит-тесты хендлеров. Связь с сегодняшней темой прямая. Во-первых, фабрика configFromEnv из этого урока просится под тесты: t.Setenv подставляет окружение, app.Test прогоняет запрос через приложение без сети — и вы проверяете, что мусорная переменная действительно оставила дефолт. Во-вторых, у app.Test есть TestConfig с полем Timeout и управлением FailOnTimeout — таймауты, о которых мы говорили в масштабе сервера, возвращаются в масштабе теста. В-третьих, graceful shutdown тоже тестируется: хендлер с задержкой, ShutdownWithTimeout и наблюдение, что ответ уехал, — это обычный тест с goroutine. Конфигурация, которую нельзя проверить тестом, — это надежда, а не конфигурация; двадцать первый урок даст инструменты, чтобы превратить весь этот урок в зелёный прогон.