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

Orbit имеет встроенный движок перенаправлений и переписи, который работает до того, как к вашему проекту поступает запрос. Он настраивается либо в KPanel, либо как файл в вашем репозитории. Это руководство охватывает оба варианта, синтаксис паттернов и их захваты, порядок правил, лимиты и поведение, которое застает людей врасплох.

Где настроить правила

Есть два места, и они оцениваются в фиксированном порядке.

1. В KPanel. Откройте проект в Orbit, перейдите в Settings и прокрутите до раздела redirects and rewrites для окружения. Каждое окружение имеет собственный независимый набор правил, поэтому production и staging настраиваются отдельно.
2. В вашем репозитории, как файл kaps.json. Это подробнее описано ниже.

Правила панели оцениваются первыми. Если ни одно из них не совпадает, то пробуются правила из kaps.json.

Добавление правила в KPanel

1. Нажмите Add rule.
2. Заполните source, паттерн пути для сравнения входящих запросов. Подсказка показывает две формы, которые он ожидает: /old-path or /blog/:slug.
3. Заполните destination. Подсказка показывает /new-path or https://..., поэтому оба варианта, локальный путь и полный внешний URL, допустимы.
4. Выберите тип правила:
   • 301 Permanent: URL переместился окончательно. Браузеры и поисковые системы кэшируют это.
   • 302 Temporary: временное перемещение, не кэшируется. Используйте для кампаний и экспериментов.
   • Rewrite: выдавайте путь места назначения без изменения URL в адресной строке браузера.
5. Нажмите Save rules.

Паттерны исходного пути

Разница между :id и :rest*, это важная. Именованный параметр совпадает с одним сегментом и останавливается перед следующим слешем. Splat совпадает со всем оставшимся, включая слеши.

Использование захватов в месте назначения

Ссылайтесь на именованный параметр по имени, а на простой wildcard как *:

Порядок правил

Правила проверяются сверху вниз, и первое совпадение побеждает. Как только правило совпадает, более поздние правила не рассматриваются. Панель это указывает под списком: "Rules are tested in order. First match wins."

Если ни одно правило не совпадает, запрос обслуживается нормально.

Типичные случаи использования

Переименование страницы

Вы переименовали /about-us на /about и хотите, чтобы старые ссылки продолжали работать.

• Источник: /about-us
• Место назначения: /about
• Тип: 301 Permanent

Перемещение целого раздела

Ваш блог переместился с /news/:slug на /blog/:slug.

• Источник: /news/:slug
• Место назначения: /blog/:slug
• Тип: 301 Permanent

Прокси пути API без видимости

Вы хотите, чтобы /api/v1/* выдавался с другого внутреннего пути без раскрытия изменения.

• Источник: /api/v1/:path*
• Место назначения: /api/internal/:path*
• Тип: Rewrite

Временная страница-заглушка

• Источник: /checkout
• Место назначения: /maintenance
• Тип: 302 Temporary

Отправка трафика на другой домен

Место назначения может быть абсолютным URL, поэтому правило может указывать на совсем другой сайт.

• Источник: /shop/:rest*
• Место назначения: https://shop.example.com/:rest*
• Тип: 301 Permanent

Конфигурация как код с kaps.json

Правила могут находиться в вашем репозитории вместо панели. Добавьте файл kaps.json, и убедитесь, что ваша сборка копирует его в output directory, потому что Orbit читает его из корня встроенного артефакта, а не из корня репозитория.

{
  "redirects": [
    { "source": "/about-us", "destination": "/about", "permanent": true },
    { "source": "/news/:slug", "destination": "/blog/:slug", "permanent": true },
    { "source": "/promo", "destination": "/spring-sale", "permanent": false }
  ],
  "rewrites": [
    { "source": "/api/v1/:path*", "destination": "/api/internal/:path*" }
  ],
  "headers": [
    {
      "source": "/*",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    }
  ]
}

permanent: true создает 301, а permanent: false, 302. Если опустить, создается 301.

Лимиты

• До 100 правил перенаправления и переписи на окружение, и 100 в kaps.json.
• До 200 правил пользовательских заголовков на окружение.

Правила сверх лимита отбрасываются молча, а не вызывают ошибку, поэтому держитесь хорошо ниже лимита.

Пользовательские заголовки ответа

Наряду с перенаправлениями, каждое окружение имеет раздел заголовков ответа в Settings для внедрения HTTP заголовков на совпадающих путях. Он использует тот же синтаксис паттернов пути, и есть быстрые пресеты для HSTS, CSP, no-embed, no-sniff, referrer policy и CORS.

В отличие от перенаправлений, все совпадающие правила заголовков применяются, а не только первое, и более позднее правило перезаписывает более раннее, когда они устанавливают один и тот же заголовок. Content-Length, Transfer-Encoding и Connection заблокированы, потому что их установка повредит ответ.

Поведение, которое стоит знать перед тем как на него полагаться

• Правила совпадают только с путем. Фрагменты (#section) никогда не достигают сервера; браузер переприкрепляет их после перенаправления.
• Переписи на путь, который не существует, создает 404, а не молчаливо падает обратно на исходный путь. Цели переписи должны существовать в вашем выходе сборки.
• Правила работают до того, как ваш проект запрашивается на что-либо, поэтому они применяются как к статическим файлам, так и к серверным запросам.
• Каждое окружение независимо. Правила на production не применяются к staging или превью. Скопируйте их сознательно.

Удаление правила

Нажмите значок мусорной корзины на строке правила, затем нажмите Save rules для применения изменения. Как и при добавлении, изменение вступает в силу со следующего развертывания.

Когда вместо этого использовать функцию Edge

Движок перенаправления обрабатывает правила path-to-path. Обратитесь к функции edge, когда вам нужна логика, которую движок правил не может выразить: ветвление по заголовку или cookie, сохранение или переписывание параметров запроса, взвешенная A/B маршрутизация или что-либо условное.

Дополнительное чтение

• Edge Functions
• Добавление пользовательского домена в ваш проект
• Развертывание вашего проекта