🚀 Deploy Center
<div align="center">
Version
Node
License
TypeScript
React
Build Status
PRs Welcome
Maintainability
GitHub issues
GitHub stars
현대적이고 안전하며 확장 가능한 자체 호스팅 CI/CD 배포 플랫폼
주요 기능 • 빠른 시작하기 • 문서화 • 아키텍처 • 기여
</div>
📋 목차 (Table of Contents)
<div id="overview"></div>
🎯 개요 (Overview)
Deploy Center는 배포 워크플로우를 자동화하고 간소화하도록 설계된 포괄적인 자체 호스팅 CI/CD(Continuous Integration / Continuous Delivery) 배포 플랫폼입니다. 현대적인 기술과 보안 모범 사례로 구축되어 엔터프라이즈급 기능을 제공하면서도 사용 및 유지 관리가 간단합니다.
왜 Deploy Center인가요?
- 🔒 자체 호스팅(Self-Hosted): 데이터와 인프라에 대한 완전한 제어권
- 🎨 현대적인 UI(Modern UI): 아름답고 반응성이 뛰어난 React 대시보드
- 🔐 엔터프라이즈 보안(Enterprise Security): 역할 기반 접근 제어 (RBAC), JWT 인증, SSH 키 관리
- 📊 실시간 모니터링(Real-Time Monitoring): 라이브 배포 상태, 큐 관리 및 알림 기능
- 🚀 쉬운 설정(Easy Setup): 빠르고 간편한 설치 및 구성
- 📱 알림(Notifications): Discord, Slack, 이메일 — 프로젝트별 구독이 가능한 중앙 집중식 제공자/채널 모델 (v3.0 F-006)
- 🔄 영구 큐(Persistent Queue): BullMQ + Redis — 프로세스 재시작에도 배포 유지 (v3.0 F-001)
- ↩️ 롤백 UI(Rollback UI): 마지막 성공적인 배포로 원클릭 롤백 기능 (v3.0 F-007)
- 🧩 프로젝트 템플릿(Project Templates): 내장 스캐폴드 제공 (Node.js, React, Next.js, Astro, Static) (v3.0 F-008)
- 📁 워크스페이스(Workspaces): @dnd-kit을 사용한 드래그 앤 드롭 프로젝트 그룹화 (v3.0 F-009)
- 🔐 암호화된 환경 변수(Encrypted Env Vars): 프로젝트별 AES-256-GCM 비밀값, 배포 시 주입 (v3.0 F-003)
- 📈 확장성(Scalable): 여러 프로젝트와 팀을 처리하도록 설계
<div id="key-features"></div>
✨ 주요 기능 (Key Features)
🔐 보안 및 인증 (Security & Authentication)
-
다중 계층 인증(Multi-Layer Authentication)
- JWT 기반 접근 및 새로고침 토큰
- 안전한 세션 관리
- bcrypt를 사용한 비밀번호 암호화
- 외부 통합을 위한 API 키 인증
-
역할 기반 접근 제어 (Role-Based Access Control, RBAC)
- 4가지 사용자 역할: 관리자(Admin), 매니저(Manager), 개발자(Developer), 뷰어(Viewer)
- 세분화된 권한 시스템
- 프로젝트 수준의 접근 제어
- 기능 기반 권한 부여
-
SSH 키 관리 (SSH Key Management)
- 자동 SSH 키 생성 (ED25519/RSA)
- 암호화된 개인 키 저장소 (AES-256-GCM)
- 키 순환 및 생명주기 관리
- GitHub 배포 키 통합
🚀 배포 기능 (Deployment Features)
-
지능형 배포 파이프라인(Intelligent Deployment Pipeline)
- 사용자 정의 다단계 파이프라인
- 조건부 단계 실행
- 변수 치환 시스템
- 사전/사후 배포 훅 (Pre/post deployment hooks)
-
다중 트리거 유형 (Multiple Trigger Types)
- GitHub 웹훅(webhook) 통합
- 수동 배포 트리거
- 예약 배포 (곧 출시 예정)
- API 기반 배포
-
영속 큐 (Persistent Queue) (BullMQ + Redis) — v3.0 F-001
- 서버 재시작 시에도 배포 유지 가능 (일회성 재등록 마이그레이션)
- 재시도 정책: 3회 시도, 지수 백오프(exponential backoff) (1초 → 5초 → 25초)
- Bull Board 관리자 UI는
/admin/queues에서 사용 가능 (관리자 전용)
- Redis에 접근할 수 없을 때
QueueReadyMiddleware를 통해 503 쇼트 서킷(short-circuit) 처리
- 큐 페이지에서 수동 취소 및 재시도 기능 제공
-
롤백 (Rollback) — v3.0 F-007
- 단일 클릭으로 실패한 배포를 롤백할 수 있음
TriggerType=rollback이 포함된 새로운 배포 행을 생성함- 표준 큐를 거침 (우선순위 20)
- from/to 커밋 해시가 기록된 감사 로그(audit log) 항목 생성
-
실시간 모니터링 (Real-Time Monitoring)
- WebSocket을 통한 실시간 배포 상태 확인
- 상세 단계별 로그 제공
- 배포 이력 추적 기능
- 성능 지표 및 분석 자료
📊 프로젝트 관리 (Project Management)
-
다중 프로젝트 지원 (Multi-Project Support)
- 무제한 프로젝트 지원
- 프로젝트별 구성 설정 가능
- 독립적인 배포 파이프라인 운영
- 프로젝트 보관 및 활성화 기능
-
프로젝트 멤버 (Project Members)
- 팀 협업 기능 제공
- 멤버 역할 할당 (소유자(Owner)/멤버(Member))
- 프로젝트별 접근 제어 설정
- 멤버 변경에 대한 감사 추적(audit trail)
-
구성 관리 (Configuration Management)
- JSON 기반 구성 설정
- 암호화된 환경 변수 (v3.0 F-003) — AES-256-GCM을 사용한
EnvironmentVariables 테이블, 행별 고유 IV(Initialization Vector), 로그에서 비밀 정보 마스킹 처리
- 구성 버전 관리 기능
-
프로젝트 템플릿 (Project Templates) — v3.0 F-008
- 5가지 내장 템플릿: Node.js 백엔드, React SPA (Vite), Next.js, 정적 HTML, Astro
- 관리자(Admin)/매니저가 편집 가능한 사용자 지정 템플릿 (내장 템플릿은 읽기 전용)
- 마법사(Wizard)는 프로젝트 생성의 단계 0으로 실행되며, 사용자는 건너뛰고 빈 상태로 시작할 수 있음
-
워크스페이스(Workspaces) — v3.0 F-009
- 색상 및 아이콘(20개 아이콘 카탈로그)을 사용한 프로젝트의 시각적 그룹화
- 드래그 앤 드롭 방식의 프로젝트 재할당 (
@dnd-kit)
- 선택 사항: 워크스페이스가 없는 프로젝트는 "미할당(Unassigned)"에 표시됨
- 워크스페이스 수정은 소유자 또는 관리자 역할 기반 접근 제어(RBAC)를 따름
📈 모니터링 및 분석 (Monitoring & Analytics)
🔔 알림 (Notifications) — v3.0 F-006 (제공자/채널/구독)
-
다중 채널 지원(Multi-Channel Support)
- Discord 웹훅
- Slack 웹훅 (
@slack/webhook)
- 이메일 (SMTP를 통한
nodemailer 사용) 및 Gmail / SendGrid / Mailgun용 사전 설정 제공
- 채널별 자격 증명은 AES-256-GCM 암호화되어 저장됨
-
세 테이블 모델(Three-Table Model)
- NotificationProvider: 자격 증명 (Discord 워크스페이스 1개, SMTP 서버 1개 등)
- NotificationChannel: 제공자별 전송 대상 (특정 채널 ID, 수신자 목록)
- ProjectNotificationSubscription: 다대다(M:N) 관계 — 어떤 프로젝트가 어떤 이벤트를 어떤 채널로 발생시킬지 정의
-
실패 격리(Failure Isolation) (FR-025b)
Promise.allSettled을 통한 팬아웃(fan-out) — 하나의 채널 실패가 다른 채널의 작동을 방해하지 않음- 채널별 실패는 해당 채널 및 제공자 컨텍스트와 함께 기록됨
-
배포를 트리거하지 않고 구성을 검증할 수 있는 제공자별 + 채널별 테스트 엔드포인트
🛠️ 개발자 경험 (Developer Experience)
<div id="what-problems-does-it-solve"></div>
💡 어떤 문제를 해결하는가?
1. 수동 배포의 복잡성(Manual Deployment Complexity)
문제점: 애플리케이션을 수동으로 배포하는 것은 시간이 많이 걸리고, 오류가 발생하기 쉬우며, 확장성이 부족합니다.
해결책: Deploy Center는 사용자 지정 가능한 파이프라인으로 전체 배포 프로세스를 자동화하여 배포 시간을 몇 시간에서 몇 분으로 단축시킵니다.
2. 배포 가시성 부족(Lack of Deployment Visibility)
문제점: 팀원들은 누가, 무엇을, 언제 배포했는지, 또는 왜 배포가 실패했는지 알지 못합니다.
해결책: 완전한 감사 추적(audit trails), 실시간 모니터링 및 상세 로그를 통해 모든 배포에 대한 완벽한 투명성을 제공합니다.
3. 보안 문제(Security Concerns)
문제점: 공유된 자격 증명(credentials)과 SSH 키는 보안 취약점을 만듭니다.
해결책: 암호화된 SSH 키 저장소, RBAC(역할 기반 접근 제어), 프로젝트 수준의 접근 통제를 통해 안전한 배포를 보장합니다.
4. 팀 협업 문제(Team Collaboration Issues)
문제점: 여러 개발자가 동시에 동일한 프로젝트에 안전하게 배포할 수 없습니다.
해결책: 지능형 대기열 시스템(queue system)이 충돌을 방지하고 배포가 올바른 순서로 실행되도록 보장합니다.
5. 중앙 통제 부재(No Central Control)
문제점: 다양한 도구와 스크립트에 분산된 배포는 관리를 어렵게 만듭니다.
해결책: 통합된 구성 및 모니터링을 갖춘 모든 배포를 위한 중앙 집중식 플랫폼을 제공합니다.
6. 배포 실패 복구(Failed Deployment Recovery)
문제점: 배포가 실패했을 때, 이전 상태로 복구하는 과정은 수동적이고 위험할 수 있습니다.
해결책: 자동 실패 감지, 롤백 기능(rollback capabilities), 그리고 배포 기록을 통해 쉬운 복구를 지원합니다.
7. 접근 제어의 한계(Access Control Limitations)
문제점: 모든 팀원이 동일한 접근 수준을 가지게 되어 보안 위험이 발생합니다.
솔루션: 4개의 역할과 프로젝트 수준의 권한을 가진 세분화된 RBAC(Role-Based Access Control) 시스템.
8. 알림 누락 문제 (Notification Gaps)
문제점: 배포가 실패하거나 성공했을 때 팀원들에게 알림이 가지 않습니다.
솔루션: Discord, Slack을 통한 다중 채널 알림으로 팀원들이 실시간으로 정보를 얻게 합니다.
<div id="architecture"></div>
🏗️ 아키텍처 (Architecture)
Deploy Center는 현대적인 3계층 아키텍처를 따릅니다:
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React SPA) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
...
<div id="key-components"></div>
주요 구성 요소 (Key Components)
-
프론트엔드 계층 (Frontend Layer)
- React 19 + TypeScript
- Material-UI (MUI) 컴포넌트
- 데이터 페칭을 위한 React Query
- 실시간 업데이트를 위한 Socket.IO 클라이언트
-
백엔드 계층 (Backend Layer)
- Express.js 서버
- 서비스 지향 아키텍처(Service-oriented architecture)
- JWT 인증 미들웨어
- WebSocket 서버
-
데이터 계층 (Data Layer)
- MySQL/MariaDB 데이터베이스
- Sequelize ORM
- 자동 마이그레이션(Automated migrations)
- 연결 풀링(Connection pooling)
-
외부 통합 (External Integrations)
- GitHub 웹훅(webhooks)
- Discord 알림
- SSH Git 작업
<div id="technology-stack"></div>
🛠️ 기술 스택 (Technology Stack)
백엔드 (Backend)
- 런타임: Node.js 18+
- 프레임워크: Express.js
- 언어: TypeScript 5.7
- ORM: Sequelize 6.37
- 데이터베이스: MySQL 8.0 / MariaDB 11.2
- 인증: JWT (jsonwebtoken)
- 암호화: bcryptjs, crypto (AES-256-GCM)
- 실시간: Socket.IO 4.8
- 프로세스 관리자: PM2
- 로깅: Winston
- 유효성 검사: express-validator
프론트엔드 (Frontend)
- 프레임워크: React 19
- 언어: TypeScript 5.6
- UI 라이브러리: Material-UI (MUI) 7.5
- 상태 관리: React Query (TanStack Query)
- 라우팅: React Router 7.6
- 차트: Recharts 2.15
- HTTP 클라이언트: Axios
- 빌드 도구: Vite 7.2
- 버전 관리 (Version Control): Git
- 패키지 매니저 (Package Manager): npm
- 코드 품질 (Code Quality): ESLint, Prettier
- 보안 스캐닝 (Security Scanning): CodeQL, npm audit
- CI/CD: GitHub Actions
- 컨테이너 (Container): Docker (선택 사항)
<div id="quick-start"></div>
🚀 빠른 시작 (Quick Start)
필수 준비물 (Prerequisites)
- Node.js >= 18.0.0
- MySQL >= 8.0 또는 MariaDB >= 11.2
- Git
- PM2 (운영 환경용)
설치 (Installation)
git clone https://github.com/FutureSolutionDev/Deploy-Center-Server.git
cd Deploy-Center-Server
...
설정 (Configuration)
- 백엔드 설정 (Backend Configuration) (
server/.env)
