refactor: Phase 1 - 긴급 보안 및 중복 제거
## 🚨 보안 강화 - 하드코딩된 비밀번호를 환경변수로 전환 - .env.example 생성 및 보안 가이드 추가 - docker-compose.yml 환경변수 적용 - README.md에서 실제 비밀번호 제거 ## 🗑️ 중복 제거 - synology_deployment/ 디렉토리 제거 (268MB) - synology_deployment*.tar.gz 아카이브 제거 (234MB) - 총 502MB의 중복 파일 삭제 ## 🧹 백업 파일 정리 - *.backup 파일 제거 (10개) - *복사본* 파일 제거 - *이전* 파일 제거 - json(백업)/ 디렉토리 제거 ## 📋 .gitignore 업데이트 - 백업 파일 패턴 추가 - 보안 파일 제외 (.env, *.pem, *.key) - 임시 파일 제외 (*.tmp, *.new) - 빌드 아티팩트 제외 (*.tar.gz) ## 📚 문서화 - docs/ 디렉토리 구조 생성 - 리팩토링 분석 및 계획 문서 작성 - 코딩 스타일 가이드 작성 - 개발 환경 설정 가이드 작성 - 시스템 아키텍처 문서 작성 ## 변경된 파일 - .env.example (신규) - .gitignore (업데이트) - docker-compose.yml (환경변수 적용) - README.md (보안 정보 제거) - docs/* (신규 문서 7개) ## 보안 개선 효과 ✅ 비밀번호 노출 위험 제거 ✅ Git 히스토리에서 민감 정보 분리 ✅ 환경별 설정 분리 가능 ✅ 배포 보안 강화 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Hyungi Ahn
662
docs/guides/SETUP.md
Normal file
662
docs/guides/SETUP.md
Normal file
@@ -0,0 +1,662 @@
|
||||
# 개발 환경 설정 가이드
|
||||
|
||||
> TK-FB-Project 로컬 개발 환경 구축 가이드
|
||||
|
||||
## 📋 목차
|
||||
|
||||
1. [시스템 요구사항](#시스템-요구사항)
|
||||
2. [필수 도구 설치](#필수-도구-설치)
|
||||
3. [프로젝트 설정](#프로젝트-설정)
|
||||
4. [데이터베이스 설정](#데이터베이스-설정)
|
||||
5. [애플리케이션 실행](#애플리케이션-실행)
|
||||
6. [개발 도구](#개발-도구)
|
||||
7. [문제 해결](#문제-해결)
|
||||
|
||||
---
|
||||
|
||||
## 시스템 요구사항
|
||||
|
||||
### 최소 사양
|
||||
- **OS**: macOS, Linux, Windows 10+
|
||||
- **CPU**: 2 Core 이상
|
||||
- **RAM**: 4GB 이상
|
||||
- **디스크**: 10GB 이상 여유 공간
|
||||
|
||||
### 권장 사양
|
||||
- **OS**: macOS (Apple Silicon) 또는 Ubuntu 22.04 LTS
|
||||
- **CPU**: 4 Core 이상
|
||||
- **RAM**: 8GB 이상
|
||||
- **디스크**: SSD 20GB 이상
|
||||
|
||||
---
|
||||
|
||||
## 필수 도구 설치
|
||||
|
||||
### 1. Node.js & npm
|
||||
|
||||
**macOS (Homebrew)**:
|
||||
```bash
|
||||
# Homebrew 설치 (없는 경우)
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# Node.js 설치
|
||||
brew install node@20
|
||||
|
||||
# 버전 확인
|
||||
node --version # v20.x.x
|
||||
npm --version # 10.x.x
|
||||
```
|
||||
|
||||
**Ubuntu/Debian**:
|
||||
```bash
|
||||
# NodeSource repository 추가
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
|
||||
# Node.js 설치
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# 버전 확인
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
**Windows**:
|
||||
- [Node.js 공식 사이트](https://nodejs.org/)에서 LTS 버전 다운로드 및 설치
|
||||
|
||||
### 2. Git
|
||||
|
||||
**macOS**:
|
||||
```bash
|
||||
brew install git
|
||||
```
|
||||
|
||||
**Ubuntu/Debian**:
|
||||
```bash
|
||||
sudo apt-get install git
|
||||
```
|
||||
|
||||
**Windows**:
|
||||
- [Git for Windows](https://git-scm.com/download/win) 다운로드
|
||||
|
||||
**설정**:
|
||||
```bash
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "your.email@example.com"
|
||||
```
|
||||
|
||||
### 3. Docker & Docker Compose
|
||||
|
||||
**macOS**:
|
||||
```bash
|
||||
# Docker Desktop 설치
|
||||
brew install --cask docker
|
||||
|
||||
# Docker Desktop 실행 후 확인
|
||||
docker --version
|
||||
docker-compose --version
|
||||
```
|
||||
|
||||
**Ubuntu/Debian**:
|
||||
```bash
|
||||
# Docker 설치
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
|
||||
# Docker Compose 설치
|
||||
sudo apt-get install docker-compose-plugin
|
||||
|
||||
# 사용자를 docker 그룹에 추가
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
# 버전 확인
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
**Windows**:
|
||||
- [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/) 설치
|
||||
|
||||
### 4. MySQL Client (선택사항)
|
||||
|
||||
**macOS**:
|
||||
```bash
|
||||
brew install mysql-client
|
||||
```
|
||||
|
||||
**Ubuntu/Debian**:
|
||||
```bash
|
||||
sudo apt-get install mysql-client
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 프로젝트 설정
|
||||
|
||||
### 1. 저장소 클론
|
||||
|
||||
```bash
|
||||
# HTTPS
|
||||
git clone https://github.com/your-org/TK-FB-Project.git
|
||||
|
||||
# 또는 SSH
|
||||
git clone git@github.com:your-org/TK-FB-Project.git
|
||||
|
||||
# 프로젝트 디렉토리로 이동
|
||||
cd TK-FB-Project
|
||||
```
|
||||
|
||||
### 2. 환경 변수 설정
|
||||
|
||||
```bash
|
||||
# .env.example 복사
|
||||
cp .env.example .env
|
||||
|
||||
# .env 파일 편집
|
||||
nano .env # 또는 vi, code 등
|
||||
```
|
||||
|
||||
**.env 파일 설정**:
|
||||
```bash
|
||||
# Database
|
||||
DB_HOST=localhost
|
||||
DB_PORT=3306
|
||||
DB_NAME=hyungi
|
||||
DB_USER=hyungi
|
||||
DB_PASSWORD=your_secure_password_here
|
||||
DB_ROOT_PASSWORD=your_root_password_here
|
||||
|
||||
# API
|
||||
API_PORT=20005
|
||||
NODE_ENV=development
|
||||
|
||||
# JWT
|
||||
JWT_SECRET=your_jwt_secret_key_at_least_32_characters
|
||||
JWT_REFRESH_SECRET=your_refresh_secret_key_at_least_32_characters
|
||||
|
||||
# Email (선택사항)
|
||||
EMAIL_HOST=smtp.gmail.com
|
||||
EMAIL_PORT=587
|
||||
EMAIL_USER=your-email@gmail.com
|
||||
EMAIL_PASSWORD=your-app-password
|
||||
|
||||
# OpenAI (선택사항)
|
||||
OPENAI_API_KEY=your_openai_api_key
|
||||
```
|
||||
|
||||
**보안 참고**:
|
||||
```bash
|
||||
# 강력한 랜덤 비밀번호 생성
|
||||
openssl rand -base64 32
|
||||
|
||||
# 또는
|
||||
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||||
```
|
||||
|
||||
### 3. 백엔드 의존성 설치
|
||||
|
||||
```bash
|
||||
cd api.hyungi.net
|
||||
npm install
|
||||
```
|
||||
|
||||
**주요 의존성**:
|
||||
- express: 웹 프레임워크
|
||||
- mysql2: MySQL 드라이버
|
||||
- jsonwebtoken: JWT 인증
|
||||
- bcryptjs: 비밀번호 해싱
|
||||
- cors: CORS 미들웨어
|
||||
- dotenv: 환경변수 관리
|
||||
|
||||
### 4. 프론트엔드 설정
|
||||
|
||||
```bash
|
||||
cd ../web-ui
|
||||
# 프론트엔드는 Vanilla JS이므로 별도 빌드 불필요
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 데이터베이스 설정
|
||||
|
||||
### 방법 1: Docker Compose (권장)
|
||||
|
||||
```bash
|
||||
# 프로젝트 루트에서
|
||||
cd /path/to/TK-FB-Project
|
||||
|
||||
# Docker 컨테이너 시작
|
||||
docker-compose up -d db
|
||||
|
||||
# 로그 확인
|
||||
docker-compose logs -f db
|
||||
|
||||
# MySQL 준비 확인 (약 30초 소요)
|
||||
docker-compose exec db mysqladmin ping -h localhost
|
||||
```
|
||||
|
||||
**초기 데이터 로드**:
|
||||
```bash
|
||||
# SQL 파일 임포트
|
||||
docker-compose exec -T db mysql -u hyungi -p hyungi < hyungi.sql
|
||||
|
||||
# 비밀번호 입력: .env 파일의 DB_PASSWORD
|
||||
```
|
||||
|
||||
### 방법 2: 로컬 MySQL 설치
|
||||
|
||||
**macOS**:
|
||||
```bash
|
||||
# MySQL 설치
|
||||
brew install mysql@8.0
|
||||
|
||||
# MySQL 시작
|
||||
brew services start mysql@8.0
|
||||
|
||||
# 보안 설정
|
||||
mysql_secure_installation
|
||||
```
|
||||
|
||||
**Ubuntu/Debian**:
|
||||
```bash
|
||||
# MySQL 설치
|
||||
sudo apt-get install mysql-server
|
||||
|
||||
# MySQL 시작
|
||||
sudo systemctl start mysql
|
||||
sudo systemctl enable mysql
|
||||
|
||||
# 보안 설정
|
||||
sudo mysql_secure_installation
|
||||
```
|
||||
|
||||
**데이터베이스 생성**:
|
||||
```bash
|
||||
# MySQL 접속
|
||||
mysql -u root -p
|
||||
|
||||
# SQL 실행
|
||||
CREATE DATABASE hyungi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
CREATE USER 'hyungi'@'localhost' IDENTIFIED BY 'your_password';
|
||||
GRANT ALL PRIVILEGES ON hyungi.* TO 'hyungi'@'localhost';
|
||||
FLUSH PRIVILEGES;
|
||||
EXIT;
|
||||
|
||||
# 데이터 임포트
|
||||
mysql -u hyungi -p hyungi < hyungi.sql
|
||||
```
|
||||
|
||||
### 데이터베이스 확인
|
||||
|
||||
```bash
|
||||
# Docker 사용 시
|
||||
docker-compose exec db mysql -u hyungi -p hyungi
|
||||
|
||||
# 로컬 MySQL 사용 시
|
||||
mysql -u hyungi -p hyungi
|
||||
```
|
||||
|
||||
```sql
|
||||
-- 테이블 확인
|
||||
SHOW TABLES;
|
||||
|
||||
-- 사용자 확인
|
||||
SELECT * FROM users LIMIT 5;
|
||||
|
||||
-- 데이터 확인
|
||||
SELECT COUNT(*) FROM daily_work_reports;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 애플리케이션 실행
|
||||
|
||||
### 개발 모드 (Docker Compose)
|
||||
|
||||
```bash
|
||||
# 전체 서비스 시작
|
||||
docker-compose up
|
||||
|
||||
# 백그라운드 실행
|
||||
docker-compose up -d
|
||||
|
||||
# 로그 확인
|
||||
docker-compose logs -f
|
||||
|
||||
# 특정 서비스 로그
|
||||
docker-compose logs -f api
|
||||
docker-compose logs -f web
|
||||
|
||||
# 서비스 중지
|
||||
docker-compose down
|
||||
|
||||
# 볼륨 포함 완전 삭제
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
### 개발 모드 (로컬 실행)
|
||||
|
||||
**터미널 1 - 백엔드**:
|
||||
```bash
|
||||
cd api.hyungi.net
|
||||
|
||||
# 개발 모드 (nodemon 사용)
|
||||
npm run dev
|
||||
|
||||
# 또는 일반 실행
|
||||
npm start
|
||||
```
|
||||
|
||||
**터미널 2 - 프론트엔드**:
|
||||
```bash
|
||||
cd web-ui
|
||||
|
||||
# 간단한 HTTP 서버 실행
|
||||
python3 -m http.server 8080
|
||||
|
||||
# 또는 Node.js http-server
|
||||
npx http-server -p 8080
|
||||
|
||||
# 또는 PHP
|
||||
php -S localhost:8080
|
||||
```
|
||||
|
||||
### 접속 확인
|
||||
|
||||
- **프론트엔드**: http://localhost:8080
|
||||
- **백엔드 API**: http://localhost:20005/api
|
||||
- **데이터베이스**: localhost:3306
|
||||
|
||||
**API 테스트**:
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:20005/api/health
|
||||
|
||||
# 로그인 테스트
|
||||
curl -X POST http://localhost:20005/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"your_password"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 개발 도구
|
||||
|
||||
### 1. VSCode 확장 프로그램
|
||||
|
||||
**필수**:
|
||||
- ESLint
|
||||
- Prettier - Code formatter
|
||||
- MySQL (cweijan.vscode-mysql-client2)
|
||||
- Docker
|
||||
|
||||
**권장**:
|
||||
- GitLens
|
||||
- Thunder Client (API 테스트)
|
||||
- Live Server
|
||||
- JavaScript (ES6) code snippets
|
||||
|
||||
**설치**:
|
||||
```bash
|
||||
# VSCode에서
|
||||
Cmd/Ctrl + Shift + X → 확장 프로그램 검색 및 설치
|
||||
```
|
||||
|
||||
### 2. VSCode 설정
|
||||
|
||||
`.vscode/settings.json`:
|
||||
```json
|
||||
{
|
||||
"editor.formatOnSave": true,
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.fixAll.eslint": true
|
||||
},
|
||||
"javascript.suggest.autoImports": true,
|
||||
"javascript.updateImportsOnFileMove.enabled": "always",
|
||||
"[javascript]": {
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 디버깅 설정
|
||||
|
||||
`.vscode/launch.json`:
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"name": "Launch API Server",
|
||||
"skipFiles": ["<node_internals>/**"],
|
||||
"program": "${workspaceFolder}/api.hyungi.net/index.js",
|
||||
"env": {
|
||||
"NODE_ENV": "development"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 유용한 명령어
|
||||
|
||||
```bash
|
||||
# 패키지 업데이트 확인
|
||||
npm outdated
|
||||
|
||||
# 보안 취약점 확인
|
||||
npm audit
|
||||
|
||||
# 보안 취약점 자동 수정
|
||||
npm audit fix
|
||||
|
||||
# 캐시 정리
|
||||
npm cache clean --force
|
||||
|
||||
# node_modules 재설치
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 일반적인 문제
|
||||
|
||||
#### 1. Port already in use
|
||||
|
||||
**증상**:
|
||||
```
|
||||
Error: listen EADDRINUSE: address already in use :::20005
|
||||
```
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# 포트 사용 중인 프로세스 확인
|
||||
lsof -i :20005
|
||||
|
||||
# 프로세스 종료
|
||||
kill -9 <PID>
|
||||
|
||||
# 또는 다른 포트 사용
|
||||
# .env 파일에서 API_PORT 변경
|
||||
```
|
||||
|
||||
#### 2. MySQL 연결 실패
|
||||
|
||||
**증상**:
|
||||
```
|
||||
Error: connect ECONNREFUSED 127.0.0.1:3306
|
||||
```
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# Docker 사용 시
|
||||
docker-compose ps # db 컨테이너 상태 확인
|
||||
docker-compose up -d db # db 재시작
|
||||
|
||||
# 로컬 MySQL 사용 시
|
||||
sudo systemctl status mysql # 상태 확인
|
||||
sudo systemctl start mysql # MySQL 시작
|
||||
|
||||
# 연결 테스트
|
||||
mysql -h localhost -u hyungi -p
|
||||
```
|
||||
|
||||
#### 3. Permission denied
|
||||
|
||||
**증상**:
|
||||
```
|
||||
Error: EACCES: permission denied
|
||||
```
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# Docker 권한 문제
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
# 파일 권한 문제
|
||||
sudo chown -R $USER:$USER /path/to/project
|
||||
```
|
||||
|
||||
#### 4. Module not found
|
||||
|
||||
**증상**:
|
||||
```
|
||||
Error: Cannot find module 'express'
|
||||
```
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# node_modules 재설치
|
||||
cd api.hyungi.net
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
#### 5. JWT 토큰 오류
|
||||
|
||||
**증상**:
|
||||
```
|
||||
Error: jwt malformed
|
||||
Error: invalid signature
|
||||
```
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# .env 파일 확인
|
||||
# JWT_SECRET이 올바르게 설정되어 있는지 확인
|
||||
|
||||
# 토큰 재발급
|
||||
# 로그아웃 후 다시 로그인
|
||||
```
|
||||
|
||||
### 데이터베이스 문제
|
||||
|
||||
#### MySQL 8.0 호환성
|
||||
|
||||
**증상**:
|
||||
```
|
||||
Error: ER_NOT_SUPPORTED_AUTH_MODE
|
||||
```
|
||||
|
||||
**해결**:
|
||||
```sql
|
||||
-- MySQL 접속
|
||||
mysql -u root -p
|
||||
|
||||
-- 인증 방식 변경
|
||||
ALTER USER 'hyungi'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
|
||||
FLUSH PRIVILEGES;
|
||||
```
|
||||
|
||||
#### 한글 깨짐
|
||||
|
||||
**해결**:
|
||||
```sql
|
||||
-- 데이터베이스 문자셋 확인
|
||||
SHOW VARIABLES LIKE 'character_set%';
|
||||
|
||||
-- 테이블 문자셋 변경
|
||||
ALTER TABLE daily_work_reports CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
```
|
||||
|
||||
### Docker 문제
|
||||
|
||||
#### 컨테이너 재시작
|
||||
|
||||
```bash
|
||||
# 컨테이너 재시작
|
||||
docker-compose restart
|
||||
|
||||
# 특정 서비스만
|
||||
docker-compose restart api
|
||||
|
||||
# 완전 재빌드
|
||||
docker-compose down
|
||||
docker-compose build --no-cache
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
#### 볼륨 문제
|
||||
|
||||
```bash
|
||||
# 볼륨 확인
|
||||
docker volume ls
|
||||
|
||||
# 볼륨 삭제 (주의: 데이터 손실)
|
||||
docker-compose down -v
|
||||
|
||||
# 특정 볼륨만 삭제
|
||||
docker volume rm tk-fb-project_mysql_data
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 추가 리소스
|
||||
|
||||
### 공식 문서
|
||||
- [Node.js](https://nodejs.org/docs)
|
||||
- [Express](https://expressjs.com/)
|
||||
- [MySQL](https://dev.mysql.com/doc/)
|
||||
- [Docker](https://docs.docker.com/)
|
||||
|
||||
### 내부 문서
|
||||
- [아키텍처 개요](../architecture/OVERVIEW.md)
|
||||
- [API 문서](../api/ENDPOINTS.md)
|
||||
- [코딩 스타일 가이드](CODING_STYLE.md)
|
||||
- [문제 해결 가이드](TROUBLESHOOTING.md)
|
||||
|
||||
### 커뮤니티
|
||||
- [Node.js GitHub](https://github.com/nodejs/node)
|
||||
- [Stack Overflow](https://stackoverflow.com/questions/tagged/node.js)
|
||||
|
||||
---
|
||||
|
||||
## 체크리스트
|
||||
|
||||
설정 완료 확인:
|
||||
|
||||
- [ ] Node.js 설치 (v20+)
|
||||
- [ ] Git 설치 및 설정
|
||||
- [ ] Docker 설치 및 실행
|
||||
- [ ] 프로젝트 클론
|
||||
- [ ] .env 파일 생성 및 설정
|
||||
- [ ] npm install 완료
|
||||
- [ ] 데이터베이스 생성 및 데이터 로드
|
||||
- [ ] 백엔드 서버 실행 확인
|
||||
- [ ] 프론트엔드 서버 실행 확인
|
||||
- [ ] API 테스트 성공
|
||||
- [ ] 로그인 성공
|
||||
- [ ] VSCode 확장 프로그램 설치
|
||||
|
||||
---
|
||||
|
||||
**도움이 필요하면**: 프로젝트 관리자에게 문의하세요.
|
||||
|
||||
*마지막 업데이트: 2025-12-11*
|
||||
Reference in New Issue
Block a user