앱에 이미 작동하는 인증 시스템과 실제 사용자 데이터베이스가 있는 경우, Clerk Auth를 도입하는 것은 단순한 코드 변경이 아닌 데이터 마이그레이션입니다. 신중한 계획 없이는Documentation Index
Fetch the complete documentation index at: https://docs.replit.com/llms.txt
Use this file to discover all available pages before exploring further.
users 테이블의 모든 기존 행이 Clerk에게는 낯선 사람이 됩니다: 새 계정이 첫 번째 로그인 시 프로비저닝되고, 기존 데이터와 일치하지 않으며, 기존 고객들이 계정을 “잃어버린” 것처럼 보이게 됩니다.
실제로 올바르게 처리해야 할 사항은 두 가지뿐입니다.
이 페이지는 사용자 정의 인증 솔루션(자체 users 테이블, 비밀번호 해싱, 세션 등)에서 Clerk Auth로 마이그레이션하는 경우만 다룹니다. Replit Auth에서 Clerk Auth로 앱을 이전하기 위한 가이드가 아닙니다 — 해당 마이그레이션 경로에 대한 공식 가이드는 곧 제공될 예정입니다.새 앱을 시작하는 경우 Clerk Auth 개요를 참조하세요 — 마이그레이션이 필요하지 않습니다.
1. 기존 사용자를 Clerk으로 가져오기
앱의 모든 활성 사용자는 Clerk Auth가 활성화되기 전에 Clerk 사용자로 존재해야 합니다. 각 가져오기에는 최소한 다음이 포함되어야 합니다:- 이메일 (필수)
- 사용 가능한 프로필 메타데이터: 이름, 인증 상태, Auth 창에 표시하고 싶은 기타 정보
- 비밀번호 다이제스트: 사용자의 기존 비밀번호 해시
- 비밀번호 해셔: Clerk이 기대하는 형식 그대로의 해시 알고리즘/형식
bcrypt, scrypt_firebase, argon2i, pbkdf2_sha256 등)를 가집니다. 전체 목록과 각각이 요구하는 정확한 다이제스트 형식은 Clerk Create User API 레퍼런스를 참조하세요.
이 단계는 한 줄짜리 프롬프트 이상이 필요합니다. 마이그레이션을 구동하는 Agent는 현재 코드베이스에서 비밀번호가 어떻게 해싱되는지에 대한 철저한 이해가 필요합니다 — 어떤 라이브러리, 어떤 파라미터(비용 계수, 솔트 레이아웃, 페퍼 등), 그리고 이것이 Clerk의 지원 해셔 중 하나에 어떻게 매핑되는지. 잘 구성된 프롬프트는 다음과 같습니다:
2. Clerk 사용자를 기존 사용자 ID로 연결
가져온 사용자들이 로그인하면 모든 인증된 요청에 Clerk ID가 포함됩니다. 서버는 해당 ID를users 테이블의 행에 다시 매핑해야 합니다 — 그렇지 않으면 Clerk 사용자 ID가 기존 외래 키(orders.user_id, documents.owner_id 등)와 일치하지 않아 기록 데이터가 사라진 것처럼 보입니다.
Replit 관리 Clerk은 이를 간단하게 만들어줍니다: 기존 ID를 Clerk 사용자의 externalId로 포함하여 사용자를 가져오면, 해당 값이 세션 클레임에 sessionClaims.userId로 자동으로 기록됩니다. 미들웨어는 이를 원시 Clerk 사용자 ID보다 우선시하기만 하면 됩니다:
- 가져온 사용자는
sessionClaims.userId를 통해 기존users.id로 연결됩니다 — 모든 기록 데이터가 유지됩니다. - 새 사용자(전환 후 가입했으며
externalId가 없는 사용자)는auth.userId로 폴백됩니다. Clerk 사용자 ID를 새 행의 기본 키로 사용하거나, 첫 번째 로그인 시 행을 생성하고 다시 연결하세요.
완료
이외의 모든 것 — 이전 인증을 병렬로 계속 실행하기, 실제 계정에 대한 드라이런 실행하기, 전환 후 중복 사용자 생성 모니터링하기, 이전 시스템 폐기하기 — 은 Clerk Auth에 특화된 것이 아닌 표준 마이그레이션 위생 관리입니다.추가 리소스
- Clerk Auth 개요 — Replit에서 Clerk Auth가 작동하는 방식
- Clerk: Create User API — 지원되는 비밀번호 해셔 및 다이제스트 형식