본문 바로가기

FastAPI10

Uvicorn 서버 10회차 : 실전 트러블슈팅 & 점검 루틴(운영자 관점) Uvicorn 서버 10회차 : 실전 트러블슈팅 & 점검 루틴(운영자 관점)요약운영에서 장애가 무서운 이유는 기술이 어려워서가 아니라, 급한 상황에서 “어디부터 봐야 하는지”가 흔들리기 때문입니다. 이번 회차는 Uvicorn(FastAPI/ASGI) 서버 운영 중 자주 터지는 문제를 정리하고, 장애가 발생했을 때의 점검 순서를 루틴으로 고정하는 데 목적이 있습니다.핵심은 복잡한 원인을 한 번에 맞히는 것이 아니라, 증상을 빠르게 분류하고(네트워크/프로세스/프록시/리소스), 중간 확인 지점을 통해 범위를 좁혀가는 것입니다. 이를 위해 포트 충돌, import 실패, 프록시 502를 일부러 만들어보고, 같은 루틴으로 복구하는 실습을 진행합니다.목차0학습 목표1핵심 개념2장애 대응 루틴(어디부터 볼지)3디버깅.. 2025. 12. 29.

Uvicorn 서버 9회차 : 서버 운영 자동화 systemd로 “재부팅해도 자동 실행” (myapp.service 템플릿 완성) Uvicorn 9회차 : 서버 운영 자동화 systemd로 “재부팅해도 자동 실행” (myapp.service 템플릿 완성)한눈에 보는 요약개발 서버는 터미널에서 uvicorn을 실행하면 끝이지만, 운영 서버는 “재부팅/장애/배포” 상황에서도 자동으로 살아나야 합니다. 이때 가장 현실적이고 표준적인 해법이 systemd 서비스 등록입니다.이번 글에서는 systemd 서비스 파일의 핵심 구조(Unit/Service/Install), 프로세스가 죽었을 때 자동으로 되살리는 Restart 정책, 그리고 장애 분석에 필수인 journalctl 로그 확인까지 한 번에 정리합니다.실습은 myapp.service 작성 → daemon-reload → enable → start → status 확인 흐름으로 진행하며,.. 2025. 12. 28.

Uvicorn 서버 8회차 : 배포 준비 2 - 리버스 프록시(Nginx)와 포트 설계 Uvicorn 서버 8회차 : 배포 준비 2 - 리버스 프록시(Nginx)와 포트 설계한눈에 보는 요약실서비스에서는 보통 Uvicorn을 인터넷에 “직접” 노출하지 않고, Nginx 같은 리버스 프록시가 외부 요청(80/443)을 받아 내부 Uvicorn(예: 8000)으로 전달합니다. 이때 핵심은 “외부에 열어둘 포트는 최소(80/443), 내부 앱 포트는 외부에서 접근 불가(로컬 바인딩)”로 설계하는 것입니다.HTTPS(TLS)는 대개 Nginx에서 종료(termination)합니다. 즉, 브라우저와 Nginx 사이가 암호화(443)되고, Nginx가 복호화한 뒤 내부로 HTTP(8000)로 넘기는 방식이 일반적입니다. 이 구조가 설정·운영·인증서 관리 측면에서 가장 단순합니다.리버스 프록시를 거치면.. 2025. 12. 27.

Uvicorn 서버 7회차 : 배포 준비 1 - 환경변수, 설정 분리, 비밀키 관리 감각(.env / APP_ENV / PORT / LOG_LEVEL) Uvicorn 서버 7회차 : 배포 준비 1 - 환경변수, 설정 분리, 비밀키 관리 감각(.env / APP_ENV / PORT / LOG_LEVEL)한눈에 보는 요약배포 준비에서 가장 중요한 습관 중 하나는 키/비밀번호를 소스코드에 박지 않는 것입니다. 실수로 한 번 커밋된 비밀값은 “나중에 지우면 된다”가 아니라, Git 히스토리/배포 이미지/로그에 남아 확산될 수 있는 사고로 이어지기 때문입니다.이 문제를 가장 현실적으로 해결하는 방법이 환경변수(Environment Variable) 기반 설정입니다. 즉, 코드에는 “읽어오는 로직”만 두고, 값은 실행 환경(개발/운영/스테이징)에서 주입합니다. 개발 환경에서는 편의를 위해 .env 파일을 사용할 수 있지만(도구 사용은 선택), 운영에서는 가능한 한.. 2025. 12. 27.

Uvicorn 서버 6회차 : 운영 실행 방식 — Uvicorn 단독 vs Gunicorn+UvicornWorker, 왜 조합을 쓰는가? Uvicorn 서버 6회차 : 운영 실행 방식 — Uvicorn 단독 vs Gunicorn+UvicornWorker, 왜 조합을 쓰는가?한눈에 보는 요약Uvicorn은 FastAPI/Starlette 같은 ASGI 앱을 실행하는 서버입니다. 단독으로도 충분히 운영이 가능합니다.그럼에도 프로덕션에서 Gunicorn(프로세스 매니저) + UvicornWorker(ASGI 워커) 조합을 많이 쓰는 이유는 “요청 처리 성능”보다 운영 안정성(프로세스 관리, 재시작/롤링, 타임아웃, 로그, 워커 제어)을 더 체계적으로 가져가기 위함인 경우가 많습니다.핵심은 “Uvicorn이 나쁘다”가 아니라, 운영 환경에서 필요한 기능(감시/복구/정교한 워커 정책)을 누가 책임질지의 선택입니다. 컨테이너 오케스트레이션(Kuber.. 2025. 12. 27.

Uvicorn 서버 5회차 : 성능의 첫 관문 – 워커(worker)와 동시성(concurrency) Uvicorn 서버 5회차 : 성능의 첫 관문 – 워커(worker)와 동시성(concurrency)한눈에 보는 요약이번 회차의 목표는 “동시 요청 처리”가 실제로 무엇을 의미하는지 감을 잡고, Uvicorn의 --workers 옵션이 서버 성능에 어떤 영향을 주는지 체감하는 것입니다. 워커 수를 많이 주면 무조건 빠를 것 같지만, 실제로는 CPU 코어 수와 작업 종류(비동기 I/O vs CPU 작업)에 따라 적절한 지점이 달라집니다.글의 후반부에서는 ab 또는 hey 같은 간단한 부하 테스트 도구를 사용해 workers 1 vs 2 vs 4 상황을 비교해 보고, 마지막에는 “내 PC 기준 권장 워커 가이드(코어 수 기반)”를 메모 형태로 정리할 수 있도록 안내합니다.목차1. 학습 목표 정리2. 동시성(.. 2025. 12. 26.

Uvicorn 서버 4회차 : 로그를 다루는 법, 문제의 80%는 로그에서 끝난다 Uvicorn 서버 4회차 : 로그를 다루는 법, 문제의 80%는 로그에서 끝난다한눈에 보는 요약Uvicorn으로 서버를 띄우다 보면 “서버가 안 떠요”, “응답이 이상해요” 같은 문제가 자주 발생합니다. 이때 가장 먼저 확인해야 할 것은 코드가 아니라 로그입니다. 로그만 정확히 읽을 줄 알아도 문제의 70~80%는 현장에서 바로 해결됩니다.이 글에서는 Uvicorn의 --log-level 옵션과 접근 로그(Access log)의 의미를 정리하고, 자주 등장하는 에러 로그(ImportError, Port already in use, 404 Not Found)를 실제 메시지 예시와 함께 설명합니다. 초보자도 혼자 따라 할 수 있도록, 의도적으로 에러를 발생시켜 스택트레이스를 읽는 연습 방법까지 단계별로 안.. 2025. 12. 23.

Uvicorn 서버 3회차 : 개발 모드의 핵심, reload와 코드 변경 반영 Uvicorn 서버 3회차 : 개발 모드의 핵심, reload와 코드 변경 반영한눈에 보는 요약Uvicorn의 --reload 옵션은 개발 중에 코드가 바뀌었을 때 서버를 자동으로 다시 띄워 주는 기능입니다. 즉, “저장만 하면 서버 재시작까지 자동”이 되는 개발 모드라고 이해하시면 됩니다.하지만 이 기능은 내부에서 파일 변경을 계속 감시하고, 변경이 감지될 때마다 프로세스를 재시작하기 때문에 리소스 사용량이 늘고 예측하기 어려운 동작이 생길 수 있어 운영(프로덕션) 환경에는 권장되지 않습니다. 이번 글에서는 초보자도 이해할 수 있도록 기본 개념부터, 실제 라우트를 추가·수정하면서 자동 반영을 확인하는 실습, 그리고 “개발용 실행 커맨드” 한 줄을 확정해 보겠습니다.목차1. 오늘 학습 목표 정리2. 개발.. 2025. 12. 22.

Uvicorn 서버 2회차 : 첫 실행 마스터, uvicorn app:app 문법 완전 이해 Uvicorn 서버 2회차 : 첫 실행 마스터, uvicorn app:app 문법 완전 이해한눈에 보는 요약Uvicorn은 FastAPI 같은 ASGI 웹 프레임워크를 실행하는 초고속 파이썬 서버입니다. 이 글에서는 Uvicorn을 “처음” 실행하는 분도 이해할 수 있도록, uvicorn main:app에서 main과 app이 각각 무엇을 의미하는지, 그리고 --host, --port 옵션을 어떻게 써야 하는지 아주 쉽게 설명합니다.또한 프로젝트 구조를 어떻게 잡아야 import 경로 실수를 줄일 수 있는지도 함께 살펴보고, 마지막에는 바로 복사해 쓸 수 있는 실행 명령어 템플릿(내 PC용 / 외부 접속용) 2가지를 제공해 드립니다.목차1. 오늘의 학습 목표 정리2. app.py / main.py: 진입.. 2025. 12. 22.

Uvicorn 서버 1회차: Uvicorn이 무엇인지, “서버”와 “앱”의 역할 분리 이해하기 :contentReference[oaicite:0]{index=0}Uvicorn 서버 1회차 : Uvicorn이 무엇인지, “서버”와 “앱”의 역할 분리 이해하기한눈에 보는 요약Uvicorn은 “파이썬 웹서버”라기보다, ASGI 표준을 구현한 비동기 서버(런타임)입니다. 파이썬 코드 바로 앞에서 HTTP·WebSocket 요청을 받아 애플리케이션으로 전달하는 역할을 합니다.기존 Django·Flask가 사용하던 WSGI는 동기 방식이고, FastAPI·Starlette이 사용하는 ASGI는 비동기(Async)·이벤트 루프 기반입니다. 이 차이를 이해하면 왜 Uvicorn이 필요한지 자연스럽게 보입니다.웹 애플리케이션을 만들 때는 “요청을 받는 계층(서버)”과 “업무 로직을 처리하는 계층(앱)”을 분리해서.. 2025. 12. 22.

이전 1 다음

티스토리툴바