이 글은 반대 순서입니다. 서비스는 만들어진 그 머신에서 계속 돌고, Cloudflare Tunnel이 거기에 공개 HTTPS 호스트명을 붙여 줍니다. 노트북에서 인터넷을 향해 열려 있는 건 아무것도 없습니다. 포트 포워딩도, 공유기 설정도, 노출된 IP 주소도 없습니다. 머신이 Cloudflare 쪽으로 먼저 연결을 걸고, Cloudflare는 그 연결을 타고 요청을 내려보냅니다. 터널은 무료이고, TLS 인증서와 DDoS 방어, 캐싱은 아마 이미 갖고 있을 Cloudflare 존에 딸려 옵니다.

예시는 실제 사례입니다. 제 제품 중 하나는 Fly.io에서 돌고, 모바일 앱은 백엔드에서 OTA(over-the-air) JavaScript 업데이트를 받습니다(셀프 호스팅한 Expo Updates). 프로덕션은 그대로 둔 채, 개발 빌드용으로 그 업데이트 서버의 두 번째 사본을 제 Mac에서 돌리고 싶었습니다. 아래 출력은 그날 오후에 나온 것이고, 제대로 안 됐던 부분도 들어 있습니다.

클라우드플레어 터널이란 실제로 무엇인가

#

보통 서버는 연결을 기다립니다. 인터넷에서 노트북에 닿으려면 공유기에서 포트를 열고, 그걸 노트북으로 포워딩하고, ISP가 공인 IPv4 주소를 주기를 바라야 합니다(제가 사는 곳을 포함해 많은 곳에서 주지 않습니다). 그러고 나면 그 포트에서 듣고 있는 모든 것이 인터넷의 모든 스캐너에게 하루 종일 노출됩니다.

터널은 이걸 뒤집습니다. cloudflared가 앱 옆에서 돌면서 Cloudflare 엣지로 나가는 연결을 엽니다. 가까운 데이터센터 두 곳에 네 개입니다. 존의 DNS 레코드가 호스트명을 터널로 향하게 합니다. 그 호스트명으로 요청이 오면 Cloudflare가 TLS를 종료하고 그 연결 중 하나로 요청을 내려보냅니다. 그러면 cloudflared가 설정에 적힌 로컬 서비스에 요청을 넘깁니다.

보안 측면에서 중요한 건, 공유기에 인바운드 규칙이 하나도 없고 IP 주소가 DNS에 절대 나타나지 않는다는 점입니다. 누가 집 회선을 스캔해도 아무것도 찾지 못합니다. 듣고 있는 게 없으니까요.

처음부터 끝까지 설정하기 (cloudflared + Docker Compose)

#

Cloudflare에 올린 도메인(무료 플랜이면 충분합니다)과 설치된 cloudflared(Mac이라면 brew install cloudflared)가 필요합니다.

1. 한 번 로그인합니다. 브라우저가 열리면 존을 고르고, 이 머신이 그 존에 터널과 DNS 레코드를 만들 수 있게 해 주는 인증서가 저장됩니다.

cloudflared tunnel login

2. 터널을 만듭니다. 저는 이 프로젝트에 관한 건 전부 전용 폴더에 둡니다. 자격 증명 파일이 곧 터널의 신원이라, 그 파일을 가진 사람은 누구든 내 호스트명으로 트래픽을 서빙할 수 있기 때문입니다.

mkdir -p ~/.cloudflared/myapp && cd ~/.cloudflared/myapp
cloudflared tunnel create --credentials-file ./creds.json myapp-local
chmod 600 creds.json

Tunnel credentials written to ./creds.json. Keep this file secret. To revoke these credentials, delete the tunnel.
Created tunnel myapp-local with id 1ade030c-…

3. 호스트명을 터널로 향하게 합니다. 호스트명마다 명령 하나로 <tunnel-id>.cfargotunnel.com을 가리키는 프록시된 CNAME이 만들어집니다.

cloudflared tunnel route dns myapp-local ota.example.com
cloudflared tunnel route dns myapp-local checkin-local.example.com

4. ingress 규칙을 씁니다. 보안에서 핵심이 되는 부분이라 아래에 따로 절을 두었습니다.

5. 실행합니다. 제 앱은 이미 Docker Compose로 돌고 있어서, cloudflared는 같은 네트워크에 컨테이너 하나를 더 얹는 것뿐입니다. 서비스 이름으로 앱에 닿으니, 앱은 호스트에 포트를 공개할 필요조차 없습니다.

# compose.tunnel.yml, used alongside the project's docker-compose.yml
services:
  cloudflared:
    image: cloudflare/cloudflared:2026.10.7
    command: tunnel --config /etc/cloudflared/config.yml run
    volumes:
      - ${HOME}/.cloudflared/myapp:/etc/cloudflared:ro
    restart: unless-stopped
    depends_on: [api, edge]

docker compose -f docker-compose.yml -f ~/.cloudflared/myapp/compose.tunnel.yml up -d cloudflared

INF Registered tunnel connection connIndex=0 … location=icn06 protocol=quic
INF Registered tunnel connection connIndex=1 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=2 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=3 … location=icn06 protocol=quic

서울로 연결 네 개, 이제 노트북은 바깥에서 안으로 인터넷에 올라와 있습니다. restart: unless-stopped 덕분에 재부팅해도 Docker가 뜨자마자 다시 살아납니다.

서버가 아니라 경로를 노출하기

#

제가 하마터면 저지를 뻔한 실수이고, 아마 가장 흔한 실수일 겁니다. 가장 쉬운 설정은 한 줄입니다. hostname → http://localhost:8000. 이러면 개발 서버 전체가 공개됩니다.

개발 서버는 그러라고 만든 게 아닙니다. 제 개발 서버는 DEBUG=True로 돌아서, 에러가 나면 전체 트레이스백과 설정을 보여줍니다. 인증도 꺼 둔 채로(AUTH_MODE=disabled) 돌아서, 아무 bearer 토큰이나 테스트 사용자로 로그인됩니다. localhost에서는 딱 맞는 설정이고 공개 호스트명에서는 재앙입니다. 여러분 쪽에도 비슷한 게 있을 겁니다. 기본 비밀번호가 걸린 관리자 화면, 시드 데이터 엔드포인트, 디버그 툴바, 아니면 호출하는 사람이 나뿐이라 호출자를 믿어 버리는 API 같은 것들요.

그래서 터널 설정은 허용 목록입니다. cloudflared는 요청마다 ingress 규칙을 순서대로, 호스트명과 경로에 대한 정규식으로 대조합니다. 처음 맞는 규칙이 이기고, 마지막 규칙이 나머지 전부를 받습니다.

tunnel: myapp-local
credentials-file: /etc/cloudflared/creds.json

ingress:
  # OTA: the two read-only endpoints the phone calls, and the files they link.
  - hostname: ota.example.com
    path: ^/api/expo-updates/(manifest|status)/$
    service: http://api:8000
  - hostname: ota.example.com
    path: ^/media/
    service: http://api:8000
  # Device check-ins, authenticated by each device's own key.
  - hostname: checkin-local.example.com
    path: ^/c/$
    service: http://edge:8081
  # Everything else, including /admin/ and the publish endpoint: 404 at the edge.
  - service: http_status:404

배포(publish) 엔드포인트는 같은 서버의 같은 접두사 아래(/api/expo-updates/import-update/)에 있지만 목록에 없습니다. 관리자 화면도, 나머지 API도 없습니다. 그런 요청은 Cloudflare를 벗어나지 못합니다.

정규식을 믿을 필요는 없습니다. URL이 어느 규칙에 걸리는지 cloudflared가 알려 줍니다.

cloudflared tunnel --config config.yml ingress rule https://ota.example.com/admin/

https://ota.example.com/api/expo-updates/manifest/        service: http://api:8000
https://ota.example.com/api/expo-updates/import-update/   service: http_status:404
https://ota.example.com/admin/                            service: http_status:404
https://ota.example.com/media/expo-updates/x.js           service: http://api:8000
https://checkin-local.example.com/c/                      service: http://edge:8081
https://checkin-local.example.com/health                  service: http_status:404

저라면 이 검사를 스크립트로 만들어 설정을 바꿀 때마다 돌리겠습니다. 몇 초면 끝나고, 의도보다 넓게 매칭되는 정규식은 남이 알려 줘야 비로소 알게 되는 종류의 실수입니다.

경험칙 두 가지를 더 덧붙이면 이렇습니다.

• 노출하는 것은 스스로 인증해야 합니다. OTA 엔드포인트는 공개된 읽기 전용 데이터를 서빙합니다. 디바이스 체크인은 디바이스별 키로 서명됩니다. 어느 쪽도 안전을 네트워크에 기대지 않습니다. 로그인이 없는 페이지를 누군가에게 보여주고 싶다면, 로그인을 직접 만들지 말고 그 호스트명 앞에 Cloudflare Access를 두세요(사용자 50명까지 무료).
• 터널을 개발 워크플로의 일부로 백그라운드에 상시 띄워 두지 마세요. 의도한 호스트명을 위해 일부러 켜고, 다 쓰면 끄세요. docker compose stop cloudflared 명령 하나로 전부 인터넷에서 내려갑니다.

호스트명을 집어삼킨 리다이렉트

#

터널이 연결되고 규칙도 검증했으니, 바깥에서 시험해 봤습니다.

https://ota.example.com/api/expo-updates/status/?…   301
https://ota.example.com/api/expo-updates/manifest/   301
https://ota.example.com/admin/                       301
https://checkin-local.example.com/c/                 301

모든 경로가 똑같은 301을 돌려줬습니다. 터널이 404로 답했어야 할 경로까지요. 요청이 cloudflared에 아예 닿지 않았다는 뜻입니다. Location 헤더는 https://www.example.com/이었고, server: cloudflare 헤더로 확실해졌습니다. Cloudflare가 스스로 답하고 있었습니다.

제가 자초한 일이었습니다. 몇 달 전 존재하지 않는 서브도메인을 훑고 다니는 스캐너를 빨아들이는 싱크홀로 “그 밖의 모든 서브도메인 → www"라는 존 단위 리다이렉트 규칙을 추가해 뒀습니다. 리다이렉트 규칙은 요청이 오리진으로 가기 전에 Cloudflare의 요청 파이프라인에서 돌고, 터널은 그저 오리진 하나일 뿐입니다. 같은 규칙이 프리뷰 환경도 잡아먹었습니다. Workers가 보기도 전에요. 해결책도 그때와 같습니다. 규칙의 표현식에 예외 하나를 더 넣는 겁니다.

… and not http.host in {"ota.example.com" "checkin-local.example.com"}

터널 호스트명이 앱 대신 Cloudflare의 리다이렉트나 에러 페이지로 답한다면, 터널을 디버깅하기 전에 그 존의 Rules → Redirect Rules, Page Rules, WAF 커스텀 규칙부터 확인하세요. cloudflared는 전달하는 요청을 전부 로그에 남기므로, 로그가 비어 있다면 요청이 거기까지 오지도 못한 겁니다.

할 수 없는 것

#

• 공개 인터넷에서 오는 UDP. 공개 터널 호스트명은 HTTP(S)(그리고 WebSocket과 gRPC)를 실어 나릅니다. 제 제품의 디바이스는 보통 UDP 위의 CoAP로 체크인하는데, 그건 터널을 통과할 수 없습니다. 로컬 사본에 붙은 디바이스는 HTTPS 체크인으로 폴백하고, 그 대가로 체크인마다 몇 초씩 더 듭니다. 아이디어가 게임 서버나 VoIP라면 터널은 맞는 도구가 아닙니다.
• 가동 시간. 결국 노트북입니다. 덮개를 닫으면 사이트가 내려가고, Cloudflare가 530 에러 페이지를 보여줍니다. 데모나 열 명짜리 베타, 스테이징 사본이라면 괜찮습니다. 누군가 의존하는 것이라면 괜찮지 않습니다.
• 빌드에 박혀 들어간 것. 모바일 앱의 업데이트 URL은 네이티브 설정이라, 터널 URL로 만든 빌드만 그걸 씁니다. 스토어 빌드는 계속 프로덕션과 통신하고, 그래서 이 구성을 안심하고 시도해 볼 수 있었습니다.

비용: Cloudflare Tunnel은 무료인가

#

무료 플랜의 Cloudflare 존, 터널, 인증서, DNS 레코드: $0. 머신은 원래 켜져 있었습니다. 진짜 비용은 이제 내가 가동 시간 담당 팀이 된다는 것 하나뿐입니다.

대신 아껴 주는 건 “내 머신에서는 잘 돼요"와 “돈 내고 호스팅할 가치가 있다” 사이의 구간입니다. 테스터나 디자이너, 첫 고객에게 같은 날 오후에 링크를 보낼 수 있습니다. 아무도 관심이 없으면 잃은 게 없습니다. 관심이 있다면, 진짜 호스트로 옮기는 건 변경 하나입니다. CNAME을 다른 곳으로 향하게 하면 됩니다.

처음 마주친 건 9월이었습니다. 헬스 체크는 전부 초록불인데 Cloudflare 대시보드에는 요청의 22%가 실패로 찍혀 있던 때였고, 저는 Early Hints를 끄고 넘어갔습니다. 11월에 같은 존(zone)을 보니 Early Hints가 다시 켜져 있었고 하루 만에 504가 또 2,600건 쌓여 있었습니다. 이번에는 그 정체를 정확히 알고 싶었고, 기능을 또 꺼야 하는지 아니면 제대로 일하게 만들어야 하는지도 확실히 하고 싶었습니다. 이 존은 Fly.io 오리진 하나를 앞에서 받고 있고, 그 오리진이 Django API, Expo 웹 앱, Hugo로 만든 마케팅 사이트를 서빙합니다.

짧은 답

#

• 이 504는 방문자가 아니라 Cloudflare의 Early Hints 캐시가 기록한 것입니다. Cloudflare 로그에서는 ClientRequestSource = earlyHintsCache로 표시됩니다.
• 여기서 504는 캐시 미스라는 뜻입니다. 그 URL에 대해 저장된 힌트가 없었다는 것이죠. 히트는 2xx로 기록됩니다.
• 이 요청은 오리진에 절대 도달하지 않습니다. OriginResponseStatus가 0입니다.
• Early Hints는 Link HTTP 응답 헤더로 동작합니다. HTML 안의 <link rel="preload"> 태그로는 동작하지 않습니다.
• 헤더를 보내면, 미리 불러올 것이 있는 페이지에서는 이 미스가 히트로 바뀌고 진짜 103 Early Hints 응답이 나가기 시작합니다.

미리 알아 두면 좋은 것이 세 가지 더 있습니다. 힌트는 렌더링에 꼭 필요한 CSS, 스크립트, 폰트만 주고, 폰트에는 crossorigin을 유지하세요. 확인은 curl -sv --http2로 하면 되고, 200 전에 103이 보여야 합니다. 그리고 무엇을 결정하든 earlyHintsCache는 알림에서 빼 두고, 헤더를 앞으로도 보내지 않을 거라면 로그 노이즈로 비용을 치르느니 Early Hints를 끄세요.

가짜 Cloudflare 504와 진짜 504 구별하기

#

Logpush나 Instant Logs를 쓴다면 무엇보다 먼저 두 필드를 보세요. ClientRequestSource는 실제 방문자 요청이면 eyeball, Early Hints 조회면 earlyHintsCache입니다. OriginResponseStatus가 0이면 오리진에 연결조차 하지 않은 것입니다.

GraphQL Analytics API에서는 같은 구분이 requestSource 디멘션으로 나옵니다. 저는 이제 5xx가 튀면 믿기 전에 이 쿼리부터 돌립니다.

query ($zone: String!, $since: Time!) {
  viewer {
    zones(filter: { zoneTag: $zone }) {
      httpRequestsAdaptiveGroups(
        limit: 20
        filter: { datetime_geq: $since, edgeResponseStatus: 504 }
        orderBy: [count_DESC]
      ) {
        count
        dimensions { requestSource userAgent clientRequestPath }
      }
    }
  }
}

User-Agent로 묶어 봐도 같은 결과가 나옵니다. 9월에는 Early Hints 조회가 bastion early hints와 nginx-ssl early hints로 찍혔습니다. 11월에는 fl2 early hints와 nginx-ssl early hints였습니다(FL2는 Cloudflare 프록시의 새 세대입니다). 24시간 동안 이 존의 504 2,631건이 전부 이 User-Agent에서 나왔습니다. 브라우저, 앱, curl, 검색 크롤러에서 나온 것은 하나도 없었습니다.

방문자가 실제로 본 진짜 504는 거의 언제나 Cloudflare 바깥, 즉 여러분 쪽에서 나온 것입니다. 애플리케이션 앞에 있는 프록시나 로드 밸런서가 기다리다 포기한 것이죠. nginx일 수도 있고, 클라우드 로드 밸런서일 수도 있고, 잠든 머신이 깨어나길 기다리는 플랫폼 프록시일 수도 있습니다. Cloudflare 자체의 타임아웃은 다른 코드를 씁니다. 522는 오리진에 연결하지 못했다는 뜻이고, 524는 연결은 됐지만 125초(Enterprise 미만 요금제의 기본값) 안에 응답을 받지 못했다는 뜻입니다.

그러니 504 때문에 Cloudflare 타임아웃을 늘리는 방법을 찾다가 이 글에 오셨다면: 504 뒤에 있는 타임아웃은 거의 Cloudflare 것이 아닙니다. nginx의 proxy_read_timeout, 로드 밸런서의 idle timeout, 또는 플랫폼이 머신을 깨우는 데 걸리는 시간을 확인하세요. 쓸 만한 단서가 하나 있습니다. 요청이 125초보다 한참 짧은 딱 떨어지는 숫자, 예를 들어 30초나 60초에서 실패한다면 Cloudflare가 아니라 여러분 프록시의 한도입니다. (Cloudflare의 125초 한도는 Enterprise 요금제에서만 최대 6,000초까지 늘릴 수 있고, Cloudflare 스스로도 이를 임시방편으로 봅니다.)

이 504의 정체

#

Early Hints가 켜진 존에서는 HTML 페이지나 확장자 없는 URL로 가는 요청마다(API가 많은 존에서는 API 호출 대부분이 여기 해당합니다) 내부 조회가 하나 더 붙습니다. Cloudflare가 보낼 힌트가 있는지 자기 캐시를 확인하는 것이죠. 이 조회는 ClientRequestSource = earlyHintsCache로 별도 줄에 기록됩니다. 최종 사용자 요청이 아니고, 오리진으로 보내지지도 않습니다.

그 줄의 상태 코드는 에러가 아니라 캐시 조회 결과입니다.

• 2xx는 히트입니다. Cloudflare에 그 URL용 Link 헤더가 저장돼 있었고, 이를 103으로 브라우저에 보냈다는 뜻입니다. 제 존에서는 히트가 200과 204 두 가지로 나타납니다.
• 504는 미스입니다. 저장된 것이 없어서 미리 보낼 것이 없었다는 뜻입니다.

오리진이 Early Hints가 쓰는 헤더를 한 번도 보내지 않으면 모든 조회가 미스가 되고, 모든 요청이 504 줄을 하나씩 남깁니다. 제가 아무것도 바꾸기 전 3시간 동안 이 존은 Early Hints 조회를 173건 기록했고, 173건 모두 미스였습니다. 기능이 켜진 뒤로 힌트를 한 번도 보낸 적이 없었던 겁니다.

9월 글에 대한 정정도 하나 하겠습니다. 저는 그때 이것을 “Fly 오리진에서 응답을 받지 못하는” 프로브라고 설명했습니다. 정확한 설명이 아닙니다. 이 조회는 오리진에 아예 가지 않습니다. 504는 타임아웃이 아니라 캐시 미스를 기록한 것입니다.

Cloudflare도 Early Hints 문서에서 이 점을 짧게 설명하고 있습니다. ClientRequestSource: earlyHintsCache로 기록된 Early Hints 조회는 “expected and benign”(예상된 것이고 무해함)이며, 200은 캐시 히트, 504는 미스입니다. Log Explorer에서는 ClientRequestSource != "earlyHintsCache"로 걸러낼 수 있습니다. Cache Analytics는 원래부터 이걸 빼고 보여 주지만, 저를 놀라게 한 HTTP 트래픽 차트는 그렇지 않습니다.

가짜 504 때문에 서버를 업그레이드했다

#

이 구분이 중요한 이유가 여기 있습니다. 이 글을 쓰기 시작하기 전날인 11월 3일, Cloudflare에는 방문자 요청 약 13,300건에 504가 3,292건 기록됐습니다. 겉보기 에러율이 25%입니다. API는 Fly.io의 shared-cpu-1x 머신에서 돌고 있는데, 이 머신은 버스트 크레딧 방식입니다. 보장되는 CPU 몫은 작고, 더 빨리 돌려면 크레딧을 씁니다. 8월 부하 테스트에서 지속 부하가 걸리면 초당 약 20~30 요청 수준으로 스로틀링된다는 것을 확인했었습니다. “피크 시간에 요청 4분의 1이 타임아웃"은 딱 그 스로틀링처럼 보였고, 그래서 API를 shared-cpu-2x로 옮겼습니다.

그런데 그 504는 전부 Early Hints 캐시 미스였습니다. requestSource로 나누고 오리진 자체 로그까지 다시 보니 이랬습니다.

• 10월 28일부터 11월 4일까지 Cloudflare의 5xx는 하루 한 건 정도의 525를 빼면 모두 earlyHintsCache 조회였습니다. (확인한 525는 보안 스캐너에서 온 것이었습니다.)
• 10월 24일부터 11월 4일까지 오리진 액세스 로그에는 5xx가 한 건도 없었고, 10초를 넘긴 요청은 한 건뿐이었습니다.
• Fly 메트릭으로 보면 가장 많을 때도 초당 7요청 정도였고, 머신이 쓴 CPU는 코어 하나의 5분의 1을 넘지 않았습니다. 스로틀링 상한 근처에도 가지 않았습니다.

더 큰 머신은 아무것도 고치지 않았습니다. 고장 난 게 없었으니까요. API는 다시 shared-cpu-1x로 돌려놓았습니다.

request source로 나눠 보지 않은 5xx 차트를 근거로 용량을 결정하지 마세요. 오리진 자체 로그와도 맞춰 보세요. Cloudflare는 요청의 4분의 1이 실패했다는데 서버 로그에 에러가 없다면, 서버를 손대기 전에 Cloudflare가 무엇을 세고 있는지부터 확인하세요.

2026년 11월 5일 업데이트: 이 섹션의 첫 버전에는 그 주에 API가 shared-cpu-1x에서 실제로 무너졌다고 썼습니다. 실제로는 그렇지 않았습니다. 위 수치는 확인해서 나온 결과입니다.

HTTP 103은 에러인가?

#

아닙니다. 1xx 대의 상태 코드는 정보성 응답, 즉 서버가 진짜 응답 전에 보낼 수 있는 중간 응답입니다. RFC 8297에 정의된 103 Early Hints는 Link 헤더를 담고 있어서, 서버가 아직 페이지를 만드는 동안 브라우저가 핵심 CSS, JavaScript, 폰트를 미리 받거나 다른 오리진에 연결을 열어 둘 수 있게 해 줍니다. 최종 200은 같은 요청에서 뒤이어 옵니다.

지원 범위는 고르지 않지만 안전합니다. Chromium 계열 브라우저(Chrome 103 이상, Edge)와 최신 Firefox는 preload와 preconnect 힌트를 모두 처리합니다. Safari(17 이상)는 preconnect만 씁니다. 브라우저는 103을 HTTP/2와 HTTP/3에서만 처리합니다. 이해하지 못하는 브라우저는 그냥 평소처럼 200을 기다릴 뿐이니, 103은 대부분의 방문자에게는 출발 신호를 앞당겨 주고 나머지에게는 아무 영향이 없습니다.

제 설정이 비어 있던 이유: Link 헤더 vs <link rel=preload>

#

여기서 시간을 가장 많이 썼습니다. 이미 동작해야 할 것처럼 보였기 때문입니다.

Early Hints가 캐시하는 것은 딱 하나, rel=preload나 rel=preconnect 관계를 가진 Link HTTP 응답 헤더입니다. Cloudflare는 평소 응답(HTML 또는 확장자 없는 URL의 200, 301, 302)에서 이 헤더를 읽어 저장해 두고, 다음 방문자에게 전체 응답이 준비되기 전에 103으로 다시 보내 줍니다.

제 페이지에는 이미 preload가 있었습니다. 다만 HTML <head> 안의 태그로요.

<link rel="preload" href="/_expo/static/css/global-7d77bd.css" as="style">
<link rel="preload" href="/_expo/static/js/web/entry-fd7fa4.js" as="script">
<link rel="preload" href="/fonts/manrope-latin.woff2" as="font" type="font/woff2" crossorigin>

이 태그도 쓸모가 있습니다. 브라우저가 이걸 보고 움직이니까요. 하지만 브라우저는 HTML을 받아서 파싱을 시작한 뒤에야 이 태그를 봅니다. Early Hints가 앞지르려는 바로 그 순간이죠. Expo 익스포트와 제가 쓰는 Hugo 테마 둘 다 이 태그는 알아서 써 주지만, 헤더는 둘 다 설정하지 않습니다. 결국 기능은 켜져 있고 preload도 선언돼 있었지만, 둘은 한 번도 만나지 못했습니다.

해결책: 이미 가진 데이터로 헤더를 보내기

#

가장 깔끔한 해결책은 번들 해시가 바뀔 때마다 낡아 버리는 핵심 에셋 목록을 손으로 관리하는 것이 아닙니다. 각 페이지는 무엇을 미리 불러올지 이미 그 태그로 선언하고 있습니다. 그러니 페이지를 서빙할 때 그 태그를 Link 헤더로 옮겨 적으면 됩니다. 표준 라이브러리의 html.parser는 따옴표가 있는 속성도 없는 속성도(Hugo의 minifier는 따옴표를 떼어 냅니다) 처리해 주니, 정규식으로 틀릴 여지가 없습니다.

from html.parser import HTMLParser


class PreloadLinks(HTMLParser):
    def __init__(self):
        super().__init__()
        self.hints = []

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag != "link" or "preload" not in (a.get("rel") or "").split() or not a.get("href"):
            return
        hint = f"<{a['href']}>; rel=preload"
        if a.get("as"):
            hint += f"; as={a['as']}"
        if a.get("as") == "font" or "crossorigin" in a:
            hint += "; crossorigin"
        self.hints.append(hint)


def link_header(html: str, limit: int = 12) -> str | None:
    parser = PreloadLinks()
    parser.feed(html)
    return ", ".join(list(dict.fromkeys(parser.hints))[:limit]) or None

그리고 Django에서 HTML 응답에 붙입니다.

response = HttpResponse(html, content_type="text/html")
if (link := link_header(html)) and "Link" not in response:
    response["Link"] = link

저를 물었던 디테일 하나는 꼭 챙길 만합니다. 폰트에는 crossorigin을 유지하세요. 이게 없는 폰트 preload는 다른 요청으로 취급돼서 폰트를 두 번 내려받게 되고, 페이지는 빨라지기는커녕 느려집니다.

103을 직접 쓸 필요는 없습니다. ASGI, Granian, uvicorn에 중간 응답 코드를 추가할 일도 없습니다. Cloudflare가 여러분의 헤더로 103을 만들고, 여러분이 할 일은 헤더를 보내는 것뿐입니다.

다른 스택에서는

#

규칙은 어디서나 같습니다. HTML 응답에 Link 헤더를 달고 나머지는 Cloudflare에 맡기세요.

• nginx에서는 HTML을 서빙하는 location에:

  location = / {
      add_header Link "</css/app.css>; rel=preload; as=style" always;
      add_header Link "</fonts/inter.woff2>; rel=preload; as=font; crossorigin" always;
  }

• Laravel과 Vite 조합에는 이미 이를 위한 미들웨어 AddLinkHeadersForPreloadedAssets가 있어서, Vite의 preload를 Link 헤더로 바꿔 줍니다. 여기에 보고된 이슈 두 가지가 위의 함정과 똑같습니다. modulepreload 힌트가 crossorigin 없이 나가서 브라우저가 이를 버리고 스크립트를 두 번 받을 수 있었고, 큰 페이지에서는 헤더가 Apache의 약 8KB 헤더 한도를 넘기도 했습니다. 쓰는 버전에서 둘 다 확인하세요.

• 그 밖의 환경: Link 헤더 하나에 쉼표로 이어 쓰거나, Link 헤더를 여러 개 보내면 됩니다. 둘 다 됩니다.

사람들이 가장 많이 과하게 하는 부분은 무엇을 힌트로 줄지입니다. 렌더링에 꼭 필요한 CSS, 진입 스크립트, 첫 화면에 쓰이는 폰트 한두 개만 힌트로 주고, 모든 청크를 다 넣지는 마세요. 목록이 길면 브라우저가 지금 필요한 것보다 아직 필요 없는 것을 먼저 받게 됩니다. 저는 12개로 제한했는데, 그것도 Expo 익스포트가 preload 목록을 이미 추려 주기 때문입니다.

Cloudflare 뒤에 있지 않거나 CDN이 Early Hints를 지원하지 않는다면, Link 헤더의 효과는 조금뿐입니다. 브라우저가 본문을 파싱하기 전, 응답 헤더가 도착하자마자 그 리소스를 받기 시작할 수 있다는 정도죠. 서버나 CDN이 보내 주지 않는 한 103은 나가지 않습니다.

제대로 동작하는지 확인하는 법

#

curl로 103을 바로 볼 수 있습니다. HTTP/2로 요청하고 상태 줄과 Link 헤더만 남기세요.

$ curl -sv --http2 -o /dev/null https://example.com/register 2>&1 | grep -E '^< (HTTP|link)'
< HTTP/2 103
< link: </_expo/static/css/reset-f5d396.css>; as=style; rel=preload, …
< HTTP/2 200
< link: </_expo/static/css/reset-f5d396.css>; rel=preload; as=style, …

103이 먼저 오고, 그다음에 200이 옵니다. Cloudflare가 힌트 안의 속성 순서를 바꾸는데, 문제없습니다. 모든 요청이 103을 받을 거라고 기대하지는 마세요. 제 경우 처음 세 번 중 두 번만 받았습니다. 변경 후 첫 방문은 헤더를 저장만 하고, 최종 응답 헤더가 이미 준비돼 있으면 Cloudflare가 103을 건너뜁니다.

그다음 위의 분석 쿼리로 돌아가 requestSource: "earlyHintsCache"로 필터링하고 상태 코드와 경로로 묶어 보세요. 고친 페이지에서는 미스 대신 히트가 보여야 합니다.

무엇이 바뀌었고, 무엇이 남았나

#

헤더를 배포하고 몇 분 만에 이 존은 처음으로 Early Hints 히트를 기록했고, curl에서는 웹 페이지에 진짜 103 응답이 보였습니다. 헤더 하나로 두 문제가 같이 풀렸습니다. 기능이 동작하기 시작했고, “504"의 일부가 사라졌습니다.

남은 문제는 JSON API에는 미리 불러올 것이 없다는 점입니다. API 엔드포인트는 계속 미스가 나고 504 줄을 계속 남기는데, API 비중이 큰 존에서는 이게 여전히 대부분입니다. 합리적인 선택지는 세 가지입니다. 효과가 있는 페이지에 헤더를 보내고, API 경로가 계속 미스를 남기는 것은 받아들이는 것. 기능은 동작하고, 차트는 조용해지지만 완전히 조용하지는 않습니다. 무엇을 결정하든 earlyHintsCache를 5xx 알림과 대시보드에서 제외하는 것. 내부 캐시 조회 때문에 누가 호출을 받아서는 안 됩니다. 아니면 Link 헤더를 앞으로도 보내지 않을 거라면 Early Hints를 끄는 것(대시보드의 Speed → Settings → Content Optimization, 또는 API의 존 설정 early_hints). HTML이 아주 작은 싱글 페이지 앱은 얻는 게 별로 없을 수 있고, 그러면 모든 조회가 멈추면서 노이즈도 같이 사라집니다.

저는 켜 두기로 했습니다. 웹 페이지는 이제 출발이 빨라졌고, API의 미스는 알림이 걸리는 모든 곳에서 걸러 냈습니다. 9월에 기능을 끄는 대신 했어야 할 일이 바로 이것이었습니다.

호스팅 APM도, 프로덕션 트레이싱도, 일부러 기억해서 열어야 하는 대시보드도 없습니다. 따로 돈이 드는 건 로그 아카이브 하나로, 한 달에 2달러 정도입니다. 아래는 전체 목록과, 버렸거나 더는 믿지 않게 된 것들입니다. 그중 하나 때문에 저는 사용자가 한 명도 겪지 않은 장애를 며칠이나 쫓아다녔습니다.

여기서 말하는 모니터링, 그리고 이게 얼마나 작은 규모인지

#

제가 말하는 DevOps 모니터링은 두 가지입니다. 누가 알려주기 전에 뭔가 고장났다는 걸 먼저 아는 것, 그리고 짐작하지 않고 원인을 찾아낼 수 있는 것. 아래 도구는 전부 이 두 기준으로 평가했습니다.

작년에 개발자가 진짜로 쓰는 모니터링 만들기라는 글을 썼는데, 그때는 주로 팀을 염두에 뒀습니다. 작은 팀이라면 클라우드 업체가 기본으로 주는 모니터링, 서비스가 수백 개라면 호스팅 APM, 이런 식이었죠. 이번 글은 같은 생각의 가장 작은 쪽 끝입니다. 두 프로덕트 모두 요즘 쓰는 기술 스택에서 설명한 대로 Fly의 shared-cpu-1x 머신 위의 Django이고, 개발자는 둘 다 저 혼자입니다. 모니터링이 하나의 프로덕트이고 개발자가 그 사용자라면, 제 모니터링의 사용자는 딱 한 명인 셈이죠. 9월에 Fly 메트릭으로 기준치를 뽑아 봤더니 마켓플레이스 API의 평균 CPU 사용률이 1%였습니다. 엔터프라이즈 스택이 아니고, 그런 척할 생각도 없습니다.

메트릭, 로그, 트레이스라는 세 기둥 중 제게 있는 건 둘입니다. 두 프로덕트 모두 분산 트레이싱이 없습니다. 각각 Django 코드베이스 하나에 데이터베이스 하나라서, 트레이스가 넘나들 서비스 경계가 없기 때문입니다. 제가 보는 트레이스는 제 워크스테이션에서 돌리는 리버스 프록시의 트레이스가 전부입니다.

목록

#

표에서 “두 앱 모두"라고 적지 않은 건 전부 마켓플레이스 얘기입니다. 견적 앱은 이보다 적습니다. Fly의 헬스 체크, 로그, 메트릭, iOS 앱 분석, 그리고 데이터베이스를 매일 Parquet으로 내보내 DuckDB로 조회하는 것 정도죠. 크래시 리포팅도 알림 채널도 없고, 이 글에서 가장 큰 빈틈이 바로 이겁니다. (업데이트 서비스 행에 대해 밝혀 둘 것: 이 서비스를 만든 회사는 그쪽 블로그에 글을 쓰는 대가로 제게 돈을 지급합니다.)

에러: 채팅으로 올리는 로깅 핸들러

#

9월 전까지는 처리되지 않은 500, 실패한 푸시 알림, 깨진 WebSocket 프레임이 나타나는 곳이 flyctl logs뿐이었고, 그 스트림을 누가 시키지도 않았는데 읽는 사람은 없습니다. 지금은 로깅 핸들러가 ERROR 이상인 모든 레코드를 API, WebSocket 서버, 백그라운드 워커 어디서 나든 채팅 채널로 보냅니다. 경고(WARNING)는 일부러 알리지 않습니다.

핸들러는 백그라운드 스레드에서 전송하니 요청을 느리게 만들지 않습니다. 핸들러 안에서는 아무것도 로그를 남기지 않으니 재귀에 빠질 일도 없습니다. 그리고 같은 에러는 10분에 한 번까지만, 시간당 최대 30건까지만 보내서, 장애가 나도 메시지 천 개가 아니라 하나로 읽힙니다.

이 채널에는 에러와 나란히 놓고 읽고 싶은 것들도 올라옵니다. 배포는 시작할 때, 올라왔을 때, 실패한 지점에서 커밋과 실행한 사람을 함께 올리고, OTA 업데이트와 웹 릴리스도 마찬가지입니다. 한 계정에 잘못된 로그인 코드가 몰리면 그것도 ERROR로 남기 때문에, 누가 비밀번호를 찍어 보고 있으면 장애와 같은 자리에 나타납니다.

10월에는 어느 로그에도 대응하는 줄이 없는 알림이 하나 왔습니다. 그 뒤로 알림마다 짧은 랜덤 id, 호스트명, 프로세스 시작 명령을 붙이고, 같은 줄을 그 프로세스의 로그에도 씁니다. 그래서 id를 어디서도 못 찾으면, 그 알림은 그곳에 로그를 남기지 않는 프로세스, 예컨대 SSH 셸에서 온 겁니다. 채널에 올라오는 건 전부, 제가 같이 일하는 코딩 에이전트가 읽을 수 있는 피드에도 들어갑니다. 코드를 만지는 에이전트도 제가 보는 시점에 같은 에러를 보는 거죠.

로그: Fly의 로그 쉬퍼로 S3에 쌓고 DuckDB로 조회

#

Fly 자체 버퍼는 몇 분치 출력, 대략 마지막 백 줄 정도를 갖고 있습니다. 배포를 지켜보기엔 충분하지만 어제 일에는 쓸모가 없죠. 그래서 세 번째 Fly 앱에서 Fly의 로그 시퍼를 돌립니다. 조직의 로그 스트림을 구독하는 Vector인데, S3 싱크 하나만 바꿨습니다.

[sinks.aws_s3]
  type = "aws_s3"
  bucket = "myapp-logs"
  compression = "gzip"
  key_prefix = "logs/{{fly.app.name}}/%F/"   # one folder per app per day
  batch.timeout_secs = 300                  # a quiet app still lands its lines

마켓플레이스 앱들의 모든 로그 줄이 gzip으로 압축된 JSON으로 S3 호환 버킷에 쌓입니다. 시퍼는 256MB짜리 shared-cpu-1x 머신 한 대로, 한 달에 2달러 정도에 스토리지는 푼돈입니다. DuckDB는 매크로 하나로 파일을 제자리에서 읽고, 하루치가 1초 안팎이면 나옵니다.

CREATE MACRO logs(app, day := '*') AS TABLE
  SELECT * FROM read_json_auto('s3://myapp-logs/logs/' || app || '/' || day || '/*.log.gz',
                               union_by_name := true);

SELECT timestamp, message FROM logs('myapp-api', '2026-09-06') WHERE message LIKE '% 500 %';

0으로 스케일 다운 글에서 콜드 스타트를 잰 것도 이 매크로였습니다. 시작 스크립트가 단계마다 알리고, 줄마다 머신 id가 붙어 있으니, 나머지는 GROUP BY 한 번이면 됩니다.

정리하면 하나의 스트림을 읽는 사람에 따라 세 단계로 나눈 셈입니다. 아카이브는 INFO 이상을 전부 보관하고(프로덕션 앱이 INFO로 로그를 남기는 이유이기도 합니다), 실시간 확인 스크립트는 경고와 에러만 보여주고, 채팅 채널은 ERROR를 받습니다. 다만 셋 다 호출한 쪽은 모릅니다. 액세스 로그에 클라이언트 IP도 user agent도 없어서, 그건 Cloudflare에서 봅니다.

메트릭: Fly에 기본으로 딸린 Prometheus

#

Fly는 조직마다 매니지드 Prometheus를 돌려주기 때문에 저는 메트릭 스택을 따로 운영하지 않습니다. 궁금한 게 생기면 API를 칩니다. 머신별 메모리, CPU, 버스트 크레딧(공유 CPU에서는 fly_instance_cpu_balance가 중요합니다), 앱별 응답 수와 동시 요청 수 같은 것들이죠. 처음부터 알았으면 좋았을 게 두 가지 있습니다. fly tokens create로 만든 토큰은 Authorization: FlyV1 <token>으로 보내야 합니다. Bearer는 flyctl auth token의 개인 토큰에만 통하고, 읽기 전용 토큰은 “something went wrong resolving organization"을 돌려줍니다. 그리고 보관 기간이 2주 정도입니다(Fly 설명으로는 15일쯤).

이게 제 몫을 한 건 9월이었습니다. 로그에 “Could not open a database connection"이 하루에도 몇 번씩 찍혔고, 딱 앱 버그처럼 보였습니다. 매니지드 Postgres 클러스터도 같은 Prometheus에 들어 있었는데, 그 에러가 난 매 분마다 프라이머리의 스크레이프 시간이 80밀리초 남짓에서 1~10초로 뛰었고, 레플리카는 멀쩡했고, Postgres 시작 시각은 그대로였습니다. Postgres가 재시작된 게 아니라 그 아래 호스트가 멈췄던 겁니다. 타임스탬프를 Fly 지원팀에 보냈고, 10월 초 점검 재시작으로 프라이머리가 다른 호스트로 옮겨진 뒤로 매일 나던 멈춤은 사라졌습니다.

크래시 리포트: 제 API를 바라보는 Sentry SDK

#

예전에는 폰에서 앱이 죽어도 제가 볼 수 있는 곳 어디에도 흔적이 남지 않았습니다. 뻔한 답은 Sentry였고, 저는 그 절반만 가져왔습니다. 앱에는 Sentry의 오픈소스 SDK가 들어 있지만 DSN은 제 Django API의 엔드포인트를 가리킵니다. 그 엔드포인트가 Sentry의 envelope 형식을 받아서 크래시를 묶고, 같은 채팅 핸들러로 알립니다. 트레이싱, 세션, 리플레이는 꺼 두었고 에러만 받습니다.

sentry.io에 가입하지 않은 건, 하루 몇 건 수준의 리포트를 위해 사용자 데이터를 쥔 업체 하나, 개인정보 처리방침 한 줄, 청구서 하나를 더 늘리고 싶지 않았기 때문입니다. 그 대가는 심볼리케이션이고, 이건 아직 대체하지 못했습니다. 스택은 minify된 JavaScript거나 날것의 네이티브 주소라서, 이슈를 보면 무엇이 어느 릴리스와 기기에서 죽었는지, 직전에 사용자가 뭘 했는지는 알지만 소스의 어디인지는 모릅니다.

대시보드는 메시지 하나

#

두 앱 모두 대시보드를 따로 만들지 않았습니다. 작년 글에 대시보드를 가리는 기준을 하나 적었는데, 아무도 알아서 열지 않는 대시보드라면 존재 가치를 증명하지 못한 거라는 겁니다. 알아서 도착하는 메시지는 열 필요가 없으니, 제게 가장 대시보드에 가까운 건 매일 아침 팀 채팅에 올라오는 글 하나입니다.

맨 앞은 지난 24시간의 프로덕션 에러입니다. 채팅 채널이 아니라 로그 아카이브에서 읽는데, 알림은 횟수가 제한돼 있어서 무언가가 몇 번 일어났는지 말해 주지 못하기 때문입니다. 숫자, id, 주소를 가린 뒤 묶기 때문에 같은 실패 백 건은 횟수가 붙은 한 줄이 되고, 이메일 주소가 채널에 흘러들 일도 없습니다.

그다음이 실패한 헬스 체크, 전날 사용량을 일주일 전 같은 요일과 비교한 것(일요일은 월요일과 절대 같지 않으니까요), 최근 일주일 검색 유입, 답장을 기다리는 채팅, 작업 보드, 그리고 지출입니다. 불러오지 못한 섹션이 있으면 그렇다고 적고, 글은 그래도 올라갑니다.

앱 분석 데이터를 API로 읽다 보면 숫자를 조금은 의심하게 됩니다. 8월에는 아제르바이잔에서 Android 첫 실행이 121건 찍히고 그 뒤로 삭제가 119건 따라왔는데, 그달 Android 합계는 이걸 빼고 읽습니다.

릴리스에는 따로 보는 화면이 있습니다. OTA 업데이트를 제 서버에서 내보내던 시절, 릴리스를 보는 방법은 “is active” 체크박스가 달린 관리자 목록이 전부였고, 업데이트를 받은 폰이 몇 대인지 전혀 몰랐습니다. 지금 쓰는 서비스의 대시보드는 기기들이 실제로 어떤 릴리스를 돌리는지, 설치가 어떻게 됐는지, 그리고 잘못된 번들이 죽어서 SDK가 이전 번들로 되돌렸을 때의 크래시 롤백까지 보여줍니다. 호스팅 업데이트 서비스로 옮긴 이야기는 따로 정리해 두었습니다.

버린 것, 또는 더는 믿지 않게 된 것

#

이 중 유료 도구는 하나도 없습니다. 대부분은 신호인 줄 알았는데 신호가 아니었던 것들이고, 하나는 잘못된 곳에서 돌던 작업입니다.

user agent로 묶어 보기 전까지의 Cloudflare 504 비율

#

9월에 Cloudflare 대시보드를 보니 하루 요청의 22%가 504로 실패하는 것처럼 나왔습니다. 앱이 30초마다 폴링하는 엔드포인트에 몰려 있었는데, 헬스 체크는 전부 정상이었고 앱 자체 로그로는 그 요청들이 빨랐습니다. 며칠을 매달렸습니다. 머신이 콜드 스타트에 25~33초가 걸리고 그걸 하루 92번 한다는 걸 찾아내 고쳤고, 0으로 스케일 다운 글에 그게 원인이라고 썼습니다.

다음 날 아침 같은 504를 user agent로 묶어 봤습니다. 9월 5일부터 9일 사이의 7,344건이 전부 Cloudflare 자체의 Early Hints 캐시 조회(user agent는 bastion early hints, nginx-ssl early hints)였습니다. 이 조회는 오리진에 아예 가지 않습니다. 그 줄의 504는 타임아웃이 아니라 캐시 미스를 기록한 것이죠. 실제 요청 경로를 따라 하기 때문에 가장 바쁜 엔드포인트에 떨어졌고, 정말로 사용자가 실패하는 것처럼 보였습니다. 앱, 브라우저, curl, 검색 엔진 크롤러에서는 한 건도 없었습니다. 오리진이 Link 헤더를 보내지 않으니 Early Hints는 아무 일도 하고 있지 않았고, 그래서 일단 껐습니다. 나중에는 제대로 동작하게 만들었습니다.

콜드 스타트 작업은 그래도 남는 게 있었습니다. 배포도 깨어나는 것도 빨라졌으니까요. 하지만 고친다고 생각했던 장애는 사용자에게 닿은 적이 없었습니다.

그래서 꼭 전하고 싶은 규칙이 이겁니다. CDN의 에러율을 믿기 전에 user agent로 묶어서, 그게 CDN 자기 장치에서 나온 게 아닌지 확인하세요. Cloudflare 무료 플랜에서는 httpRequestsAdaptiveGroups에 대한 GraphQL 쿼리로, 하루씩 끊어서 볼 수 있습니다. 다음 소동도 같은 쿼리로 정리됐습니다. 폴링 엔드포인트 하나가 하루 70~260건에서 2,880건으로 뛰었는데, 스크레이퍼가 아니었습니다. 테스트하고 나서 iOS 시뮬레이터에 앱을 켜 둔 채로 둔 제 Mac이었습니다.

초록불 헬스 체크

#

Fly는 두 앱의 /api/health/를 30초마다 확인하고, 그 결과로 어느 머신에 트래픽을 보낼지 정합니다. 그 일은 잘합니다. 하지만 헬스 체크는 이미 떠 있는 머신을 상대로 돌기 때문에, 머신이 뜨기 전에 일어나는 일은 보지 못합니다. 콜드 스타트, 프록시 앞의 대기열, 끝내 도착하지 않는 요청 같은 것들이죠. 지금은 라우팅 말고는 바라는 게 없습니다.

배포 때는 대신 프로브 스크립트를 씁니다. 배포 내내 오리진을 치다가 하나라도 실패하면 1로 종료합니다. 이 스크립트가 평범한 flyctl deploy에서 7.3초짜리 공백을 잡아냈고, 예비 머신을 먼저 깨우는 배포 스크립트로 바꾼 뒤에는 2,514건 중 실패가 0건이었습니다.

헬스 체크는 스스로 장애를 두 번 일으키기도 했습니다. 7월에는 Django의 SECURE_SSL_REDIRECT가 Fly의 평문 HTTP 프로브에 301로 답해서, 모든 머신이 체크에 실패했고 모두가 503을 받았습니다. 8월에는 헬스 뷰의 except Exception을 좁혔더니 “connection already closed” 에러가 500으로 새어 나갔고, 뷰의 재시도가 바로 그 경우를 위해 있었는데도 Fly가 머신을 빼 버렸습니다. 지금 체크는 이 프로세스가 요청을 처리할 수 있는지만 묻고, DB가 멈춰도 두 앱이 라우팅에서 빠지지 않습니다.

아침 요약도 세는 법에서 같은 교훈을 얻었습니다. 마켓플레이스는 놀고 있는 머신을 서스펜드하기 때문에, 요청에 깨어난 머신은 시작 후 몇백 밀리초 만에 첫 체크에 실패하고 다음 체크는 통과합니다. 이걸 세다 보니 매일 아침이 장애처럼 읽혔고, 그래서 1분 안에 다시 통과한 실패는 이제 머신 기상과 배포로 따로 적습니다.

CI의 예약 작업

#

아침 요약은 cron 일정으로 도는 CI 워크플로로 시작했다가 하루 만에 옮겼습니다. 앱 분석과 검색 데이터를 읽게 되자 필요한 키가 분석 프로젝트의 서비스 계정 키였는데, 그 프로젝트에서 뭐든 할 수 있는 키라 CI 시크릿에 두고 싶지 않았습니다. 지금은 제 Mac의 스케줄러가 20분마다 실행하고, 오클랜드 시간으로 아침 8시가 지났는데 오늘 글이 아직 안 올라갔을 때만 올립니다. 그러니 8시에 잠들어 있던 Mac은 깨어나면서 올리죠. 워크플로는 앱 분석과 검색 섹션을 뺀 수동 대비책으로 남겨 두었습니다.

다시 시작한다면

#

첫 장애가 난 뒤가 아니라 첫 사용자가 오기 전에 세 가지를 깔겠습니다. 팀이 이미 읽는 채팅 채널로 에러 보내기(횟수 제한 포함), SQL로 조회할 수 있는 오브젝트 스토리지 로그 아카이브, 그리고 플랫폼이 이미 모으고 있는 메트릭. 한 달에 몇 달러면 됩니다. 크래시 리포팅은 앱이 폰에 올라가는 주에 붙입니다. 그러지 않으면 폰에서 난 크래시는 아무에게도 아무것도 알려주지 않으니까요. 아침 요약은 확인할 곳이 너무 많아져서 결국 아무 데도 확인하지 않게 될 즈음에 붙이면 됩니다.

트레이싱은 요청이 넘나들 두 번째 서비스가 생길 때까지, 호스팅 APM은 공유 대시보드와 온콜 순번, 남의 청구서를 감당할 예산이 필요한 팀이 생길 때까지 미루겠습니다. 작년 글의 도구들이 제값을 하기 시작하는 건 그때부터입니다. 그 전까지 가장 쓸모 있는 습관은 공짜입니다. 숫자가 무서워 보이면, 무엇이 고장났는지 정하기 전에 그 숫자를 무엇이 만들었는지부터 확인하세요. 이 글에 나온 소동 중 여럿은 프로덕트가 아니라 모니터링에서 나왔습니다.

GitHub Actions에서 Docker Compose를 돌리는 법을 찾아 오셨다면, 결론부터. 저는 그걸 2년 하다가 그만뒀습니다. 지금 CI는 같은 Postgres와 Valkey 이미지를 services:로 선언하고, 같은 uv run …과 npm run … 명령을 러너에서 바로 돌립니다. Compose는 개발자가 로컬에서 돌리는 것으로 남았고요. 나머지는 그 이유와 실제 파일들입니다.

2024년에 플랫폼 종속 YAML 대신 Docker Compose로 CI/CD 하기라는 글을 썼습니다. 빌드 로직은 Compose에 두고 CI 도구는 그걸 호출하는 일만 하게 하라는 내용이었죠. 2년이 지나 제가 실제로 배포하는 저장소를 전부 다시 훑어봤습니다. 워크플로가 있는 저장소는 넷이고, 커미터는 모두 저 한 명입니다. 그리고 그 워크플로 중 docker compose를 호출하는 건 이제 하나도 없습니다. 원칙은 살아남았고, 방법은 살아남지 못했습니다. 아래는 그 자리를 대신한 것들입니다. 줄여서 예제로 만든 파일, GitHub가 기록한 단계별 소요 시간, 그리고 CI/CD 다이어그램이 바라는 것보다 덜 자동화된 부분까지 적었습니다.

제가 돌리는 파이프라인 전부, 표 하나로

#

교과서 용어로 말하면 두 Hugo 사이트는 지속적 배포이고, 앱(제가 만드는 마켓플레이스 겸 커뮤니티 앱)은 지속적 통합에 명령 한 줄짜리 릴리스를 더한 지속적 전달입니다. 체크는 뭔가 잘못됐다고 알려 줄 뿐, 배포를 막지는 않습니다. 일부러 이렇게 나눴습니다. OTA 업데이트는 대상 바이너리 버전을 쓰는 모든 휴대폰에 닿으니, 머지의 부작용이 아니라 결정이어야 합니다. 그리고 API는 데이터베이스 마이그레이션이 실행되는 곳입니다. 제 나머지 Django 앱 두 개에는 워크플로가 아예 없습니다.

CI 쪽: 워크플로 하나, 잡 두 개

#

앱의 CI는 .github/workflows/checks.yml 파일 하나입니다. 10월 11일 전까지는 이것조차 없었습니다. 아래는 그 구조를 줄여서 만든 예제입니다.

# Lint, types and tests on every push and pull request to main.
# Nothing here deploys.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: checks-${{ github.ref }}
  cancel-in-progress: true

jobs:
  python:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: myapp
          POSTGRES_PASSWORD: myapp
          POSTGRES_DB: myapp
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U myapp"
          --health-interval 5s --health-timeout 5s --health-retries 20
      valkey:
        image: valkey/valkey:8-alpine
        ports: ["6379:6379"]
    env:
      DEBUG: "True"
      DATABASE_URL: postgresql://myapp:myapp@localhost:5432/myapp
      REDIS_URL: redis://localhost:6379
      PYTHON_JIT: "0"   # match production
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          prune-cache: true
      - run: uv sync --locked
      - run: uv run ruff check .
      - run: uv run mypy myapp/
      - run: uv run python manage.py test --parallel 4 --noinput

  app:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      # Expo writes this on `expo start` and it is gitignored,
      # so a fresh checkout doesn't have it.
      - run: printf '/// <reference types="expo/types" />\n' > expo-env.d.ts
      - run: npm run typecheck
      - run: npx jest --ci

두 잡은 나란히 돕니다. 지금까지 성공한 35번의 실행에서 앱 잡의 중앙값은 7분쯤, Python 잡은 12분 반쯤입니다.

services: 블록이 바로 Compose 파일이 옮겨 간 자리인데, 다음 절에서 다룹니다. 환경 변수는 몇 개와 플래그 하나뿐입니다. 나머지는 전부 개발자가 docker compose up에서 받는 개발용 기본값으로 떨어지기 때문에, 테스트에는 시크릿이 하나도 필요 없습니다. 정말 그런지 보려고 딱 그 환경만, 다른 건 아무것도 없이 테스트 일부를 돌려 확인했습니다.

CI는 제 노트북, 프로덕션 이미지와 같은 인터프리터, 즉 uv가 직접 빌드한 Python 3.15.0으로 돕니다. uv sync가 .python-version을 읽고 정확히 그 빌드를 내려받기 때문입니다. (실제 파일에서는 setup-uv에 python-version-file 입력도 넘기는데, 이건 아무 일도 하지 않습니다. setup-uv v6에는 그런 입력이 없고, 매 실행마다 그렇다는 경고가 붙어 있습니다. 이 글을 쓰다가야 알았습니다.)

인터프리터를 맞춘 보람은 워크플로를 넣은 지 8일 만에 나타났습니다. 10월 19일에 3.15의 JIT 컴파일러를 켰더니, 켠 뒤 첫 실행에서 테스트 하나가 실패했습니다. 앱이 저장할 때마다 지나가는 코드 경로의 평범한 yield from이 AttributeError: 'list' object has no attribute 'send'를 던진 겁니다. 같은 커밋을 JIT를 끄고 돌리면 통과했습니다. 제 Mac은 arm64라서 이 문제를 한 번도 만나지 않았고, 러너는 프로덕션 머신과 같은 x86_64입니다. JIT는 CI에서도 Dockerfile에서도 다시 꺼 두었고, 버그는 프로덕션에 닿지 않았습니다. python/cpython#155823로 올라가 있던 버그로, 3.15.0이 나온 뒤인 10월 13일에 업스트림에서 고쳐졌습니다.

사실 맨 첫 실행도 실패했는데, 이유는 더 시시했습니다. Expo는 expo start를 할 때 expo-env.d.ts를 만들고 이 파일은 gitignore되어 있습니다. 그래서 제가 쓰던 작업 사본에는 모두 있었고, 새로 받은 체크아웃에는 없었죠. TypeScript가 로컬에서는 한 번도 보지 못한 오류 다섯 개를 냈습니다. 그 파일을 써 주는 단계가 해결책입니다.

concurrency는 같은 브랜치에 더 새로운 push가 오면 이전 실행을 취소합니다. 지금까지 취소된 12번의 실행은 모두 이렇게 끝났습니다. 커밋 전 훅(pre-commit hook)이 린터를 돌리고, Python이나 TypeScript가 스테이징돼 있으면 타입 체커도 돌리기 때문에 실수는 대부분 push까지 가지도 않습니다.

Docker Compose 파일은 어디로 갔나

#

앱의 docker-compose.yml에서 CI와 관련된 부분을 예제로 옮긴 것입니다. 실제 파일에는 서비스도 더 있고 환경 변수도 훨씬 많습니다.

services:
  valkey:
    image: valkey/valkey:8-alpine
    ports:
      - "6379:6379"

  # Host port 55432, not 5432, so it can't collide with a local Postgres.
  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=myapp
      - POSTGRES_PASSWORD=myapp
      - POSTGRES_DB=myapp
    ports:
      - "55432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myapp"]
      interval: 5s
      retries: 10

  api:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp
      - REDIS_URL=redis://valkey:6379
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started

volumes:
  postgres_data:

checks.yml의 services: 블록 옆에 놓고 보면 같은 이미지 두 개입니다. Postgres 17(여기서는 Alpine 빌드, CI에서는 Debian 빌드)과 valkey/valkey:8-alpine. 지금의 관계는 이렇습니다. Compose 파일은 개발자가 돌리는 것이고, CI는 같은 이미지를 서비스 컨테이너로 선언한 다음 개발자가 돌리는 것과 같은 명령, uv run …과 npm run …을 러너에서 바로 돌립니다.

2024년 글과 비교하면, 제가 가장 신경 쓰던 부분은 살아남았습니다. CI 도구는 얇고, 체크와 배포는 제가 직접 돌릴 수 있는 명령입니다. 살아남지 못한 건 CI가 Compose를 호출하는 방식입니다.

앱의 CI는 Docker 이미지를 아예 빌드하지 않습니다. 이미지는 배포할 때 Fly의 빌더가 한 번 빌드하고, CI는 코드가 괜찮은지만 말해 주면 됩니다. 툴체인이 캐시돼 있으면 그건 6초짜리 설치로 끝납니다. 게다가 Compose 파일은 작업 사본을 바인드 마운트하고 데이터를 시드하는데, 테스트 실행이 할 일은 아닙니다. 그러니 CI용 Compose 파일이 따로 필요했을 테고, 그건 같은 서비스를 두 번째로 정의해 손으로 맞춰 가야 한다는 뜻입니다.

그리고 2024년 예제에는 당시 눈치채지 못한 버그가 있었습니다. docker compose build는 이미지를 빌드할 뿐 서비스의 command를 실행하지 않습니다. 그러니 그 파일의 npm test는 CI에서 한 번도 돌지 않았고, 워크플로는 테스트가 통과하든 말든 초록불이었습니다.

그 글이 가장 걱정했던 위험, 즉 CI 업체를 바꾸는 일은 결국 일어나지 않았습니다. 실제로 일어난 이동은 반대쪽 끝에서였습니다. 이 블로그와 그 클라이언트 사이트가 호스팅을 Cloudflare Pages로 옮겼는데, 블로그 쪽은 45줄짜리 워크플로 하나를 새로 쓰는 걸로 끝났습니다. 빌드가 원래 명령 한 줄이었기 때문이죠. 그리고 제가 경고했던 300줄짜리 워크플로요? 하나 있습니다. pyhtml2text의 워크플로입니다. wheel을 Linux, macOS, Windows 러너에서 각각 여러 아키텍처로 빌드해야 해서 긴 건데, 그래서 플랫폼 전용 YAML이 맞는 도구인 유일한 작업이기도 합니다.

캐싱: 단계별 소요 시간부터 읽기

#

GitHub는 모든 단계의 소요 시간을 기록해 두고, gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs로 꺼내 볼 수 있습니다. 아래는 10월 20일, 앱의 가장 최근 성공 실행입니다.

의존성 캐시 두 개는 모두 켜져 있고, 둘 다 저렴한 부분입니다. GitHub가 이 저장소용으로 보관하는 uv 캐시는 200KB 정도인데, setup-uv가 다시 내려받으면 되는 것들은 정리해 버리기 때문입니다. npm 캐시는 400MB에 가깝습니다. 시간이 드는 곳은 테스트이고, 테스트는 이미 4갈래로 병렬 실행됩니다. 실행을 더 빠르게 하고 싶다면 캐시가 아니라 테스트 스위트를 손보겠습니다.

블로그는 정반대입니다. Hugo가 처리한 이미지는 gitignore된 resources/_gen에 있어서, 새 러너마다 커버, 본문 이미지, 플레이스홀더를 전부 다시 인코딩했습니다. 아래 워크플로는 actions/cache로 이것을 복원합니다. 키는 사진 자체의 해시이고, 키가 맞지 않으면 가장 최근의 이전 캐시로 대신합니다. Hugo는 빠진 것만 처리하니까요. 캐시를 넣기 전 마지막 8번의 실행에서 빌드 단계는 3376초 걸렸고, 넣은 뒤 26번은 620초였습니다. 94초가 한 번 있었을 뿐이고, 같은 커밋에서 플레이스홀더와 두 번째 카드 크기까지 추가했는데도 그렇습니다.

앱의 이미지는 Fly의 빌더에서 빌드되고, 의존성 파일을 코드보다 먼저 복사하며 uv의 다운로드 캐시는 BuildKit 캐시 마운트(RUN --mount=type=cache,target=/root/.cache/uv)에 둡니다. 하지만 더 큰 개선은 캐시가 아니었습니다. 예전 .dockerignore는 블록리스트였는데, 추가 git worktree들을 모아 둔 폴더를 빠뜨렸습니다. worktree마다 자기 의존성과 빌드 산출물이 들어 있었죠. 그래서 파일 27만 7천 개, 7.7GB가 배포할 때마다 빌더로 올라갔습니다. 허용 목록으로 다시 쓴 지금은 빌드 컨텍스트가 40MB 정도입니다. 그 패턴을 예제로 보면 이렇습니다.

# Exclude everything, then let back in only what the Dockerfile COPYs.
*

!pyproject.toml
!uv.lock
!manage.py
!myapp
!static

# Rules match the whole relative path and the last match wins,
# so these re-excludes apply inside the allowed directories too.
**/__pycache__/
**/*.pyc
**/.DS_Store
**/*.log

시크릿은 최대한 적은 곳에

#

시크릿은 세 군데에 있습니다. GitHub Actions 시크릿은 워크플로가 하는 일을 위한 것이고, 두 Hugo 저장소에는 CLOUDFLARE_API_TOKEN 딱 하나씩만 있습니다. Fly 시크릿은 앱의 런타임 설정으로 flyctl secrets set으로 넣고, Actions를 거치지 않습니다. 그리고 제 노트북의 gitignore된 .env에는 배포 스크립트가 Cloudflare 캐시를 비울 때 쓰는 토큰이 있습니다.

PyPI에는 시크릿이 아예 필요 없습니다. pyhtml2text는 신뢰할 수 있는 게시(trusted publishing)를 씁니다. PyPI가 GitHub이 워크플로에 발급하는 수명 짧은 OIDC 토큰을 받아 주기 때문에, 릴리스 잡은 id-token: write만 요청하고 저장소의 시크릿 페이지는 비어 있습니다. 샐 것도, 교체할 것도 없죠.

토큰에는 필요한 만큼만 줍니다. GitHub에 있는 앱의 Fly 토큰은 머신 목록만 조회하는 예약 체크용이라 fly tokens create readonly로 만들었습니다. Pages 배포는 contents: read와 deployments: write만 요청하고 그 이상은 없습니다.

입력값은 스크립트에 바로 넣지 않고 반드시 env:를 거칩니다. OTA 워크플로는 자유롭게 쓰는 릴리스 노트를 받습니다. 이걸 run: 안에 ${{ inputs.notes }}로 쓰면 bash가 읽기 전에 텍스트가 스크립트에 그대로 붙여 넣어지니, 따옴표와 세미콜론이 든 노트는 코드가 되어 버립니다. 환경 변수로 넘기면 데이터로 남습니다. 패턴을 예제로 보면 이렇습니다.

      - name: Publish
        env:
          OTA_API_TOKEN: ${{ secrets.OTA_API_TOKEN }}
          INPUT_PLATFORM: ${{ inputs.platform }}
          INPUT_ROLLOUT: ${{ inputs.rollout }}
          INPUT_NOTES: ${{ inputs.notes }}
        run: |
          args=("$INPUT_PLATFORM")
          [ -n "$INPUT_ROLLOUT" ] && args+=(--rollout "$INPUT_ROLLOUT")
          [ -n "$INPUT_NOTES" ] && args+=(--notes "$INPUT_NOTES")
          ./scripts/publish-ota.sh "${args[@]}"

아예 GitHub 밖에 두는 키도 있습니다. 예약 리포트 하나에는 앱의 로그인 백엔드에 대한 관리자 권한이 있는 키가 필요해서, 그 리포트는 예약 워크플로에서 제 Mac의 예약 작업으로 옮겼습니다. 워크플로는 수동 예비용으로 남아 있고, 그 키가 필요한 섹션은 빼고 게시합니다.

배포: push마다, 스크립트로, 태그로

#

Hugo 사이트는 push마다 배포됩니다

#

블로그 워크플로를 예제로 옮긴 것입니다. Pages 프로젝트를 처음 만드는 단계는 뺐습니다.

name: Deploy to Cloudflare Pages

on:
  push:
  workflow_dispatch:

env:
  HUGO_VERSION: "0.165.0"
  PAGES_PROJECT: my-site

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: true

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      # Processed images are gitignored; restore them so Hugo only
      # re-encodes what is new. An older cache still helps.
      - uses: actions/cache@v6
        with:
          path: resources/_gen
          key: hugo-resources-${{ hashFiles('content/**/*.jpg', 'content/**/*.png', 'assets/img/**') }}
          restore-keys: |
            hugo-resources-

      # A multilingual site has no root 404.html; without one, Pages
      # answers unknown paths with index.html and a 200.
      - name: Build
        run: |
          hugo --gc
          cp public/en/404.html public/404.html

      # ...

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}

--branch=${{ github.ref_name }} 덕분에 main은 프로덕션이 되고 다른 브랜치는 모두 미리보기 URL을 받습니다. 클라이언트 사이트의 워크플로는 이것과 같은 구조에 빌드 전 rm -rf public 한 줄이 더 있습니다. 그쪽은 public/이 커밋되어 있어서, 안 그러면 삭제한 페이지가 업로드에 계속 남기 때문입니다.

Hugo 버전은 여기에서만 고정합니다. 10월에 패키지 매니저 업그레이드로 제 노트북의 Hugo가 0.168이 됐는데, 테마가 지원하는 최신 버전보다 하나 높습니다. 배포는 0.165에 머물렀고 아무 일도 없었습니다.

그리고 빌드가 곧 테스트입니다. 9월 14일, 한 브랜치의 미리보기 배포가 세 번 연달아 실패했습니다. 그 브랜치의 글 하나가 Hugo의 ref로 아직 초안인 글을 가리키고 있었거든요. CI는 프로덕션이 빌드하는 것과 똑같이, 초안을 빼고 빌드합니다. 그러니 링크는 아무것도 가리키지 않았고 Hugo는 REF_NOT_FOUND로 멈췄습니다. 그동안에도 main은 계속 배포되고 있었습니다.

앱의 API는 스크립트로 배포합니다

#

배포 스크립트의 핵심을 예제로 옮긴 것입니다.

IMAGE_LABEL="deploy-$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"

# Build first, then wake a spare machine, then roll out exactly that image.
flyctl deploy --config fly.toml --build-only --push --image-label "$IMAGE_LABEL"
curl -fsS --retry 5 https://myapp.fly.dev/health > /dev/null
flyctl deploy --config fly.toml --image "registry.fly.io/myapp:$IMAGE_LABEL"

그리고 fly.toml에서 짝이 되는 부분입니다.

[deploy]
  # max_unavailable only counts machines that are running,
  # which is why the script wakes one first.
  strategy = "rolling"
  max_unavailable = 1

이미지는 한 번 빌드해서 커밋과 시각으로 만든 라벨을 붙여 Fly 레지스트리에 올리고, 그 라벨로 배포합니다. 그래서 롤아웃되는 건 정확히 빌드한 그것입니다.

무중단 배포를 가능하게 하는 건 예비 머신을 먼저 깨우는 단계입니다. max_unavailable = 1은 실행 중인 머신만 셉니다. 그런데 앱은 한가할 때 실행 중인 머신을 하나도 두지 않습니다(일시 정지된 머신은 1초 남짓이면 깨어납니다). 그래서 깨어 있던 머신 하나가 잠든 머신들과 같은 묶음에서 교체되곤 했고, 그 뒤에는 따뜻한 머신이 하나도 없었습니다. 9월 28일에 오리진에 프로브를 계속 보내 봤더니, 그냥 flyctl deploy를 할 때는 타임아웃 7번과 7.3초의 공백이 있었고, 먼저 빌드하고 롤아웃 전에 머신 하나를 깨워 두는 스크립트 배포로는 요청 2,514개 중 실패가 하나도 없었습니다.

스크립트의 나머지는 오류 알림이 오는 팀 채팅 채널에 배포 표시를 남깁니다. 그래야 오류가 몰렸을 때 방금 무엇이 바뀌었는지와 맞춰 볼 수 있죠. 그리고 Cloudflare 캐시를 비우고 머신들을 데워 둡니다. 웹 프런트엔드는 이미지를 아예 거치지 않는데, 그건 프론트엔드와 백엔드 따로 배포하기에 적었습니다.

마이그레이션은 파이프라인 단계가 아닙니다. Fly의 release_command가 제 환경에서는 멈춰 버려서, 새 이미지로 처음 부팅하는 머신이 락을 잡고 마이그레이션하는 동안 나머지는 기다립니다. 그러니 모든 마이그레이션은 아직 돌고 있는 코드와도 맞아야 합니다. 컬럼은 한 배포에서 추가하고, 다음 배포에서 쓰지 않게 하고, 세 번째 배포에서 지웁니다.

이 스크립트에 꼭 제 노트북이어야 하는 부분은 없지만, 노트북에만 있는 파일 몇 개가 스크립트를 거기 묶어 둡니다. Cloudflare 자격 증명, 그리고 마지막으로 무엇을 배포했는지 적어 둔 기록입니다. 새 러너에는 이 파일들이 없죠. 커밋하지 않은 변경도 배포해 버리고 채팅 채널에 그렇다고 알리는데, 웹 릴리스 스크립트는 더러운 작업 트리를 거부합니다.

브랜치별 프리뷰 환경에서 저는 이걸 손으로 하는 건 혼자일 때는 괜찮지만, 두 번째 개발자부터는 git에서 뭔가 일어났기 때문에 일어나야 한다고 썼습니다. 앱의 개발자는 아직 한 명입니다. 그 글의 브랜치 환경 워크플로는 제가 만들었던 브랜치에 그대로 있습니다.

OTA 워크플로는 수동 전용입니다. 게시는 결정이어야 하고, 업데이트 서비스는 부분 롤아웃이 열려 있는 동안 새 릴리스를 거부하기 때문에 push 트리거라면 카나리 배포 때마다 걸릴 테니까요. 이 워크플로는 한 번도 실행된 적이 없습니다. 지금까지 OTA 업데이트는 전부 제 노트북에서, 워크플로가 호출하는 것과 같은 스크립트로 나갔습니다. 얇은 워크플로를 쓰는 이유가 한 줄로 이겁니다. 릴리스를 어떻게 시작하든 같은 스크립트죠.

pyhtml2text는 태그로 릴리스합니다

#

릴리스 잡입니다. 패키지 이름은 일반적인 이름으로 바꿨습니다.

  release:
    runs-on: ubuntu-latest
    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
    needs: [linux, macos, windows, sdist]
    environment:
      name: pypi
      url: https://pypi.org/p/mypackage
    permissions:
      id-token: write       # trusted publishing and signing
      contents: write
      attestations: write
    steps:
      - uses: actions/download-artifact@v8
      - uses: actions/attest@v4
        with:
          subject-path: 'wheels-*/*'
      - uses: astral-sh/setup-uv@v10
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        with:
          prune-cache: true
      - name: Publish to PyPI
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        run: uv publish --trusted-publishing always 'wheels-*/*'

릴리스 잡은 모든 빌드 잡을 기다리고, 실제 게시는 태그일 때만 합니다. 수동 실행은 빌드하고 증명(attestation)까지 만들지만 아무것도 올리지 않습니다. actions/attest는 어느 워크플로가 각 wheel을 빌드했는지 기록하고, uv publish --trusted-publishing always는 비밀번호 대신 OIDC 토큰으로 업로드합니다. 패키지 자체에 대해서는 닫힌 풀 리퀘스트, 포크, 그리고 PyPI 패키지에 썼습니다.

예약 워크플로는 최선을 다할 뿐입니다

#

앱에는 예약 워크플로가 하나 있습니다. Fly가 기준치보다 머신을 더 띄우지 않았는지 보는 체크로, 그냥 두면 청구서에서 처음 알게 될 일입니다. 알림은 일부러 실패하는 방식으로 보냅니다. 예약 실행이 실패하면 GitHub이 소유자에게 메일을 보내니까요.

설정은 cron: '*/15 * * * *', 하루 96번입니다. 그런데 지난 2주 동안은 하루 3~8번만 돌았고, 실행 간격의 중앙값은 3시간 40분쯤이었습니다. GitHub 문서가 내놓는 설명은 부하뿐입니다. Actions가 바쁘면 예약 실행이 늦어질 수 있고, 아주 바쁘면 빠질 수도 있다는 거죠. 계속되는 스케일 아웃이라면 몇 시간이면 충분합니다. 몇 분 안에 울려야 하는 것이라면 GitHub의 cron은 모니터링이 아닙니다.

파이프라인에 던져 볼 질문

#

파이프라인을 만들고 있거나 이미 있는 걸 들여다보고 있다면:

1. GitHub Actions가 하루 동안 멈추면 그래도 릴리스할 수 있나요? 못 한다면 릴리스 로직이 YAML 안에 있는 것이고, 2024년 글이 여전히 유효합니다.
2. CI가 프로덕션과 같은 인터프리터, 같은 CPU 아키텍처, 같은 데이터베이스 메이저 버전으로 도나요? 제 CI가 컴파일러 버그를 잡은 건 러너와 프로덕션은 둘 다 x86_64이고 제 노트북은 아니었기 때문입니다.
3. 새로 받은 체크아웃이 통과하나요? 안 된다면 대개 생성되고 gitignore된 파일 때문입니다.
4. 실행 시간은 실제로 어디에 쓰이나요? 캐시를 넣기 전에 단계별 소요 시간부터 읽어 보세요.
5. 시크릿마다 몇 군데에 있나요? 그리고 정말 GitHub에 있어야 하나요?

제 작업 환경은 좀처럼 한곳에 모이지 않는 기계 세 대입니다. 어디든 들고 다니는 MacBook Air가 있습니다. 사무실에는 devbox라는 워크스테이션이 있는데, 제대로 된 GPU가 달려 있고 Ollama, 파인튜닝 도구, 자체 컨테이너 레지스트리를 갖춘 작은 Kubernetes 클러스터, 그리고 긴 작업을 붙잡고 씨름하도록 놔둔 에이전트가 무엇이든 돌아갑니다. 그리고 폰이 있습니다. 제가 만드는 앱이 실제로 쓰이는 곳이고, 하루 대부분을 wifi가 아니라 모바일 데이터로 보내죠.

오랫동안 이 셋은 서로 제대로 이야기하지 못했습니다. 노트북은 사무실 LAN에 있을 때만 devbox에 닿았고 그 밖에서는 못 닿았습니다. 폰은 노트북과 같은 wifi에 있을 때만 노트북의 dev 서버에 닿았고, 그것도 제가 0.0.0.0에 바인딩하는 걸 잊지 않고 그날 아침 DHCP가 Mac에 준 주소를 직접 쳐 넣었을 때 얘기였습니다. 워크스테이션에서 재미있는 건 전부, 그러니까 Ollama API, 클러스터 대시보드, 트레이스, 레지스트리는 일부러 localhost나 클러스터 네트워크에 바인딩돼 있었습니다. 어느 것도 인터넷에 있을 물건이 아니니까요.

이 글은 Cloudflare WARP와 Cloudflare Tunnel 한 쌍으로 이것들을 어떻게 이었는지, 그게 AI 기능과 모바일 앱을 만드는 방식을 어떻게 바꿨는지, 그리고 저한테 말도 없이 고장 난 몇 가지에 대한 이야기입니다.

제가 실제로 원한 것

#

요구사항으로 적으면 짧습니다.

1. 노트북은 씬 클라이언트여야 합니다. GPU나 많은 RAM, 몇 시간의 실행 시간이 필요한 일은 전부 devbox에서 돌아야 하고, 노트북은 사무실에서든 집에서든 카페에서든 똑같은 방식으로 거기에 닿아야 합니다.
2. 폰은 어디서든, 모바일 데이터로, 켜고 끄는 걸 기억해야 하는 VPN 없이 제 dev 서버와 셸에 닿아야 합니다.
3. 시스템이 어떻게 돌아가는지 보는 데 쓰는 것들, 즉 대시보드, 트레이스, docker info, 모델 목록은 저만 닿을 수 있어야 하고, 공개 URL을 절대 가져서는 안 됩니다.
4. 인바운드 포트는 없습니다. 사무실 라우터에도, 집 라우터에도, 어디에도요.

네 번째 요구사항이 예전의 답, 즉 포트 포워딩과 동적 DNS 이름을 배제합니다. 잔재주도 상당수 배제되죠. devbox와 노트북 둘 다 제가 통제하지 못하는 NAT 뒤에 있고, 노트북은 몇 시간마다 다른 NAT 뒤에 있습니다.

이전: SSH 터널 저장소

#

첫 버전은 제가 직접 만든 작은 저장소였고, 지금도 바닥층으로 남아 있습니다. 노트북에서 “SSH로 닿는 것들에 깔끔한 이름 붙이기” 문제만 풀고, 그 이상은 하지 않습니다. dnsmasq가 *.test에 127.0.0.1로 답하고, Caddy가 호스트명에 따라 로컬 포트로 라우팅하면서 tls internal로 브라우저를 만족시키고, autossh launch agent 묶음이 SSH 포워드를 열어 두었다가 끊기면 다시 잇습니다. 호스트명이 그 물건이 어디 사는지 말해 줍니다.

그래서 https://devbox-ollama.ssh.test/api/tags는 워크스테이션의 모델 목록을 보여 주고, https://api.local.test는 제 기계에서 도는, 지금 작업 중인 앱의 API입니다.

.ssh나 .cloud 같은 새 최상위 이름이 아니라 .test의 서브도메인이고, .local도 아닙니다. RFC 6761이 바로 이런 용도로 .test를 예약해 두었고, .local은 mDNS 몫입니다. 그걸 가로채면 Mac에서 Bonjour 탐색이 멈춥니다. dnsmasq가 이미 *.test 전체를 와일드카드로 잡고 있으니 라벨 하나 더 붙이는 데 드는 비용은 없습니다. 127.0.0.1을 가리키는 /etc/resolver/test 파일 하나면 되고, 그 뒤로 DNS를 더 건드릴 일은 영영 없습니다.

존재하지 않는 이름에 HTTPS 붙이기

#

저 이름들은 전부 브라우저가 신뢰하는 인증서로 HTTPS 서비스됩니다. 제 노트북에만 존재하는 호스트명에 그게 된다니 불가능하게 들리죠. Caddy는 자체 내부 인증 기관으로 이걸 해냅니다. 사이트에 tls internal을 넣으면 Caddy는 Let’s Encrypt에 요청하는 대신 로컬 CA에서 그 사이트의 인증서를 발급하고, 설치 스크립트가 한 번 실행하는 caddy trust가 그 CA의 루트를 macOS 시스템 키체인(Chrome과 Safari가 읽는 곳)과 Firefox 자체 저장소에 넣습니다. 그다음부터 https://anything.test는 인증서 경고 없이 열리고, 평범한 http://는 그쪽으로 리다이렉트되며, 아무것도 기계 밖으로 나가지 않습니다.

겉모양만의 문제가 아닙니다. 요즘 웹 플랫폼의 상당 부분이 평범한 HTTP에서는 동작을 거부합니다. secure 쿠키, 서비스 워커, 클립보드 API, SameSite=None이 들어간 모든 것이요. 웹 빌드를 평범한 http://localhost에서 테스트하면 실제 HTTPS 도메인에서 나타날 버그가 가려집니다. https://app.local.test에서 테스트하면 그 버그가 제 노트북에서 대신 드러납니다.

사이트 블록 하나입니다. 포트만 빼면 모든 서비스가 똑같습니다.

devbox-ollama.ssh.test, devbox-ollama.test {
	tls internal
	import cors
	reverse_proxy 127.0.0.1:11435 {
		import proxyhdr
		transport http {
			keepalive off
			dial_timeout 5s
		}
	}
}

손이 많이 가는 부분은 두 스니펫이 맡습니다. cors는 *를 보내는 대신 호출한 쪽의 Origin을 그대로 돌려줍니다. 자격 증명이 끼는 순간 *는 허용되지 않기 때문입니다. 그리고 OPTIONS 프리플라이트에는 직접 204로 답해서 업스트림이 신경 쓸 필요가 없게 합니다. proxyhdr는 Host 헤더를 다이얼 주소로 바꿔 씁니다. 라우터 관리 페이지나 Chrome의 원격 디버깅 엔드포인트 같은 까다로운 백엔드는 Host를 검사하는데, 이게 없으면 devbox-ollama.ssh.test를 처음 듣는 이름이라며 거부합니다. Ollama의 자체 origin 검사는 포트와 상관없이 루프백을 받아 주니, Host를 127.0.0.1:11435로 바꿔 쓰면 통과합니다.

keepalive off는 제가 틀렸을 법한 부분입니다. 업스트림은 네트워크가 바뀔 때마다 autossh가 허물고 다시 세우는 SSH 포워드입니다. keep-alive가 켜져 있으면 Caddy는 이미 죽은 터널에 대한 풀링된 연결을 쥐고 있다가, 리로드할 때까지 영문 모를 404를 돌려줍니다. 끄면 요청마다 새로 다이얼하는데, 루프백에서는 측정할 만한 비용이 없습니다.

각 서비스는 예전의 평평한 이름(devbox-ollama.test)으로도 답하기 때문에, 접미사 체계 이전의 북마크도 여전히 동작합니다.

메뉴 막대

#

launchd가 포워드 십여 개를 열어 두고 있으니 제가 계속 던진 질문은 “살아 있나?“였고, 그 답은 세 군데에 흩어져 있었습니다. launchctl list, lsof, 그리고 curl. 그래서 작은 메뉴 막대 플러그인으로 한곳에 모았습니다. 호스트명마다 옆에 점이 하나씩 붙습니다.

• 🟢 서비스가 터널을 통한 요청에 답했습니다
• 🟡 터널은 열려 있지만 그 뒤의 서비스가 조용합니다
• 🔴 로컬 포트에서 아무것도 듣고 있지 않으니, 터널 자체가 죽었습니다

쓸모 있는 건 노란색입니다. 초록/빨강 검사로는 “SSH 포워드가 죽었다"와 “반대편에서 Ollama가 뻗었다"를 구분할 수 없고, 둘은 고치는 방법이 전혀 다릅니다. 플러그인은 자체 서비스 목록을 따로 두지 않고 다른 것들과 같은 프록시 설정과 SSH 설정을 읽으니, 거기에 서비스를 추가하면 메뉴에도 추가됩니다.

첫 버전은 욕심이 과했습니다. 10초마다 새로 고치면서 서비스마다 프로세스를 몇 개씩 띄워 한 번 돌 때 70개쯤 됐고, macOS는 곧바로 이 플러그인을 “에너지를 많이 사용하는 앱"에 올렸죠. 한 번 돌 때 스냅샷을 한 번만 뜨고 몇 분 간격으로 새로 고치게 바꾸니 코어 하나의 0.1% 정도로 내려왔습니다. 배터리를 갉아먹는 상태 표시는 도움이 안 되니, 처음부터 비용을 따져 둘 만합니다.

구멍이 하나 있었는데, 하필 중요한 구멍이었습니다. devbox에는 공개 이름이 없습니다. 그 SSH 포워드는 192.168.x 주소로 다이얼했으니, 노트북이 사무실 LAN에 있을 때만 동작했습니다. 사무실을 벗어나면 메뉴 막대가 빨개진 채로 그대로였고, 노트북을 아끼려고 워크스테이션으로 옮겨 둔 모든 것이 정확히 제가 그 옆에 앉아 있지 않을 때 닿지 않았습니다.

방향을 제대로 잡은 터널 두 개

#

해결책은 세 부분이고, 앞의 둘이 Cloudflare Tunnel입니다.

Cloudflare Tunnel은 cloudflared가 Cloudflare 엣지로 아웃바운드 연결을 붙잡고 있는 것입니다. Cloudflare는 그 연결로 요청을 내려보내니, NAT가 몇 겹이든 그 뒤의 기계가 라우터에서 아무것도 듣지 않고도 닿을 수 있게 됩니다. 노트북을 따라 호텔 wifi로 가고, CGNAT에서도 살아남습니다.

저는 기계마다 하나씩 두 개를 돌리는데, 그 이유는 한 문장 들일 만합니다. 뻔한 지름길은 노트북에 터널 하나를 두고, 사무실 LAN에 있는 devbox의 SSH 포트를 가리키는 ingress 규칙을 하나 더 넣는 것이었습니다. 그러면 devbox에는 아무것도 설치할 필요가 없습니다. 대신 노트북을 거쳐 라우팅되는데, 노트북은 사무실을 떠나는 기계입니다. 고치려던 바로 그 상황에서 고장 났을 겁니다. devbox는 제자리에 있으니, devbox가 엣지로 가는 자기 연결을 쥡니다.

# config.yml on devbox (runs as a systemd service)
protocol: auto        # prefer QUIC, fall back to HTTP/2 over TCP 443
ha-connections: 4     # mains-powered, its job is to stay reachable

warp-routing:
  connectTimeout: 5s

ingress:
  - hostname: ssh-devbox.example.com
    service: tcp://127.0.0.1:22
  - service: http_status:404

ssh://가 아니라 tcp://라는 건 헷갈리기 쉬운 부분입니다. ssh://는 Cloudflare의 브라우저 렌더링 터미널을 선택하는데, 이건 스트림을 웹 페이지용으로 감쌉니다. 평범한 ssh 클라이언트를 거기로 통과시키면 배너까지는 받고 키 교환에서 죽습니다. tcp://는 cloudflared access ssh가 기대하는 평범한 바이트 파이프이고, 덤으로 scp, rsync, SSH 위의 git, 포트 포워드까지 실어 나릅니다.

그 마지막 부분이 SSH 계층의 구멍을 막았습니다. 이제 SSH 설정이 연결마다 경로를 고릅니다.

Match originalhost devbox !exec "nc -z -G 1 <office-lan-ip> 22 >/dev/null 2>&1"
    ProxyCommand cloudflared access ssh --hostname ssh-devbox.example.com ...

사무실 LAN에서는 탐침이 성공하고 SSH가 한 홉으로 직접 갑니다. 그 밖의 어디서든 탐침이 실패하고 SSH는 Cloudflare를 거치는데, Access 서비스 토큰으로 인증하니 브라우저 로그인이 끼어들지 않습니다. Match host가 아니라 Match originalhost입니다. host는 HostName이 치환된 뒤에 매칭되니, 그 시점엔 이름이 이미 IP라서 블록이 절대 발동하지 않습니다. 결과적으로 devbox-ollama.ssh.test가 사무실에서도, 집에서도, 기차에서도 동작하고, 메뉴 막대의 점은 초록으로 남습니다.

노트북의 터널은 반대 방향으로 갑니다. Mac의 dev 서버에 진짜 공개 HTTPS 호스트명을 줍니다. 작업 중인 앱마다 API, WebSocket 서버, 웹 빌드요. 전부 Cloudflare Access 뒤에 있는데, 이건 뒤에서 다시 다루겠습니다. 이걸 무모한 게 아니라 안전한 것으로 만드는 부분이니까요.

메뉴 막대도 두 터널을 알게 됐는데, 탐침으로는 할 수 없었습니다. 인바운드 터널에는 확인할 로컬 포트가 없고, 커넥터 둘 중 하나는 노트북에서 돌지도 않으며, 뻔한 테스트인 ssh-devbox.example.com에 curl 날리기는 커넥터가 붙어 있든 말든 Cloudflare 엣지가 답하니, 죽은 터널에서도 초록으로 읽힐 겁니다. launchd도 나을 게 없습니다. cloudflared는 엣지 연결이 전부 끊긴 채로 “loaded, exit 0” 상태로 앉아 있거든요. 그래서 터널 상태는 각 터널에 건강한 커넥터가 붙어 있는지 Cloudflare API에 물어서 확인합니다. ssh가 닿을지를 결정하는 게 바로 그쪽이니까요. API에 닿지 못하면 빨갛게 그리지 않고 그 부분을 통째로 뺍니다. 메뉴는 힐끗 보고 읽는 것이라, 거기서 잘못된 경보는 빠진 한 줄보다 비쌉니다.

세 번째 부분: WARP가 이걸 네트워크로 만듭니다

#

호스트명이 붙은 터널은 HTTPS로 말하는 것, 그리고 cloudflared를 돌릴 수 있는 기계에서의 SSH에는 훌륭합니다. 폰은 못 돌립니다. 게다가 터널 호스트명은 TCP 엔드포인트가 아닙니다. Cloudflare 엣지는 거기서 HTTPS와 WebSocket만 종단하니, ssh.example.com의 22번 포트는 닫혀 있고 Access를 아무리 만지작거려도 열리지 않습니다.

그게 WARP의 일입니다. Cloudflare One Agent(엔터프라이즈용 WARP 클라이언트입니다. 조직에 가입할 수 없는 일반 소비자용 “1.1.1.1” 앱이 아니고요)를 노트북과 폰에 설치해 제 Zero Trust 조직에 등록했습니다. 각 터널이 사설 경로를 광고하면, WARP를 돌리는 기기는 그 주소로 평범한 소켓을 열어 올바른 기계에 닿을 수 있습니다. “이 서비스에 이름으로 닿기"가 아니라 “이 기계들이 나와 같은 네트워크에 있다"가 되는 거죠.

이 주소들은 부팅 때 만들어지는 각 기계의 루프백 별칭이라, DHCP나 제가 어떤 라우터 뒤에 있는지와 아무 상관이 없습니다. 198.18.42.2는 사무실에서도, 집에서도, 5G에 붙은 폰에서도 devbox입니다. Mac의 진짜 LAN 주소는 옮길 때마다 바뀌지만, 이 주소는 절대 바뀌지 않습니다.

스플릿 터널은 include 모드이고, 저 경로들(과 WARP가 스스로 쓰는 Cloudflare 대역)만 들어 있습니다. 이게 클라이언트를 켜 두고 살 수 있게 만드는 부분입니다. 기본값은 exclude 모드인데, WARP가 사설 대역 목록을 뺀 모든 것을 실어 나르니 폰이 보내는 모든 바이트가 Cloudflare를 돌아갑니다. 배터리와 지연 시간 비용이 실제로 있고, 결국 필요할 때만 켜게 됐을 만큼입니다. 그러면 요점이 무너지죠. include 모드에서는 제 기계 세 대로 가는 트래픽만 WARP를 거치고 나머지는 전부 평소 경로로 손대지 않은 채 나갑니다. 그래서 클라이언트는 그냥 켜진 채로 있습니다. 노트북의 warp-cli status는 하루 종일 Connected라고 하고, 저는 신경 쓰지 않습니다.

전송 방식은 UDP 2408 위의 WireGuard가 아니라, UDP 443 위의 HTTP/3에 HTTP/2 폴백이 붙은 MASQUE로 해 두었습니다. 일부 통신사와 게스트 네트워크는 2408을 막지만, 443을 막는 곳은 거의 없습니다. 제 조직 정책에서는 MASQUE에 양자내성 키 합의도 켜져 있는데, 찾아서 켠 건 아니지만 마다할 이유도 없죠.

왜 198.18이고, 왜 IPv6 주소가 있는지

#

주소가 좀 이상해 보이는데, 처음 고른 주소는 배울 게 있는 방식으로 틀렸습니다.

첫 시도는 10.10.0.1이었습니다. 다들 손이 가는 주소니까요. 이건 두 스플릿 터널 모드 모두에서 실패합니다. exclude 모드에서는 WARP의 기본 목록이 RFC 1918 대역 전부와 100.64.0.0/10을 제외하니, 클라이언트가 그 주소로 가는 트래픽을 기기를 떠나기도 전에 버렸을 겁니다. include 모드에서는 제가 어쩌다 붙는 실제 10.x 네트워크와 충돌했을 겁니다. 카페, 코워킹 스페이스, 그리고 꽤 많은 사무실이 딱 그 대역을 씁니다. 198.18.0.0/15는 RFC 2544 벤치마킹 대역입니다. 예약돼 있고, 공용 인터넷에서 라우팅되는 일이 없고, WARP의 exclude 목록에 없으며, 평범한 네트워크라면 쓰지 않습니다. IPv6 주소가 ULA(fd00::/8)인 것도 같은 이유입니다.

IPv6가 애초에 왜 있는지가 더 재미있는 이야기입니다. v4 주소가 동작하자 폰에서 wifi로 테스트해 봤고, 잘 됐고, 끝났다고 선언했습니다. 5G에서는 안 됐습니다. Agent는 connected라고 했고, 터널은 멀쩡했고, Access도 괜찮았습니다. wifi 테스트가 그 전부를 증명했으니까요. 문제는 요즘 모바일 네트워크가 대부분 IPv6 전용이라는 점이었습니다. 폰에는 네이티브 IPv4가 아예 없었고, v4 리터럴에는 통신사의 464XLAT 변환기를 통해 닿고 있었는데, include 목록에 v4 접두사만 있으면 그 변환기는 터널 바깥에 놓입니다. 트래픽은 198.18.0.0/15가 라우팅되지 않는 공용 인터넷으로 나갔고, 소리 없이 버려졌습니다. 폰에도 오류가 없고, 커넥터 로그에도 아무것도 없었습니다.

해결책은 모든 기계에 폰이 IPv6로 네이티브하게 닿을 수 있는 두 번째 주소를 주고, 그걸 경로와 include 목록에 추가하는 것입니다. 이제 모바일 데이터에서 폰의 SSH 클라이언트가 실제로 쓰는 건 fd12:3456:789a:: 주소입니다.

오프로딩: 단말기로서의 노트북

#

이 셋업 전체가 존재하는 이유가 이 부분입니다.

모델과 파인튜닝. Ollama는 devbox에서 돌고 127.0.0.1:11434에 바인딩됩니다. 인터넷은 고사하고 사무실 LAN의 다른 기계에서도 보이지 않습니다. 노트북에서는 https://devbox-ollama.ssh.test로 나타나고, 포트 번호만 원하는 도구에는 그냥 포트로 나타납니다.

OLLAMA_HOST=127.0.0.1:11435 ollama list

11434가 아니라 11435인 건 일부러입니다. 11434는 Ollama 자체 기본값이라, 노트북에서도 로컬 Ollama를 돌리게 되면 둘이 포트를 두고 경쟁하고, 어느 쪽이 먼저 떴느냐에 따라 “로컬” 쪽에서 devbox의 답을 소리 없이 받게 됩니다.

실제 효과는, AI 기능을 만들 때 그 기능이 호출하는 모델이 제가 어디에 있든 노트북이 아니라 워크스테이션 GPU라는 점입니다. 평가 실행, 문서 한 무더기 임베딩, 파인튜닝은 devbox에서 돌고, 노트북 팬은 조용합니다. 에이전트를 프로토타이핑할 때는 워크스테이션의 로컬 모델을 가리키게 해서 API 청구서 없이 툴 호출 반복을 마음껏 태울 수 있고, 루프가 제대로 잡히면 호스팅 모델로 바꾸면 됩니다.

오래 도는 에이전트. 한 시간 도는 에이전트 세션이 제 노트북 덮개가 열려 있는지에 달려 있어서는 안 됩니다. 대신 devbox에서 돌리면 노트북은 그저 거기로 난 창문입니다. 덮개를 닫고, 나중에 어디서든, 혹은 폰에서 ssh devbox를 하면 여전히 거기 있습니다. 터널 이전에는 이게 사무실에서만 됐는데, 사무실은 정확히 이게 필요 없는 곳이었죠.

빌드와 클러스터. devbox의 클러스터에는 자체 레지스트리가 있어서, 이미지를 노트북에서 호텔 wifi로 올리는 대신 워크스테이션에서, 실행될 곳 바로 옆에서 빌드하고 푸시할 수 있습니다. 클러스터 대시보드, ingress 대시보드, 레지스트리 UI는 노트북에서 전부 *.ssh.test 호스트명입니다.

모바일 루프. 폰은 노트북과 같은 사설 네트워크에 있고, 노트북의 dev 서버에는 Access 뒤의 공개 호스트명도 있습니다. 그래서 앱의 네이티브 빌드를 들고 건물 밖으로 나가 5G에서 써도, 제 책상에서 도는 API와 통신합니다. 제가 devbox에 띄워 두었다면 그쪽과 통신하고요. 실제 모바일 네트워크 위의 실제 기기로 피드백 루프를 돌리려면 예전에는 공유 스테이징 서버에 배포해야 했습니다. 지금은 파일을 저장하면 됩니다.

앱 버그로 착각하고 디버깅하기 전에 알아 둘 만한 함정이 하나 있습니다. Access는 WebSocket 호스트명도 보호하는데, 네이티브 WebSocket 클라이언트는 브라우저가 아닙니다. CF_Authorization 쿠키를 들고 있지 않으니, 네이티브 빌드가 WebSocket 서버에 연결하면 엣지에서 403으로 거부되는데, 이게 내 서버가 내는 오류와는 전혀 닮지 않았습니다. 브라우저 탭은 로그인할 때 받은 쿠키를 이미 들고 있으니 괜찮습니다. 브라우저가 아닌 모든 것(네이티브 앱, 스크립트, dev API를 호출하는 에이전트)에 대한 답은 Access 서비스 토큰이고, 헤더 두 개로 보냅니다.

CF-Access-Client-Id:     <client_id>
CF-Access-Client-Secret: <client_secret>

토큰은 그 자체로는 아무 권한도 주지 않습니다. Access는 정책에 그 토큰이 명시된 앱에서만 받아 주니, 토큰이 닿는 범위는 정확히 dev 호스트명 목록이고 그보다 넓지 않습니다. 저는 그 정책을 allow가 아니라 non_identity 결정으로 분류해 두는데, 그러면 감사 로그에서 로그인한 사람이 아니라 bearer 시크릿으로 보입니다.

인터넷은 절대 보지 못하는 통계

#

제가 원한 것의 나머지 절반은 가시성이었습니다. 시스템이 어떻게 돌아가는지 알려 주는 것 대부분은 공개돼 있지 않은 게 맞습니다. devbox에서는 이런 것들입니다.

• ingress 프록시 대시보드, 그리고 그 트레이스가 담긴 트레이싱 UI
• Kubernetes 클러스터용 대시보드
• 컨테이너 레지스트리 UI(읽기 전용)
• Ollama 모델 목록과 지금 로드된 것
• docker info와 컨테이너 통계

이 중 어느 것도 공개 호스트명이 없고, 앞으로도 없을 겁니다. 루프백이나 클러스터 서비스 IP에 바인딩돼 있고, 그 자체가 터널을 타는 SSH 포워드로 닿습니다. 폰의 모니터링 앱은 WARP 너머 SSH로 docker info --format '{{json .}}'를 읽으니, 컨테이너가 떠 있는지 아니면 뭔가 메모리를 다 먹어 치웠는지 어디서든 볼 수 있습니다.

그 앱 덕분에 언급할 만한 작은 버그를 하나 찾았습니다. Mac의 터널용 sshd가 디버깅하던 시절 그대로 LogLevel DEBUG2였습니다. -e를 주면 sshd는 stderr로 로그를 남기는데, 세션에서는 그 stderr가 곧 SSH 채널의 stderr입니다. 모든 명령의 출력 끝에 debug2: do_setup_env: set TMPDIR가 붙어서 돌아왔고, 두 스트림을 합치는 폰 앱은 유효한 JSON 뒤에 로그 한 줄이 붙은 걸 받아 파싱에 실패하고는 통째로 오류로 보여 줬습니다. LogLevel INFO로 고쳤습니다. 디버깅이 끝나면 로그 레벨을 되돌려 놓으세요.

이 네트워크에 올리지 않는 것도 똑같이 의도적입니다. 예전 autossh 터널은 제가 관리를 돕는 남의 네트워크의 라우터 몇 대에도 닿습니다. 그것들에는 공개 호스트명도, WARP 경로도 주지 않습니다. 인터넷에 나온 라우터 관리 페이지는 로그인 뒤에 있어도 골칫거리고, 제가 넓힐 수 있는 제 네트워크도 아니니까요.

Access는 선택이 아닙니다

#

Cloudflare Tunnel 호스트명은 DNS 레코드가 생기는 순간 공용 인터넷에 올라갑니다. 앞에 방화벽이 없습니다. 포트를 열지 않는다는 게 애초에 요점이니까요. 보호는 Cloudflare 엣지에서 와야 하고, 그게 Access가 하는 일입니다. 방문자가 누구인지 증명하기 전까지는 요청을 아예 전달하지 않으니, 인증되지 않은 스캐너는 노트북에 절대 닿지 못합니다. 이게 중요한 건 이것들이 dev 서버이기 때문입니다. 설정값이 그대로 드러나는 디버그 모드 트레이스백, 열려 있는 JavaScript 번들러. 이 호스트명들 뒤에 있는 것 중 인터넷을 마주하도록 만들어진 건 하나도 없습니다.

정책은 제 이메일 주소들만 허용하고 나머지는 아무것도 허용하지 않으며, 증명 방법은 이메일 일회용 PIN과 SSO 두 가지입니다. 세션은 8시간인데, 현실적인 위협은 누군가 PIN을 무차별 대입하는 게 아니라 하루짜리 쿠키를 품은 채 카페에 열어 두고 온 노트북이기 때문입니다.

SSH는 서로의 존재를 모르는 두 시스템이 두 번 인증합니다. Access는 TCP 스트림이 sshd에 닿아도 되는지를 정하고, sshd는 그래도 제 키를 요구합니다. 어느 하나를 잃어도 기계가 열리지는 않습니다. Mac의 터널용 sshd는 Cloudflare의 SSH CA도 신뢰해서, Access가 제 SSO 세션으로 발급한 단기 인증서로 저를 로그인시킬 수 있습니다. 그러면서 authorized_keys도 나란히 동작하니, Access 설정이 망가져도 제 노트북에서 제가 쫓겨나는 일은 없습니다.

제일 마음에 드는 건 작은 부분입니다. 노출은 세 가지가 맞아떨어질 때 일어납니다. DNS 레코드, 돌고 있는 커넥터, 활성 상태의 존. 이 셋은 제가 통제하지 못하는 순서로, 서로 다른 시점에 참이 됩니다. 존은 네임서버를 바꾸고 얼마 뒤에 혼자 활성으로 바뀌는데, Mac이 잠들어 있을 때일 수도 있습니다. 그래서 launch agent는 cloudflared를 직접 실행하지 않습니다. 대신 터널 자체 설정에서 호스트명을 읽어 Access API에 어느 것이 보호되고 있는지 묻고, 하나라도 빠져 있으면 시작을 거부하는 사전 점검을 돌립니다.

HOSTNAMES=$(grep -E '^\s*-\s*hostname:' "$CONFIG" | sed -E 's/.*hostname:\s*//' | sort -u)
PROTECTED=$(curl -fsS -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/apps?per_page=100" \
    | python3 -c 'import sys,json; print("\n".join(a.get("domain","") for a in json.load(sys.stdin)["result"]))') \
    || { echo "could not reach the Access API. refusing (fail closed)."; exit 1; }

for h in $HOSTNAMES; do
    grep -qxF "$h" <<<"$PROTECTED" || { echo "NOT starting: $h has no Access app"; exit 1; }
done
exec cloudflared tunnel --config "$CONFIG" run

launch agent에는 KeepAlive가 걸려 있어서, 거부되면 30초마다 알아서 재시도하고 Access 앱이 생기면 터널이 혼자 올라옵니다. 닫힌 채로 실패하면 장애를 치르고, 열린 채로 실패하면 노출을 치릅니다. 둘 중 어느 쪽을 해명하고 싶은지는 압니다.

발목을 잡은 네 가지

#

위의 모든 게 지금은 동작합니다. 여기까지 오는 동안 넷 중 셋은 패턴이 같았습니다. 고장 난 부분은 어디에도 오류를 내지 않았고, 제 눈에 보이는 부분은 전부 정상이라고 보고했습니다.

경로와 include 목록은 서로 다른 목록입니다. 터널 경로는 Cloudflare가 어떤 주소를 올바른 커넥터로 실어 나를 의향을 갖게 합니다. WARP include 목록은 클라이언트가 애초에 그걸 보내게 만드는 것입니다. devbox가 폰에서 닿지 않았는데, 경로는 있었지만 include 목록에는 여전히 Mac의 주소만 있었기 때문입니다. 폰은 패킷을 로컬에서 버렸고, 커넥터는 흐름을 보지 못했고, 모든 대시보드는 초록이었습니다. 새 기계를 들일 때마다 주소를 양쪽 모두에 추가해야 합니다.

IPv6 전용 모바일 네트워크의 IPv4 리터럴. 위에서 다뤘습니다. wifi에서는 되고, 5G에서는 안 되고, 오류는 없습니다. WARP 경로가 wifi에서는 되는데 모바일 데이터에서 안 되고 Agent가 connected로 나온다면, 터널이 아니라 라우팅 문제입니다.

cloudflared 뒤의 macOS sshd. macOS는 sshd를 launchd 소켓 활성화로 띄웁니다. 연결마다 수명이 짧은 sshd -i가 하나씩 뜨는 식이죠. cloudflared 뒤에서는 배너가 클라이언트에 닿은 다음, 클라이언트의 식별 문자열이 돌아오기 전에 스트림이 끊겨서, 모든 로그인이 kex_exchange_identification에서 죽습니다. 양쪽 끝에서 확인했고, 평범한 TCP 릴레이로도 재현해서 Cloudflare 탓이 아님을 확인했습니다. 해결책은 127.0.0.1:2222와 WARP 루프백 주소에서 제 사용자로 도는 두 번째 독립 sshd -D인데, 오직 터널의 origin 노릇을 하려고 존재합니다. 시스템 설정의 원격 로그인은 건드리지 않았습니다. 평범하게 오래 사는 sshd를 쓰는 Linux인 devbox에는 이 문제가 애초에 없었습니다.

더는 존재하지 않는 설정 필드. 예전 예제에는 터널 설정에 warp-routing: enabled: true가 있습니다. cloudflared 2026.8은 그 필드를 대놓고 거부합니다. WARP 라우팅은 블록이 있고 경로가 터널을 가리키기만 하면 켜집니다. 이건 적어도 오류를 냈는데, 다른 셋을 겪은 뒤라 거의 너그럽게 느껴졌습니다.

무엇이 바뀌었나

#

솔직하게 요약하면, 하드웨어가 어디 있느냐에 따라 일할 곳을 고르는 걸 그만뒀습니다. 노트북은 배터리가 오래가는 좋은 키보드와 좋은 화면이고, 그 이상일 필요가 없습니다. 워크스테이션은 제가 어디에 있든 무거운 일을 맡습니다. 폰은 사무실 wifi에 묶인 무언가가 아니라 실제 네트워크 위의 실제 테스트 기기입니다. 그리고 시스템이 뭘 하는지 보는 데 쓰는 부분들은 저에게는 클릭 한 번 거리에 있고, 다른 누구에게는 존재하지 않습니다.

이 규모면 Cloudflare의 무료 Zero Trust 플랜에 들어갑니다. 제가 치른 건 시간, 그리고 써 두길 잘했다 싶은 README 하나입니다. 위에 적은 실패는 하나같이 두 번째에도 새로운 미스터리였을 테니까요.

비슷한 걸 고민하고 있다면, 여러분의 셋업에 이런 질문을 던져 보겠습니다.

1. 노트북이 언제나 닿을 수 있는 유일한 기계라는 이유만으로 노트북에서 돌고 있는 건 무엇인가요?
2. 폰이 사무실 wifi에서만이 아니라 모바일 데이터로도 dev 서버에 닿나요? wifi 말고 5G에서 테스트해 보세요.
3. 밖에서 보기 쉬운 방법이 그것뿐이라서 공개된 대시보드는 어느 것인가요? 하나하나가 사설 경로로 옮길 후보입니다.
4. 내일 터널 호스트명이 Access 앱 없이 올라온다면, 무엇이 그걸 막나요? 답이 “제가 기억하겠죠"라면 사전 점검을 작성하세요.
5. 여러분의 사설 주소는 여러분이 드나드는 네트워크가 절대 쓰지 않을 대역에 있나요?

앱 하나를 만드는 작은 팀을 떠올려 보세요. 개발자 둘일 수도, 다섯일 수도 있습니다. 전문 분야가 나뉜 사람들이 아니라, 각자 자기 브랜치에서 데이터베이스 마이그레이션부터 API를 거쳐 모바일 앱 화면까지 기능 하나를 처음부터 끝까지 맡는 사람들입니다. 팀을 굴리기에 좋은 방식이고, 두 번째 개발자가 합류하는 순간부터 반복되는 실패가 하나 있습니다. “지금 스테이징 쓰는 사람 있어요?“라는 메시지입니다.

그 메시지 뒤에는 기능을 다 만들고 테스터나 디자이너에게 보여주고 싶은데 그럴 수 없는 개발자가 있습니다. 스테이징에는 두 번째 개발자의 브랜치가 올라가 있고, dev에는 세 번째 개발자의 브랜치가 올라가 있는데 그건 이틀 전에 로그인을 망가뜨린 뒤로 다시 배포되지 않았습니다. 몇 사람, 공유 환경 둘, 그리고 일정 조율을 떠맡은 채팅 스레드.

이건 사람 문제가 아닙니다. 토폴로지 문제입니다. 모든 개발자가 환경을 “내 브랜치가 실제가 되는 곳"으로 다루니, 환경이 머지가 해야 할 일을 브랜치 하나씩 차례로 대신하고 있고, 나머지 전부는 줄을 서 있는 겁니다.

제 스택의 프로덕션 형태는 My Current Stack에 적었습니다. Fly.io의 가장 싼 머신 위의 Django, 커넥션 풀러 뒤의 Postgres, 캐시와 Channels 레이어용 Redis, 별도의 WebSocket 앱, 백그라운드 워커, 파일용 S3 호환 버킷, 호스팅형 인증 서비스, 앞단의 Cloudflare, 그리고 이 모든 것과 통신하는 모바일 앱입니다. 이 글은 그 스택을, 어떤 브랜치든 개발자가 PR에 라벨 하나를 붙이면 몇 분 안에 HTTPS가 붙은 공개 복사본 전체를 얻는 것으로 바꾼 이야기입니다. 다른 누구에게 부탁하지도, 누가 프로비저닝해 주지도 않고요. Postgres 클러스터를 하나 더 두지도, Redis를 하나 더 두지도, 버킷을 하나 더 두지도 않고요. 인프라는 공유된 채로 남습니다. 달라지는 건 모든 공유 자원이 이름으로 잘리는 법을 배운다는 것이고, 그 이름은 브랜치에서 나옵니다. 여기에 팀 규모를 전제하는 건 없습니다. 개발자 둘이든 스물이든 설계는 같고, 늘어나는 건 앱 목록뿐이며 그건 스위퍼가 처리합니다. 오후 한나절에 만들고, 브랜치 셋을 동시에 띄우고, 예상 못 한 두 군데에서 부러뜨리고, 다시 걷어냈습니다. 아래 출력은 그 실행에서 나온 것입니다.

공유 환경 하나가 개발자 한 명 이상으로 늘어나지 못하는 이유

#

공유 dev 환경에는 전제가 하나 깔려 있습니다. 모두가 보고 싶어 하는 “현재 코드 버전"이 하나라는 전제입니다. 개발자가 한 명이거나, 팀이 변경 흐름 하나를 발맞춰 작업할 때는 맞는 말입니다. 두 번째 개발자가 다른 일정으로 기능을 시작하는 순간 틀린 말이 되고, 처음부터 끝까지 맡는 방식에서는 모든 기능이 그렇습니다. 그때부터 환경이 쥐고 있는 모든 것이 쟁탈 대상이 됩니다.

• 배포된 코드. 마지막에 배포한 사람이 이깁니다. 나머지 사람들의 작업은 다시 배포하기 전까지 보이지 않고, 다시 배포하면 앞사람 것이 지워집니다.
• 데이터베이스 스키마. 개발자마다 자기 기능의 데이터 모델을 소유할 때 가장 아프게 무는 부분입니다. 첫 브랜치가 컬럼을 추가합니다. 한 시간 뒤 배포된 두 번째 브랜치는 그 컬럼을 모르고, ORM이 insert에서 실패하기 시작합니다. 아니면 두 브랜치 모두 0042_* 마이그레이션을 갖고 있어서, 공유 데이터베이스가 누구의 마이그레이션 이력과도 맞지 않는 상태가 되고, 누군가 초기화하면서 세 번째 개발자가 오후 내내 세팅한 테스트 데이터를 지웁니다.
• 캐시. 한 브랜치의 serializer 변경이 다른 브랜치 코드가 읽는 것과 같은 Redis 키 아래 캐시됩니다. 그래서 나오는 버그 리포트는 어리둥절하고, 하나에 오전 한나절씩 잡아먹습니다.
• 서드파티 연동. OAuth 콜백 하나, 웹훅 URL 하나, 푸시 인증서 하나. 누구 브랜치가 배포돼 있든 그 브랜치가 이벤트를 받습니다.
• 테스터. 배포된 것만 테스트할 수 있으니, 기능이 준비된 순서가 아니라 환경이 우연히 점유된 순서대로 한 번에 하나씩 테스트합니다.

팀은 예약 시스템으로 대응합니다. 채팅 스레드, 고정 메시지, /claim staging 봇. 그건 락입니다. 작업을 보여줄 수 있는 유일한 장소에 걸린 락은 전달 속도에 걸린 락입니다. 개발자 둘이면 성가신 정도입니다. 셋이면 좋은 주에는 견딜 만합니다. 네 번째가 합류하거나, 기능 하나가 디자이너와 사흘간 주고받느라 스테이징을 붙들고 있으면 견딜 수 없게 됩니다.

사람들이 먼저 손대는 해결책은 세 번째 공유 환경, “dev2"나 “uat"입니다. 몇 주는 벌어 줍니다. 줄이 두 갈래가 됐을 뿐입니다.

진짜 해결책은 dev와 스테이징이 애초에 환경이 아니었다는 걸 알아차리는 것입니다. 그것들은 누군가의 브랜치의 현재 상태에 URL이 붙은 것이었습니다. 그렇다면 알맞은 개수는 지금 팀이 신경 쓰는 브랜치의 개수이고, 알맞은 수명은 브랜치의 수명입니다.

모델: 브랜치가 곧 환경

#

목표 상태는 이렇습니다.

표에서 누가 만들고 누가 없애는지를 다시 보세요. 전부 git 이벤트 아니면 시계입니다. git이 컨트롤 플레인입니다. 존재해야 할 환경의 집합은 존재하는 브랜치의 집합에서 그대로 따라 나오고, 자동화가 하는 일은 현실을 거기에 맞춰 두는 것뿐입니다. PR의 라벨이 만들고, 그 뒤의 push마다 갱신하고, PR을 닫거나 머지하면 없애고, 매일 밤 도는 잡이 앞의 셋이 놓친 것을 정리합니다. 모든 브랜치가 환경을 얻는 것도 아닙니다. 라벨이 게이트이고 개발자의 클릭 한 번이니, 백업 push나 봇의 의존성 업데이트는 비용이 없습니다. 아무도 환경을 프로비저닝하지 않습니다. 티켓을 받은 DevOps 엔지니어도, 채팅에서 부르는 봇도, 매번 프롬프트를 넣어야 하는 AI 에이전트도 아닙니다. 열 번째 개발자의 첫 브랜치도 첫 번째 개발자의 브랜치와 똑같은 방법으로, PR에 라벨을 붙였다는 이유로 환경을 얻습니다. 사람에게 부탁해야 한다면 확장된 게 아니라 줄이 자리를 옮긴 것뿐입니다.

그리고 이걸 굴러가게 하는 규칙은 하나입니다. 환경이 건드리는 모든 자원은 브랜치 이름을 따서, 결정론적으로 이름 붙인다. 개발자 이름도 아니고, 티켓 번호도 아니고, 누군가 열기 전까지는 존재하지도 않는 PR 번호도 아닙니다. 브랜치입니다. 개발자가 실제로 다루는 것이 브랜치이고, 이름이 결정론적이면 같은 브랜치에서 ./scripts/env up을 두 번째 실행했을 때 새 환경을 또 만드는 대신 이미 만든 환경을 찾아내기 때문입니다.

이름은 사람을 위한 슬러그와 유일성을 위한 짧은 해시입니다.

branch=$(git rev-parse --abbrev-ref HEAD)              # feature/payments-retry
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20)
hash=$(printf '%s' "$branch" | sha256sum | cut -c1-6)
ENV="${slug%-}-${hash}"                                 # feature-payments-retr-3f9a1c

feature-payments-retr-3f9a1c가 환경입니다. 이 문자열이 Fly 앱 이름, Postgres 데이터베이스 이름(하이픈은 밑줄로), Redis 키 접두사, 버킷의 객체 접두사, 에러 트래커의 environment, 그리고 호스트명의 맨 왼쪽 라벨이 됩니다. 브랜치 이름을 아는 사람은 누구나 계산할 수 있습니다. 어디서도 찾아볼 필요가 없습니다.

마지막 문장이 곧 설계입니다. 환경 목록도 없고 조정자도 없습니다. env up, env down, 호스트명을 라우팅하는 Cloudflare Worker, 밤마다 도는 스위퍼가 각자 브랜치에서 이름을 독립적으로 다시 계산하고, 구조적으로 서로 일치합니다. 특히 Cloudflare는 아무것도 조정하지 않습니다. Worker는 호스트명에서 Fly 앱으로 가는 순수 함수이고, 환경이 만들어졌는지 없어졌는지 영영 알지 못합니다. 앱이 있으면 요청이 닿고, 없으면 Fly가 자기 오류로 답합니다.

여기서 세 가지가 따라 나옵니다.

첫째, “스테이징 누가 쓰고 있어요"가 더는 질문이 아닙니다. feature-payments-retr-3f9a1c-dev.example.com이 있고 fix-login-redirect-8b21e0-dev.example.com이 있으며, 각각 그 브랜치를 맡은 사람의 것입니다.

둘째, 스테이징이 쓰레기장이 아니라 프로덕션의 정직한 리허설이 됩니다. 프로덕션에 갈 바로 그 이미지로, 몇 분 전 프로덕션 모양의 스냅샷에서 복제한 데이터베이스를 상대로 만들어집니다. 거기서 되면 프로덕션에 남은 변수는 프로덕션 데이터뿐입니다.

셋째, 개발자마다 공유 자원의 root 권한 없이도 힘을 얻습니다. 브랜치 환경의 폭발 반경은 그 브랜치 환경입니다. 네 번째로 합류한 사람이 첫날에 자기 브랜치에 뭘 배포하든, 최악의 결과는 자기 브랜치가 망가지는 것입니다.

fly.io/dashboard/my-org

물리적으로는 공유, 논리적으로는 분리

#

“브랜치마다 환경"의 솔깃한 버전은 통째로 복사하는 것입니다. Postgres 클러스터 하나씩, Redis 하나씩, 버킷 하나씩. 깔끔하지만 잘못된 거래입니다. Fly Postgres 클러스터는 머신 하나에 볼륨 하나에 복원 한 번이고, Redis는 머신 하나 더입니다. 환경마다 몇 분씩 기다리고 놀고 있는 데이터베이스 열두 개 값을 내게 됩니다. 스위퍼가 치울 것도 한 종류가 아니라 네 종류가 됩니다.

대신 각 공유 서비스는 프리뷰 조직 전체에 한 번만, 작은 프로덕션 크기로 마련하고, 모든 환경이 $ENV를 키로 한 조각씩 받습니다. 벽에 붙여 두고 싶은 표입니다.

둘은 한마디씩 덧붙일 만합니다.

Postgres: 스키마가 아니라 데이터베이스. 클러스터 하나를 자르는 다른 방법은 환경마다 스키마를 두고 연결마다 search_path를 설정하는 것입니다. 연결 options로 -c search_path=...를 밀어 넣으면 Django도 해 주지만, 트랜잭션 풀링 모드의 커넥션 풀러는 따로 말해 주지 않는 한 시작 옵션을 버리고, 그러고 나면 어차피 풀의 모든 연결이 한 환경에 속해야 합니다. “왜 내 쿼리가 엉뚱한 테이블을 치지"류의 버그를 낳는 원천이고, 환경마다 데이터베이스를 두면 그냥 없는 문제입니다. 데이터베이스는 단단한 경계이고, CREATE DATABASE ... TEMPLATE은 몇 초 만에 하나를 만들며, DROP DATABASE는 아무것도 남기지 않고 지웁니다. 브랜치 환경은 풀러를 거치지 않고 5433 포트로 Postgres에 직접 붙습니다. 프로덕션의 백그라운드 워커가 하는 것과 같은 방식입니다. 풀러는 프로덕션 동시성에서 제 값을 하는데, 브랜치 환경은 그런 동시성을 볼 일이 없습니다.

시크릿: 공유가 아니라 생성. dev 시크릿 한 벌을 만들어 모든 환경에 복사하면 편할 겁니다. 하지 마세요. env up 스크립트는 환경마다 새 SECRET_KEY(세션 서명), ENCRYPTION_KEY(저장 시 암호화되는 모든 것), ENV_TOKEN(모바일 앱이 제시하는 bearer 토큰, 아래에서 더 설명)을 생성해 그 Fly 앱의 시크릿 저장소에만 넣습니다. 한 브랜치의 세션 쿠키는 다른 브랜치에서 쓸모없고, 유출된 프리뷰 토큰은 프리뷰 하나만 열며, 개발자는 일부러 찾아보지 않는 한 값을 볼 일이 없습니다. Fly만이 아니라 별도의 시크릿 매니저에 시크릿을 둔다면 같은 규칙이 적용됩니다. 경로는 myapp/preview/$ENV/이고, 스위퍼가 환경과 함께 그 경로를 지웁니다. 환경 간에 정말로 공유되는 시크릿은 공유 인프라 자체의 자격 증명(Postgres 관리자 URL, Redis URL, 버킷 키)뿐이고, 그건 어느 환경도 아닌 CI에 삽니다.

Redis 행이 가장 의심하기 쉬우니, 테스트해 봤습니다. 한 환경 안에서 캐시 키를 넣고, 다른 환경에서 읽고, 공유 Redis의 모든 키를 나열합니다.

$ fly ssh console -a myapp-feature-profile-tagl-fa8832 -C "python manage.py shell -c \"from django.core.cache import cache; cache.set('who-am-i', 'tagline-branch', 600)\""
$ fly ssh console -a myapp-feature-profile-webs-dcb2e7 -C "python manage.py shell -c \"from django.core.cache import cache; print(cache.get('who-am-i'))\""
None

$ # every key in the shared Redis
  feature-profile-tagl-fa8832:1:who-am-i
  ...

같은 Redis, 같은 키 이름인데 다른 환경에서는 아무것도 보이지 않습니다.

이 글의 나머지는 저 여덟 행에 $ENV를 찍는 스크립트와, 그걸 정직하게 유지하는 규칙입니다.

./scripts/env up

#

개발자가 자기 브랜치에서 실행하는 스크립트로서의 전부입니다. CI도 같은 스크립트를 실행합니다. 따로 놀다 어긋날 CI 전용 경로가 없습니다. 노트북에 필요한 건 fly와 git뿐입니다. SQL은 fly ssh로 Postgres 앱에 가고, 환경의 Redis 키와 버킷 객체는 없애기 전에 환경 자신의 머신이 지우므로, 노트북은 gitignore된 env 파일 말고는 공유 Redis나 버킷 자격 증명을 쥐고 있지 않습니다. 중요한 줄만 남겨 추리면 이렇습니다.

#!/usr/bin/env bash
# scripts/env up|down|name|url: one environment per branch on shared preview infrastructure
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; PG_APP=${PREVIEW_PG_APP:-myapp-preview-pg}; DOMAIN=${BASE_DOMAIN:-example.com}

branch=${BRANCH:-$(git rev-parse --abbrev-ref HEAD)}
[[ "$branch" == "main" ]] && { echo "main has staging, not a branch environment" >&2; exit 1; }
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20); slug=${slug%-}
ENV=${ENV_OVERRIDE:-${slug}-$(printf '%s' "$branch" | shasum -a 256 | cut -c1-6)}   # the sweeper passes the name
APP="myapp-${ENV}"; DB="env_${ENV//-/_}"; HOST="${ENV}-dev.${DOMAIN}"

pg() { fly ssh console -a "$PG_APP" -q -C "psql postgres://postgres:${PG_PASSWORD}@localhost:5433/postgres -At -c \"$1\""; }
exists() { fly apps list --org "$ORG" --json | grep -q "\"Name\": *\"$APP\""; }

up() {
  echo "== $branch -> $ENV"
  exists || fly apps create "$APP" --org "$ORG"                         # idempotent
  [[ "$(pg "SELECT 1 FROM pg_database WHERE datname='$DB'")" == "1" ]] || pg "CREATE DATABASE $DB TEMPLATE seed_template"

  have=$(fly secrets list -a "$APP" --json | grep -o '"Name": *"[^"]*"' | cut -d'"' -f4 || true)
  gen() { grep -qx "$1" <<<"$have" || echo "$1=$(openssl rand -hex 32)"; }   # generated once, never rotated by a later `up`
  { gen SECRET_KEY; gen ENCRYPTION_KEY; gen ENV_TOKEN
    echo "ENV_NAME=$ENV"; echo "ALLOWED_HOSTS=$HOST,$APP.fly.dev"
    echo "DATABASE_URL=postgres://postgres:${PG_PASSWORD}@${PG_APP}.flycast:5432/${DB}"
    # ... plus the shared Redis URL and bucket credentials
  } | fly secrets import -a "$APP" --stage

  fly deploy -a "$APP" --config fly.preview.toml --remote-only --ha=false \
    --build-arg GIT_SHA="$(git rev-parse --short HEAD)" --build-arg GIT_BRANCH="$branch"
  echo "https://$HOST"
}

down() {
  [[ "$APP" =~ ^myapp-[a-z0-9-]+-[0-9a-f]{6}$ ]] || { echo "refusing to destroy $APP" >&2; exit 1; }
  if exists; then
    fly machine start -a "$APP" >/dev/null 2>&1 || true                 # it may be suspended
    fly ssh console -a "$APP" -q -C "python manage.py teardown_env" || echo "warning: cleanup failed; the sweeper will catch it" >&2
    fly apps destroy "$APP" --yes
  fi
  pg "DROP DATABASE IF EXISTS $DB WITH (FORCE)" || true
}

case "${1:-}" in up) up ;; down) down ;; name) echo "$ENV" ;; url) echo "https://$HOST" ;; esac

데모에서는 push하는 대신 제 노트북에서 직접 돌렸습니다. 브랜치 셋이 저장소 히스토리에 남기고 싶지 않은 일회용이었고, 출력이 흘러가는 걸 지켜보고 싶었기 때문입니다. 팀에서 쓸 때는 아무도 이걸 타이핑하지 않습니다. 아래에 나오는 라벨 워크플로가 정확히 이 스크립트를 돌리고, 지금부터 보이는 출력은 Actions 로그에 남을 그것입니다. 툴링 자체를 담은 브랜치에서 처음 실행했을 때 찍힌 출력입니다.

$ ./scripts/env up
== feature/branch-environments -> feature-branch-envir-c65cb4
New app created: myapp-feature-branch-envir-c65cb4
CREATE DATABASE
Secrets have been staged, but not set on VMs. Deploy or update machines in this app for the secrets to take effect.
==> Building image
image size: 139 MB
✔ Machine 1a2b3c4d5e6f78 [app] update finished: success
https://feature-branch-envir-c65cb4-dev.example.com

$ curl -s https://feature-branch-envir-c65cb4-dev.example.com/api/version/
{"environment": "feature-branch-envir-c65cb4", "branch": "feature/branch-environments", "commit": "a1b2c3d4", "region": "syd"}

명령에서 URL까지 2분 30초쯤이고, 대부분은 이미지 빌드입니다. 커밋 하나 더 한 뒤 같은 브랜치에서 두 번째 up을 하니 “New app created"도 “CREATE DATABASE"도 찍히지 않았고, 같은 시크릿 이름을 스테이징하되 생성된 것들은 다시 만들지 않았으며, 다시 빌드했습니다. 같은 URL, 새 커밋.

안에 든 선택 몇 가지는 한 문장씩 값을 합니다.

fly.preview.toml은 fly.toml이 아닙니다. 프로덕션은 API, WebSocket 서버, 백그라운드 워커를 별도 Fly 앱과 프로세스 그룹으로 굴려 각자 자기 지표로 스케일하게 하고, 그게 스택 글의 논지 전부입니다. 브랜치 환경은 스케일할 필요가 없습니다. 머신 하나여야 합니다. 그래서 프리뷰 설정은 프로세스가 하나이고, 컨테이너 entrypoint에 프리뷰 모드가 생겨 마이그레이션을 돌린 뒤 WebSocket을 켠 ASGI 서버 하나를 띄웁니다. Channels가 이미 ASGI 애플리케이션 하나 안에서 HTTP와 WebSocket 트래픽을 모두 라우팅하니 프로세스 하나가 앱 전체를 서빙합니다. 그 모드에서 동기 뷰는 thread-sensitive로, 대략 한 번에 요청 하나씩 돕니다. 프로덕션에서 제가 벗어난 바로 그 거래인데, 여기서는 정확히 맞는 거래입니다. 브랜치를 테스트하는 사람은 아무도 눈치채지 못하니까요.

# fly.preview.toml (the app name comes from `fly deploy -a`)
app = 'placeholder'
primary_region = 'syd'

[processes]
  app = "/app/entrypoint.sh preview"   # migrate, then one ASGI server for HTTP and WebSockets

[env]
  DJANGO_SETTINGS_MODULE = 'myapp.settings'
  DEBUG = 'False'

[http_service]
  internal_port = 8000
  force_https = true
  auto_stop_machines = 'suspend'
  auto_start_machines = true
  min_machines_running = 0
  [[http_service.checks]]
    path = '/healthz'
    [http_service.checks.headers]
      Host = '127.0.0.1'               # the app's own hostname isn't known to a static file

[[vm]]
  size = 'shared-cpu-1x'
  memory = '1gb'

auto_stop_machines = "suspend", min_machines_running = 0. 점심 이후 아무도 열지 않은 브랜치 환경은 비용이 0이어야 합니다. stop 대신 suspend를 쓰면 30초 콜드 스타트 대신 504를 쫓다가 도달한 3초쯤의 재개를 얻는데, 여기서는 30초라도 견딜 만합니다. 데모 환경 셋 중 둘은 배포가 끝나고 1분 만에 fly apps list에서 이미 suspended였습니다.

fly.io/apps/myapp-feature-profile-tagl-fa8832

DEBUG = False, 프로덕션과 같은 settings 모듈. 브랜치 환경은 공개 URL입니다. 테스트에 중요한 모든 면(진짜 HTTPS, 진짜 쿠키, 같은 헬스 체크)에서 프로덕션처럼 굴고, 누군가를 다치게 할 수 있는 모든 면에서는 프로덕션과 달라야 합니다. 별도의 프리뷰용 settings 파일 대신, 차이는 env up이 설정하는 시크릿이 실어 나릅니다. 샌드박스 결제 키, 인증 서비스 관리자 자격 증명 없음, 그리고 아래의 모든 접두사를 켜는 ENV_NAME.

설정 하나가 모든 것을 자릅니다. ENV_NAME은 settings에 새로 들어간 유일한 손잡이이고, 네 곳에 적용됩니다.

ENV_NAME = os.getenv("ENV_NAME", "")
_prefix = f"{ENV_NAME}/" if ENV_NAME else ""

CACHES["default"]["KEY_PREFIX"] = ENV_NAME                           # every cache key
CHANNEL_LAYERS["default"]["CONFIG"]["prefix"] = f"{ENV_NAME}:asgi"  # Channels group and channel names
STORAGES["default"]["OPTIONS"]["location"] = f"{_prefix}media"      # uploads
STORAGES["staticfiles"]["OPTIONS"]["location"] = f"{_prefix}static"

channels 쪽을 빠뜨리면 두 브랜치의 WebSocket 서버가 그룹 이름을 공유해서, 한 환경에서 보낸 메시지가 다른 환경에 나타납니다. 하루를 잡아먹는 종류의 버그입니다.

다섯 번째 자리는 나중에 공유 Redis를 읽어 보고서야 찾았습니다. 504 글의 시작 락, 즉 이미지당 머신 하나가 마이그레이션을 돌리는 동안 나머지가 기다리게 하는 장치는 이미지 참조를 키로 삼고 있었습니다. 같은 커밋에서 빌드된 브랜치 환경 둘은 같은 이미지를 갖습니다. 두 번째 환경은 첫 번째의 “done” 마커를 발견하고, 마이그레이션되지 않은 자기 데이터베이스에 대한 자기 마이그레이션을 건너뛰었을 겁니다. 지금은 환경 이름이 키에 들어가고 키는 접두사 아래에 삽니다. 공유 인프라 설계가 계속 만들어 내는 종류의 문제입니다. 암묵적으로 “배포당"이던 모든 것을 명시적으로 환경당으로 만들어야 하고, 뭐가 암묵적이었는지는 들여다보기 전까지 모릅니다.

데이터베이스는 빈 상태에서 마이그레이션하는 게 아니라 복제합니다. 다음 절입니다.

데이터베이스: 몇 초 만에 복제되는 템플릿

#

브랜치 환경의 데이터베이스는 셋 중 하나일 수 있습니다. 모두와 공유. 우리를 여기까지 데려온 방식입니다. 빈 상태에서 마이그레이션하고 픽스처로 시드. 결정론적이지만, 픽스처는 실제 모양의 데이터만큼 좋았던 적이 없고 언제나 열여덟 달은 묵어 있습니다. 아니면 프로덕션 모양 스냅샷의 복제. 현실적인 행 수, 픽스처는 늘 채워져 있다고 가정했던 컬럼의 현실적인 null, 빈 테이블에서는 즉시 끝나지만 실제 테이블에서는 40분 걸리는 마이그레이션이 제 모습을 드러냅니다.

세 번째로 가되, 두 번째는 CI 전용 검사로 남깁니다. 그리고 세 번째를 브랜치마다 할 만큼 빠르게 만드는 건 대부분이 있는지도 잊은 Postgres 기능입니다.

-- Nightly, on the preview cluster. Restore last night's prod backup into seed_raw,
-- run the anonymiser, then freeze it as a template nobody can connect to.
ALTER DATABASE seed_raw RENAME TO seed_template;
UPDATE pg_database SET datistemplate = true, datallowconn = false WHERE datname = 'seed_template';

-- Per branch, in the time it takes to copy the files:
CREATE DATABASE env_feature_payments_retr_3f9a1c TEMPLATE seed_template;

CREATE DATABASE ... TEMPLATE은 클러스터 안에서의 파일 수준 복사입니다. 몇 기가바이트면 pg_restore가 걸리는 몇 분이 아니라 몇 초입니다. 복제되는 동안 템플릿에는 열린 연결이 있으면 안 되고, datallowconn = false가 그걸 강제합니다. 밤 작업이 살아 있는 템플릿 위에 복원하는 대신 seed_raw에 빌드하고 마지막에 이름을 바꾸는 이유이기도 합니다.

데모에서는 프로덕션 덤프 대신 손으로 템플릿을 만들었습니다. fly proxy로 프리뷰 클러스터에 터널을 뚫고, manage.py migrate, 그다음 저장소에 있는 시드 명령으로 작지만 현실적인 데이터 세트를 넣었습니다. 19메가바이트. 브랜치 셋이 올라오면서 클러스터에 복제본 셋이 나타났고, 각각 19 MB, 각각 1초 미만이었습니다.

$ fly ssh console -a myapp-preview-pg -C "psql ... -c '\l'"
             datname             | template | size
---------------------------------+----------+-------
 env_feature_branch_envir_c65cb4 | f        | 19 MB
 env_feature_profile_tagl_fa8832 | f        | 19 MB
 env_feature_profile_webs_dcb2e7 | f        | 19 MB
 seed_template                   | t        | 19 MB

프리뷰 클러스터는 관리형이 아닌 Fly Postgres 노드 하나, 1 GB 볼륨을 단 shared-cpu-1x로, 한 달에 2달러쯤입니다. 브랜치 환경은 사설 네트워크의 .flycast로 붙습니다. 공개된 것은 아무것도 없습니다.

익명화기는 선택이 아닙니다. 프로덕션 데이터가 -dev 호스트명에서 닿는 순간, 그건 프로덕션 데이터가 아니어야 합니다. 이름, 이메일, 전화번호, 주소, 자유 텍스트, 결제 참조, 토큰을 이름을 바꾸기 전에 전부 덮어씁니다. 익명화기가 실패하면 전날 밤 템플릿이 남고 누군가 메시지를 받습니다. 작은 일이고, 이 접근 전체를 개인정보 설문에 답하는 사람이 받아들일 수 있게 만드는 바로 그 일입니다.

entrypoint가 모든 이미지의 첫 부팅에서 migrate를 돌리므로, 브랜치 자신의 마이그레이션이 템플릿 위에 적용됩니다. “내 마이그레이션이 프로덕션 모양의 데이터에서 되나"의 첫 정직한 테스트이고, 누가 URL을 열어 보기 전에 일어납니다.

호스트명: 와일드카드 하나, Worker 하나, 그리고 문서가 알려주지 않은 두 가지

#

모든 환경에는 공개 HTTPS 호스트명이 필요하고, “공개"가 핵심입니다. 폰을 든 테스터, 다른 네트워크의 디자이너, VPN을 깔지 않을 프로덕트 매니저. Fly는 앱마다 myapp-$ENV.fly.dev를 공짜로 주고, 그것만으로도 됩니다. 하지만 *.fly.dev 호스트명에는 문제가 셋 있습니다. 보내기에 못생겼고, 앞에 Cloudflare가 없어서 프로덕션에 걸어 둔 보호가 하나도 적용되지 않으며, 자기 도메인에 두고 싶으면 환경마다 DNS 레코드 하나와 인증서 하나를 만들어야 하니 스위퍼가 치울 것이 하나 더 생깁니다.

그걸 전부 없애는 버전은 와일드카드 하나와 Cloudflare Worker 하나입니다. 계획은 *.dev.example.com이었습니다. 두 가지가 막았고, 같은 걸 계획하기 전에 둘 다 알아 둘 가치가 있습니다.

Universal SSL은 와일드카드 한 단계만 덮습니다. Cloudflare의 무료 인증서는 example.com과 *.example.com에 발급됩니다. *.dev.example.com은 덮지 않습니다. 두 단계 와일드카드에는 월 10달러의 Advanced Certificate Manager가 필요합니다. feature-branch-envir-c65cb4.dev.example.com으로의 첫 요청은 제 것이 무엇 하나 돌기도 전에 SSL 핸드셰이크 실패로 죽었습니다. 해결은 환경을 첫 라벨에 두는 것입니다. feature-branch-envir-c65cb4-dev.example.com. 이미 있는 인증서가 덮고, 이미 있는 프록시된 *.example.com 레코드가 덮습니다. 지어낸 서브도메인을 훑는 스캐너용 싱크홀로 제가 만들어 둔 그 레코드입니다. 그러니 환경에는 DNS가 아예 필요 없습니다.

Redirect Rules는 Workers보다 먼저 돕니다. 라우트를 걸어 두자 모든 -dev 호스트명이 Worker가 돌지도 않은 채 www 홈페이지로 301을 답했습니다. 싱크홀은 존 수준 리다이렉트 규칙 “그 밖의 모든 서브도메인 → www"이고, Cloudflare의 리다이렉트 단계는 Workers 단계보다 먼저 실행됩니다. 규칙에 절 하나가 필요했습니다. and not ends_with(http.host, "-dev.example.com"). 배포 스크립트가 up에서 넣고 down에서 빼는데, 누군가 손으로 고친 규칙이야말로 잊히는 것이기 때문입니다.

dash.cloudflare.com/…/example.com/rules/redirect-rules/…/edit

DNS 쪽은 이미 있던 그 레코드입니다.

dash.cloudflare.com/…/example.com/dns/records

그 둘을 치우고 나면 라우팅은 *-dev.example.com/*에 걸린 Worker 하나입니다.

// dev-router.js: <env>-dev.example.com -> myapp-<env>.fly.dev
const DEV_SUFFIX = "-dev.example.com";
const ENV_NAME = /^[a-z0-9-]+-[0-9a-f]{6}$/;   // slug-hash, as scripts/env names them

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (!url.hostname.endsWith(DEV_SUFFIX)) return new Response("not a dev hostname", { status: 404 });
    const env = url.hostname.slice(0, -DEV_SUFFIX.length);
    if (!ENV_NAME.test(env)) return new Response(`no such environment: ${env}`, { status: 404 });

    url.hostname = `myapp-${env}.fly.dev`;
    const upstream = new Request(url, request);
    upstream.headers.set("X-Forwarded-Host", request.headers.get("host") ?? "");

    const res = await fetch(upstream);
    const out = new Response(res.body, res);
    out.headers.set("X-Robots-Tag", "noindex, nofollow");   // a half-finished branch is not for search engines
    out.headers.set("X-Dev-Environment", env);
    return out;
  },
};

Cloudflare가 와일드카드에서 TLS를 종단하고, Worker가 라벨에서 Fly 호스트명을 계산하며, 머신까지의 구간은 Fly 자체의 *.fly.dev 인증서가 덮습니다. WebSocket 업그레이드는 fetch를 그대로 통과합니다. 그리고 라우트가 존에 있으니 Cloudflare가 프로덕션에 해 주는 모든 것을 쓸 수 있습니다. WAF 규칙, 속도 제한, 봇 대응 모드, 그리고 Access.

dash.cloudflare.com/…/example.com/workers

브랜치 셋을 동시에 띄우고, Worker 하나, 각 호스트명이 답한 것.

모든 200에는 Worker가 붙인 X-Robots-Tag: noindex, nofollow와 X-Dev-Environment: <env>가 함께 왔습니다. 404는 Fly에 묻기도 전에 Worker가 직접 낸 것입니다.

Cloudflare Access는 “공개"를 “닿아야 할 사람에게 닿음"으로 바꾸는 장치입니다. *-dev.example.com에 애플리케이션 하나, “@example.com 이메일이면 누구나” 정책 하나면 브라우저 방문자는 로그인 페이지를 한 번 보고 다시는 신경 쓰지 않습니다. 노트북의 디자이너, PM, 테스터는 그걸로 됩니다. 데모에는 넣지 않았습니다. 환경은 한 시간 동안 noindex를 달고 시드 데이터 말고는 아무것도 없이 떠 있었습니다.

모바일 앱은 덮지 못합니다. 네이티브 앱은 Access 로그인 리다이렉트를 완료할 수 없으니까요. 길은 둘입니다. Access는 로그인을 우회하는 서비스 토큰(CF-Access-Client-Id / CF-Access-Client-Secret 헤더 쌍)을 지원하고, 모바일 앱의 dev 메뉴가 dev 호스트명용 한 쌍을 실을 수 있습니다. 아니면 더 단순하게, /api/에 Access 우회를 넣고 Django가 로그인한 사용자나 환경의 ENV_TOKEN, 즉 env up이 바로 이 환경을 위해 생성한 그 토큰이 없는 요청을 거부하게 합니다. 어느 쪽이든 모바일 쪽은 기본 URL과 토큰 두 필드가 있는 dev 메뉴 화면이고, 테스터가 이미 설치한 앱이 이제 그 브랜치와 통신합니다. 새 빌드는 없습니다. OTA 업데이트 채널은 앱이 빌드된 대로 그대로 두고, API 기본 URL은 빌드 시점이 아니라 런타임 설정이며, 원래 그랬어야 합니다.

인증은 일부러 공유하는 유일한 공유 서비스입니다. 신원은 환경에 따라 다르지 않습니다. 테스터는 모든 브랜치에서 같은 계정으로 로그인하고 싶어 합니다. 승인된 도메인에 example.com을 넣은 인증 서비스의 dev 프로젝트 하나가 모든 -dev 호스트명을 덮고, 모든 환경이 그걸 상대로 ID 토큰을 검증합니다. 각 환경 데이터베이스의 사용자 테이블은 템플릿 사용자의 복사본이니, 테스터의 계정은 템플릿에 있던 모든 곳에 있습니다.

GitHub Actions로 프리뷰 환경 자동화하기: 이벤트가 들어가고 환경이 나온다

#

위의 모든 것을 손으로 하는 건 혼자 할 때는 괜찮습니다. 두 번째 개발자가 생기는 순간부터는 누가 기억해서가 아니라 git에서 뭔가 일어났기 때문에 일어나야 합니다. 자동화 전체는 워크플로 넷, 저장소 설정 하나, 룰셋 하나, GitHub environment 하나이고, 그 하나하나가 git 이벤트를 개발자가 손으로 돌리는 것과 같은 scripts/env 호출에 대응시킵니다. 따로 놀다 어긋날 CI 전용 경로는 없습니다.

라벨, push, delete 워크플로

#

# .github/workflows/branch-env.yml
name: branch environment
on:
  pull_request:
    types: [labeled, unlabeled, synchronize, closed]
  delete:
  workflow_dispatch:
    inputs:
      branch: { description: branch to bring up without a PR, required: true }

concurrency:
  group: env-${{ github.head_ref || github.event.ref || inputs.branch }}
  cancel-in-progress: true

env:
  FLY_API_TOKEN: ${{ secrets.FLY_PREVIEW_TOKEN }}   # org-scoped deploy token; a separate preview org keeps it away from prod
  PG_PASSWORD: ${{ secrets.PREVIEW_PG_PASSWORD }}
  # ... the shared Redis URL and bucket credentials, the same way

jobs:
  up:
    # the gate: a PR carrying the `env` label, or someone asking for a branch by hand
    if: >-
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' && github.event.action != 'closed'
        && contains(github.event.pull_request.labels.*.name, 'env'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { ref: "${{ github.head_ref || inputs.branch }}" }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - id: env
        env: { BRANCH: "${{ github.head_ref || inputs.branch }}" }
        run: scripts/env up && echo "url=$(scripts/env url)" >> "$GITHUB_OUTPUT"
      - if: github.event_name == 'pull_request'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: env
          message: "Branch environment: ${{ steps.env.outputs.url }}"

  down:
    # label removed, labelled PR closed or merged, or the branch itself deleted
    if: >-
      (github.event_name == 'pull_request' &&
        ((github.event.action == 'closed' && contains(github.event.pull_request.labels.*.name, 'env')) ||
         (github.event.action == 'unlabeled' && github.event.label.name == 'env'))) ||
      (github.event_name == 'delete' && github.event.ref_type == 'branch')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: BRANCH="${{ github.head_ref || github.event.ref }}" scripts/env down

게이트는 env 라벨이고, 제가 가장 강하게 주장하고 싶은 부분입니다. 게이트가 없으면 모든 브랜치가 앱 하나와 데이터베이스 복제본 하나를 비용으로 치릅니다. 노트북 백업용으로 push한 브랜치, 내일 squash될 스파이크, 봇이 새벽 3시에 연 의존성 업데이트까지요. 그래서 push만으로는 아무 일도 일어나지 않고, PR을 여는 것만으로도 아무 일도 일어나지 않습니다. PR에 env를 붙이면 환경이 올라오고, 라벨이 붙어 있는 동안의 push마다 갱신되고, 라벨을 떼거나 PR을 닫거나 머지하면 내려갑니다. 옵트인은 여전히 GitHub 이벤트이지 사람에게 하는 부탁이 아니고, 누가 볼 건지 아는 유일한 사람이 하는 클릭 한 번입니다. 고정 댓글이 사용자 인터페이스입니다. PR에 라벨을 붙이면 누구에게든 보낼 수 있는 URL이 담긴 댓글이 나타나고, push마다 쌓이는 대신 제자리에서 갱신됩니다. PR이 생기기 전에 올리고 싶은 브랜치는 workflow_dispatch가, 나머지는 노트북에서 돌리는 ./scripts/env up이 맡습니다.

알아 둘 만한 게이트가 둘 더 있습니다. 브랜치 이름 필터(branches: ['feature/**', 'fix/**'])는 PR이 필요 없지만 모든 기능 브랜치가 비용을 치릅니다. “드래프트가 아닌 모든 PR"은 가장 자동적이고, 팀이 PR을 늦게, 준비됐을 때만 연다면 맞는 선택입니다. 저는 라벨을 골랐습니다. 비용 결정을 맥락을 아는 사람에게 두고, 아무것도 닫지 않고 되돌릴 수 있기 때문입니다. 마음에 드는 부작용 하나. 포크에서 온 pull_request 실행은 시크릿을 받지 못하니, 포크는 환경을 띄울 수 없습니다.

concurrency는 보기보다 중요합니다. 한 브랜치에 push가 연달아 오면 앞선 배포를 경주시키는 대신 취소합니다. 같은 앱에 fly deploy 둘이 동시에 돌면 하나가 지는 걸로 끝납니다.

PR이 있던 것은 머지됐든 아니든 closed가 철거를 맡습니다. delete 이벤트는 workflow_dispatch로 띄웠는데 끝내 PR이 생기지 않은 브랜치를 위한 뒷받침이고, 브랜치가 실제로 삭제될 때만 발생합니다. 그건 저장소 설정 Automatically delete head branches이고, 기본은 꺼져 있습니다. 켜 두면 Merge를 누르는 것이 PR을 닫고 브랜치를 삭제하니, 두 이벤트 중 어느 하나만으로도 env down이 돌았을 겁니다. 머지 버튼이 철거입니다.

gh api -X PATCH repos/org/myapp -f delete_branch_on_merge=true

FLY_PREVIEW_TOKEN이 파일에서 위험한 줄입니다. 앱을 만들고 없앨 수 있으니, $APP이 브랜치 환경이 아닌 무언가가 되는 순간 프로덕션을 없앨 수도 있습니다. 가드는 둘이고 둘 다 두겠습니다. 토큰을 별도의 Fly 조직에 한정해 프로덕션 조직을 말 그대로 볼 수 없게 하는 것(데모에서는 새 조직에 결제 정보를 붙이는 걸 건너뛰려고 프로덕션 조직을 그대로 썼고, 두 번째 가드 하나에 기댔습니다), 그리고 down()이 slug-hash 패턴에 맞지 않는 앱 이름을 전부 거부하는 것.

브랜치 환경이 스스로 할 수 없는 검사

#

브랜치는 자기 마이그레이션만 봅니다. 그래서 중요한 검사는 pull request에서 main을 머지한 상태를 상대로 돌고, main이 요구하는 유일한 상태 검사입니다.

# .github/workflows/migrations-check.yml
name: migrations
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:18
        env: { POSTGRES_PASSWORD: ci, POSTGRES_DB: ci }
        ports: ['5432:5432']
        options: --health-cmd pg_isready --health-interval 5s --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:ci@localhost:5432/ci
      SECRET_KEY: ci-only
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: '3.14' }
      - run: pip install -r requirements.txt
      - name: Merge main into the branch (a conflict here fails the check too)
        run: |
          git config user.email ci@example.com && git config user.name ci
          git merge --no-edit origin/main
      - name: One leaf in the migration graph
        run: python manage.py makemigrations --check --dry-run
      - name: The full chain applies from nothing
        run: python manage.py migrate --noinput

30초. 0042 / 0042 충돌을 릴리스 당일의 놀람에서 두 번째 개발자 PR의 빨간 체크로 바꿔 주는 것이 이겁니다. 아래 마이그레이션 절에서 실제로 걸리는 모습을 보여줍니다.

main의 규칙

#

브랜치가 한 달을 살거나 누군가 main에 직접 push하면 이 중 무엇도 버티지 못합니다. 규칙은 보호라기보다 환경을 작게, 마이그레이션을 최신으로 유지하기 위한 것입니다.

• main은 보호되고 언제나 배포 가능합니다. 현재 main을 기준으로 migrations 검사가 초록인 PR로만 머지합니다(strict 상태 검사이니, 지난주에 초록이던 PR은 main이 움직이면 다시 돕니다). 선형 이력, force-push 금지, 삭제 금지.
• 기능 브랜치는 짧습니다. 2주 열려 있는 브랜치는 main보다 2주 뒤처진 환경과, 남의 것과 충돌할 확률이 2주치 더 높은 마이그레이션을 갖습니다. 한 달짜리 기능은 플래그 뒤에서 조각조각 main에 머지합니다. 오래 사는 건 플래그이지 브랜치가 아닙니다.
• 브랜치 하나, 환경 하나, 데이터베이스 하나. 이미 이름이 강제합니다.
• 프로덕션에 가는 건 릴리스 태그뿐입니다. 이미지는 태그에서 한 번 빌드되고, 스테이징과 프로덕션은 그 이미지를 돌립니다. 다시 빌드하지 않습니다.
• migrations/를 건드리는 PR은 나머지 둘 중 하나가 리뷰합니다. 아래에.

룰셋으로는, gh api -X POST repos/org/myapp/rulesets --input ruleset-main.json으로 한 번 적용합니다.

{
  "name": "main", "target": "branch", "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_linear_history" },
    { "type": "pull_request",
      "parameters": { "required_approving_review_count": 1, "dismiss_stale_reviews_on_push": true,
                      "required_review_thread_resolution": true } },
    { "type": "required_status_checks",
      "parameters": { "strict_required_status_checks_policy": true,
                      "required_status_checks": [ { "context": "check" } ] } }
  ]
}

솔직한 주름 하나. 이 저장소는 GitHub Free 플랜의 비공개 저장소이고, Free에서 브랜치 보호와 룰셋은 공개 저장소에서만 쓸 수 있습니다. API는 403 Upgrade to GitHub Pro or make this repository public이라고 답합니다. delete_branch_on_merge 설정, environment, 워크플로는 Free에서도 전부 됩니다. 그러니 비공개 Free 저장소의 작은 팀에게 위 룰셋은 관례입니다. migrations 워크플로는 여전히 돌고 여전히 빨개지지만, 머지 버튼을 회색으로 만드는 것은 없습니다. 월 4달러짜리 결정이고, 저라면 두 번째 사람이 머지할 수 있게 되는 순간 하겠습니다.

develop 브랜치도 release/* 브랜치도 없습니다. Git-flow는 통합이 비싸서 묶어서 해야 한다는 전제로 설계됐습니다. 브랜치 환경이 통합을 싸게 만드니, 묶음이 사라집니다.

스테이징은 태그의 환경이고, 프로덕션은 승격이다

#

스테이징은 장치 전부를 재사용합니다. main의 v* 태그가 브랜치 이름 staging/v1.42.0으로 scripts/env up을 돌리고, 이름 규칙이 그걸 staging-v1-42-0-<hash>로 바꿉니다. 같은 템플릿 복제 데이터베이스, 같은 놀면 suspend되는 머신, 같은 호스트명 체계. 차이는 그 뒤에 오는 것입니다.

# .github/workflows/release.yml (abridged)
on:
  push:
    tags: ['v*']
jobs:
  staging:
    steps:
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env up
      - run: echo "image=$(fly image show -a "myapp-$(BRANCH=staging/$GITHUB_REF_NAME scripts/env name)" --json | jq -r '…')" >> "$GITHUB_OUTPUT"
  production:
    needs: staging
    environment: production        # required reviewer on this environment = the promotion gate
    steps:
      - run: fly deploy --config fly.api.toml --image "${{ needs.staging.outputs.image }}"
      - run: fly deploy --config fly.ws.toml  --image "${{ needs.staging.outputs.image }}"
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env down

production 잡은 필수 리뷰어가 있는 GitHub environment를 기다립니다. 누군가 스테이징을 보고 Approve를 누르면, 프로덕션은 스테이징이 돌린 같은 이미지를 참조로 받습니다. 다시 빌드하지 않습니다. 마지막 단계가 스테이징을 없애는 건 제 할 일을 다 했기 때문입니다. 아무도 승인하지 않으면 릴리스 후보는 거절된 것이고, 스위퍼가 그 “브랜치”(staging/v1.42.0은 origin에 존재한 적이 없습니다)가 생존 검사에 실패할 때 스테이징을 치웁니다. 스위퍼가 확인할 수 있는 이유 없이는 아무것도 존재할 수 없습니다.

밤마다 도는 스위퍼

#

# .github/workflows/sweep-envs.yml
on:
  schedule:
    - cron: '0 14 * * *'     # 02:00 NZST
  workflow_dispatch:
jobs:
  sweep:
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: scripts/sweep-envs

fetch-depth: 0은 스위퍼가 Actions가 기본으로 체크아웃하는 커밋 하나가 아니라 모든 원격 브랜치와 마지막 커밋 날짜를 필요로 하기 때문입니다. workflow_dispatch는 사고 뒤에 손으로 돌릴 수 있게 하려는 것입니다.

개발자가 실제로 하는 일

#

브랜치를 push하고, PR을 열고, 누군가 봐 줬으면 할 때 env 라벨을 붙입니다. 목록은 그게 전부입니다. 3분 안에 PR에 URL이 나타나고, push마다 갱신되고, PR이 머지되거나 닫히면 사라집니다. 팀원과 충돌했다면 마이그레이션 검사가 누구보다 먼저 알려줍니다. 차지할 스테이징이 없으니 아무도 스테이징을 차지하지 않고, 철거가 곧 머지이니 아무도 뭘 철거하지 않습니다.

그리고 이걸 세팅한 사람이 그 뒤로 브랜치마다 하는 일은, 없습니다. 공유 Postgres, Redis, 버킷은 한 번 프로비저닝하고, 시크릿은 Actions에 한 번 넣고, 그 뒤로 반복되는 일이라곤 월요일에 스위퍼 로그를 읽는 것뿐입니다. 티켓 큐도, 불러야 할 봇도, 프롬프트를 넣을 대상도 없습니다.

철거를 믿지 않는 철거

#

env down이 보통의 경우이고, 흥미로운 부분은 누가 치우느냐입니다. Redis 키와 버킷 객체는 공유 서비스의 것이고, down을 돌리는 노트북은 어느 쪽 자격 증명도 필요 없습니다. 환경 자신의 머신이 이미 그걸 갖고 있고 자기 접두사를 이미 알기 때문입니다. 그래서 down은 머신이 suspend돼 있으면 깨우고, 거기서 작은 정리 명령을 돌린 다음에야 앱을 없애고 데이터베이스를 드롭합니다. 환경이 스스로 뒷정리를 합니다.

$ BRANCH=feature/profile-website ./scripts/env down
redis: deleted 0 keys under feature-profile-webs-dcb2e7:*
bucket: deleted 278 objects under feature-profile-webs-dcb2e7/
Destroyed app myapp-feature-profile-webs-dcb2e7
DROP DATABASE

$ curl -s -o /dev/null -w '%{http_code}\n' https://feature-profile-webs-dcb2e7-dev.example.com/api/version/
530

530은 조정에 관한 요점을 다시 보여줍니다. Worker는 여전히 호스트명을 라우팅하고, Fly에는 아무것도 없으며, 아무도 Cloudflare에 알릴 필요가 없었습니다.

정리 명령은 ENV_NAME 없이는 실행을 거부합니다. 접두사가 비어 있으면 공유 버킷을 통째로 지우는 일이 되니까요. 그 가드가 이게 셸 스크립트 세 줄이 아니라 앱 안의 명령으로 존재하는 이유 전부입니다.

그래도 환경은 샙니다. GitHub Actions가 장애인 사이에 브랜치가 삭제됩니다. 개발자가 실험용으로 노트북에서 env up을 돌리고 push는 영영 안 합니다. fly apps destroy가 일시적으로 실패하고 || true가 삼킵니다. 석 달 뒤 앱이 마흔 개이고, 누군가 무슨 일이냐고 묻게 만드는 청구서가 옵니다.

그래서 첫 번째를 믿지 않는 두 번째 장치가 있습니다. 위 표의 밤마다 도는 스위퍼입니다. 모든 myapp-* 앱을 나열하고, 각각이 어느 브랜치 것인지 알아내고, 브랜치가 사라졌거나 7일간 push가 없는 것을 전부 없앱니다. 일주일 논 브랜치에 살아 있는 URL은 필요 없고, 다음 push가 2분 만에 다시 만듭니다. 해시는 되돌릴 수 없으니, 스위퍼는 살아 있는 모든 브랜치의 환경 이름을 계산해 그 집합에 없는 앱을 전부 없앤 뒤, 뒤에 앱이 없는 env_* 데이터베이스를 드롭합니다.

#!/usr/bin/env bash
# scripts/sweep-envs: nightly
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; TTL_DAYS=${TTL_DAYS:-7}
cutoff=$(( $(date +%s) - TTL_DAYS*86400 ))

git fetch --prune --quiet origin
live=""
while IFS=$'\t' read -r ts branch; do
  [[ "$branch" == "main" ]] && continue
  (( ts >= cutoff )) || continue
  live+="$(BRANCH="$branch" scripts/env name)"$'\n'
done < <(git for-each-ref --format='%(committerdate:unix)%09%(refname:short)' refs/remotes/origin | sed 's#^\([0-9]*\)\torigin/#\1\t#')

apps=$(fly apps list --org "$ORG" --json | grep -o '"Name": *"myapp-[^"]*"' | cut -d'"' -f4)
for app in $apps; do
  env="${app#myapp-}"
  [[ "$env" =~ ^[a-z0-9-]+-[0-9a-f]{6}$ ]] || continue       # not a branch environment (e.g. myapp-preview-pg)
  grep -qx "$env" <<<"$live" && continue
  echo "sweeping $app: branch gone or idle > ${TTL_DAYS}d"
  ENV_OVERRIDE="$env" scripts/env down || true
done
# ...then any env_* database with no app: DROP DATABASE.

데모 브랜치는 어느 것도 push된 적이 없으니(위의 노트북 실행), 스위퍼 입장에서는 전부 사라진 것이었습니다. 누군가 노트북에서 띄우고 끝내 push하지 않은 스파이크가 일주일 뒤에 놓일 상태가 정확히 이것입니다. 남은 둘을, tagline 환경이 써 둔 Redis 키까지 포함해 해체했습니다.

$ ./scripts/sweep-envs
sweeping myapp-feature-branch-envir-c65cb4: branch gone or idle > 7d
redis: deleted 0 keys under feature-branch-envir-c65cb4:*
bucket: deleted 322 objects under feature-branch-envir-c65cb4/
Destroyed app myapp-feature-branch-envir-c65cb4
DROP DATABASE
sweeping myapp-feature-profile-tagl-fa8832: branch gone or idle > 7d
redis: deleted 3 keys under feature-profile-tagl-fa8832:*
bucket: deleted 278 objects under feature-profile-tagl-fa8832/
Destroyed app myapp-feature-profile-tagl-fa8832
DROP DATABASE

$ fly apps list --org myapp-preview | grep myapp-
 myapp-preview-pg │ myapp-preview │ deployed

(작게 문 것 하나. macOS에는 연관 배열이 없는 bash 3이 딸려 옵니다. 스위퍼 첫 버전은 그걸 썼다가 제 노트북에서 declare -A에서 죽었습니다. 위 버전은 줄바꿈으로 구분한 목록을 써서 어디서든 돕니다.)

비용은 즐거운 부분입니다. suspend된 머신은 rootfs 값만 내고, 한 달에 몇 센트입니다. 데이터베이스는 이미 값을 치른 볼륨 위의 19 MB입니다. Redis는 종량제 플랜으로, 명령 10만 개에 20센트인데 브랜치 테스트 규모에서는 0으로 반올림됩니다. 버킷 접두사는 저장한 만큼 냅니다. 공유 Postgres 노드가 유일한 고정 항목으로, 한 달에 2달러쯤입니다. 활성 브랜치 스무 개는 항상 켜진 shared-cpu-1x 하나 값쯤이고, 스위퍼가 그걸 이백이 아니라 스물로 유지합니다. 데모 전체, 즉 한 시간 동안의 환경 셋과 공유 부품은 그동안 마신 커피보다 쌌습니다.

브랜치를 가로지르는 마이그레이션, 경고해 줄 공유 데이터베이스 없이

#

개발자마다 기능을 처음부터 끝까지 맡으면 모든 브랜치에 마이그레이션이 들어 있습니다. 그래서 이 절이 중요한 절입니다.

공유 환경 세계를 떠날 때 사람들이 놓치는 것이 있습니다. 모두가 dev 데이터베이스 하나에 배포할 때 마이그레이션 충돌은 즉시, 아프게 드러났지만, 어쨌든 드러났습니다. 마이그레이션 하나가 돌고, 다음 배포가 실패하고, 누군가 그날 오후에 고쳤습니다. 브랜치마다 데이터베이스가 있으면 각 마이그레이션은 자기 환경에서 완벽하게 돌고, 둘은 두 번째가 main에 머지될 때 처음 만납니다. 부주의하게 하면 충돌이 싸던 dev에서 싸지 않은 릴리스로 옮겨 갑니다.

규칙 넷, 전부 CI로 강제할 수 있어서 아무도 기억할 필요가 없습니다.

1. main을 머지한 상태에서 마이그레이션 그래프에 리프가 둘이면 CI가 실패합니다. makemigrations --check는 모델과 마이그레이션이 어긋난 걸 잡지만, 중요한 충돌은 두 브랜치가 둘 다 0042_*를 추가한 것입니다. 브랜치 단독이 아니라 main에 머지된 브랜치를 상대로 확인합니다.

git fetch origin main
git merge --no-commit --no-ff origin/main || { echo "merge conflict"; exit 1; }
python manage.py makemigrations --check --dry-run
python manage.py migrate --plan 2>&1 | grep -q "Conflicting migrations" && exit 1

이건 제가 일부러 일으킨 것입니다. 데모 브랜치 셋 중 둘, feature/profile-tagline과 feature/profile-website가 각각 마이그레이션 하나로 사용자 프로필 모델에 필드 하나를 추가했고, 각 환경은 올라오면서 자기 것을 적용했습니다. 새 컬럼은 있어야 할 곳에만 있었습니다.

env_feature_branch_envir_c65cb4      (no new column)
env_feature_profile_tagl_fa8832      tagline
env_feature_profile_webs_dcb2e7      website

둘 다 0042_*입니다. 어느 브랜치도 상대 것을 볼 수 없으니, 어느 환경도 문제가 있다고 말해 주지 못합니다. 하나를 다른 하나에 머지하면 검사가 말해 줍니다.

$ git merge --no-commit --no-ff feature/profile-tagline
$ python manage.py makemigrations --check --dry-run
CommandError: Conflicting migrations detected; multiple leaf nodes in the migration graph:
  (0042_profile_tagline, 0042_profile_website in accounts).
To fix them run 'python manage.py makemigrations --merge'

$ python manage.py makemigrations --merge --noinput
Created new merge migration accounts/migrations/0043_merge_20260919_0324.py
    dependencies = [
        ('accounts', '0042_profile_tagline'),
        ('accounts', '0042_profile_website'),
    ]

두 번째 작성자가 자기 브랜치에서, 자기 환경에서, 아무도 귀찮게 하지 않고 그 --merge를 돌리면, 다음 env up이 자기 복제본 위에 0043을 적용합니다. (이 경우 git이 먼저 텍스트 충돌도 표시했습니다. 두 필드가 모델 파일의 같은 줄에 추가됐기 때문입니다. 현실적이고, 텍스트 충돌이 해소되기 전까지 마이그레이션 충돌을 가린다는 걸 알아 둘 가치가 있습니다.)

2. 마이그레이션은 이전 릴리스의 코드와 하위 호환됩니다. 배포 중에는 새 스키마와 옛 코드가 공존하는 창이 있고, 머신이 롤백되면 그 반대도 있습니다. 컬럼은 nullable이거나 기본값을 갖게 추가하고, 한 번에 이름을 바꾸지 않으며, 현재 릴리스가 여전히 읽는 것은 절대 드롭하지 않습니다. 추가하고, 배포하고, 백필하고, 코드를 바꾸고, 나중 릴리스에서 드롭합니다. expand and contract입니다. 여기서 더 중요한 이유는 일회용 환경이 배포를 잦게 만들어서 그 창 안에 더 자주 들어가기 때문입니다. 태그별 스테이징이 그걸 리허설하는 곳입니다.

3. CI는 빈 데이터베이스에 0부터 마이그레이션도 합니다. 템플릿 복제는 “내 마이그레이션이 현실적인 데이터에 적용되나"를 테스트합니다. 빈 실행은 “전체 체인이 여전히 무에서 되나"를 테스트하고, 이전 데이터 마이그레이션이 뭔가 채워 놨다고 가정한 마이그레이션을 잡습니다. 30초이고, 그러지 않으면 다음 새 노트북을 기다리는 부류의 버그를 잡습니다.

4. 스키마 변경에는 두 번째 눈이 붙습니다. 작은 팀에는 CODEOWNERS 파일이 필요 없지만, 규칙은 필요합니다. migrations/를 건드리는 PR은 머지 전에 팀원 하나가 리뷰하고, 리뷰어의 일은 SQL을 확인하는 게 아닙니다. 자기나 팀의 다른 누군가가 이번 2주 안에 같은 테이블을 건드리고 있는지 알고, 그렇다고 말하는 것입니다. 개발자가 열댓 명을 넘어가면 그 지식이 한 사람 머리에 다 들어가지 않으니, 그때는 migrations/에 CODEOWNERS 항목을 두는 게 제값을 합니다. 어떤 툴링도 이걸 대신하지 못합니다. 기계적인 건 툴링이 전부 잡아 주니 2분짜리 일이고, 옛 공유 환경 세계에서 간직할 가치가 있는 유일한 부분입니다. 두 사람이 곧 부딪힐 걸 알아차리는 순간.

버전 관리, URL이 무엇을 돌리는지 말해 주도록

#

공유 환경 하나일 때 “스테이징에 뭐 올라가 있어요"는 채팅으로 묻는 질문이었습니다. 여럿이면 환경의 속성이어야 하고, 아니면 모든 버그 리포트가 고고학으로 시작합니다.

• 모든 이미지는 커밋 SHA를 지니고 앱이 그걸 노출합니다. fly deploy --build-arg GIT_SHA=... --build-arg GIT_BRANCH=...가 이미지에 환경 변수로 찍고, /api/version/이 환경 이름, 리전과 함께 돌려줍니다(위 출력 참고). “feature-profile-tagl-fa8832에서 깨져요"에 누구나 제일 먼저 하는 일은 생각한 커밋을 돌리고 있는지 확인하는 것입니다. 첫 데모 환경은 툴링이 커밋되기 한 커밋 전의 작업 트리에서 배포됐고, 엔드포인트가 그렇게 말했습니다. 제가 예상한 SHA가 아니라 이전 커밋을 보고했죠.
• ENVIRONMENT=$ENV가 모든 로그 줄과 에러 트래커의 environment 태그에 있습니다. 브랜치 오류가 프로덕션 오류 추적을 더럽히지 않고, 클릭 한 번으로 걸러집니다.
• 브랜치는 SHA를, 릴리스는 태그를 갖습니다. feature-payments-retr-3f9a1c에는 버전 번호가 없습니다. 커밋이 있습니다. 스테이징과 프로덕션에는 v1.42.0이 있습니다.
• 모바일 앱은 URL이 아니라 최소 API 버전을 지닙니다. dev 메뉴의 URL 필드가 테스터가 실제 폰을 브랜치에 향하게 하는 방법이고, API 스키마 버전을 실은 버전 엔드포인트가 앱이 이해할 수 있는 상대와 통신하는지 아는 방법입니다.

이걸로 해결되지 않는 것

#

같이 있어야만 말이 되는 기능 둘은 해결하지 못합니다. 브랜치 환경은 브랜치 하나를 보여줍니다. 답은 둘 다 플래그 뒤에 머지하고 main을 보는 것이고, main을 따라가는 상시 환경 하나(main-dev.example.com, 머지마다 재배포)로 할 수 있습니다. 제가 남겨 둘 유일한 장수 비프로덕션 환경이고, 아무도 거기에 배포하지 않습니다. 다음 릴리스가 무엇이 될지 보는 용도입니다.

등록된 콜백을 요구하면서 와일드카드를 받지 않는 제공자는 해결하지 못합니다. 제가 쓰는 인증 서비스는 상위 도메인을 받으니 example.com이 모든 -dev 브랜치 호스트명을 덮습니다. 일부 OAuth와 결제 제공자는 안 되고, 그런 경우 Worker가 마지막으로 차지한 환경으로 라우팅하는 공유 호스트명 하나를 둡니다. 작은 것에 걸린 작은 락이고, 모든 것에 걸린 락보다 훨씬 낫습니다.

마이그레이션의 사람 쪽은 해결하지 못합니다. 툴링은 기계적 충돌을 잡습니다. 같은 2주 안에 둘이 같은 개념을 양립 불가능하게 모델링하는 건 잡지 못하고, 그걸 고치는 유일한 방법은 한 명이 알아차리는 마이그레이션 리뷰입니다.

당신의 환경에서 확인해 볼 것

#

공유 dev나 스테이징이 있고 그걸 예약하는 채팅 스레드가 있다면:

1. 완성된 브랜치가 작성자 아닌 누군가가 도는 걸 볼 수 있기까지 얼마나 기다립니까? 한 시간 넘으면 그 락 값을 전달 시간으로 치르고 있는 것이고, 작은 팀이면 팀의 상당 부분이 기다리는 겁니다.
2. 공유 데이터베이스는 얼마나 자주 초기화되고, 그때 누가 작업을 잃습니까?
3. 새 개발자가 첫날에 누구에게 아무것도 묻지 않고 자기 브랜치가 도는 공개 URL을 얻을 수 있습니까? 물어야 하는 것이 무엇이든, 그게 제일 먼저 자동화할 것입니다.
4. 새 환경은 현실적인 데이터에서 시작합니까? 빈 상태에서 시작하면, 처음으로 못 잡을 버그는 빈 테이블에서는 멀쩡하고 실제 테이블에서는 40분 걸리는 마이그레이션입니다.
5. 비프로덕션 호스팅에 모두가 잊고 한 달 뒤에도 여전히 존재할 것이 있습니까? 있다면 다른 무엇보다 먼저 스위퍼를 쓰세요. 누수는 첫날부터 시작됩니다.

채팅 스레드의 그 질문이 사라지는 건 사람들이 묻기를 그만둬서가 아니라, 답이 언제나 “네, 당신 것에서요"이기 때문입니다.

이 블로그의 검색 유입은 2년쯤 제자리이고, 이제는 움직이길 기대하지도 않습니다. 그래서 대신 방문자가 어디서 오는지, 그 안에 AI 어시스턴트도 있는지를 들여다봤습니다. 있긴 합니다. 간신히요. 2026년 9월 16일까지 열두 달 동안 방문 분석 도구가 센 세션은 5,372개였습니다. 그중 AI 어시스턴트에서 온 건 27개. chatgpt.com에서 12개, gemini.google.com에서 9개, Perplexity에서 6개, claude.ai에서는 하나도 없었습니다. 0.5퍼센트죠. 다만 ChatGPT에서 온 방문자는 좋은 쪽이었습니다. 직접 유입이 평균 27초, 구글이 3분 머무는 동안 이쪽은 평균 5분을 머물렀습니다. 이미 답을 읽고 자세한 내용을 보러 온 사람들이니까요.

그래서 작은 블로그가 그런 답변의 출처로 뽑히려면 뭐가 필요한지 시간을 좀 들여 봤습니다. 이 글은 제가 이 사이트에 한 일과, 로그가 그에 대해 뭐라고 하는지입니다. 숫자가 있는 곳에는 숫자를 적고, 추측인 곳은 추측이라고 밝히겠습니다. 초고에 있던 문장 세 개는 막상 들여다보니 틀린 것으로 드러났는데, 고친 흔적은 그대로 남겨 뒀습니다.

봇은 두 종류이고, 인용하는 쪽은 하나뿐입니다

#

먼저 짚고 갈 것은 “AI 봇"이라는 게 사실 서로 다른 유저 에이전트를 쓰는 두 가지 다른 일이고, 한쪽을 막아도 다른 쪽에는 아무 영향이 없다는 점입니다.

학습용 크롤러는 다음 모델을 만들려고 페이지를 대량으로 긁어 갑니다. OpenAI는 GPTBot, Anthropic은 ClaudeBot이고, 구글은 Google-Extended 토큰으로, 애플은 Applebot-Extended로 제어하며, Common Crawl의 CCBot은 공개 데이터셋 대부분에 들어갑니다. 이들이 가져간 건 가중치가 되어 끝이고, 여러분에게 돌아오는 링크는 없습니다. 이쪽을 막아야 한다는 주장에는 일리가 있고, 저도 터무니없는 얘기라고는 생각하지 않습니다.

검색용 봇은 다른 종류입니다. 누군가 ChatGPT나 Claude, Perplexity에 질문하면 어시스턴트는 검색을 돌리고, 그 자리에서 페이지 몇 개를 가져와 읽은 다음, 인용을 달아 답을 씁니다. 그 요청은 OAI-SearchBot과 ChatGPT-User, Claude-SearchBot과 Claude-User, PerplexityBot과 Perplexity-User로 들어옵니다. 구글의 AI 오버뷰는 그냥 Googlebot을 쓰기 때문에 따로 끌 스위치 자체가 없습니다. 방문자를 돌려보내 주는 건 이쪽 봇들입니다. 목표가 인용되는 거라면 최적화 대상은 이쪽이고, GPTBot을 막아도 ChatGPT 검색 결과에는 어느 방향으로도 아무 영향이 없다는 건 알아 둘 만합니다.

이 사이트의 robots.txt는 Hugo 기본값 그대로, 전부 허용입니다.

User-agent: *
Allow: /
Sitemap: https://jared.lynskey.co.nz/sitemap.xml

검색용 봇은 들이고 학습용은 막는 식으로 나눌까 생각해 봤지만, 읽히는 게 존재 이유의 전부인 블로그에서 그럴 만한 가치는 없다고 결론 내렸습니다. 굳이 하자면 아래 블록처럼 될 겁니다. 이걸 보여 드리는 이유는 Cloudflare가 Googlebot에게 빈 페이지를 내줬다에서와 같은 교훈 때문입니다. 목록에는 회사가 아니라 봇 이름을 적어야 합니다. “OpenAI"라고 쓸 수 있는 줄은 없습니다.

User-agent: GPTBot
User-agent: ClaudeBot
User-agent: Google-Extended
User-agent: Applebot-Extended
User-agent: CCBot
Disallow: /

User-agent: *
Allow: /

사이트가 Cloudflare 뒤에 있다면 확인할 게 하나 있습니다. 2025년 중반부터 거기서 새로 만드는 존은 기본으로 AI 크롤러를 막고, 봇 설정에는 기존 존에도 같은 걸 적용하는 원클릭 토글이 있습니다. 두 종류를 다 막습니다. 이 블로그는 지난주에 Cloudflare Pages로 옮겼기 때문에 이것도 제 확인 목록에 있었습니다. “AI 봇"이라는 말이 막아야 할 무언가처럼 들려서 켰다면, 인용도 같이 꺼 버린 겁니다. 그 뒤로 Cloudflare는 자기가 관리하는 robots.txt 파일에 search, ai-input, ai-train 플래그를 따로 둔 Content-Signal 줄을 쓰기 시작했습니다. 아무도 지킬 의무는 없지만 어휘는 제대로 골랐습니다. 위와 같은 구분을 벽이 아니라 선호로 표현한 거니까요.

실제로 문을 두드리는 건 누구인가

#

Cloudflare로 옮긴 데는 부수 효과가 하나 있었습니다. 처음으로 모든 요청을 유저 에이전트별로 볼 수 있게 된 겁니다. 2026년 9월 13일부터 16일까지 나흘 동안 들어온 건 아래와 같습니다. 가짜는 걸러낸 숫자인데, 그 얘기는 곧 하겠습니다.

눈에 띄는 게 두 가지 있습니다. 검색용 봇이 페이지 수십 개를 읽는 사이 학습용 크롤러는 전부를 두 번씩 읽었습니다. 그리고 검색용 봇은 아무거나 가져가지 않습니다. ChatGPT-User와 Claude-User 둘 다 이 사이트에서 가장 구체적인 글인 업데이트 서버 글을 집어 갔고, 콜드 스타트 글은 일본어판으로 가져갔습니다.

이제 가짜 얘기입니다. GPTBot이라고 주장한 요청 20개 중 18개는 OpenAI가 공개한 IP 대역 밖에서 왔고, /.env, /.git/HEAD, /firebase-adminsdk.json을 달라고 했습니다. “ChatGPT-User” 요청 36개 중 15개도 같은 부류였습니다. “PerplexityBot” 트래픽은 대부분 /id_ed25519를 원했습니다. 유저 에이전트는 누구나 보낼 수 있는 문자열이고, 취약점 스캐너들은 AI 봇 이름을 달면 그냥 통과된다는 걸 눈치챘습니다. OpenAI, Anthropic, Perplexity 모두 IP 대역을 공개합니다. 봇을 어느 방향으로든 특별 취급할 거라면 이름이 아니라 주소를 확인해야 합니다. 위 표의 20, 59, 8은 제대로 된 주소에서 온 요청만 센 숫자입니다.

페이지는 브라우저 없이도 읽혀야 합니다

#

검색용 봇은 답변하는 그 시점에 타임아웃을 걸고 페이지를 가져오며, 대부분 JavaScript를 실행하지 않습니다. 번들이 로드되기 전까지 빈 div인 페이지는 그들이 읽지 않는 페이지입니다. Hugo는 완성된 HTML을 써 주니 이 블로그는 그걸 공짜로 얻고, 제가 더 영리한 무언가로 옮기고 싶었던 적이 한 번도 없는 주된 이유이기도 합니다. 제가 운영하는 마켓플레이스는 정반대 경우인 React Native 웹앱이라, 크롤러에게 제대로 된 문서를 주기까지 동적 렌더링 분기가 하나 필요했고, 그다음엔 그걸 조용히 되돌려 버린 캐싱 버그가 있었습니다. 위의 Cloudflare 글이 그 이야기입니다.

속도도 같은 식으로 셈에 들어가는데, 여기서 로그가 저를 바로잡았습니다. Cloudflare 뒤에 있는 정적 사이트는 가장 가까운 엣지에서 나간다고 넘겨짚고 있었거든요. 아닙니다. 이 블로그는 Cloudflare Pages에 있고, HTML은 캐시되지 않은 채 나가며, 서울에서 요청하면 응답이 로스앤젤레스에서 0.5초쯤 걸려 돌아옵니다. 타임아웃이 몇 초인 봇에게는 그래도 충분하지만, 제가 장담했을 법한 수십 밀리초는 아니고, 이걸 아는 것도 직접 재 봤기 때문입니다. 페이지 여섯 개로 답을 짜는 어시스턴트는 3초 걸리는 하나를 그냥 버립니다. 버렸다고 말해 주지도 않습니다.

문단 하나를 그대로 떼어 갈 수 있게 쓰기

#

이 시스템들이 페이지를 쓰는 방식은 독자가 읽는 방식과 다릅니다. 페이지를 청크로 쪼개고, 청크마다 질문에 대해 점수를 매기고, 점수가 나오는 것을 인용합니다. 800단어에 걸쳐 요점을 향해 쌓아 올라가는 글은 모든 청크에서 점수가 낮습니다. 섹션마다 첫 문장에서 주장을 말하고 그다음에 뒷받침하는 글은 질문에 맞는 섹션에서 점수를 냅니다.

이게 어떤 기술적인 것보다 제가 여기 글을 쓰는 방식을 많이 바꿨습니다. 프런트매터의 description은 이제 읽어 보라고 낚는 문구가 아니라 글이 말하는 내용의 요약입니다. 어시스턴트가 보여 주는 게 description뿐인 경우가 많거든요. 섹션 제목은 그 섹션이 내리는 결론을 말합니다. 숫자는 차트가 아니라 단위와 함께 문장 안에 들어갑니다. 날짜는 풀어서 씁니다. 1년 뒤에 이 페이지를 읽는 모델에게 “지난주"는 아무 뜻도 없으니까요. 그리고 글 하나는 한 가지에 대해서만 씁니다.

나머지 절반은 인용할 만한 게 있느냐인데, 여기서는 데이터가 엇갈립니다. 로그를 보면 답변 시점에 봇이 가져가는 페이지는 구체적인 글들입니다. 콜드 스타트, 업데이트 서버, iOS 디버깅. 네이버 크롤러는 Yeti이고 다음 크롤러는 Daumoa다, 제가 쓰는 호스팅의 재시작은 504가 나는 30초짜리 구간이다, Cloudflare의 실시간 Brotli 압축은 제 번들에서 gzip보다 나쁘게 측정됐다. 이런 사실은 적혀 있는 곳이 많지 않아서, 그중 하나가 필요한 질문은 여기로 옵니다. 그런데 어시스턴트에서 클릭해 들어오는 사람들은 대부분 2023년과 2024년에 쓴 관리에 대한 글에 내려앉습니다. 글마다 한두 세션씩요. 구체적인 글은 기계가 읽고, 일반적인 글은 클릭을 받습니다. 이걸 깔끔하게 설명할 방법이 저한테는 없고, 지어내느니 그대로 보고하는 편을 택하겠습니다. 지렛대가 있다면 그건 여전히, 이번 주에 알아냈는데 검색했을 때는 찾을 수 없었던 그 구체적인 것을 적어 두는 겁니다. 기계가 실제로 읽는 건 그쪽이라는 게 로그에 보이니까요.

누가 썼는지 밝히고, 계속 같은 말을 하기

#

페이지를 인용할지 결정하는 어시스턴트는 꼼꼼한 독자가 하는 것과 비슷한 일을 합니다. 누가 썼고, 언제 썼고, 내가 찾은 다른 것들과 맞아떨어지는가? 이 사이트에서 그 부분의 기계적인 처리는 대부분 테마가 해 줍니다. 모든 글에 저자, 게시일, 수정일이 든 Article 구조화 데이터가 붙고, 저자는 같은 공개 프로필들로 링크된 Person입니다. 템플릿 몇 줄이지만 “페이지 하나"와 “이력이 있는 특정 사람이 쓴 페이지"의 차이가 거기서 납니다.

테마가 해 주지 않는 부분은 일관성입니다. 소개 페이지, llms.txt, 공개 프로필, 모든 글 맨 위의 한 줄이 전부 같은 사람을 같은 경력으로 설명합니다. 뭔가 바뀌면 전부 바꿔야 하고, 아니면 깜빡한 하나가 틀린 하나가 됩니다. 까다롭게 들리지만, 한 페이지는 제가 엔지니어링 매니저라고 하고 다른 페이지는 프리랜서라고 하는 건 모델이 얼버무리거나 다른 사람을 고르게 만드는 바로 그런 종류의 모순입니다.

수정일도 정직해야 합니다. 내용이 바뀔 때 바뀌고, 그 외에는 손대지 않습니다. 신선해 보이려고 날짜를 올리는 건 한 번은 통하고 그다음엔 도메인 전체가 평가절하되는 종류의 일입니다.

llms.txt란 무엇인가, 그리고 아무것도 읽지 않는다는 사실

#

llms.txt는 2024년 9월에 나온 제안으로, 사이트 루트에 언어 모델에게 사이트 요약과 골라 놓은 링크 목록을 주는 Markdown 파일을 두자는 겁니다. 저는 올해 2월에 하나 추가했습니다. 제가 누구인지 한 문단, 그다음 관리, 인프라, 모바일, 커뮤니티 섹션이 있고, 글마다 제목, URL, 그 글이 내리는 결론 한 문장으로 된 한 줄이 있습니다. 바쁜 사람을 위해 쓴 목차처럼 읽힙니다.

단서는, 아무것도 이 파일을 읽지 않는다는 겁니다. 제가 가진 나흘치 로그에서 /llms.txt 요청은 제가 보낸 것뿐이었습니다. Common Crawl은 2026년 8월 크롤에서 이 사이트의 페이지 76개를 담아 갔지만 그 파일은 한 번도 가져가지 않았습니다. 주요 어시스턴트 중 이 파일을 읽는다고 밝힌 곳도 없습니다. 그러니 여기 있는 뭔가가 인용되는 이유가 이 파일은 아니고, 그런 이유로 누군가에게 권하는 것도 삼가겠습니다. 그래도 두 가지 이유로 두고 있습니다. 한 시간 들었는데, 글마다 실제로 뭘 결론 내리는지 한 문장씩 쓰는 일이 파일 자체보다 값어치가 있었습니다. 어떤 글이 아무것도 결론 내리지 않는지 보여 줬거든요. 그리고 사이트가 뭘 위한 곳인지 기계에게 말해 주는 유일한 페이지라서, 필요 없더라도 있는 편이 낫습니다. 손으로 쓰다 보니 깜빡해서 그 뒤로 어긋나긴 했는데, 그게 Hugo 출력 포맷으로 프런트매터에서 생성하자는 쪽의 논거입니다. 할 일 목록에 있습니다.

피드, 사이트맵, 그리고 다섯 개 언어

#

재미없는 기본 설비도 여전히 중요합니다. 크롤러가 올라간 당일에 새 글을 찾는 건 사이트맵을 통해서고, 글이 바뀐 걸 아는 건 RSS를 통해서입니다. 둘 다 Hugo 기본값이라 신경 써 본 적이 없습니다. ClaudeBot은 이틀 동안 사이트맵을 36번 읽었고, 페이지 1,380개를 그렇게 빨리 찾아낸 것도 그 덕입니다.

언어는 중요할 거라고 예상하지 못했던 부분입니다. 여기 있는 건 전부 영어, 일본어, 한국어, 중국어 간체, 베트남어로 있고, 크롤러가 같은 글이라는 걸 알 수 있도록 alternate 링크가 붙어 있습니다. 크롤러는 이걸 사이트 다섯 개로 취급합니다. ClaudeBot의 크롤은 다섯 언어에 거의 고르게 나뉘었고, Common Crawl이 8월에 가져간 글 페이지 73개 중 영어판은 네 개뿐이었습니다. 어시스턴트는 질문받은 언어로 답하고 그 언어로 된 출처를 선호하기 때문에, 콜드 스타트에 대한 한국어 질문은 영어 페이지를 즉석에서 번역한 것이 아니라 한국어 페이지로 답할 수 있고, ChatGPT가 실제로 가져간 것도 일본어 페이지였습니다. 조건은 번역이 그 언어로 쓴 것처럼 읽혀야 한다는 겁니다. 올해 초에 원어민 검토를 받아 가며 한 번 손본 건 사람 독자를 위해서였지만, 베트남어 페이지가 구경거리가 아니라 출처가 되는 것도 그 덕입니다.

측정할 수 있는 것

#

추측을 그만두고 나니 생각보다 많았습니다. Cloudflare 무료 플랜은 유저 에이전트와 경로별 요청 로그를 한 번에 하루치씩 조회하게 해 주는데, 위의 봇 표는 거기서 나왔습니다. 리퍼러는 유료 플랜이 필요합니다. 리퍼러는 방문 분석 도구에 있고, 대시보드를 눈 찌푸리고 들여다보는 대신 리포트 API로 뽑아낸 게 맨 위의 숫자들입니다. 둘을 합치면 윤곽이 보입니다. 나흘 동안 검색용 봇은 OpenAI와 Anthropic 주소에서 페이지 90개쯤을 가져갔습니다. 지난 한 달 동안 ChatGPT에서 건너온 사람은 두 명입니다. 많이 읽히고, 가끔 인용되고, 클릭은 드물게. 페이지를 썼는데 클릭은 안 된 답변을 볼 방법은 여전히 제가 아는 한 없습니다. 가장 유용한 확인은 여전히 수동입니다. 내 글이 답하는 질문을 어시스턴트에게 물어보고 누구 페이지를 인용하는지 보는 거죠.

이 중에 하나만 남겨야 한다면 글쓰기 규칙입니다. robots.txt, 구조화 데이터, llms.txt는 오후 한나절 일이고 그러면 끝납니다. 섹션마다 주장을 먼저 말하도록 쓰는 것, 일반적인 것 대신 구체적인 것에 대해 쓰는 것은 습관이고, 페이지가 인용할 가치가 있는지를 결정하는 건 그 습관입니다. 두 번째는 주장하기 전에 재 보는 겁니다. 기계에게 신뢰받는 건 알고 보면 사람에게 신뢰받는 것과 많이 닮았습니다. 내가 누구인지 말하고, 내가 아는 걸 말하고, 매번 같은 방식으로 말하는 것.

얼마 전까지 제가 만드는 마켓플레이스 앱의 웹 쪽 변경은 전부 Django API 변경과 똑같은 길로 나갔습니다. Docker 이미지를 빌드하고, 푸시하고, Fly.io의 머신 전부에 롤링 배포하는 식이었죠. 웹 프론트엔드(모바일 앱의 웹 export와 정적 사이트 생성기가 만드는 마케팅 페이지)가 API 옆에 이미지로 복사되어 있었기 때문에 다른 방법이 없었습니다. CSS 수정 하나에 7분쯤 걸리고 머신 11대가 재시작됐습니다. 8월 어느 날은 이걸 여섯 번 했습니다.

이 글은 그걸 무엇으로 바꿨는지 순서대로 따라갑니다. 배포 스크립트가 프론트엔드 트리 둘을 빌드하고, 버전 붙은 경로 아래 오브젝트 스토리지에 올리고, 포인터 객체 하나를 바꾸고, 머신 전부가 새 버전을 서빙할 때까지 기다린 다음, Cloudflare 캐시를 API로 퍼지합니다. 반대편에서는 Django가 요청마다 포인터를 읽어 거기 적힌 버전을 서빙합니다. API는 아예 재시작하지 않습니다.

예전 방식이 왜 문제였나

#

가장 큰 비용은 재시작이었습니다. 머신 11대가 롤링된다는 건 콜드 부팅 11번이라는 뜻이고, 공유 CPU에서 Django가 뜨는 데 13초 정도 걸리는데 그중 7초는 그냥 Django를 import하는 시간입니다. 실제 방문자가 그 비용을 치르지 않도록 배포 스크립트 끝에 머신 전부를 한 번씩 찍는 워밍업 단계를 뒀는데, 결국 모든 웹 릴리스가 가장 느린 머신을 기다리는 걸로 끝났습니다. 그 콜드 부팅이 Fly.io에서 얼마나 비싼지는 0으로 스케일 다운, 그리고 재시작마다 30초짜리 장애에 따로 써 뒀습니다. 요약하면 재시작 하나하나가 방문자가 504를 받을 수 있는 구간이라서, 아무것도 재시작하지 않는 배포 경로는 웹 릴리스에서 그 구간을 아예 없애 줍니다.

두 번째 문제는 정적 사이트 출력물이 둘로 갈라져 있었다는 겁니다. HTML은 이미지에 들어갔지만 RSS 피드와 검색 인덱스는 바로 버킷으로 갔습니다. 같은 소스에서 빌드되긴 하는데 같은 시점은 아니라서 서로 어긋날 수 있었고, 어긋나기 전까지는 아무도 몰랐습니다.

세 번째는 습관에 가깝습니다. 릴리스 한 번에 7분과 재시작이 들면 작은 릴리스를 안 하게 됩니다. 수정 서너 개를 하나씩 내보내는 대신 쌓아 두게 되고, 그게 바로 한 줄짜리 변경이 망가진 무언가와 함께 나가는 방식이죠.

버킷 구조

#

전부 S3 호환 버킷 안 web/ 경로 아래에 있습니다.

web/current                              ← a text file containing one version string
web/a1b2c3d-20260914021500/manifest.json ← every file in this version
web/a1b2c3d-20260914021500/app/...       ← the app's web export
web/a1b2c3d-20260914021500/site/...      ← the static site's output
web/9f8e7d6-20260912093012/...           ← the previous version, still there

버전은 짧은 git SHA에 UTC 타임스탬프를 붙인 것이라 어떤 커밋이 언제 올라갔는지 바로 읽힙니다. 릴리스가 라이브로 갈 때 바뀌는 건 web/current 하나뿐입니다.

배포 스크립트가 하는 일

#

전체가 스크립트 하나이고, 저장소 루트에서 실행합니다. 순서대로:

1. 더러운 트리는 거부합니다. 제일 먼저 git status --porcelain을 돌리고 뭔가 나오면 종료합니다. 디스크에 있는 게 그대로 올라가는데, 예전 마케팅 사이트 배포 스크립트가 그렇게 커밋 안 된 문구를 내보낸 적이 있거든요. 뭘 하는지 알고 쓰는 경우를 위한 우회 플래그가 있지만 아직 써 본 적은 없습니다. 그다음 git rev-parse --short HEAD와 현재 시각으로 버전 문자열을 만듭니다.

2. 두 트리를 빌드합니다. 앱은 프로덕션 API와 WebSocket URL을 박아 넣고 웹 export를 돌린 다음, Brotli 사전 압축을 합니다. 사전 압축은 설명할 가치가 있습니다. Cloudflare가 실시간으로 Brotli 압축을 해 주긴 하는데 낮은 품질 레벨이라, 이 번들에서는 gzip보다 오히려 나빴습니다(1.66MB 대 2.04MB). 빌드 시점에 품질 11로 한 번만 압축하면 1.28MB가 되기 때문에, 스크립트가 1KB 넘는 JS, CSS, JSON 파일마다 .br 쌍둥이를 옆에 써 둡니다. 마케팅 사이트는 정적 사이트 생성기를 minify 옵션을 켜고 돌립니다.

3. 업로드합니다. 빌드 디렉터리 두 곳을 훑어서 모든 파일을 스레드 16개로 web/<version>/app/...와 web/<version>/site/...에 올립니다. 객체마다 파일명에서(.br을 먼저 떼고) 추측한 Content-Type을 붙이고, Brotli 쌍둥이에는 Content-Encoding: br도 붙입니다. 파일이 전부 올라간 뒤에야 상대 경로 목록 두 개가 담긴 JSON인 manifest.json을 씁니다. 이 순서가 중요합니다. Django 쪽은 매니페스트 없는 버전을 존재하지 않는 것으로 취급하기 때문에, 반쯤 올라간 버전은 절대 현재 버전이 될 수 없습니다. 지금은 파일 수백 개이고 업로드에 6초 정도 걸립니다.

4. 포인터를 바꿉니다. put_object 한 번으로 web/current에 버전 문자열을 씁니다. 그게 릴리스입니다.

5. 머신들을 기다립니다. API 머신마다 포인터를 5초 캐시하니까, 바꾼 직후 잠깐은 일부가 아직 옛 버전입니다. 스크립트는 API의 버전 엔드포인트를 0.5초마다 폴링하면서 새 버전을 담은 연속 응답을 셉니다. Fly가 머신 전체에 부하를 분산하므로 일치하는 응답이 16번 연속(머신 수보다 많이) 나오면 전부 포인터를 다시 읽었다고 판단합니다. 옛 응답이 하나라도 오면 카운트가 리셋됩니다. 90초 뒤엔 포기하고 직접 확인하라고 알려 줍니다. 첫 실제 전환이 30초 조금 넘게 걸려서 제한을 더 낮추지 않았습니다.

6. Cloudflare를 퍼지합니다. API 호출 한 번이고, 아래에서 다룹니다. 실패하면 경고를 찍고 계속 갑니다.

7. 팀 채팅에 올립니다. 런타임 에러 알림이 쓰는 웹훅에 버전과 실행한 사람을 한 줄로 보냅니다. 에러가 몰려올 때 방금 뭐가 바뀌었는지 대조해 볼 수 있게요. 롤백은 주황색으로 올라갑니다.

처음부터 끝까지 릴리스 한 번에 1분 조금 넘게 걸리고, 대부분은 웹 export 시간입니다.

Django 쪽

#

프론트엔드를 서빙하는 건 원래부터 Django였습니다. API가 아닌 URL은 전부 해당 라우트의 웹 export에서 프리렌더된 페이지로 응답하고, 마케팅·개인정보처리방침·지원 페이지는 정적 사이트 출력물에서 옵니다. 이 뷰들은 예전엔 디스크의 파일을 열었습니다. 지금은 버킷을 아는 작은 레이어 하나를 거쳐서 읽습니다.

요청마다 세 가지를 풉니다. 현재 버전(web/current에서 읽고 5초 캐시), 그 버전의 매니페스트(그 버전이 현재인 동안 캐시), 그리고 파일 자체(파일 본문을 담는 작은 인메모리 LRU라서 페이지 HTML과 메인 번들은 메모리에 남습니다). 404가 싼 이유가 매니페스트입니다. 경로가 목록에 없으면 버킷에 물어보지 않고 없다고 답합니다. 클라이언트가 Brotli를 받으면 .br 쌍둥이 파일을 대신 읽고 인코딩 헤더를 붙입니다. 에셋은 파일명에 콘텐츠 해시가 있으니 1년짜리 immutable 캐시 헤더를 달고 나갑니다. 라우트를 프리렌더된 페이지에 매핑하는 테이블처럼 파일 목록에서 나오는 것들도 버전별로 캐시되기 때문에, 새 배포가 나가면 첫 요청에서 다시 만들어지고 그 전에는 안 만듭니다.

그리고 배포 스크립트가 폴링하는 엔드포인트가 있습니다.

def web_version(request):
    # bundle: the layer that reads web/current and the manifest
    response = JsonResponse({"source": bundle.source(), "version": bundle.version()})
    response["Cache-Control"] = "no-store"
    return response

이 엔드포인트는 프로덕션에서는 bucket:<version>을, 이미지에서 서빙 중이면 filesystem을 답합니다. Fly 머신마다 자기 자신에 대해 답하기 때문에 열두 번쯤 찍어 보면 전체가 수렴했는지 알 수 있습니다. 뭔가 이상해 보일 때 어떤 머신이 뭘 라이브라고 생각하는지 확인하는 가장 빠른 방법이기도 합니다.

Cloudflare 캐시를 API로 퍼지하기

#

사이트의 HTML은 Cloudflare 엣지에 5분간 캐시됩니다. 퍼지를 안 하면 배포는 머신에 올라가 있는데 대부분의 방문자는 최대 5분 동안 옛 페이지를 계속 받게 되니, 애초 목적이 무색해집니다.

퍼지는 API 호출 한 번입니다.

urllib.request.Request(
    f"https://api.cloudflare.com/client/v4/zones/{zone}/purge_cache",
    data=json.dumps({"hosts": ["example.com", "www.example.com"]}).encode(),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)

페이지를 일일이 나열하지 않으려고 URL이 아니라 호스트 단위로 퍼지합니다. 에셋은 퍼지할 필요가 아예 없습니다. 파일명에 콘텐츠 해시가 붙어 있어서 새 빌드는 새 파일명을 가리키고 옛 파일은 그냥 참조되지 않게 되니까요. 그 파일명을 참조하는 HTML만 새로 고치면 됩니다.

스크립트가 퍼지 전에 머신을 기다리는 건 일부러 그런 겁니다. 먼저 퍼지하면 Cloudflare가 아직 옛 버전인 머신에서 캐시를 다시 채울 수 있고, 그 페이지가 엣지에 5분 더 앉아 있게 됩니다.

퍼지가 실패하면 스크립트는 경고를 찍고 그래도 끝까지 갑니다. 캐시는 5분 안에 알아서 만료되니 최악의 경우라도 느린 릴리스이지 망가진 릴리스는 아닙니다. 마지막 단계에서 배포가 중단되는 것보다는 그편이 낫습니다.

라이브 전에 빌드 확인하기

#

플립 없이 돌리는 모드는 3단계까지만 하고 멈춥니다. 버전은 버킷에 있는데 아무도 서빙하지 않는 상태죠. 확인할 때는 머신 한 대에 환경 변수를 하나 설정하는데, 그러면 web/current가 뭐라고 하든 그 머신은 그 빌드에 고정됩니다. 괜찮아 보이면 롤백 명령으로 현재 버전으로 만듭니다. 이름은 롤백이지만 실제로는 “current를 이 버전으로 가리켜라"이고, 앞으로 가나 뒤로 가나 같은 동작입니다.

롤백

#

옛 버전은 버킷에 남아 있으니, 롤백은 같은 명령에 이전 버전을 주면 되고 목록 명령이 최신순으로 뭐가 있는지 보여줍니다. 앞으로 가는 배포와 똑같이 기다리고 퍼지합니다. 아직 써 본 적은 없습니다. 지금은 옛 버전을 지우는 건 아무것도 없는데, 작기도 하고 없는 것보다 있는 편이 낫습니다.

그대로인 것

#

API는 여전히 자체 배포 스크립트로 예전 방식대로 배포하고, 그래야 합니다. 상태가 있고 마이그레이션이 실행되는 곳이니까요. Dockerfile도 여전히 프론트엔드 빌드 두 개를 이미지에 복사합니다. 이건 의도한 겁니다. 버킷 설정이 없거나(로컬 개발, 테스트 스위트) 버킷을 읽을 수 없으면 서빙 레이어가 디스크의 그 디렉터리로 넘어가기 때문에, 스토리지 장애가 나도 방문자는 에러 페이지 대신 마지막 이미지에 실려 나간 프론트엔드를 받습니다. 버킷을 잠시 빼야 할 일이 생기면 환경 변수 하나로 프로덕션에서 그 동작을 강제할 수 있습니다.

프론트엔드는 API보다 훨씬 자주 바뀌고, 이제 릴리스 한 번에 7분이 아니라 1분쯤 걸립니다. 애쓰지 않았는데도 모아서 배포하는 버릇이 없어졌습니다.

제가 만드는 마켓플레이스 앱은 React Native Web으로 만든 싱글 페이지 앱입니다. 모든 리스팅 페이지는 자바스크립트가 실행되기 전까지 스크립트 태그 하나와 빈 div일 뿐입니다. 사람에게는 아무 문제가 없지만 검색에는 치명적입니다. 구글은 그 JS를 실행할 때도 있지만, Bing은 하지 않고, 리스팅이 거의 다 한국어인 사이트에 가장 중요한 네이버 크롤러는 확실히 하지 않습니다.

이 글은 그 페이지들을 보이게 만든 과정과, 그다음에 제가 예상하지 못한 방식으로 그걸 되돌려버린 캐싱 규칙에 대한 이야기입니다.

클로킹이 아닌 다이내믹 렌더링

#

해결책은 오래됐고 구글도 인정하는 방식입니다. 크롤러를 감지해서, SPA가 그렸을 바로 그 콘텐츠를 담은 서버 렌더링 HTML을 내주는 것. 다른 콘텐츠가 아니라, 같은 콘텐츠를 더 일찍.

그래서 /listings/view?id=... 같은 리스팅 URL은 분기합니다. 브라우저는 SPA 셸을 받습니다. 크롤러는 진짜 문서를 받습니다. 제목, 리스팅의 핵심 정보, alt 텍스트가 붙은 사진별 이미지, 본문 발췌, 그리고 이 페이지가 고아가 되지 않도록 관련 리스팅 몇 개로 가는 링크까지.

마지막 항목이 생각보다 훨씬 중요했습니다. 내부 링크가 생기기 전에는 리스팅 페이지 약 1,000개를 가리키는 것이 아무것도 없었고, 서치 콘솔에서 크롤이 하루 7~11회로 가라앉는 게 보였습니다. 페이지를 찾지 못하는 크롤러는 그 페이지가 얼마나 좋은지 신경 쓰지 않습니다.

함정: 벤더 이름은 그 회사 봇의 이름이 아니다

#

크롤러 감지는 user-agent 매칭이고, 바로 여기서 발목을 잡혔습니다.

한국 플랫폼들은 회사 이름과 전혀 닮지 않은 이름으로 크롤링합니다. 네이버의 크롤러는 Yeti. 다음은 Daumoa. 카카오의 링크 스크래퍼는 kakaotalk-scrap. 셋 중 어느 것도 벤더 이름이 아닙니다.

한편 같은 벤더들이 인앱 브라우저를 탑재한 앱을 내놓고, 그 브라우저는 진짜 브라우저 UA 뒤에 앱 이름을 붙여 보냅니다. 카카오톡 인앱 브라우저는 KAKAOTALK/10.5.1이라고 말합니다. 카카오의 스크래퍼는 kakaotalk-scrap/1.0이라고 말하고요.

kakao로 매칭하면 둘 다 걸립니다. 제가 정확히 그렇게 했고, 그래서 링크를 연 카카오톡·네이버앱·다음앱 사용자 전원이 크롤러 페이지를 받았습니다. 자바스크립트도, 내비게이션도, 로그인도 없는 페이지를요. 문서로서는 훌륭하고, 사람에게는 완전히 쓸모없는.

해결책은 순서 규칙이고, 규칙으로 적어둘 만합니다.

import re

# 인앱 브라우저는 평범한 브라우저 UA 뒤에 앱 이름을 붙인다.
INAPP_BROWSER_RE = re.compile(r"kakaotalk/|naver\(inapp|daumapps", re.I)

# 벤더가 아니라 봇 이름으로 매칭한다. 네이버는 Yeti, 다음은 Daumoa,
# 카카오의 링크 미리보기 스크래퍼는 kakaotalk-scrap.
CRAWLER_RE = re.compile(r"googlebot|bingbot|yeti/|daumoa|kakaotalk-scrap", re.I)


def is_crawler(user_agent: str) -> bool:
    # 인앱 브라우저는 절대 크롤러가 아니다. 그래서 이 검사가 먼저 온다.
    if not user_agent or INAPP_BROWSER_RE.search(user_agent):
        return False
    return bool(CRAWLER_RE.search(user_agent))

인앱 브라우저를 먼저 검사하고, 그쪽이 이깁니다. 그리고 모든 크롤러 토큰은 벤더가 아니라 봇을 지목해야 합니다.

그다음 앞단에 Cloudflare를 놓았다

#

오리진은 시드니에 있는 공유 CPU 머신 한 대이고, 초당 20~30 요청을 감당합니다. Googlebot이 걸어야 할 URL은 약 995개입니다. 그 전부가 시드니까지 도달하고 있었습니다. 모든 URL에서 cf-cache-status가 DYNAMIC이었기 때문입니다. Cloudflare는 규칙이 시키지 않으면 HTML을 캐싱하지 않습니다. 존의 약 16%만 캐싱되고 있었고, 정작 중요한 부분은 하나도 포함되지 않았습니다.

그래서 크롤러 페이지에 캐시 규칙을 걸었습니다. 간단한 일이죠. 리스팅 URL의 본문이 하나가 아니라는 점만 빼면. 본문은 셋입니다.

• HTML을 요청하는 크롤러는 서버 렌더링 페이지를 받습니다.
• 사람은 SPA 셸을 받습니다.
• Accept: text/markdown을 보내는 에이전트는 데이터베이스에서 만든 마크다운을 받습니다. 빈 HTML 셸을 변환해봐야 빈 문서가 나올 뿐이니까요.

오리진은 Vary: Accept를 보내고, user-agent에 대한 Vary는 어차피 가망이 없습니다. 그리고 제가 몰랐던 게 여기 있습니다.

Cloudflare는 HTML에서 Vary를 무시합니다. 세 본문이 하나의 캐시 키를 공유합니다.

먼저 도착한 본문이 그 URL을 차지하고, 해당 엣지 위치의 이후 모든 방문자에게 오리진의 s-maxage가 허용하는 한 시간 동안, 거기에 stale-while-revalidate 하루를 더해 그대로 나갑니다.

프로덕션에서 양방향으로 다 목격했습니다.

• 네이버앱 사용자가 크롤러 페이지로 리스팅 URL을 워밍했고, 그다음 평범한 아이폰 사파리가 HIT으로 그 페이지를 받았습니다. 자바스크립트 없는 문서를 들여다보는 사람이 된 거죠.
• 사람이 SPA 셸로 URL을 워밍했고, Googlebot이 빈 셸을 받았습니다. SEO 작업 전체가 막으려던 바로 그 실패가, 이제 더 빠르게 엣지에서 제공된 겁니다.

좁혀서 고치는 규칙

#

Cloudflare가 HTML에서 Vary를 존중하게 만들 수는 없습니다. 대신 할 수 있는 건, 세 본문 중 하나만 캐시에 들어갈 자격을 갖게 만드는 것입니다.

(starts_with(http.request.uri.path, "/listings/")
 and not any(http.request.headers["accept"][*] contains "text/markdown")
 and (lower(http.user_agent) contains "googlebot" or ...)
 and not (lower(http.user_agent) contains "kakaotalk/" or ...))

크롤러 UA만 매칭하고, 마크다운 요청은 제외합니다. 이제 사람의 요청은 어떤 규칙에도 매칭되지 않으므로 예전처럼 DYNAMIC을 읽고 오리진으로 갑니다. 캐시를 읽고 쓰는 건 크롤러 요청뿐이고, 거기 들어갈 수 있는 본문은 크롤러용 하나뿐입니다.

엣지 TTL은 respect_origin입니다. 수명은 대시보드에 박히는 대신 페이지를 렌더링하는 코드가 계속 소유합니다.

놓치기 쉬운 운영 디테일 하나. 규칙을 좁힌다고 이미 캐시에 있는 것이 사라지지는 않습니다. 퍼지해야 합니다. 안 그러면 방금 생성을 멈춘 그 오염된 항목을 계속 내주게 됩니다.

두 목록, 그리고 그 오류가 대칭이 아닌 이유

#

이 규칙에는 크롤러 UA 목록이 필요하고, Django에는 이미 하나 있습니다. 같은 지식이 두 시스템에 두 벌 있는 건 대개 냄새나는 일이지만, 여기서 흥미로운 건 둘이 어긋났을 때 벌어지는 일입니다. 대칭이 아니거든요.

• Cloudflare의 봇 목록은 Django 쪽의 부분집합으로 유지되어야 합니다. Cloudflare는 봇이라 여기지만 Django는 아니라고 보는 토큰이 있으면, 크롤러 전용 키 아래에 SPA 셸이 캐싱되고 그게 진짜 크롤러에게 나갑니다.
• 인앱 브라우저 제외 목록은 Django 쪽의 상위집합이어야 합니다. 너무 많이 제외해봐야 캐시 히트를 잃을 뿐입니다.

어느 쪽이든 안전한 방향으로 틀리면 캐싱을 조금 잃습니다. 첫 번째를 반대 방향으로 틀리면 다시 Googlebot에게 빈 페이지를 내주게 됩니다. 참고로 이 비대칭 때문에 목록이 정규식 대신 contains를 씁니다. matches는 Business 플랜이 필요하고, 알려진 안전한 방향으로 대충이어도 되는 목록에는 contains로 충분합니다.

페이지 대신 빌드를 실패시키는 불변식

#

크롤러 페이지에는 7일간 유효한 presigned 이미지 URL이 들어갑니다. 페이지 자체는 엣지에서 한 시간, 거기에 stale-while-revalidate 하루가 붙습니다.

이 두 숫자는 서로 관련이 있고, 캐시 수명이 이미지 수명을 넘어서는 순간 엣지는 모든 사진이 403인 페이지를 내주기 시작합니다. 이걸 알려주는 알림은 없습니다. HTML 자체는 멀쩡하니까요.

그래서 그 숫자들을 정의하는 코드는 관계가 깨지면 임포트 자체를 거부합니다.

CRAWLER_IMAGE_TTL = 7 * 24 * 3600  # presigned 이미지 URL
EDGE_S_MAXAGE = 3600
EDGE_STALE_WHILE_REVALIDATE = 24 * 3600

# 엣지 캐시가 이미지 URL보다 오래 살 수 있으면 임포트 시점에 실패시킨다.
if EDGE_S_MAXAGE + EDGE_STALE_WHILE_REVALIDATE >= CRAWLER_IMAGE_TTL:
    raise RuntimeError("edge cache lifetime must stay below the image URL lifetime")

서로 다른 파일에 있는 두 상수 사이의 제약은 코드 리뷰에서는 보이지 않고, 프로세스 시작 시점에는 명백합니다. 프로세스가 시작하는 곳에 두세요.

Cloudflare가 한 일 중 되돌려야 했던 두 가지

#

Vary: Origin이 번들을 캐시 밖으로 밀어냈습니다. django-cors-headers는 자기가 건드리는 모든 응답에 Vary: Origin을 찍고, Cloudflare는 Accept-Encoding 외의 헤더로 Vary가 걸린 응답은 캐싱하지 않습니다. 그래서 크리티컬 패스에서 가장 큰 1.6MB 자바스크립트 번들이 통째로 엣지에서 조용히 제외되고 있었습니다. 해결책은 미들웨어를 목록 맨 앞에 두어 나가는 길에 마지막으로 실행되게 하고, 정적 자산 경로의 Vary를 다시 쓰는 것입니다.

엣지 압축이 오리진 압축보다 나빴습니다. Cloudflare가 즉석에서 Brotli를 하게 두면 2,041,742바이트가 나왔고, 오리진의 gzip은 1,658,115바이트였습니다. 생각하지 않아도 되는 대가로 23% 더 큰 셈입니다. 온더플라이 압축은 압축률이 아니라 CPU를 최적화합니다. 오리진에서 미리 압축한 자산이 이깁니다.

크롤링을 기다리지 않고 검색엔진에 알리기

#

프로토콜 두 개, 그리고 둘을 합쳐도 커버리지는 실망스럽습니다.

IndexNow는 핑 하나를 받고 Bing, Yandex, Seznam을 커버합니다. 구글과 네이버는 참여하지 않습니다. 리스팅이 저장될 때마다 백그라운드에서 짧은 타임아웃으로 핑을 보내고, 판매완료·마감된 리스팅은 건너뜁니다. 네트워크 실패는 경고를 남길 뿐 그걸 촉발한 저장을 절대 실패시키지 않습니다. 부가적인 베스트 에포트 작업에 허용할 수 있는 동작은 이것뿐이죠.

구글의 Indexing API는 정확히 두 가지 스키마 타입만 받고, 그중 하나가 제게 있는 JobPosting입니다. 살아 있는 공고는 URL_UPDATED, 마감된 공고는 URL_DELETED를 보냅니다. 그 삭제 신호가 정직한 이유는 마감된 리스팅이 noindex도 함께 내보내기 때문이고, 코드에 그렇게 적어두었습니다. 나중에 noindex를 걷어내는 사람이 무엇을 같이 망가뜨리는지 알 수 있도록.

거기서 시간을 두 번 썼습니다. 할당량은 하루 200 URL인데, 리스팅을 일괄 임포트하면 한 번에 수백 번이 호출됩니다. 그래서 임포트된 리스팅은 건너뜁니다. 안 그러면 임포트 한 번이 하루치 예산을 전부 씁니다. 그리고 엔드포인트는 콜론이 들어간 urlNotifications:publish입니다. 슬래시를 쓰면 구글은 평범한 HTML 404를 반환하는데, 그건 API가 비활성화된 것과 똑같아 보입니다.

구조화 데이터가 가르쳐준 것

#

규칙 셋, 각각 서치 콘솔에게 혼나면서 배웠습니다.

1. 파싱할 수 없는 건 빼세요. 급여는 자유 텍스트로 들어옵니다. 예전에는 원문 문자열을 baseSalary.value로 내보냈는데, 그건 유효하지 않고 모든 공고에 단위 누락 플래그가 붙었습니다. 지금은 파싱 안 되는 급여는 그냥 없습니다.
2. 스키마를 만족시키려고 필드를 지어내지 마세요. 구인 공고에 상세 주소가 있는 경우는 드뭅니다. PostalAddress에 그럴듯한 걸 넣고 싶어지죠. 구인 공고에 지어낸 주소는 불완전한 주소보다 나쁩니다. 그래서 지역과 국가만 들어갑니다.
3. 만료일은 선택이 아닙니다. 구글은 validThrough가 없는 JobPosting을 버립니다. 그래서 하나를 유도하되, 오래된 공고가 어제 만료됐다고 주장하지 않도록 하한을 둡니다.

그리고 사이트맵에 대한 네 번째. 전부에 changefreq: daily를 주장하지 마세요. 리스팅 천 개를 매일 다시 크롤링해달라는 요청은 과부하 상태의 호스트로 읽히고, 구글은 사이트 전체의 크롤 속도를 낮추는 것으로 응답합니다. 실제로 얼마나 최근에 바뀌었는지에서 유도하세요.

사이트맵에는 품질 하한선도 있습니다. 제목과 본문을 합쳐 40자. 서치 콘솔이 약 1,000개 리스팅을 “크롤링됨 – 현재 색인이 생성되지 않음"으로 보고했었고, 어떤 중고 페이지의 고유 콘텐츠 전부가 한 단어짜리 제목과 전화번호 하나였습니다. 40자는 일부러 낮게 잡았습니다. 484개 리스팅 중 471개가 한국어이고 한국어는 글자당 담는 정보가 많으니까요. 영어에 맞춘 기준이었다면 마켓플레이스의 절반이 날아갔을 겁니다. 얇은 리스팅도 인덱스 페이지를 통해 크롤 가능한 상태로 남고, 누군가 수정하면 자동으로 사이트맵에 다시 들어옵니다.

여기서 가져갈 것

#

• 한 URL에서 서로 다른 본문을 내주는 일은, 무엇보다 먼저 캐시 키 문제입니다. CDN이 무엇을 키로 삼는지 알아내고, 바로 그 콘텐츠 타입에서 증명하기 전까지는 Vary를 무시한다고 가정하세요.
• 두 시스템이 하나의 목록에 합의해야 한다면, 어느 방향의 오류가 안전한지 알아내서 양쪽 사본 옆에 적어두세요. “이건 어긋날 수 있고, 허용되는 어긋남은 이 방향뿐이다"가 어긋나지 않는 척하는 것보다 낫습니다.
• 봇은 벤더 이름이 아니라 봇 이름으로 매칭하세요. 특히 영어권 밖에서는, 그 벤더가 사용자 손에 들린 브라우저도 만들고 있습니다.
• 멀리 떨어진 상수 사이의 불변식은 시끄럽게 실패하는 곳에 두세요. 임포트 시점은 공짜이고 아무도 건너뛸 수 없습니다.

업데이트 (2026년 11월 4일): 정정이 하나 더 있습니다. 이 504는 오리진이 응답하지 못한 프로브가 아닙니다. Cloudflare 자체의 Early Hints 캐시 조회로, 오리진에는 아예 가지 않으며, 여기서 504는 그 URL에 캐시된 것이 없었다는 뜻일 뿐입니다. Early Hints를 끈 것도 최선의 해결책은 아니었습니다. Link 응답 헤더를 보내자 기능이 동작하기 시작했고 이 미스는 히트로 바뀌었습니다. 자세한 내용은 Cloudflare 504 에러, 사실은 장애가 아니었다: Early Hints와 HTTP 103에 정리했습니다.

결론부터 말하면, auto_stop_machines를 켜 두면 멈춰 있는 Fly.io 머신에 들어온 요청은 부팅이 끝날 때까지 기다립니다. 제 앱은 머신이 시작될 때마다 entrypoint가 Django 마이그레이션과 collectstatic을 돌리고, 바이트코드도 전혀 캐시되지 않아서 콜드 스타트에 25~33초가 걸렸습니다. 이 작업을 이미지당 한 번만(FLY_IMAGE_REF를 키로 쓰는 Redis 락으로) 실행하고 빌드에 compileall을 넣자 콜드 부팅이 약 9초로 줄었습니다. 그리고 auto_stop_machines를 'stop'에서 'suspend'로 바꾸자(그러려면 swap을 빼야 했습니다) 깨어나는 데 약 3초면 충분해졌습니다.

Cloudflare 대시보드에서 트래픽이 튄 구간을 확인하러 들어갔다가, 그 아래에 훨씬 심각한 문제가 깔려 있는 걸 발견했습니다. 하루 동안 앱이 처리한 요청의 22%가 실패하고 있었습니다. 알림은 하나도 울리지 않았고, 헬스 체크는 전부 정상이었으며, 로그도 멀쩡해 보였습니다. 실패한 요청이 애초에 애플리케이션까지 도달하지 못했기 때문입니다.

원인은 제가 직접 작성한 컨테이너 시작 스크립트였습니다. 합리적인 작업을, 완전히 잘못된 타이밍에 하고 있었습니다.

트래픽 급증은 미끼였다

#

원래 확인하려던 건 한 시간 동안 약 4,900건이 몰린 구간이었습니다. 중앙값은 시간당 121건이고요. 순 방문자는 42명. 방문자 한 명당 110건인데, 사람이 이렇게 브라우징하지는 않습니다.

스캐너였습니다. 봇 하나가 존재하지도 않는 서브도메인을 지어내며 시크릿 파일을 찾아다니고 있었습니다.

api-stage-asia.example.com/.env.local
api-us-east-1-demo.example.com/.env
api-eu-uat.example.com/wp-config.php~
app-test-us-east-1.example.com/actuator/configprops
prod-api-use2.example.com/.env.local
relay.example.com/.env.production

서른 개쯤 되는 호스트명, 생각할 수 있는 모든 .env 변형, 그리고 Django 앱에 대고 요청한 어느 Java 프레임워크의 actuator 엔드포인트까지. 전부 정규 호스트로 301 리다이렉트됐고 아무것도 노출되지 않았습니다. 지루하고, 실제로 무해한 트래픽이었습니다.

그런데 분석 화면을 열어둔 김에 같은 날짜를 상태 코드로 묶어봤습니다. 진짜 문제는 거기 있었습니다.

22%입니다. 게다가 사이트 전체에 고르게 퍼진 게 아니라, 가장 아픈 곳에 정확히 몰려 있었습니다.

전부 모바일 앱이 30초마다 폴링하는 엔드포인트입니다. 그러니까 이건 추상적인 에러율 숫자가 아니었습니다. 사용자들의 폰이 하루 종일, 아마 몇 주 동안, 안 읽은 알림 배지를 조용히 못 불러오고 있었던 겁니다.

로그가 멀쩡해 보였던 이유

#

처음엔 앱이 느려졌겠거니 했습니다. 아니었습니다. 가장 나빴던 시간대의 애플리케이션 요청 로그를 아카이브에서 꺼내봤습니다.

[2026-09-08 01:00:29] "GET /api/notifications/unread/" 304 61.615
[2026-09-08 01:00:29] "GET /api/notifications/"        304 63.568
[2026-09-08 01:00:59] "GET /api/notifications/unread/" 304 58.742
[2026-09-08 01:00:59] "GET /api/notifications/"        304 105.438

44~105밀리초, 전부 304. 오리진은 빨랐습니다.

이게 중요한 단서이고, 규칙으로 적어둘 만합니다. 엣지가 오리진은 들어본 적도 없는 에러를 보고한다면, 요청은 도착하기 전에 죽고 있는 것입니다. 애플리케이션 로그를 그만 읽고, 그 앞에 있는 것을 보세요.

제 경우엔 Fly.io의 프록시였고, 답은 머신 스케줄링 방식에 있었습니다.

0으로 스케일 다운은 비용에 대한 약속이지, 지연 시간에 대한 약속이 아니다

#

제 설정은 이렇습니다. 언뜻 보면 합리적이죠.

[http_service]
  auto_stop_machines = 'stop'
  auto_start_machines = true
  min_machines_running = 1

유휴 머신은 정지하고, 트래픽이 오면 다시 시작합니다. 쓴 만큼만 냅니다. 트래픽이 들쭉날쭉한 작은 앱이라면 정확히 원하는 동작이고, 그래서 머신을 열 대 정의해두고도 평소엔 한 대만 돌고 있었습니다.

이 방식이 숨기는 청구서는 지연 시간입니다. 정지된 머신으로 요청이 들어오면, 누군가는 그 머신이 부팅될 때까지 기다려야 합니다. 부팅이 프록시의 인내심보다 오래 걸리면, 그 누군가는 504를 받습니다.

그래서 제 머신은 부팅에 얼마나 걸렸을까요? 한 번도 측정한 적이 없었습니다. 로그 아카이브는 알고 있습니다. 시작 스크립트가 각 단계를 출력하고, 모든 줄에 머신 ID가 붙어 있으니까요.

WITH s AS (
  SELECT instance, timestamp,
         CASE WHEN message ILIKE '%Starting app server%' THEN 'begin'
              WHEN message ILIKE '%Migrations complete%' THEN 'migrated'
              WHEN message LIKE  '%"GET /healthz%'       THEN 'serving' END AS phase
  FROM logs
  WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
)
SELECT instance,
       min(timestamp) FILTER (WHERE phase = 'begin')    AS started,
       min(timestamp) FILTER (WHERE phase = 'migrated') AS migrated,
       min(timestamp) FILTER (WHERE phase = 'serving')  AS first_serve
FROM s GROUP BY instance

모든 머신에서 일관되게 나온 답입니다.

그리고 이게 얼마나 자주 일어나는지 세어봤습니다.

SELECT count(*) AS starts, count(DISTINCT instance) AS machines
FROM logs
WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
  AND message ILIKE '%Starting app server%'
-- starts: 92, machines: 10

하루에 콜드 스타트 92번. 매번 그 머신으로 라우팅된 요청이 타임아웃되는 30초짜리 창이 열린 겁니다. 22%가 더는 미스터리가 아니었습니다.

원인은 제 entrypoint 안에 있었다

#

모든 머신이 요청 하나를 처리하기 전에 실행하던 코드입니다.

# entrypoint.sh, run on every machine start
echo "Running migrations..."
python manage.py migrate --noinput

echo "Running collectstatic in background..."
python manage.py collectstatic --noinput &

exec "$@"    # then start the app server

“하루에 92번"을 떠올리면서 다시 읽어보세요.

migrate는 완전한 Django 부팅입니다. 모든 모델을 임포트하고, Postgres에 연결하고, 마이그레이션 테이블을 조회한 뒤, 할 일이 없다고 판단합니다. 공유 CPU에서 아무것도 하지 않기 위해 10초를 씁니다. collectstatic은 두 번째 완전한 Django 부팅이고, 그다음 정적 파일을 오브젝트 스토리지에 업로드하면서 웹 서버가 기동하려는 바로 그 단일 코어를 두고 경쟁합니다. 앱 서버가 세 번째 부팅이고요.

파이썬 인터프리터 세 개, 그중 둘은 이미 끝난 일을 반복하면서, 머신이 깨어날 때마다 매번.

이렇게 짠 이유는 나름 타당했고, 아마 여러분 코드도 비슷할 겁니다. 마이그레이션은 어딘가에서는 돌아야 하고, Fly의 release_command는 예전에 멈춘 적이 있었으며, entrypoint는 배포 시 반드시 실행되는 유일한 지점이니까요. 배포 작업을 넣기에 맞는 자리입니다. 다만 머신 시작마다 넣기에 맞는 자리가 아닐 뿐입니다. 그리고 머신이 알아서 멈추고 시작하기 시작한 순간, 이 둘은 더 이상 같은 사건이 아닙니다.

버그의 전부는 이것이고, 흔한 실수라고 생각합니다.

릴리스에 속한 작업이 머신 시작마다 실행되고 있었습니다. 0으로 스케일 다운이 사건 하나를 아흔두 개로 바꿔놓았습니다.

해법: 릴리스를 한 번만 선점하기

#

특정 이미지로 부팅하는 여덟 번째 머신에서 마이그레이션이 돌 필요는 없습니다. 그 이미지에 대해 한 번만 돌면 되고, 나머지는 그게 끝났다는 사실만 알면 됩니다.

즉, 배포할 때마다 이름이 바뀌는 락입니다. Fly가 FLY_IMAGE_REF로 그 이름을 공짜로 주고, Redis는 이미 있었습니다. 전체가 Django보다 먼저 실행되는 작은 스크립트라서, 흔한 경우의 답이 프레임워크 부팅이 아니라 밀리초로 끝납니다.

# release_gate.py: runs before Django exists. Exit code 0 means "prepare this release".
import os, time

PREPARE, SKIP = 0, 1
LOCK_TTL, WAIT, POLL = 300, 240, 2
_sleep, _monotonic = time.sleep, time.monotonic    # aliases, so tests can replace them


def release_id() -> str:
    """Something that changes exactly when the deployed image does."""
    return os.getenv("FLY_IMAGE_REF") or os.getenv("FLY_MACHINE_VERSION") or ""


def claim(client, release: str) -> int:
    if client is None or not release:   # no Redis, or no idea which release: behave as before
        return PREPARE
    done_key, lock_key = f"release:{release}:done", f"release:{release}:lock"
    if client.get(done_key):            # somebody already did it for this image
        return SKIP

    owner = os.getenv("FLY_MACHINE_ID", "unknown")
    if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
        return PREPARE                  # we won the race; we do the work

    # Someone else is preparing. Wait for them, because serving requests
    # against a half-migrated schema is worse than starting slowly.
    deadline = _monotonic() + WAIT
    while _monotonic() < deadline:
        _sleep(POLL)
        if client.get(done_key):
            return SKIP
        if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
            return PREPARE              # the owner died and its lock expired; take over
    return PREPARE                      # waited long enough; do it ourselves

# ... plus `done` (sets done_key) and a main() that treats any Redis error as PREPARE