Repository navigation
Shortlink Architecture
[방문자 · 비로그인] [발급자 · 로그인]
│ │
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개다.
공개 주소는 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에 이유를 남긴다.
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)가 즉시 반영되지 않는 위험이 생긴다. 이 모듈에서 즉시 반영은 기능의 본체다.
FE 번들을 거치지 않는다(명세 §6.1·§7). BE 리소스로 HTML 2장이 들어간다.
- 인라인 CSS + 인라인 SVG(브랜드 마크). 외부 요청 0
- 다크/라이트는
prefers-color-scheme만 — 테마 컨텍스트·localStorage에 의존하지 않는다 - 디자인 시스템 컴포넌트를 쓸 수 없다. 색·타이포 값을 손으로 옮겨 적는 유일한 지점이며, 그래서 화면을 브랜드 마크 + 한 줄로 극단적으로 줄여 뒀다
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)
shortlink_visit에서 90일 초과 행을 삭제하는 스케줄 작업 하나(하루 1회, 새벽). 집계 테이블은 건드리지 않는다.
주기 루프 인벤토리에 행을 추가하지 않는다. Periodic-Loops는 S3나 유료 외부 API를 두드리는 루프만 싣는다. 이 배치는 로컬 MySQL DELETE라 비용 표면이 없다. PR 체크리스트 항목에는 "해당 없음"으로 답한다.
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).
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다. JDKHttpClient에는 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)에 적어 뒀다
| 계층 | 조치 |
|---|---|
| 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인에게만 열려 있다는 점이 유일한 통제이며, 보안 위협 모델에 그대로 기록한다 |
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와 같은 방식)
| 대상 | 변화 | 위험 |
|---|---|---|
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).