FAQ (자주 묻는 질문)¶

현재 저장소의 실제 코드 기준으로 정리한 FAQ입니다. 동작은 배포 모드에 따라 다를 수 있으니 먼저 backend, Supabase, Firebase 중 어떤 모드로 실행 중인지 확인하세요.

실행 및 배포¶

Q: Docker 없이 실행할 수 있나요?¶

A: 가능합니다. 기본 개발 흐름은 다음과 같습니다.

# Backend
cd backend
cargo run

# Frontend
cd frontend
bun install
bun run dev

기본 환경 변수와 로컬 실행 방법은 로컬 개발 환경, 환경 변수를 참고하세요.

Q: SQLite만 지원하나요?¶

A: 기본값은 SQLite이지만 PostgreSQL도 지원합니다.

기본 DATABASE_URL: sqlite:data/sqlite.db?mode=rwc
PostgreSQL 예시: postgresql://postgres:postgres@localhost:5432/open_codelabs
서버 시작 시 마이그레이션은 자동 실행됩니다.
MySQL은 현재 런타임에서 지원하지 않습니다.

Q: 어떤 배포 모드를 선택하는 게 좋나요?¶

A: 현재 구현 기준으로는 다음처럼 보는 게 맞습니다.

모드	권장 상황	현재 지원 범위
`backend`	자체 호스팅, 전체 기능 사용	가장 완전한 기능 세트. 백업, 코드랩 복제/가져오기/내보내기, 워크스페이스, 감사 로그, CLI 브라우저 인증, 링크 제출, 업데이트 확인 포함
`Supabase`	서버리스 + 비교적 넓은 기능 범위	Google 로그인, 수료증, 자료, 파일 제출, 퀴즈는 지원. 다만 백업, 워크스페이스, 코드랩 복제/가져오기/내보내기, 링크 제출, 업데이트 확인은 제한
`Firebase`	가벼운 서버리스 데모/기본 운영	가장 제한이 큽니다. 수료증, 자료 관리, 제출물 관리, 퀴즈 관리, 백업, 워크스페이스, 코드랩 복제/가져오기/내보내기는 현재 미지원

Q: 리버스 프록시 뒤에서 운영할 때 주의할 점이 있나요?¶

A: 있습니다.

프록시의 x-forwarded-* 헤더를 신뢰하려면 TRUST_PROXY=true를 설정해야 합니다.
쿠키를 SameSite=None으로 쓰려면 COOKIE_SECURE=true가 함께 필요합니다. 그렇지 않으면 서버가 Lax로 낮춰 처리합니다.

공개 배포 예시는 공개 배포 가이드를 참고하세요.

Q: API 호출이 403으로 막히는 경우가 있습니다¶

A: 세션 쿠키를 사용하는 상태 변경 요청은 CSRF 헤더가 필요합니다.

브라우저 UI는 자동 처리합니다.
curl이나 별도 스크립트로 POST, PUT, DELETE를 호출할 때는 쿠키와 x-csrf-token을 함께 보내야 합니다.

참가자 및 세션 운영¶

Q: 비공개 Codelab도 참가자 목록에 보이나요?¶

A: 보이지 않습니다. 일반 참가자는 is_public=true인 코드랩만 목록에서 볼 수 있고, 비공개 코드랩은 관리자만 등록/접근시킬 수 있습니다.

Q: 참가자 이름이 중복되면 어떻게 되나요?¶

A: 같은 코드랩 안에서는 닉네임 중복이 막혀 있습니다. 다만 예외가 하나 있습니다.

같은 닉네임과 같은 참가 코드로 다시 들어오면 기존 참가자로 재입장합니다.
다른 사람이 같은 닉네임을 쓰면 등록이 거부됩니다.
입력 길이 제한은 이름 80자, 코드 64자입니다.

Q: Google 로그인으로 관리자나 참가자를 등록할 수 있나요?¶

A: 서버리스 모드에서만 가능합니다.

Supabase / Firebase: Google 로그인 지원
backend: 관리자 ID/PW 로그인, 참가자 닉네임+코드 방식

Q: 참가 진행 상황은 어디에 저장되나요?¶

A: 기본적으로 브라우저 localStorage에 저장됩니다. 같은 브라우저로 다시 접속하면 이어서 진행할 수 있습니다.

추가로 backend 모드에서는 WebSocket 이벤트를 통해 서버의 current_step도 함께 갱신됩니다.

Q: 채팅 메시지나 DM은 새로고침하면 사라지나요?¶

A: backend 모드 기준으로는 사라지지 않습니다.

공개 채팅과 DM 모두 DB에 저장됩니다.
페이지를 다시 열면 채팅 기록을 다시 불러옵니다.
DM도 sender_id, target_id를 포함해 저장됩니다.

Q: 수료증은 언제 발급되나요?¶

A: 현재 UI 기준으로는 코드랩 설정에 따라 다음 조건을 확인합니다.

require_quiz: 퀴즈 통과 필요
require_feedback: 피드백 제출 필요
require_submission: 제출물 최소 1개 필요

backend 모드에서는 완료 API가 제출물 필수 여부를 한 번 더 검사합니다. 발급된 수료증은 /certificate/{attendee_id}에서 열 수 있고, 검증 URL은 /verify/{attendee_id} 형식입니다. Firebase 모드에서는 수료증 기능이 현재 지원되지 않습니다.

Q: 제출물 업로드 제한이 있나요?¶

A: 있습니다.

파일 제출: 파일당 5MB
총 제출 용량: 참가자당 10MB
이미지 제출: 서버에서 WebP로 변환될 수 있음
HEIC / HEIF: 현재 지원하지 않음

링크 제출은 백엔드 API에는 있지만, 현재 프런트엔드에서는 backend 모드에서만 지원됩니다. Supabase와 Firebase 모드에서는 링크 제출이 막혀 있습니다.

Q: 일반 이미지 업로드가 실패합니다¶

A: 일반 채팅/본문용 이미지 업로드는 관리자와 참가자 모두 가능하지만, 제한이 있습니다.

최대 크기: 5MB
서버 저장 형식: WebP
저장 경로: /uploads/{uuid}.webp

Q: 자료(Materials) 파일 업로드 제한은 어떻게 되나요?¶

A: 자료 업로드는 관리자만 할 수 있고 최대 10MB입니다.

저장 경로: /uploads/materials/...
링크 자료는 http 또는 https URL만 허용됩니다.
자료 삭제는 현재 DB 레코드만 삭제합니다. 실제 파일은 자동 삭제되지 않습니다.

Q: 화면 공유가 되나요?¶

A: 됩니다. 관리자와 참가자 모두 화면 공유 기능이 있습니다.

WebRTC 기반
품질 프리셋: auto, low, medium, high
브라우저가 getDisplayMedia를 지원해야 함

네트워크 상태와 품질 제한 여부도 UI에 표시됩니다.

Q: 본문에 인라인 댓글을 달 수 있나요?¶

A: 가능합니다. 참가자는 가이드/스텝 본문에서 텍스트를 선택해 스레드를 만들고, 답글과 삭제도 할 수 있습니다.

관리자가 본문을 크게 수정한 뒤 저장하면 기존 인라인 댓글이 stale 될 수 있어서, 저장 전에 영향 범위를 경고하는 UI가 표시됩니다.

관리자, AI, 워크스페이스¶

Q: Gemini API 키 저장이 실패합니다¶

A: 현재 관리자 설정 API는 암호화된 키만 받습니다. 평문 키는 거부됩니다.

실무적으로는 다음 둘 중 하나가 필요합니다.

로그인 과정에서 저장된 관리자 비밀번호
VITE_ADMIN_ENCRYPTION_PASSWORD 환경 변수

또한 백엔드에서 Gemini API 키를 사용할 때 우선순위는 다음과 같습니다.

관리자 설정에 저장된 키
요청 payload로 전달된 키
GEMINI_API_KEY 환경 변수

Q: 참가자도 Gemini를 사용할 수 있나요?¶

A: 가능합니다. 참가자 화면에는 AskGemini 패널이 있으며, 브라우저 로컬에 저장한 API 키를 사용해 스트리밍 응답을 받을 수 있습니다.

Q: 코드랩 워크스페이스 기능은 어떤 모드에서 쓸 수 있나요?¶

A: 현재는 backend 모드 전용입니다.

워크스페이스 생성/삭제
branch 또는 folder 구조 선택
초기 파일 업로드
step별 start/end 브랜치 또는 폴더 생성
파일 읽기/수정
tar.gz 다운로드

서버리스 모드에서는 현재 지원되지 않습니다.

Q: 백업에는 무엇이 포함되나요?¶

A: backend 모드의 관리자 백업은 상당히 넓게 담습니다.

코드랩, 스텝, 참가자
채팅, 도움 요청, 피드백
자료, 퀴즈, 퀴즈 제출, 제출물
AI conversations / threads / messages
inline comments
audit logs
업로드 파일
워크스페이스 메타데이터와 워크스페이스 파일

관리자 전용 export, inspect, restore API가 있으며, 복원 업로드 제한은 기본 200MB입니다. 서버리스 모드에서는 현재 백업/복원이 지원되지 않습니다.

Q: 감사 로그는 어디까지 남나요?¶

A: 주요 동작은 best-effort로 감사 로그에 기록됩니다. 기록 실패가 원래 요청까지 막지는 않습니다.

조회는 관리자 전용
기본 조회 수: 100건
최대 조회 수: 1000건
action, codelab_id 필터 지원

Q: CLI 로그인 방식이 어떻게 바뀌었나요?¶

A: 현재 oc auth login은 브라우저 승인 기반 로그인 흐름을 사용합니다.

인증 요청 TTL: 10분
poll interval: 2초
상태 흐름: pending -> approved -> consumed

자세한 사용법은 CLI 가이드를 참고하세요.

기타¶

Q: 429 Too Many Requests가 발생합니다¶

A: 기본 rate limit이 걸린 것일 수 있습니다. 현재 기본값은 다음과 같습니다.

일반 요청: 분당 120회
로그인: 5분당 20회
AI 요청: 분당 30회
업로드: 분당 20회

Q: 다국어를 지원하나요?¶

A: 네. 현재 프런트엔드에는 21개 언어 번역 파일이 포함되어 있습니다. 최소한 ko, en, ja, zh, zh-TW, es, fr, de, ru 등을 포함한 다국어 구조가 이미 들어 있습니다.

Q: 상업적으로 사용할 수 있나요?¶

A: 가능합니다. 현재 프로젝트 라이선스는 MIT가 아니라 Apache License 2.0입니다. 자세한 내용은 라이선스를 참고하세요.

추가 도움¶

위에서 답을 찾지 못했다면 다음 문서를 함께 보세요.