1 · 데이터 소스 연동
API, 데이터베이스, CSV, 크롤러를 과금 가능한 도구로 나누는 단계 — 여기가 가장 지뢰를 심기 쉬운 지점입니다.
01수집기에서 gzip을 끄지 않아, 상대가 압축을 켜자 파싱이 터졌습니다
- 당시
- 상대 API를 호출하면 gzip 바이트 스트림이 돌아왔는데, 이를 그대로 텍스트로 파싱해 깨진 문자 오류가 쏟아졌습니다.
- 해결 방법
- 수집 레이어는 항상
Accept-Encoding: identity를 보내고 상대의 기본 동작에 의존하지 않습니다; 타임아웃과 재시도를 추가합니다.
02온체인 로그를 0번 블록부터 스캔하면 반드시 실패합니다
- 당시
- 온체인 데이터를 제네시스 블록부터 스캔했지만 타임아웃까지 결과가 없었습니다.
- 해결 방법
- 체인 헤드에서 고정 블록 수만큼 되돌아가 증분 스캔하고 커서를 DB에 저장하면, 재실행 시 이어서 진행됩니다.
03402 응답 헤더를 보냈는데 브라우저에서 읽히지 않음
- 당시
- 패킷 캡처에서는 payment 관련 헤더가 보이는데, 프런트엔드 JS에서는 undefined였습니다.
- 해결 방법
- 사용자 정의 응답 헤더는 명시적으로
Access-Control-Expose-Headers에 추가해야 하며, 그렇지 않으면 브라우저가 보안 정책에 따라 차단합니다.
04금액 단위를 잘못 써서 facilitator가 바로 거부
- 당시
- 0.01 USDC를 1e16으로 적었더니 facilitator는 'amount mismatch'만 돌려줬고, 단위 문제라는 걸 알 수 없었습니다.
- 해결 방법
- USDC는 소수점 6자리입니다. 0.01 = 10000. 가격 생성은 공통 변환 함수를 거치고 직접 쓰지 않습니다.
2 · 배포와 라우팅
문법 검사를 통과해도 사이트가 열린다는 뜻은 아닙니다. 이 섹션의 함정은 모두 문법 밖에 있습니다.
05nginx -t는 모두 통과인데 리다이렉트 루프로 사이트가 열리지 않음
- 당시
- 정확 일치 location의 301과 try_files의 내부 리다이렉트가 서로를 물고 늘어져 브라우저가 '리다이렉트가 너무 많음'을 표시했습니다.
- 해결 방법
- 변경 후에는 실제로 요청을 보내 상태 코드와 홉 수를 확인하고,
--max-redirs 로 리디렉션 횟수를 제한해 검증해야 하며, 문법만 봐서는 안 됩니다.
06관리자 주소가 301 → 슬래시 추가 → 403 흰 화면
- 당시
/admin 는 301로 /admin/로 넘어갔습니다. 실제 디렉터리에 index 파일이 없어 곧바로 403; 들어갈 수 있는 것은 /admin.html 뿐입니다.- 해결 방법
- 내부 rewrite로 파일에 직접 연결합니다:
rewrite ^/admin/?$ /admin.html last;. 로그인 보호 계층은 그대로 유지합니다.
07location에서 if로 정규식 판정을 하다 캡처 그룹을 덮어썼습니다
- 당시
- 클린 URL 규칙에 if 정규식 판정을 넣었더니,
$1 가 초기화되고,/pricing.html 는 301로 홈페이지로 넘어갔습니다.
- 해결 방법
- if 판정을 해당 location 밖으로 빼거나 map으로 바꿉니다. location 안에서 if와 캡처 그룹을 함께 쓰지 마세요.
08MCP 엔드포인트 리버스 프록시가 버퍼링해 SSE가 멈췄습니다
- 당시
- streamable-http는 SSE를 쓰는데 nginx 기본 버퍼링이 스트림을 막아 클라이언트가 응답을 받지 못했습니다.
- 해결 방법
proxy_buffering off; + proxy_cache off; + 늘리기 proxy_read_timeout。
3 · 캐시와 버전
가장 까다로운 유형: 서버는 멀쩡한데 페이지만 계속 오류를 냅니다.
09CSS / JS를 고쳤는데 운영에서 '적용되지 않은 것처럼' 보임(3연속 발생)
- 당시
- nginx가 정적 리소스에
expires 7d를 설정했는데, 페이지 참조에는 버전 번호가 없었습니다.
- 해결 방법
- 긴 캐시를 설정하면 버전 스탬프가 필수입니다. 리소스를 바꿀 때마다 버전을 올리고 릴리스 체크리스트에 적습니다.
10서버 로그는 모두 200인데 페이지는 '데이터를 읽을 수 없다'고 표시
- 당시
- 브라우저가 7일간 캐시된 옛 스크립트를 실행하다 새 데이터 형식을 렌더링할 때 크래시가 났고, catch가 이를 모두 '서버를 읽을 수 없음'으로 보고했습니다.
- 해결 방법
- 관리자 스크립트는 별도로 no-cache, 데이터 조회와 렌더링은 두 개의 try로 분리, 완전 실패 시 localStorage로 폴백합니다.
11어떤 페이지는 새것, 어떤 페이지는 옛것
- 당시
- 같은 CSS를 여러 페이지가 참조하는데, 그중 몇 개만 버전 번호를 올렸습니다.
- 해결 방법
- 사이트 전체에서 해당 리소스 이름을 검색해 일괄로 버전을 올립니다. 페이지를 손으로 골라 고치지 마세요.
12오류 문구가 방향을 잘못 잡게 만든다
- 당시
- 렌더링 크래시, 네트워크 실패, 키 만료, 타임아웃이 모두 하나의 catch에서 같은 문구로 보고되어 서버 쪽을 이틀 동안 뒤졌습니다.
- 해결 방법
- 네 가지 실패에 네 가지 문구, 401/403은 재시도 없이 재로그인을 안내하고, 실패 시 캐시 데이터를 먼저 보여 줍니다.
4 · 모니터링과 운영
크론 작업과 생존 확인 스크립트는 잘못 작성하면 조용히 데이터를 망칩니다.
13손으로 고친 876개 페이지가 크론 1회로 전부 덮어써짐
- 당시
- 정적 생성 사이트는 크론으로 재생성되므로 산출물을 손으로 고치면 반드시 덮어써집니다.
- 해결 방법
- 생성기 템플릿만 수정 → 재생성 → 배포. 산출물 mtime을 감시하는 가드 스크립트를 추가합니다.
14JSON 클라이언트로 MCP 엔드포인트를 확인해 SSE를 '죽음'으로 판정
- 당시
- 생존 확인 스크립트가 응답 본문을 파싱했는데, MCP는 SSE 스트림을 반환하므로 파싱 실패가 곧 사망 판정이 되었습니다.
- 해결 방법
- HTTP 상태 코드만으로 판정합니다. 200과 402 모두 살아 있음으로 보고 응답 본문은 절대 파싱하지 않습니다.
15탐지 필드명을 잘못 적어 모든 항목이 항상 '변동'으로 판정됨
- 당시
- 작성한 값은
p.ok 지만 실제 필드는 p.lastOk여서 판정 로직이 항상 예외 분기로 빠졌습니다.
- 해결 방법
- 필드명은 기억이 아니라 DB에 쓰는 코드와 대조해 확인합니다. 배포 전에 알려진 데이터 두 건으로 판정 로직을 검증하세요.
16일별 집계를 증분 누적으로 하면 PV가 하루에 두 배가 됩니다
- 당시
- '어제 값 + 오늘 증분'은 재실행할 때마다 두 배가 됩니다.
- 해결 방법
- 일 단위로 다시 계산해 덮어써 멱등성을 보장합니다. 시간 문자열 변환은 반드시 모든 집계 뒤에 둡니다.
5 · GEO와 인용 가능성
AI가 당신을 볼 수 없으면 아무리 좋은 데이터도 팔리지 않습니다.
17기본 robots.txt가 모든 AI 크롤러를 차단해 GEO가 0이 됨
- 당시
- 프레임워크 기본 템플릿을 써서 주요 AI 크롤러가 문 앞에서 막혔습니다.
- 해결 방법
- 40개 이상의 AI 크롤러를 하나씩 명시적으로 허용하고, 관리자 등 비공개 경로는 별도로 Disallow합니다.
18llms.txt를 마케팅 문구로 쓰면 어떤 AI도 인용하지 않습니다
- 당시
- 소개와 형용사를 넣었지만 AI가 검증할 수 없으니 쓰지 않은 것과 같습니다.
- 해결 방법
- 검증 가능한 사실만 씁니다. 가격, 네트워크, 엔드포인트, 절대 경로, 명확한 정산 규칙입니다.
19외부 AI가 언급은 했지만 규칙을 틀리게 말했습니다
- 당시
- AI가 수수료를 15%, 정산을 T+7로 말했는데 '언급률' 지표는 초록불이었습니다.
- 해결 방법
- 모니터링은 '내용 정확도'를 별도 지표로 두어야 합니다. 언급되었어도 틀렸다면 언급되지 않은 것과 같습니다.
6 · 가격과 정산
돈 문제는 한 번 틀리면 신뢰를 되찾기 어렵습니다.
20가격이 너무 낮아 1년이 지나도 정산 기준에 못 미침
- 당시
- 단가를 너무 낮게 잡아 월 매출이 $50 정산 기준을 넘지 못해 자금이 계속 장부에 묶여 있었습니다.
- 해결 방법
- 등록 전에 계산합니다. 호출량 × 단가 × 분배율로 최소 성립 가격을 역산하고 회수 기간을 확인합니다.
21런타임에 데이터 파일을 고쳤더니 메모리의 옛 값이 다시 덮어씀
- 당시
- 서비스가 도는 중에 데이터 파일을 직접 고쳤는데, 재시작 전에 옛 값이 다시 기록되었습니다.
- 해결 방법
- 데이터를 만지기 전에 서비스를 멈춥니다. 대사는 온체인 Transfer 이벤트만 인정하며 허용 오차는 ±$0.02입니다.
22무료 할당량을 IP로 제한하면 분산된 Agent에게는 전혀 효과가 없습니다
- 당시
- Agent는 매번 소스 IP가 달라서 IP 기준 제한은 제한이 아닙니다.
- 해결 방법
- 할당량을 Agent / 키 차원에 묶고 일일 서킷 브레이커를 추가합니다. 무료 할당량은 획득 비용으로 보고 ROI를 계산합니다.
이 22건을 20개의 무료 도구로 만들었습니다
각 항목 아래 도구는 모두 무료이고 로그인이 필요 없으며, 입력 내용은 브라우저 안에서만 계산됩니다. 직접 해낼 수 있으면 도구를 쓰고, 안 되면 저희가 대신 등록·홍보·정산합니다.