와니의 Data Engineering

ngrok 이란?

ngrok은 로컬 개발 환경에서 실행 중인 서버를 외부에서 접근 가능하도록 해주는 무료 터널링 서비스

보통 로컬에서 띄운 서버를 외부에서 접속할 수 있도록 연결해 간단한 테스트를 해볼 때 많이 이용한다.

ngrok 계정 생성 및 로그인

서버 또는 로컬에 ngrok을 설치하기 전에 ngrok에서 계정이 생성되어 있어야 한다.

아래 홈페이지에서 계정을 생성한다.

https://ngrok.com/

ngrok 설치

Linux 환경에서 설치

# ngrok 다운로드
wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz

# 압축 해제
tar -xzf ngrok-v3-stable-linux-amd64.tgz

# 실행 파일을 시스템 경로로 이동
sudo mv ngrok /usr/local/bin/

# 실행 권한 부여
sudo chmod +x /usr/local/bin/ngrok

# 설치 확인
ngrok version

mac os 환경에서 설치

# homebrew 설치
brew install ngrok

ngrok 토큰 추가

ngrok 홈페이지에서 토큰을 발급

https://dashboard.ngrok.com/get-started/your-authtoken

서버 또는 로컬에 토큰 추가

# ngrok 발급 토큰 추가
ngrok config add-authtoken [my-authtoken]

# 결과 확인
Authtoken saved to configuration file: /root/.config/ngrok/ngrok.yml

ngrok 실행

# HTTP 터널 생성 (포트 3000)
ngrok http 3000

# HTTPS 터널 생성
ngrok http 3000 --scheme https

# 특정 도메인 사용 (유료 계정 필요)
ngrok http 3000 --domain=your-domain.ngrok.io

# 백그라운드에서 실행
nohup ngrok http 3000 > ngrok.log 2>&1 &

# 프로세스 확인
ps aux | grep ngrok

# 로그 확인
tail -f ngrok.log

ngrok은 http 외에 tcp도 연결이 가능해서 mqtt 통신을 이용할 때 유용하게 사용할 수 있다.

`ngrok tcp 1883` 같은 명령어로 간단히 이용할 수 있다.

백그라운드에서 실행한 경우, ngrok 웹페이지 메뉴에서 domain과 port 정보를 확인할 수 있다.

https://dashboard.ngrok.com/endpoints

Cloudflare Tunnel 개념 설명

기본 개념

역방향 프록시 역할을 하는 보안 터널
로컬 서버(내 PC, 사내 서버 등)를 공인 IP 없이도 인터넷에 안전하게 노출시켜주는 서비스
cloudflared라는 경량 클라이언트를 설치해서 사용

주요 특징

방화벽 개방 불필요
서버의 80/443 포트를 외부에 직접 열지 않아도 됨
cloudflared가 Cloudflare 네트워크 쪽으로 먼저 연결을 여는 방식

보안 강화

Cloudflare 네트워크가 앞단에서 공격 필터링
DDoS 방어, WAF 규칙 적용 가능
설치와 사용이 간단
로컬에서 cloudflared tunnel create → Cloudflare 대시보드에서 라우팅 설정 → 도메인 연결

활용 예시

개발 환경 서버를 임시로 외부 팀원에게 공유
사내 내부망 웹 서비스에 외부 접근 허용 (Zero Trust 기반)
IoT 기기 원격 제어

Cloundflare 설치 방법

맥OS / 맥북에서 설치할 때

brew install cloudflared

CentOS / RHEL 계열 Linux 서버일 때

wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-x86_64.rpm
sudo rpm -ivh cloudflared-linux-x86_64.rpm

Debian/Ubuntu 계열 Linux 서버일 때

wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

cloudflare tunnel 

처음 시작할 때

cloudflared tunnel login

cloudflared를 설치한 직후에는 cert 정보가 없다.

위 명령어로 브라우저를 오픈하고 cloudflare 사이트에서 인증하면 cert 정보가 생성된다.

cloudflare tunnel 생성

cloudflared tunnel create my-tunnel

이 명령으로 터널 ID와 자격 증명 파일이 생성된다.

여기서 알려주는 token은 아래 위치에 자동으로 저장된다.

mac os일 때는 /home/사용자/.cloudflared/xxxx.json

linux 일 때는 /root/.cloudflared/xxxx.json

config.yml 작성 (위와 동일 경로에 생성)

tunnel: mqtt-tunnel
credentials-file: /home/사용자/.cloudflared/xxxx.json

ingress:
  - hostname: your.domain.com
    service: tcp://localhost:1883
  - service: http_status:404

터널 실행

cloudflared tunnel run mqtt-tunnel

Systemctl에 등록 후 이용하기

서비스 파일 생성

# systemd 서비스 파일 생성
sudo tee /etc/systemd/system/cloudflared-tunnel.service > /dev/null << EOF
[Unit]
Description=Cloudflare Tunnel Service
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/root
ExecStart=/usr/local/bin/cloudflared tunnel run pet-api-tunnel
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

서비스 활성화 및 시작

# systemd 재로드
sudo systemctl daemon-reload

# 서비스 활성화 (부팅 시 자동 시작)
sudo systemctl enable cloudflared-tunnel

# 서비스 시작
sudo systemctl start cloudflared-tunnel

# 서비스 상태 확인
sudo systemctl status cloudflared-tunnel

Cloudflare DNS 도 이용하고 싶다면

Cloudflare 대시보드 → DNS → your.domain.com

유형: CNAME

값: uuid.cfargotunnel.com (터널 생성 시 발급된 값)

프록시(구름 아이콘)는 활성화(주황) 상태여야 함

• HTTP/1.0
  • 1990년대 초 등장, 한 번의 연결에 한 개의 요청·응답만 처리(단기 커넥션).
  • 요청할 때마다 매번 새로운 TCP 연결 생성(비효율).
  • 헤더와 메서드, 상태코드 등 기본적인 웹 통신 구조 정의.

• HTTP/1.1
  • 1997년 도입, 기존의 단점을 보완.
  • Persistent Connection(지속적 커넥션): 연결을 한 번 유지해 여러 요청·응답을 처리, 성능 향상.
  • Pipelining: 클라이언트가 응답을 기다리지 않고 여러 요청을 순차적으로 보냄.
  • 캐싱, 가상 호스팅(Host 헤더), 청크 전송 등 다양한 기능 추가.
  • 문제점: 순차적 처리(이전 응답이 지연되면 뒤에 있는 요청들도 차단, “HOL blocking” 현상), 헤더 중복.

• HTTP/2
  • 2015년 채택, 성능 향상에 집중.
  • 멀티플렉싱: 한 커넥션에 여러 요청·응답을 동시에 독립적 스트림으로 전달.
  • 이진 프레임 전송: 텍스트 대신 바이너리 프레임 사용(오버헤드 및 파싱 시간 감소).
  • 헤더 압축(HPACK): 중복 헤더를 효율적으로 압축해서 대역폭 절약.
  • 서버 푸시: 클라이언트 요청이 없어도 서버가 미리 리소스를 전송 가능.
  • 문제점: TCP 기반이라 패킷 손실 시 전체 스트림이 지연되는 HOL 블로킹 완벽 해결은 어려움.

• HTTP/3
  • 최신 버전, UDP 기반의 QUIC 프로토콜을 사용.
  • TCP 사용(X) → 연결 설정 속도 빠름(1-RTT/0-RTT, 핸드셰이크 최소화).
  • 멀티플렉싱 기술을 전송(네트워크) 레벨에서 지원, 패킷 손실 시 다른 스트림에 영향 없음, HOL 블로킹 완전 해결.
  • 헤더 압축(QPACK) 및 TLS 1.3 통합 보안 지원.
  • 모바일‧무선 환경에서 성능 크게 향상, 네트워크 변경에도 연결 유지성 뛰어남.
  • Netflix, Shopify 등에서 도입 후 실제 페이지 로딩, 영상 시작 등 성능 10~30% 향상 사례.

Grafana는 여러가지 시계열 데이터, metric 등을 시각화해서 모니터링 할 수 있게 해주는 분석 도구이다.

오픈 소스 플랫폼이어서 널리 이용되고 있다.

Grafana

# 설치
sudo dnf install grafana

# 서버 부팅시 Grafana 서비스가 자동으로 시작되도록 설정
sudo systemctl enable grafana-server.service

# 서비스 시작
sudo systemctl start grafana-server.service

Loki

# 설치 (최신 버전인지 확인)
sudo wget https://github.com/grafana/loki/releases/download/v3.5.2/loki-linux-amd64.zip

# 압축해제
unzip loki-linux-amd64.zip

# 수정 권한변경
chmod +x loki-linux-amd64

# 실행파일 디렉토리로 이동
sudo mv loki-linux-amd64 /usr/local/bin/loki

실행 바이너리 파일은 보통 아래 두 디렉토리 아래에 두게 된다.

/opt 는 복합적인 패키지를 수동으로 관리해야 할 때 주로 이용하고

/usr/local/bin 은 보통 단일 바이너리 파일일 때 이용한다. 시스템 PATH에 자동 등록되어 편리하다.

loki는 단독 파일이어서 local에 두었다.

Loki 설정파일

아래 url에서 내용을 다운받을 수 있다.

https://raw.githubusercontent.com/grafana/loki/main/cmd/loki/loki-local-config.yaml

`/etc/loki/loki-local.yaml` 파일로 내용을 저장했다.

Systemd 로 관리하기

# systemd에 loki.service 등록
vi /etc/systemd/system/loki.service

# 아래 내용 입력 후 저장
[Unit]
Description=Loki Log Aggregation System
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/loki -config.file=/etc/loki/loki-config.yaml
Restart=on-failure
User=root
WorkingDirectory=/etc/loki
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

실행파일 위치, 설정파일 위치 잘 확인 후 내용 저장

서비스 등록

# 유닛 파일 리로드
sudo systemctl daemon-reexec
sudo systemctl daemon-reload

# 서비스 등록
sudo systemctl enable loki

# 서비스 시작
sudo systemctl start loki

Prometheus

ㅇㅇ

도메인이 없는 ip 주소를 특정 도메인으로 접속하고 싶을 때 쓰는 방법이다.

Windows, Linux, Mac 모두 hosts 라는 파일로 관리한다.

hosts 파일의 위치는 /etc/hosts 이다.

1. hosts 파일 오픈
   아래 명령어를 입력해서 hosts 파일을 편집기로 연다.

sudo vi /etc/hosts

2. IP, Domain 입력 후 저장
   편집기로 파일을 열고 i 키를 누르면 insert, 즉 수정모드로 들어갈 수 있다.
   잘 안눌린다면 한글로 전환되어 있을 수도 있으니 확인해본다.

<IP 주소> <도메인명> 형식으로 원하는 ip, 도메인명을 입력한다.

다 입력했으면 esc 키를 눌러 :wq 입력 후 엔터를 누르면 파일이 저장된다.

3. 네트워크 적용
   보통 hosts 파일은 입력 후 바로 적용되지만, 만약 적용되지 않으면 DNS 캐시를 정리해본다.

# "network-manager" 사용하는 경우
sudo service network-manager restart

# "hostnamed" 사용하는 경우
sudo systemctl restart systemd-hostnamed

# "dnsmasq" 유틸리티 사용하는 경우
sudo pkill -HUP dnsmasq

# 웹, WAS서버와 같은 시스템의 경우 재시작(restart)이 필요할 수 있음

클라우드 서버와 github 레포를 연동해 코드를 관리하려면 ssh 방식을 이용해야 한다.

예~전에는 email로 된 id, pw 방식을 이용할 수 있었지만 몇년 전부터 무조건 ssh 방식을 이용하도록 방침이 변경되었다.

이번 글에서는 클라우드에서 이용중인 리눅스 서버에 ssh 키를 생성하고 github 계정에 등록해 연동하는 방법을 기록해본다.

ssh key 생성

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

-t 는 type 옵션이다. 암호화 알고리즘 타입을 의미한다.

-t 옵션을 주지 않으면 디폴트로 rsa가 사용된다. 가장 많이 사용되는 알고리즘이다.

ed25519 알고리즘도 자주 사용된다.

-b 는 bit, 즉 키 길이 옵션이다. 일반적으로 2024bit / 4096bit 이 많이 사용된다.

이렇게 키를 생성하면 The key fingerprint is: SHA256 어쩌구가 나온다.

키를 생성할 때 쓰는 알고리즘이 RSA였다면, 공개키 지문을 생성하는 데 이용되는 해시방식은 SHA256이 많이 쓰인다.

공개키 지문은 키를 식별하는 데 쓰이는 고유 식별값이다.

[root@my-server .ssh]# ls
id_rsa  id_rsa.pub

생성된 키는 `~/.ssh` 디렉토리에서 확인할 수 있다.

`id_rsa` 키는 개인키, `id_rsa.pub` 키는 공개키이다.

깃허브에 ssh key 등록

깃허브에 로그인하고 [설정]> [SSH and GPG Keys] 메뉴로 들어간다.

https://github.com/settings/keys

이 링크를 클릭해도 된다.(로그인 상태여야 함)

Title에는 내가 알아볼 수 있도록 키에 대한 이름을 붙여주면 된다.

Key type은 Authentication Key로 설정

Key에는 위에서 발급한 키 중에서 공개키 (~.pub) 를 복사해서 붙여넣으면 된다.

간편하게 키값을 복사하는 방법은 `cat id_rsa.pub` 명령어로 내용을 프린트한 뒤에 드래그 해서 복사해오면 된다.

혹시나 헷갈릴까봐 친절하게 ssh-rsa / ecdsa-sha2-nistp256 / ssh-ed25519 등으로 시작되는 값을 넣으면 된다고 입력란에서 다시 한 번 알려주고 있다. 공개키는 ssh-rsa처럼 사용된 알고리즘의 이름이 처음에 나온다.

이렇게! 마지막에 자신의 이메일 주소까지 잘 들어갔는지 확인한다.

깃 레포지토리 클론

깃 레포지토리를 가져오고자 하는 디렉토리로 이동 또는 생성한다.

git init

원하는 디렉토리에서 git을 사용하기 위해 초기화하는 작업이다.

git은 보통 기본적으로 설치되어 있으므로 따로 설치할 필요 없이, 바로 명령어를 사용할 수 있다.

깃허브 레포지토리에서 [<> Code] 버튼을 누르면 해당 레포의 SSH 주소값이 나온다.

이 값을 복사해서 클라우드 서버에 클론해온다.

git clone git@github.com:<그룹명>/<레포명>.git

git clone 뒤에 복사한 값을 그대로 복붙하면 된다.

The authenticity of host 'github.com (20.200.245.247)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

이런 문구가 뜨면, yes를 입력해준다.

github가 아직 서버의 known hosts에 등록되어있지 않아서 나오는 문구이다.

yes를 입력하면 자동으로 등록해주고, 클론이 끝난다.

이제 완료!

새로 클라우드 서버를 생성하고 기본 프로그램들을 설치하면서 기록해나가고 있습니다.

참고로 제가 사용중인 os는 rocky입니다.(Red Hat 계열)

Debian 계열을 사용하시는 분들은 dnf 대신 apt-get 명령어를 이용해주세요.

✅  linux 계열별로 호환되는 패키지 매니저

dnf Red Hat 계열 패키지 매니저 (Rocky, CentOS, Fedora 등)

apt-get Debian 계열 패키지 매니저 (Ubuntu, Debian 등)

Nginx

✅ Nginx란?

정적 웹 콘텐츠 제공, 리버스 프록시, 로드 밸런싱, SSL 종단, API 게이트웨이 등 다양한 역할을 수행할 수 있는 고성능 웹 서버

✅ 주로 사용되는 곳

- 웹 사이트 배포 (HTML, React, Vue 앱 정적 호스팅)

- Next.js, Express, FastAPI 앱 앞단에서 프록시 역할

- 인증서 자동갱신 (Certbot + Nginx)

- 도커/쿠버네티스에서 서비스 게이트웨이 역할

# 설치
sudo dnf install nginx

# 설정파일 - 내용은 아래 첨부
sudo vi /etc/nginx/nginx.conf

# 설정 테스트
sudo nginx -t

# 서버 시작때 자동으로 시작하도록 설정
sudo systemctl enable nginx

# 서비스 시작
sudo systemctl start nginx

Certbot

✅ Certbot이란?

무료로 TLS 인증서를 발급해주는 비영리기관 Let's encrypt 를 이용해서 TLS 인증서를 발급, 갱신할 수 있게 도와주는 오픈 소스 프로그램

# EPEL 저장소 활성화
sudo dnf install epel-release

# Certbot 설치
sudo dnf install certbot

# python3-certbot-nginx 설치
sudo dnf install python3-certbot-nginx

pytohn3-certbot-nginx은 certbot과 nginx를 묶어주는 역할을 한다.

nginx 웹서버에 https를 활성화하기 위해 certbot을 사용하기 위한 패키지이다.

# 인증서 발급
certbot --nginx -d your.domain.com

--nginx 옵션을 넣으면 certbot이 nginx에 설정을 추가하여 https 인증서를 적용하도록 한다.

-d {domain} 옵션은 인증서를 발급받을 도메인 이름을 지정하는 옵션이다.

이전 글에서 네이버 클라우드 플랫폼에서 서버를 생성해보았다.

이번에는 생성한 서버의 비밀번호를 설정하는 방법을 기록해본다.

관리자 비밀번호 확인

자동으로 부여된 접속 비밀번호는 서버를 생성할 때 지정한 인증키 파일로 확인할 수 있다.

최초 비밀번호 확인

서버 접속

생성된 서버에 접근하는 방법은 2가지가 있다.

1. NCP 서버 접속 콘솔

네이버 클라우드 플랫폼 콘솔에서도 [서버 접속 콘솔] 메뉴를 제공하고 있다.

급할 때는 유용하지만, ui의 글씨가 작고 약간의 글자입력 딜레이가 있어서 답답하다.

게다가 5분 사용 시간제한이 있어서 길게 작업하기 힘들다.

2. 원격 연결 터미널

나는 맥의 Shell 에서 제공하는 원격 연결 기능을 이용해 접속한다.

Shell 외에도 서버 원격접속 기능을 제공하는 방법이 많이 있으니 편한대로 고르면 된다.

ACG를 통해 해당 서버에 외부접속이 가능하도록 설정했는지 반드시 확인해야 한다!

외부 접속을 위한 SSH 포트는 기본적으로 22번 포트를 사용한다는 점 참고

비밀번호 변경

최초 비밀번호를 이용해 root 계정에 접속한 뒤 비밀번호를 변경할 수 있다.

sudo passwd root

이제 원하는 비밀번호 세팅 완료

네이버 클라우드 플랫폼 NCP에서 서버를 생성하는 방법이다.

어려운 건 아니지만, 주니어가 처음 생성할 때는 은근 헤맬 수 있는데(내 얘기) 블로그 후기글은 잘 없더라고.

이번에 기존 최소사양 서버를 확장하라는 팀장님의 지시를 듣고 새로 서버를 생성하면서, 누군가에게는 도움이 될까 싶어서 기록해본다.

서버 생성

OS 타입은 리눅스와 윈도우가 있다.

서버 이미지 스펙 오른쪽에 다음> 버튼을 누른다.

내가 선택한 건

OS타입 Rocky (리눅스 종류다)

하이퍼바이저 All (XEN, KVM)

서버 이미지 rocky-9.4-base

서버 설정

#VPC

VPC (Virtual Private Cloud)는 클라우드 환경에서 나(or 우리팀)만이 쓸 수 있는 공간이다.

이미 서버를 운영중인 팀의 vpc가 있어서 선택했고, 콘솔에서 생성해두지 않았다면 이 단계에서 생성이 가능하다.

#Subnet

VPC를 좀더 잘 나누어 쓰기 위해 네트워크를 쪼갠 개념이다.

외부에서 접속 가능한 공인 IP를 부여받기 위해서는 반드시 public subnet을 선택해야 한다.

역시 나는 미리 생성되어 있던 팀의 서브넷을 이용했다.

VPC, Subnet이 헷갈린다면 아래 비유를 참고해보자.

🏠 비유로 쉽게 이해하기

- VPC: 큰 아파트 단지 (네트워크 전체)

- 서브넷: 단지 안의 건물 (서브 네트워크)

- 서버들 (EC2, DB 등): 각 건물 안의 세입자

#서버스펙

원래는 가장 최소 사양인 CPU2EA, Memory 4GB를 이용하고 있었다.

이번에 개발팀장님 허락으로 CPU16EA, Memory 32GB로 파격적인(?) 업그레이드를 했다.

#요금제 선택

월 요금제로 선택했습니다.

월 60만원짜리 서버라니 팀장님 감사합니다..!

#서버 개수

내부 admin 용도라 트래픽이 많이 필요하지는 않아서 1대로 설정

#서버 이름

캡쳐 이미지상으로는 예시로 my-server라고 지었다.

#NetworkInterface

미리 생성해둔 subnet이 있다면 적용할 수 있다.

#공인IP

#물리 배치 그룹

사용 버튼이 비활성화 되어있어 자동으로 미사용 선택

#반납 보호

설정한다고 따로 비용이 들지 않으므로 설정 선택

스토리지 설정

#크기

최소 사양으로 서버를 생성하면 10GB는 무료로 제공된다.

나는 기존에 이 사양을 선택해서 아주 아끼고 쪼개면서 서버를 사용중이었다.

이번에는 팀장님이 무려 1000기가!! 기존의 100배에 해당하는 용량을 부여받았다 크..(팀장님 쵝옹)

#스토리지 타입

CB1, CB2를 선택할 수 있게 되어있다.

두 타입의 차이점은 따로 설명된 곳을 찾지 못 했다.

아래 가이드에서도 CB1/2 라는 식으로 두 개를 묶어서 설명하는 내용만 찾을 수 있었다.

https://guide.ncloud-docs.com/docs/server-storage-vpc#fb1-cb1-%EC%84%B1%EB%8A%A5-%EC%83%81%EC%84%B8-%EC%A0%95%EB%B3%B4

인증키 설정

인증키는 서버의 로그인 등 다양한 곳에 쓰인다.

현재 팀에서 공동으로 사용하고 있는 인증키가 있어서 그걸 사용했고,

기존에 만들어둔 키가 없으면 이 단계에서 새로운 인증키를 생성할 수 있다.

네트워크 접근 설정

#ACG

ACG = Access Control Group 이건 네이버 클라우드에서만 쓰이는 용어다.

AWS에서는 Security Group이라고 부르는 개념이고, 한 마디로 방화벽 설정을 묶음으로 관리하는 개념이다.

인바운드/아웃바운드, 즉 들어오고 나가는 IP 또는 port를 관리할 수 있다.

네이버클라우드 콘솔에서 [신규 Network Interface] 메뉴를 통해 생성된 ACG만 설정 가능하다.

나는 기존 어드민용 서버 전용으로 만든 ACG를 동일하게 적용했다. 최대 3개까지 선택 가능하다고 한다.

최종 확인

마지막으로 선택한 설정사항을 한 화면에서 확인해볼 수 있다.

필요한 사양이 맞는지 선택한 후, [서버 생성] 버튼을 누르면 이제 서버가 생성된다.

서버 생성에는 시간이 좀 걸린다.

안내 팝업에는 15~30분 이상 걸릴 수 있다고 되어있으나, 체감상 5분이면 세팅이 완료되었다.

FastAPI는 python 백엔드 개발에 이용되는 프레임워크이다. 가볍고 빠르게 만들 수 있으면서도 높은 성능, 비동기지원, 자동문서 생성 등 장점이 많아 널리 이용되고 있는 프레임워크이다.

나 역시 간단한 api 서버를 만들기 위해 파이썬과 FastAPI 조합을 이용해보기로 결정하고, 초반 세팅 작업을 기록해본다.

🎯 단계별 순서

✅ 1️⃣ FastAPI 프로젝트 기본 설정

FastAPI 프로젝트를 위한 가상환경을 만들고, 필요한 패키지를 설치

1. 가상환경 생성 및 활성화

터미널에서 아래 명령어 실행:

mkdir fastapi-project && cd fastapi-project # 프로젝트 폴더 생성 및 이동
python -m venv venv # 가상환경 생성
source venv/bin/activate # (Windows는 `venv\Scripts\activate`)

2. FastAPI 및 Uvicorn 설치

pip install fastapi uvicorn

• fastapi: FastAPI 프레임워크
• uvicorn: FastAPI 서버 실행을 위한 ASGI 서버(비동기 서버 게이트웨이 인터페이스)

✅ 2️⃣ FastAPI 서버 실행

📂 main.py 파일을 만들고 테스트코드 작성

from fastapi import FastAPI

app = FastAPI() # 앱 객체 생성

@app.get("/")   # 라우터
def read_root():
	return {"message": "Hello, FastAPI!"}

3. FastAPI 서버 실행

uvicorn main:app --reload

• --reload: 코드 변경 시 자동으로 서버 재시작

4. API 테스트

브라우저에서 아래 url에 접속하여 JSON 응답이 정상적으로 나오는지 확인
👉 http://127.0.0.1:8000/

# 변수 파라미터를 url로 받을 수 있는 엔드포인트 추가
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
	return {"item_id": item_id, "query": q}

✅ 4️⃣ FastAPI 자동 문서 기능

FastAPI는 자동으로 API 문서를 생성 가능

1. Swagger UI (API 테스트 가능)

👉http://127.0.0.1:8000/docs

2. ReDoc 문서

👉http://127.0.0.1:8000/redoc

✅ 5️⃣ POST 요청 (데이터 받기)

📂 main.py

from pydantic import BaseModel

class Item(BaseModel):
	name: str
    price: float
    is_offer: bool = False
    
@app.post("/items/")
def create_item(item: Item):
	return {"message": f"Item '{item.name}' with price {item.price} created!"}

• pydantic: 파이썬의 type annotation을 이용해 데이터 검증과 설정관리를 해주는 라이브러리

✅ 6️⃣ 데이터베이스 연동 (SQLite + SQLAlchemy)

FastAPI에서 SQLAlchemy를 사용하여 데이터베이스와 연동해 보자.

1. 필요한 패키지 설치

pip install sqlalchemy databases sqlite

2. 데이터베이스 설정 (database.py)

📂 database.py

from sqlalchemy import create_engine, Column, Integer, String, Float, Boolean
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "sqlite:///./test.db"

engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()

def get_db():
	db = SessionLocal()
    try:
    	yield db
    finally:
    	db.close()

3. 데이터 모델 (models.py)

📂 models.py

from database import Base
from sqlalchemy import Column, Integer, String, Float, Boolean

class Item(Base):
	__tablename__ = "items"
    
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    price = Column(Float)
    is_offer = Column(Boolean, default=False)

4. 데이터베이스 테이블 생성

📂 main.py

from database import engine
import models

models.Base.metadata.create_all(bind=engine)

✅ 7️⃣ CRUD API 만들기

1. GET 모든 데이터 가져오기

from fastapi import Depends
from sqlalchemy.orm import Session
from database import get_db import models

@app.get("/items/")
def read_items(db: Session = Depends(get_db)):
	return db.query(models.Item).all()

2. POST 데이터 추가

@app.post("/items/")
def create_item(item: Item, db: Session = Depends(get_db)):
	db_item = models.Item(name=item.name, price=item.price, is_offer=item.is_offer)
	db.add(db_item)
	db.commit()
	db.refresh(db_item)
	return db_item

✅ 8️⃣ FastAPI + Docker 배포

1. Dockerfile 생성

📂 Dockerfile

FROM python:3.10
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir fastapi uvicorn sqlalchemy databases sqlite
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

2. Docker 이미지 빌드

docker build -t fastapi-app .

3. Docker 컨테이너 실행

docker run -p 8000:8000 fastapi-app

API 확인

👉 http://127.0.0.1:8000/docs