Streamlit Cloud 배포 가이드¶

Python 앱을 무료로 웹에 배포하는 가장 쉬운 방법

Streamlit이란?¶

비유: Vercel이 "HTML/JS 사이트를 올리는 인쇄소"라면, Streamlit은 "Python 앱을 올리는 인쇄소"

Python 코드만으로 웹 앱을 만들 수 있는 프레임워크
HTML/CSS/JS를 몰라도 됨 - st.button(), st.dataframe() 같은 Python 명령으로 UI 구성
데이터 분석, 차트, 입력 폼, 파일 다운로드 등 지원

왜 Streamlit을 선택했나¶

방법	장점	단점	적합한 경우
Vercel (Astro/Next.js)	빠름, SEO 좋음, 정적 사이트	Python 백엔드 어려움	홈페이지, 프롬프트 사이트
Streamlit Cloud	Python 그대로, 무료, 배포 쉬움	느림, 디자인 제한적	데이터 분석 도구, Python 앱
Cloudflare Pages	빠름, CDN, R2 이미지	Python 불가	이미지 많은 사이트

SNS 분석기를 Streamlit으로 만든 이유: - yt-dlp (유튜브 자막 추출) = Python 라이브러리 - httpx (인스타 API) = Python 라이브러리 - wordcloud (워드클라우드) = Python 라이브러리 - 전부 Python이라 Streamlit이 자연스러운 선택

로컬 개발 방법¶

1. 설치¶

pip install streamlit

2. 앱 파일 만들기 (app.py)¶

import streamlit as st

st.title("내 앱")
name = st.text_input("이름을 입력하세요")
if st.button("확인"):
    st.write(f"안녕하세요, {name}님!")

3. 실행¶

streamlit run app.py

- 브라우저에서 http://localhost:8501 자동 열림 - 코드 수정하면 브라우저가 자동 새로고침

배포 방법 (Streamlit Community Cloud)¶

사전 준비¶

GitHub repo에 코드 push
requirements.txt 파일 필수 (Python 패키지 목록)
한글 폰트 필요하면 fonts/ 폴더에 포함

배포 단계¶

https://share.streamlit.io 접속 → GitHub 로그인
"Create app" → "Deploy a public app from GitHub"
Repository / Branch / Main file path 입력
"Deploy" 클릭 → 2~3분 대기

비공개 repo 사용 시¶

Workspace settings → Linked accounts → Private access → "Connect here" 클릭
GitHub에서 Streamlit 앱 권한 허용
그래도 안 되면 repo를 public으로 변경 (코드에 비밀 정보 없으면 OK)

App URL 변경¶

기본: xxx-randomstring.streamlit.app
대시보드 → 앱 오른쪽 ⋮ → Settings → App URL에서 변경
예: coss-analyzer.streamlit.app

주요 차이점: Vercel vs Streamlit Cloud¶

항목	Vercel	Streamlit Cloud
언어	JS/TS (Node.js)	Python
배포 트리거	git push 자동	git push 자동
커스텀 도메인	O	X (xxx.streamlit.app 고정)
속도	빠름 (CDN)	느림 (서버 렌더링)
비용	무료 (취미)	무료 (Community)
GitHub 연결	Vercel 대시보드	Streamlit 대시보드
이메일 함정	커밋 이메일 = Vercel 이메일 필수	없음

실전 삽질 기록¶

인스타 API 서버 차단 (HTTP 429)¶

증상: 로컬에서 되는 인스타 API가 Streamlit Cloud에서 429 에러
원인: 클라우드 서버 IP가 인스타에서 rate limit에 걸림
교훈: 비공식 API는 서버 배포 시 차단될 수 있다. 로컬에서는 항상 됨.

한글 폰트¶

증상: 워드클라우드에서 한글이 깨짐
원인: Linux 서버에 malgun.ttf 없음

해결: fonts/malgun.ttf를 프로젝트에 포함, 코드에서 경로 자동 감지

from pathlib import Path
_local = Path("fonts/malgun.ttf")
FONT_PATH = str(_local) if _local.exists() else "C:/Windows/Fonts/malgun.ttf"

엑셀 다운로드 시 화면 초기화¶

증상: 다운로드 버튼 누르면 Streamlit이 전체 페이지를 rerun해서 결과 사라짐

해결: st.session_state에 분석 결과 저장, 결과 표시는 session_state에서 읽기

# 분석 시 저장
st.session_state["result"] = data
# 화면에 표시
if "result" in st.session_state:
    st.dataframe(st.session_state["result"])

Streamlit 주요 컴포넌트 (자주 쓰는 것)¶

컴포넌트	용도	예시
`st.text_input()`	텍스트 입력	URL 입력
`st.button()`	버튼	"분석하기"
`st.dataframe()`	표	분석 결과 테이블
`st.metric()`	수치 카드	팔로워, 참여율
`st.tabs()`	탭	인스타/유튜브 탭
`st.spinner()`	로딩 표시	"분석 중..."
`st.download_button()`	파일 다운로드	엑셀 다운로드
`st.session_state`	상태 유지	결과 초기화 방지
`st.progress()`	진행 바	"3/5 완료"
`st.expander()`	접기/펼치기	자막 전문 보기

빌드 케이스: COSS SNS 분석기¶

프로젝트: D:\Sites\coss-analyzer\
GitHub: hangglwriter/coss-analyzer
URL: https://coss-analyzer.streamlit.app
구성: 인스타 참여율 + 유튜브 채널 분석 + 유튜브 내용 분석 (3탭)
기술: httpx (인스타 API) + yt-dlp (유튜브) + wordcloud + pandas
용도: COSS 서포터즈 강의 도구 (학생들이 직접 사용)