CyberTrainРуководстваКонфигурация

Конфигурация

Конфигурация и переменные окружения

ruby
# config/app.rb
Cybertrain.configure do |c|
  c.port = 3000
  c.workers = 1
end

Cybertrain::Config сначала читает переменные окружения; config/app.rb их переопределяет:

Переменная Атрибут По умолчанию
CYBERTRAIN_ENV env "development"; "production" в бинарном файле из cybertrain build (также "test")
PORT port 3000
CYBERTRAIN_DATABASE database_path storage/#{env}.sqlite3
CYBERTRAIN_SECRET_KEY_BASE secret_key_base обязательна в production; в dev/test генерируется автоматически в tmp/secret_key
CYBERTRAIN_ENCRYPTION_KEY encryption_key ""; 64 шестнадцатеричных символа (cybertrain secret --hex), ключ столбцов, которые модель шифрует через encrypts. Запуск завершается ошибкой, если ключ неверного вида или пуст, когда модель объявляет encrypts (см. Зашифрованные столбцы)
CYBERTRAIN_ENCRYPTION_KEY_PREVIOUS encryption_keys_previous []; прежние ключи через запятую, пробуются только для расшифровки, так что ключ меняют, пересохраняя записи; неверная запись останавливает запуск
SPINEL_WORKERS workers 1; сервер разработки игнорирует это значение и всегда работает с одним воркером (почему)
CYBERTRAIN_HOST host "127.0.0.1"; 0.0.0.0 слушает на всех интерфейсах (контейнеры)
CYBERTRAIN_ALLOWED_HOSTS allowed_hosts Режим разработки принимает localhost, 127.0.0.1, [::1]; разделённые запятыми точные имена хостов расширяют этот список (без схемы, порта и подстановочных знаков). Другие хосты получают 403 до статических файлов, сессий, маршрутизации и диагностики. Это не связано с адресом прослушивания; production и test применяют этот список, только когда CYBERTRAIN_HOSTS включает там проверку
CYBERTRAIN_HOSTS hosts_from_env (добавляется к allowed_hosts) []; разделённые запятыми точные имена хостов (IPv6-адрес в квадратных скобках; без схемы, пути, порта и подстановочных знаков, иначе запуск не удаётся), добавляемые после имён loopback во всех окружениях. Если они заданы, проверка хостов включается и в production и test: другой Host получает 403 Blocked host и записывается в лог. GET или HEAD пути проверки здоровья проходит при любом Host (см. Хосты)
CYBERTRAIN_FORCE_SSL force_ssl false; 1 или true перенаправляет http на https (301 для GET и HEAD, 307 для остального; за прокси — по X-Forwarded-Proto), отправляет Strict-Transport-Security: max-age=63072000; includeSubDomains и пишет все cookies с Secure; путь проверки здоровья никогда не перенаправляется. Любое значение, кроме 1, true, 0, false или пустого, останавливает запуск. За прокси задайте также CYBERTRAIN_TRUSTED_PROXY или CYBERTRAIN_TRUSTED_PROXIES, иначе URL, которые строит приложение, останутся http
CYBERTRAIN_SESSION_SAME_SITE session_same_site "Lax"; также Strict или None (None всегда добавляет Secure); любое другое значение останавливает сервер при запуске
CYBERTRAIN_SESSION_PARTITIONED session_partitioned false; 1 или true добавляет Partitioned (и Secure)
CYBERTRAIN_TRUSTED_PROXY trusted_proxy false; 1 или true делает request.client_ip (то, что засчитывает rate_limit) последним адресом X-Forwarded-For соединения с loopback — для обратного прокси на том же хосте (см. Ограничение частоты запросов); сокращение для CYBERTRAIN_TRUSTED_PROXIES=127.0.0.0/8,::1
CYBERTRAIN_TRUSTED_PROXIES trusted_proxies []; разделённые запятыми адреса IPv4/IPv6 или CIDR (172.16.0.0/12,10.0.0.0/8), для соединений с которых request.client_ip берётся из последнего адреса X-Forwarded-For, — для прокси, доступного по сети, например kamal-proxy в его контейнере; неверная запись останавливает сервер при запуске
CYBERTRAIN_MAX_PAGE max_page 10000: наибольшая страница, которую выдаёт params.page_number и принимает Relation#page (см. Постраничный вывод); значение, не являющееся числом не более чем из 18 цифр, или меньше 1 заменяется значением по умолчанию
CYBERTRAIN_FILTER_PARAMETERS filter_parameters ["password", "password_confirmation", "token", "secret", "secret_key_base", "session_key", "api_key", "authorization"]; разделённые запятыми имена заменяют список. Значение параметра, имя которого содержит одно из них (без учёта регистра ASCII: password совпадает и с user[password]), записывается как [FILTERED] в лог запросов и на страницу ошибок режима разработки; [] в config/app.rb это отключает
CYBERTRAIN_LOG_LEVEL log_level :info: наименее важный записываемый уровень, debug, info, warn, error, fatal или none (в любом регистре; none выключает журнал запросов, но строки ошибок пишет); любое другое значение останавливает загрузку (см. Журнал). cybertrain test использует :none, если config/app.rb не задаёт его
CYBERTRAIN_LOG_FORMAT log_format :text; json пишет по одному объекту JSON на строку, для сборщика логов; любое другое значение останавливает загрузку. cybertrain test оставляет текстовые строки, если config/app.rb не задаёт формат, что бы ни говорила переменная
CYBERTRAIN_SENTRY_DSN sentry_dsn "": ничего не отправляется. DSN Sentry или GlitchTip отправляет туда каждый отчёт об ошибке (см. Отчёты об ошибках); нужен require "cybertrain/error_reporter/sentry" (или require "cybertrain") в bin/<app>.rb, иначе загрузка отказывает. Нечитаемый DSN останавливает загрузку, называя неверную часть и никогда ключ. cybertrain test опустошает его, если config/app.rb его не присваивает
CYBERTRAIN_ERROR_SAMPLE_RATE error_sample_rate 1.0: доля отчётов об ошибках, отправляемых в Sentry, от 0.0 до 1.0, записанная цифрами с необязательной .цифрами; подписчики видят каждый отчёт; любое другое значение останавливает загрузку
CYBERTRAIN_RELEASE release "": версия или коммит, отправляемые с каждым отчётом об ошибке
CYBERTRAIN_WORKER worker true; 0 или false не даёт процессу server выполнять задачи по расписанию, фоновые задачи и фиды WebSocket (см. Роли процессов); ./<app> worker и feeds его игнорируют
CYBERTRAIN_JOB_THREADS job_threads 3: сколько задач один процесс выполняет одновременно (см. Фоновая работа); не меньше 1
CYBERTRAIN_TIME_ZONE time_zone "UTC": пояс приложения, имя IANA вроде Asia/Tokyo, для Time.zone, границ дней и месяцев, Date.current, l и time_tag (см. Часовые пояса); пояс, которого нет в zoneinfo системы, останавливает загрузку
CYBERTRAIN_SCHEDULER_TZ scheduler_tz time_zone, если не задан: пояс, в котором читается задача Scheduler.cron без tz:, имя IANA (см. Часовые пояса); пояс, которого нет в zoneinfo системы, останавливает загрузку
CYBERTRAIN_JOBS_PAGE_PER_PAGE jobs_page_per_page 50: строк в списке на странице задач; не меньше 1
CYBERTRAIN_CACHE_PRUNE_INTERVAL cache_prune_interval 300: секунд между очистками истёкших строк кэша, читается при подключении cybertrain/cache; не меньше 1
CYBERTRAIN_FEED_STATUS_INTERVAL feed_status_interval 10: секунд между записями строки состояния каждого фида WebSocket (см. Состояние фидов); не меньше 1
CYBERTRAIN_FEED_RESTART_LIMIT feed_restart_limit 10: перезапусков потока одного фида за окно, после которых процесс feeds завершается со статусом 1, когда фид снова умирает (см. Потребление потоков WebSocket); не меньше 1
CYBERTRAIN_FEED_RESTART_WINDOW feed_restart_window 600: это окно в секундах; не меньше 1
CYBERTRAIN_STREAM_PATH stream_path "/cybertrain/stream": точка входа реального времени (см. Реальное время); пустое значение выключает потоки; путь должен начинаться с / и отличаться от health_path
CYBERTRAIN_REUSE_PORT reuse_port false; 1 или true выполняет bind с SO_REUSEPORT, так что несколько процессов могут слушать один порт, а в Linux ядро распределяет между ними соединения (в разработке игнорируется; см. Running several processes). Задайте CYBERTRAIN_WORKER=0 во всех процессах, кроме одного
CYBERTRAIN_HEALTH_PATH health_path "/up"; путь встроенной проверки работоспособности (см. Эксплуатация); пустое значение её отключает; значение без ведущего / останавливает сервер при запуске. health_worker_stale (300 с) задаётся в config/app.rb
CYBERTRAIN_HEALTH_FEEDS health_feeds true: проверка работоспособности отвечает 503 feed stale и для фида WebSocket, который перестал сообщать состояние или замолчал (см. Состояние фидов); 0 или false отключает эту часть
CYBERTRAIN_HEALTH_FEED_STALE health_feed_stale 180: секунд молчания фида или его процесса, не пишущего состояние, до 503 feed stale; не меньше 1 и, пока включён health_feeds, больше feed_status_interval (иначе загрузка отклоняет значение)
CYBERTRAIN_HTTP_ALLOW_PRIVATE http_allow_private false; 1 или true позволяет Cybertrain::HttpClient подключаться к loopback, частным и другим непубличным адресам (см. Исходящий HTTP)
CYBERTRAIN_SMTP_HOST smtp_host ""; SMTP-сервер, через который отправляет Cybertrain::Mailer (см. Отправка электронной почты)
CYBERTRAIN_SMTP_PORT smtp_port 0: порт режима — 587 для starttls, 465 для tls, 25 для none; всё, кроме значений от 1 до 65535, считается 0
CYBERTRAIN_SMTP_USER smtp_user "": без AUTH; если задано, мейлер аутентифицируется через AUTH PLAIN
CYBERTRAIN_SMTP_PASSWORD smtp_password ""; секрет, никогда не пишется в лог, в стартовый баннер и в сообщения об ошибках
CYBERTRAIN_SMTP_FROM smtp_from "": отправитель, которого использует Mailer.deliver, когда ему не передан from:
CYBERTRAIN_SMTP_TLS smtp_tls "starttls"; также tls (неявный TLS) или none (открытый текст, учётные данные — только на loopback); обоим режимам TLS нужен require "cybertrain/net/tls", который загружает require "cybertrain"
CYBERTRAIN_MAIL_DELIVERY_METHOD mail_delivery_method :test в тестовом окружении, :smtp во всех остальных: :test сохраняет каждое письмо в Cybertrain::Mailer.deliveries вместо отправки (Тестирование почты); вне тестового окружения загрузка идёт с предупреждением, и ничего не отправляется; любое другое значение останавливает загрузку; cybertrain test использует :test, если config/app.rb не задаёт его, что бы ни говорила переменная
CYBERTRAIN_TEST_DATABASE — "": файл, который cybertrain test удаляет, мигрирует и на котором запускает тесты вместо storage/test.sqlite3; путь к файлу (не :memory: и не URI file:). Существующий файл удаляется, только если его создал cybertrain test (он помечает свои базы), если это storage/test.sqlite3 самого приложения или если он пуст; любой другой, как и база разработки или продакшена, отклоняется с кодом выхода 2, и ничего не удаляется (Запуск тестов)
CYBERTRAIN_I18N_DEFAULT_LOCALE i18n_default_locale :en: локаль, с которой начинается каждый запрос, имя вроде ja или pt-BR (см. Локали); всё остальное останавливает загрузку
CYBERTRAIN_AUTH_LOCKOUT_ATTEMPTS auth_lockout_attempts 10: неверных паролей до блокировки учётной записи; 0 отключает блокировку (см. Настройки аутентификации)
CYBERTRAIN_AUTH_LOCKOUT_PERIOD auth_lockout_period 3600: сколько секунд длится блокировка; не меньше 1
CYBERTRAIN_AUTH_REMEMBER_FOR auth_remember_for 2592000 (30 дней): сколько секунд длится вход с «оставаться в системе»; не меньше 1
CYBERTRAIN_AUTH_IDLE_TIMEOUT auth_idle_timeout 604800 (7 дней): через сколько секунд без запросов заканчивается вход; 0 отключает

Используйте None (вместе с CYBERTRAIN_SESSION_PARTITIONED=1) только для приложения, которое показывается во фрейме другого сайта; браузер должен обращаться к приложению по HTTPS.

Другие атрибуты с фиксированными переопределяемыми значениями по умолчанию: views_root ("app/views"), public_root ("public"), layout ("layouts/application"), log_tags ([:request_id]: теги запроса в каждой строке журнала; :remote_ip добавляет адрес клиента, [] не показывает ничего, а любое другое значение останавливает загрузку; см. Идентификаторы запросов), session_cookie_name, session_max_age (2 недели), session_secure (true в production, что помечает cookie сессии как Secure; false в остальных окружениях, хотя SameSite=None и Partitioned всё равно добавляют Secure), pool_size (4), static_files/csrf (true), csrf_exempt_prefixes ([]: префиксы путей, например "/api/", чьи не-GET-запросы пропускают проверку CSRF, — для эндпоинта, который программы вызывают с собственными учётными данными; каждый должен начинаться и заканчиваться на / и не быть просто /, иначе запуск завершается сбоем; префикс сопоставляется с путём в том виде, в каком он отправлен, поэтому percent-кодированное написание всё равно проверяется; ни один другой маршрут не должен совпадать с путём под этим префиксом, а освобождённый контроллер не должен полагаться на сессию для аутентификации, поскольку сессия там всё равно загружается), max_body_bytes (10 МиБ: на более длинное тело запроса, в том виде, в каком оно отправлено, отвечается 413 до его чтения; увеличьте для больших загрузок; распакованный размер тела в gzip ограничивается отдельно через request.decoded_body(limit)), max_render_depth (12 одновременно открытых отрисовок: страница и её партиалы; увеличьте для партиалов, которым обоснованно нужна более глубокая рекурсия; значение должно быть не меньше 1, иначе запуск завершается сбоем). Примечание к обновлению: вложенность отрисовки, прежде неограниченная, теперь по умолчанию ограничена 12 (страница — глубина 1, поэтому партиалы могут вкладываться на 11 уровней; макет отрисовывается после страницы и во вложенность не входит), и приложение с более глубоким деревом (комментарии в виде веток, меню категорий) получает ошибку шаблона, пока не задаст max_render_depth. Загрузка файлов: max_upload_bytes (5 МиБ на загруженный файл; не должен превышать max_body_bytes), max_multipart_parts (128 частей, включая текстовые поля, не более 4096), upload_root ("storage/uploads", куда пишет Cybertrain::BlobStore; создаётся при первой загрузке, а не при запуске).

Задачи и потоки: помимо переменных выше, config/app.rb задаёт scheduler_interval (1 с, такт планировщика), job_poll_interval (1 с, сколько ждёт свободный поток задач; до потоков задач было 5), job_max_attempts (5), job_heartbeat_interval (30 с), job_heartbeat_stale (300 с, больше интервала), job_drain_timeout (10 с, сколько SIGTERM ждёт выполняющиеся задачи) и scheduler_lease_ttl (30 с, не меньше двух scheduler_interval), а также настройки потоков stream_poll_ms, stream_retention, stream_ping_interval, stream_max_connections, stream_max_message и stream_max_backlog (Ограничения и настройки). Значение вне диапазона останавливает запуск с сообщением, которое его называет.

Заголовки безопасности: каждый ответ, который пишет сервер (действия, middleware статических файлов, страницы ошибок и страница диагностики режима разработки, собственные 400/411/413/500 сервера и HEAD), несёт X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN и Permissions-Policy: camera=(), microphone=(), geolocation=(), если только ответ уже не задаёт заголовок с таким именем (в любом регистре): Response#to_http добавляет их после собственных заголовков ответа и только при их отсутствии, поэтому response.set_header("X-Frame-Options", "DENY") в действии отправляет ровно ваше значение, один раз. c.permissions_policy заменяет значение третьего ("camera=(), microphone=(), geolocation=(self)"), "" не отправляет его вовсе, а CR или LF в нём останавливает запуск. Переключателя в Config, чтобы отключить первые два для всего приложения, намеренно нет; встраиваемый виджет переопределяет заголовок в собственных ответах (заголовок Content-Security-Policy: frame-ancestors ... в современных браузерах имеет приоритет над X-Frame-Options). Из-за nosniff браузеры понимают Content-Type буквально: middleware статических файлов знает обычные расширения public/ (html, css, js/mjs, изображения, включая webp и avif, шрифты, wasm, pdf, аудио и видео, json, csv, xml), а всё остальное отдаётся как application/octet-stream, то есть на скачивание; добавьте расширение в Cybertrain::Static::EXTENSIONS, если приложению нужно показывать в браузере другое. Обратный прокси, который сам отдаёт public/, обходит эти заголовки (см. docs/deploy.en.md). Cybertrain::Test::Client вызывает приложение внутри процесса и никогда не сериализует ответ, поэтому эти значения по умолчанию в нём не видны; проверяйте их на response.to_http.

Content Security Policy: по умолчанию выключена, как в Rails; cybertrain new пишет блок ниже закомментированным в config/app.rb. c.content_security_policy do |p| ... end объявляет политику (по методу на директиву, p.script_src :self, "https://cdn.jsdelivr.net"; второй вызов дополняет ту же политику), c.content_security_policy_nonce_directives ([]) называет директивы, которые получают nonce запроса (имя, не являющееся директивой, останавливает запуск), а c.content_security_policy_report_only (false) отправляет заголовок как Content-Security-Policy-Report-Only. Контроллер объявляет собственную копию через content_security_policy do |p|; см. Content Security Policy.

Фильтруемые параметры: строка Started GET "/login?..." в логе запросов и страница ошибок режима разработки (её строка запроса и дамп params и тела JSON) показывают значение каждого параметра, названного в config.filter_parameters, как [FILTERED], как это делает filter_parameters в Rails, поэтому ?token= в URL или пароль, отправленный в форму, которая не прошла проверку, не появляется в логе запросов фреймворка и на странице ошибок режима разработки. Заменяются только значения: остальная часть строки запроса пишется в лог как отправлена (управляющие символы экранируются). Список сопоставляется по подстроке без учёта регистра; расширьте его в config/app.rb (c.filter_parameters = c.filter_parameters + ["otp", "ssn"]) или замените через CYBERTRAIN_FILTER_PARAMETERS. Значения, которые действие пишет в лог само, не фильтруются; там спрашивайте Cybertrain::ParameterFilter.filter?(name) или ParameterFilter.filter_query(text).

Развёртывание: cybertrain build создаёт dist/: бинарный файл dist/NAME со встроенными представлениями, dist/public/ (статические ресурсы; или пусть их отдаёт обратный прокси), а также dist/storage/ (по умолчанию файл SQLite) и dist/tmp/. Запускайте его из dist/ с заданной CYBERTRAIN_SECRET_KEY_BASE; это production, если CYBERTRAIN_ENV не говорит иного, а ./NAME migrate применяет вкомпилированные в него миграции. Бинарный файл говорит только на обычном HTTP/1.1; для TLS и HTTP/2 поставьте перед ним nginx/Caddy (в production cookie сессии имеет флаг Secure, поэтому отдавайте приложение по HTTPS). В production исключение даёт ответ 500, а голый ответ с ошибкой (текстовый 404 маршрутизатора, head :not_found, render plain:) заменяется на public/<status>.html, если такой файл существует; ошибки, которые действие отрисовывает как HTML или JSON, проходят без изменений. SIGTERM прекращает приём соединений, даёт уже выполняющимся запросам завершиться (с ответом Connection: close; простаивающие keep-alive-соединения закрываются сразу) и выходит, когда они закончатся, или по истечении drain_timeout сервера (10 с). Цикл слежения и пересборки никогда не работает в production. docs/deploy.en.md (на японском: docs/deploy.md) проводит через весь процесс: cybertrain new, сервер Ubuntu, systemd, Caddy с HTTPS, повторные развёртывания, откаты и резервные копии.

Kamal: cybertrain new также записывает то, что нужно Kamal 2: Dockerfile, который выполняет cybertrain setup и cybertrain build на этапе сборки в Ubuntu и копирует dist/ в облегчённый этап того же выпуска (миграции при запуске, затем обслуживание на 0.0.0.0:3000), .dockerignore, config/deploy.yml (kamal-proxy с Let's Encrypt перед приложением, проверка работоспособности по public/up.html, файл SQLite на томе в /app/storage) и .kamal/secrets (KAMAL_REGISTRY_PASSWORD и CYBERTRAIN_SECRET_KEY_BASE из окружения). Заполните значения, помеченные CHANGE ME, сделайте коммит и выполните kamal setup; подробности — в docs/deploy-kamal.md (часть 8 учебника по развёртыванию). examples/blog содержит ту же конфигурацию, собранную с фреймворком из этой рабочей копии.

Настройки приложения

Собственные настройки приложения (публичный базовый URL, переключатель функции, интервал, SMTP-хост) объявляются в том же Config с типом, переменной окружения и значением по умолчанию:

ruby
# config/app.rb
Cybertrain.configure do |c|
  c.setting_string :base_url, env: "MYAPP_BASE_URL", default: ""
  c.setting_string :smtp_password, env: "MYAPP_SMTP_PASSWORD", default: "", secret: true
  c.setting_bool :worker, env: "MYAPP_WORKER", default: true
  c.setting_int :prune_interval, env: "MYAPP_PRUNE_INTERVAL", default: 3600, min: 1, max: 9_999_999
end

Cybertrain.config.string_setting(:base_url)
Cybertrain.config.bool_setting(:worker)
Cybertrain.config.int_setting(:prune_interval)

Каждое значение читается один раз, когда config/app.rb выполняется при запуске. Пустая или незаданная переменная означает значение по умолчанию. Булево значение принимает 1/true или 0/false; целое — десятичные цифры (с необязательным ведущим -) в пределах min..max (обе границы необязательны). Любое другое значение заменяется значением по умолчанию, и в лог пишется строка WARN об этом (текстовая при любом log_format: config/app.rb ещё выполняется). Чтение необъявленного имени или имени, объявленного с другим типом, возбуждает ArgumentError, как и повторное объявление имени. Тесты меняют значение через set_string_setting, set_int_setting и set_bool_setting. ./NAME help перечисляет все объявленные настройки с их переменными и значениями по умолчанию, а стартовый баннер выводит текущие значения (=> Settings: base_url="" worker=true ...); настройка с secret: true в обоих местах показывается только по имени, как [FILTERED]. Аксессора Cybertrain.config.base_url нет: в Spinel нет define_method, поэтому читатели — это типизированные методы, принимающие имя.

Локали

ruby
# config/app.rb
Cybertrain.configure do |c|
  c.i18n_default_locale = :en               # или CYBERTRAIN_I18N_DEFAULT_LOCALE
  c.i18n_available_locales = [:en, :ja]
  c.i18n_raise_on_missing = true if c.test?
end

i18n_available_locales ([], только локаль по умолчанию) перечисляет локали, которые принимают I18n.locale= и I18n.locale_available?; при загрузке отвергаются элемент, не являющийся именем локали, и локаль по умолчанию, которой нет в непустом списке. i18n_raise_on_missing (false) заставляет отсутствующий перевод вызывать I18n::MissingTranslationData вместо метки (разработка и тесты) или ключа в читаемом виде (продакшен). Словари и локаль для каждого запроса описаны в разделе Интернационализация.

Настройки аутентификации

Код, который пишет cybertrain generate authentication, читает четыре настройки (переменные — в таблице выше): auth_lockout_attempts (10) и auth_lockout_period (3600 с) для блокировки, auth_remember_for (30 дней) для входа с «оставаться в системе» и auth_idle_timeout (7 дней) для неиспользуемого входа (Оставаться в системе); вход без флажка длится session_absolute_max_age (две недели). Значение вне диапазона останавливает загрузку. Генератор также объявляет настройку приложения base_url из <APP>_BASE_URL, с которой начинаются ссылки в письмах; задайте её с https везде, где работает приложение (Ссылки в письмах).

Часовые пояса

Spinel не поставляется с базой данных tz, а установка ENV["TZ"] для преобразования времени меняет его для всех потоков процесса. Cybertrain::TimeZone вместо этого читает системные файлы часовых поясов: /usr/share/zoneinfo/<name> или $TZDIR/<name>, если задан TZDIR (в облегчённом образе контейнера установите пакет tzdata). Он разбирает TZif версий 1–4 (RFC 8536), включая правило POSIX TZ, на которое «облегчённый» файл опирается после своего последнего перехода, и кэширует каждый пояс на всё время жизни процесса (копирование при записи, поэтому поиск из нескольких воркеров не берёт блокировку).

Всё выражается целыми секундами эпохи Unix. Локальная эпоха — это показание настенных часов, считаемое так, будто это UTC, поэтому арифметика настенного времени — это простое сложение, а TimeZone.civil_to_epoch / TimeZone.epoch_to_civil переводят между ней и [year, month, day, hour, minute, second]:

ruby
tokyo = Cybertrain::TimeZone.find("Asia/Tokyo")
tokyo.found?                         # false для неизвестного имени: тогда пояс ведёт себя как UTC
tokyo.utc_offset_at(Time.now.to_i)   # => 32400
tokyo.abbreviation_at(Time.now.to_i) # => "JST"

# Ближайшие 09:00 в Токио:
now = Time.now.to_i
today = Cybertrain::TimeZone.epoch_to_civil(tokyo.utc_to_local(now))
run = tokyo.local_to_utc(Cybertrain::TimeZone.civil_to_epoch(today[0], today[1], today[2], 9, 0, 0))
run = tokyo.local_to_utc(Cybertrain::TimeZone.civil_to_epoch(today[0], today[1], today[2] + 1, 9, 0, 0)) if run <= now

На переходе на летнее время и обратно local_to_utc детерминирован: настенное время, которое пропускает переход вперёд (02:30 в день перевода часов вперёд в США), читается со смещением до перехода, поэтому попадает после него (03:30 EDT); настенное время, которое повторяет переход назад, даёт более ранний момент. find принимает только относительное имя из символов A-Za-z0-9_+-./ без пустых сегментов и сегментов . или .., поэтому имя пояса, взятое из профиля пользователя, не может добраться до файла вне каталога поясов; неизвестный или некорректный пояс не кэшируется, а "UTC" не нужен файл.

Пояс приложения

ruby
# config/app.rb
Cybertrain.configure do |c|
  c.time_zone = "Asia/Tokyo"   # или CYBERTRAIN_TIME_ZONE; по умолчанию "UTC"
end

c.time_zone принимает имя IANA (собственные имена Rails, такие как «Tokyo», не читаются), и загрузка останавливается на поясе, которого нет в системе. Значения остаются моментами в UTC: столбец, Time.current и календарные методы возвращают Time в UTC, а time.hour — это час UTC. Пояс определяет календарь (beginning_of_day и подобные, Date.current; Время и часовой пояс) и отображение: l(time) и time_tag(time) показывают Time в этом поясе, включая %z и %Z, а datetime у time_tag — это ISO 8601 со смещением пояса (2026-11-12T05:00:00+09:00). l(time, zone: "America/New_York") и time_tag(time, zone: "...") показывают одно значение в другом поясе. Time со смещением 0, то есть любой Time, который выдаёт фреймворк, показывается в поясе; Time, несущий собственное другое смещение (time.getlocal("+05:30")), сохраняет его, если не указан zone:; Date показывается как есть. Задачи cron без tz: тоже следуют этому поясу, если не задан scheduler_tz. Зарегистрированная команда (Main.command), ./<app> jobs и ./<app> console тоже устанавливают пояс перед запуском и отклоняют неизвестный, как загрузка: error: time_zone "Mars/Base" is not a known time zone и код выхода 1, до открытия базы. В cybertrain test каждый тест начинается в настроенном поясе. (Форматы l — в разделе Даты и время.)