Community Board

오픈소스 커뮤니티 보드 — 게시판, 댓글, 좋아요, 신고, 알림, 카테고리, 관리자 페이지를 포함한 풀스택 Node.js + MySQL 애플리케이션입니다.

배경

이 프로젝트는 원래 고등학교 학생들을 위한 폐쇄형 커뮤니티로 만들어졌습니다. 학교 외부인의 가입을 막아야 했기 때문에 다음과 같은 설계 결정이 들어가 있습니다.

• 인증키 기반 회원가입: 관리자가 미리 발급한 인증키를 가진 사람만 가입할 수 있습니다. 학교에서는 담임 선생님이 학번별로 인증키를 학생에게 나눠주는 방식이었습니다. 일반 오픈 커뮤니티에는 불필요한 단계지만, 소속 인증이 필요한 동호회·동아리·사내 커뮤니티 등에는 그대로 유용합니다.
• 사용자 제재 시스템 (영구·일시·글쓰기 제한): 익명성 높은 학교 커뮤니티 특성상 강한 모더레이션이 필요해서 추가됐습니다.
• 신고 → 관리자 승인 워크플로: 같은 이유로, 신고가 곧바로 게시물에 영향을 주지 않고 관리자가 검토하도록 설계됐습니다.

오픈소스로 공개하면서 학교 고유 정보(특정 학교 이름, 학번 5자리 검증, NEIS 급식 연동 등)는 모두 제거했고, 사이트 이름·URL·설명은 환경변수로 설정되도록 바꿨습니다. 그대로 fork 해서 자신의 커뮤니티로 운영할 수 있습니다.

주요 기능

• 사용자 가입/로그인 (JWT)
• 인증키 기반 가입 (관리자가 발급)
• 게시글 CRUD + 카테고리 + 공지(고정)
• 댓글 / 대댓글 / 좋아요
• 게시글·댓글 신고 → 관리자 승인/반려
• 사용자 제재 (영구/일시/글쓰기 제한)
• 알림 시스템
• 관리자 페이지 (회원·게시글·신고·인증키 관리)

기술 스택

• Backend: Node.js, Express, MySQL2
• Auth: JWT, bcrypt
• Frontend: Vanilla JS + Quill 에디터
• Process manager: PM2 (선택)

빠른 시작

1. 저장소 클론 + 의존성 설치

git clone <YOUR_FORK_URL>
cd <repo>
npm install

2. 환경변수 설정

cp .env.example .env
# .env 파일을 열어 값들을 채워 넣으세요

필수 항목:

변수	설명
SITE_NAME	사이트 이름 (헤더·title·footer 등에 표시)
SITE_URL	사이트 URL (sitemap, schema.org meta)
JWT_SECRET	JWT 서명 키. 충분히 긴 랜덤 문자열 (openssl rand -hex 32)
DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME	MySQL 접속 정보
ADMIN_USERNAME, ADMIN_PASSWORD	초기 관리자 계정 (create-admin.js 실행 시)

3. 데이터베이스 초기화

MySQL 또는 MariaDB가 실행 중이어야 합니다.

mysql -u root -p < schema.sql

4. 초기 관리자 계정 생성

npm run create-admin

.env의 ADMIN_USERNAME / ADMIN_PASSWORD 값으로 admins 테이블에 행이 추가됩니다.

5. 서버 실행

# 개발 모드 (파일 변경 시 자동 재시작)
npm run dev

# 프로덕션 모드
npm start

기본 포트는 3000 입니다 (.env의 PORT 로 변경 가능).

사이트 이름 변경

SITE_NAME, SITE_URL, SITE_DESCRIPTION 환경변수만 바꾸면 됩니다. 서버가 HTML 응답을 보낼 때 {{SITE_NAME}}, {{SITE_URL}}, {{SITE_DESCRIPTION}} 자리표시자를 자동 치환합니다 (server.js 의 renderHtml 미들웨어).

런타임 JS에서 사이트 정보가 필요하면 /api/config 엔드포인트를 호출하세요.

디렉터리 구조

.
├── server.js              # Express 진입점 + 모든 API 라우트
├── create-admin.js        # 초기 관리자 계정 생성 스크립트
├── ecosystem.config.js    # PM2 설정
├── schema.sql             # DB 스키마 (MySQL/MariaDB)
├── .env.example           # 환경변수 템플릿
└── public/                # 정적 파일
    ├── index.html, login.html, register.html, post.html, write.html
    ├── admin/             # 관리자 페이지
    ├── css/               # 스타일
    └── js/                # 클라이언트 스크립트
        ├── components/    # 재사용 컴포넌트 (인증, 알림, 댓글 등)
        └── pages/         # 페이지별 진입점

API 개요

Method	Path	설명
GET	/api/config	사이트 메타 정보
POST	/api/register	회원가입
POST	/api/login	로그인
POST	/api/verify-auth-key	인증키 검증
GET/POST/PUT/DELETE	/api/posts(/:id)	게시글 CRUD
POST	/api/posts/:id/like	좋아요
GET/POST/PUT/DELETE	/api/posts/:postId/comments	댓글
POST	/api/comments/:commentId/reply	대댓글
GET	/api/categories	카테고리 목록
POST	/api/:type/:id/report	신고
GET	/api/notifications	알림 목록
*	/api/admin/*	관리자 API

PM2 로 운영

npm install -g pm2
pm2 start ecosystem.config.js --env production
pm2 save

라이선스

MIT — LICENSE 파일 참고.

기여

PR / 이슈 환영합니다. fork 후 사이트 이름만 바꿔서 자유롭게 사용하세요.