LibreBBS

리브레위키 커뮤니티를 위한 BBS(Bulletin Board System) API 서버입니다.

NestJS + Prisma + MySQL 기반으로 구현되었으며, 원본 Rust/Actix-web/Diesel 프로젝트(librebbs)를 Node.js로 포팅한 버전입니다.

기능

• 게시판(Boards): 게시판 목록 조회, 게시판별 토픽 목록
• 토픽(Topics): 토픽 생성, 조회, 상태 변경(고정/숨김/닫기/정지)
• 댓글(Comments): 댓글 작성, 조회, 숨김 처리
• 파일(Files): S3 파일 업로드
• 인증(Auth): 리브레위키 OAuth2 연동 (로그인/로그아웃/토큰 갱신)
• 사용자(Me): 현재 사용자 프로필 조회

기술 스택

• Runtime: Node.js
• Framework: NestJS 11
• ORM: Prisma 6
• Database: MySQL
• HTTP Client: @nestjs/axios
• File Storage: AWS S3
• Authentication: OAuth2 (librewiki.net)

설치

yarn install

환경 변수 설정

프로젝트 루트에 .env 파일을 생성하고 다음 변수를 설정하세요:

DATABASE_URL="mysql://user:password@localhost:3306/librebbs"

OAUTH_CLIENT_ID="your_oauth_client_id"
OAUTH_CLIENT_SECRET="your_oauth_client_secret"

AWS_S3_BUCKET="your_bucket_name"
AWS_S3_REGION="ap-northeast-2"
AWS_ACCESS_KEY_ID="your_access_key"
AWS_SECRET_ACCESS_KEY="your_secret_key"

JWT 토큰 검증을 위해 pubkey.pem 파일을 프로젝트 루트에 배치하세요 (선택 사항).

데이터베이스 설정

# Prisma 클라이언트 생성
npx prisma generate

# 마이그레이션 실행
npx prisma migrate dev --name init

실행

# 개발 모드
yarn start:dev

# 프로덕션 빌드
yarn build

# 프로덕션 실행
yarn start:prod

Docker Compose로 실행

Docker Compose를 사용하면 MariaDB와 함께 개발 환경을 쉽게 구성할 수 있습니다.

1. 환경 변수 설정

.env 파일에 OAuth 및 AWS 설정을 추가하세요:

OAUTH_CLIENT_ID="your_oauth_client_id"
OAUTH_CLIENT_SECRET="your_oauth_client_secret"

# AWS S3 설정 (선택 사항 - 없으면 파일 업로드 비활성화)
AWS_S3_BUCKET="your_bucket_name"
AWS_S3_REGION="ap-northeast-2"
AWS_ACCESS_KEY_ID="your_access_key"
AWS_SECRET_ACCESS_KEY="your_secret_key"

2. 컨테이너 실행

# 빌드 및 실행
docker compose up -d

# 로그 확인
docker compose logs -f app

3. 마이그레이션 실행

docker compose exec app npx prisma migrate deploy

4. 접속

• API 서버: http://localhost:3000
• 헬스체크: http://localhost:3000/health

기타 명령어

# 컨테이너 중지
docker compose down

# 볼륨 포함 삭제 (DB 데이터 초기화)
docker compose down -v

# 이미지 재빌드
docker compose up -d --build

테스트

# 유닛 테스트
yarn test

# 테스트 커버리지
yarn test:cov

# E2E 테스트
yarn test:e2e

API 엔드포인트

Method	Endpoint	설명
GET	/	서버 상태 확인
POST	/auth/login	OAuth 로그인
POST	/auth/logout	로그아웃
POST	/auth/refresh	토큰 갱신
GET	/me	현재 사용자 정보
GET	/boards	게시판 목록
GET	/boards/:boardId/topics	게시판의 토픽 목록
GET	/topics/:topicId	토픽 상세 조회
POST	/topics	토픽 생성
PUT	/topics/:topicId/status	토픽 상태 변경 (관리자)
GET	/topics/:topicId/comments	토픽의 댓글 목록
POST	/topics/:topicId/comments	댓글 작성
GET	/comments/:commentId	댓글 상세 조회
PUT	/comments/:commentId/status	댓글 상태 변경 (관리자)
POST	/files	파일 업로드

프로젝트 구조

src/
├── auth/           # 인증 모듈 (OAuth2)
├── boards/         # 게시판 모듈
├── comments/       # 댓글 모듈
├── common/         # 공통 유틸, 데코레이터, 가드
│   ├── decorators/ # @User, @ClientIp, @Public
│   ├── guards/     # AuthGuard, AdminGuard
│   ├── types/      # 공통 타입 정의
│   └── utils/      # IP 변환 유틸리티
├── files/          # 파일 업로드 모듈 (S3)
├── me/             # 사용자 정보 모듈
├── prisma/         # Prisma 서비스
├── topics/         # 토픽 모듈
├── app.module.ts   # 루트 모듈
└── main.ts         # 엔트리포인트

라이선스

MIT License