Spacebar 서버 구축 가이드: 환경 설정부터 실행까지 완벽한 단계별 설명
Spacebar Server는 TypeScript로 개발된 Discord 백엔드의 재구현 프로젝트로, 개발자가 자체 채팅 서버를 구축하면서 기존 Discord 클라이언트, 봇 및 애플리케이션과의 호환성을 유지할 수 있게 해줍니다. 본 가이드는 환경 설정부터 서버 성공 실행까지 전 과정을 단계별로 안내하며, 초보자도 쉽게 따라할 수 있도록 구성되었습니다.
사전 준비: 시스템 요구사항
시작하기 전에 시스템이 다음 기본 요구사항을 충족하는지 확인하세요:
- Node.js: v16.0.0 이상 버전 (LTS 버전 권장)
- npm: v7.0.0+ (일반적으로 Node.js와 함께 설치됨)
- Git: 프로젝트 저장소 클론용
- 데이터베이스: PostgreSQL 13+ (최신 안정 버전 권장)
- 시스템 자원: 최소 1GB RAM 및 10GB 여유 디스크 공간
빠른 설치: 3단계로 기본 배포 완료
1. 저장소 클론
먼저 Git을 사용하여 프로젝트 코드를 로컬에 다운로드합니다:
git clone https://gitcode.com/gh_mirrors/server9/server
cd spacebar-project
2. 의존성 패키지 설치
프로젝트 디렉토리로 이동한 후 npm을 사용하여 필요한 의존성을 설치합니다:
npm install
팁: 설치 속도가 느릴 경우, 국내 미러 소스를 사용해 보세요:
npm install --registry=https://registry.npmmirror.com
3. 환경 변수 설정
프로젝트가 정상적으로 작동하려면 일부 필수 환경 변수가 필요합니다. 예제 구성 파일을 복사하고 실제 환경에 맞게 수정합니다:
cp .env.example .env
텍스트 편집기로 .env 파일을 열어 다음과 같은 핵심 항목을 최소한으로 구성해야 합니다:
DB_CONNECTION_STRING: PostgreSQL 데이터베이스 연결 주소API_PORT: API 서버 포트 (기본값 3000)WEBSOCKET_PORT: WebSocket 게이트웨이 포트 (기본값 3001)
서버 시작: 두 가지 실행 방식
개발 모드로 시작
개발 및 디버깅에 적합하며, 코드 수정 시 자동으로 재시작됩니다:
npm run development
프로덕션 모드로 시작
실제 서비스 배포에 적합하며, 먼저 TypeScript 코드를 JavaScript로 컴파일합니다:
npm run compile
npm run production
성공적으로 시작되면 다음과 유사한 출력이 표시됩니다:
[2023-10-01 12:00:00] INFO: API 서버가 3000 포트에서 시작되었습니다
[2023-10-01 12:00:01] INFO: 게이트웨이 서버가 3001 포트에서 시작되었습니다
[2023-10-01 12:00:02] INFO: CDN 서버가 3002 포트에서 시작되었습니다
[2023-10-01 12:00:03] INFO: 데이터베이스에 성공적으로 연결되었습니다
설치 확인: 서비스 상태 점검
서버가 시작된 후 다음 방법으로 정상적으로 실행되는지 확인할 수 있습니다:
- API 서비스 확인:
http://localhost:3000/api/v9/health에 접속하여{"status": "ok", "timestamp": "2023-10-01T12:00:00Z"}응답을 확인 - 게이트웨이 연결 테스트: WebSocket 클라이언트로
ws://localhost:3001에 연결하여 서버의 Hello 메시지 수신 확인 - 관리 인터페이스:
http://localhost:3000/console으로 접속하여 관리 콘솔에 진입 (기본 계정: admin@spacebar.local, 비밀번호: admin123)
자주 발생하는 문제 해결
데이터베이스 연결 실패
- PostgreSQL 서비스가 정상적으로 실행 중인지 확인
.env파일의DB_CONNECTION_STRING형식이 올바른지 확인 (예시:postgresql://user:password@localhost:5432/spacebar_db)- 데이터베이스 사용자가 충분한 권한을 가지고 있는지 확인
포트 사용 중 오류
.env파일의API_PORT,WEBSOCKET_PORT등 포트 설정 수정netstat -tulpn | grep :포트번호를 사용하여 사용 중인 프로세스를 찾아 종료
의존성 설치 오류
node_modules디렉토리를 삭제 후 재설치 시도:rm -rf node_modules && npm install- Node.js 버전이 요구사항을 충족하는지 확인:
node --version
프로젝트 구조 분석
프로젝트 구조를 이해하면 향후 사용자 정의 및 확장에 도움이 됩니다:
- src/api/: HTTP API 서버 구현, 모든 API 라우트 및 미들웨이 포함
- src/ws/: WebSocket 게이트웨이 서비스, 실시간 메시지 전송 처리
- src/storage/: 콘텐츠 저장소 서비스, 파일 업로드 및 분산 처리
- src/helpers/: 유틸리티 함수 및 데이터베이스 스키마
- src/models/: API 요청/응답 데이터 구조 정의
업데이트 유지
Spacebar Server는 계속 개발 중이므로, 정기적으로 업데이트하여 최신 기능 및 보안 패치를 받으세요:
git fetch origin
git pull origin main
npm update
npm run compile
npm run production
이 가이드가 Spacebar Server 구축 여정에 도움이 되기를 바랍니다!