4줄 요약

velog와 github.io 포스팅을 자동으로 백업/동기화하는 툴을 만들었습니다.

• Velog → GitHub.io 자동 동기화: Velog에 올린 글을 그대로 github.io 블로그에도 반영
• 기존 글 백업: Velog에 이미 작성된 글들을 한 번에 가져오기
• 수정 사항 반영: Velog 글을 수정하면 GitHub Pages에도 자동 업데이트

서론

서론 건너뛰기

약 1년 8개월 동안 Velog를 메인 블로그로 사용해왔습니다. 글을 쓰기 편리하고 개발자 커뮤니티가 잘 형성되어 있다는 큰 장점이 있습니다.

그런데 글이 쌓이다 보니 몇 가지 아쉬움이 생겼습니다.

1. 검색 문제

• Velog 내부 검색 품질이 아쉬웠습니다.
• 예를 들어, 제가 직접 작성한 글 중에 제목에 JAVA가 들어간 글이 몇 개나 있는데, 정작 Velog 검색창에 JAVA를 입력하면 아무 결과도 나오지 않았습니다. (저만 그런건지는 모르겠습니다)

2. 부실한 통계 기능

• Velog에는 기본 제공되는 조회수 외에 상세 통계가 부족합니다.
• 크롬 익스텐션을 활용하면 통계를 볼 수는 있지만, 매번 일일이 돌려야 해서 불편했어요.

3. 광고 불가능

• Velog는 플랫폼 특성상 광고를 붙일 수 없어서, 수익화가 사실상 불가능합니다.
• 포스팅 조회수가 많지는 않지만...광고 붙여보고 싶어요..

그럼에도 불구하고 Velog는 글을 작성하기 편리하고, 개발자 독자층이 많다는 장점이 큽니다. 그래서 저는 Velog와 github.io를 동시에 운영하기로 했습니다.

본론

이를 위해 만든 도구가 바로 velog-sync 입니다.

• velog-sync는 Velog와 GitHub Pages(github.io) 블로그를 자동으로 동기화해주는 CLI 도구입니다.
• 한 번 글을 Velog에 업로드하면, 동일한 글이 내 GitHub Pages에도 자동으로 반영됩니다.

이 도구를 만들면서 제가 목표로 한 점은 Velog의 편리함 + GitHub Pages의 독립성 두 가지를 동시에 누리는 것이었습니다. 따라서, 글을 두 번 작성할 필요 없이 Velog에 글을 쓰면 알아서 github.io에도 동기화됩니다.

■ velog-sync 사용 준비물

velog-sync를 사용하기 위해서는 다음 두 가지가 필요합니다.

1. Jekyll 테마의 gitHub.io 블로그

• velog-sync는 Velog 글을 Markdown 파일로 변환해서 github.io 리포지토리 내의 폴더에 업로드합니다.
• 따라서 미리 username.github.io 저장소를 만들어 두고, Jekyll 테마(저는 chirpy를 사용했습니다.) 테마를 적용해 두는 것이 좋아요.

준비가 안 되어 있다면 아래의 부록으로 설명해두었으니, 참고하시면 좋을 것 같습니다. 부록으로 이동하기

2. GitHub Personal Access Token (PAT)

• GitHub 저장소에 velog-sync가 자동으로 push하기 위해 인증 토큰이 필요합니다.
• GitHub → Settings → Developer settings → Personal Access Tokens에서 생성할 수 있습니다.
• 권한은 최소한 repo (저장소 쓰기 권한)만 체크해도 충분합니다.

■ 사용방법

Step1. 설치

1. Velog-Sync 저장소를 Fork 합니다.

• GitHub 페이지에서 Fork 버튼을 눌러 본인 계정으로 저장소를 복사하세요.
• https://github.com/jaewon-ju/velog-sync

2. fork한 저장소를 로컬로 클론합니다.

• 로컬 디렉토리에서 아래와 같은 커맨드를 입력하세요.

  git clone https://github.com/<your-username>/velog-sync
  cd velog-sync

3. 이제 본인 리포지토리 Settings → Secrets → Actions 에서 GH_PAT_FOR_GHIO를 등록합니다.

   GitHub 리포지토리 → Settings → Secrets and variables → Actions → New repository secret
   

이름: GH_PAT_FOR_GHIO

값: 본인 GitHub Personal Access Token

![](https://velog.velcdn.com/images/jaewon-ju/post/43d1aae2-6e08-467c-99d4-03cb5e1d0f8b/image.png)

<br>


> #### Step2. 초기 설정

처음 velog-sync를 사용할 때는, 내 Velog 계정과 github.io 리포지토리 정보를 알려줘야 합니다.

```bash
velog-sync init
# 위 커맨드 실행 후 오류가 발생하면 npm link를 한 뒤 다시 실행해보세요

실행하면 터미널에서 차례대로 질문이 나옵니다 👇

1. Velog 주소 또는 아이디:

   • https://velog.io/@username 형식 전체 주소, 또는 username 만 입력해도 됩니다.

2. github.io 리포지토리 URL

   • 예: https://github.com/myname/myname.github.io

3. github.io 리포지토리 절대 경로

   • 내 컴퓨터에 클론 받아둔 블로그 폴더의 경로
   • 예: /Users/projects/myname.github.io

4. 포스트 디렉토리 (기본값: _posts)

   • myname.github.io 프로젝트에서, 포스팅 마크다운들을 저장하는 폴더 이름을 작성해주시면 됩니다. 여기에 자동으로 velog 포스팅이 업로드됩니다.
   • Jekyll 블로그라면 보통 _posts를 그대로 쓰면 됩니다.

5. 푸시할 브랜치 (기본값: main)

   • 저장소의 기본 브랜치명을 입력하세요.
   • 그냥 엔터 누르셔도 됩니다.

6. Git author 정보 (선택사항)

   • 커밋 시 사용할 user.name과 user.email
   • 그냥 엔터 누르셔도 됩니다.

7. 커밋 메시지 템플릿 (선택사항)

   • 커밋 메시지를 커스텀할 수 있습니다.
   • 그냥 엔터 누르셔도 됩니다.

중요: 여기까지 진행한 후 push하면, GitHub Actions (.github/workflows/velog-sync.yml)이 자동으로 활성화됩니다.

즉, 이제 velog에 글을 작성하면 github.io에도 똑같이 글이 업로드 됩니다.(매일 오전 9시마다 복사)

Step3. (선택) 로컬에서 수동 실행

Actions 자동 실행이 잘 동작하지만, 원한다면 로컬에서도 직접 동기화를 실행할 수 있습니다:

velog-sync sync

명령어를 실행하면 다음 단계를 거칩니다:

1. 내 계정(@username)의 최신 글 목록을 가져옵니다. 2. 이미 저장된 글과 비교해서 새 글/수정된 글을 자동으로 판별합니다. 3. Velog 글을 _posts 디렉토리에 Markdown 파일로 저장합니다. 4. 새 글/수정된 글을 자동으로 커밋합니다.

■ 결과물

velog-sync는 매일 00시(UTC 기준)에 velog 포스팅을 긁어서, 추가/수정된 포스팅을 github.io 리포지토리에 push 해줍니다.

따로 관리하지 않아도, velog에 글을 쓰면 자동으로 내 github.io에 동기화됩니다. 찾는 글이 있으면 github.io에서 검색하면 됩니다.

결론

다른 사용자에게 github 리포지토리를 공개하고, 서비스를 공유하는 것이 처음이라 오류가 있을 수 있습니다😓 댓글 남겨주시면 빠르게 패치하도록 하겠습니다.

원하시는 기능이 있다면 알려주세요! pull request도 언제든 환영입니다!

• Velog 글 안의 이미지는 모두 다운로드하여 블로그 저장소(assets/posts/)에 저장됩니다.
• 따라서 Velog CDN이 변하더라도 내 블로그에는 영향을 주지 않습니다.

부록: Jekyll 테마 gitHub.io 블로그 만들기

간단하게 정리해두었습니다! 먼저 구글 검색으로 관련 가이드를 찾아보시고, 작동하지 않을 경우 이 가이드라인을 참고해 설정해보시기 바랍니다.

1. GitHub 리포지토리 만들기

• 이름: 사용자명.github.io

  • 예: jaewon-ju.github.io

• 이 리포지토리는 GitHub Pages에서 개인 사이트 도메인으로 자동 인식됩니다. → https://사용자명.github.io

2. 로컬 프로젝트 생성 및 원격 연결

로컬에서 프로젝트 폴더 생성:

mkdir <폴더명>
cd <폴더명>
git init

원격 리포지토리 연결:

git remote add origin https://github.com/<사용자명>/<리포지토리명>

초기 커밋 후 푸시:

git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main

3. Jekyll 테마 다운로드 및 적용

• http://jekyllthemes.org/ 에서 마음에 드는 테마를 고릅니다.
• 해당 테마 리포지토리를 클론하거나, ZIP으로 다운로드 후 압축 해제합니다.
• 테마 폴더 내용을 프로젝트 루트에 복사/붙여넣기 합니다.

3. macOS에서 Jekyll 환경 세팅

brew install rbenv ruby-build

echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

rbenv install 3.3.0
rbenv global 3.3.0

4. 의존성 설치

프로젝트 루트에서 아래 명령어 실행:

bundle install
bundle update

이후 다시 한 번:

bundle install

5. GitHub Actions 워크플로우 파일 생성

• 루트에 .github/workflows 디렉토리 만들기

  mkdir -p .github/workflows

• 그 안에 pages-deploy.yml 파일 작성 .github/workflows/pages-deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write # 격리 커밋 푸시를 위해 필요

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"

      - name: Install Dependencies
        run: |
          gem install bundler
          bundle install

      # 🔁 빌드 실패 시 문제 파일(_posts/*.md)만 _quarantine/로 이동 후 재시도
      - name: Build Jekyll Site (auto-quarantine)
        run: |
          set -eo pipefail
          mkdir -p _quarantine

          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          success=0
          quarantined=0
          max_attempts=10   # 필요시 6~10으로 여유

          for i in $(seq 1 $max_attempts); do
            echo "==> Jekyll build attempt #$i"
            if bundle exec jekyll build --trace 2>build.err; then
              success=1
              break
            fi

            offender=$(grep -oE "$GITHUB_WORKSPACE/_posts/[^:]+\.md" build.err | head -n1 || true)
            if [ -z "$offender" ]; then
              echo "No offending post detected. Full error follows:"
              cat build.err
              exit 1
            fi

            reason=$(grep -m1 "Error" build.err || true)
            echo "Error reason: $reason" # 에러 원인 출력

            base=$(basename "$offender")
            echo "⚠️  Quarantining failing post: $base"
            git mv "$offender" "_quarantine/$base" || mv "$offender" "_quarantine/$base"
            git commit -m "ci: quarantine failing post $base" || true
            git push origin HEAD:main || true

            quarantined=1
            # 바로 다음 루프로 넘어가 재빌드
          done

          # 루프가 끝났는데 마지막이 격리로 종료되었을 수 있으니 한 번 더 시도
          if [ $success -ne 1 ] && [ $quarantined -eq 1 ]; then
            echo "==> Final build after last quarantine"
            if bundle exec jekyll build --trace 2>build.err; then
              success=1
            fi
          fi

          if [ $success -ne 1 ]; then
            echo "Build failed after quarantine attempts."
            cat build.err
            exit 1
          fi

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

그다음 push

git commit -am "[feat] actions setting"
git push

6. GitHub Pages 설정 변경

• GitHub 저장소 → Settings → Pages 로 이동
• Deploy from a branch → gh-pages 브랜치 선택

7. 권한 설정 확인

• 리포지토리 → Settings → Actions → General Workflow permissions 항목에서 Read and write permissions 체크
• Allow GitHub Actions to create and approve pull requests 옵션 활성화

8. 완료

이제 커밋 후 main 브랜치에 푸시하면, GitHub Actions가 자동으로 실행되어 _site 폴더가 gh-pages 브랜치로 배포됩니다. 잠시 후 https://사용자명.github.io 에 접속해 사이트를 확인할 수 있습니다.

✏️ 백트래킹 (Backtracking)

■ 핵심 개념

모든 경우의 수를 탐색하는 과정에서, 해답이 될 수 없는 경우는 더 이상 탐색하지 않고 되돌아가는 방법. DFS를 기반으로 하며, 가지치기를 통해 탐색 효율을 높임.

■ 템플릿 요약

1. 현재 노드를 탐색
2. 조건 충족 시 다음 단계 DFS 재귀 호출
3. 조건 불충족 또는 끝까지 탐색 시 이전 단계로 되돌아감

■ 구현 템플릿

def backtrack(depth, path):
    # 종료 조건
    if depth == 목표_깊이 or 조건_만족:
        결과 처리()
        return

    for 다음_선택 in 가능한_선택지:
        path.append(다음_선택)
        dfs(depth+1, path)
        path.pop()  # 백트래킹 (되돌리기)

dfs를 활용한 예시

def backtrack(node, graph, visited):
    # 종료 조건
    if (종료조건):
        return

    for next in graph[node]:
        if visited[next] == 0:
            visited[next] = 1       # 방문 처리
            backtrack(next, graph, visited)
            visited[next] = 0       # 방문 해제 (rollback)

✏️ 투 포인터 (Two Pointers)

■ 핵심 개념

하나의 배열에서 두 개의 인덱스를 움직여 조건을 만족하는 구간을 찾는 기법.

■ 템플릿 요약

1. 오른쪽 포인터로 확장
2. 조건 위반 시 왼쪽 포인터로 축소
3. 정답 갱신

■ 구현 템플릿

def two_pointers(arr):
    n = len(arr)
    left = 0
    state = {} # 윈도우 상태관리

    # 1. 윈도우 자동 확장
    for right in range(n):

        # 2. 조건 위반 시 왼쪽 축소
        while 조건위반():
            left += 1

        # 3. 정답 갱신
        answer = max(answer, right - left)

예시: 서로 다른 문자 종류가 최대 K개인 부분문자열의 최대 길이를 구하라.

from collections import defaultdict

N = len(string) # 주어진 문자열 길이

freq = defaultdict(int)
left = 0
maximum = 0

for right, element in enumerate(N):
    freq[element] += 1

    while(len(freq) > K):
        freq[string[left]] -= 1
        left += 1

    maximum = max(maximum, right - left + 1)

✏️ 최단거리 알고리즘

■ 핵심 개념

그래프에서 두 정점 사이의 최소 거리를 구하는 알고리즘. 다양한 방법이 있으며, 문제의 조건(음수 가중치 여부, 전체 경로 탐색 필요 여부)에 따라 알고리즘이 달라진다.

• Dijkstra 알고리즘: 음수 가중치가 없는 경우, 우선순위 큐(힙)을 이용하여 가장 짧은 경로를 탐색.
• Bellman-Ford 알고리즘: 음수 가중치가 있어도 사용 가능하며, 음수 사이클 탐지 가능.
• Floyd-Warshall 알고리즘: 모든 정점 쌍의 최단거리를 구하는 알고리즘.

■ 템플릿 요약

1. 시작 노드의 거리를 0으로 초기화, 나머지는 무한대(INF)로 설정
2. 최단 거리 후보 중 가장 작은 값을 가진 노드를 선택
3. 선택한 노드를 거쳐가는 경로가 더 짧다면 거리 갱신
4. 모든 노드가 처리될 때까지 반복

■ 구현 템플릿 (Dijkstra)

다익스트라는 가장 가까운 노드부터 차례대로 확장해 나가는 방식이다.

• 이때, heapq는 탐색할 후보 노드를 저장한다.

import heapq

def dijkstra(start, graph, n):
    INF = int(1e9)
    distance = [INF] * (n+1)
    distance[start] = 0
    queue = []
    heapq.heappush(queue, (0, start))

    while queue:
        # heap에서 가장 짧은 거리(dist)를 가진 노드(now)를 꺼낸다.
        # heapq는 최소힙이므로, 지금까지 발견된 "가장 가까운 후보"가 나온다.
        dist, now = heapq.heappop(queue)

        # 이미 더 짧은 경로로 방문한 적이 있다면 무시한다.
        if distance[now] < dist:
            continue

        # 현재 노드에 연결된 모든 인접 노드 탐색
        for next, cost in graph[now]:
            # 현재 노드까지의 거리(dist)에다, 간선 비용(cost)을 더한 값
            # 즉, start → ... → now → next 경로의 총 비용
            new_dist = dist + cost

            # 만약 이 경로가 기존에 기록된 next까지의 최단거리보다 짧다면,
            # distance[next]를 갱신하고, 우선순위 큐에 새로운 후보로 추가한다.
            if new_dist < distance[next]:
                distance[next] = new_dist
                # heap에는 "next까지의 최신 최단거리 후보"를 넣는다.
                heapq.heappush(queue, (new_dist, next))

    return distance

Dijkstra 알고리즘은 음수 가중치가 없는 경우에 적합하며, BFS와 유사하게 동작하지만 우선순위 큐를 활용해 효율적으로 최단 경로를 찾는다.

결론부터 말하자면,

적극 추천한다.

• 하루 8시간씩 코딩에 집중할 수 있는 경험
• 프로젝트의 A-Z까지 총괄해보는 경험
• 협업 경험
• 다양한 기술을 써보는 경험

이 외에도 정말 다양한 경험을 할 수 있었고, 앞으로의 개발 인생에 큰 도움이 될 것이라 생각한다.

무엇을 배웠는가?

1. 프로젝트의 전 과정

입사 전까진 백엔드와 RDB 외에는 다뤄본 적이 없었다. 배포 경험이 있긴 했지만, 항상 AWS EC2만 사용했기에 기술 스택의 폭이 넓진 않았다.

하지만 이번 인턴 기간 동안 정말 다양한 분야를 접할 수 있었다.

Firestore, Firebase Authentication, Cloudflare workers, R2, inngest, nginx, next.js, hono, authentik, railway....

프론트부터 Serverless Function, 인증 서버, NoSQL DB, 배포 서비스까지. 프로젝트의 A to Z를 직접 연결하고 구축해보는 경험이었다.

물론 기술의 '깊이'도 자연스레 늘었지만, 무엇보다 기술의 '폭'이 확장되었다는 점을 크게 느꼈다. 이는 스타트업의 장점이라고 생각한다.

• 새롭고 트렌디한 기술을 직접 도입해볼 수 있다는 점.

물론 단점도 있다. 잘 알려지지 않은 기술을 다뤄야 하다 보니, 레퍼런스가 적고 문제 해결이 쉽지 않다는 것.

그럼에도 불구하고, 이제는 나 혼자서도 하나의 서비스를 처음부터 끝까지 만들 수 있겠다는 자신감이 생겼다.

2. 엉덩이 힘

코딩을 좋아하지만, 하루 8시간씩 주 5일을 몰입했던 적은 없었던 것 같다. 매일 새로운 에러가 터진다. 빠르면 3시간, 길면 3일 동안 에러를 잡는다. 출근해서 어제 에러를 잡고 밥 먹고 돌아오면 또 다른 에러가 터져 있다.

하루 종일 화면만 보다 보니 눈도 뻑뻑해졌다. 그럼에도 불구하고, 이제는 ‘하루 = 코딩’ 이 수식이 너무 익숙해졌다. 오히려 좋아.

3. 백엔드 개발자가 UX를 신경써야 하는 이유

예전에는 “백엔드 개발자가 UI/UX까지 고려해야 할까?” 하는 생각이 있었다. 하지만 토스 페이먼츠를 연동하면서, 그 이유를 뼈저리게 깨달았다.

Stripe의 구독 라이프사이클을 참고해서 결제 시스템을 구축하던 중, Incomplete라는 상태를 발견했다. 이는 첫 결제가 실패했을 때 구독이 머무는 상태다. 당시에는 왜 이게 필요한지 이해하지 못했다. 그래서 나는 INACTIVE, ACTIVE, UNPAID(연장 결제 실패) 세 가지 상태만 있는 라이프사이클을 설계했고, 그대로 CTO님께 보고했다.

그런데 실제 구현 과정에서 문제가 발생했다. 사용자 입장에서 생각해보니, 첫 결제가 실패할 경우 다시 결제하려면 상품을 처음부터 다시 선택 → 결제 팝업 작성 → 결제 재시도의 과정을 거쳐야 한다. 이는 상당히 번거롭고, 사용자 경험을 크게 떨어뜨린다.

바로 이 문제를 해결하기 위해 존재하는 상태가 Incomplete였다. 결제 실패 시 해당 상태로 유지하면, 사용자는 이전에 실패한 결제 내역을 그대로 재결제할 수 있어 번거로운 과정을 줄일 수 있다.

이 경험을 통해 깨달았다. 백엔드 개발이라도 사용자 경험을 고려한 설계가 필요하다. UI/UX는 화면에 보이는 것만이 아니라, 사용자가 서비스를 어떻게 경험하는지 전반을 포함하기 때문이다.

4. 개발자 != 코더

개발자는 단순히 코드를 작성하는 코더가 아니다.

회사 업무를 하면서 비즈니스 로직을 짜는 것보다 다른 요소들에 훨씬 많은 시간을 투자했다. 서버 관리, 서비스 비교 후 선택(Inngest 등), DB 설계, 환경 구성, 서비스 연결 등… 순수한 코딩보다 이 과정들에 더 많은 시간이 들었다.

회사에서 AI 대신 개발자를 고용해야 할 이유를 묻는다면, 이렇게 대답할 것이다.

• 단순한 비즈니스 로직 짜기? 사실 나보다 GPT가 더 잘한다.
• 그럼에도 불구하고 회사에서 개발자를 고용하는 이유는 소프트웨어 개발 != 코딩이기 때문이다.

소프트웨어 개발은 요구사항 분석부터 서비스 유지보수까지 전 과정을 포함한다. 비즈니스 로직 작성은 그중 일부일 뿐이다. 스택을 선택하고, 서비스들을 연결하며, 그 과정에서 발생하는 오류를 해결하는 것까지 모두 개발자의 역할이다. 이 과정에서 CS 지식이 빛을 발한다.

서비스의 흐름을 보자.

1. nginx가 요청을 받는다
2. 프론트로 전달
3. 프론트가 백엔드에 요청
4. 인증 처리
5. 백엔드는 DB에서 데이터 조회
6. 가공 후 응답
7. 프론트는 응답을 받아 Redux로 상태 관리
8. 필요 시 백엔드가 Inngest로 요청
9. Inngest가 특정 작업을 실행

이 흐름 속에는 CORS, 버퍼 관리, 동시성 관리, 비동기 요청, DB 쿼리, 인증, 메시지 큐 등 다양한 기술과 개념이 맞물린다. CS 지식은 바로 이런 순간에 힘을 발휘한다.

비즈니스 로직을 잘짜는 것? 물론 중요하다. 하지만 개발자라면 흐름을 설계하고, 문제가 생겼을 때 어느 서비스의 어느 부분을 수정해야 하는지 파악할 수 있어야 한다. GPT에게 모든 맥락을 이해시키는 것도 가능하겠지만, 정확도와 맥락 파악은 결국 개발자의 몫이다.

기억에 남는 경험

1. 결제 시스템 구축기

처음 입사했을 때, 회사 서비스는 Firebase 기반의 MVP였다. Firestore, Firebase Authentication, Firebase Function, Firebase Hosting 등 모든 곳에서 Firebase를 사용하고 있었다.

자연스럽게 Firebase에 익숙해질 수 있었고, 특히 초반에는 백엔드 API 개발을 맡았기에 Firebase Function을 심도 있게 다뤄볼 수 있었다.

초반 2개월은 결제 시스템을 구축했다. 그냥 PG사 연동만 하면 되는거 아닌가???

맞다. 백엔드는 그리 어렵지 않았다. 하지만, DB 설계가 굉장히 까다로웠다.

'돈이 연관된 기능은 그 어떠한 것보다 정확하고 섬세해야 한다'

사용자가 구독을 요청했을 때, 구독을 취소했을 때, invoice가 생성된 뒤에 구독을 취소했을 때, invoice가 생성되기 전에 구독 요금제를 변경했을 때, 관리자가 사용자의 구독을 임의로 조정할 때....

이 모든 상황을 추적할 수 있는 구조가 필요했다. 그러나 이를 여러 필드의 조합으로 처리하려다 보니 복잡함이 상당했다.

처음 2주간 정말 머리를 싸매며 DB를 설계하고 백엔드 로직까지 완성해 CTO님께 컨펌을 받았다. 물론 요구사항에 맞게 모든 기능을 구현했지만, CTO님이 정곡을 찌르셨다.

‘확장성이 부족하고, 현 상태를 파악하려면 여러 필드를 조합해야 하는 점이 아쉽다.’

이 피드백과 함께, Stripe의 구독 관리 예시를 보여주시며 조언을 해주셨다. 항상 작업할 때는 best practice를 참고하는 것이 좋다는 이야기였다.

나보다 먼저 이 길을 걸어간 개발자들이 이미 많은 시행착오를 겪었고, 우리는 그중 검증된 길을 따라가야 효율적이라는 조언이었다.

이 피드백을 바탕으로 DB를 전면 재설계했다. 그 결과, 단일 필드만으로 현재 상태를 즉시 파악할 수 있는 구조를 만들었고, 새로운 상태나 기능이 추가되더라도 쉽게 확장 가능하도록 설계했다. 이 구조 덕분에 이후 Stripe 결제 방식을 추가할 때도 DB 스키마 변경 없이 바로 적용할 수 있었다.

2. Firebase 의존성 제거

입사할 때만 해도 우리 서비스는 Firebase에 올인된 구조였다. Firestore, Firebase Auth, Firebase Functions, Firebase Storage… 뭐든 Firebase에서 다 해결되는 구조였고, 덕분에 금방 익숙해졌다.

하지만, 편리한 만큼 제약도 많았다. 새로운 기능을 붙이거나 다른 서비스와 연동하려고 할 때, Firebase 구조에 맞춰야 하는 제약이 항상 따라왔다. 이러한 문제 때문에, 서비스에서 Firebase 의존성을 모두 제거하는 업무를 맡게 되었다.

DB부터 뜯어고치기

DB부터 뜯어고치기 첫 번째 타깃은 Firestore였다. 가장 힘들었던 건 NoSQL에서 RDB로 전환하는 과정이었다. 컬렉션·도큐먼트 기반으로 느슨하게 저장되던 데이터를, 관계형 구조에 맞춰 테이블·PK·FK·조인 테이블로 재설계해야 했다. 데이터 참조 방식이 완전히 달라지다 보니, 기존 로직도 전부 손봐야 했다.

처음엔 ORM(Prisma)로 접근했지만, Cloudflare Workers 환경에서 Node 전용 라이브러리들이 먹히지 않았다. Accelerate도 시도했지만, 이렇게 되면 플랫폼 의존성을 줄이려는 초기 목적과 멀어졌다. 결국 node-postgres로 직접 쿼리를 쓰기로 했고, 그때부터 Repository 레이어를 전부 손으로 다시 쓰는 장대한 작업이 시작됐다.

프론트 직접 DB 접근 제거

MVP 시절에 만들어진 코드다 보니, 프론트에서 DB를 직접 호출하는 로직이 여기저기 박혀 있었다. 당시에는 빠르게 기능을 붙이는 게 목적이었으니 가능한 구조였겠지만, 서비스가 커진 지금은 보안·유지보수·확장성 측면에서 전혀 맞지 않았다.

그래서 전부 뜯어냈다. 프론트의 DB 직접 접근 코드를 전부 삭제하고, 대신 백엔드 API를 통해서만 데이터를 주고받도록 변경했다. 이 과정에서 API 스펙을 정리하고, 필요한 엔드포인트를 새로 만들었으며, 응답 포맷도 { code, message?, data? } 형태로 통일했다.

결과적으로, 프론트와 백의 역할이 명확히 분리됐고, 데이터 흐름을 추적·관리하기가 훨씬 쉬워졌다.

Functions를 Workers로

Firebase Functions도 마찬가지였다. Cloudflare Workers + Hono로 마이그레이션하면서 라우팅, 인증, 서비스 구조를 싹 재정리했다. Swagger랑 zod를 붙여서 문서와 검증을 한 번에 돌렸고, 기존 Functions 호출하던 프론트 로직도 전부 Workers API 호출로 바꿨다.

인증 갈아엎기

Firebase Auth는 Authentik으로 교체했다. 결정은 쉬웠지만, 붙이는 과정은 예상보다 길었다. 기록을 보면 거의 하루 단위로 문제를 부딪히고, 원인 찾고, 한 줄씩 고쳐 나갔다.

• 프론트에서는 next-auth로 로그인 플로우를 다시 짰다.
• API 테스트 환경도 손봤다. Swagger UI에 Security 스키마를 추가해서 Authorization 헤더로 실제 토큰을 넣고 테스트할 수 있게 했고, 개발 환경에서 Authentik ↔ Workers 연동을 끝까지 확인했다.
• 추가로 로그인 옵션을 확장했다.
  • Google OAuth
  • Passkey

이메일 비밀번호 재설정은 SMTP(SendGrid)로 구현해서 복구 메일을 보낼 수 있게 했다.

Inngest로 비동기 작업 처리

파일 업로드 후 썸네일 생성, 월간 정산, 활성 유저 기록 같은 비동기 작업은 Inngest로 옮겼다. 원래는 워커 간 상태 공유와 큐 처리를 위해 Redis를 붙이려 했는데, Cloudflare Workers 환경에서는 직접 TCP 연결이 불가능했다. 이 경우에는 Upstash 같은 HTTP 기반 Redis 서비스를 써야 한다.

그런데 외부 SaaS 의존성을 또 늘리고 싶진 않았다. 그래서 한동안 셀프 호스팅 가능한 메시지 큐 서비스들을 조사한 뒤, Inngest라는 서비스를 도입했다.

업로드 이벤트를 받아 후처리를 실행하는 워크플로우, 크론 스케줄을 통한 주기 작업까지 전부 Inngest로 구성했다.

3. 배포

초기에는 모든 서비스를 Docker로 감싸서 회사 NAS에 올리는 방식을 사용하려 했다. DB, 백엔드, 프론트까지 전부 컨테이너로 띄우고, NAS에서 돌리는 구조였다. 여기에 서브 도메인을 붙이기 위해 nginx를 프록시로 두었고, 서비스별 라우팅도 전부 직접 관리했다.

이 방식은 회사 내부망에서 모든 걸 제어할 수 있다는 장점이 있었지만, 외부 접근과 확장성 면에서는 불편한 점이 많았다. 특히, 배포 변경이나 확장이 필요할 때마다 NAS에 직접 접속해 docker-compose를 수정하고 nginx 설정까지 건드려야 하는 구조였다.

그래서 지금은 각 서비스를 환경에 맞게 분리 배포하는 방식으로 전환했다.

• 프론트엔드: Next.js를 Railway에 배포
• 인증 서버: Authentik 역시 Railway에서 구동
• 비동기 작업(Inngest): Inngest 자체 호스팅 서비스 사용
• 백엔드 API: Cloudflare Workers에서 동작
• DB: Supabase PostgreSQL 사용

이렇게 나누니 서비스별 스케일링을 각각 조절할 수 있고, 배포 속도도 훨씬 빨라졌다. 특히 Workers와 Railway를 조합하니,프론트와 백엔드가 서로 다른 환경에서 돌아가면서도 CORS·도메인 라우팅 문제 없이 안정적으로 붙을 수 있었다.

앞으로의 방향

실제로 업무를 하다보니, AI가 정말 강력함을 느꼈다. 코드를 짜는 것은 확실히 나보다 잘한다. 감히 예상해보자면, 10년 뒤에는 프론트, 백엔드 같은 직군은 없어질 것 같다..

그럼에도 불구하고, 프론트와 백엔드 개발은 개발자라면 한번씩 거쳐야 할 관문이라고 생각한다.

실제로 업무에 투입돼서 개발, 배포, 에러 해결까지 하다보면 프로젝트의 전반적인 흐름을 알게 된다. 그 흐름을 알고 있는 사람만이 AI를 효율적으로 사용할 수 있고, 기업에서도 그런 인재를 원할 것이다.

이제부터는 취업과 졸업 준비를 병행하려 한다. 웬만하면 IT 통합 직군으로 들어가서 관리하는 역할을 맡고 싶지만, 백엔드 직군으로 들어가서 에러랑 한번 더 뒹굴어 보는 것도 좋은 경험일 것 같다.

현장실습 인턴 고민중이라면 꼭꼭 해보시길 추천드립니다~

✏️ BFS

■ 핵심 개념

• 시작 노드에서 출발하여 인접한 노드를 너비 우선으로 탐색.
• 큐(Queue)를 이용하여 구현.
• 방문 여부를 체크하는 visited 리스트가 필수 (중복 방문 방지).

■ 한줄 요약

1. 큐에 시작 노드 삽입
2. 큐에서 꺼낸 후 인접 노드 탐색
3. 방문 안했으면 큐에 추가 및 방문 처리

■ 구현

1. 인접 리스트 방식

• 그래프를 딕셔너리로 표현
• 노드마다 연결된 노드의 리스트를 가짐

인수: 시작 노드, 그래프, visited 배열

from collections import deque

def BFS(start, graph, visited):
    queue = deque([start])
    visited[start] = True

    while queue:
        current = queue.popleft()

        for next in graph[current]:
            if not visited[next]:
                visited[next] = True
                queue.append(next)

2. 인접 행렬 방식

• 인접 행렬로 그래프를 표현
• 노드 수가 적고 간선이 많은 경우 유리

인수: 시작 노드, 그래프, visited 배열

from collections import deque

def BFS(start, graph, visited):
    queue = deque([start])
    visited[start] = True

    while queue:
        current = queue.popleft()

        for next in range(len(graph)):
            if graph[current][next] == 1 and not visited[next]:
                visited[next] = True
                queue.append(next)

3. 격자 기반 방식

• 미로 탐색, 최단거리 구하기 등에 자주 등장
• 2차원 배열로 그래프 표현

인수: 시작 x좌표, y좌표

from collections import deque

dy = [-1, 1, 0, 0] #상, 하
dx = [0, 0, -1, 1] #좌, 우

def BFS(x, y):
    queue = deque()
    queue.append((x, y))
    visited[y][x] = True

    while queue:
        x, y = queue.popleft()

        for dir in range(4):
            nx = x + dx[dir]
            ny = y + dy[dir]

            if 0 <= nx < M and 0 <= ny < N:
                if not visited[ny][nx] and graph[ny][nx] == 1:
                    visited[ny][nx] = True
                    queue.append((nx, ny))

✏️ DFS

■ 핵심 개념

• 시작 노드에서 출발하여 자식 노드를 하나씩 깊이 탐색.
• 재귀 또는 스택을 이용해 구현.
• 방문 여부를 체크하는 visited 리스트가 필수 (무한루프 방지).

■ 한줄 요약

1. 방문 처리
2. 인접 노드 순회
3. 방문 안했으면 DFS 재귀 호출

■ 구현

1. 인접 리스트 방식

• 그래프를 딕셔너리로 표현
• 노드마다 연결된 노드의 리스트를 가짐

인수: 현재 노드, 그래프, visited 배열

def DFS(current, graph, visited):
    visited[current] = True

    for next in graph[current]:
        if(visitied[next] == False):
            DFS(next, graph, visited)

2. 인접 행렬 방식

• 인접 행렬로 그래프를 표현
• 노드 수가 적고 간선이 많은 경우 유리

인수: 현재 노드, 그래프, visited 배열

def DFS(current, graph, visited):
    visited[current] = True

    for next in range(len(graph)):
        if(graph[current][next] == 1 and visited[next] == False):
            DFS(next, graph, visited)

3. 격자 기반 방식

• 미로 탈출, 좌표 기반 이동에서 사용
• 2차원 배열로 그래프를 표현

인수: 현재 x좌표, 현재 y좌표

dy = [-1, 1, 0, 0] #상, 하
dx = [0, 0, -1, 1] #좌, 우

def DFS(x, y):
    visited[y][x] = True

    for dir in range(4):
        nx = x + dx[dir]
        ny = y + dy[dir]

        if((0 <= nx < M) and (0 <= ny < N)):
            if(visited[ny][nx] == False and graph[ny][nx] == 1):
                DFS(nx, ny)

현대 웹과 Node.js 애플리케이션에서는 이미지, 영상, 오디오, 압축 파일 등 다양한 바이너리 데이터를 다루는 일이 흔하다. 이러한 데이터는 기본적인 문자열로는 표현할 수 없기 때문에, 자바스크립트는 이를 처리하기 위한 다양한 저수준 타입들을 제공한다.

Buffer, Blob, Uint8Array... 프론트-백 API 연동을 할 때 항상 헷갈리는 것들이다. Binary Data의 타입은 어떤 것들이 있고, HTTP로 전송할 때는 어떤 방식을 사용해야하는지 정리해보자.

✏️ 바이너리 데이터란?

바이너리 데이터(Binary Data)란 사람이 읽을 수 있는 텍스트가 아닌 비트와 바이트로 구성된 순수 데이터를 의미한다.

대표적인 예시:

• 이미지: PNG, JPG
• 오디오: MP3, WAV
• 영상: MP4, TS
• 압축 파일: ZIP, RAR
• PDF, 바이너리 로그 파일 등

✏️ 타입 구조도

자바스크립트에서 바이너리 데이터를 다루는 주요 타입들은 다음과 같은 계층 구조를 이룬다.

┌────────────┐
│ ArrayBuffer│  ← 원시 메모리
└────┬───────┘
     │     
     │                           
 TypedArray (ex: Uint8Array)   
          │
     ┌────┴────┐
     │         │
  Buffer     Blob/File
(Node.js)   (브라우저)

◼︎ ArrayBuffer

고정 길이의 메모리 덩어리이다.

• 직접 값을 읽거나 쓸 수 없으며, 보통 Uint8Array와 함께 사용한다.
• 말 그대로 "빈 메모리 공간"이다.

const buffer = new ArrayBuffer(8)

◼︎ TypedArray (예: Uint8Array)

ArrayBuffer 위에 구조를 입힌 배열 타입이다.

• 각 요소는 고정된 크기의 정수 또는 실수이다.
• 바이너리 데이터를 가장 널리 다룰 수 있는 방식이다.

const arr = new Uint8Array([72, 101, 108, 108, 111]) // Hello

◼︎ Buffer (Node.js 전용)

Uint8Array를 확장한 Node.js 전용 바이너리 타입이다.

• 파일, 네트워크, 스트림 등과의 빠른 IO 처리를 위해 설계되었다.
• 대부분의 Node API에서 기본적으로 사용된다.

const buf = Buffer.from('Hello')

◼︎ Blob (브라우저 전용)

바이너리 대용량 데이터를 추상적으로 감싼 컨테이너이다.

• 내부 내용을 직접 수정할 수 없으며, 읽기 전용이다.
• type(MIME 타입)을 지정할 수 있다.

const blob = new Blob([Uint8Array], { type: 'image/png' })

◼︎ File (브라우저 전용)

Blob을 확장한 구조로, 파일명과 수정일 등 메타데이터를 포함한다.

• 보통 사용자가 입력한 파일을 다룰 때 사용된다.

const file = new File([blob], 'image.png', { type: 'image/png' })

✏️ Binary Data의 직렬화

⚠️⚠️⚠️ 바이너리 데이터는 JSON.stringify를 통해 직렬화가 되지 않는다.

JSON.stringify(new ArrayBuffer(8)) // 결과: {}

왜냐하면 ArrayBuffer나 Buffer, Uint8Array는 메모리 주소만 가지며, 구조화된 정보를 담지 않기 때문이다. 직렬화를 위해서는 Array<number> 형태로 변환하거나, base64 문자열로 인코딩하는 방법을 사용해야 한다.

✏️ FormData와 바이너리 전송 시 고려할 점

바이너리 데이터를 API로 전송할 때는 일반적으로 두 가지 방식이 사용된다:

1. FormData를 사용하는 방식 (multipart/form-data)
2. 바디에 바이너리 자체를 넣는 방식 (application/octet-stream 혹은 base64/JSON 변환)

◼︎ FormData

FormData는 파일 업로드에 특화된 구조이며, 여러 필드와 함께 파일을 함께 전송할 수 있다.

장점

• 브라우저 fetch, axios, form 등과 호환성이 높다.
• 파일 이름, 타입 등 메타데이터를 포함할 수 있다.
• 문자열, 숫자 등의 부가 정보도 함께 전송 가능하다.

주의할 점

Node.js에서 FormData를 생성할 경우, form-data, formdata-node, undici, formdata-polyfill 등 환경별 라이브러리 호환 이슈가 발생할 수 있다.

◼︎ 직접 바이너리 전송 (application/octet-stream)

파일 하나만 전송하거나, 간단한 API 설계를 원할 경우 request body에 바이너리를 직접 담아 전송할 수 있다.

장점

• 간결하다. form 구조 없이 곧바로 버퍼를 전송할 수 있다.
• 서버 측에서 메모리 사용량을 줄이고 스트리밍 처리하기 좋다.

주의할 점

• 파일 외의 추가 메타데이터(fileId, userId 등)를 함께 보내기 어렵다.
• 다중 파일 업로드에는 적합하지 않다.

fetch('/upload', {
  method: 'POST',
  headers: { 'Content-Type': 'application/octet-stream' },
  body: fileBuffer,
})

Next.js 프로젝트에서 Authentik 기반 OIDC 인증을 구성한 후, 로그인된 사용자 세션을 기반으로 WebAuthn 장치 정보를 가져오는 API(/api/auth/webauthn)에서 production 환경에서만 403 Forbidden 오류가 발생하는 문제가 있었다.

✏️ 오류 발생 환경

로그인 후, 다음과 같은 API를 통해 현재 사용자의 WebAuthn 장치 보유 여부를 확인하고자 했다:

const authentikRes = await fetch(
  `${process.env.NEXT_PUBLIC_AUTHENTIK_URL}api/v3/authenticators/webauthn/`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`, // 액세스 토큰으로 인증
    },
  },
);

그러나 production 환경에서 다음과 같은 에러가 발생했다:

GET https://app.wedeo.io/api/auth/webauthn 403 (Forbidden)

이때 사용한 accessToken은 NextAuth.js의 getToken() 함수로부터 추출한 OAuth2 Access Token이다.

Authentik의 공식 문서에서는 다음과 같이 명시되어 있다:

JWT Token

OAuth2 clients can request the scope goauthentik.io/api, which allows their OAuth Access token to be used to authenticate to the API.

• 즉, Access Token을 API 인증에 사용하려면 반드시 scope에 goauthentik.io/api가 포함되어 있어야 한다.

• 그러나 기존 설정에서는 scope 항목에 이 값이 누락되어 있었기 때문에, 발급받은 토큰이 API 접근 권한을 갖지 못했고, 그 결과 403 Forbidden 오류가 발생한 것이다.

✏️ 해결방법

OAuth2 인증 요청 시 scope에 goauthentik.io/api를 추가

NextAuth.js의 AuthentikProvider 설정을 다음과 같이 수정하였다:

const authOptions: NextAuthOptions = {
  debug: true,
  providers: [
    AuthentikProvider({
      id: 'authentik',
      name: 'authentik',
      authorization: {
        url: 'http://localhost:9000/application/o/authorize/',
        params: {
          scope: 'openid email profile offline_access goauthentik.io/api',
        },
      },
      clientId: process.env.NEXT_PUBLIC_AUTHENTIK_CLIENT_ID,
      clientSecret: process.env.NEXT_PUBLIC_AUTHENTIK_CLIENT_SECRET,
      issuer: process.env.NEXT_PUBLIC_AUTHENTIK_ISSUER,
      profile(profile) {
        return {
          id: profile.sub,
          name: profile.name,
          email: profile.email,
        };
      },
    }),
  ],
};

해당 설정 이후, 발급된 Access Token은 API 호출 시 Authorization: Bearer 헤더를 통해 인증 토큰으로 정상 인식되었고, 403 Forbidden 오류는 더 이상 발생하지 않았다.

const authentikRes = await fetch(
  `${process.env.NEXT_PUBLIC_AUTHENTIK_URL}api/v3/authenticators/webauthn/`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  },
);

However, in the production environment, the following error occurred:

GET https://app.wedeo.io/api/auth/webauthn 403 (Forbidden)

✏️ Root Cause

According to the Authentik documentation, JWT access tokens can only be used to authenticate against the API if the OAuth2 scope includes:

goauthentik.io/api

Without this scope, the access token lacks API privileges and is rejected with a 403 Forbidden response, even if the user is otherwise authenticated.

✏️ Solution

Add goauthentik.io/api to the OAuth2 scope when configuring the provider

We updated the AuthentikProvider configuration in NextAuth.js as follows:

AuthentikProvider({
  id: 'authentik',
  name: 'authentik',
  authorization: {
    url: 'http://localhost:9000/application/o/authorize/',
    params: {
      scope: 'openid email profile offline_access goauthentik.io/api',
    },
  },
  clientId: process.env.NEXT_PUBLIC_AUTHENTIK_CLIENT_ID,
  clientSecret: process.env.NEXT_PUBLIC_AUTHENTIK_CLIENT_SECRET,
  issuer: process.env.NEXT_PUBLIC_AUTHENTIK_ISSUER,
  profile(profile) {
    return {
      id: profile.sub,
      name: profile.name,
      email: profile.email,
    };
  },
})

After including this scope, Authentik issued access tokens that were authorized to access the API. As a result, the 403 Forbidden error was resolved.

환경에서 PostgreSQL 데이터베이스에 접근할 때 가장 큰 병목 중 하나는 TCP 연결 시간이다. Workers는 요청마다 콜드스타트를 동반하며, 매번 TCP 핸드셰이크를 수행해야 한다. 이로 인해 단순 SELECT 쿼리조차 평균 500ms 이상의 지연이 발생하는 경우가 많다.

이를 해결하기 위해 Cloudflare Hyperdrive를 적용했고, 그 결과 단순 조회는 평균 10ms 내외, INSERT는 약 200ms 수준까지 응답 속도를 줄이는 데 성공했다. 이 글은 Hyperdrive의 개념부터 적용 방법, 그리고 성능 개선 결과까지 정리한 실전 도입 사례다.

✏️ Hyperdrive란?

◻️ 개요

HyperDrive

: Cloudflare에서 제공하는 SQL 연결 최적화 레이어다.

• PostgreSQL 또는 MySQL과 같은 전통적인 관계형 데이터베이스는 TCP 소켓을 통해 통신하는데, 이때 매 요청마다 발생하는 연결 지연을 Hyperdrive가 해결한다.
• Hyperdrive는 전역에 배포된 Cloudflare 인프라 내에서 연결을 사전 생성 및 풀링하고, 쿼리를 캐싱 및 릴레이하여 요청-응답 시간을 최소화한다.

◻️ 기존 구조의 문제점

• Workers는 상태 없는 실행 환경이기 때문에 매번 새로운 TCP 핸드셰이크가 발생
• PostgreSQL 드라이버는 TLS 설정 등으로 인해 초기 연결에 수백 ms 소요
• 하나의 함수에서 두 번 이상 DB 접근 시, 두 번째 요청부터는 커넥션이 재사용되어 속도는 빨라지지만 첫 요청의 지연은 불가피

◻️ Hyperdrive는 이 문제를 다음과 같이 해결한다.

1. Cloudflare 네트워크 상에 전역으로 배포된 노드에서 DB 연결을 풀링 및 유지
2. 자주 수행되는 쿼리에 대해 스마트 캐싱 전략을 활용하여 RTT를 제거

✏️ Hyperdrive 적용 방법

1. Hyperdrive 설정 생성

npx wrangler hyperdrive create hyperdrive-config \
  --connection-string="postgres://USER:PASSWORD@HOST:5432/DB"

이 명령을 실행하면 Hyperdrive 설정 ID가 출력된다.

2. wrangler.toml 파일에 바인딩 추가

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-08-21"
compatibility_flags = ["nodejs_compat"]

[hyperdrive]
binding = "HYPERDRIVE"
id = "<생성된 Hyperdrive ID>"

3. 타입 선언 파일 생성

npx wrangler types

4. Worker 코드 수정

import postgres from 'postgres'

export default {
  async fetch(request, env, ctx) {
    const sql = postgres(env.HYPERDRIVE.connectionString)

    const data = await sql`SELECT * FROM users LIMIT 1`;
    return new Response(JSON.stringify(data));
  }
}

5. 배포

npx wrangler deploy

✏️ 오류 발생 환경

NextAuth.js의 AuthentikProvider를 다음과 같이 설정:

wellKnown: 'http://server:9000/application/o/wedeo/.well-known/openid-configuration'

이 때 NextAuth.js 라이브러리 내부 코드를 확인한 결과:

• wellKnown 옵션이 존재하면, NextAuth.js는 해당 엔드포인트로 직접 HTTP 요청을 보내어 authorize, token, jwks, userinfo 등의 엔드포인트 URL을 동적으로 가져옴.

• 이 과정에서 다음과 같은 OIDC 메타데이터가 반환됨:

  {
  "authorization_endpoint": "http://server:9000/application/o/authorize/",
  "token_endpoint": "http://server:9000/application/o/token/",
  "userinfo_endpoint": "http://server:9000/application/o/userinfo/",
  "jwks_uri": "http://server:9000/application/o/wedeo/jwks/"
  }

그러나 이 URL들은 브라우저 입장에서 접근이 불가능함:

• 브라우저 → server:9000 → Docker 내부 DNS → 접근 불가 (브라우저는 내부 컨테이너 네트워크를 인식하지 못함)
• 브라우저는 반드시 auth.localhost 와 같은 public-facing 도메인을 통해 접근해야 한다.

✏️ 원인

NextAuth.js는 wellKnown를 통해 OIDC 서버 메타데이터를 자동 수집함.

• wellKnown 응답에 포함되는 모든 엔드포인트가 상대 경로가 아닌 절대 경로로 반환됨.
• Authentik은 이 절대 경로를 PUBLIC_URL 기준으로 계산함 → 현재는 내부 DNS(server:9000) 기준으로 URL을 생성.

따라서, Authorization URL → 브라우저 접근 실패 Token URL → docker 내부 호출 시 Connection refused

특히, 만약 wellKnown에 auth.localhost를 넣더라도 문제가 발생하는데:

Authorization URL은 정상작동하나 이후 토큰 교환 과정에서 Next.js 서버가 auth.localhost에 접근하려다 → ECONNREFUSED 발생 (docker 내부에서 외부 도메인으로 연결 불가)

결국 브라우저용 엔드포인트와 서버용 엔드포인트가 충돌하는 문제 발생.

✏️ 해결방법

wellKnown 자동 요청을 완전히 차단

• wellKnown: null로 설정하여 NextAuth.js가 OIDC 서버 메타데이터를 자동으로 가져오지 않도록 만듦
• 모든 OIDC 엔드포인트를 명시적으로 수동 지정

AuthentikProvider({
  id: 'authentik',
  name: 'authentik',
  authorization: {
    url: 'http://auth.localhost/application/o/authorize/',
    params: { scope: 'openid email profile offline_access' },
  },
  clientId: process.env.NEXT_PUBLIC_AUTHENTIK_CLIENT_ID,
  clientSecret: process.env.NEXT_PUBLIC_AUTHENTIK_CLIENT_SECRET,
  wellKnown: null, // 자동 wellKnown 사용 차단
  jwks_endpoint: 'http://server:9000/application/o/wedeo/jwks/',
  issuer: 'http://server:9000/application/o/wedeo/',
  token: 'http://server:9000/application/o/token/',
  userinfo: 'http://server:9000/application/o/userinfo/',
  profile(profile) {
    return {
      id: profile.sub,
      name: profile.name,
      email: profile.email,
    };
  },
})

Issue: Incorrect Public URL Resolution When Using Authentik as OIDC Provider in Docker with Next.js

In a Next.js project, Authentik was used as the OIDC Provider. Inside a docker-compose setup, Authentik was internally exposed as server:9000. During integration with NextAuth.js, Public URL resolution issues occurred due to how NextAuth.js retrieves OIDC metadata using the wellKnown mechanism, ultimately breaking the OAuth flow.

✏️ Problem Environment

The AuthentikProvider in NextAuth.js was configured as follows:

wellKnown: 'http://server:9000/application/o/wedeo/.well-known/openid-configuration'

By inspecting the NextAuth.js library code directly:

• If wellKnown is specified, NextAuth.js sends an HTTP request to the provided endpoint.
• It dynamically retrieves the OIDC metadata such as authorization, token, userinfo, jwks, etc.

The returned metadata looked like this:

{
  "authorization_endpoint": "http://server:9000/application/o/authorize/",
  "token_endpoint": "http://server:9000/application/o/token/",
  "userinfo_endpoint": "http://server:9000/application/o/userinfo/",
  "jwks_uri": "http://server:9000/application/o/wedeo/jwks/"
}

However, these URLs are inaccessible from the browser:

• Browser → server:9000 → Docker internal DNS → unreachable (browsers have no knowledge of container-internal DNS)
• The browser must always use a public-facing domain such as auth.localhost.

✏️ Root Cause

• NextAuth.js automatically fetches OIDC server metadata using wellKnown.
• The OIDC server (Authentik) returns absolute URLs (not relative paths).
• Authentik generates these URLs based on its configured PUBLIC_URL, which in this case is incorrectly resolved to server:9000.

This causes:

• authorization_endpoint → Browser cannot reach server:9000 → login fails.
• token_endpoint → When exchanging the token, server-to-server call to server:9000 succeeds, but when switched to auth.localhost, it causes ECONNREFUSED inside Docker because containers must use Docker internal DNS.

⚠ Even if wellKnown is pointed to auth.localhost, problems remain:

• Authorization URL works in browser.
• But token exchange fails inside Docker since container cannot resolve external domain auth.localhost.

✏️ Solution

Fully disable automatic wellKnown discovery

• Set wellKnown: null to prevent NextAuth.js from automatically requesting OIDC metadata.
• Manually define all OIDC endpoints to fully control internal vs public routing.

AuthentikProvider({
  id: 'authentik',
  name: 'authentik',
  authorization: {
    url: 'http://auth.localhost/application/o/authorize/',
    params: { scope: 'openid email profile offline_access' },
  },
  clientId: process.env.NEXT_PUBLIC_AUTHENTIK_CLIENT_ID,
  clientSecret: process.env.NEXT_PUBLIC_AUTHENTIK_CLIENT_SECRET,
  wellKnown: null, // disable automatic metadata fetching
  jwks_endpoint: 'http://server:9000/application/o/wedeo/jwks/',
  issuer: 'http://server:9000/application/o/wedeo/',
  token: 'http://server:9000/application/o/token/',
  userinfo: 'http://server:9000/application/o/userinfo/',
  profile(profile) {
    return {
      id: profile.sub,
      name: profile.name,
      email: profile.email,
    };
  },
})

✏️ 오류 발생 환경

Nginx에서 다음과 같이 서브패스 프록시를 구성했었다:

location /authentik/ {
    proxy_pass http://server:9000/;
    ...
}

그러나 브라우저에서 Authentik에 접근하면 다음과 같이 정적 파일 요청 실패가 발생:

GET http://app.localhost/static/dist/main.js 404 (Not Found)
GET http://app.localhost/static/dist/theme.css 404 (Not Found)

✏️ 원인

Authentik은 내부적으로 정적 리소스의 경로를 절대경로(/static/...)로 지정하고 있다. 서브패스를 사용하면 브라우저가 /authentik/static/... 경로를 요청해야 하는데, Authentik은 이를 상대 경로가 아닌 절대경로(/static/...)로 반환하여 충돌 발생.

• 결과적으로 정적 리소스 요청이 전부 404 에러로 실패.

✏️ 해결방법

서브도메인 방식으로 분리하여 각각 독립적인 도메인으로 서비스

• Authentik → auth.localhost
• Next.js → app.localhost

이를 위해 Nginx에서 다음과 같이 도메인 단위로 리버스 프록시 설정을 변경:

server {
    listen 80;
    server_name auth.localhost;

    location / {
        proxy_pass http://authentik:9000;
        ...
    }
}

server {
    listen 80;
    server_name app.localhost;

    location / {
        proxy_pass http://nextjs-app:3000;
        ...
    }
}

이후 Authentik의 PUBLIC_URL을 http://auth.localhost로 지정하여 절대경로 문제도 동시에 해결됨. 이로써 인증 UI, 정적 파일, OIDC 엔드포인트 모두 정상 동작하게 되었다.

✏️ Error Scenario

Initially, Nginx was configured with the following subpath proxy rule:

location /authentik/ {
    proxy_pass http://authentik:9000/;
    ...
}

However, when accessing Authentik in the browser, static resource requests failed:

GET http://app.localhost/static/dist/main.js 404 (Not Found)
GET http://app.localhost/static/dist/theme.css 404 (Not Found)

✏️ Root Cause

Internally, Authentik uses absolute paths (/static/...) for its static resources. When using a subpath, the browser expects URLs like /authentik/static/.... However, Authentik returns absolute URLs such as /static/..., which leads to incorrect requests.

As a result, all static resource requests fail with 404 Not Found errors.

✏️ Solution

Instead of using subpaths, configure separate subdomains to serve each service independently:

• Authentik → auth.localhost
• Next.js → app.localhost

Update Nginx configuration to route by domain:

server {
    listen 80;
    server_name auth.localhost;

    location / {
        proxy_pass http://authentik:9000;
        ...
    }
}

server {
    listen 80;
    server_name app.localhost;

    location / {
        proxy_pass http://nextjs-app:3000;
        ...
    }
}

This resolves the absolute path issue entirely, allowing the authentication UI, static files, and all OIDC endpoints to work correctly.

에러 메시지는 다음과 같다:

npm error node-pre-gyp ERR! install response status 404 Not Found on https://github.com/Automattic/node-canvas/releases/download/...
npm error Package pangocairo was not found in the pkg-config search path.
npm error gyp ERR! stack Error: `gyp` failed with exit code: 1

✏️ 오류 발생 환경

Next.js 프로젝트의 Dockerfile에서 다음과 같이 npm ci를 실행하는 코드가 포함되어 있었다:

RUN npm ci --prefer-offline --no-audit

해당 프로젝트는 canvas 모듈을 사용하고 있었고, 이 모듈은 C++로 구현된 네이티브 확장 모듈이므로 시스템 레벨의 라이브러리와 빌드 도구가 필요하다. 하지만 Docker 이미지에는 이러한 의존성이 포함되어 있지 않아 빌드 실패가 발생하였다.

✏️ 원인

canvas는 사전 빌드된 바이너리를 찾지 못하면 직접 소스 빌드 시도

• 이 과정에서 pkg-config, pangocairo, libcairo2-dev 등 필수 시스템 패키지가 누락되어 빌드 실패
• 기본적으로 사용하는 node 기반 Docker 이미지에는 이러한 라이브러리가 없기 때문에 gyp 빌드가 실패함

✏️ 해결방법

canvas 빌드를 위해 필요한 패키지들을 Dockerfile에 명시적으로 설치한다. 예시는 다음과 같다:

FROM node:20

RUN apt-get update && apt-get install -y \
  build-essential \
  python3 \
  pkg-config \
  libcairo2-dev \
  libpango1.0-dev \
  libjpeg-dev \
  libgif-dev \
  && rm -rf /var/lib/apt/lists/*

위 패키지를 설치한 후 다시 npm ci를 실행하면 canvas 모듈도 문제없이 설치된다. 이제 docker-compose up --build 명령으로도 빌드가 정상 완료되며, Next.js 앱이 정상적으로 구동된다.

에러 메시지는 다음과 같다.

"error_message": "Expected 200 OK from the JSON Web Key Set HTTP response"

✏️ 오류 발생 코드

Authentik에서 발급된 JWT를 jose 라이브러리로 검증하기 위해, 아래와 같이 createRemoteJWKSet으로 JWKS URL을 설정하였다.

const AUTHENTIK_JWKS_URL = c.env.AUTHENTIK_JWKS_URL;
const JWKS = createRemoteJWKSet(new URL(AUTHENTIK_JWKS_URL));

const { payload } = await jwtVerify(token, JWKS, {
  issuer: c.env.AUTHENTIK_ISSUER,
});

하지만... .dev.vars에 분명 JWKS URL을 올바르게 입력했음에도, 여전히 JOSEError: Expected 200 OK... 에러가 발생했다.

✏️ 원인

결론부터 말하자면, 환경변수 덮어쓰기 이슈였다.

로컬 개발 중 npx wrangler dev를 실행했을 때, 예상과는 다르게 c.env.AUTHENTIK_JWKS_URL 값이 .dev.vars의 로컬 값이 아닌, wrangler.toml의 [vars] 혹은 [env.production.vars]에 설정된 값으로 덮어쓰이고 있었던 것이다.

즉, 로컬 개발인데도 배포용 환경변수가 로드되어 localhost 대신 접근 불가능한 URL로 요청을 보내고 있었던 것이다.

✏️ 해결방법

환경별 변수를 명확하게 분리하고, 로컬 개발 환경에서 올바른 환경변수가 로드되도록 설정한다.

wrangler dev 실행 시 반드시 --env 옵션을 명시한다.

npx wrangler dev --env dev

이후에는 문제없이 JWKS URL에 fetch 요청이 성공했고, jwtVerify도 정상적으로 동작하였다.

Stripe의 Checkout Session을 사용하지 않고, 사용자의 카드 정보를 웹사이트 내에서 직접 수집하고 저장하는 방법을 설명한다. 여기서 핵심은 "결제는 하지 않고 카드 정보만 미리 받아두는 것" 이다. 결제는 이후 필요할 때 따로 진행한다.

✏️ 핵심 개념 정리

1. SetupIntent

SetupIntent는 Stripe에서 결제 수단을 미리 등록할 때 사용하는 객체다. 결제는 하지 않지만, 사용자 카드가 유효한지 확인하고 Stripe 서버에 안전하게 저장하는 역할을 한다.

즉, SetupIntent는 "결제 수단을 등록할 준비가 되었다"를 Stripe에 선언하는 것이다.

• 따라서, setupIntent 생성만으로는 아무것도 등록되지 않는다.
• 반드시 confirmCardSetup을 호출해야 결제 수단이 등록된다.

2. PaymentIntent

PaymentIntent는 실제 결제를 실행할 때 사용하는 객체다. SetupIntent로 등록해둔 payment_method를 사용해서 PaymentIntent를 만들어 결제할 수 있다.

3. Stripe Elements

Stripe가 제공하는 클라이언트 측 카드 입력 UI 컴포넌트다. CardElement, PaymentElement 등을 통해 카드 번호, 만료일, CVC 등을 사용자로부터 입력받을 수 있다.

⚠️ 보안상 중요한 점은, 카드 정보가 브라우저에서 Stripe로 직접 전달되므로 서버가 민감 정보를 다루지 않아도 된다는 것이다.

✏️ 코드

전체 흐름 요약

1. 사용자가 웹사이트의 CardElement에 카드 정보를 입력한다.
2. 제출 시, 백엔드 API(/api/create-setup-intent)를 호출해 SetupIntent를 생성하고 client_secret을 받아온다.
3. 프론트엔드는 stripe.confirmCardSetup(client_secret)으로 카드 정보를 인증한다.
4. 인증이 완료되면 Stripe 서버에 payment_method.id가 생성되고 저장된다.
5. 이 ID를 DB에 저장해두고, 나중에 PaymentIntent를 통해 결제에 사용한다.

// stripe 초기화 설정
// Stripe 퍼블리시 키로 초기화
const stripePromise = loadStripe('pk_test_...');

// Elements 컴포넌트에 전달할 옵션 (mode: setup을 명시적으로 지정)
const options = {
  mode: 'setup' as const, // 결제가 아닌 카드 등록 목적
  currency: 'usd',
};

// 최상위 App 컴포넌트에서 Stripe context 구성
export default function App({ children }: { children: React.ReactNode }) {
  return (
    <Elements stripe={stripePromise} options={options}>
      <Provider store={store}>
        <I18nextProvider i18n={i18n}>
          <RecoilRoot>
            <MainWrapper>{children}</MainWrapper>
          </RecoilRoot>
        </I18nextProvider>
      </Provider>
    </Elements>
  );
}

export default function SetupForm() {
  const stripe = useStripe();        // Stripe 객체
  const elements = useElements();    // Stripe Elements 객체

  const [errorMessage, setErrorMessage] = useState(); // 에러 메시지 상태
  const [loading, setLoading] = useState(false);      // 로딩 상태
  const { data: session } = useSession();             // 로그인 세션
  const token = session?.accessToken;                 // 인증 토큰

  const handleError = (error) => {
    setLoading(false);
    setErrorMessage(error.message); // 에러 메시지 설정
  };

  const handleSubmit = async (event) => {
    event.preventDefault();         // 폼 기본 동작 차단 (새로고침 방지)

    if (!stripe) return;            // Stripe.js가 아직 로드되지 않았다면 종료

    setLoading(true);               // 로딩 시작

    const { error: submitError } = await elements.submit(); // 카드 유효성 검사
    if (submitError) return handleError(submitError);

    // 백엔드 API 호출해서 SetupIntent 생성 → clientSecret 반환
    const clientSecret = (await createSetupIntent(undefined, undefined, token)).data;

    // Stripe에 카드 정보 등록 및 인증 요청
    const { error } = await stripe.confirmCardSetup(clientSecret, {
      payment_method: {
        card: elements.getElement(CardElement),
      },
    });

    if (error) {
      // 인증 실패 시 에러 처리
      handleError(error);
    } else {
      // 인증 성공 시 추가 처리 (예: 성공 메시지, DB 저장 등)
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardElement
        options={{
          style: { base: { color: 'white' } }, // 스타일 설정
        }}
      />
      <button type="submit" disabled={!stripe || loading}>
        Submit
      </button>
      {errorMessage && <div>{errorMessage}</div>}
    </form>
  );
}

export const createPaymentMethod = async (
  stripe: Stripe,
  sql: postgres.Sql<{}>,
  userId: string,
): Promise<string> => {
  try {
    // 사용자 정보 조회 (Stripe customer_id 필요)
    const user: usersRowType = await usersRepository.findById(sql, userId);

    // Stripe SetupIntent 생성 (카드 등록만 수행)
    const setupIntent = await stripe.setupIntents.create({
      customer: user.customer_id!,           // Stripe customer 연결
      automatic_payment_methods: { enabled: true }, // 여러 결제 수단 지원 가능 (카드만 사용해도 문제 없음)
    });

    // client_secret을 프론트에 반환 → 카드 인증 시 사용
    return setupIntent.client_secret!;
  } catch (error: any) {
    // 에러 로깅 및 예외 처리
    logger.error('Failed to create payment method', {
      error_message: error.message,
      error_stack: error.stack,
      context: 'stripe.payment-method.ts',
      timestamp: new Date().toISOString(),
    });
    throw new Error(error as string);
  }
}

아래는 동일한 내용을 영어로 정리한 것입니다.

Goal

This guide explains how to collect and save a user's card information directly on your website without using Stripe Checkout Session. The key point is that you're not charging the customer right away, just saving their payment method for later use.

✏️ Core Concepts

1. SetupIntent

SetupIntent is a Stripe object used to register a payment method without charging the customer. It ensures the card is valid and securely saves it to the Stripe server.

Think of SetupIntent as telling Stripe: "I'm preparing to register a payment method."

• Creating a SetupIntent does not register anything by itself.
• You must call confirmCardSetup to actually register the payment method.

2. PaymentIntent

PaymentIntent is used when you're ready to charge the customer. You can use a payment_method saved via SetupIntent to create a PaymentIntent and process the actual payment.

3. Stripe Elements

Stripe Elements are client-side UI components for securely collecting payment information. Examples include CardElement, PaymentElement, etc., which allow users to input their card number, expiry date, CVC, etc.

⚠️ The important security detail: card information is sent directly from the browser to Stripe — your server never touches sensitive data.

✏️ Code

Overall Flow Summary

1. User inputs card info via CardElement on the website.
2. On submit, frontend calls a backend API (/api/create-setup-intent) to create a SetupIntent and receive a client_secret.
3. The frontend calls stripe.confirmCardSetup(client_secret) to authenticate the card info.
4. On success, a payment_method.id is created and stored on the Stripe server.
5. Save this ID in your database and use it later with PaymentIntent to charge the user.

// Stripe initialization
const stripePromise = loadStripe('pk_test_...');

// Stripe Elements config: setup mode
const options = {
  mode: 'setup' as const, // setup only, not payment
  currency: 'usd',
};

// Global app context setup
export default function App({ children }: { children: React.ReactNode }) {
  return (
    <Elements stripe={stripePromise} options={options}>
      <Provider store={store}>
        <I18nextProvider i18n={i18n}>
          <RecoilRoot>
            <MainWrapper>{children}</MainWrapper>
          </RecoilRoot>
        </I18nextProvider>
      </Provider>
    </Elements>
  );
}

export default function SetupForm() {
  const stripe = useStripe();
  const elements = useElements();

  const [errorMessage, setErrorMessage] = useState();
  const [loading, setLoading] = useState(false);
  const { data: session } = useSession();
  const token = session?.accessToken;

  const handleError = (error) => {
    setLoading(false);
    setErrorMessage(error.message);
  };

  const handleSubmit = async (event) => {
    event.preventDefault();
    if (!stripe) return;

    setLoading(true);
    const { error: submitError } = await elements.submit();
    if (submitError) return handleError(submitError);

    const clientSecret = (await createSetupIntent(undefined, undefined, token)).data;

    const { error } = await stripe.confirmCardSetup(clientSecret, {
      payment_method: {
        card: elements.getElement(CardElement),
      },
    });

    if (error) {
      handleError(error);
    } else {
      // success handling (e.g., store payment_method.id)
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardElement
        options={{
          style: { base: { color: 'white' } },
        }}
      />
      <button type="submit" disabled={!stripe || loading}>
        Submit
      </button>
      {errorMessage && <div>{errorMessage}</div>}
    </form>
  );
}

export const createPaymentMethod = async (
  stripe: Stripe,
  sql: postgres.Sql<{}>,
  userId: string,
): Promise<string> => {
  try {
    // Lookup user to get customer_id
    const user: usersRowType = await usersRepository.findById(sql, userId);

    // Create SetupIntent linked to customer
    const setupIntent = await stripe.setupIntents.create({
      customer: user.customer_id!,
      automatic_payment_methods: { enabled: true },
    });

    // Return client_secret to frontend
    return setupIntent.client_secret!;
  } catch (error: any) {
    logger.error('Failed to create payment method', {
      error_message: error.message,
      error_stack: error.stack,
      context: 'stripe.payment-method.ts',
      timestamp: new Date().toISOString(),
    });
    throw new Error(error as string);
  }
}

Next.js 13 App Router 환경

middleware.ts 파일 안에서 getServerSession(authOptions)을 사용해 세션을 가져오려 했지만, session 값이 null인 문제가 발생했다.

✏️ 오류 발생 코드

import { getServerSession } from "next-auth/next";
import { authOptions } from "@/app/api/auth/[...nextauth]/route";

export async function middleware(request: NextRequest) {
  const session = await getServerSession(authOptions);
  console.log(session); // 항상 null
}

✏️ 원인

Github Issue

NextAuth의 getServerSession()은 내부적으로 req.headers.cookie를 읽으려 한다. 그런데 Next.js 미들웨어의 request.headers는 일반적인 객체가 아니라 Headers 타입이다. Headers 객체는 cookie라는 필드로 접근할 수 없고, get("cookie") 메서드를 통해서만 쿠키에 접근할 수 있다.

따라서, 헤더에 담긴 쿠키를 수동으로 읽어와서, 임시 request 객체를 만들어 getSession({ req: 임시객체 })로 넘겨주면 정상적으로 세션을 복원할 수 있다.

✏️ 해결 방법

NextRequest로부터 쿠키를 수동으로 추출해 getSession()에 넘겨줄 수 있는 request 객체를 만들어준다.

import { getSession } from "next-auth/react";

export async function middleware(request: NextRequest) {
  const requestForNextAuth = {
    headers: {
      cookie: request.headers.get("cookie"),
    },
  };

  const session = await getSession({ req: requestForNextAuth });
  const token = session?.accessToken;

  console.log(session);
  console.log(token);
}

• request.headers.get("cookie")를 통해 클라이언트로부터 전달된 쿠키를 가져온다.
• 가져온 쿠키를 포함하는 임시 req 객체를 만들어 getSession({ req })에 넘긴다.

#next-auth getSession null #next-auth getServerSession null #next-auth app router getSession #next-auth app router middleware #next-auth session not found #next-auth getSession cookie issue #next-auth nextrequest getSession #next-auth next.js 13 app router session #next-auth middleware token 가져오기 #next-auth getSession edge runtime #next-auth getSession nextrequest #next-auth getServerSession request headers #next-auth session 복구 오류 #next-auth middleware 인증 문제 #next-auth app router 인증 처리 #next-auth session token 직접 전달

이 문서는 React와 styled-components를 활용해 "한 화면씩 넘기는 원 페이지 스크롤" 기능을 구현하는 방법을 설명합니다. 사용자는 마우스 휠을 통해 슬라이드를 하나씩 전환하며, 각 슬라이드는 전체 화면(viewport)을 채우는 구조로 구성됩니다.

1. 시작: 스크롤 이벤트 감지

원 페이지 스크롤의 핵심은 사용자의 휠 스크롤 이벤트를 감지하는 것입니다. 브라우저는 기본적으로 사용자가 마우스 휠을 움직일 때마다 wheel 이벤트를 발생시킵니다.

이 이벤트는 deltaY라는 값을 포함하고 있어, 사용자가 스크롤을 위로 움직였는지(음수) 아래로 움직였는지(양수)를 확인할 수 있습니다.

스크롤 이벤트를 감지하려면 다음을 설정합니다:

• 특정 요소(보통 전체 페이지를 감싸는 div)에 이벤트 리스너를 추가
• passive: false 옵션을 주어 기본 동작(브라우저의 스크롤)을 막을 수 있음

2. 동작: 현재 슬라이드 인덱스 업데이트

휠 스크롤이 감지되면 다음 단계는 현재 사용자가 보고 있는 슬라이드 인덱스를 갱신하는 작업입니다.

이를 위해 내부적으로 유지되는 currentPage 상태값을 사용하여:

• 아래로 스크롤 시: currentPage를 1 증가
• 위로 스크롤 시: currentPage를 1 감소
• 첫 페이지와 마지막 페이지에서는 더 이상 이동하지 않도록 제한

이 로직은 사용자 스크롤에 따라 어떤 슬라이드를 보여줄지를 판단하는 핵심 기준이 됩니다.

3. 결과: 화면 이동 (스크롤 위치 제어)

슬라이드 인덱스가 변경되면, 해당 인덱스에 맞는 화면 위치로 스크롤을 프로그래밍적으로 이동시킵니다.

이를 위해 scrollTo 또는 scrollTop 값을 직접 조작하여:

• 예를 들어, 2번째 슬라이드 = 2 * 화면 높이 (100vh)로 계산
• 부드러운 이동을 위해 behavior: 'smooth' 옵션 사용

이 과정을 통해 마우스 휠 한 번에 정확히 한 슬라이드씩 이동하는 느낌을 줄 수 있습니다.

4. 부가 처리: 스크롤 이벤트 최적화

스크롤 이벤트는 매우 자주 발생할 수 있으므로, 다음과 같은 처리가 추가로 필요합니다:

• 스크롤 중복 방지: 스크롤 중에는 추가 입력을 막기 위해 잠깐 상태를 잠그는 방식 사용 (debounce 또는 flag 활용)
• 페이지 범위 체크: 0보다 작거나, 슬라이드 총 개수를 초과하지 않도록 제한
• 모바일 대응: 터치 이벤트 (touchstart, touchend)도 별도 감지 필요

5. 결론

원 페이지 스크롤은 마우스 휠을 감지하고, 현재 페이지를 기준으로 다음 화면 위치를 계산해 스크롤하는 구조입니다. 이 과정은 스크롤 이벤트 감지 → 현재 위치 판단 → 위치 이동이라는 순서를 반복하면서 동작합니다.

구현은 간단해 보이지만, UX 관점에서 부드럽고 안정적인 전환을 위해 이벤트 제어와 스크롤 상태 관리가 중요합니다.

1. 구조 개요

기본 구조는 다음과 같습니다:

• Base: 전체 스크롤을 제어하는 컨테이너 (스크롤 대상)
• SliderContainer: 모든 슬라이드를 포함하는 요소 (높이 = 슬라이드 개수 x 100vh)
• 각 Slide: 개별 페이지 (높이 100vh)

<Base ref={containerRef}>
  <SliderContainer>
    <Slide />
    <Slide />
    <Slide />
  </SliderContainer>
</Base>

2. 슬라이드 이동 구현 방법

2.1 scrollToPage 함수

window.innerHeight를 기준으로 슬라이드 위치 계산:

const scrollToPage = (index: number) => {
  if (!containerRef.current) return;
  const targetScrollTop = index * window.innerHeight;
  containerRef.current.scrollTo({
    top: targetScrollTop,
    behavior: "smooth",
  });
  setCurrentPage(index);
};

2.2 마우스 휠 이벤트 처리

사용자의 휠 스크롤을 감지해 현재 페이지 상태에 따라 scrollToPage 호출:

useEffect(() => {
  const handleWheel = (e: WheelEvent) => {
    e.preventDefault();
    if (e.deltaY > 0 && currentPage < slides.length - 1) {
      scrollToPage(currentPage + 1);
    } else if (e.deltaY < 0 && currentPage > 0) {
      scrollToPage(currentPage - 1);
    }
  };

  const container = containerRef.current;
  if (container) {
    container.addEventListener("wheel", handleWheel, { passive: false });
  }
  return () => {
    if (container) {
      container.removeEventListener("wheel", handleWheel);
    }
  };
}, [currentPage, slides.length]);

3. 스타일 구성

const Base = styled.div`
  height: 100vh;
  overflow-y: auto;
  scroll-behavior: smooth;
`;

const SliderContainer = styled.div`
  height: calc(100vh * 슬라이드 개수);
`;

const Slide = styled.div`
  height: 100vh;
  width: 100vw;
  display: flex;
  align-items: center;
  justify-content: center;
`;

슬라이드는 반드시 height: 100vh로 설정되어야 하며, 컨테이너는 슬라이드 개수만큼 높이를 갖도록 해야 스크롤이 제대로 작동합니다.

4. 주의사항 및 개선 포인트

• IntersectionObserver를 활용하여 슬라이드 진입 시 애니메이션 트리거 가능
• 모바일 터치 이벤트 처리 필요시 touchstart / touchend 이벤트 별도 추가
• 슬라이드 개수가 많을 경우 throttle 또는 debounce를 통해 이벤트 최적화 필요

5. 결론

React 환경에서 원 페이지 스크롤을 구현하기 위해서는 각 섹션을 정확히 100vh로 분할하고, 사용자 스크롤에 맞춰 정확한 위치로 이동시키는 제어가 핵심입니다. 이를 통해 보다 몰입감 있는 인터랙티브 웹페이지를 제작할 수 있습니다.

React에서 자주 쓰이는 주요 속성들인 ref, key, className, onClick, style, children에 대해 정리한 문서이다.

1. ref

◼︎ 역할

• 특정 DOM 요소에 직접 접근할 수 있게 해준다.
• focus, scroll, style 등을 직접 조작할 때 사용

◼︎ 사용 예

import { useRef, useEffect } from 'react';

function FocusInput() {
  const inputRef = useRef<HTMLInputElement>(null);

  useEffect(() => {
    inputRef.current?.focus();
  }, []);

  return <input ref={inputRef} />;
}

ref는 일반적인 props와는 달리, 실제 HTML 요소를 참조하는 특수한 prop입니다.

2. key

◼︎ 역할

• React가 리스트를 렌더링할 때, 각 항목을 고유하게 식별할 수 있게 해줍니다.
• 어떤 요소가 변경, 추가, 삭제되었는지를 빠르게 파악할 수 있게 하여 성능 향상에 중요합니다.

◼︎ 어떻게 작동하나요?

React는 리스트 요소들을 다시 그릴 때, key를 기준으로 "이전 요소와 같은지" 판단합니다. key가 같으면 재사용, 다르면 다시 렌더링합니다.

◼︎ 사용 예

const fruits = [
  { id: 'a1', name: '🍎 사과' },
  { id: 'b2', name: '🍌 바나나' },
  { id: 'c3', name: '🍇 포도' },
];

return (
  <ul>
    {fruits.map((fruit) => (
      <li key={fruit.id}>{fruit.name}</li>
    ))}
  </ul>
);

❗ 단순히 index를 key로 사용하는 것은 항목의 순서가 바뀌는 경우 예기치 않은 렌더링 문제가 생길 수 있으므로 주의해야 합니다.

3. className

◼︎ 역할

• HTML의 class 대신 React에서는 className을 사용해야 합니다. (JS 예약어 class와 충돌 방지)

◼︎ 사용 예

<div className="card-container">Hello</div>

4. onClick, onChange, onSubmit 등

◼︎ 역할

• 이벤트 처리 함수를 등록하는 속성입니다.
• 반드시 camelCase로 작성해야 합니다 (onclick ❌ → onClick ✅)

◼︎ 사용 예

<button onClick={() => alert("눌렀어요!")}>Click Me</button>
<input onChange={(e) => console.log(e.target.value)} />

5. style

◼︎ 역할

• 인라인 스타일을 적용할 때 사용합니다.
• 객체 형태로 작성하며, CSS 속성은 camelCase로 표기합니다.

◼︎ 사용 예

<div style={{ backgroundColor: 'skyblue', padding: '20px' }}>
  스타일이 적용된 박스
</div>

6. children

◼︎ 역할

• 컴포넌트 태그 안에 들어가는 모든 요소를 의미합니다.
• 부모 컴포넌트가 자식 콘텐츠를 유연하게 구성할 수 있게 해줍니다.

◼︎ 사용 예

function Card({ children }: { children: React.ReactNode }) {
  return <div className="card">{children}</div>;
}

<Card>
  <h2>제목</h2>
  <p>내용입니다</p>
</Card>

props vs attributes 차이점

1. attributes

정의:

HTML 태그에서 사용하는 전통적인 속성. 브라우저가 직접 해석해서 동작합니다.

<!-- HTML에서의 attributes -->
<input type="text" placeholder="이름을 입력하세요" />

• type, placeholder, disabled, checked, value 등은 HTML이 해석하는 속성입니다.

2. props (React 속성)

정의:

컴포넌트에 데이터를 전달하는 수단입니다. JavaScript 객체의 형태로 전달되며, JS 내부에서 자유롭게 사용할 수 있습니다.

function Welcome({ name }: { name: string }) {
  return <h1>Hello, {name}</h1>;
}

<Welcome name="민수" />

• name은 props이며, 함수의 인자로 전달되어 컴포넌트 내부 로직에 활용됩니다.

주요 차이점 비교

$ prefix로 props와 HTML attributes 구분하기

◼︎ 문제 상황

React에서는 props가 실제 DOM 요소에도 전달될 수 있는데, HTML 태그가 인식하지 못하는 props가 그대로 전달되면 경고가 발생합니다.

const Box = styled.div<{ highlight: boolean }>`
  background-color: ${(props) => (props.highlight ? "yellow" : "white")};
`;

<Box highlight={true}>강조된 박스</Box>

⚠️ 경고: React does not recognize the 'highlight' prop on a DOM element

highlight는 HTML의 표준 속성이 아니므로,

const Box = styled.div<{ $highlight: boolean }>`
  background-color: ${(props) => (props.$highlight ? "yellow" : "white")};
`;

<Box $highlight={true}>강조된 박스</Box>

// 최상위 App 컴포넌트
function App() {
  const [user, setUser] = useState({ name: 'Jin' });
  return <Parent user={user} />;
}

// App의 하위 컴포넌트 Parent
function Parent({ user }) {
  return <Child user={user} />;
}

// Parent의 하위 컴포넌트 Child
function Child({ user }) {
  return <p>Hello, {user.name}</p>;
}

// store/index.ts
import { configureStore } from '@reduxjs/toolkit';
import authReducer from './slices/authSlice';

export const store = configureStore({
  reducer: {
    auth: authReducer,
  },
});

{
  type: 'SET_USER',
  payload: { name: 'Jin' }
}

// store/authSlice.ts
const authSlice = createSlice({
  name: 'auth',
  initialState: { user: null },

  // 여기에 함수들을 정의한다.
  reducers: {

    // 이 함수는 dispatch(setUser(payload))가 실행됐을 때 동작한다.
    // user state의 값에 payload의 값을 대입한다.
    setUser(state, action) {
      state.user = action.payload;
    },

    // 이 함수는 dispatch(updateCurrentTeam(payload))가 실행되었을 때 동작한다.
    updateCurrentTeam: (state, action) => {
      state.user.currentTeam = action.payload;
    },
    ...

  },
});

// store/slices/authSlice.ts
import { createSlice } from '@reduxjs/toolkit';

const authSlice = createSlice({
  name: 'auth',
  initialState: {
    user: null,
  },
  reducers: {
    // user 상태를 바꾸는 동기 Action
    setUser(state, action) {
      state.user = action.payload;
    },
  },
});

export const { setUser } = authSlice.actions;
export default authSlice.reducer;

import { configureStore } from '@reduxjs/toolkit';
import authReducer from './slices/authSlice';

export const store = configureStore({
  reducer: {
    auth: authReducer,
  },
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

import { useAppDispatch, useAppSelector } from '@/store/hooks';
import { setUser } from '@/store/slices/authSlice';

function Profile() {
  const dispatch = useDispatch();
  const user = useAppSelector((state) => state.auth.user);

  return (
    <div>
      <p>User: {user}</p>
      <button onClick={() => dispatch(setUser('JIM'))}>Set User</button>
    </div>
  );
}

const user = useAppSelector((state) => state.auth.user);

const dispatch = useDispatch();
dispatch(setUser('JIM'));

// 예시: Action 내부에서 백엔드 API 호출 함수인 getUSer()를 사용하는 경우
// 비동기 함수를 정의한다.
export const setUser = createAsyncThunk(
  'auth/setUserStatus',
  async (currentUser, { rejectWithValue }) => {
    const result = await getUser(...);
    return result.data.user;
  }
);

AUTHENTIK_EMAIL__HOST=smtp.sendgrid.net
AUTHENTIK_EMAIL__PORT=587
AUTHENTIK_EMAIL__USERNAME=apikey
AUTHENTIK_EMAIL__PASSWORD=SG.패스워드내용
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__USE_SSL=false
AUTHENTIK_EMAIL__FROM=이메일주소

window.location.href = http://localhost:9000/if/flow/default-authenticator-webauthn-setup;

import { Inngest } from "inngest";

export const inngest = new Inngest({
  id: "wedeo-inngest",
  baseUrl: process.env.INNGEST_BASE_URL,
  eventKey: process.env.INNGEST_EVENT_KEY,
});

import { serve } from "inngest/next";
import { inngest } from "./client";
import { onFileInBucketCreate } from "./workflow";

export const { GET, POST, PUT } = serve({
  client: inngest,
  functions: [onFileInBucketCreate],
});

import { inngest } from "./client";

export const onFileInBucketCreate = inngest.createFunction(
  { id: "on-file-in-bucket-create" },
  { event: "file.uploaded" },
  async ({ event, step }) => {
    const { userId, fileId } = event.data;

    await step.run("Call worker's post-upload handler", async () => {
      const res = await fetch("http://localhost:8787/storage/post-upload", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ userId, fileId }),
      });

      if (!res.ok) {
        throw new Error(`Worker 처리 실패: ${await res.text()}`);
      }
    });

    return { status: "ok" };
  }
);

export const uploadFileToStorage = async (
  bucket: R2Bucket,
  inngestBaseUrl: string,
  inngestEventKey: string,
  filePath: string,
  userId: string,
  fileId: string,
  file: Buffer,
) => {
  await bucket.put(filePath, file);

  const response = await sendInngestEvent(inngestBaseUrl, inngestEventKey, "file.uploaded", {
    userId,
    fileId,
  });

  return filePath;
};

export const sendInngestEvent = async (
  inngestBaseUrl: string,
  inngestEventKey: string,
  name: string,
  data: any
) => {
  return await fetch(`${inngestBaseUrl}/e/${inngestEventKey}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name, data }),
  });
};

npm install bull

// queue.js
import Queue from 'bull'

// Redis에 연결된 큐 생성
const myQueue = new Queue('my-job-queue', {
  redis: {
    host: 'localhost',
    port: 6379,
  },
})

// 작업 추가
myQueue.add({
  type: 'sendEmail',
  email: 'user@example.com',
})

// worker.js
import Queue from 'bull'

const myQueue = new Queue('my-job-queue', {
  redis: {
    host: 'localhost',
    port: 6379,
  },
})

myQueue.process(async (job) => {
  const { type, email } = job.data
  if (type === 'sendEmail') {
    // 이메일 전송 로직
    console.log(`Sending email to ${email}`)
  }
})