← 전체로 돌아가기
프로젝트 메모 network -home-son-prj-qr-generator

qr-generator deploy

FastAPI QR 서비스 배포 및 Nginx/systemd 세팅 정리

fastapinginxsystemddeployment

qr-generator (FastAPI) 파일 업로드하면 다운로드 링크 QR 생성해줌.

Nginx proxy setup https://dev.ericfromkorea.com/qr-generator

nginx config에서 /qr-generator/ → http://localhost:60025로 프록시. prefix 안 깎음. StaticFiles mount 경로 맞추려면 prefix 붙어있어야 함.

client_max_body_size 2048m - 업로드 용량 제한. QR_MAX_FILE_BYTES(2GiB)랑 맞춰둠.

systemd unit qr-generator.service

  • User=son
  • venv uvicorn 사용
  • workers=2
  • enabled (부팅시 자동 실행)

Storage & Path /mnt/4tb/temp/qr-generator-files/[id]/[original-name]

처음엔 /mnt/3tb 썼는데 /mnt/4tb unmount 상태라(fstab UUID 꼬임) 일단 퉁침. sdd1 UUID 597b7640-...로 수정해서 4tb 다시 붙임. 이후 경로 이동 완료.

*주의: sdd2 PARTLABEL "quarantine"는 배드섹터 때문에 일부러 비워둔 거임. 건드리지 말 것.

Config 변경법 코드 수정 말고 systemd unit 내 env vars 수정하면 끝. - QR_STORAGE_DIR: 저장 경로 - QR_BASE_URL: 베이스 URL - QR_ROOT_PATH: 루트 패스

여기서 배울 것

  1. Nginx proxy 시 prefix 안 깎아야 StaticFiles 경로 안 깨짐
  2. 용량 큰 파일 업로드 시 Nginx client_max_body_size 필수
  3. 환경 변수는 코드 말고 systemd unit에서 관리하는 게 편함
  4. fstab UUID 틀리면 마운트 안 됨. 확인 필수
원본 파일 보기 (.claude/projects/-home-son-prj-qr-generator/memory/qr-generator-deploy.md) 
---
name: qr-generator-deploy
description: "How the qr_generator file→QR service is deployed (port, storage, nginx, systemd)"
metadata: 
  node_type: memory
  type: project
  originSessionId: 9451119c-52e0-45a8-9fd9-8f7724e23508
---

`qr_generator` (FastAPI) lets users upload files and get a download-link QR per file.

- Served at https://dev.ericfromkorea.com/qr-generator (nginx 443 block proxies `/qr-generator/` → `http://localhost:60025`, prefix NOT stripped — needed because the StaticFiles mount only resolves under the full prefixed path).
- systemd unit: `qr-generator.service` (User=son, venv uvicorn, 2 workers, enabled).
- Uploads stored at `/mnt/4tb/temp/qr-generator-files/<id>/<original-name>` (+meta.json).

**Storage history:** initially `/mnt/3tb` because `/mnt/4tb` was unmounted (stale fstab UUID — fixed: sdd1 UUID `597b7640-…`). Once /mnt/4tb was remounted the user moved storage to `/mnt/4tb/temp/qr-generator-files`. Note: sdd2 PARTLABEL "quarantine" is an **intentional** bad-sector carve-out — leave it alone.

**How to apply:** to change storage/url/prefix, edit env vars in the systemd unit (QR_STORAGE_DIR / QR_BASE_URL / QR_ROOT_PATH), not the code. nginx `client_max_body_size 2048m` caps uploads (matches QR_MAX_FILE_BYTES default 2GiB).