나만의 영상 앱 만들기

moa-lite는 MOA의 화면과 플레이어를 그대로 옮겨, 서버 없이 Vercel 무료 요금제에서 돌아가게 만든 개인용 영상 앱입니다. 아래 세 단계를 따라 하면 내 앱이 만들어집니다.

영상과 확장 저장소는 들어 있지 않습니다. 처음에는 빈 앱이고, 쓸 Mangayomi JS 저장소는 직접 추가합니다. 무엇을 추가하고 보는지는 사용자의 책임입니다. 면책 조항

설정 코드와 비밀키 만들기

첫 관리자 계정을 만들 때 쓰는 설정 코드와, 로그인·저장된 API 키를 보호하는 앱 비밀키입니다. 이 브라우저 안에서만 만들어지고 어디에도 전송되지 않습니다.

값은 자동으로 저장되지 않으니 파일로 보관해 두세요. 설정 코드는 3단계에서 한 번 더 씁니다. 앱 비밀키는 업데이트할 때도 바꾸지 마세요. 바꾸면 저장한 TMDB·Gemini 키를 다시 넣어야 합니다.

Vercel에 배포하기

원클릭 배포는 처음 설치하기 간편하지만, 내 저장소가 Fork가 아닌 복사본으로 만들어져 이후 업데이트가 조금 번거롭습니다. 업데이트를 자주 받을 생각이면 아래 Fork로 배포하기도 좋습니다.

Vercel 배포 시작 ↗

먼저 1단계에서 두 값을 만들어 주세요.

새 창에서 할 일

  1. GitHub로 로그인하고, 저장소 이름을 정한 뒤 Create를 누릅니다.
  2. Upstash 저장 공간을 새로 만들고 요금제는 Free를 고릅니다. 계정과 시청 기록을 보관하는 곳입니다. 지역은 서울이 없으면 도쿄(Tokyo)를 고르세요. Free가 안 보이면 유료 요금제를 고르지 말고 새 창을 닫은 뒤, 아래 Free가 안 보일 때 방법으로 배포하세요.
  3. 환경변수를 아래처럼 채우고 Deploy를 누릅니다. 빌드는 몇 분 걸립니다.

계정 연결과 약관 동의는 직접 진행해야 합니다. 배포가 끝나면 앱 미리보기를 눌러 내 앱 주소(이름.vercel.app)를 엽니다.

관리자 계정 만들고 시작하기

  1. 내 앱 주소를 열면 관리자 계정 만들기 화면이 나옵니다. 바로 나오지 않으면 주소 뒤에 /__moa/setup을 붙여 엽니다.
  2. 1단계의 설정 코드와 원하는 아이디·비밀번호를 입력합니다. 다음부터는 아이디·비밀번호로 로그인합니다.
  3. 프로필을 만든 뒤 영상 소스에서 쓸 Mangayomi JS 저장소 주소를 추가하고 소스를 설치합니다. 기본으로 들어 있는 저장소는 없습니다.
  4. 작품 정보와 자막 번역을 쓰려면 설정에서 TMDB·Gemini API 키를 넣습니다. 둘 다 선택 사항입니다.

다른 사람은 계정과 초대에서 초대합니다. 휴대폰에서는 브라우저 메뉴의 홈 화면에 추가로 앱처럼 쓸 수 있습니다.

Free가 안 보일 때 · 업데이트를 쉽게: Fork로 배포하기

이미 Upstash 저장 공간을 만든 적 있는 계정에서는 2단계 새 창에 Free 없이 유료 요금제만 보일 수 있습니다. 이때는 Upstash 콘솔에서 Free 저장 공간을 직접 만들고, 저장소를 Fork해서 배포합니다. Fork는 GitHub의 Sync fork 버튼으로 업데이트할 수 있어 편합니다. 1단계의 두 값은 그대로 씁니다.

Upstash에 무료 저장 공간 만들기

Upstash 콘솔 열기 ↗
  1. GitHub로 로그인하고 Create Database를 누릅니다.
  2. 이름은 자유롭게 정하고, Primary Region은 앱 서버(서울)와 가까운 곳을 고릅니다. 서울이 없으면 도쿄(Tokyo)를 고르세요.
  3. 요금제는 Free를 고르고 만듭니다. Pay as you go는 사용한 만큼 요금이 나오니 고르지 마세요.
  4. 만든 데이터베이스 화면의 REST API 항목에서 주소와 토큰을 복사해 아래에 붙여 넣습니다.

주소는 https://로 시작하는 REST 주소입니다. redis://나 rediss://로 시작하는 주소는 쓰지 않습니다. 붙여 넣은 값은 C단계에서 한꺼번에 복사하는 데만 쓰입니다.

GitHub에서 Fork하기

moa-lite Fork하기 ↗
  1. Owner가 내 계정인지 확인하고, 저장소 이름은 그대로 두거나 원하는 이름으로 바꿉니다.
  2. Copy the main branch only는 체크된 채로 두고 Create fork를 누릅니다.

Vercel에서 가져와 배포하기

Vercel 프로젝트 만들기 ↗

  1. Import Git Repository 목록에서 B단계에서 만든 저장소의 Import를 누릅니다. 목록에 없으면 Adjust GitHub App Permissions에서 그 저장소 접근을 허용합니다.
  2. Application Preset(또는 Framework Preset)을 Other로 바꿉니다. 저장소 안의 여러 폴더를 감지해 Services가 자동으로 골라지고 “Multiple applications detected”, “needs a vercel.json” 안내가 보일 수 있는데, Other로 바꾸면 사라집니다. 아래 목록의 Import single project는 누르지 않습니다. Root Directory는 ./, 빌드 설정은 그대로 둡니다. 저장소의 vercel.json을 씁니다.
  3. Environment Variables를 펼치고 첫 Key 칸에 복사한 내용을 붙여 넣으면 다섯 줄이 한 번에 채워집니다. 안 되면 아래 표를 보고 하나씩 넣습니다.
  4. Deploy를 누르고, 끝나면 위 3단계대로 관리자 계정을 만듭니다.

잘 만들어졌나요?

GitHub에서 Star를 눌러 주시면 프로젝트를 이어 가는 데 큰 힘이 됩니다. 내 서버에서 Aniyomi 확장·내 영상 파일·FFmpeg 변환까지 쓰고 싶다면 Docker판 MOA를 둘러보세요.

★ moa-lite에 Star ★ MOA Docker 자체 호스팅판

막혔을 때

앱이 열리지 않거나 “hosting-not-configured” 오류가 나와요

필요한 환경변수가 빠졌거나 형식이 맞지 않는 상태입니다. 내 앱 주소 뒤에 /api/health를 붙여 열면 빠진 항목이 missing에 표시됩니다. "ok": true가 나오면 정상입니다.

값을 고친 뒤에는 Deployments → ⋯ → Redeploy를 눌러야 적용됩니다.

저장 공간(Upstash)을 나중에 연결하고 싶어요
  1. Vercel 대시보드에서 내 moa-lite 프로젝트를 엽니다.
  2. Storage → Create Database에서 Upstash → Redis를 고르고 Free 요금제로 만듭니다. 이미 만든 게 있다면 그것을 골라도 됩니다.
  3. Connect to Project에서 내 프로젝트를, 환경은 Production을 고릅니다.
  4. Deployments에서 가장 최근 배포의 ⋯ → Redeploy를 누릅니다.

이렇게 연결하면 Vercel이 KV_REST_API_URL·KV_REST_API_TOKEN을 넣어 주며, moa-lite는 이 이름도 읽습니다. Upstash 콘솔에서 직접 복사했다면 UPSTASH_REDIS_REST_URL·UPSTASH_REDIS_REST_TOKEN으로 넣습니다. 주소는 https://로 시작해야 합니다.

Upstash 요금제에 Free가 안 보여요

이미 Upstash 저장 공간을 만든 적 있는 계정에서는 Vercel 화면에 Pay as you go나 Fixed 같은 유료 요금제만 보일 수 있습니다. Pay as you go는 Free의 무료 사용량이 따로 남지 않고 처음부터 사용량만큼 요금이 붙으니 고르지 마세요.

대신 Fork로 배포하기를 따라 Upstash 콘솔에서 Free 저장 공간을 직접 만들어 연결하세요.

설정 코드를 잃어버렸어요

Vercel 프로젝트의 Settings → Environment Variables에서 SETUP_CODE 값을 확인할 수 있습니다. 새 코드로 바꾸려면 이 페이지에서 다시 만들어 값을 바꾸고 Redeploy합니다. 설정 코드는 관리자 계정이 하나도 없을 때만 쓰입니다.

새 버전으로 업데이트하고 싶어요

Fork로 배포했다면 GitHub에서 내 저장소의 main 브랜치를 선택하고 Sync fork → Update branch를 누릅니다. Vercel이 자동으로 새로 배포합니다.

Vercel 배포 시작으로 배포했다면 내 저장소가 Fork가 아닌 복사본이라 이 버튼이 없습니다. 배포 문서의 새 버전 받기 명령으로 가져옵니다.

Redeploy만으로 원본의 최신 코드를 가져오지는 않습니다. 선택한 기존 배포를 다시 빌드하는 기능입니다. APP_SECRET과 Upstash 저장 공간을 그대로 두면 계정과 기록이 유지됩니다.

Deployment Blocked와 커밋 작성자 권한 오류가 나오면 아래 항목을 확인하세요.

배포가 작성자 권한 때문에 막혔어요 (Deployment Blocked)

The deployment was blocked because the commit author did not have contributing access 오류에 해당합니다. Vercel Hobby의 비공개 저장소는 커밋 작성자가 프로젝트를 소유한 Hobby 계정과 연결되어 있어야 합니다. 원본 코드를 가져와도 작성자는 원본 개발자로 남을 수 있습니다. Vercel 공식 안내

  1. Vercel에 연결한 본인 GitHub 계정으로 로그인하고, 내 저장소에서 main → README.md → 연필(Edit)을 엽니다.
  2. 맨 아래에 <!-- deployment check -->를 추가합니다. 이미 있으면 주석 안에 날짜 등을 붙여 바꿉니다. 이 주석은 README 화면에 표시되지 않습니다.
  3. Commit changes에서 main에 직접 커밋합니다.
  4. Vercel Deployments에서 방금 만든 커밋의 새 배포가 Ready · Production인지 확인합니다. 이전에 막힌 배포의 Redeploy를 누르지 마세요.
어떤 소스는 목록이 안 뜨거나 재생이 안 돼요

Vercel에 배포해도 원본 사이트의 접근 제한·Cloudflare 인증·데이터센터 IP 차단은 풀리지 않고, 쓸 수 있는 소스도 저장소마다 다릅니다. 영상은 브라우저가 원본에서 직접 받으므로 브라우저가 바로 재생할 수 있는 HTTPS MP4·WebM·HLS만 재생됩니다. WebView가 필요한 소스나 FFmpeg 변환이 필요한 포맷은 지원하지 않습니다.

PC에서는 선택 사항인 연결 확장을 설치하면 내 브라우저로 원본에 접속합니다. 설치 방법은 배포 문서를 참고하세요.

정말 무료인가요?

Vercel Hobby와 Upstash Free의 사용량 한도 안에서는 무료입니다. 한도는 무제한이 아니며, Vercel Hobby는 개인·비상업 용도로만 쓸 수 있습니다. 관리자 계정의 설정 → 운영 → 진단 · 할당량에서 한도와 공식 사용량 화면 링크를 확인할 수 있습니다. 유료 요금제를 고르면 요금이 나올 수 있으니 직접 확인하세요.