이미지가 늦게 뜰 때, 먼저 나누어 봐야 할 것들
프로젝트 목록을 열면 글은 먼저 보이는데 이미지는 한 박자 늦게 나타납니다. 한 번 기다리고 나면 괜찮아 보이다가도 새로 열면 다시 느린 느낌이 듭니다. 이미지를 많이 사용하는 포트폴리오에서는 이런 작은 지연이 사이트 전체의 인상에 영향을 줍니다.
제로원 사이트를 다듬는 과정에서도 비슷한 질문이 나왔습니다. 노션에서 이미지를 매번 가져오기 때문에 느린 것은 아닐까. 한 번 받아두고 같은 파일이라면 다시 사용하면 되지 않을까. 질문은 단순하지만 해결하려면 무엇이 바뀌고 무엇을 재사용할지 먼저 나눠봐야 했습니다.
이미지 로딩이 늦다는 현상에는 여러 원인이 있을 수 있습니다. 원본 파일이 크거나, 네트워크가 느리거나, 브라우저가 아직 이미지 요청을 시작하지 않았을 수도 있습니다. 캐시를 도입한다고 이 모든 문제가 한 번에 사라지는 것은 아닙니다. 이번 작업에서는 그중 같은 원본을 반복해서 내려받는 경로를 정리하는 데 집중했습니다.
노션의 이미지 주소는 파일 이름 이상의 정보를 담습니다
노션 API로 받은 이미지를 화면에 넣을 때는 파일이 어디에 있는지 확인해야 합니다. 노션에 직접 올린 파일과 외부 주소를 연결한 이미지는 같은 방식으로 다룰 수 없습니다. 이번 글은 노션에 업로드된 이미지의 임시 다운로드 주소를 중심으로 설명합니다.
Notion 공식 문서에 따르면 노션 호스팅 파일의 응답에는 임시 URL과 만료 시각이 포함됩니다. 이 URL은 영구 주소가 아니며 접근이 만료되면 파일 정보를 다시 조회해 새 주소를 받아야 합니다. 그러므로 응답에서 받은 주소를 한 번 저장해두고 계속 사용할 수 있다고 가정하면 안 됩니다.
여기서 주소가 만료된다는 말은 파일 자체가 사라진다는 뜻이 아닙니다. 다운로드를 허용하는 임시 정보의 유효 시간이 끝난다는 의미에 가깝습니다. 파일을 가리키는 정보와 지금 접근할 수 있게 해주는 정보를 구분하는 것이 출발점입니다.
주소가 바뀌었다고 사진까지 바뀐 것은 아닙니다
같은 이미지를 다시 조회했는데 주소의 뒷부분이 달라질 수 있습니다. 파일을 교체하지 않았더라도 인증 서명이나 만료 관련 값이 갱신되기 때문입니다. URL 전체를 그대로 비교하면 실제로는 같은 파일을 새로운 이미지로 판단할 수 있습니다.
택배를 받는 장소와 출입증을 나누어 생각하면 이해하기 쉽습니다. 목적지는 같지만 출입증이 새로 발급될 수 있습니다. 출입증이 바뀔 때마다 이미 받아둔 물건까지 새 물건으로 취급할 필요는 없습니다. 다만 이 비유가 원본에 접근할 권한을 생략해도 된다는 뜻은 아닙니다.
이번 구현에서는 허용한 노션 파일 주소에서 인증 서명과 만료 관련 항목을 제외한 정보를 정리해 식별 키를 계산합니다. 파일 경로와 의미가 있는 나머지 쿼리는 유지합니다. 모든 쿼리를 무조건 지워도 되는 것은 아니기 때문입니다.
이 방법은 현재 사용 중인 노션 파일 경로의 특성을 바탕으로 한 선택입니다. 파일 내용이 달라지면 언제나 경로도 바뀐다는 보편적인 보장은 아닙니다. 다른 저장소나 동일 주소의 내용이 덮어써지는 환경이라면 버전 정보나 별도의 갱신 정책이 필요합니다.
달라진 것은 파일일까요, 출입증일까요?
/flower.jpg?Signature=AAA파일 A/flower.jpg?Signature=BBB같은 파일 A브라우저에는 사이트 안의 주소를 줍니다
파일을 구분하는 기준을 정한 다음에는 이미지를 전달하는 경로를 바꿨습니다. 브라우저에 만료되는 노션 주소를 직접 전달하는 대신, 프로젝트 ID와 파일 키로 구성된 사이트 내부 주소를 제공합니다. 브라우저가 보는 주소와 서버가 원본을 가져오는 주소를 분리한 것입니다.
이미지 요청을 받은 서버는 먼저 현재 공개된 프로젝트의 이미지인지 확인합니다. 그다음 저장된 파일이 있으면 읽어서 응답하고, 없으면 유효한 원본 주소로 내려받아 저장합니다. 다음 요청부터는 저장된 원본을 사용할 수 있습니다.
중요한 차이는 브라우저가 어떤 외부 주소든 서버에게 대신 받아달라고 요청하는 구조가 아니라는 점입니다. 서버는 자신이 조회한 공개 프로젝트 데이터 안에서 해당 키의 원본을 찾습니다. 알 수 없는 프로젝트나 이미지 키를 요청하면 파일을 제공하지 않습니다.
이렇게 주소를 분리하면 노션의 인증 서명이 갱신되더라도 같은 파일의 사이트 내부 주소는 유지할 수 있습니다. 다만 이미지 파일 캐시가 있다는 이유로 노션의 프로젝트 정보 조회까지 전부 없어지는 것은 아닙니다. 콘텐츠 확인과 이미지 원본 다운로드는 서로 다른 작업입니다.
처음에는 저장하고, 다음에는 꺼내 씁니다
- 공개 프로젝트인지 확인
- 노션 원본 다운로드
- 서버에 저장하고 응답
- 공개 프로젝트인지 확인
- 저장된 이미지 읽기
- 브라우저에 응답
처음 한 번의 대기는 어디에서 줄일까요
캐시가 비어 있다면 누군가는 첫 다운로드를 기다려야 합니다. 파일을 저장하는 기능만 추가하면 첫 방문의 요청에는 여전히 원본을 가져오는 시간이 포함됩니다. 자주 보이는 썸네일을 먼저 받아두면 이 대기를 방문자가 겪기 전에 처리할 수 있습니다.
현재 사이트는 페이지 응답 이후 공개 프로젝트 이미지들을 백그라운드에서 미리 받도록 구성했습니다. 너무 자주 실행하지 않게 간격을 두고, 한꺼번에 원본 서버로 요청이 몰리지 않도록 다운로드 작업 수도 제한했습니다. 별도의 사전 저장 명령으로 미리 채우는 방법도 준비했습니다.
같은 프로세스에서 동시에 들어온 동일 이미지 요청은 진행 중인 다운로드를 공유합니다. 여러 방문자가 같은 시점에 파일을 요청했다고 똑같은 파일을 여러 번 받지 않도록 하기 위한 처리입니다. 다만 서버가 여러 대라면 프로세스 안의 중복 방지만으로 충분하지 않으므로 저장소와 잠금 전략을 따로 설계해야 합니다.
미리 받기는 실패할 수도 있습니다. 네트워크 오류나 만료된 원본 주소 때문에 저장하지 못한 경우가 있다면 이후 요청에서 다시 시도할 수 있어야 합니다. 백그라운드 작업을 실행했다는 사실과 필요한 파일이 실제로 저장됐다는 사실은 구분해서 확인해야 합니다.
파일을 교체했을 때는 새 이미지를 보여줘야 합니다
캐시에서 가장 조심해야 하는 상황은 빠르게 보여주는 대신 오래된 내용을 계속 보여주는 것입니다. 같은 파일은 다시 받아오지 않되, 사용자가 새 파일로 바꿨다면 갱신 결과가 반영되어야 합니다.
이번 방식에서는 노션에서 파일 교체로 원본의 고유 경로가 바뀌면 새로운 키와 사이트 내부 주소가 만들어집니다. 기존 캐시를 덮어쓰는 대신 새 파일을 저장하기 때문에 주소 갱신과 파일 저장의 경계가 비교적 명확합니다.
그렇다고 편집 직후 모든 화면에 즉시 새 이미지가 나타난다는 뜻은 아닙니다. 프로젝트 정보 조회에도 별도의 재검증 간격이 있으므로 서버가 최신 데이터를 확인한 뒤 새 이미지 주소를 사용하게 됩니다. 캐시의 갱신 시간은 파일 저장소만이 아니라 콘텐츠 조회 경로까지 함께 봐야 합니다.
이전 키의 파일을 디스크에 남겨두는 것과 그 파일을 계속 공개하는 것도 다른 문제입니다. 현재 이미지 요청 경로는 공개 프로젝트 데이터에 해당 키가 있는지 확인합니다. 다만 이미 브라우저나 중간 캐시에 전달된 응답은 정해진 캐시 시간 동안 남을 수 있으므로 즉시 회수가 필요한 자료를 이런 공개 캐시에 올려서는 안 됩니다.
같은 파일은 재사용, 새 파일은 새 주소로
/file-a/flower.jpg기존 키 · 캐시 재사용/file-b/flower.jpg새 키 · 새 파일 저장서버 캐시와 브라우저 캐시는 서로 다른 일을 합니다
서버에 파일을 저장했다고 해서 브라우저가 서버로 보내는 요청까지 없어지는 것은 아닙니다. 첫 번째 재사용은 서버가 노션 원본을 다시 내려받지 않는 것이고, 두 번째 재사용은 브라우저가 이미 받은 응답을 활용하는 것입니다.
현재 이미지 응답에는 브라우저가 일정 시간 재사용할 수 있는 Cache-Control을 설정합니다. 조건부 요청에 활용할 ETag도 함께 제공합니다. 브라우저가 기존 ETag를 보내고 서버의 파일이 같다면, 서버는 이미지 본문을 다시 보내는 대신 304 응답을 줄 수 있습니다.
304는 요청 자체가 없었다는 뜻이 아닙니다. 서버가 확인 요청을 받고 내용이 같다고 응답한 것입니다. 반면 브라우저의 유효한 캐시를 바로 사용하면 원격 요청 없이 표시될 수도 있습니다. 네트워크 기록을 볼 때 이 두 경우를 나눠야 합니다.
캐시 시간은 길수록 무조건 좋지 않습니다. 자주 바뀌거나 공개 범위가 민감한 데이터에는 다른 정책이 필요합니다. 현재는 공개 프로젝트의 이미지 전달을 위한 설정이며 사용자별 비공개 파일을 제공하는 설계는 아닙니다.
외부 파일을 대신 받는 서버에는 제한이 필요합니다
이미지 저장 기능은 편리하지만 외부 주소를 서버가 가져온다는 점에서 주의가 필요합니다. 요청한 사람이 임의의 주소를 지정할 수 있으면 공개 이미지와 무관한 내부 주소나 큰 파일을 서버가 받아오는 통로가 될 수 있습니다.
그래서 이번 구현은 허용한 노션 파일 호스트만 원본으로 다루고, 주소가 다른 곳으로 이동하는 리다이렉트에서도 허용 범위를 다시 확인합니다. 외부 URL을 문자열로 받기만 하면 어떤 이미지든 저장하는 프록시로 만들지 않았습니다.
파일의 크기와 형식도 확인합니다. 현재 캐시는 최대 25MB의 허용된 래스터 이미지 형식을 다루고, 확장자나 응답 헤더만 믿지 않고 파일의 앞부분도 검사합니다. 다운로드 중에도 크기를 확인해 제한을 넘기면 중단합니다.
이러한 검사는 모든 위험을 해결했다는 선언이 아닙니다. 요청 빈도 제한과 저장 공간 관리, 장애 관찰 같은 운영 대책도 필요합니다. 특히 이 기능을 다른 용도로 확장할 때는 공개 범위와 원본 접근 조건을 다시 살펴봐야 합니다.
재시작 뒤에도 남는 저장소인지 확인합니다
개발 환경에서는 한 번 저장된 이미지가 서버 재시작 이후에도 남아 있는지 쉽게 확인할 수 있습니다. 하지만 배포 환경이 달라지면 같은 결과를 기대할 수 없습니다. 실행될 때마다 초기화되는 디스크에 저장하면 새로운 서버에서는 캐시를 다시 채워야 합니다.
현재 로컬 실행은 빌드 폴더 밖의 캐시 경로를 사용합니다. 새 빌드를 만들어도 저장한 파일이 같이 사라지지 않도록 한 선택입니다. 운영에서는 영구 디스크를 연결하거나 여러 서버가 함께 사용하는 저장소를 마련하는 등 배포 방식에 맞는 결정을 해야 합니다.
권한과 용량도 확인해야 합니다. 현재 코드는 파일을 영구 저장하지 못하더라도 내려받은 이미지를 응답할 수 있지만, 그 경우 다음 요청에서 다운로드를 반복할 수 있습니다. 화면이 보인다는 이유만으로 캐시 저장도 성공했다고 생각하면 안 됩니다.
교체 전 파일이 계속 쌓이는 문제도 남습니다. 현재 구현은 이전 파일을 자동으로 정리하지 않습니다. 운영 시에는 사용량을 관찰하고, 더 이상 참조하지 않는 파일을 어떤 기준과 유예 기간으로 지울지 정해야 합니다. 영구 저장은 영원히 보관한다는 뜻이 아닙니다.
빠르게 보이는 것과, 제대로 재사용하는 것은 다릅니다
이번 작업에서 확인한 것은 같은 파일의 서명이 달라져도 같은 키가 만들어지는지, 저장한 파일을 다음 요청에서 재사용하는지, 재시작 뒤에도 파일이 남는지, ETag 조건부 응답과 없는 프로젝트 차단이 동작하는지였습니다. 실제 화면에서 내부 이미지 주소가 사용되는지도 함께 확인했습니다.
이 결과를 사이트가 몇 배 빨라졌다는 말로 바꾸지는 않으려 합니다. 그런 성능 주장을 하려면 같은 조건에서 전송량과 응답 시간, 첫 방문과 재방문을 나눠 측정해야 합니다. 기능이 작동하는 확인과 사용자 체감의 개선을 측정하는 일은 다릅니다.
또한 원본을 캐시하는 것과 이미지를 가볍게 만드는 것은 별개입니다. 큰 이미지를 그대로 저장하면 첫 전송량은 여전히 큽니다. 필요한 크기로 썸네일을 만들고 적절한 형식으로 압축하는 최적화는 별도로 검토해야 합니다.
노션 이미지를 매번 내려받지 않기 위한 핵심은 단순히 파일을 어딘가에 저장하는 일이 아니었습니다. 주소의 만료와 파일의 변경을 나누고, 공개된 콘텐츠를 확인하면서 저장과 전달, 갱신의 경계를 정하는 일이었습니다. 같은 것은 다시 활용하고 달라진 것은 새로 가져오는 것. 이 원칙을 실제 환경에서 유지할 수 있어야 캐시가 지속적으로 도움이 됩니다.