<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Presigned URLs · 인재덕</title>
    <link>https://jared.lynskey.co.nz/ko/tags/presigned-urls/</link>
    <description>소프트웨어 엔지니어링과 개발 조직 리더십에 대한 이야기. 성과 리뷰, 채용과 팀 확장, CI/CD, 데브옵스 모니터링, 에이전틱 AI. 서울에서 씁니다.</description>
    <generator>Hugo</generator>
    <language>ko</language>
    <copyright>© 2026 인재덕</copyright>
    <lastBuildDate>Fri, 13 Nov 2026 00:00:00 +1300</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/ko/tags/presigned-urls/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>AWS Emulator 사용법: 무료 LocalStack 대체 설정하기</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2026/aws-emulator-setup/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2026/aws-emulator-setup/</guid>
      <pubDate>Fri, 13 Nov 2026 00:00:00 +1300</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>AWS Emulator</category>
      <category>LocalStack</category>
      <category>Moto</category>
      <category>Floci</category>
      <category>S3</category>
      <category>Testing</category>
      <category>Docker</category>
      <category>GitHub Actions</category>
      <category>Python</category>
      <category>Presigned URLs</category>
      <category>OTA Updates</category>
      <description>AWS의 무료 에뮬레이터를 Docker, Linux, GitHub Actions에 설정하고 boto3를 연결하는 법. 제 S3 로컬 테스트에서 LocalStack 4.12가 놓친 것을 이 에뮬레이터가 잡아낸 이야기도 담았습니다.</description>
      <content:encoded><![CDATA[<p>AWS가 2026년 11월 11일 <a href="https://github.com/aws/aws-emulator"  target="_blank" rel="noreferrer">AWS Emulator</a>를 공개했습니다. 내 컴퓨터에서 직접 돌리는 AWS API의 로컬 사본입니다. 무료이고, AWS 계정이 필요 없고, 코드는 퍼블릭 도메인(CC0)이며, 지원하는 서비스가 200개가 넘습니다. LocalStack이 최신 이미지에 계정과 인증 토큰을 요구하기 시작한 지 7개월 만에 나온 터라, 많은 사람이 오래 기다려 온 무료 LocalStack 대체 도구로 이걸 눈여겨보고 있습니다.</p>
<p>이 글은 대부분 설정 이야기입니다. Mac이나 Windows에서는 Docker, Linux에서는 패키지, AWS CLI와 boto3가 에뮬레이터를 바라보게 하는 환경 변수, 그리고 Docker Compose, pytest, GitHub Actions까지요. 여기 나오는 명령은 전부 버전 1.0.342에서 제가 직접 돌려 봤습니다. 설정 다음에는 제 프로젝트 두 개의 S3 테스트를 여기에 돌렸을 때 무엇을 맞히고 무엇을 틀렸는지를 LocalStack 4.12, Moto, Floci와 나란히 놓고 봅니다. 두 프로젝트는 제 마켓플레이스 앱의 업로드 흐름, 그리고 직접 호스팅하는 Codemagic Patch 서버가 OTA 번들을 보관하는 버킷입니다.</p>

<h2 class="relative group">1분 만에 보는 AWS Emulator
    <div id="1분-만에-보는-aws-emulator" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#1%eb%b6%84-%eb%a7%8c%ec%97%90-%eb%b3%b4%eb%8a%94-aws-emulator" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>AWS는 컨테이너 이미지를 배포하지 않습니다. AWS의 Linux 패키지를 설치하는 아홉 줄짜리 Dockerfile로 이미지를 직접 만들고, 9297 포트로 띄운 다음, 환경 변수 몇 개를 설정하면 됩니다. 그때부터 SDK는 AWS 대신 에뮬레이터와 이야기하고, 코드는 하나도 바뀌지 않습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">docker build -t aws-emulator .           <span class="c1"># the Dockerfile is below</span>
</span></span><span class="line"><span class="cl">mkdir -p ~/.aws/emulator
</span></span><span class="line"><span class="cl">docker run --rm -d --name aws-emulator -p 127.0.0.1:9297:9297 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -e <span class="nv">HOME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$HOME</span><span class="s2">&#34;</span> -v <span class="s2">&#34;</span><span class="nv">$HOME</span><span class="s2">/.aws/emulator:</span><span class="nv">$HOME</span><span class="s2">/.aws/emulator&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  aws-emulator -p <span class="m">9297</span> --telemetry off
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_ENDPOINT_URL</span><span class="o">=</span>https://127.0.0.1:9297
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_SHARED_CREDENTIALS_FILE</span><span class="o">=</span>~/.aws/emulator/9297/emulator_credentials
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_CONFIG_FILE</span><span class="o">=</span>~/.aws/emulator/9297/config
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_CA_BUNDLE</span><span class="o">=</span>~/.aws/emulator/9297/ca.pem
</span></span><span class="line"><span class="cl">aws sts get-caller-identity              <span class="c1"># &#34;Account&#34;: &#34;000000000000&#34;</span></span></span></code></pre></div></div>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-setup.jpg" style="background:url('data:image/webp;base64,UklGRloAAABXRUJQVlA4IE4AAACQBACdASogABIAPw1yskwmIyIhKAqoxiGJ6QDG9BPdK4I2hDwC1QaVpF521UAA/ui2Gzha/NBVWRJqzq2oTgehY/P2cqAeQAizoM8AAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="터미널: Dockerfile, AWS Emulator 컨테이너 시작, ok로 답하는 헬스 체크, 계정 000000000000을 돌려주는 aws sts get-caller-identity, S3 업로드, 그리고 HTTP 501로 답하는 CORS preflight">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-setup.mp4" type="video/mp4">
  </video><figcaption>제 Mac에서 녹화한 설정 전 과정입니다. 시작, 헬스 체크, 에뮬레이터의 계정, S3 업로드, 그리고 아직 못 하는 한 가지(CORS preflight가 501로 답합니다. 아래에서 자세히 다룹니다).</figcaption>
</figure>

<p>준비되기까지 0.5초 정도 걸리고, 가만히 있을 때 메모리를 175 MiB쯤 씁니다. 모든 게 메모리에 있어서 컨테이너를 멈추면 싹 지워집니다.</p>

<h2 class="relative group">계정이 필요할까? (LocalStack 무료 플랜 vs AWS Emulator)
    <div id="계정이-필요할까-localstack-무료-플랜-vs-aws-emulator" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ea%b3%84%ec%a0%95%ec%9d%b4-%ed%95%84%ec%9a%94%ed%95%a0%ea%b9%8c-localstack-%eb%ac%b4%eb%a3%8c-%ed%94%8c%eb%9e%9c-vs-aws-emulator" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>아니요. AWS Emulator, Moto, Floci는 모두 아무 데도 가입하지 않고 돌아갑니다. AWS Emulator는 AWS 자격 증명조차 원하지 않습니다. 시작할 때마다 자기 액세스 키를 새로 만들고, 그 키로 서명한 요청만 받습니다.</p>
<p>달라진 건 LocalStack입니다. 2026년 3월부터 최신 이미지는 <code>LOCALSTACK_AUTH_TOKEN</code>이 있어야 하는데, 이 토큰은 무료 계정(무료 플랜은 취미와 비상업적 용도를 겨냥합니다)이나 유료 계정에서 받습니다. 토큰이 없으면 컨테이너가 시작 단계에서 멈춥니다. 둘 다 시험해 봤습니다. <code>latest</code> 태그 이미지(2026.10.7, 11월 11일 빌드)는 종료 코드 55로 끝나고, 마지막 커뮤니티 릴리스이자 LocalStack이 직접 고정해 쓰라고 권하는 버전인 4.12는 토큰 없이도 아직 시작됩니다.</p>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/localstack-needs-account.jpg" style="background:url('data:image/webp;base64,UklGRlYAAABXRUJQVlA4IEoAAABQBACdASogABIAPw10pUymIyGhKA1QxiGJ6QDJTPgAtfKr5WoM7/AUVx4AAP7ozNYDExNyKOZLAQjfzKlQvzdAcPxaBgAGLrjAAA==') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="터미널: localstack/localstack:latest가 &#39;License activation failed&#39;와 종료 코드 55로 끝나고, 이어서 localstack/localstack:4.12가 시작돼 헬스 체크에서 버전 4.12.0과 사용 가능한 S3를 보고함">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/localstack-needs-account.mp4" type="video/mp4">
  </video><figcaption>토큰 없이 띄운 LocalStack 최신 이미지, 그다음 버전을 고정한 4.12. 지금은 고정으로 버틸 수 있지만, 4.12에는 앞으로 수정이 나오지 않습니다.</figcaption>
</figure>

<p>AWS Emulator가 원하는 게 하나 있긴 합니다. 기본으로 켜져 있는 텔레메트리입니다. AWS는 요청, 코드, 자격 증명은 절대 포함되지 않는다고 하지만, 아무것도 보내지 않게 하고 싶다면 스위치가 세 가지 있습니다. 명령줄의 <code>--telemetry off</code>, 환경 변수 <code>EMULATOR_TELEMETRY=off</code>, 아니면 <code>~/.aws/emulator/config.toml</code>에 이렇게 적는 겁니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">telemetry</span><span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="nx">enabled</span> <span class="p">=</span> <span class="kc">false</span></span></span></code></pre></div></div>

<h2 class="relative group">macOS·Windows에서 Docker로 AWS Emulator 설정하기
    <div id="macoswindows에서-docker로-aws-emulator-설정하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#macoswindows%ec%97%90%ec%84%9c-docker%eb%a1%9c-aws-emulator-%ec%84%a4%ec%a0%95%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>Mac이나 Windows에서는 Docker로 갑니다. 빈 폴더에 아래 내용을 <code>Dockerfile</code>로 저장하세요. AWS가 직접 만든 것으로, <a href="https://docs.aws.amazon.com/emulator/latest/userguide/getting-started-docker.html"  target="_blank" rel="noreferrer">AWS의 Docker 가이드</a>에 있습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dockerfile" data-lang="dockerfile"><span class="line"><span class="cl"><span class="k">FROM</span><span class="w"> </span><span class="s">public.ecr.aws/amazonlinux/amazonlinux:2023-minimal</span><span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">ADD</span> https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpm<span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">RUN</span> rpm -i /tmp/aws-emulator.rpm <span class="o">&amp;&amp;</span> rm /tmp/aws-emulator.rpm <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="o">&amp;&amp;</span> mkdir -p /home/emulator <span class="o">&amp;&amp;</span> chown <span class="m">1000</span> /home/emulator<span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">USER</span><span class="w"> </span><span class="s">1000</span><span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">ENV</span> <span class="nv">HOME</span><span class="o">=</span>/home/emulator<span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">EXPOSE</span><span class="w"> </span><span class="s">9297</span><span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">ENTRYPOINT</span> <span class="p">[</span><span class="s2">&#34;aws-emulator&#34;</span><span class="p">,</span> <span class="s2">&#34;-b&#34;</span><span class="p">,</span> <span class="s2">&#34;0.0.0.0&#34;</span><span class="p">]</span></span></span></code></pre></div></div>
<p>Apple silicon이나 다른 ARM 머신에서는 <code>x86_64.rpm</code>을 <code>aarch64.rpm</code>으로 바꾸세요. 그다음 빌드하고 띄웁니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">docker build -t aws-emulator .
</span></span><span class="line"><span class="cl">mkdir -p ~/.aws/emulator
</span></span><span class="line"><span class="cl">docker run --rm -d --name aws-emulator --memory<span class="o">=</span>2g --memory-swap<span class="o">=</span>2g <span class="se">\
</span></span></span><span class="line"><span class="cl">  -p 127.0.0.1:9297:9297 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -e <span class="nv">HOME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$HOME</span><span class="s2">&#34;</span> -v <span class="s2">&#34;</span><span class="nv">$HOME</span><span class="s2">/.aws/emulator:</span><span class="nv">$HOME</span><span class="s2">/.aws/emulator&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  aws-emulator -p <span class="m">9297</span> --telemetry off</span></span></code></pre></div></div>
<p>제 Mac에서 빌드는 88초 걸렸고 이미지는 1.67 GB입니다. 이 <code>docker run</code> 줄에서 보기보다 중요한 부분이 세 군데 있습니다.</p>
<ul>
<li><strong><code>-p 9297:9297</code>이 아니라 <code>-p 127.0.0.1:9297:9297</code>.</strong> 짧게 쓰면 에뮬레이터가 네트워크 전체에 열립니다.</li>
<li><strong>볼륨과 <code>-e HOME</code>.</strong> 에뮬레이터는 시작할 때 <code>~/.aws/emulator/9297/</code>에 파일 네 개를 씁니다. 자격 증명, AWS <code>config</code> 파일, 인증서(<code>ca.pem</code>), 그리고 Java 트러스트 스토어입니다. 이 폴더를 컨테이너 안의 같은 경로에 마운트해야 호스트의 SDK가 그 파일들을 읽을 수 있습니다.</li>
<li><strong>포트가 세 번 나옵니다.</strong> 바꾼다면 전부 바꾸세요. 에뮬레이터는 그 파일들에 자기 포트를 적어 넣기 때문에, 폴더를 공유하는 컨테이너 두 개는 서로의 파일을 덮어씁니다.</li>
</ul>

<h2 class="relative group">Linux에 AWS Emulator 설치하기
    <div id="linux에-aws-emulator-설치하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#linux%ec%97%90-aws-emulator-%ec%84%a4%ec%b9%98%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>Linux에서는 Docker가 필요 없습니다. Debian 패키지와 RPM이 있습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Debian / Ubuntu (use aws-emulator_arm64.deb on ARM)</span>
</span></span><span class="line"><span class="cl">curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
</span></span><span class="line"><span class="cl">sudo apt-get install -y ./aws-emulator.deb
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Amazon Linux, Fedora, RHEL (aarch64.rpm on ARM)</span>
</span></span><span class="line"><span class="cl">sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">aws-emulator --telemetry off</span></span></code></pre></div></div>
<p>패키지는 150 MB입니다. <code>127.0.0.1:9297</code>에서 포그라운드로 돌고, 같은 파일 네 개를 <code>~/.aws/emulator/9297/</code>에 씁니다. Ctrl+C를 누르면 깔끔하게 멈추면서 그 파일들도 지웁니다. 테스트용으로 돌릴 때는 <code>--idle-timeout 900</code>을 붙이세요. 요청 없이 15분이 지나면 알아서 꺼지니까, 깜빡 잊은 에뮬레이터가 일주일 내내 떠 있을 일이 없습니다.</p>

<h2 class="relative group">AWS CLI와 boto3를 에뮬레이터에 연결하기
    <div id="aws-cli와-boto3를-에뮬레이터에-연결하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#aws-cli%ec%99%80-boto3%eb%a5%bc-%ec%97%90%eb%ae%ac%eb%a0%88%ec%9d%b4%ed%84%b0%ec%97%90-%ec%97%b0%ea%b2%b0%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>변수는 이렇습니다. 표준 AWS 환경 변수를 읽는 SDK라면 무엇이든 이걸 가져가니까, 테스트 대상 코드에는 엔드포인트도 키도 필요 없습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">E</span><span class="o">=</span>~/.aws/emulator/9297
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_ENDPOINT_URL</span><span class="o">=</span>https://127.0.0.1:9297
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_SHARED_CREDENTIALS_FILE</span><span class="o">=</span><span class="nv">$E</span>/emulator_credentials
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_CONFIG_FILE</span><span class="o">=</span><span class="nv">$E</span>/config
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_CA_BUNDLE</span><span class="o">=</span><span class="nv">$E</span>/ca.pem
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_REGION</span><span class="o">=</span>us-east-1
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_EC2_METADATA_DISABLED</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_DISABLE_HOST_PREFIX_INJECTION</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="nb">unset</span> AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s --cacert <span class="nv">$AWS_CA_BUNDLE</span> <span class="nv">$AWS_ENDPOINT_URL</span>/__admin/health   <span class="c1"># ok</span>
</span></span><span class="line"><span class="cl">aws sts get-caller-identity                                          <span class="c1"># 000000000000</span></span></span></code></pre></div></div>
<p>그러면 평범한 boto3가 그냥 동작합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">boto3</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">s3</span> <span class="o">=</span> <span class="n">boto3</span><span class="o">.</span><span class="n">client</span><span class="p">(</span><span class="s2">&#34;s3&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">s3</span><span class="o">.</span><span class="n">create_bucket</span><span class="p">(</span><span class="n">Bucket</span><span class="o">=</span><span class="s2">&#34;uploads&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="n">s3</span><span class="o">.</span><span class="n">list_buckets</span><span class="p">()[</span><span class="s2">&#34;Buckets&#34;</span><span class="p">])</span></span></span></code></pre></div></div>
<p>꼭 남겨 둘 줄은 <code>unset</code>입니다. 환경 변수가 자격 증명 파일보다 우선하기 때문에, 진짜 AWS 키가 아직 export돼 있으면 SDK는 그 키로 서명하고, 에뮬레이터는 요청을 거부하고, 여러분은 이유를 찾느라 10분을 날립니다. <code>aws sts get-caller-identity</code>는 빠르게 확인하기 좋습니다. 에뮬레이터는 항상 계정 <code>000000000000</code>이거든요. 자기 계정 번호가 보인다면 AWS와 이야기하고 있는 겁니다.</p>
<p>그 밖에 제가 부딪혔거나 부딪힐 뻔한 것들입니다.</p>
<ul>
<li><strong>엔드포인트에는 <code>localhost</code>가 아니라 <code>127.0.0.1</code>을 쓰세요.</strong> IP 주소면 SDK가 버킷 이름을 경로에 넣습니다. <code>localhost</code>면 JavaScript, Java, Go SDK가 버킷 이름을 호스트 이름으로 옮기는데(<code>uploads.localhost</code>), 에뮬레이터는 이걸 받지 않습니다.</li>
<li><strong>HTTPS 전용이고, 시작할 때마다 인증서가 새로 만들어집니다.</strong> boto3, AWS CLI, Go는 <code>AWS_CA_BUNDLE</code>을 읽습니다. Node는 같은 <code>ca.pem</code>을 가리키는 <code>NODE_EXTRA_CA_CERTS</code>가 필요하고, Java는 <code>JAVA_TOOL_OPTIONS</code>로 <code>truststore.p12</code>를 씁니다. <code>AWS_CA_BUNDLE</code>은 그 프로세스가 신뢰하는 인증서를 통째로 바꿔 버리기 때문에, 실제 HTTPS API도 호출하는 테스트라면 둘을 합친 번들이 필요합니다.</li>
<li><strong>리셋이 없습니다.</strong> 내용을 비워 주는 관리용 경로가 없으니, 테스트마다 버킷 이름을 따로 주거나 테스트 묶음 사이에 에뮬레이터를 재시작하세요.</li>
<li><strong>키는 시작할 때마다 바뀝니다.</strong> <code>.env</code> 파일에 복사해 두지 말고 자격 증명 파일을 가리키게 하세요.</li>
<li><strong>앱이 엔드포인트를 명시해서 자기 클라이언트를 따로 만든다면</strong>(예를 들어 django-storages의 <code>AWS_S3_ENDPOINT_URL</code>), 그 값도 <code>AWS_ENDPOINT_URL</code>에서 가져오게 하세요. 안 그러면 그 클라이언트 하나만 계속 실제 서비스와 이야기합니다.</li>
</ul>

<h2 class="relative group">Docker Compose로 AWS Emulator 실행하기
    <div id="docker-compose로-aws-emulator-실행하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#docker-compose%eb%a1%9c-aws-emulator-%ec%8b%a4%ed%96%89%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이미 <code>compose.yaml</code>이 있는 프로젝트라면 아래 서비스를 쓰면 됩니다. 위의 Dockerfile로 이미지를 빌드하고, 에뮬레이터 파일을 홈 디렉터리 대신 프로젝트 폴더에 두고, 헬스 체크도 있어서 <code>docker compose up --wait</code>가 준비가 끝난 뒤에 돌아옵니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">services</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">aws</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">build</span><span class="p">:</span><span class="w"> </span><span class="l">./aws-emulator           </span><span class="w"> </span><span class="c"># the folder with the Dockerfile</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;-p&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;9297&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;--telemetry&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;off&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;127.0.0.1:9297:9297&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">environment</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">HOME</span><span class="p">:</span><span class="w"> </span><span class="l">${PWD}/.aws-emulator-home</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">./.aws-emulator-home/.aws/emulator:${PWD}/.aws-emulator-home/.aws/emulator</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">mem_limit</span><span class="p">:</span><span class="w"> </span><span class="l">2g</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">healthcheck</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">test</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;CMD&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;curl&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;-sf&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;--cacert&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;${PWD}/.aws-emulator-home/.aws/emulator/9297/ca.pem&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">             </span><span class="s2">&#34;https://127.0.0.1:9297/__admin/health&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">interval</span><span class="p">:</span><span class="w"> </span><span class="l">1s</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">retries</span><span class="p">:</span><span class="w"> </span><span class="m">30</span></span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir -p .aws-emulator-home/.aws/emulator
</span></span><span class="line"><span class="cl">docker compose up -d --wait aws       <span class="c1"># healthy in about 5 s with the image already built</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">E</span><span class="o">=</span><span class="nv">$PWD</span>/.aws-emulator-home/.aws/emulator/9297   <span class="c1"># then the variables from above</span></span></span></code></pre></div></div>
<p><code>.aws-emulator-home/</code>은 <code>.gitignore</code>에 넣으세요. 그 실행의 키가 들어 있습니다.</p>

<h2 class="relative group">pytest에서 AWS Emulator 쓰기
    <div id="pytest에서-aws-emulator-쓰기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#pytest%ec%97%90%ec%84%9c-aws-emulator-%ec%93%b0%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>테스트 자체에는 에뮬레이터 전용 코드가 없습니다. 제가 더하는 건 안전장치 하나입니다. 제가 걱정하는 실패는 빨간 테스트가 아니라, 진짜 버킷을 상대로 돌고 초록색으로 끝난 테스트이기 때문입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># conftest.py</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">os</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">uuid</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">boto3</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">pytest</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nd"><span>@</span>pytest.fixture</span><span class="p">(</span><span class="n">scope</span><span class="o">=</span><span class="s2">&#34;session&#34;</span><span class="p">,</span> <span class="n">autouse</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">only_against_the_emulator</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">    <span class="n">url</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;AWS_ENDPOINT_URL&#34;</span><span class="p">,</span> <span class="s2">&#34;&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="ow">not</span> <span class="n">url</span><span class="o">.</span><span class="n">startswith</span><span class="p">((</span><span class="s2">&#34;https://127.0.0.1&#34;</span><span class="p">,</span> <span class="s2">&#34;http://127.0.0.1&#34;</span><span class="p">)):</span>
</span></span><span class="line"><span class="cl">        <span class="n">pytest</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;AWS_ENDPOINT_URL is </span><span class="si">{</span><span class="n">url</span><span class="si">!r}</span><span class="s2">; refusing to run against real AWS&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nd"><span>@</span>pytest.fixture</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">s3</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">boto3</span><span class="o">.</span><span class="n">client</span><span class="p">(</span><span class="s2">&#34;s3&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nd"><span>@</span>pytest.fixture</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">bucket</span><span class="p">(</span><span class="n">s3</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">name</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&#34;test-</span><span class="si">{</span><span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">()</span><span class="o">.</span><span class="n">hex</span><span class="p">[:</span><span class="mi">12</span><span class="p">]</span><span class="si">}</span><span class="s2">&#34;</span>   <span class="c1"># no reset route, so never reuse a name</span>
</span></span><span class="line"><span class="cl">    <span class="n">s3</span><span class="o">.</span><span class="n">create_bucket</span><span class="p">(</span><span class="n">Bucket</span><span class="o">=</span><span class="n">name</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">name</span></span></span></code></pre></div></div>
<p>그러면 테스트는 여느 테스트와 다를 게 없습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">os</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">requests</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">test_presigned_upload_rejects_the_wrong_content_type</span><span class="p">(</span><span class="n">s3</span><span class="p">,</span> <span class="n">bucket</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">url</span> <span class="o">=</span> <span class="n">s3</span><span class="o">.</span><span class="n">generate_presigned_url</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;put_object&#34;</span><span class="p">,</span> <span class="n">ExpiresIn</span><span class="o">=</span><span class="mi">300</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">Params</span><span class="o">=</span><span class="p">{</span><span class="s2">&#34;Bucket&#34;</span><span class="p">:</span> <span class="n">bucket</span><span class="p">,</span> <span class="s2">&#34;Key&#34;</span><span class="p">:</span> <span class="s2">&#34;media/a.jpg&#34;</span><span class="p">,</span> <span class="s2">&#34;ContentType&#34;</span><span class="p">:</span> <span class="s2">&#34;image/jpeg&#34;</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="sa">b</span><span class="s2">&#34;&lt;html&gt;&#34;</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="p">{</span><span class="s2">&#34;Content-Type&#34;</span><span class="p">:</span> <span class="s2">&#34;text/html&#34;</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">                     <span class="n">verify</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&#34;AWS_CA_BUNDLE&#34;</span><span class="p">])</span>
</span></span><span class="line"><span class="cl">    <span class="k">assert</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">403</span></span></span></code></pre></div></div>
<p>이건 제 마켓플레이스 앱의 업로드 흐름에서 가져온 테스트인데, 어떤 에뮬레이터를 고르느냐가 왜 중요한지 잘 보여 줍니다. 제가 시험한 다섯 개 중 세 개가 여기에 200을 돌려주거든요. 자세한 건 아래에서 다룹니다. 변경할 때마다 영향받는 테스트만 돌린다면 <a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-10-26-pytest-testmon/" >pytest-testmon</a>도 손대지 않고 그대로 함께 쓸 수 있습니다.</p>

<h2 class="relative group">GitHub Actions에서 AWS Emulator 실행하기
    <div id="github-actions에서-aws-emulator-실행하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#github-actions%ec%97%90%ec%84%9c-aws-emulator-%ec%8b%a4%ed%96%89%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>GitHub 러너에서는 Docker를 건너뛰고 Debian 패키지를 설치하세요. 한 스텝에서 띄운 백그라운드 프로세스는 잡이 끝날 때까지 계속 돕니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">jobs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">test</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/checkout@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">astral-sh/setup-uv@v10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Start AWS Emulator</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
</span></span></span><span class="line"><span class="cl"><span class="sd">          sudo apt-get install -y ./aws-emulator.deb
</span></span></span><span class="line"><span class="cl"><span class="sd">          aws-emulator --telemetry off --idle-timeout 900 &gt; emulator.log 2&gt;&amp;1 &amp;
</span></span></span><span class="line"><span class="cl"><span class="sd">          E=$HOME/.aws/emulator/9297
</span></span></span><span class="line"><span class="cl"><span class="sd">          for i in $(seq 30); do
</span></span></span><span class="line"><span class="cl"><span class="sd">            curl -sf --cacert $E/ca.pem https://127.0.0.1:9297/__admin/health &amp;&amp; break
</span></span></span><span class="line"><span class="cl"><span class="sd">            sleep 1
</span></span></span><span class="line"><span class="cl"><span class="sd">          done
</span></span></span><span class="line"><span class="cl"><span class="sd">          {
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_ENDPOINT_URL=https://127.0.0.1:9297&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_SHARED_CREDENTIALS_FILE=$E/emulator_credentials&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_CONFIG_FILE=$E/config&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_CA_BUNDLE=$E/ca.pem&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_REGION=us-east-1&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_EC2_METADATA_DISABLED=true&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_DISABLE_HOST_PREFIX_INJECTION=true&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">          } &gt;&gt; &#34;$GITHUB_ENV&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">uv run pytest</span></span></span></code></pre></div></div>
<p>같은 스텝을 새 <code>ubuntu:24.04</code> 컨테이너에서도 돌려 봤습니다(제 Mac이 ARM이라 arm64 패키지로요). 설치는 29초 걸렸는데 거의 전부가 150 MB 다운로드였고, 헬스 체크는 4초 안에 응답했습니다. 이 잡에는 실제 AWS 자격 증명을 아예 넣지 마세요. 잡 안의 무엇도 AWS에 닿지 않는다고 확신할 수 있는 가장 싼 방법입니다.</p>
<p><code>LTS/latest</code>는 마지막으로 릴리스된 버전을 가리키는데, 아래에서 보겠지만 이게 하루에도 몇 번씩 바뀝니다. CI를 재현 가능하게 하고 싶다면 AWS 문서에 <a href="https://docs.aws.amazon.com/emulator/latest/userguide/versioning.html"  target="_blank" rel="noreferrer">특정 버전을 설치하는 방법</a>이 나와 있습니다. 파이프라인의 나머지를 제가 어떻게 짜는지는 <a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-10-22-docker-compose-ci-github-actions/" >요즘 제가 돌리는 GitHub Actions 파이프라인</a>을 참고하세요.</p>

<h2 class="relative group">LocalStack에서 옮겨 오기
    <div id="localstack에서-옮겨-오기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#localstack%ec%97%90%ec%84%9c-%ec%98%ae%ea%b2%a8-%ec%98%a4%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이미 LocalStack으로 테스트를 돌리고 있다면, 옮기는 일은 대부분 설정입니다.</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>LocalStack</th>
					<th>AWS Emulator</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>엔드포인트</td>
					<td><code>http://localhost:4566</code></td>
					<td><code>https://127.0.0.1:9297</code>과 <code>AWS_CA_BUNDLE</code></td>
			</tr>
			<tr>
					<td>자격 증명</td>
					<td>아무거나 (<code>test</code> / <code>test</code>)</td>
					<td>실행할 때마다 쓰는 파일, 또는 <code>--auth off</code></td>
			</tr>
			<tr>
					<td>계정 ID</td>
					<td><code>000000000000</code></td>
					<td><code>000000000000</code></td>
			</tr>
			<tr>
					<td>설정 스크립트</td>
					<td><code>/etc/localstack/init/ready.d</code>의 init hook</td>
					<td>없음: 헬스 체크 뒤에 fixture에서 리소스 생성</td>
			</tr>
			<tr>
					<td>이미지</td>
					<td><code>localstack/localstack</code> (4.12 이후는 토큰 필요)</td>
					<td>AWS 패키지로 직접 빌드</td>
			</tr>
	</tbody>
</table>
<p>init hook을 많이 쓴다면 그 부분이 진짜로 손이 가는 곳입니다. 저는 테스트마다 버킷을 따로 만들어서 쓸 일이 없었습니다. 그리고 재시작하면 아무것도 남지 않습니다. 에뮬레이터는 전부 메모리에 들고 있으니까요.</p>

<h2 class="relative group">S3 로컬 테스트에서 AWS Emulator가 잡아낸 것과 놓친 것
    <div id="s3-로컬-테스트에서-aws-emulator가-잡아낸-것과-놓친-것" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#s3-%eb%a1%9c%ec%bb%ac-%ed%85%8c%ec%8a%a4%ed%8a%b8%ec%97%90%ec%84%9c-aws-emulator%ea%b0%80-%ec%9e%a1%ec%95%84%eb%82%b8-%ea%b2%83%ea%b3%bc-%eb%86%93%ec%b9%9c-%ea%b2%83" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>설정은 쉬운 부분입니다. 제가 알고 싶었던 건, 제 코드가 S3의 동작에 기대는 지점에서 이 에뮬레이터도 S3처럼 동작하느냐였습니다. 검사를 12개 썼고, 각각 AWS 문서에 적힌 실제 S3의 동작을 확인합니다.</p>
<ul>
<li><strong>마켓플레이스 앱의 업로드 흐름에서 6개.</strong> 앱이 브라우저에 presigned URL을 건네면, 브라우저가 사진을 버킷에 바로 PUT하고(그래서 버킷에 CORS가 필요합니다), <code>ObjectCreated</code> 이벤트가 파일이 도착했다고 백엔드에 알립니다. <a href="https://jared.lynskey.co.nz/ko/posts/2026/tigris-object-notifications/" >객체 알림에 관한 글</a>에서 다룬 흐름인데, 웹훅 자리에 SQS를 넣었습니다.</li>
<li><strong>Codemagic Patch 버킷에서 6개.</strong> Patch는 React Native 앱용 OTA 업데이트 서버입니다(<a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-09-13-moving-to-codemagic-patch/" >Patch로 옮겨 간 이야기</a>). 휴대폰이 번들을 내려받을 수 있도록 버킷은 공개인데, 업로드가 게시를 기다리는 <code>_internal/</code> 프리픽스만은 예외라서 버킷 정책으로 이 프리픽스를 비공개로 묶어 둡니다.</li>
</ul>
<p>이 검사들을 AWS Emulator 1.0.342(기본 상태로 한 번, <code>--auth off</code>로 한 번), LocalStack 4.12(기본 상태로, 그리고 <code>S3_SKIP_SIGNATURE_VALIDATION=0</code>으로), 서버 모드의 Moto 5.2.6, Floci 1.5.5, 그리고 Patch의 셀프 호스팅 번들이 쓰는 MinIO 포크인 Silo에 돌렸습니다.</p>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/s3-emulator-test-run.jpg" style="background:url('data:image/webp;base64,UklGRk4AAABXRUJQVlA4IEIAAAAQBACdASogABIAPw10rkymIyIhKAqoxiGJ6QDM0PgAtf/5Tl8J29EIQAD+6MzcUMCFo8DULSYQXf8FTN9rmZMAAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="터미널: 스크립트가 같은 S3 검사 12개를 에뮬레이터 설정 일곱 가지에 돌리고 통과/실패 표를 출력함. 모든 설정이 12개 중 6~8개 통과로 끝남">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/s3-emulator-test-run.mp4" type="video/mp4">
  </video><figcaption>실제로 돌린 결과입니다. 12개를 전부 통과한 건 없었습니다.</figcaption>
</figure>

<p>12개를 모두 통과한 구성은 없었고, 다들 6개에서 8개 사이였습니다. 합계보다 각자 어떤 검사를 놓쳤는지가 더 중요하니, 저한테 가장 아팠을 것부터 순서대로 적어 보겠습니다.</p>
<p><strong>AWS Emulator가 권한에는 가장 엄격합니다.</strong> 제 앱이 JPEG 한 장을 위해 서명해 주는 presigned URL을 예로 들어 보죠. 기본 설정의 LocalStack 4.12, Moto, Floci에서는 같은 URL로 HTML 파일을 올릴 수 있었고, 200이 돌아왔습니다. 공개 파일을 서빙하는 버킷이라면 저장형 XSS가 터지기를 기다리는 셈입니다. AWS Emulator는 S3처럼 403으로 거부했고, 만료된 URL도 다시 거부했습니다. (LocalStack 4.12는 <code>S3_SKIP_SIGNATURE_VALIDATION=0</code>을 설정하면 둘 다 잡고, Floci는 만료는 잡지만 바꿔치기한 파일 형식은 통과시킵니다.) 새 S3 버킷은 Block Public Access가 켜진 채로 만들어져서 그걸 끄기 전까지 공개 버킷 정책이 거부된다는 걸 아는 것도 이것뿐이었고, 명시적 <code>Deny</code>를 낯선 사람뿐 아니라 서버 자신의 서명된 요청에도 적용한 것도 이것뿐이었습니다. 모든 테스트를 통과하고 나서 첫 실제 배포에서 터지는 실수가 딱 이런 것들입니다.</p>
<p><strong>브라우저가 하는 일은 아직 테스트할 수 없습니다.</strong> CORS preflight(브라우저가 교차 출처 PUT 전에 보내는 <code>OPTIONS</code> 요청)는 <code>501 Not Implemented</code>를 받습니다. 기본값대로 인증이 켜져 있으면 서명 없는 요청도 전부 거부하기 때문에, 정책이 허용하더라도 공개 버킷에서의 익명 다운로드가 403을 받습니다. 두 빈틈 모두 이미 저장소에 등록돼 있습니다. 이 프로젝트는 알려진 빈틈을 <code>issues/things-that-do-not-work/</code> 아래에 파일로 관리하는데, 11월 13일 기준으로 6,840개가 있었고 13,409개는 이미 <code>things-that-now-work/</code>로 옮겨져 있었습니다.</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="GitHub의 things-that-do-not-work 폴더에 있는 AWS Emulator의 S3 이슈 파일, 제목은 &ldquo;7 net-new causes — CORS preflight answers 501…&rdquo;"
    width="1400"
    height="804"
    src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-cors-preflight-issue_hu_33033b091b284c0d.webp"
    srcset="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-cors-preflight-issue_hu_33033b091b284c0d.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-cors-preflight-issue_hu_f0294a8a0a022038.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-cors-preflight-issue_hu_925176ba1af6cb05.webp"></span><figcaption>프로젝트의 자체 이슈 탐색 에이전트가 11월 9일에 등록한 CORS 빈틈.</figcaption></figure>
</p>
<p><strong><code>--auth off</code>는 한쪽을 얻는 대신 다른 쪽을 내줍니다.</strong> 인증을 끄면 익명 읽기가 되고 버킷 정책도 제대로 평가돼서, Patch 검사 6개가 모두 통과합니다. 그걸 해낸 설정은 이것 하나뿐입니다. 하지만 presigned URL도 더는 검사하지 않아서 업로드 쪽 검사는 2개로 떨어집니다. 에뮬레이터 두 개를 다른 포트에 띄워 하나는 인증을 켜고 하나는 끄면 양쪽을 다 덮을 수 있지만, 다음에 CI 파일을 읽을 사람에게 설명할 거리가 하나 늘어나죠.</p>
<p><strong>변화가 빠릅니다.</strong> v1.0.290부터 v1.0.342까지의 릴리스가 사흘 만에 나왔고, 하나하나가 긴 수정 목록입니다(AWS 말로는 코딩 에이전트가 만들었다는데, 속도만 봐도 알 만합니다). 11월 11일 수정 가운데 하나는 S3의 &ldquo;presigned GET refused with 403&quot;이었습니다. 제 표의 어느 칸이든 다음 주면 어느 쪽으로든 달라져 있을 수 있습니다. CI에서는 버전을 고정하고, 올릴 때는 의식적으로 올리세요.</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="GitHub의 aws/aws-emulator 릴리스 페이지: 3시간 전에 나온 v1.0.342에 Latest 표시가 붙어 있고, 사이드바에 릴리스 9개가 더 보임"
    width="1600"
    height="1125"
    src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-releases_hu_e39a0eec6b783a7a.webp"
    srcset="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-releases_hu_e39a0eec6b783a7a.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-releases_hu_df197ee02b7c435c.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-releases_hu_59bd3abd9b9aaf92.webp"></span><figcaption>사흘에 릴리스 10개. 하나를 골라 고정하세요.</figcaption></figure>
</p>

<h2 class="relative group">Patch 버킷: 실제 S3에서만 문제가 되는 정책 조건 하나
    <div id="patch-버킷-실제-s3에서만-문제가-되는-정책-조건-하나" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#patch-%eb%b2%84%ed%82%b7-%ec%8b%a4%ec%a0%9c-s3%ec%97%90%ec%84%9c%eb%a7%8c-%eb%ac%b8%ec%a0%9c%ea%b0%80-%eb%90%98%eb%8a%94-%ec%a0%95%ec%b1%85-%ec%a1%b0%ea%b1%b4-%ed%95%98%eb%82%98" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>예상하지 못한 건 이 부분이었습니다. Patch의 셀프 호스팅 번들은 모든 걸 버킷 하나에 두고, 번들에 포함된 스토리지에 적용하는 정책도 뻔한 것입니다. 누구나 읽을 수 있되 <code>_internal/</code> 아래만 예외죠.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;Version&#34;</span><span class="p">:</span> <span class="s2">&#34;2012-10-17&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;Statement&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span> <span class="nt">&#34;Effect&#34;</span><span class="p">:</span> <span class="s2">&#34;Allow&#34;</span><span class="p">,</span> <span class="nt">&#34;Principal&#34;</span><span class="p">:</span> <span class="s2">&#34;*&#34;</span><span class="p">,</span> <span class="nt">&#34;Action&#34;</span><span class="p">:</span> <span class="s2">&#34;s3:GetObject&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;Resource&#34;</span><span class="p">:</span> <span class="s2">&#34;arn:aws:s3:::example-ota/*&#34;</span> <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span> <span class="nt">&#34;Effect&#34;</span><span class="p">:</span> <span class="s2">&#34;Deny&#34;</span><span class="p">,</span> <span class="nt">&#34;Principal&#34;</span><span class="p">:</span> <span class="s2">&#34;*&#34;</span><span class="p">,</span> <span class="nt">&#34;Action&#34;</span><span class="p">:</span> <span class="s2">&#34;s3:GetObject&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;Resource&#34;</span><span class="p">:</span> <span class="s2">&#34;arn:aws:s3:::example-ota/_internal/*&#34;</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>Silo에서 관리자 자격 증명으로 서명하면 이 정책은 적힌 그대로 동작합니다. 낯선 사람은 <code>_internal/</code>을 읽지 못하고, 서버가 직접 <code>_internal/</code>에서 공개 프리픽스로 하는 복사(&lsquo;게시&rsquo; 단계)는 통과합니다. 그런데 실제 S3에서는 <code>&quot;Principal&quot;: &quot;*&quot;</code>를 건 명시적 <code>Deny</code>가 여러분 자신의 자격 증명을 포함해 모두에게 적용되기 때문에, 같은 정책이 서버 자신의 게시 단계를 막아 버립니다. AWS Emulator는 그 복사를 403으로 거부했는데, AWS의 정책 평가 규칙에 따르면 S3가 하는 동작이 바로 그겁니다.</p>
<p>Patch 메인테이너들도 분명 이걸 알고 있습니다. <a href="https://github.com/codemagic-ci-cd/codemagic-patch/blob/main/deploy/selfhost/aws-s3-bucket-policy.example.json"  target="_blank" rel="noreferrer">AWS S3용 예시 정책</a>에서는 <code>Deny</code>에 조건을 하나 더 붙이거든요.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="s2">&#34;Condition&#34;</span><span class="err">:</span> <span class="p">{</span> <span class="nt">&#34;StringNotEquals&#34;</span><span class="p">:</span> <span class="p">{</span> <span class="nt">&#34;aws:PrincipalAccount&#34;</span><span class="p">:</span> <span class="s2">&#34;YOUR_AWS_ACCOUNT_ID&#34;</span> <span class="p">}</span> <span class="p">}</span></span></span></code></pre></div></div>
<p>이 줄이 있으면 AWS Emulator(익명 쪽도 테스트할 수 있게 <code>--auth off</code>로)와 Moto 둘 다 워커의 게시는 허용하면서 <code>_internal/</code> 익명 읽기는 여전히 거부합니다. 하지만 이 줄이 없는 버전을 잡아낸 건 AWS Emulator뿐이었습니다. Moto, LocalStack 4.12, Floci는 어느 쪽이든 복사를 통과시켰으니, 이 중 무엇을 썼어도 저는 망가진 정책을 그대로 배포했을 겁니다. 쓸 수 있는 가장 엄격한 에뮬레이터로 정책을 테스트해야 하는 이유로는 이게 제가 찾은 가장 분명한 사례입니다. MinIO 환경에서 쓰던 정책을 그 조건 없이 S3로 옮기면, 첫 실제 게시 전까지는 아무것도 문제를 알려 주지 않습니다.</p>
<p>(제 Patch 서버는 번들을 Tigris에 저장하는데, Tigris에는 버킷 정책이 아예 없어서 <code>_internal/</code>은 별도의 비공개 버킷에 둡니다. Patch 설정의 <code>S3_INTERNAL_BUCKET</code>이 그 용도입니다. 그리고 저는 Codemagic에 Patch에 관한 유료 기고 글도 씁니다. 이 글은 그런 글이 아니고, 누구에게서도 돈을 받지 않았습니다.)</p>

<h2 class="relative group">지금이라면 무엇을 쓸지
    <div id="지금이라면-무엇을-쓸지" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%a7%80%ea%b8%88%ec%9d%b4%eb%9d%bc%eb%a9%b4-%eb%ac%b4%ec%97%87%ec%9d%84-%ec%93%b8%ec%a7%80" aria-label="앵커">#</a>
    </span>
    
</h2>
<table>
	<thead>
			<tr>
					<th></th>
					<th>준비 시간</th>
					<th>유휴 메모리</th>
					<th>이미지</th>
					<th>계정</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>AWS Emulator 1.0.342</td>
					<td>0.4–0.5초</td>
					<td>176 MiB</td>
					<td>1.67 GB (직접 빌드)</td>
					<td>불필요</td>
			</tr>
			<tr>
					<td>LocalStack 4.12</td>
					<td>0.9–2.2초</td>
					<td>90 MiB</td>
					<td>1.89 GB</td>
					<td>4.12는 불필요, 이후 버전은 토큰 필요</td>
			</tr>
			<tr>
					<td>Moto 5.2.6 (서버)</td>
					<td>0.7–0.8초</td>
					<td>45 MiB</td>
					<td>560 MB</td>
					<td>불필요</td>
			</tr>
			<tr>
					<td>Floci 1.5.5</td>
					<td>0.3–0.4초</td>
					<td>11 MiB</td>
					<td>292 MB</td>
					<td>불필요</td>
			</tr>
	</tbody>
</table>
<p>제 Mac의 Docker에서 각각 콜드 스타트 세 번씩 잰 값입니다. 신경 쓸 만큼 느린 건 하나도 없습니다.</p>
<p>백엔드 테스트라면 저는 AWS Emulator로 시작하겠습니다. 이게 잡아내는 실수(권한, 서명, Block Public Access)는 이게 아니면 프로덕션에서야 드러나는 것들이고, 이 목록에서 무료이면서 최신이고 S3를 만드는 사람들이 직접 만든 건 이것뿐이니까요. CORS preflight가 구현되기 전까지는 브라우저 쪽 검사(preflight, 그리고 공개 프리픽스에서의 익명 다운로드)를 위한 작은 잡 하나를 Floci로 남겨 두겠습니다. 엄격한 서명 검사를 켠 LocalStack 4.12도 이 검사들을 통과하지만, 멈춰 있는 버전이라 수정이 나오지 않습니다. 테스트가 Python이고 컨테이너를 띄우고 싶지 않다면 여전히 Moto의 인프로세스 mock이 가장 가볍습니다. 다만 presigned URL 검사만큼은 Moto에 맡기지 마세요.</p>
<p>검사 12개는 오후 한나절이면 자기 버킷에 맞게 쓸 수 있을 만큼 짧습니다. 어떤 에뮬레이터든, 이것까지 포함해서, 믿기 전에 꼭 한번 해 보길 권합니다. 표에 나온 도구는 저마다 다른 검사에서 실패했고, 그게 바로 여러분의 테스트가 조용히 넘어가 버릴 빈틈입니다.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>S3에 직접 업로드하면서 이미지 압축도 놓치지 않기: Tigris 객체 알림과 Django</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2026/tigris-object-notifications/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2026/tigris-object-notifications/</guid>
      <pubDate>Sat, 07 Nov 2026 00:00:00 +1300</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Tigris</category>
      <category>S3</category>
      <category>S3 Event Notifications</category>
      <category>Presigned URLs</category>
      <category>Image Uploads</category>
      <category>Image Compression</category>
      <category>Object Storage</category>
      <category>Webhooks</category>
      <category>Django</category>
      <category>Fly.io</category>
      <category>Discord</category>
      <description>presigned URL로 S3에 직접 업로드하면 빠르지만, 파일이 도착했다는 걸 백엔드는 알 길이 없어서 이미지 압축과 썸네일 처리가 애매해집니다. Tigris 객체 알림이 그 빈틈을 메워 줍니다. 버킷이 Django 웹훅으로 POST를 보내고, 사용자가 아직 글을 쓰는 동안 사진이 처리되죠. 같은 신호로 로그 파일을 Discord 알림으로 바꾸기도 했습니다.</description>
      <content:encoded><![CDATA[<p>제가 만들어 본 이미지 업로드에는 늘 같은 긴장이 있었습니다. 올리는 사람은 사진이 빨리 올라가길 바랍니다. 저는 서버가 그 사진을 압축하고, 썸네일을 만들고, blurhash와 색상 몇 개를 뽑아내고, 있어서는 안 될 메타데이터를 떼어 내고, 앱의 나머지 부분이 기대하는 모양으로 저장해 주길 바라고요. 제 목록을 전부 채우는 가장 쉬운 길은 파일을 API로 보내는 것인데, 바로 그 길이 올리는 사람의 목록을 느리게 만듭니다.</p>
<p>빠른 쪽은 presigned URL(미리 서명된 URL)입니다. API가 URL에 서명해 주면 클라이언트가 파일을 버킷에 바로 PUT하고, 바이트는 API를 전혀 거치지 않습니다. 표준적인 답이고, 그럴 만한 이유가 있습니다. 그런데 이렇게 하는 순간 백엔드는 흐름에서 빠져 버립니다. URL을 하나 내주고 나서는 아무 소식도 못 듣죠. 파일이 도착했는지, 예상한 크기인지, 애초에 JPEG이 맞기는 한지. 누군가는 백엔드에 알려 줘야 하는데, 흔한 선택지는 하나같이 좀 서글픕니다. 클라이언트가 &ldquo;다 됐어요&quot;라고 다시 호출해 주길 믿거나(클라이언트는 거짓말하고, 죽고, 신호가 끊깁니다), 버킷을 주기적으로 폴링하거나(느리고 낭비죠), 첫 읽기 때 느긋하게 처리하거나(첫 방문자가 그 비용을 치르고, 파일을 언제부터 참조해도 안전한지는 여전히 모릅니다). S3 직접 업로드가 실제보다 어려워 보이는 이유가 이겁니다. 업로드 자체는 쉽습니다. 빠진 건 신호입니다.</p>
<p>객체 알림이 바로 그 신호입니다. 제가 Fly.io에서 쓰는 S3 호환 스토리지인 Tigris는 버킷에서 객체가 생성되거나 삭제될 때마다 작은 JSON 본문을 여러분의 앱에 POST해 줍니다. AWS에서 이에 해당하는 것이 S3 이벤트 알림인데, 보통은 Lambda나 SQS 큐, EventBridge를 먼저 엮어야 뭔가가 코드에 닿습니다(SNS가 HTTPS 엔드포인트로 POST를 보내 줄 수는 있지만, 그러면 구독 확인과 서명 검증부터 해야 하죠). Tigris는 이걸 여러분이 소유한 URL로 가는 HTTP 요청 하나로 줄였습니다. 스토리지에서 백엔드로 신호를 보내는 방법으로는 이보다 단순하기 어렵죠. 버킷이 백엔드와 이야기할 수 있도록, 여러분이 그 사이에 다리를 놓지 않아도 되도록 있는 기능입니다.</p>
<p>이 글은 그 흐름 전체를 다룹니다. 설정, 이벤트를 받는 Django 엔드포인트, 서버 쪽 처리를 하나도 포기하지 않는 presigned 업로드, 그리고 함정들(CORS, 크기 제한, 만료, 여러 파일)까지요. 마지막에는 같은 신호로 백오피스 일을 시킨 이야기도 있습니다. 버킷에 떨어지는 로그 파일이 Discord 알림이 됐고, 덕분에 몇 달 동안 달래 가며 쓰던 cron 작업 하나를 지울 수 있었습니다.</p>

<h2 class="relative group">짧은 답
    <div id="짧은-답" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%a7%a7%ec%9d%80-%eb%8b%b5" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>Tigris 대시보드에서 버킷을 열고 Settings, 그다음 Object notifications로 들어갑니다. 앱의 HTTPS URL을 넣고 Basic 인증을 고릅니다(Tigris가 <code>Authorization</code> 헤더에 담아 보내는 사용자 이름과 비밀번호입니다. 다른 선택지는 bearer 토큰이고요). 관심 있는 키만 듣도록 필터도 하나 겁니다. 필터는 SQL 비슷한 표현식이라서, &ldquo;이 글에서 다루는 프리픽스 세 개만&quot;은 이렇게 씁니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">WHERE</span><span class="w"> </span><span class="o">`</span><span class="k">key</span><span class="o">`</span><span class="w"> </span><span class="n">REGEXP</span><span class="w"> </span><span class="s2">&#34;^(uploads/raw|logs/api|media)/&#34;</span></span></span></code></pre></div></div>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="Tigris 버킷 설정의 Notifications 탭: 객체 알림 켜짐, 웹훅 URL, 사용자 이름과 비밀번호를 쓰는 Basic 인증, SQL 비슷한 키 필터"
    width="1204"
    height="671"
    src="https://jared.lynskey.co.nz/en/posts/2026/tigris-object-notifications/tigris-object-notifications-settings_hu_7e9da7c6ca1125db.webp"
    srcset="https://jared.lynskey.co.nz/en/posts/2026/tigris-object-notifications/tigris-object-notifications-settings_hu_7e9da7c6ca1125db.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/tigris-object-notifications/tigris-object-notifications-settings_hu_4ddc968851d1f052.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/tigris-object-notifications/tigris-object-notifications-settings_hu_4ddc968851d1f052.webp"></span><figcaption>설정은 이게 전부입니다. 앱의 HTTPS URL, Basic 인증, 그리고 키 필터. 여기 보이는 버킷 이름과 URL은 예시로 바꿔 둔 것입니다.</figcaption></figure>
</p>
<p>그러면 Tigris가 변경이 있을 때마다 이런 배치를 보냅니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;events&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;eventName&#34;</span><span class="p">:</span> <span class="s2">&#34;OBJECT_CREATED_PUT&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;eventTime&#34;</span><span class="p">:</span> <span class="s2">&#34;2026-11-07T09:12:44Z&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;bucket&#34;</span><span class="p">:</span> <span class="s2">&#34;example-bucket&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;object&#34;</span><span class="p">:</span> <span class="p">{</span> <span class="nt">&#34;key&#34;</span><span class="p">:</span> <span class="s2">&#34;uploads/raw/1f3c.jpg&#34;</span><span class="p">,</span> <span class="nt">&#34;size&#34;</span><span class="p">:</span> <span class="mi">48213</span><span class="p">,</span> <span class="nt">&#34;eTag&#34;</span><span class="p">:</span> <span class="s2">&#34;9b2c…&#34;</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>마주치게 될 이벤트 이름은 <code>OBJECT_CREATED_PUT</code>, <code>OBJECT_CREATED_MULTIPART</code>, <code>OBJECT_CREATED_COPY</code>, <code>OBJECT_DELETED</code>이고, 이름 변경과 스토리지 계층 전환 이벤트도 있습니다. 엔드포인트는 인증을 확인하고, 이벤트마다 키 프리픽스로 라우팅한 뒤, 10초 안에 2xx를 돌려주면 됩니다. 처음부터 염두에 둘 것이 세 가지 있습니다. 전달은 최소 한 번(at least once)이라 같은 이벤트를 다시 보게 되고, 이벤트는 배치로 오기 때문에 요청 하나에 여러 개가 실릴 수 있으며, 순서가 뒤바뀌어 도착할 수도 있으니 도착한 순서로 &ldquo;최신&quot;을 판단하면 안 됩니다.</p>

<h2 class="relative group">버킷 이벤트를 받는 Django 웹훅
    <div id="버킷-이벤트를-받는-django-웹훅" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%b2%84%ed%82%b7-%ec%9d%b4%eb%b2%a4%ed%8a%b8%eb%a5%bc-%eb%b0%9b%eb%8a%94-django-%ec%9b%b9%ed%9b%85" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>뷰는 일부러 지루하게 만들었습니다. 인증을 확인하고, 본문을 파싱하고, 이벤트를 하나씩 라우터에 넘깁니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">base64</span><span class="o">,</span> <span class="nn">hmac</span><span class="o">,</span> <span class="nn">json</span><span class="o">,</span> <span class="nn">logging</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.http</span> <span class="kn">import</span> <span class="n">JsonResponse</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.views.decorators.csrf</span> <span class="kn">import</span> <span class="n">csrf_exempt</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.views.decorators.http</span> <span class="kn">import</span> <span class="n">require_POST</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">.bucket_events</span> <span class="kn">import</span> <span class="n">handle</span><span class="p">,</span> <span class="n">parse</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">_authorised</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">secret</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="n">header</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;Authorization&#34;</span><span class="p">,</span> <span class="s2">&#34;&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="ow">not</span> <span class="n">header</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">&#34;Basic &#34;</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="kc">False</span>
</span></span><span class="line"><span class="cl">    <span class="k">try</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="n">user</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">password</span> <span class="o">=</span> <span class="n">base64</span><span class="o">.</span><span class="n">b64decode</span><span class="p">(</span><span class="n">header</span><span class="p">[</span><span class="mi">6</span><span class="p">:])</span><span class="o">.</span><span class="n">decode</span><span class="p">()</span><span class="o">.</span><span class="n">partition</span><span class="p">(</span><span class="s2">&#34;:&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">except</span> <span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="ne">UnicodeDecodeError</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="kc">False</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">hmac</span><span class="o">.</span><span class="n">compare_digest</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">encode</span><span class="p">(),</span> <span class="sa">b</span><span class="s2">&#34;tigris&#34;</span><span class="p">)</span> <span class="ow">and</span> <span class="n">hmac</span><span class="o">.</span><span class="n">compare_digest</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="n">password</span><span class="o">.</span><span class="n">encode</span><span class="p">(),</span> <span class="n">secret</span><span class="o">.</span><span class="n">encode</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nd">@csrf_exempt</span>
</span></span><span class="line"><span class="cl"><span class="nd">@require_POST</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">bucket_webhook</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">secret</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">BUCKET_WEBHOOK_SECRET</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="ow">not</span> <span class="n">secret</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">JsonResponse</span><span class="p">({</span><span class="s2">&#34;error&#34;</span><span class="p">:</span> <span class="s2">&#34;not configured&#34;</span><span class="p">},</span> <span class="n">status</span><span class="o">=</span><span class="mi">503</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="ow">not</span> <span class="n">_authorised</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">secret</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">JsonResponse</span><span class="p">({</span><span class="s2">&#34;error&#34;</span><span class="p">:</span> <span class="s2">&#34;unauthorised&#34;</span><span class="p">},</span> <span class="n">status</span><span class="o">=</span><span class="mi">401</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">try</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="n">body</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">body</span> <span class="ow">or</span> <span class="sa">b</span><span class="s2">&#34;</span><span class="si">{}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">JsonResponse</span><span class="p">({</span><span class="s2">&#34;error&#34;</span><span class="p">:</span> <span class="s2">&#34;invalid json&#34;</span><span class="p">},</span> <span class="n">status</span><span class="o">=</span><span class="mi">400</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">event</span> <span class="ow">in</span> <span class="n">parse</span><span class="p">(</span><span class="n">body</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">try</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="n">handle</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="n">logger</span><span class="o">.</span><span class="n">exception</span><span class="p">(</span><span class="s2">&#34;bucket event failed: </span><span class="si">%s</span><span class="s2">&#34;</span><span class="p">,</span> <span class="n">event</span><span class="o">.</span><span class="n">key</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">JsonResponse</span><span class="p">({</span><span class="s2">&#34;ok&#34;</span><span class="p">:</span> <span class="kc">True</span><span class="p">})</span></span></span></code></pre></div></div>
<p><code>compare_digest</code>를 쓴 건 무엇을 보내든 확인에 걸리는 시간이 같게 하려는 겁니다(바이트로 비교하는 이유는, 문자열로 비교하면 ASCII가 아닌 입력에서 예외가 나서 조작된 헤더가 401 대신 500을 받기 때문입니다). 갓 만든 스테이징 서버처럼 시크릿이 설정돼 있지 않으면, 엔드포인트는 전부 받아들이는 대신 전부 거부합니다. 그리고 핸들러가 예외를 던져도 로그만 남기고 200을 돌려줍니다. Tigris는 2xx가 아니면 전부 재시도하는데, 재시도해 봐야 같은 버그에 부딪힐 테고, 그때쯤이면 이벤트는 이미 선점돼 있어서(두 섹션 아래에 나옵니다) 재시도가 아무 일도 하지 않을 테니까요. 고치게 만드는 건 그 로그 한 줄입니다. 다만 이건 실패가 매번 똑같이 재현된다는 가정 위에 서 있습니다. 스토리지가 잠깐 타임아웃된 거라면 그 이벤트는 영영 소비돼 버립니다. 사진은 상관없습니다. 저장 요청이 직접 처리할 수 있으니까요. 하지만 로그 파일 쪽 알림은 그대로 잃어버리게 됩니다. 그게 중요하다면 <code>except</code>에서 선점을 풀고 500을 돌려줘 Tigris가 재시도하게 하세요. 대신 진짜 버그는 고칠 때까지 계속 재시도된다는 건 감수해야 하고요.</p>

<h2 class="relative group">프리픽스로 라우팅하기
    <div id="프리픽스로-라우팅하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%94%84%eb%a6%ac%ed%94%bd%ec%8a%a4%eb%a1%9c-%eb%9d%bc%ec%9a%b0%ed%8c%85%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>버킷 안의 모든 것이 이미 프리픽스별로 정리돼 있으니, 라우팅도 그걸 기준으로 하는 게 자연스럽습니다. 용도 하나가 함수 하나, 테이블 한 줄입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">HANDLERS</span> <span class="o">=</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="p">(</span><span class="s2">&#34;uploads/raw/&#34;</span><span class="p">,</span>   <span class="n">on_raw_photo</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">    <span class="p">(</span><span class="s2">&#34;logs/api/&#34;</span><span class="p">,</span>      <span class="n">on_api_log_file</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">    <span class="p">(</span><span class="s2">&#34;media/&#34;</span><span class="p">,</span>         <span class="n">on_media_change</span><span class="p">),</span>
</span></span><span class="line"><span class="cl"><span class="p">]</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">handle</span><span class="p">(</span><span class="n">event</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">prefix</span><span class="p">,</span> <span class="n">fn</span> <span class="ow">in</span> <span class="n">HANDLERS</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">prefix</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">            <span class="k">if</span> <span class="n">claim</span><span class="p">(</span><span class="n">event</span><span class="p">):</span>  <span class="c1"># 아래 참고</span>
</span></span><span class="line"><span class="cl">                <span class="n">fn</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span></span></span></code></pre></div></div>
<p>나중에 네 번째 용도를 추가하려면 함수 하나와 행 하나만 더하면 됩니다. 이게 생각보다 마음에 들더군요.</p>

<h2 class="relative group">최소 한 번은 &ldquo;두 번일 수도 있다&quot;는 뜻
    <div id="최소-한-번은-두-번일-수도-있다는-뜻" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%b5%9c%ec%86%8c-%ed%95%9c-%eb%b2%88%ec%9d%80-%eb%91%90-%eb%b2%88%ec%9d%bc-%ec%88%98%eb%8f%84-%ec%9e%88%eb%8b%a4%eb%8a%94-%eb%9c%bb" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>엔드포인트가 느리거나 에러를 돌려주면 Tigris는 재시도합니다. 그리고 대부분의 웹훅 발신자가 그렇듯, 이벤트를 딱 한 번만 받는다는 보장은 해 주지 않습니다. 그래서 핸들러가 돌기 전에 <code>(key, eTag, eventName)</code> 기준으로 이벤트를 선점합니다. 여기서 eTag가 중요합니다. 파일이 덮어써지면 eTag가 바뀐 새 버전이니 다시 처리해야 합니다. 같은 버전이 반복해서 온 거라면 처리하면 안 되고요.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.core.cache</span> <span class="kn">import</span> <span class="n">cache</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">claim</span><span class="p">(</span><span class="n">event</span><span class="p">,</span> <span class="n">ttl</span><span class="o">=</span><span class="mi">7</span> <span class="o">*</span> <span class="mi">24</span> <span class="o">*</span> <span class="mi">3600</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="n">k</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&#34;bucket-event:</span><span class="si">{</span><span class="n">event</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">:</span><span class="si">{</span><span class="n">event</span><span class="o">.</span><span class="n">key</span><span class="si">}</span><span class="s2">:</span><span class="si">{</span><span class="n">event</span><span class="o">.</span><span class="n">etag</span><span class="si">}</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">cache</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">k</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">ttl</span><span class="p">)</span>  <span class="c1"># 이미 누가 선점했으면 False</span></span></span></code></pre></div></div>
<p><code>cache.add</code>는 키가 없을 때만 값을 넣고, Redis에서는 이게 원자적으로 처리됩니다. 그래서 같은 재시도를 받은 머신 두 대가 둘 다 이길 수는 없습니다. 실제 코드에서는 Redis가 비워져도 살아남게 하고 싶어서 데이터베이스 기반 리스(lease)를 쓰지만, 아이디어는 똑같습니다.</p>

<h2 class="relative group">이미지는 S3에 직접 업로드, 파이프라인은 그대로
    <div id="이미지는-s3에-직접-업로드-파이프라인은-그대로" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%9d%b4%eb%af%b8%ec%a7%80%eb%8a%94-s3%ec%97%90-%ec%a7%81%ec%a0%91-%ec%97%85%eb%a1%9c%eb%93%9c-%ed%8c%8c%ec%9d%b4%ed%94%84%eb%9d%bc%ec%9d%b8%ec%9d%80-%ea%b7%b8%eb%8c%80%eb%a1%9c" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이 배관 작업이 제값을 하는 부분이 여기입니다.</p>
<p>예전에는 게시글에 넣을 사진을 고르면 앱이 들고 있다가, &lsquo;게시&rsquo;를 누르는 순간 전부 base64로 API에 보냈습니다. API가 리사이즈하고, 썸네일을 만들고, 색상과 blurhash를 계산한 다음에야 응답했죠. 느린 회선에서 사진 열 장이면 스피너가 한참 돌았습니다. 그리고 base64 사진 열 장을 실은 요청은 API 서버가 메모리에 들고 있기엔 크고 느린 본문이라, 사실 제가 사진을 작게 유지해 온 조용한 이유도 그거였습니다.</p>
<p>이제는 네 단계로 나뉘고, 백엔드는 단계마다 소식을 듣습니다.</p>

<h3 class="relative group">1. 클라이언트가 사진을 줄이고 슬롯을 요청한다
    <div id="1-클라이언트가-사진을-줄이고-슬롯을-요청한다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#1-%ed%81%b4%eb%9d%bc%ec%9d%b4%ec%96%b8%ed%8a%b8%ea%b0%80-%ec%82%ac%ec%a7%84%ec%9d%84-%ec%a4%84%ec%9d%b4%ea%b3%a0-%ec%8a%ac%eb%a1%af%ec%9d%84-%ec%9a%94%ec%b2%ad%ed%95%9c%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>앱은 여전히 기기에서 리사이즈합니다. 서버가 보관하는 긴 변 길이(1080px)에 맞춰 품질 0.7의 JPEG로요. 이 리사이즈는 오로지 사용자의 대역폭을 위한 것이고, 다른 이유는 없습니다. 그다음 API에 업로드 슬롯을 요청합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">uuid</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">timedelta</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">boto3</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.utils</span> <span class="kn">import</span> <span class="n">timezone</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">s3</span> <span class="o">=</span> <span class="n">boto3</span><span class="o">.</span><span class="n">client</span><span class="p">(</span><span class="s2">&#34;s3&#34;</span><span class="p">,</span> <span class="n">endpoint_url</span><span class="o">=</span><span class="s2">&#34;https://fly.storage.tigris.dev&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">BUCKET</span> <span class="o">=</span> <span class="s2">&#34;example-bucket&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">create_upload_slot</span><span class="p">(</span><span class="n">user</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">public_id</span> <span class="o">=</span> <span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="n">key</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&#34;uploads/raw/</span><span class="si">{</span><span class="n">public_id</span><span class="si">}</span><span class="s2">.jpg&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">upload</span> <span class="o">=</span> <span class="n">PhotoUpload</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">create</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="n">user</span><span class="o">=</span><span class="n">user</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">public_id</span><span class="o">=</span><span class="n">public_id</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">raw_key</span><span class="o">=</span><span class="n">key</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">expires_at</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">now</span><span class="p">()</span> <span class="o">+</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">2</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">url</span> <span class="o">=</span> <span class="n">s3</span><span class="o">.</span><span class="n">generate_presigned_url</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;put_object&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">Params</span><span class="o">=</span><span class="p">{</span><span class="s2">&#34;Bucket&#34;</span><span class="p">:</span> <span class="n">BUCKET</span><span class="p">,</span> <span class="s2">&#34;Key&#34;</span><span class="p">:</span> <span class="n">key</span><span class="p">,</span> <span class="s2">&#34;ContentType&#34;</span><span class="p">:</span> <span class="s2">&#34;image/jpeg&#34;</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">        <span class="n">ExpiresIn</span><span class="o">=</span><span class="mi">15</span> <span class="o">*</span> <span class="mi">60</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;upload_id&#34;</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">upload</span><span class="o">.</span><span class="n">public_id</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;url&#34;</span><span class="p">:</span> <span class="n">url</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;method&#34;</span><span class="p">:</span> <span class="s2">&#34;PUT&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;headers&#34;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&#34;Content-Type&#34;</span><span class="p">:</span> <span class="s2">&#34;image/jpeg&#34;</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;expires_in&#34;</span><span class="p">:</span> <span class="mi">15</span> <span class="o">*</span> <span class="mi">60</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span></span></span></code></pre></div></div>
<p>슬롯은 파일이기 전에 먼저 행(row)입니다. 그 덕분에 서버는 누가 요청했는지, 언제 만료되는지, 나중에는 실제로 쓰였는지까지 알 수 있습니다.</p>

<h3 class="relative group">2. 클라이언트가 버킷에 바로 PUT한다
    <div id="2-클라이언트가-버킷에-바로-put한다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#2-%ed%81%b4%eb%9d%bc%ec%9d%b4%ec%96%b8%ed%8a%b8%ea%b0%80-%eb%b2%84%ed%82%b7%ec%97%90-%eb%b0%94%eb%a1%9c-put%ed%95%9c%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ts" data-lang="ts"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">slot</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">api</span><span class="p">.</span><span class="nx">post</span><span class="p">(</span><span class="s2">&#34;/photo-uploads/&#34;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">res</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">fetch</span><span class="p">(</span><span class="nx">slot</span><span class="p">.</span><span class="nx">url</span><span class="p">,</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">method</span>: <span class="kt">slot.method</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">headers</span>: <span class="kt">slot.headers</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">body</span>: <span class="kt">blob</span><span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="p">});</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">res</span><span class="p">.</span><span class="nx">ok</span><span class="p">)</span> <span class="k">throw</span> <span class="k">new</span> <span class="nb">Error</span><span class="p">(</span><span class="s2">&#34;upload refused&#34;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="c1">// 저장할 때 쓰도록 slot.upload_id를 보관
</span></span></span></code></pre></div></div>
<p>API는 바이트를 구경도 못 합니다. 브라우저든 React Native든 네이티브 앱이든 똑같고, 유일한 차이는 브라우저에는 버킷에 CORS 규칙이 필요하다는 점입니다. 아래 함정 섹션에 있습니다.</p>

<h3 class="relative group">3. Tigris가 백엔드에 알리고, 파이프라인이 돈다
    <div id="3-tigris가-백엔드에-알리고-파이프라인이-돈다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#3-tigris%ea%b0%80-%eb%b0%b1%ec%97%94%eb%93%9c%ec%97%90-%ec%95%8c%eb%a6%ac%ea%b3%a0-%ed%8c%8c%ec%9d%b4%ed%94%84%eb%9d%bc%ec%9d%b8%ec%9d%b4-%eb%8f%88%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>몇 초 안에 Tigris가 <code>uploads/raw/…</code>에 대한 <code>OBJECT_CREATED_PUT</code>을 보내고, 핸들러는 base64 경로가 늘 쓰던 것과 같은 이미지 파이프라인을 돌립니다. 사용자가 아직 제목을 입력하는 동안에요.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">io</span> <span class="kn">import</span> <span class="n">BytesIO</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">PIL</span> <span class="kn">import</span> <span class="n">Image</span><span class="p">,</span> <span class="n">ImageOps</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.core.files.base</span> <span class="kn">import</span> <span class="n">ContentFile</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.utils</span> <span class="kn">import</span> <span class="n">timezone</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">blurhash</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">MAX_BYTES</span> <span class="o">=</span> <span class="mi">15</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">on_raw_photo</span><span class="p">(</span><span class="n">event</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="ow">not</span> <span class="n">event</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">&#34;OBJECT_CREATED&#34;</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">size</span> <span class="o">&gt;</span> <span class="n">MAX_BYTES</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="n">s3</span><span class="o">.</span><span class="n">delete_object</span><span class="p">(</span><span class="n">Bucket</span><span class="o">=</span><span class="n">event</span><span class="o">.</span><span class="n">bucket</span><span class="p">,</span> <span class="n">Key</span><span class="o">=</span><span class="n">event</span><span class="o">.</span><span class="n">key</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span>
</span></span><span class="line"><span class="cl">    <span class="n">upload</span> <span class="o">=</span> <span class="n">PhotoUpload</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">raw_key</span><span class="o">=</span><span class="n">event</span><span class="o">.</span><span class="n">key</span><span class="p">,</span> <span class="n">processed_at</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span><span class="o">.</span><span class="n">first</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">upload</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span>
</span></span><span class="line"><span class="cl">    <span class="n">data</span> <span class="o">=</span> <span class="n">s3</span><span class="o">.</span><span class="n">get_object</span><span class="p">(</span><span class="n">Bucket</span><span class="o">=</span><span class="n">event</span><span class="o">.</span><span class="n">bucket</span><span class="p">,</span> <span class="n">Key</span><span class="o">=</span><span class="n">event</span><span class="o">.</span><span class="n">key</span><span class="p">)[</span><span class="s2">&#34;Body&#34;</span><span class="p">]</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="n">process</span><span class="p">(</span><span class="n">upload</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">to_webp</span><span class="p">(</span><span class="n">im</span><span class="p">,</span> <span class="n">longest</span><span class="p">,</span> <span class="n">quality</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">im</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="n">im</span><span class="o">.</span><span class="n">thumbnail</span><span class="p">((</span><span class="n">longest</span><span class="p">,</span> <span class="n">longest</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">    <span class="n">buf</span> <span class="o">=</span> <span class="n">BytesIO</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="n">im</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="s2">&#34;WEBP&#34;</span><span class="p">,</span> <span class="n">quality</span><span class="o">=</span><span class="n">quality</span><span class="p">,</span> <span class="n">icc_profile</span><span class="o">=</span><span class="n">im</span><span class="o">.</span><span class="n">info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;icc_profile&#34;</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">ContentFile</span><span class="p">(</span><span class="n">buf</span><span class="o">.</span><span class="n">getvalue</span><span class="p">())</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">process</span><span class="p">(</span><span class="n">upload</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="k">with</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">BytesIO</span><span class="p">(</span><span class="n">data</span><span class="p">))</span> <span class="k">as</span> <span class="n">im</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="n">im</span> <span class="o">=</span> <span class="n">ImageOps</span><span class="o">.</span><span class="n">exif_transpose</span><span class="p">(</span><span class="n">im</span><span class="p">)</span><span class="o">.</span><span class="n">convert</span><span class="p">(</span><span class="s2">&#34;RGB&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="n">im</span><span class="o">.</span><span class="n">thumbnail</span><span class="p">((</span><span class="mi">1080</span><span class="p">,</span> <span class="mi">1080</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">        <span class="n">upload</span><span class="o">.</span><span class="n">width</span><span class="p">,</span> <span class="n">upload</span><span class="o">.</span><span class="n">height</span> <span class="o">=</span> <span class="n">im</span><span class="o">.</span><span class="n">size</span>
</span></span><span class="line"><span class="cl">        <span class="n">upload</span><span class="o">.</span><span class="n">dominant_color</span> <span class="o">=</span> <span class="s2">&#34;#</span><span class="si">%02x%02x%02x</span><span class="s2">&#34;</span> <span class="o">%</span> <span class="n">im</span><span class="o">.</span><span class="n">resize</span><span class="p">((</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">))</span><span class="o">.</span><span class="n">getpixel</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">        <span class="n">upload</span><span class="o">.</span><span class="n">image</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="n">upload</span><span class="o">.</span><span class="n">public_id</span><span class="si">}</span><span class="s2">.webp&#34;</span><span class="p">,</span> <span class="n">to_webp</span><span class="p">(</span><span class="n">im</span><span class="p">,</span> <span class="mi">1080</span><span class="p">,</span> <span class="mi">80</span><span class="p">),</span> <span class="n">save</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="n">upload</span><span class="o">.</span><span class="n">thumbnail</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="n">upload</span><span class="o">.</span><span class="n">public_id</span><span class="si">}</span><span class="s2">_t.webp&#34;</span><span class="p">,</span> <span class="n">to_webp</span><span class="p">(</span><span class="n">im</span><span class="p">,</span> <span class="mi">320</span><span class="p">,</span> <span class="mi">70</span><span class="p">),</span> <span class="n">save</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="n">upload</span><span class="o">.</span><span class="n">blurhash</span> <span class="o">=</span> <span class="n">blurhash</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">im</span><span class="o">.</span><span class="n">resize</span><span class="p">((</span><span class="mi">32</span><span class="p">,</span> <span class="mi">32</span><span class="p">)),</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">upload</span><span class="o">.</span><span class="n">processed_at</span> <span class="o">=</span> <span class="n">timezone</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="n">upload</span><span class="o">.</span><span class="n">save</span><span class="p">()</span></span></span></code></pre></div></div>
<p><code>on_raw_photo</code>의 첫 줄은 보기보다 중요합니다. 라우터는 <code>uploads/raw/</code> 아래의 모든 이벤트를 여기로 보내는데, 고아 정리 작업과 크기 검사 자체가 만들어 내는 삭제 이벤트까지 포함해서요. 이미 사라진 키에 <code>get_object</code>를 하면 예외만 날 뿐입니다.</p>
<p>그러니 클라이언트에서 줄인 건 처음부터 끝까지 전송로를 위한 것이었습니다. 포맷(WebP), 크기, 썸네일, 플레이스홀더, 저장할 치수는 여전히 서버가 정합니다. Pillow로 다시 인코딩하면 EXIF 블록도 떨어져 나가는데, 휴대폰 카메라가 GPS 위치를 넣어 두는 곳이 바로 거기라서 개인정보 제거는 덤으로 따라옵니다. ICC 프로필도 같은 식으로 사라질 텐데, 그러면 광색역(wide-gamut) 휴대폰 사진의 색이 살짝 틀어지기 때문에 <code>to_webp</code>는 이걸 그대로 넘겨 줍니다. 픽셀 하나 손대지 않은 원본을 보관하고 싶다면 클라이언트에서 줄이지 않으면 됩니다. 흐름은 똑같고 PUT만 커지는데, 큰 PUT이야말로 이 설계가 싸게 만들어 주는 바로 그것이니까요. 한 가지 걸리는 점은, iPhone 원본은 HEIC라서 Pillow가 <code>pillow-heif</code>를 설치해야만 열 수 있다는 겁니다.</p>

<h3 class="relative group">4. 저장은 사진을 붙이기만 하고, 웹훅을 기다리지 않는다
    <div id="4-저장은-사진을-붙이기만-하고-웹훅을-기다리지-않는다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#4-%ec%a0%80%ec%9e%a5%ec%9d%80-%ec%82%ac%ec%a7%84%ec%9d%84-%eb%b6%99%ec%9d%b4%ea%b8%b0%eb%a7%8c-%ed%95%98%ea%b3%a0-%ec%9b%b9%ed%9b%85%ec%9d%84-%ea%b8%b0%eb%8b%a4%eb%a6%ac%ec%a7%80-%ec%95%8a%eb%8a%94%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>&lsquo;게시&rsquo;를 누르면 요청에는 이미지 데이터 대신 <code>upload_ids</code>가 실려 갑니다. 서버는 이를 하나씩 찾아보고, 결과는 세 가지 중 하나입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">take</span><span class="p">(</span><span class="n">user</span><span class="p">,</span> <span class="n">upload_ids</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">uploads</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">PhotoUpload</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="n">user</span><span class="o">=</span><span class="n">user</span><span class="p">,</span> <span class="n">public_id__in</span><span class="o">=</span><span class="n">upload_ids</span><span class="p">,</span> <span class="n">expires_at__gt</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="p">))</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">uploads</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="n">upload_ids</span><span class="p">)):</span>     <span class="c1"># 만료됐거나 이 사용자의 것이 아님</span>
</span></span><span class="line"><span class="cl">        <span class="k">raise</span> <span class="n">UploadNotReadyError</span><span class="p">(</span><span class="n">upload_ids</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">upload</span> <span class="ow">in</span> <span class="n">uploads</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">upload</span><span class="o">.</span><span class="n">processed_at</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>          <span class="c1"># 웹훅이 아직 도착하지 않음</span>
</span></span><span class="line"><span class="cl">            <span class="n">data</span> <span class="o">=</span> <span class="n">read_raw</span><span class="p">(</span><span class="n">upload</span><span class="p">)</span>              <span class="c1"># PUT이 안 됐으면 None</span>
</span></span><span class="line"><span class="cl">            <span class="k">if</span> <span class="n">data</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">                <span class="k">raise</span> <span class="n">UploadNotReadyError</span><span class="p">(</span><span class="n">upload</span><span class="o">.</span><span class="n">public_id</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="n">process</span><span class="p">(</span><span class="n">upload</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">uploads</span></span></span></code></pre></div></div>
<p>알림이 이미 처리를 마쳤다면 처리된 파일을 그대로 붙입니다. 파일은 버킷에 있는데 알림이 아직 안 왔다면, 저장 요청이 그 자리에서 인라인으로 처리합니다. 그래서 게시글이 웹훅을 기다리는 일은 없습니다. 알림은 의존성이 아니라 먼저 출발할 기회일 뿐이죠. 파일이 아예 없거나, id가 만료됐거나 다른 사람의 것이라면 저장은 검증 에러를 돌려주고 앱이 잠시 후 재시도합니다. 앱은 자기 PUT이 끝나길 기다린 뒤에 보내니까, 실제로는 드문 일입니다.</p>
<p>제대로 버티게 해 준 디테일이 몇 가지 있습니다. 슬롯은 사용자 소유라서 서버는 같은 사람이 만든 업로드 id만 받습니다. 그렇지 않으면 id를 본 누구든 남의 사진을 자기 게시글에 붙일 수 있으니까요. 모든 경로에 대체 수단이 있습니다. 슬롯 요청이 실패하거나, PUT이 거부되거나, API가 구버전이면 앱은 예전과 똑같이 base64를 보냅니다. 업로드 경로를 타는 건 새 사진 전부에 슬롯이 있을 때뿐이라서, 게시글 하나의 사진은 전부 업로드이거나 전부 base64이고, 순서도 목록 하나로 유지됩니다. 그리고 고아 업로드는 만료됩니다. 사진을 골라 놓고 그만두는 사람도 있어서, 어디에도 붙지 않은 업로드는 이틀 뒤에 만료되고 기존의 고아 미디어 정리 작업이 파일을 치웁니다.</p>

<h2 class="relative group">presigned URL 업로드의 함정: CORS, 크기 제한, 만료, 여러 파일
    <div id="presigned-url-업로드의-함정-cors-크기-제한-만료-여러-파일" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#presigned-url-%ec%97%85%eb%a1%9c%eb%93%9c%ec%9d%98-%ed%95%a8%ec%a0%95-cors-%ed%81%ac%ea%b8%b0-%ec%a0%9c%ed%95%9c-%eb%a7%8c%eb%a3%8c-%ec%97%ac%eb%9f%ac-%ed%8c%8c%ec%9d%bc" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>presigned 업로드에서 꼬이는 일은 대부분 알림이 나가기도 전에 꼬입니다. 한 페이지에 모아 두고 싶었던 것들입니다.</p>

<h3 class="relative group">CORS, 브라우저에만 해당
    <div id="cors-브라우저에만-해당" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#cors-%eb%b8%8c%eb%9d%bc%ec%9a%b0%ec%a0%80%ec%97%90%eb%a7%8c-%ed%95%b4%eb%8b%b9" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>네이티브 앱은 신경 쓸 일이 없습니다. 브라우저는 PUT 전에 버킷으로 preflight <code>OPTIONS</code>를 보내는데, 버킷의 CORS 규칙이 여러분의 오리진에서 오는, <code>Content-Type</code> 헤더가 붙은 <code>PUT</code>을 허용하지 않으면 업로드는 CORS 에러로 실패합니다. Tigris는 표준 S3 CORS 설정을 그대로 받으니 규칙 모양은 AWS와 같습니다. presigned PUT이 <code>curl</code>에서는 되고 페이지에서는 안 될 때 제일 먼저 확인할 것이 이겁니다.</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="Tigris 버킷 설정의 CORS and headers 탭: 두 오리진에서 오는 PUT을 Content-Type 헤더와 함께 허용하는 규칙 하나"
    width="1204"
    height="671"
    src="https://jared.lynskey.co.nz/en/posts/2026/tigris-object-notifications/tigris-bucket-cors_hu_7f61261034a8a56.webp"
    srcset="https://jared.lynskey.co.nz/en/posts/2026/tigris-object-notifications/tigris-bucket-cors_hu_7f61261034a8a56.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/tigris-object-notifications/tigris-bucket-cors_hu_3aa47360232f6475.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/tigris-object-notifications/tigris-bucket-cors_hu_3aa47360232f6475.webp"></span><figcaption>브라우저 업로드에 필요한 CORS 규칙은 하나면 됩니다. 여러분의 오리진, PUT, 그리고 서명이 기대하는 Content-Type 헤더.</figcaption></figure>
</p>

<h3 class="relative group">Content-Type은 서명의 일부다
    <div id="content-type은-서명의-일부다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#content-type%ec%9d%80-%ec%84%9c%eb%aa%85%ec%9d%98-%ec%9d%bc%eb%b6%80%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h3>
<p><code>ContentType</code>을 넣어 서명하면 클라이언트는 정확히 그 헤더를 보내야 하고, 아니면 버킷이 403 <code>SignatureDoesNotMatch</code>로 답합니다. 슬롯이 URL과 함께 헤더까지 돌려주는 이유가 그겁니다. 일부러 넣어서 서명하되, 그게 어디까지 막아 주는지는 알아 두세요. 강제되는 건 헤더이지 내용이 아니라서, <code>image/jpeg</code>라고 이름표를 붙인 PDF는 통과합니다. 진짜 검사는 파이프라인입니다. Pillow는 이미지가 아닌 것은 열기를 거부하고, 행은 끝내 처리됨으로 표시되지 않습니다.</p>

<h3 class="relative group">크기 제한
    <div id="크기-제한" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%81%ac%ea%b8%b0-%ec%a0%9c%ed%95%9c" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>presigned PUT URL에는 크기 제한이 없습니다. 바이트가 떨어지기 전에 확실히 막아야 한다면 <code>content-length-range</code> 정책 조건을 건 presigned POST가 그 일을 합니다. 저는 굳이 그러지 않았습니다. 알림에 객체의 <code>size</code>가 실려 오니까요. 핸들러는 제한을 넘는 것은 읽기 전에 지워 버리고, 저장 시점 경로는 많아야 제한에 1바이트를 더한 만큼만 읽어서 넘었는지 판별합니다. 앱이 보내는 건 몇백 KB입니다. 15MB 근처라면 앱이 보낸 게 아닙니다.</p>

<h3 class="relative group">만료
    <div id="만료" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%a7%8c%eb%a3%8c" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>시계가 두 개입니다. presigned URL은 15분 동안 유효한데, PUT 한 번에는 충분하고 새어 나간 URL이 금방 쓸모없어질 만큼 짧습니다. 슬롯 행은 이틀 동안 유효해서, 사진을 골라 놓고 휴대폰을 내려놨다가 다음 날 게시글을 마무리하는 경우까지 감당합니다. 클라이언트는 하루가 지난 미완료 업로드는 낡은 것으로 보고, 요행을 바라는 대신 새로 시작합니다.</p>

<h3 class="relative group">여러 파일, 그리고 더 큰 파일
    <div id="여러-파일-그리고-더-큰-파일" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%97%ac%eb%9f%ac-%ed%8c%8c%ec%9d%bc-%ea%b7%b8%eb%a6%ac%ea%b3%a0-%eb%8d%94-%ed%81%b0-%ed%8c%8c%ec%9d%bc" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>파일 하나에 슬롯 하나입니다. 사진 열 장이면 슬롯 열 개와 병렬 PUT 열 개이고, 각각 진행률이 따로 있습니다(<code>XMLHttpRequest</code>는 <code>upload.onprogress</code>를 주고, <code>fetch</code>는 주지 않습니다). 거대한 base64 POST 하나로는 얻을 수 없는 것이죠. 몇 MB를 넘어가면 멀티파트를 쓰세요(파트 하나가 최소 5 MiB라서, 그보다 한참 큰 파일에 쓰는 겁니다). 서버에서 멀티파트 업로드를 만들고, <code>upload_part</code>마다 presign한 뒤, 파트가 다 들어오면 완료하면 됩니다. 업로드가 완료되면 Tigris가 <code>OBJECT_CREATED_MULTIPART</code>를 보내니 같은 핸들러가 돌고 다른 건 아무것도 바뀌지 않습니다.</p>

<h3 class="relative group">순서가 뒤바뀔 때
    <div id="순서가-뒤바뀔-때" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%88%9c%ec%84%9c%ea%b0%80-%eb%92%a4%eb%b0%94%eb%80%94-%eb%95%8c" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>객체가 둘 이상의 리전에 쓰였을 수 있기 때문에 이벤트는 순서가 뒤바뀌어 도착할 수 있습니다. 업로드에는 상관없습니다. 키 하나에 이벤트 하나니까요. 덮어써지는 키라면 웹훅이 도착한 순서가 아니라 eTag와 객체의 <code>Last-Modified</code>를 믿으세요.</p>

<h2 class="relative group">같은 신호를 로그에도: Discord 알림
    <div id="같은-신호를-로그에도-discord-알림" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ea%b0%99%ec%9d%80-%ec%8b%a0%ed%98%b8%eb%a5%bc-%eb%a1%9c%ea%b7%b8%ec%97%90%eb%8f%84-discord-%ec%95%8c%eb%a6%bc" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>버킷이 백엔드와 이야기할 수 있게 되면, 버킷에 떨어지는 무엇에든 같은 방식으로 반응할 수 있습니다. 제가 두 번째로 겨냥한 것은 로그였습니다.</p>
<p>앱 로그는 작은 gzip 파일로 버킷에 실려 옵니다. 앱마다 대략 5분에 하나씩이죠. 올해 대부분 동안은 15분 주기 cron으로 도는 GitHub Action이 DuckDB로 그 아카이브의 최근 20분을 읽어서 느린 요청 줄을 찾아 Discord에 요약을 올리고 있었습니다. 서류상으로는 문제없습니다. 그런데 실제로는 플랫폼이 바쁠 때 GitHub의 예약 워크플로가 제시간에 돌지 않습니다. 그래서 &ldquo;15분마다&quot;는 사실상 &ldquo;몇 시간마다&quot;에 가까웠고, 겨우 돌 때쯤엔 씹어야 할 구간이 커져 있어서 가끔 메모리가 바닥났습니다. 실행 사이에 빠지는 게 없도록 구간을 겹치게 잡아 뒀더니 같은 느린 요청이 두 번 올라오는 일도 생겼고요. &ldquo;요청이 느리면 알려 줘&rdquo; 하나 하자고 돌리기엔 장치가 너무 많았습니다.</p>
<p>이제는 로그 파일이 도착하는 순간 한 번씩만 읽습니다. gzip으로 몇 KB밖에 안 되는 파일들이죠. 핸들러가 느린 요청 줄을 뽑아내고, 그런 줄이 충분히 많거나 정말 느린 게 하나라도 있으면 Discord 웹훅으로 채널에 요약을 올립니다. 한 파일 안에 5xx 응답이 몰려 있을 때도 마찬가지입니다. Python에서 Discord 웹훅을 쏘는 건 호출 한 번입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">requests</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">discord_alert</span><span class="p">(</span><span class="n">text</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="n">settings</span><span class="o">.</span><span class="n">DISCORD_WEBHOOK_URL</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">json</span><span class="o">=</span><span class="p">{</span><span class="s2">&#34;content&#34;</span><span class="p">:</span> <span class="n">text</span><span class="p">[:</span><span class="mi">1900</span><span class="p">]},</span>  <span class="c1"># Discord 메시지 상한은 2000자</span>
</span></span><span class="line"><span class="cl">        <span class="n">timeout</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span></span></span></code></pre></div></div>
<p>cron도 없고, 구간 겹침도 없고, 중복도 없습니다. 알림은 GitHub가 마음 내킬 때가 아니라 요청이 있고 몇 분 안에 도착합니다. 그 Action은 사라졌습니다.</p>
<p>어차피 파일을 열어 둔 김에, 안에 든 것(에러, 경고, 헬스 체크)을 세어서 시간별 집계 테이블에도 넣습니다. 일일 요약은 예전엔 하루치 아카이브를 통째로 훑었는데, 이제는 몇백 행만 읽고 집계에 빈 곳이 있을 때만 아카이브로 돌아갑니다.</p>

<h2 class="relative group">삭제 감시
    <div id="삭제-감시" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%82%ad%ec%a0%9c-%ea%b0%90%ec%8b%9c" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이건 계획한 게 아닙니다. <code>OBJECT_DELETED</code> 이벤트가 생기니 저절로 따라 나온 거죠. 미디어 파일이 삭제되면 핸들러가 아직 그 파일을 가리키는 행이 있는지 확인합니다. 있다면 어딘가에 버그가 있는 거라서(아니면 버킷 콘솔에서 손이 미끄러진 사람이 있거나요), 해당 컬럼을 비워 앱이 깨진 이미지 대신 플레이스홀더를 보여 주게 하고, 보고를 올립니다.</p>
<p>시간당 삭제 수도 셉니다. 평소 정리 작업으로 지워지는 건 몇 개 정도입니다. 혹시라도 한 시간에 몇백 개가 지워진다면, 사용자들이 사진이 비어 있다고 신고하기 시작할 때가 아니라 바로 그 순간에 알고 싶습니다.</p>

<h2 class="relative group">알아 두면 좋은 것들
    <div id="알아-두면-좋은-것들" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%95%8c%ec%95%84-%eb%91%90%eb%a9%b4-%ec%a2%8b%ec%9d%80-%ea%b2%83%eb%93%a4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>빨리 응답하세요. Tigris는 전달 한 번에 10초를 줍니다. 5 KB짜리 로그 파일을 읽거나 휴대폰 사진 한 장을 처리하는 건 그 안에 들어갑니다. 더 걸릴 수 있는 건 큐로 보내고 뷰는 200을 돌려주세요. 안 그러면 Tigris가 타임아웃 후 재시도하고, 다시 중복 제거 문제로 돌아가게 됩니다.</p>
<p>버킷 단에서 거르세요. 제 로그 수집기는 앱마다 몇 분에 한 번씩, 끝없이 파일을 씁니다. 관심 있는 프리픽스가 하나뿐이라면 알림 필터에 그렇게 적어서, 나머지 일로 앱이 깨어나지 않게 하세요.</p>
<p>가짜 본문으로 테스트하세요. 페이로드가 작고 안정적이라서, 테스트는 올바른 <code>Authorization</code> 헤더와 함께 JSON을 뷰에 POST하고 핸들러가 한 일을 확인하기만 하면 됩니다. 실제 스토리지는 건드리지 않습니다.</p>
<p>첫날부터 모든 걸 걸지는 마세요. 여기 나온 용도는 전부 대체 수단이 있습니다. 저장이 사진을 직접 처리할 수 있고, 일일 요약은 여전히 아카이브를 훑을 수 있고, 앱은 여전히 base64를 보낼 수 있습니다. 알림 덕분에 하나하나 빨라지고 저렴해졌지만, 웹훅 하나가 빠졌다고 무너지는 건 없습니다.</p>
<p>이번 주의 백미는 그 워크플로 파일을 지운 순간이었습니다. YAML 40줄, Python 스크립트 하나, 저장소 시크릿 두 개, 그리고 주기적으로 찾아오던 &ldquo;알림이 왜 안 왔지?&ldquo;가 전부 사라졌고, 그 자리를 작은 파일 하나가 도착하면 그걸 읽는 핸들러 하나가 대신하고 있습니다. 그래도 핵심은 업로드였습니다. 사진은 네트워크가 허락하는 만큼 빠르게 올라가고, 서버는 여전히 사진 하나하나에 대해 마지막 결정권을 쥐고 있으며, 버킷과 백엔드 사이에 다리를 놓을 필요는 아무에게도 없었습니다. 이제는 버킷이 무슨 일이 있었는지 그냥 말해 주니까요.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/tigris-object-notifications/featured.jpg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
