72hours security check

YMCA-hackathon-2026

코디세이 AI 해커톤 2026 | 이노베이션아카데미 (2026.10.30 ~ 11.02)

개발 시작하기

git clone https://github.com/maebsy/YMCA-hackathon-2026.git
cd YMCA-hackathon-2026
bash scripts/setup-dev.sh
cp .env.example .env

구조

DB는 .env의 DATABASE_URL로 정합니다. Docker 없이 실행할 때 비워 두면 SQLite, Compose에서는 로컬 PostgreSQL을 씁니다. Supabase 연결 문자열을 넣으면 팀 공용 DB를 사용합니다. SQLite는 Item 예제와 검사 응답 테이블을 자동 생성합니다. PostgreSQL의 검사 결과 저장에는 저장 migration 적용이 필요하며, 서비스 스키마·인증·비동기 큐는 DB 설계와 활성화 절차를 따릅니다.

Docker로 실행 (권장)

Docker Desktop 또는 Docker Engine + Compose v2.24.4 이상이면 Node.js·Python·PostgreSQL을 호스트에 따로 설치하지 않아도 됩니다.

cp .env.example .env              # 처음 한 번
docker compose up --build --watch

• 프론트 http://localhost:3000, API http://localhost:8000, 로컬 PostgreSQL이 같이 뜹니다. 프론트 주소의 http://localhost:3000/api/health 에서 "db":"postgresql"이 나오면 프록시와 DB 연결까지 성공입니다.
• 브라우저는 같은 주소의 /api/*로 요청하고 Next.js 서버가 http://backend:8000으로 전달합니다. 컨테이너 안의 localhost는 다른 서비스가 아닙니다.
• frontend/src, frontend/public, backend/app 저장 내용은 --watch로 반영됩니다. 프론트 package/lock/Next/TypeScript 설정과 백엔드 requirements 변경은 해당 이미지를 다시 빌드합니다. OS별 node_modules를 공유하지 않습니다.
• 끄기는 Ctrl+C 또는 docker compose down. DB 데이터는 남고, 지우려면 docker compose down --volumes
• .env의 DATABASE_URL이 비어 있으면 로컬 DB를, Supabase 주소가 있으면 그 DB를 씁니다
• DB만 Docker로 쓰고 서버는 직접 띄워도 됩니다: docker compose up db 후 .env에 DATABASE_URL=postgresql://app:app@localhost:5432/app. 이 값은 컨테이너 안에서 통하지 않으니 전체를 Docker로 띄울 때는 다시 비우세요
• 프론트 컨테이너에는 루트 .env를 전달하지 않습니다. DB 비밀번호·GPU 키는 백엔드에만 전달하며, 모든 호스트 포트는 127.0.0.1에만 엽니다.

빌드한 프론트로 통합 시연

docker compose -f compose.yaml -f compose.production.yaml up --build --detach --wait

이 모드는 Next.js standalone 빌드와 정적 파일만 담은 비root 컨테이너를 사용하며, 백엔드 reload와 양쪽 watch를 끕니다. 종료도 같은 -f 두 개를 사용합니다. 개발 모드로 돌아갈 때는 기본 docker compose up --build --watch를 실행합니다. Next.js Docker 배포 방식

프록시 주소는 배포 빌드 시 확정됩니다. Compose의 frontend.build.args.BACKEND_ORIGIN을 바꾸면 이미지를 다시 빌드해야 합니다. Docker 없이 실행하면 기존 127.0.0.1:8000 기본값과 npm run build/start가 유지되며, 필요하면 서버 환경 변수 BACKEND_ORIGIN을 설정합니다. 브라우저 공개 변수(NEXT_PUBLIC_*)는 사용하지 않습니다.

이 구성은 기존 일반 서버의 systemd/Caddy/GPU 터널을 자동 전환하지 않습니다. 공개 시연은 기존 인증 프록시를 거쳐 연결해야 합니다. 현재 프론트의 예제 데이터·OAuth·스캔 접수 같은 기능 통합은 별도 작업이며 Compose 기동이 전체 서비스 연동 완료를 뜻하지는 않습니다. Supabase를 지정해도 기본 Compose의 개발 DB 컨테이너는 함께 뜨지만 API는 지정한 Supabase에 연결합니다. 비동기 모드는 스키마와 별도 worker 준비 후 활성화합니다.

문제가 생기면:

백엔드 실행 (Docker 없이)

cd backend
python -m venv .venv
source .venv/Scripts/activate      # macOS·Linux: source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

• http://localhost:8000/api/health 에서 {"status":"ok","db":"sqlite"}가 나오면 성공 (Supabase면 "postgresql")
• http://localhost:8000/docs 에서 API를 직접 눌러 볼 수 있습니다
• Item과 /api/items는 연결 확인용 예시입니다. 실제 테이블을 만들면 지우세요.

LLM 서버 연결 (vLLM, 8001 포트)

GPU 서버의 vLLM은 8001 포트로 띄웁니다. 백엔드(8000)와 겹치지 않게 서버와 내 PC 모두 같은 번호를 씁니다.

# GPU 서버: 처음 한 번 setup-gpu.sh, 그다음 serve.sh. 127.0.0.1에만 열고 API 키를 요구합니다
bash scripts/llm/setup-gpu.sh
tmux new -d -s vllm 'bash scripts/llm/serve.sh'

# 내 PC: 서버의 8001을 내 PC의 8001로 가져옵니다 (SSH 터널 허용 여부는 운영진 확인 필요)
ssh -N -L 8001:127.0.0.1:8001 <GPU 서버>

• 백엔드를 직접 띄우면 .env의 LLM_BASE_URL=http://localhost:8001/v1을 그대로 씁니다
• Docker로 띄우면 compose가 http://host.docker.internal:8001/v1(내 PC의 8001)로 바꿔 연결합니다
• vLLM은 OpenAI 호환 API라, 개발 중에는 OpenAI·Ollama 주소로 바꿔도 코드는 그대로입니다
• 모델(Qwen3.8-27B), Red–Blue 흐름, API, 테스트 방법: docs/llm.md

리포트·신고서

• 비전공자용 점검 리포트(완료 리포트 포함)와 KISA 침해사고 신고(24시간)·개인정보 유출 신고(72시간) 초안: docs/reports.md
• POST /api/reports/plain · /assess · /incident-24h · /privacy-72h, ?format=json|markdown|html

규칙

• 이슈·브랜치·커밋·PR 규칙: CONTRIBUTING.md
• 외부 자원 활용 내역: docs/external-resources.md