프로젝트 계획서

프로젝트 계획서

1. 프로젝트 주제

주 주제: Kubernetes 기반 3-Tier 고가용성 시스템 구축
세부 주제: 개발자를 위한 올인원 협업 플랫폼 (Gition - Git + Notion)

구분	내용
코드 관리	GitHub 연동, 브랜치/커밋 관리
문서화	Notion 스타일 블록 에디터
CI/CD	GitHub Actions + GitLab CI 하이브리드
인증	GitHub OAuth 2.0

2. 요구사항 정의

2.1. 시스템 요구사항

On-Premise VMware 환경에서 Kubernetes 클러스터 구축
Control Plane(k8s-m): Master 노드
Worker Node(k8s-n1~n3): 3개 워커 노드
인프라 서버: NFS, MySQL, GitLab
네트워크: VMware NAT 172.100.100.0/24 대역

2.2. 기능 요구사항

인증 및 계정 관리

기능	구현 방식	상태
GitHub OAuth	OAuth 2.0	O
세션 관리	Token 기반	O
로그인/로그아웃	localStorage 저장	O

저장소 관리

기능	설명	상태
저장소 목록	GitHub API 연동	O
저장소 복제	서버로 Clone	O
브랜치 전환	로컬/리모트 브랜치	O
파일 탐색	디렉토리 네비게이션	O

에디터

기능	설명	상태
블록 에디터	Notion 스타일	O
마크다운 렌더링	MarkdownRenderer	-
코드 블록	구문 강조	-
`.gition` 저장소	브랜치별 로컬 페이지	O

Git 연동

기능	설명	상태
커밋 히스토리	브랜치별 조회	O
파일 뷰어	내용 조회/편집	O
코드 검색	저장소 내 검색	O
Issues/PR	GitHub 연동 표시	O

CI/CD 파이프라인

플랫폼	기능	상태
GitHub Actions	ESLint / PyLint 검사	O
	Unit Test 실행	O
	Gitleaks / Trivy 보안 스캔	O
	GitLab Mirror 동기화	O
GitLab CI	Docker 이미지 빌드	O
	Container Registry 푸시	O
	수동 배포 트리거	O

Kubernetes 인프라

구성 요소	설명	상태
Ingress Controller	Host/Path 기반 라우팅	O
MetalLB	LoadBalancer IP 할당	O
NFS Provisioner	동적 PVC 생성	O
FastAPI Deployment	3 replicas + 공유 볼륨	O
Frontend Deployment	2 replicas (React + Nginx)	O
MySQL Master	VM Docker (외부 Endpoints)	O
MySQL Slave StatefulSet	K8s 내 2 replicas (GTID 복제)	O
imagePullSecrets	GitLab Registry 인증	O

2.3. 비기능 요구사항

항목	요구사항	설명
응답 시간	API 응답 < 500ms	사용자 경험 보장
가용성	99% 이상	연간 다운타임 87시간 이내
확장성	K8s 기반 스케일 아웃	HPA/VPA 자동 스케일링
보안	OAuth 2.0 + Token 기반	GitHub 인증 연동
유지보수성	모듈화 아키텍처	컴포넌트 단위 배포 가능

3. 프로젝트 목표

3.1. 목표 개요

고가용성 시스템: MySQL Master-Slave Replication + Frontend/Backend 다중 복제
자동화 CI/CD: GitHub Actions + GitLab CI 하이브리드 파이프라인
무중단 배포: Rolling Update + MySQL Read/Write 분리

3.2. 기술 스택

계층	기술
Frontend	React + Vite + TypeScript
Backend	Python FastAPI + GitPython
Database	MySQL 8.0 (Master-Slave Replication)
Auth	GitHub OAuth 2.0
Infra	Kubernetes + MetalLB + NFS
CI/CD	GitHub Actions + GitLab CI

3.3. 마일스톤

버전	목표	진행률
v0.1	Core Platform	85%
v0.2	Visualization & Features	10%
v0.3	Advanced Integrations	0%

4. 시스템 아키텍처

4.1. 전체 구성

┌─────────────────────────────────────────────────────────────┐
│                         Client                               │
│                    (React + Vite)                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│             Ingress Controller (nginx-ingress)               │
│                    Host: gition.local                        │
│                    /api/* → api-svc:3001                     │
│                    /*     → frontend-svc:80                  │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────────┐
│        FastAPI          │     │         React SPA           │
│   (Deployment: 3 pods)  │     │   (Deployment: replicas)    │
│                         │     │                             │
│  • GitHub OAuth         │     │  • 블록 에디터              │
│  • Git Operations       │     │  • 파일 브라우저            │
│  • Page CRUD            │     │  • 커밋 히스토리            │
│  • /repos NFS Mount     │     │                             │
└─────────────────────────┘     └─────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│                     MySQL (Master-Slave)                     │
├──────────────────────────┬──────────────────────────────────┤
│   Master (VM Docker)     │      Slave (K8s StatefulSet)     │
│   172.100.100.11         │      mysql-slave-0, mysql-slave-1│
│   Write 전용             │      Read 전용 (GTID 복제)       │
└──────────────────────────┴──────────────────────────────────┘

4.2. 네트워크 설계

호스트	IP	용도
GitLab	172.100.100.8	GitLab CE + Registry
Bastion	172.100.100.9	SSH 게이트웨이
NFS	172.100.100.10	공유 스토리지
MySQL Master	172.100.100.11	외부 MySQL (Write)
k8s-m	172.100.100.12	Control Plane
k8s-n1	172.100.100.13	Worker Node 1
k8s-n2	172.100.100.14	Worker Node 2
k8s-n3	172.100.100.15	Worker Node 3
MetalLB VIP	172.100.100.20	외부 트래픽 진입점

4.3. CI/CD 파이프라인

GitHub → GitHub Actions (ESLint/PyLint → Test → Gitleaks/Trivy → Mirror)
                                                                    │
                                                                    ▼
GitLab CI (Docker Build → Container Registry → Kubernetes Deploy)

5. 데이터베이스 설계

5.1. ERD

┌────────────────────┐
│       Users        │
├────────────────────┤
│ PK  id             │
│     github_id      │
│     login          │
│     email          │
│     avatar_url     │
│     access_token   │
└─────────┬──────────┘
          │ 1:N
          ▼
┌────────────────────┐         ┌────────────────────┐
│    Repositories    │         │      Sessions      │
├────────────────────┤         ├────────────────────┤
│ PK  id             │         │ PK  id             │
│ FK  user_id        │         │ FK  user_id        │
│     github_id      │         │     token_hash     │
│     name           │         │     expires_at     │
│     clone_url      │         └────────────────────┘
│     default_branch │
└─────────┬──────────┘
          │ 1:N
          ▼
┌────────────────────┐
│    BranchPages     │
├────────────────────┤
│ PK  id             │
│ FK  repo_id        │
│ FK  user_id        │
│     branch_name    │
│     title          │
│     content (JSON) │
└────────────────────┘

5.2. MySQL 복제 구성

구성 요소	위치	역할
Master	VM (172.100.100.11) Docker Compose	Write 전용
Slave (x2)	K8s StatefulSet	Read 전용 (GTID 복제)

6. 프로젝트 산출물

6.1. 구현 파일 목록

구분	파일	설명
Frontend	`App.tsx`	메인 라우팅
Backend	`main.py`	FastAPI 엔드포인트
DB	`database.py`	Read/Write Split
Git Ops	`git_ops.py`	GitPython 연동
CI/CD	`pipelines.yaml`	GitHub Actions
GitLab CI	`.gitlab-ci.yml`	빌드/배포 파이프라인

6.2. Kubernetes 매니페스트

파일	설명
`ingress.yaml`	Ingress 라우팅 규칙
`fastapi-deployment.yaml`	FastAPI Deployment + Service (3 replicas)
`frontend.yaml`	React Deployment + Service
`nfs-provisioner.yaml`	NFS 동적 프로비저닝
`github-secret.yaml`	GitLab Registry 인증

6.3. 배포 순서

NFS Provisioner 설치
MySQL Master (VM Docker) 기동
MySQL Slave StatefulSet 배포 → 복제 설정
Backend (FastAPI) 배포 - NFS PVC 마운트
Frontend (React) 배포
Ingress 설정

6.4. 검증 방법

./check-cluster.sh - 클러스터 상태 확인
kubectl get pods - Pod 상태
kubectl exec mysql-slave-0 -- mysql -e "SHOW SLAVE STATUS\G" - 복제 상태
Primary Pod 삭제 → 서비스 지속 확인

7. 일정 계획

단계	작업 내용	상태
1단계	K8s 클러스터 초기 구축	O 완료
2단계	GitLab CI/CD 구축	O 완료
3단계	애플리케이션 배포 (Frontend/Backend)	O 완료
4단계	MySQL Master-Slave 복제 구성	O 완료
5단계	OAuth + Ingress 트러블슈팅	O 완료
6단계	블록 에디터 고도화	- 진행중
7단계	CI/CD 시각화	- 예정

프로젝트 계획서

목차

1. 프로젝트 주제

2. 요구사항 정의

2.1. 시스템 요구사항

2.2. 기능 요구사항

인증 및 계정 관리

저장소 관리

에디터

Git 연동

CI/CD 파이프라인

Kubernetes 인프라

2.3. 비기능 요구사항

3. 프로젝트 목표

3.1. 목표 개요

3.2. 기술 스택

3.3. 마일스톤

4. 시스템 아키텍처

4.1. 전체 구성

4.2. 네트워크 설계

4.3. CI/CD 파이프라인

5. 데이터베이스 설계

5.1. ERD

5.2. MySQL 복제 구성

6. 프로젝트 산출물

6.1. 구현 파일 목록

6.2. Kubernetes 매니페스트

6.3. 배포 순서

6.4. 검증 방법

7. 일정 계획

관련 문서

그래프 뷰

목차​

1. 프로젝트 주제​

2. 요구사항 정의​

2.1. 시스템 요구사항​

2.2. 기능 요구사항​

인증 및 계정 관리​

저장소 관리​

에디터​

Git 연동​

CI/CD 파이프라인​

Kubernetes 인프라​

2.3. 비기능 요구사항​

3. 프로젝트 목표​

3.1. 목표 개요​

3.2. 기술 스택​

3.3. 마일스톤​

4. 시스템 아키텍처​

4.1. 전체 구성​

4.2. 네트워크 설계​

4.3. CI/CD 파이프라인​

5. 데이터베이스 설계​

5.1. ERD​

5.2. MySQL 복제 구성​

6. 프로젝트 산출물​

6.1. 구현 파일 목록​

6.2. Kubernetes 매니페스트​

6.3. 배포 순서​

6.4. 검증 방법​

7. 일정 계획​

관련 문서​

그래프 뷰

목차

1. 프로젝트 주제

2. 요구사항 정의

2.1. 시스템 요구사항

2.2. 기능 요구사항

인증 및 계정 관리

저장소 관리

에디터

Git 연동

CI/CD 파이프라인

Kubernetes 인프라

2.3. 비기능 요구사항

3. 프로젝트 목표

3.1. 목표 개요

3.2. 기술 스택

3.3. 마일스톤

4. 시스템 아키텍처

4.1. 전체 구성

4.2. 네트워크 설계

4.3. CI/CD 파이프라인

5. 데이터베이스 설계

5.1. ERD

5.2. MySQL 복제 구성

6. 프로젝트 산출물

6.1. 구현 파일 목록

6.2. Kubernetes 매니페스트

6.3. 배포 순서

6.4. 검증 방법

7. 일정 계획

관련 문서