nginx-portal/ARCHITECTURE.md

cyanburu.com 홈랩 아키텍처

전체 구조

flowchart TD
  User["외부 사용자\nhttps://cyanburu.com"]
  Router["MSI 라우터\n포트포워딩 80/443"]
  Ingress["Nginx Ingress Controller\nTLS 종료 · Let's Encrypt 인증서"]
  CoreDNS["CoreDNS\n내부 도메인 헤어핀 NAT 우회"]

  User --> Router --> Ingress --> CoreDNS

  subgraph K8s["Docker Desktop Kubernetes"]
    subgraph WebPortal["web-portal namespace"]
      FE["Frontend\nNginx · index.html"]
      BE["Backend\nFastAPI · main.py"]
      DB["PostgreSQL\nportaldb"]
      Notifier["notifier.py\nDiscord · Gmail 다중 채널"]
      Monitor["monitor.py\nPod 1분 · 인증서 24시간"]
      NotifyCh["notify_channels\nDB 테이블"]

      FE --> BE --> DB
      BE --> Notifier
      BE --> Monitor
      Notifier --> NotifyCh
    end

    subgraph GitOps["GitOps 파이프라인"]
      Gitea["Gitea\n코드 · Container Registry"]
      ArgoCD["ArgoCD\nGitOps 자동 배포"]
      Deploy["K8s Deployment\nbackend · frontend"]

      Gitea -->|git push| ArgoCD -->|sync| Deploy
      Gitea -->|image pull| Deploy
    end

    CoreDNS --> WebPortal
  end

  Notifier -->|Webhook| Discord["Discord"]
  Notifier -->|SMTP SSL| Gmail["Gmail"]

---

네임스페이스 구성

네임스페이스	구성 요소	역할
web-portal	Frontend, Backend, PostgreSQL	웹 포털 서비스
gitea	Gitea, PostgreSQL-HA, Valkey	코드 저장소 + Container Registry
argocd	ArgoCD Server	GitOps 자동 배포
ingress-nginx	Nginx Ingress Controller	외부 트래픽 라우팅 + TLS
cert-manager	cert-manager	Let's Encrypt 인증서 자동 발급

---

도메인 구성

도메인	서비스	인증서
cyanburu.com	Web Portal	Let's Encrypt
gitea.cyanburu.com	Gitea	Let's Encrypt
argo.cyanburu.com	ArgoCD	Let's Encrypt

---

배포 흐름 (GitOps)

sequenceDiagram
  participant Dev as 개발자
  participant Gitea as Gitea
  participant Registry as Container Registry
  participant ArgoCD as ArgoCD
  participant K8s as Kubernetes

  Dev->>Gitea: git push (코드 변경)
  Dev->>Registry: docker build & push
  Gitea-->>ArgoCD: Webhook 감지
  ArgoCD->>K8s: Sync (yaml 적용)
  K8s->>Registry: image pull
  K8s-->>Dev: Pod Running

---

알림 채널 발송 규칙

채널 유형	Pod 이상/복구	계정 잠금/임시PW	인증서 만료
Discord+Gmail	Discord + Gmail	Discord만	Gmail만
Discord 전용	Discord만	Discord만	발송 안 함
Gmail 전용	Gmail만	발송 안 함	Gmail만

---

이미지 레지스트리 주의사항

Docker Desktop 환경에서는 kubelet이 Docker 데몬을 통해 이미지를 Pull하므로 K8s 내부 DNS(gitea-http.gitea.svc.cluster.local)를 사용할 수 없음.

반드시 외부 IP 사용:

192.168.10.101:30000/qorgh529/portal-backend:latest
192.168.10.101:30000/qorgh529/portal-frontend:latest