Перейти до вмісту
Onetime Secret Onetime Secret - Docs

Довідник конфігурації

Цей комплексний посібник охоплює всі параметри конфігурації для власних екземплярів Onetime Secret.

Конфігураційні файли

Section titled “Конфігураційні файли”

Onetime Secret використовує кілька конфігураційних файлів:

  • .env - Змінні середовища для загальних налаштувань. Використовуйте для простої конфігурації та розгортань Docker без зміни файлів YAML. (Скопіюйте з .env.example)
  • config/config.yaml - Основна конфігурація додатку з використанням шаблонів ERB. Тут інтегровані змінні середовища, що дозволяє легко бачити, як застосовується кожне налаштування. (Скопіюйте з etc/config.example.yaml)

Основна конфігурація

Section titled “Основна конфігурація”

Основний конфігураційний файл - це config/config.yaml, який використовує шаблони ERB для інтеграції змінних середовища.

Початок роботи:

  1. Скопіюйте приклад: cp etc/config.example.yaml config/config.yaml
  2. Відредагуйте значення відповідно до вашого розгортання
  3. Більшість загальних налаштувань можна перевизначити змінними середовища

Переглянути повний конфігураційний файл: config.example.yaml

Ключові розділи конфігурації

Section titled “Ключові розділи конфігурації”

Ось найважливіші розділи, які ви, ймовірно, захочете налаштувати:

---
:site:
  :host: <%= ENV['HOST'] || 'localhost:3000' %>
  # Вмикає/вимикає https/http при генерації посилань
  :ssl: <%= ENV['SSL'] == 'true' || false %>
  # ВАЖЛИВО: Після встановлення секрет не повинен змінюватися.
  # Обов'язково створіть і збережіть резервну копію в безпечному
  # віддаленому місці. Зміна секрету може призвести до непередбачуваних
  # проблем, таких як неможливість розшифрувати існуючі секрети.
  :secret: <%= ENV['SECRET'] || nil %>
  # Конфігурація API та UI
  :interface:
    :ui:
      # Контролює, чи увімкнено веб-інтерфейс
      # Коли false, показується лише базова пояснювальна сторінка
      :enabled: <%= ENV['UI_ENABLED'] != 'false' %>
      # Конфігурація заголовка
      # Контролює брендинг та навігацію в заголовку сайту
      :header:
        # Перемикач для вмикання/вимикання налаштування заголовка
        :enabled: <%= ENV['HEADER_ENABLED'] != 'false' %>
        # Конфігурація брендингу для логотипу та назви компанії
        :branding:
          # Конфігурація логотипу
          :logo:
            # URL до файлу зображення логотипу
            :url: <%= ENV['LOGO_URL'] || 'DefaultLogo.vue' %>
            # Альтернативний текст для зображення логотипу
            :alt: <%= ENV['LOGO_ALT'] || 'Share a Secret One-Time' %>
            # Куди веде логотип при натисканні
            :href: <%= ENV['LOGO_LINK'] || '/' %>
          # Перевизначення назви компанії (повертається до i18n, якщо не встановлено)
          :site_name: <%= ENV['SITE_NAME'] || 'One-Time Secret' %>
        # Конфігурація навігації
        :navigation:
          # Увімкнути/вимкнути навігацію заголовка повністю
          :enabled: <%= ENV['HEADER_NAV_ENABLED'] != 'false' %>
      # Конфігурація посилань футера
      # Ці посилання з'являються у футері кожної сторінки
      :footer_links:
        # Головний перемикач для вмикання/вимикання всіх посилань футера
        :enabled: <%= ENV['FOOTER_LINKS'] == 'true' || false %>
        # Організовані групи посилань
        :groups:
          - :name: legal
            :i18n_key: web.footer.legals
            :links:
              - :text: Terms of Service
                :i18n_key: terms-of-service
                # Замініть на власний URL умов або використовуйте відносний шлях як /terms
                :url: <%= ENV['TERMS_URL']  %>
                :external: <%= ENV['TERMS_EXTERNAL'] || false %>
              - :text: Privacy Policy
                :i18n_key: privacy-policy
                # Замініть на власний URL конфіденційності або використовуйте відносний шлях як /privacy
                :url: <%= ENV['PRIVACY_URL']  %>
                :external: <%= ENV['PRIVACY_EXTERNAL'] || false %>
          - :name: resources
            :i18n_key: web.footer.resources
            :links:
              - :text: Status
                :i18n_key: status
                # Замініть на URL вашої сторінки статусу, якщо вона у вас є
                :url: <%= ENV['STATUS_URL'] %>
                :external: <%= ENV['STATUS_EXTERNAL'] || true %>
                :icon: signal
              - :text: About
                :i18n_key: web.COMMON.about
                # Замініть на URL вашої сторінки про нас
                :url: <%= ENV['ABOUT_URL'] %>
                :external: <%= ENV['ABOUT_EXTERNAL'] || false %>
          - :name: support
            :i18n_key: web.footer.support
            :links:
              - :text: Contact
                :i18n_key: web.footer.contact
                :url: <%= ENV['CONTACT_URL'] %>
                :external: false
    # Контролює, чи доступні API-ендпоінти. Коли вимкнено, API
    # повністю вимкнено. Запити до /api/* повернуть 404.
    :api:
      :enabled: <%= ENV['API_ENABLED'] != 'false' %>
  # Параметри конфігурації для управління секретами
  :secret_options:
    # Стандартний час життя (TTL) для секретів у секундах
    # Це значення використовується, якщо конкретний TTL не вказано при створенні секрету
    :default_ttl: <%= ENV['DEFAULT_TTL'] || nil %>
    # Доступні варіанти TTL для створення секретів (у секундах)
    # Ці варіанти будуть представлені користувачам при створенні нового секрету
    # Формат: Рядок цілих чисел, що представляють секунди
    :ttl_options: <%= (ENV['TTL_OPTIONS'] || nil) %>
    # Налаштування для поля пароля, яке захищає доступ до секретів
    :passphrase:
      # Вимагати від користувачів вводити пароль при створенні секретів
      :required: <%= ENV['PASSPHRASE_REQUIRED'] == 'true' || false %>
      # Мінімальна кількість символів, необхідна для паролів
      :minimum_length: <%= ENV['PASSPHRASE_MIN_LENGTH'] || 8 %>
      # Максимальна кількість символів, дозволена для паролів
      :maximum_length: <%= ENV['PASSPHRASE_MAX_LENGTH'] || 128 %>
      # Застосовувати вимоги складності (великі, малі літери, цифри, символи)
      :enforce_complexity: <%= ENV['PASSPHRASE_ENFORCE_COMPLEXITY'] == 'true' || false %>
    # Налаштування для генерації паролів (коли користувачі натискають "Згенерувати пароль")
    :password_generation:
      # Стандартна довжина згенерованих паролів
      :default_length: <%= ENV['PASSWORD_GEN_LENGTH'] || 12 %>
      # Набори символів для включення у згенеровані паролі
      :character_sets:
        # Включити великі літери (A-Z)
        :uppercase: <%= ENV['PASSWORD_GEN_UPPERCASE'] != 'false' %>
        # Включити малі літери (a-z)
        :lowercase: <%= ENV['PASSWORD_GEN_LOWERCASE'] != 'false' %>
        # Включити цифри (0-9)
        :numbers: <%= ENV['PASSWORD_GEN_NUMBERS'] != 'false' %>
        # Включити символи (!@#$%^&*()_+-=[]{}|;:,.<>?)
        :symbols: <%= ENV['PASSWORD_GEN_SYMBOLS'] == 'true' || false %>
        # Виключити неоднозначні символи (0, O, l, 1, I) для запобігання плутанини
        :exclude_ambiguous: <%= ENV['PASSWORD_GEN_EXCLUDE_AMBIGUOUS'] != 'false' %>
  # Налаштування реєстрації та автентифікації
  :authentication:
    # Може бути повністю вимкнена, включаючи автентифікацію API.
    :enabled: <%= ENV['AUTH_ENABLED'] != 'false' %>
    # Дозволити користувачам створювати облікові записи. Це можна вимкнути, якщо ви плануєте
    # створювати облікові записи вручну або увімкнути під час налаштування, коли можна
    # створювати облікові записи, а потім вимкнути, щоб запобігти створенню нових
    # облікових записів користувачами.
    :signup: <%= ENV['AUTH_SIGNUP'] != 'false' %>
    # Зазвичай, якщо ви дозволяєте реєстрацію, ви дозволяєте вхід. Але є
    # обставини, коли корисно тимчасово вимкнути автентифікацію.
    :signin: <%= ENV['AUTH_SIGNIN'] != 'false' %>
    # За замовчуванням нові облікові записи повинні підтвердити свою електронну адресу перед
    # тим, як вони зможуть увійти. Це захід безпеки для запобігання спаму
    # та зловживань системою. Якщо ви запускаєте приватний екземпляр або
    # екземпляр для вашої команди чи компанії, ви можете вимкнути цю функцію,
    # щоб полегшити користувачам вхід.
    :autoverify: <%= ENV['AUTH_AUTOVERIFY'] == 'true' || false %>
    # Коли увімкнено, форма секрету на головній сторінці недоступна, якщо
    # користувач не увійшов. Подібно до вимкненої головної сторінки, але все ще
    # показує заголовок з логотипом та навігаційними посиланнями. Це дозволяє
    # більш обмежувальний режим, де лише автентифіковані користувачі можуть створювати
    # секрети, зберігаючи при цьому навігацію та брендинг сайту.
    :required: <%= ENV['AUTH_REQUIRED'] == 'true' %>
    # Електронні адреси, наведені нижче, отримають автоматичні
    # адміністративні привілеї при створенні облікового запису. Ці
    # облікові записи мають доступ до сторінки, яка показує базову статистику системи.
    # Термін "colonel" використовується замість "admin". "Colonel" (який
    # вимовляється як "kernel") посилається як на захищене ядро
    # системи Linux, так і на військове звання, символізуючи високий рівень доступу
    # до дозволів. Це найменування допомагає уникнути базових автоматизованих атак,
    # які націлені на загальні URL адміністратора або імена ролей.
    :colonels:
      - <%= ENV['COLONEL'] || 'CHANGEME@example.com' %>
  # Функція, схожа на captcha, яка захищає форму зворотного зв'язку
  # від ботів та інших безладь.
  :authenticity:
    :type: <%= ENV['AUTHENTICITY_TYPE'] || 'altcha' %>
    :secret_key: <%= ENV['AUTHENTICITY_SECRET_KEY'] || '<REPLACE_WITH_STRONG_HMAC_KEY>' %>
  # Посилання на документацію. Для onetimesecret.com це
  # docs.onetimesecret.com.
  :support:
    :host: <%= ENV['SUPPORT_HOST'] || nil %>
  :plans:
    :enabled: <%= ENV['PLANS_ENABLED'] == 'true' || false %>
    :stripe_key: <%= ENV['STRIPE_KEY'] || nil %>
  :regions:
    :enabled: <%= ENV['REGIONS_ENABLED'] == 'true' || false %>
    :current_jurisdiction: <%= ENV['JURISDICTION'] || nil %>
  :domains:
    :enabled: <%= ENV['DOMAINS_ENABLED'] == 'true' || false %>
    # Стандартний домен, що використовується для URL посилань. Коли не встановлено або порожньо,
    # використовується site.host.
    :default: <%= ENV['DEFAULT_DOMAIN'] || nil %>
    # Тип кластера визначає, як додаток підтримуватиме
    # кілька доменів. За замовчуванням nil, що означає, що
    # сам додаток відповідає за обробку кількох доменів.
    :cluster:
      :type: <%= ENV['CLUSTER_TYPE'] || nil %>
      :api_key: <%= ENV['APPROXIMATED_API_KEY'] || nil %>
      :cluster_ip: <%= ENV['APPROXIMATED_PROXY_CLUSTER_IP'] || '<CLUSTER_IP>' %>
      :cluster_host: <%= ENV['APPROXIMATED_PROXY_CLUSTER_HOST'] || '<CLUSTER_HOST>' %>
      :cluster_name: <%= ENV['APPROXIMATED_PROXY_CLUSTER_NAME'] || '<CLUSTER_NAME>' %>
      :vhost_target: <%= ENV['APPROXIMATED_PROXY_VHOST_TARGET'] || '<VHOST_TARGET>' %>
:features:
  :incoming:
    :enabled: false
    :email: CHANGEME@example.com
    :passphrase: abacus
# Конфігурація Redis
:redis:
  # Основний URI підключення Redis - Вкажіть повний рядок підключення, включаючи автентифікацію
  # Формат: redis://[:password@]host[:port]/[db-number]
  # Приклади:
  #   - redis://mypassword@localhost:6379/0        # Проста автентифікація паролем
  #   - redis://user:pass@localhost:6379/0         # Автентифікація ім'я користувача/пароль
  #   - redis://redis.example.com:6379/0          # Без автентифікації (тільки розробка)
  :uri: <%= ENV['REDIS_URL'] || 'redis://CHANGEME@127.0.0.1:6379/0' %>


# Конфігурація логування
:logging:
  # Журнали HTTP-запитів (Rack::CommonLogger)
  :http_requests: <%= ENV['LOG_HTTP_REQUESTS'] != 'false' %>


# Відправлення електронної пошти
:emailer:
  # Локальна розробка з Mailpit
  # -----------------------------
  # Mailpit - це SMTP-сервер для розробки, який захоплює листи для тестування
  # Встановлення: brew install mailpit
  # Запуск: mailpit
  # Веб UI: http://localhost:8025
  #
  #  :mode: smtp                      # Використовуйте режим SMTP для локального тестування
  #  :from: secure@onetimesecret.com # Адреса відправника
  #  :fromname: OTS Support          # Ім'я відправника
  #  :host: 127.0.0.1                # Хост Mailpit
  #  :port: 1025                     # Стандартний SMTP-порт Mailpit
  #  :user: ~                        # Автентифікація не потрібна для Mailpit
  #  :pass: ~                        # Автентифікація не потрібна для Mailpit
  #  :auth: false                    # Вимкнути SMTP-автентифікацію для Mailpit
  #  :tls: false                     # Вимкнути TLS для локального тестування


  # Налаштування продукції (для довідки)
  # ----------------------------------
  :mode: <%= ENV['EMAILER_MODE'] || 'smtp' %>
  :from: <%= ENV['FROM_EMAIL'] || ENV['FROM'] || 'CHANGEME@example.com' %>
  :fromname: <%= ENV['FROMNAME'] || 'Support' %>
  :host: <%= ENV['SMTP_HOST'] || 'smtp.provider.com' %>
  :port: <%= ENV['SMTP_PORT'] || 587 %>
  :user: <%= ENV['SMTP_USERNAME'] %>
  :pass: <%= ENV['SMTP_PASSWORD'] %>
  :auth: <%= ENV['SMTP_AUTH'] || 'login' %>
  :tls: <%= ENV['SMTP_TLS'] %>


:mail:
  :truemail:
    # Доступні типи перевірки: :regex, :mx, :mx_blacklist, :smtp
    :default_validation_type: :regex
    # Обов'язково для перевірки :smtp
    :verifier_email: <%= ENV['VERIFIER_EMAIL'] || 'CHANGEME@example.com' %>
    #:verifier_domain: <%= ENV['VERIFIER_DOMAIN'] || 'example.com' %>
    #:connection_timeout: 2
    #:response_timeout: 2
    #:connection_attempts: 3
    #:validation_type_for:
    #  'example.com': :regex
    #
    # Truemail перевірятиме лише електронні адреси, які відповідають
    # доменам, перерахованим у :allowed_domains. Якщо домен не
    # вказаний, електронна адреса завжди вважатиметься недійсною.
    :allowed_domains_only: false
    #
    # Електронні адреси з цього списку завжди будуть дійсними.
    #:allowed_emails: []
    #
    # Електронні адреси з цього списку завжди будуть недійсними.
    #:blocked_emails: []
    #
    # Адреси з цими доменами завжди будуть дійсними
    #:allowed_domains: []
    #
    # Адреси з цими доменами завжди будуть недійсними
    #:blocked_domains: []
    #
    # Виключити ці IP-адреси з процесу пошуку MX.
    #:blocked_mx_ip_addresses: []
    #
    # Сервери імен для використання для пошуку записів MX тощо.
    # За замовчуванням CloudFlare, Google, сервери Oracle/OpenDNS.
    :dns:
      - 1.1.1.1
      - 8.8.4.4
      - 208.67.220.220
    #:smtp_port: 25
    #
    # Завершити перевірку smtp після першої недійсної відповіді замість
    # повторної спроби з наступним сервером. Може скоротити час
    # перевірки електронної адреси, але може не виявити всі проблеми.
    :smtp_fail_fast: false
    #
    # Аналізувати вміст повідомлення про помилку SMTP, щоб визначити, чи
    # електронна адреса дійсна. Це може бути корисно для деяких SMTP-серверів,
    # які не повертають точних відповідей.
    :smtp_safe_check: true
    #
    # Чи вимикати потік пошуку RFC MX. Коли true, тільки DNS
    # перевірка буде виконана для записів MX та Null MX.
    :not_rfc_mx_lookup_flow: false
    #
    # Перевизначити стандартний шаблон регулярного виразу для електронних адрес
    # та/або вмісту в повідомленнях про помилки SMTP.
    #:email_pattern: /regex_pattern/
    #:smtp_error_body_pattern: /regex_pattern/
    #
    # Логувати в консоль, файл або обидва. Процес ruby повинен мати
    # доступ на запис до файлу журналу. Файл журналу буде створено, якщо він
    # не існує. Ротація файлу журналу не обробляється додатком.
    :logger:
      # Один з: :error (за замовчуванням), :unrecognized_error, :recognized_error, :all.
      :tracking_event: :error
      :stdout: true
      # log_absolute_path: '/home/app/log/truemail.log'


:internationalization:
  :enabled: <%= ENV['I18N_ENABLED'] == 'true' || false %>
  :default_locale: <%= ENV['I18N_DEFAULT_LOCALE'] || 'en' %>
  :fallback_locale:
    fr-CA: [fr_CA, fr_FR, en]
    fr: [fr_FR, fr_CA, en]
    de-AT: [de_AT, de, en]
    de: [de, de_AT, en]
    it: [it_IT, en]
    pt: [pt_BR, en]
    default: [en]
  # Список кодів мов ISO (наприклад, 'en' для англійської, 'es'
  # для іспанської тощо). Є відповідний файл у src/locales
  # з тим самим ім'ям, що містить перекладений текст. Якщо він не
  # вибраний автоматично, користувачі можуть вибрати бажану
  # мову за допомогою перемикача у футері або в модальному вікні налаштувань,
  # якщо вони увійшли в систему.
  :locales:
    - bg
    - da_DK
    - de
    - de_AT
    - el_GR
    - en
    - es
    - fr_CA
    - fr_FR
    - it_IT
    - ja
    - ko
    - mi_NZ
    - nl
    - tr
    - uk
    - pl
    - pt_BR
    - sv_SE


:experimental:
  # ФУНКЦІЯ БЕЗПЕКИ: Контролює, чи може додаток працювати без
  # site.secret (або в цьому файлі, або через змінну середовища SECRET).
  #
  # ЗА ЗАМОВЧУВАННЯМ: false (додаток не запуститься, якщо site.secret є nil)
  #
  # ПОПЕРЕДЖЕННЯ: Встановлення true представляє значні ризики безпеки:
  # - Секрети можуть зберігатися без належного шифрування
  # - Можливий несанкціонований доступ до конфіденційних даних
  # - Цілісність секретного посилання не може бути гарантована
  #
  # ДОПУСТИМІ ВИПАДКИ ВИКОРИСТАННЯ (тільки тимчасово):
  # 1. ВІДНОВЛЕННЯ: Ви випадково запустили з nil секретом і вам потрібно відновити
  #    існуючі секрети, створені в той час. Увімкніть тимчасово до тих пір, поки
  #    всі постраждалі секрети не закінчаться (максимальний період TTL).
  # 2. МІГРАЦІЯ: Під час контрольованої міграції між схемами шифрування,
  #    з належними заходами безпеки.
  #
  # ПОВЕДІНКА ПРИ TRUE:
  # - Додаток запускається без збою
  # - Попередження з'являються в журналах при запуску
  # - При розшифруванні CipherErrors зі справжнім секретом викличуть
  #   автоматичну повторну спробу з nil секретом
  #
  :allow_nil_global_secret: <%= ENV['ALLOW_NIL_GLOBAL_SECRET'] == 'true' || false %>
  # ФУНКЦІЯ БЕЗПЕКИ: Підтримка ротації глобального секрету
  #
  # ФОРМАТ: Масив рядків, що містять попередні значення секретів
  # ["old_secret_1", "old_secret_2", "oldest_secret"]
  #
  # ВИКОРИСТАННЯ: При ротації секретів додайте старі значення сюди, встановлюючи новий основний
  # секрет у site.secret або змінну середовища SECRET. Додаток буде:
  # 1. Використовувати поточний основний секрет для всіх нових шифрувань
  # 2. Пробувати кожен ротований секрет (по порядку) для розшифрування, коли основний не вдається
  #
  # ОБСЛУГОВУВАННЯ: Видаліть секрети з цього списку після того, як відповідні секрети
  # закінчилися або були успішно перешифровані з поточним
  # основним секретом. Проста настанова - це максимальний TTL у `ttl_options`.
  :rotated_secrets: []
  # Коли встановлено true, Rack::Builder#freeze_app заморожує стек проміжного ПЗ
  # після ініціалізації, щоб запобігти будь-яким змінам під час виконання в ланцюзі
  # проміжного ПЗ додатку. Це захід безпеки, який запобігає шкідливому
  # коду від впровадження нового проміжного ПЗ.
  #
  # Ефекти:
  # - Заморожує стек проміжного ПЗ, запобігаючи додаванню/видаленню після завантаження
  # - Заморожує об'єкт додатку, переданий до Rack::Builder
  # - Не впливає на змінюваність об'єктів запиту/відповіді
  #
  # Примітка: Це налаштування може допомогти зробити ваш додаток більш безпечним, запобігаючи
  # маніпуляціям з ланцюгом проміжного ПЗ під час виконання. Для більшості додатків це
  # має бути увімкнено в продуктивних середовищах.
  :freeze_app: false
  # Конфігурація проміжного ПЗ
  # Контролює, які компоненти проміжного ПЗ безпеки та продуктивності увімкнені
  :middleware:
    # Обслуговувати статичні файли для фронтенд-додатку vue
    :static_files: true
    # Санітизує параметри запиту для забезпечення належного кодування UTF-8
    # Запобігає атакам на основі кодування та неправильному вводу
    :utf8_sanitizer: true
    # Захищає від атак міжсайтової підробки запиту (CSRF)
    # Перевіряє, що запити походять з того ж сайту
    :http_origin: false
    # Екранує HTML-сутності в параметрах запиту
    # Допомагає запобігти атакам XSS через параметри запиту
    :escaped_params: false
    # Встановлює заголовок X-XSS-Protection для увімкнення фільтрації XSS у браузері
    # Сучасні браузери менше покладаються на це, оскільки CSP стає стандартом
    :xss_header: false
    # Запобігає вбудовуванню вашого сайту в фрейми (захист від кліквджекінгу)
    # Встановлює заголовок X-Frame-Options на SAMEORIGIN або DENY
    :frame_options: false
    # Блокує атаки обходу каталогів з використанням "../" у шляхах
    # Критично для запобігання несанкціонованого доступу до файлів
    :path_traversal: false
    # Захищає від атак підкидання cookies
    # Запобігає фіксації сесії через маніпульовані cookies
    :cookie_tossing: false
    # Запобігає атакам підміни IP, перевіряючи IP-адреси
    # Корисно, коли реалізовано контроль доступу на основі IP
    :ip_spoofing: false
    # Примушує всі з'єднання використовувати HTTPS через заголовки HSTS
    # Вимикайте тільки для розробки або коли за безпечним проксі
    :strict_transport: false
  # Коли увімкнено, додає заголовки Content-Security-Policy до відповіді. Коли
  # `development.enabled=true`, заголовки будуть менш обмежувальними, але все одно
  # запобігатимуть завантаженню будь-якого вмісту з інших джерел. У звичайному продуктивному режимі
  # безпечний nonce буде включено до заголовків, а небезпечний вбудований вміст
  # буде повністю заблоковано. Nonce можна отримати через об'єкт запиту rack
  # `req.env['ots.nonce']`. Бекенд-представлення беруть його звідти, щоб додати його до всіх
  # фронтенд-скриптів та стильових ресурсів автоматично. Вам потрібно було б використовувати
  # nonce тільки якщо ви додаєте нові залежності скриптів або стилів.
  # Коли вимкнено, жодні csp-заголовки не включаються в жодному середовищі.
  :csp:
    :enabled: <%= ENV['CSP_ENABLED'] == 'true' || false %>