무료 자막 API 연결 — 관리자 한 번 설정
Supadata는 자막 API, Supabase는 기존 DB입니다. 서로 다른 서비스입니다. 앱은 먼저 YouTube 공개 영어 자막을 무료로 확인하고, 실패할 때만 Supadata Free를 사용합니다. 확보한 텍스트만 Gemini에 보내 교재를 만듭니다.
- Supadata의 Free 무료 계정으로 가입해 API 키를 받습니다. 결제·유료 업그레이드는 하지 마세요. 현재 Free는 월 100 credits이며 정책은 바뀔 수 있습니다.
- 앱 관리자 → AI·자막 API → Supadata 연결에서 키 입력 → 연결 확인 후 저장을 누릅니다.
- 테스트할 영상 URL을 입력하고 이 영상 자막 가져오기 테스트를 누릅니다. 무료 제공량을 사용하며 Gemini는 호출하지 않습니다.
- 일반 화면에서 URL → 교재 생성을 누르면 자막 확보 후 AI 교재 생성 순서로 진행합니다. 실패해도 확보한 자막은 입력란에 남습니다.
Supadata 요청 전에 Free 플랜과 남은 제공량을 확인합니다. 유료 플랜·한도 소진·확인 실패이면 전문 API를 사용하지 않고 무료 사이트 안내로 전환합니다. native 모드로 기존 자막만 조회하며 auto/generate 음성 전사를 요청하지 않습니다. 선택적으로 Cloudflare Secret SUPADATA_API_KEY를 넣을 수도 있으나 관리자 화면이 더 간편합니다.
Gemini도 본인의 무료 사용 프로젝트 키인지 확인하세요. 앱은 Google 프로젝트의 결제 연결 여부를 판별하지 못합니다. 무료 무제한·모든 영상 성공은 보장할 수 없으며 운영 키를 통한 검증은 아직 하지 못했습니다. 상세 내용은 docs/UPDATE_V1_9.md에 있습니다.
v1.9.0 — 교재 관리와 실패 안내
- v1.8까지 설치했다면 Supabase SQL Editor에 supabase/bank_v1_9.sql 전체를 붙여넣고 Run을 누릅니다. 이전 SQL 미적용이면 repair_save_v1_7.sql → study_progress_v1_8.sql → bank_v1_9.sql 순서입니다.
- 코드 배포 후 /api/health의 version 1.9.0을 확인합니다. 환경변수 추가는 없습니다.
- 상단 교재 관리에서 검색·같은 영상/대본 선택·내용 정리를 사용합니다. 삭제 전 제목·개수를 확인하세요. 삭제는 되돌릴 수 없고 연결된 복습 기록도 제거됩니다. 필요하면 JSON 백업을 내려받으세요(자동 복원 기능은 없음).
- URL 분석 실패 안내창에서 주소 복사 → 자막 사이트 → 앱 붙여넣기 또는 파일 선택 순서로 진행합니다. API 키·사용 한도 문제는 관리자가 별도로 확인해야 합니다.
관리자만 전체 사용자 범위를 선택할 수 있습니다. 같은 대본 비교는 저장된 텍스트 기준이며 전체 대본 없는 교재에는 제공하지 않습니다. 모든 영상 분석 성공을 보장하지 않습니다. 운영 API·DB·휴대폰 실화면 검증은 별도로 필요합니다. 상세 내용: docs/UPDATE_V1_9.md
v1.8.0 — 파일 없이 공부하는 학습 교재
학습 탭에서 영어 발음, 문장 체크 후 선택 듣기, 문장별/전체 반복, 속도·간격 조절, 영어/번역 가리기와 통합 복습을 사용하세요. 발음은 기기 영어 음성이며 검증된 구간은 영상 원음도 지원합니다.
자동 테스트 결과는 TEST_REPORT.md에 있습니다. 운영 API·SQL 실행·PC/모바일 실제 화면 검증은 별도로 필요합니다. 아래는 이전 버전 설치 안내와 이력입니다.
v1.7.0 필수 업데이트 — 저장 오류 수정과 간편 입력
- Supabase 프로젝트 → SQL Editor → New query를 엽니다.
- ZIP의 supabase/repair_save_v1_7.sql 전체를 복사해 붙여넣고 Run을 누릅니다. 기존 v1.2 이상 설치용이며 기존 학습 데이터는 삭제하지 않습니다. 처음 설치하는 경우에는 수정된 schema.sql을 사용하세요.
- 수정 파일을 GitHub 저장소의 같은 위치에 반영합니다. public/assets/js/config.js의 본인 프로젝트 설정을 확인하세요.
- Cloudflare Pages 배포 완료 후 /api/health의 version이 1.7.0인지 확인하고 앱을 강력 새로고침합니다.
- URL 없이 짧은 SRT/TXT 파일로 교재 생성·저장을 시험합니다. 이어 자막 있는 영상과 자막을 못 가져오는 영상을 시험하세요.
새 환경변수, Worker, Cron 설정은 필요 없습니다. 저장 함수의 열 이름 충돌과 Gemini 영상 입력 형식을 수정했습니다.
사용자가 달라지는 점
- URL만 입력: 자막 우선, 실패하면 체크된 자동 전환 옵션에 따라 AI 영상 분석. 영상 전송·추가 API 사용량 안내를 보고 원하지 않으면 체크를 끄세요.
- 파일만 입력: TXT/SRT/VTT로 URL 없이 교재 생성. 연결 영상이 없으면 원음 재생은 제공하지 않습니다.
- 저장 실패: 결과를 받은 뒤 1시간 동안 저장만 다시 시도. AI를 다시 호출하지 않습니다. SQL 오류 안내가 뜨면 먼저 위 수정 SQL을 실행하세요.
- 새로고침: 같은 탭에서 입력과 재시도 결과 복구. 로그아웃하면 삭제되며 탭을 닫으면 복구가 보장되지 않습니다.
- 외부 대안: 자막 도움말의 URL 복사 → YouTube 또는 외부 서비스 열기 → 자막 붙여넣기.
자동 테스트 57개·정적 검사 145개 통과. 실제 운영 서버·SQL 실행·브라우저 화면 검증은 미완료입니다. 자세한 변경/제약과 검증용 SQL은 docs/UPDATE_V1_7.md를 참고하세요.
이전 버전 기록: v1.6.0 업데이트 — 일반 분석으로 단순화
- 기존 Cloudflare의 tubeenglish-analysis-worker에서 Cron Trigger를 제거해 이전 작업 실행을 먼저 중지합니다. Pages 앱 tubeenglish-study는 유지하세요.
- 수정 파일을 GitHub에 덮어쓰고, ZIP의 DELETE_FILES.txt에 있는 이전 파일도 삭제합니다. 전체 목록과 쉬운 적용 순서는 docs/UPDATE_V1_6.md에 있습니다.
- Cloudflare Pages 배포 성공 후 앱을 새로고침합니다.
- 로그인 후 짧은 영어 대본으로 교재 생성을 확인합니다.
- 별도 Worker의 Git 자동 빌드 연결을 해제하고 더 이상 사용하지 않는 tubeenglish-analysis-worker를 삭제할 수 있습니다. 학습 데이터가 있는 Supabase 프로젝트는 삭제하지 마세요.
자막을 먼저 확인하고, 없으면 직접 대본을 넣거나 동의 후 Gemini로 영상 분석을 선택합니다. 긴 대본은 최대 24,000자를 발췌하여 한 번 분석하므로 전체 요약이 아닙니다. 이전 ANALYSIS_JOBS_ENABLED 설정은 삭제해도 되며 이 버전에서 읽지 않습니다.
0. 시작 전에 준비할 것
아래 계정 4개만 있으면 됩니다. 모두 처음에는 무료 플랜으로 시작할 수 있습니다.
| 서비스 | 용도 | 주소 |
|---|---|---|
| GitHub | 소스코드 Private 저장소 | github.com |
| Cloudflare | 웹 호스팅 + 서버 API | dash.cloudflare.com |
| Supabase | 로그인 + PostgreSQL DB | supabase.com |
| Google AI Studio | Gemini API Key | aistudio.google.com |
1. 앱의 전체 구조
브라우저에는 Supabase Publishable Key만 있습니다. Gemini API Key와 Supabase Secret Key는 Cloudflare 서버 영역에만 있습니다. 전체 대본과 AI 분석 원본은 소유자에게만 제공되며, 브라우저가 직접 DB에 INSERT할 수 없습니다.
2. ZIP을 풀고 파일 확인
압축을 풀면 아래처럼 보여야 합니다.
3. Supabase 프로젝트 만들기
새 프로젝트를 만듭니다. 예: tubeenglish-study.
길고 안전한 비밀번호를 만들어 별도 비밀번호 관리자에 보관하세요.
주 사용자가 한국이라면 가능한 가까운 Asia region을 선택하세요.
왼쪽에 SQL Editor / Table Editor / Authentication이 보이면 됩니다.
4. Supabase DB를 한 번에 설치
설치되는 핵심 테이블은 다음과 같습니다.
| 테이블 | 역할 |
|---|---|
| profiles | 사용자 표시명과 user/admin 역할 |
| videos | YouTube 영상, 공개/비공개, 관리자 숨김/추천 |
| analyses | Gemini 분석 JSON 원본과 버전 |
| expressions | 개별 영어 표현, 타임스탬프, CEFR, AI 점수, 대표형 |
| user_expression_progress | 중요/헷갈림/외움, 듣기·반복·받아쓰기, 개인 메모, 복습일 |
| study_events | 장기 학습 이벤트 통계 |
| app_settings | 커뮤니티 운영 설정 |
| app_secrets | Gemini 키의 AES-GCM 암호문만 저장 |
| community_recommendations | 관리자 공식 추천 표현 |
5. 브라우저용 Supabase 정보 입력
Cloudflare 환경변수는 서버 Functions용입니다. 정적 브라우저 JavaScript에는 별도로 Supabase Project URL과 Publishable Key를 넣어야 합니다.
6. Supabase 로그인 설정
이메일 로그인
Supabase → Authentication → Providers에서 Email provider가 켜져 있는지 확인합니다.
테스트 중 이메일 인증
처음 혼자 테스트할 때 이메일 확인 절차가 번거롭다면 Auth 설정에서 이메일 확인 정책을 확인할 수 있습니다. 실제 공개 서비스에서는 이메일 인증을 사용하는 편이 안전합니다.
배포 후 URL 설정
Cloudflare 배포 후 Supabase → Authentication → URL Configuration에서:
7. GitHub Private 저장소에 업로드
초보자에게 쉬운 GitHub Desktop 방법
터미널 방법
8. GitHub Private 저장소를 Cloudflare Pages에 연결
| 설정 | 값 |
|---|---|
| Production branch | main |
| Framework preset | None |
| Build command | exit 0 |
| Build output directory | public |
| Root directory | 비움 |
Cloudflare의 현재 Static HTML 안내에서도 build가 필요 없는 프로젝트에 exit 0과 정적 output directory 사용을 안내합니다. functions 폴더는 public 안이 아니라 저장소 최상위에 있어야 Pages Functions 라우트가 생성됩니다.
9. Cloudflare Variables and Secrets 설정
이 프로젝트는 저장소 최상위의 wrangler.toml을 Cloudflare Pages 설정 파일로 사용합니다. 이 경우 Cloudflare Dashboard의 Variables and Secrets 화면에서 일반 Variable 타입을 선택하지 못하고 Secret으로 고정되어 보일 수 있습니다. 오류가 아닙니다. 일반 Variable은 wrangler.toml에 등록하고, 민감한 Secret만 Cloudflare Dashboard에 등록하면 됩니다.
9-1. 먼저 전체 설정 구조를 이해하세요
TubeEnglish Study v1.2.0에서는 아래처럼 두 곳에 나누어 설정하는 것을 권장합니다.
| 이름 | 저장 위치 | 값 예시 | 필수 여부 |
|---|---|---|---|
| SUPABASE_URL | wrangler.toml | https://xxxxx.supabase.co | 필수 |
| SUPABASE_PUBLISHABLE_KEY | wrangler.toml | sb_publishable_xxxxx | 필수 |
| GEMINI_MODEL | wrangler.toml | gemini-3.7-flash | 기본값이며 관리자 화면 선택값이 우선 |
| GEMINI_THINKING_LEVEL | wrangler.toml | medium | 권장 |
| GEMINI_API_REVISION | wrangler.toml | 2026-05-20 | 권장 |
| MAX_ANALYSES_PER_DAY | wrangler.toml | 10 | 권장 |
| SUPABASE_SECRET_KEY | Cloudflare Secret | sb_secret_xxxxx | 필수 |
| APP_ENCRYPTION_KEY | Cloudflare Secret | 32바이트 Base64 | 필수 |
| GEMINI_API_KEY | Cloudflare Secret 또는 관리자 화면 | 선택 fallback | 선택 |
일반 Variable을 억지로 Secret으로 등록하지 말고 아래 9-2 단계에서 wrangler.toml에 넣으세요. wrangler.toml을 삭제할 필요도 없습니다.
9-2. 일반 Variable 6개를 wrangler.toml에 등록
초보자에게는 GitHub 웹사이트에서 직접 파일을 수정하는 방법이 가장 쉽습니다.
파일 목록에서 저장소 최상위의 wrangler.toml을 클릭합니다.
현재 파일은 보통 아래처럼 시작합니다.
SUPABASE_URL과 SUPABASE_PUBLISHABLE_KEY 두 값만 본인 Supabase 값으로 바꾸고, 나머지는 아래 값을 그대로 사용하면 됩니다.
기존 [vars] 아래에 필요한 항목만 추가하거나 값을 수정합니다.
SUPABASE_URL / Publishable Key는 어디서 찾나요?
Supabase Dashboard → 본인 프로젝트 → Connect 또는 Settings → API Keys에서 확인합니다.
- Project URL → SUPABASE_URL에 입력
- Publishable key → SUPABASE_PUBLISHABLE_KEY에 입력
Commit 메시지는 예를 들어 Add Cloudflare environment variables라고 입력하면 됩니다. main 브랜치에 반영되면 Cloudflare Pages가 GitHub 연결을 통해 자동으로 새 배포를 시작합니다.
9-3. 민감한 Secret은 Cloudflare Dashboard에 등록
Cloudflare Dashboard → Workers & Pages → tubeenglish-study → Settings → Variables and Secrets로 이동합니다. Production 환경부터 설정하세요.
여기에서 타입이 Secret으로 고정되어 있는 것은 정상입니다. 아래 두 개를 등록합니다.
| 이름 | 값 | 종류 |
|---|---|---|
| SUPABASE_SECRET_KEY | Supabase의 sb_secret_... | Secret · 필수 |
| APP_ENCRYPTION_KEY | 10번에서 생성한 32바이트 Base64 | Secret · 필수 |
| GEMINI_API_KEY | Gemini API Key | Secret · 선택 |
9-4. Production과 Preview는 어떻게 하나요?
처음에는 Production만 설정하는 것을 권장합니다. 실제 서비스가 정상 동작한 뒤 GitHub Pull Request나 Preview 배포에서도 서버 기능을 테스트해야 할 때 Preview에도 동일한 Secret을 추가하세요. 일반 Variable 6개는 wrangler.toml에 있으므로 코드와 함께 배포됩니다.
9-5. 저장 후 정상 작동 확인
missing: []이 보이고 Supabase 관련 설정이 정상으로 표시되는지 확인합니다. Gemini 키를 아직 관리자 화면에서 저장하지 않았다면 Gemini 관련 상태는 아직 미설정으로 표시될 수 있습니다.
10. APP_ENCRYPTION_KEY 1회 생성
이 키는 관리자 화면에서 Gemini API Key를 암호화/복호화하기 위한 마스터 키입니다. 32바이트를 Base64로 만든 값이어야 합니다.
가장 쉬운 방법 — Node.js가 설치되어 있을 때
출력된 문자열 전체를 Cloudflare의 APP_ENCRYPTION_KEY Secret에 저장합니다.
macOS / Linux 대안
11. 첫 관리자 계정 만들기
12. 관리자 화면에서 Gemini API Key·무료 모델 연결
Google AI Studio에서 API Key를 생성한 뒤 이 단계에서 저장합니다.
13. 최초 전체 동작 테스트
아래를 순서대로 하나씩 확인하세요.
- https://내주소/api/health 접속 — backend_ready: true 확인
- 회원가입/로그인 성공
- 관리자 페이지 Gemini 연결 테스트 성공
- 공개 영어 대화 YouTube URL 입력
- 최대 10/20/40개 옵션 중 하나로 분석 성공
- 분석 결과가 새로고침 후에도 최근 영상/보관함에 유지
- 문장별 ▶ 듣기 → 해당 구간으로 이동
- 반복 3회/5회/계속이 실제 문장 구간에서 동작
- 0.75× / 1.0× / 1.25× 속도 변경
- 일시정지 → 계속 듣기, 정지, 다시 듣기
- 문장 여러 개 선택 → 선택 문장 연속 듣기
- 영문/한국어 가리기
- 받아쓰기 정답/재시도
- 중요 ★, 헷갈림 ?, 외웠어요, 개인 메모 저장
- 보관함에서 중요/헷갈림/외움/복습 예정 필터
- 통계에서 전체/1일/7일/30일/1년 전환
- 본인 영상 공개 → 다른 일반 계정의 공개 학습에 표시
- 관리자에서 공개 영상 숨김 → 일반 커뮤니티에서 사라짐
- 관리자 전체 표현 통계 → 추천 추가 → 공식 추천에 노출
14. 일반 사용자 앱 사용법
가장 기본 사용
- 로그인
- 홈에서 YouTube URL 붙여넣기
- 학습량 10/20/40 선택
- 영어 교재 만들기 — 영어 자막을 먼저 자동으로 찾습니다.
- 완료 후 핵심 표현과 전체 영어 대본 확인
- 각 표현의 영상 원음을 듣고 표시/복습
50분 이상 긴 영상
대본·자막 직접 넣기를 열고 YouTube의 스크립트 표시 내용을 시간과 함께 복사해 붙여넣으세요. TXT, SRT, VTT 파일도 선택할 수 있습니다. 시간 정보가 없는 일반 텍스트는 표현 분석은 가능하지만 잘못된 구간 재생을 막기 위해 문장 듣기가 비활성화됩니다.
영어 듣기 학습 기능
- 전체 영어 대본 확인
- 타임스탬프 기반 문장별 영상 구간 재생
- 1·3·5회·계속 반복
- 느린 0.5/0.75배 듣기
- 여러 표현 체크 후 순차 재생
- 영문 숨기기 → 귀로 먼저 듣기
- 한국어 숨기기 → 의미 떠올리기
- 받아쓰기 → 실제 문장 복원 연습
장기 복습 기능
중요/헷갈림/외움 상태, 메모, 반복/듣기 횟수, 복습 예정일이 계정에 축적됩니다. 같은 영상 URL을 다시 넣으면 저장된 교재를 열어 불필요한 AI 호출을 줄입니다.
15. 관리자 센터 사용법
| 탭 | 할 수 있는 일 |
|---|---|
| 운영 설정 | 공개 학습 전체 ON/OFF, 사용자 공개 허용, 전체 통계 공개, 공식 제목 |
| Gemini API | 키 상태, 후보 연결 테스트, 암호화 저장, 교체, 삭제 |
| 전체 URL | 모든 사용자 업로드 영상 검색/페이지 조회, 공개 자료 숨김, 추천 영상 지정 |
| 전체 표현 | 모든 저장 영어 표현/번역/레벨/점수/사용자/영상 검색 |
| 전체 통계·추천 | 출현 영상 수, 사용자 수, AI 중요도, 듣기/반복/중요/헷갈림 통계, 공식 추천 표현 관리 |
16. 내 PC에서 수정하며 개발하기
Wrangler가 표시한 localhost 주소로 접속합니다.
17. 수정한 뒤 Cloudflare에 반영하는 방법
GitHub 연동이 끝나면 배포는 매우 단순합니다.
Cloudflare Dashboard의 Deployments에서 성공/실패 여부를 확인하세요.
18. 자주 생기는 문제 해결
화면에 “초기 설정 필요”
public/assets/js/config.js의 Supabase URL/Publishable Key를 확인합니다.
/api/health가 503 또는 backend_ready=false
Cloudflare SUPABASE_URL / SUPABASE_PUBLISHABLE_KEY / SUPABASE_SECRET_KEY를 확인합니다. Gemini 키는 관리자 저장 전이라면 gemini_configured:false일 수 있습니다.
관리자에서 Gemini 키 저장 실패
APP_ENCRYPTION_KEY가 정확한 32바이트 Base64인지 확인합니다.
Functions 404
Cloudflare output은 public, functions 폴더는 저장소 root여야 합니다. 이 프로젝트는 Git integration을 권장합니다.
YouTube 분석 실패 또는 시간초과
공개 영상인지 확인합니다. 50분 이상 영상은 홈에서 대본·자막 직접 넣기를 열고 YouTube 스크립트를 시간과 함께 붙여넣는 방법이 가장 안정적입니다. Gemini 사용 한도와 관리자 모델 설정도 확인하세요.
전체 대본은 있는데 듣기 버튼이 비활성화됨
붙여넣은 텍스트에 타임스탬프가 없기 때문입니다. 시간 표시를 포함해 다시 복사하거나 SRT/VTT 파일을 사용하세요.
같은 URL을 넣었는데 다시 분석되지 않음
의도한 동작입니다. 같은 계정의 동일 YouTube ID는 기존 교재를 엽니다. 대본을 바꿔 다시 만들려면 현재 버전에서는 기존 자료 정리 또는 후속 재분석 기능이 필요합니다.
19. 외부 공개 전 보안·운영 체크
- GitHub repository가 Private인지
- GitHub에 Gemini Key / sb_secret / 비밀번호가 없는지
- Supabase RLS가 켜져 있는지
- Cloudflare Secret에 SUPABASE_SECRET_KEY / APP_ENCRYPTION_KEY가 있는지
- 일반 계정으로 다른 사용자의 private video를 직접 읽을 수 없는지
- 일반 계정으로 analyses/expressions 원본을 직접 INSERT/UPDATE할 수 없는지
- 관리자 API가 일반 계정에 403을 반환하는지
- 공개 여부에 관계없이 본인 교재만 보이는지
- 일반 사용자가 다른 계정의 교재를 직접 조회할 수 없는지
- 서비스 이용약관·개인정보 처리방침·Google/YouTube 약관을 실제 서비스 형태에 맞게 검토했는지
20. 현재 버전에서 알고 있어야 할 한계와 다음 개발 후보
- 공개 자막 자동 확인은 YouTube 페이지 형식이나 접근 정책 변경에 따라 실패할 수 있으므로 대본 붙여넣기와 파일 입력을 함께 제공합니다.
- 영상 URL 분석의 지원 범위는 선택한 Gemini 모델과 API에 따라 다릅니다. 실패하면 시간 포함 대본을 직접 넣으세요.
- 자동 생성 자막의 단어와 타임스탬프에는 오류가 있을 수 있습니다.
- 현재 받아쓰기는 대소문자·일부 문장부호를 정규화한 정확 일치 방식입니다.
- 현재 같은 URL은 저장된 교재를 우선합니다. 재분석/버전 비교 UI는 후속 기능입니다.
- 대규모 공개 서비스가 되면 작업 큐, 진행상태 재조회, 더 정교한 rate limit과 감사 로그가 필요합니다.
21. 백업·복구 — 꼭 설정해 두세요
이 앱은 시간이 지날수록 영상·영어표현·중요/헷갈림 표시·메모·복습기록이 쌓이므로 DB 백업이 매우 중요합니다.
A. 소스코드 백업
- GitHub Private 저장소 자체가 코드의 1차 백업입니다.
- 중요 변경 전에는 Git commit을 남기고 버전 태그를 만드세요. 예: v1.0.0.
- .dev.vars와 실제 Secret은 Git에 올리지 않습니다.
B. Supabase 데이터 백업
Supabase Dashboard의 Database 백업/내보내기 기능은 요금제와 시점에 따라 메뉴가 달라질 수 있습니다. 운영 전 현재 사용 중인 Supabase 플랜의 백업 정책을 확인하세요. 최소한 중요한 시점에는 아래 테이블 데이터를 별도로 내보내 보관하는 것을 권장합니다.
C. 복구 순서
- GitHub에서 정상 동작했던 코드 버전으로 되돌립니다.
- 새 Supabase 프로젝트를 만드는 경우 supabase/schema.sql을 먼저 실행합니다.
- 백업한 사용자/영상/표현/학습 데이터를 복구합니다.
- Cloudflare Variables/Secrets를 다시 등록합니다.
- 기존 암호화 Gemini 키를 복구한다면 동일한 APP_ENCRYPTION_KEY를 사용해야 합니다.
- /api/health → 로그인 → 저장영상 → 반복듣기 → 관리자 Gemini 테스트 순으로 확인합니다.
D. 실수로 잘못 배포했을 때
Cloudflare Pages Deployments에서 이전 성공 배포 상태를 확인하고, GitHub에서는 정상 commit으로 revert한 뒤 다시 push하는 방법이 가장 이해하기 쉽습니다. DB 스키마를 수정한 배포라면 코드만 되돌리지 말고 DB migration 영향도 함께 확인해야 합니다.
22. 장기 운영·업데이트 방법
업데이트 전 6단계
- GitHub에서 새 branch를 만들거나 현재 정상 버전에 tag를 남깁니다.
- Supabase DB를 백업합니다.
- 코드를 수정합니다.
- npm run check를 실행해 실패 0건인지 확인합니다.
- 가능하면 Preview 배포에서 일반 사용자/관리자 계정 각각으로 테스트합니다.
- 정상일 때 main에 반영합니다.
Gemini 모델이 바뀌었을 때
Cloudflare의 GEMINI_MODEL 값을 바꾸기 전에 Google AI Developer 공식 모델 문서에서 해당 모델이 Interactions API, YouTube URL 입력, Structured Output을 지원하는지 확인합니다. 무료 티어/요금/데이터 정책도 함께 확인하세요.
DB 구조를 바꿀 때
이미 사용 중인 서비스에서는 최신 schema.sql 전체를 무조건 다시 실행하기보다 변경분만 migration SQL로 적용하는 편이 안전합니다. 컬럼 삭제·타입 변경·RLS 정책 변경 전에는 반드시 백업합니다.
사용자가 많아질 때 추가 권장 기능
- Cloudflare Turnstile로 봇/무단 자동요청 방지
- 사용자·IP·시간대별 더 정교한 rate limit
- 관리자 감사 로그
- 회원 탈퇴와 내 데이터 삭제/내보내기
- DB 정기 백업·복구 리허설
- Gemini 비용/무료한도 사용량 모니터링
- AI 분석 재시도 큐와 실패 로그
- 프롬프트/모델 버전별 재분석 및 결과 비교
v1.2.0 업데이트 — 기존 사용자부터 읽으세요
기존 v1.1.0 DB에는 supabase/migrations/20260909_v1_2_0.sql을 실행합니다. 신규 DB는 supabase/schema.sql 전체를 실행합니다. 기존 데이터/테이블을 삭제하는 migration은 아닙니다. RLS 접근 범위는 강화됩니다.
코드만 바꾸면 save_my_progress가 없어 메모·학습 상태 저장이 실패합니다.
새 편의 기능
- 홈: 마지막으로 연 교재 이어서 학습, 오늘 복습 바로가기.
- 학습: 검색 결과 전체 선택/해제, 선택 개수 표시, 외운 표현 진행률, 0.5배속.
- 반복/속도는 계정별·기기별 기억. 글자 크기는 기기별 기억.
- 메모·받아쓰기 임시 입력은 화면 갱신과 검색 필터 변경 중 보존됩니다. 메모 저장 버튼을 눌러야 계정에 저장되며 새로고침/로그아웃 전에는 꼭 저장하세요.
- 보관함은 50개씩 이전/다음 페이지를 제공합니다.
- 영상이 막히면 표현을 읽으면서 영상 다시 불러오기/YouTube 열기를 이용하세요.
GitHub에 수정 파일 반영하기
- ZIP에는 Git 이력인 .git 폴더가 없습니다. ZIP을 푼 폴더에서 바로 git status를 실행하면 저장소가 아니라고 나옵니다.
- 이미 clone한 저장소 폴더를 사용하거나 새 폴더에 clone합니다.
- 압축 내부 tubeenglish-study-main의 내용물을 저장소 최상위에 복사·병합합니다. 기존 config.js 및 직접 수정한 파일은 CHANGED_FILES.md를 보며 먼저 비교하세요. 비밀키 파일은 덮어쓰지 마세요.
- 변경 내용을 확인한 뒤 커밋하고 푸시합니다. 아래 명령은 clone된 저장소 내부에서 실행합니다.
git status node scripts/check.mjs node --test tests/*.test.mjs git diff --stat git add . git diff --cached --stat git commit -m "Improve study usability and security for v1.2.0" git push
HTTPS 인증에서 GitHub 계정 비밀번호를 입력하면 인증되지 않습니다. GitHub가 지원하는 토큰 또는 인증 도구를 사용하세요. 토큰을 채팅이나 소스코드에 붙이지 마세요. GitHub 인증 안내
배포 후 확인
- 일반 계정: 로그인, 기존 영상 열기, 메모 저장, 반복 듣기, 외웠어요, 보관함 검색.
- 설정: 이름, 세 단계 글자 크기, 비밀번호 복구 메일과 새 비밀번호 저장.
- 관리자: 사용자 목록, 시험 계정 역할 변경, Gemini 연결 테스트, 공개 학습 켜기/끄기.
- 서로 다른 두 계정으로 비공개 영상 접근이 차단되는지 확인.
- 휴대폰/태블릿/PC에서 메뉴, 긴 제목, 글자 확대, 표 스크롤과 실제 YouTube 재생 확인.
자동 검사는 실제 Supabase SQL 실행, 이메일 수신, Cloudflare 배포, 실제 Gemini/YouTube 호출, 실브라우저 화면 검증을 대신하지 않습니다. 자세한 결과는 TEST_REPORT.md에 기록했습니다.