Skip to content

Shortlink Architecture

wcorn edited this page Aug 24, 2026 · 3 revisions

시스템 아키텍처: 단축 URL (링크)

확정 명세 · 유스케이스 · 데이터 모델 · API · 결정 기록

1. 전체 구조

[방문자 · 비로그인]                        [발급자 · 로그인]
        │                                        │
  s.orino.dev/{slug}                        orino.dev/links
        │                                        │
        ▼                                        ▼
┌───────────────────────── Istio Gateway (istio-ingress) ─────────────────────────┐
│  Gateway hosts: orino.dev, *.orino.dev   ·  cert: *.orino.dev (기존, 변경 없음)  │
│                                                                                 │
│  VirtualService(s.orino.dev)                    VirtualService(orino.dev) — 기존 │
│   ├ /robots.txt        → directResponse         VirtualService(api.orino.dev)—기존│
│   ├ ^/([a-z0-9]{1,32})$ → rewrite /r/$1 → be                                     │
│   └ 그 외              → directResponse 404                                      │
│  + EnvoyFilter: local_ratelimit (s.orino.dev vhost)                             │
└─────────────────────────────────────────────────────────────────────────────────┘
        │                                        │
        ▼                                        ▼
┌─────────────────────────── orino-app-api (기존 BE, 같은 배포) ──────────────────┐
│  SecurityFilterChain                                                            │
│    permitAll : /r/**            ← 공개 표면은 이 한 줄이 전부                    │
│    auth      : /api/shortlinks/**                                               │
│                                                                                 │
│  planner/shortlink/                                                             │
│   ├ redirect/   RedirectController  ·  실패·비밀번호 화면 서버 렌더             │
│   ├ controller/ ShortlinkController (관리 API)                                   │
│   ├ service/    발급 · 슬러그 생성 · 목적지 교체 · 통계 조회                     │
│   ├ visit/      VisitRecorder(@Async) · 봇 판정 · 기기 판정                     │
│   └ og/         OgPreviewService (SSRF 방어 fetch)                              │
└─────────────────────────────────────────────────────────────────────────────────┘
        │                          │
        ▼                          ▼
   MySQL (shortlink 5테이블)      (GeoLite2 미도입 — D-9 뒤집힘)

신규 배포 대상이 없다. 새 Deployment·이미지·Helm 차트·CI 잡을 만들지 않는다. 늘어나는 것은 VirtualService 1개 · EnvoyFilter 1개 · BE 패키지 1개 · 테이블 5개다.

2. 리다이렉트 경로

2.1 왜 게이트웨이에서 경로를 재작성하나

공개 주소는 s.orino.dev/{slug}(명세 §3), 내부 경로는 /r/{slug}. Istio VirtualService가 재작성한다.

재작성하지 않으면
BE 루트에 @GetMapping("/{slug}") catch-all이 생긴다 /swagger-ui.html·정적 리소스·오타 요청을 전부 삼킨다
인증 예외 경로를 루트로 열어야 한다 공개 표면의 크기가 설정에서 안 보인다
슬러그 문자셋에 안 맞는 요청도 BE까지 온다 스캐너 트래픽이 애플리케이션 스레드를 쓴다

재작성 규칙(정규식)은 슬러그 문자셋을 그대로 반영한다 — ^/([a-z0-9]{1,32})$에 맞지 않으면 게이트웨이가 404를 직접 낸다(BE 미도달).

게이트웨이가 내는 404와 BE가 내는 404는 화면이 다르면 안 된다. 게이트웨이 directResponse에 같은 HTML을 심는다. 두 곳에 같은 문자열이 생기므로 결정 기록 D-7에 이유를 남긴다.

2.2 요청 처리 순서

GET s.orino.dev/9dwqr
 1. Envoy   rate limit 통과?            아니면 429
 2. Envoy   정규식 매치 → /r/9dwqr 로 재작성
 3. BE      slug 소문자 정규화 → 조회 (활성 · 미만료 · 미삭제)
 4. BE      없으면 → 404 HTML (명세 §7)
 5. BE      비밀번호 링크면 → 확인 화면 HTML 200 (명세 §10)
 6. BE      방문 기록 비동기 제출 (실패해도 아래로 진행 — 명세 §6.5)
 7. BE      목적지 URL 조립 (쿼리 규칙 — 명세 §6.4)
 8. BE      302 + Location + Cache-Control: no-store + Referrer-Policy: no-referrer

3번 조회는 Redis 캐시를 두지 않는다. 단일 사용자 트래픽에서 MySQL PK/UNIQUE 조회는 충분히 빠르고, 캐시를 두면 목적지 교체(명세 §5.1)가 즉시 반영되지 않는 위험이 생긴다. 이 모듈에서 즉시 반영은 기능의 본체다.

2.3 실패·비밀번호 화면은 서버 렌더 정적 HTML이다

FE 번들을 거치지 않는다(명세 §6.1·§7). BE 리소스로 HTML 2장이 들어간다.

  • 인라인 CSS + 인라인 SVG(브랜드 마크). 외부 요청 0
  • 다크/라이트는 prefers-color-scheme만 — 테마 컨텍스트·localStorage에 의존하지 않는다
  • 디자인 시스템 컴포넌트를 쓸 수 없다. 색·타이포 값을 손으로 옮겨 적는 유일한 지점이며, 그래서 화면을 브랜드 마크 + 한 줄로 극단적으로 줄여 뒀다

3. 방문 기록 (비동기)

RedirectController ──▶ VisitRecorder.record(...)   @Async, 별도 트랜잭션
                            ├ User-Agent  → 봇 여부 · 기기 구분     (원문 저장 안 함)
                            ├ Referer     → 도메인만 추출            (전체 URL 저장 안 함)
                            ├ (국가 판정 없음 — IP를 읽지 않는다, D-9)
                            ├ INSERT shortlink_visit                (원시, 90일)
                            └ UPSERT shortlink_visit_daily          (집계, 영구)
  • 원시와 집계를 방문 시점에 함께 쓴다. 야간 집계 배치를 만들지 않는다 — 배치가 하나 줄고, 90일 정리로 원시가 사라져도 일별 그래프가 남는다(명세 §8.3)
  • 예외는 삼켜서 로그로만 남긴다. 통계 실패가 302를 막지 않는다
  • 봇 판정: 알려진 프리뷰 UA 목록(kakaotalk-scrap · facebookexternalhit · Slackbot · Discordbot · TelegramBot · WhatsApp · Twitterbot · Googlebot · bingbot …) + 일반 패턴(bot · crawl · spider · preview · scrap). 완벽하지 않다는 것을 화면에서 밝힌다(명세 §8.2)

3.1 보존 배치

shortlink_visit에서 90일 초과 행을 삭제하는 스케줄 작업 하나(하루 1회, 새벽). 집계 테이블은 건드리지 않는다.

주기 루프 인벤토리에 행을 추가하지 않는다. Periodic-Loops는 S3나 유료 외부 API를 두드리는 루프만 싣는다. 이 배치는 로컬 MySQL DELETE라 비용 표면이 없다. PR 체크리스트 항목에는 "해당 없음"으로 답한다.

4. 국가 판정 (GeoIP) — 하지 않는다

2026-08-24 정정(개발자 판단). GeoLite2를 들이지 않는다(D-9 뒤집힘, #1241 미착수 종료). 방문 기록에 IP를 읽는 코드가 없고, shortlink_visit.country는 컬럼만 남아 항상 NULL이다. stats의 countries는 항상 빈 배열이다.

아래는 채택했다가 뒤집힌 기록이다 — 국가가 정말 필요해지면 여기서 다시 출발한다.

원안 (뒤집힌 기록)

Cloudflare를 제거(#456)하면서 CF-IPCountry를 잃었고, 현재 인프라에 국가를 알 수단이 없다. SL-019를 하려면 수단을 새로 들여야 한다.

안 판단
MaxMind GeoLite2-Country DB를 BE 이미지에 내장 채택. 라이브러리 com.maxmind.geoip2(Apache 2.0), DB ~9MB. 조회가 로컬 파일이라 외부 호출·요금·지연이 없다
Envoy geoip 필터 기각. 같은 DB가 필요한데 게이트웨이에 파일을 마운트하고 EnvoyFilter를 하나 더 얹어야 한다. 얻는 게 없다
외부 GeoIP API 호출 기각. 방문마다 유료·외부 호출. ELOG-023의 교훈에 정면으로 반한다
국가를 포기 기각(2026-08-23 개발자 판단, 전체 범위 채택)

조달 방식 — GeoLite2는 MaxMind 계정의 라이선스 키로 받는다. 이미지 빌드 시 다운로드해 COPY한다(런타임 설치 금지 원칙 준수). 키는 GitHub Actions 시크릿으로만 존재하고 클러스터에 들어가지 않는다.

갱신 — MaxMind는 주 2회 갱신하지만 국가 정확도는 참고치이므로 이미지 재빌드 주기에 딸려간다. 별도 갱신 루프를 만들지 않는다.

IP 취급 — X-Forwarded-For의 첫 값으로 조회하고 즉시 버린다. 어떤 테이블·로그에도 남기지 않는다(명세 §8.1).

5. OG 프리뷰 — 이 모듈에서 가장 위험한 코드

BE가 사용자가 입력한 임의 URL을 fetch한다. 그 BE는 note1/note2 클러스터 안에서 MySQL·Redis·MinIO와 같은 망에 있다. 방어 없이 켜면 내부망 스캐너가 된다.

방어 내용
스킴 http · https만
주소 판정은 DNS 해석 결과로 호스트명 문자열 검사로는 못 막는다. 해석된 IP가 사설(10/8 · 172.16/12 · 192.168/16) · 루프백 · 링크로컬(169.254/16, 메타데이터 169.254.169.254 포함) · CGNAT(100.64/10) · 멀티캐스트 · IPv6 대응 대역이면 차단
k3s 내부 대역 추가 차단 파드·서비스 CIDR을 목록에 넣는다
DNS 재바인딩 해석한 IP로 직접 연결하고 Host 헤더만 원본 유지. 해석과 연결 사이에 재해석하지 않는다
리다이렉트 최대 3홉, 매 홉마다 위 검사를 다시 수행
자원 타임아웃 3초 · 본문 최대 1MB · Content-Type이 HTML일 때만 파싱
실패 사유 비노출 응답은 { ok: false } 하나. "연결 거부"와 "타임아웃"을 구분해 주면 그게 곧 내부망 포트 스캐너다

발급 흐름과 완전히 분리된 엔드포인트다(명세 §4.4). 이 서비스가 통째로 죽어도 링크는 발급된다.

구현 시점 보강(#1243)

  • 연결 대상 IP를 고정하는 자리는 OkHttp의 Dns다. JDK HttpClient에는 DNS를 갈아끼울 자리가 없어, 검사한 뒤 다시 해석되는 창(DNS 재바인딩)을 닫을 수 없다. SsrfGuard.resolveSafely()가 통과시킨 주소만 Dns.lookup()이 돌려주고, 호스트명은 그대로 남아 TLS SNI와 Host 헤더가 산다. 그래서 okhttp를 build.gradle에 명시적으로 선언했다(전에는 OTLP 익스포터를 통해 전이 의존으로만 들어와 있었다)
  • 리다이렉트는 OkHttp에 맡기지 않는다(followRedirects(false)). 홉마다 URL을 다시 검사한 뒤 다음 요청을 만든다 — 자동 추적이면 2홉째가 검사를 건너뛴다
  • IPv6로 감싼 우회를 되돌려 본다 — IPv4 매핑(::ffff:10.0.0.5)·6to4(2002:0a00::/16)는 안쪽 IPv4를 꺼내 다시 판정한다. Teredo(2001:0::/32)는 안쪽 주소가 비트 반전으로 들어 있어 다루지 않는다(공개 대역이라 판정 자체는 안전한 쪽으로 떨어진다)
  • shortlink.og-preview.enabled 스위치가 있다. 끄면 외부로 나가는 요청이 0이 된다 — 운영에서 문제가 생기면 여기서 끄고, 테스트 프로파일은 기본으로 꺼 둔다(발급마다 남의 서버를 두드리는 테스트는 느리고 결과가 흔들린다). 방어 자체는 SsrfGuardTest·OgPreviewClientTest가 실제 소켓으로 확인한다
  • og_fetched_at은 결과가 비어 있어도 남긴다. "아직 시도 안 함"과 "해 봤는데 없더라"를 구분하지 못하면 같은 URL을 계속 다시 긁는다
  • k3s 파드(10.244.0.0/16)·서비스(10.96.0.0/12)는 둘 다 10/8 안이라 기본 차단에 이미 걸리지만, 무엇을 막고 있는지 보이도록 설정(blocked-cidrs)에 적어 뒀다

6. 공개 표면 방어

계층 조치
Envoy rate limit s.orino.dev vhost에 local_ratelimit. 기존 EnvoyFilter는 api.orino.dev vhost에만 걸려 있어 그대로 두면 무방비다
정규식 필터 슬러그 문자셋 밖 요청은 BE 미도달(§2.1)
응답 무정보 없음·꺼짐·만료·삭제 동일 404(명세 §7)
슬러그 엔트로피 32⁵ ≈ 3,355만, 난수 생성(명세 §4.2)
비밀번호 시도 슬러그당 분당 10회(명세 §10)
robots.txt Disallow: / — 게이트웨이 directResponse로 BE 미도달
오픈 리다이렉트 성격 설계상 그렇다. 임의 목적지로 보내는 것이 기능이다. 발급이 인증된 1인에게만 열려 있다는 점이 유일한 통제이며, 보안 위협 모델에 그대로 기록한다

7. FE 구조

fe/src/
├─ pages/links/LinkListPage.tsx        ← /links
├─ pages/links/LinkDetailPage.tsx      ← /links/:slug
├─ features/shortlink/
│   ├─ api/           엔드포인트 래퍼
│   ├─ hooks/         useLinks · useLink · useLinkStats · useShortlinkSummary · 뮤테이션
│   ├─ components/    LinkRow · QuickCreateBar · NewLinkModal · QrPanel · StatsPanel
│   └─ queryKeys.ts   shortlinkKeys (기존 travelKeys 패턴)
├─ pages/WorkspaceSelectPage.tsx       ← 카드 3장으로 (SL-020)
├─ app/layout/Sidebar.tsx              ← 전환 3분할 + 링크 메뉴 + 태그 섹션
└─ app/router.tsx · routeImports.ts    ← 지연 로드 라우트 2개
  • QR은 FE에서 canvas로 렌더 → toBlob → 다운로드. BE는 QR을 모른다. 라이브러리는 링크 라우트 청크에만 들어간다(코드 스플리팅)
  • 낙관적 발급: 빠른 발급은 응답 전에 목록 맨 위에 행을 넣고, 실패 시 되돌린다. 클립보드 복사는 서버 응답의 슬러그로만 한다(낙관적 값으로 복사하면 틀린 주소를 붙여넣게 된다)
  • 워크스페이스 판정은 경로 하나로 — isLinkWorkspace = pathname === "/links" || pathname.startsWith("/links/"). 별도 상태를 두면 새로고침에 어긋난다(기존 isTravelWorkspace와 같은 방식)

8. 기존 코드에 생기는 변화

대상 변화 위험
SecurityConfig /r/** permitAll 추가 인증 경계 변경. 테스트로 고정한다(/r/**만 열리고 /api/**는 여전히 401)
WorkspaceSelectPage 카드 2 → 3, basis-[260px] → basis-[200px] 여행·일상 진입이 지나가는 공용 화면
Sidebar 전환 2분할 → 3분할, 아이콘-라벨 gap-1.5 → gap-[5px] 〃
Istio istio-gateway 차트 VirtualService·EnvoyFilter 추가 게이트웨이 설정 오류는 전 서비스에 영향. helm template 확인 필수

아래 둘은 여행 워크스페이스도 매일 지나가는 화면이다. #1176 실사용 리허설(10/6–10/19)과 기간이 겹치면 리허설이 여행 변경과 링크 변경을 동시에 검증하게 된다. 2026-08-23 개발자 판단으로 동선 변경을 포함해 지금 전부 진행하기로 했고, 대신 리허설 시작 전에 끝내는 것을 일정 조건으로 둔다(결정 기록 D-8).

Clone this wiki locally