리디렉트 및 재작성 구성

Orbit는 프로젝트가 요청되기 전에 실행되는 내장된 리디렉션 및 리라이트 엔진을 가지고 있으며, KPanel이나 저장소의 파일로 설정할 수 있습니다. 이 가이드는 두 가지 방법, 패턴 구문과 캡처, 규칙 순서, 제한 사항, 그리고 사람들이 놓치기 쉬운 동작을 다룹니다.

규칙을 설정할 위치

두 가지 위치가 있으며, 고정된 순서로 평가됩니다.

1. KPanel에서. Orbit에서 프로젝트를 열고, Settings로 이동한 후, 환경의 redirects and rewrites 섹션으로 스크롤합니다. 각 환경은 독립적인 규칙 세트를 가지므로 프로덕션과 스테이징은 별도로 설정됩니다.
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*의 차이가 중요합니다. 명명된 매개변수는 단일 세그먼트를 매치하고 다음 슬래시에서 중지합니다. 스플릿은 슬래시를 포함하여 나머지 모든 것을 매치합니다.

대상에서 캡처 사용

명명된 매개변수는 이름으로 참조하고, 빈 와일드카드는 *로 참조합니다:

규칙 순서

규칙은 목록의 맨 위부터 아래로 테스트되며 첫 번째 매치가 승리합니다. 규칙이 일치하면 이후 규칙은 고려되지 않습니다. 패널은 목록 아래에 다음과 같이 표시합니다: "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개의 리디렉션 및 리라이트 규칙, 그리고 kaps.json의 100개.
• 환경당 최대 200개의 사용자 정의 헤더 규칙.

한계를 초과하는 규칙은 오류를 발생시키지 않고 조용히 삭제되므로 한계 훨씬 아래에 유지하세요.

사용자 정의 응답 헤더

리디렉션과 함께, 각 환경의 Settings에는 일치하는 경로에 HTTP 헤더를 삽입하기 위한 응답 헤더 섹션이 있습니다. 동일한 경로 패턴 구문을 사용하며, HSTS, CSP, no-embed, no-sniff, referrer policy 및 CORS에 대한 빠른 추가 프리셋이 있습니다.

리디렉션과 달리, 모든 일치하는 헤더 규칙이 적용되며, 나중 규칙이 동일한 헤더를 설정할 때 이전 규칙을 덮어씁니다. Content-Length, Transfer-Encoding 및 Connection은 차단됩니다. 이들을 설정하면 응답이 손상되기 때문입니다.

이를 신뢰하기 전에 알아야 할 동작

• 규칙은 경로만 매치합니다. 프래그먼트(#section)는 서버에 도달하지 않습니다. 브라우저는 리디렉션 후 이들을 다시 연결합니다.
• 존재하지 않는 경로로의 리라이트는 404를 생성합니다. 원래 경로로 조용히 폴스루하지 않습니다. 리라이트 대상은 빌드 출력에 존재해야 합니다.
• 규칙은 프로젝트가 요청되기 전에 실행됩니다. 따라서 정적 파일과 서버 모드 요청 모두에 적용됩니다.
• 각 환경은 독립적입니다. 프로덕션의 규칙은 스테이징 또는 미리보기에 적용되지 않습니다. 의도적으로 복사하세요.

규칙 삭제

규칙 행의 휴지통 아이콘을 클릭한 후 Save rules을 클릭하여 변경 사항을 적용합니다. 규칙을 추가할 때와 마찬가지로 변경 사항은 다음 배포부터 효과가 나타납니다.

대신 엣지 함수를 사용할 때

리디렉션 엔진은 경로-대경로 규칙을 처리합니다. 규칙 엔진이 표현할 수 없는 로직이 필요할 때 엣지 함수를 사용하세요: 헤더 또는 쿠키의 분기, 쿼리 매개변수 보존 또는 리라이트, 가중치 A/B 라우팅, 또는 조건부 항목입니다.

관련 읽기

• Edge Functions
• 프로젝트에 사용자 정의 도메인 추가
• 프로젝트 배포