🚀 배포용: PDF 뷰어 개선 및 서적별 UI 데본씽크 스타일 적용
✨ 주요 개선사항: - PDF API 500 에러 수정 (한글 파일명 UTF-8 인코딩 처리) - PDF 뷰어 기능 완전 구현 (PDF.js 통합, 네비게이션, 확대/축소) - 서적별 문서 그룹화 UI 데본씽크 스타일로 개선 - PDF Manager 페이지 서적별 보기 기능 추가 - Alpine.js 로드 순서 최적화로 JavaScript 에러 해결 🎨 UI/UX 개선: - 확장/축소 가능한 아코디언 스타일 서적 목록 - 간결하고 직관적인 데본씽크 스타일 인터페이스 - PDF 상태 표시 (HTML 연결, 서적 분류) - 반응형 디자인 및 부드러운 애니메이션 🔧 기술적 개선: - PDF.js 워커 설정 및 토큰 인증 처리 - 서적별 PDF 자동 그룹화 로직 - Alpine.js 컴포넌트 초기화 최적화
This commit is contained in:
hyungi
276
QUICK-START.md
Normal file
276
QUICK-START.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# 🚀 빠른 시작 가이드
|
||||
|
||||
Document Server를 Synology DS1525+에 배포하는 가장 간단한 방법입니다.
|
||||
|
||||
## ⚠️ 실제 서비스 환경 주의사항
|
||||
|
||||
### 🚨 중요: 이 시스템은 실제 서비스 중입니다!
|
||||
이 Document Server는 **실제 운영 중인 맥미니**에 설치되어 사용되고 있습니다.
|
||||
|
||||
**절대 삭제하면 안 되는 원본 데이터:**
|
||||
- 모든 업로드된 문서 파일들
|
||||
- 사용자가 작성한 메모, 하이라이트, 노트북
|
||||
- 데이터베이스의 모든 사용자 데이터
|
||||
- 설정 파일 및 사용자 환경설정
|
||||
|
||||
### 🛡️ 업데이트 시 필수 원칙
|
||||
1. **백업 우선**: 모든 작업 전 반드시 백업
|
||||
2. **데이터 보존**: 기존 데이터 디렉토리는 절대 삭제 금지
|
||||
3. **점진적 적용**: 코드만 업데이트하고 데이터는 보존
|
||||
4. **즉시 롤백**: 문제 발생 시 바로 이전 버전으로 복구
|
||||
|
||||
## 📋 준비사항
|
||||
|
||||
- Synology DS1525+ (32GB RAM, SSD 캐시 활성화) 또는 Mac Mini
|
||||
- Docker 패키지 설치 (Package Center에서 설치)
|
||||
- SSH 접속 가능
|
||||
- Git 설치 (선택사항)
|
||||
- **중요**: 기존 서비스 중단 최소화를 위한 계획
|
||||
|
||||
## 🎯 한 번에 배포하기
|
||||
|
||||
### 방법 1: Git 클론 (권장) ⭐
|
||||
|
||||
```bash
|
||||
# 1. NAS에 SSH 접속
|
||||
ssh admin@your-nas-ip
|
||||
|
||||
# 2. 프로젝트 클론
|
||||
cd /volume1/docker/
|
||||
git clone https://git.hyungi.net/hyungi/document-server.git
|
||||
cd document-server
|
||||
|
||||
# 3. 자동 배포 (환경 설정 + 배포)
|
||||
./scripts/deploy-synology.sh
|
||||
```
|
||||
|
||||
### 방법 2: 파일 업로드
|
||||
|
||||
```bash
|
||||
# 1. 로컬에서 NAS로 파일 전송
|
||||
scp -r ./document-server admin@your-nas-ip:/volume1/docker/
|
||||
|
||||
# 2. NAS에 SSH 접속
|
||||
ssh admin@your-nas-ip
|
||||
cd /volume1/docker/document-server
|
||||
|
||||
# 3. 자동 배포
|
||||
./scripts/deploy-synology.sh
|
||||
```
|
||||
|
||||
## ⚙️ 환경 설정 (자동)
|
||||
|
||||
배포 스크립트 실행 시 자동으로 환경 설정이 시작됩니다:
|
||||
|
||||
```
|
||||
=== 🔧 Document Server 환경 변수 설정 ===
|
||||
|
||||
1. 데이터베이스 비밀번호
|
||||
기본값: AbC123XyZ (자동생성)
|
||||
입력: [엔터 = 기본값 사용]
|
||||
|
||||
2. JWT 시크릿 키 (보안용)
|
||||
기본값: kL9mN2pQ... (자동생성)
|
||||
입력: [엔터 = 기본값 사용]
|
||||
|
||||
3. 관리자 이메일
|
||||
기본값: admin@document-server.local
|
||||
입력: admin@mydomain.com
|
||||
|
||||
4. 관리자 비밀번호
|
||||
기본값: MyPass123 (자동생성)
|
||||
입력: [엔터 = 기본값 사용]
|
||||
|
||||
5. 도메인 이름 (외부 접속용)
|
||||
기본값: localhost
|
||||
입력: nas.mydomain.com
|
||||
```
|
||||
|
||||
**💡 팁**: 대부분 엔터만 눌러도 안전한 기본값이 자동 설정됩니다!
|
||||
|
||||
## 🎉 배포 완료 후
|
||||
|
||||
### 접속 확인
|
||||
```
|
||||
🌐 웹 인터페이스: http://your-nas-ip:24100
|
||||
📧 관리자 이메일: admin@document-server.local
|
||||
🔑 관리자 비밀번호: (설정 시 표시된 비밀번호)
|
||||
```
|
||||
|
||||
### 주요 기능 테스트
|
||||
1. **할일관리**: `http://your-nas-ip:24100/todos.html`
|
||||
2. **메모 트리**: `http://your-nas-ip:24100/memo-tree.html`
|
||||
3. **노트북**: `http://your-nas-ip:24100/notebooks.html`
|
||||
4. **문서 업로드**: 메인 페이지에서 HTML 파일 드래그&드롭
|
||||
|
||||
## 🔄 안전한 업데이트 방법
|
||||
|
||||
### ⚠️ 업데이트 전 필수 체크리스트
|
||||
```bash
|
||||
# 1. 현재 서비스 상태 확인
|
||||
docker-compose ps
|
||||
./scripts/monitor-synology.sh
|
||||
|
||||
# 2. 전체 백업 실행 (필수!)
|
||||
./scripts/backup.sh
|
||||
|
||||
# 3. 백업 파일 확인
|
||||
ls -la /volume2/document-storage/backups/
|
||||
|
||||
# 4. 사용자 알림 (서비스 중단 예고)
|
||||
echo "⚠️ 시스템 업데이트 예정 - 잠시 중단될 수 있습니다"
|
||||
```
|
||||
|
||||
### Git 사용 (권장) - 데이터 보호 포함
|
||||
```bash
|
||||
# NAS 또는 Mac Mini에 SSH 접속
|
||||
ssh admin@your-server-ip
|
||||
cd /volume1/docker/document-server # 또는 실제 설치 경로
|
||||
|
||||
# ⚠️ 중요: 자동 업데이트 스크립트는 백업을 포함합니다
|
||||
# 백업 + 업데이트 + 헬스체크 + 롤백 기능
|
||||
./scripts/update-synology.sh
|
||||
```
|
||||
|
||||
### 수동 업데이트 (고급 사용자용)
|
||||
```bash
|
||||
# 1. 필수 백업 실행
|
||||
./scripts/backup.sh
|
||||
|
||||
# 2. 로컬 변경사항 보존
|
||||
git stash # 설정 파일 등 로컬 변경사항 임시 저장
|
||||
|
||||
# 3. 코드 업데이트 (데이터 디렉토리 제외)
|
||||
git pull origin main
|
||||
|
||||
# 4. 로컬 변경사항 복원 (필요시)
|
||||
git stash pop
|
||||
|
||||
# 5. 컨테이너 재시작 (데이터 볼륨 보존)
|
||||
docker-compose -f docker-compose.synology-optimized.yml restart
|
||||
|
||||
# 6. 서비스 상태 확인
|
||||
./scripts/monitor-synology.sh
|
||||
```
|
||||
|
||||
### 🚨 데이터 보호 원칙
|
||||
- **볼륨 매핑 보존**: Docker 볼륨은 절대 삭제하지 않음
|
||||
- **백업 우선**: 모든 변경 전 반드시 백업 실행
|
||||
- **점진적 업데이트**: 한 번에 하나씩 컴포넌트 업데이트
|
||||
- **롤백 준비**: 문제 발생 시 즉시 이전 버전으로 복구
|
||||
|
||||
## 📊 모니터링
|
||||
|
||||
```bash
|
||||
# 시스템 상태 확인
|
||||
./scripts/monitor-synology.sh
|
||||
|
||||
# 실시간 모니터링 (5초 간격)
|
||||
watch -n 5 './scripts/monitor-synology.sh'
|
||||
|
||||
# 로그 확인
|
||||
docker-compose -f docker-compose.synology-optimized.yml logs -f
|
||||
```
|
||||
|
||||
## 🚨 문제 해결
|
||||
|
||||
### 포트 충돌
|
||||
```bash
|
||||
# 포트 사용 확인
|
||||
netstat -tuln | grep -E "(24100|24101|24102|24103)"
|
||||
|
||||
# 다른 포트 사용 시 .env.synology 파일 수정
|
||||
nano .env.synology
|
||||
# EXTERNAL_PORT=24200 (예시)
|
||||
```
|
||||
|
||||
### 권한 문제
|
||||
```bash
|
||||
# 디렉토리 권한 수정
|
||||
sudo chown -R 1000:1000 /volume1/docker/document-server/
|
||||
sudo chown -R 1000:1000 /volume2/document-storage/
|
||||
```
|
||||
|
||||
### 서비스 재시작
|
||||
```bash
|
||||
# 전체 재시작
|
||||
docker-compose -f docker-compose.synology-optimized.yml restart
|
||||
|
||||
# 특정 서비스만 재시작
|
||||
docker-compose -f docker-compose.synology-optimized.yml restart backend
|
||||
```
|
||||
|
||||
### 롤백 (업데이트 실패 시)
|
||||
```bash
|
||||
# 이전 버전으로 롤백
|
||||
./scripts/update-synology.sh rollback
|
||||
```
|
||||
|
||||
## 💾 백업
|
||||
|
||||
### 자동 백업 설정
|
||||
```bash
|
||||
# Synology 작업 스케줄러에서 설정
|
||||
# 제어판 > 작업 스케줄러 > 생성 > 사용자 정의 스크립트
|
||||
|
||||
# 매일 새벽 2시 백업
|
||||
0 2 * * * /volume1/docker/document-server/backup.sh
|
||||
```
|
||||
|
||||
### 수동 백업
|
||||
```bash
|
||||
# 즉시 백업 실행
|
||||
/volume1/docker/document-server/backup.sh
|
||||
|
||||
# 백업 파일 확인
|
||||
ls -la /volume2/document-storage/backups/
|
||||
```
|
||||
|
||||
## 🔒 보안 설정
|
||||
|
||||
### 방화벽 (권장)
|
||||
```bash
|
||||
# Synology 제어판 > 보안 > 방화벽
|
||||
# 규칙 추가: 포트 24100 허용
|
||||
```
|
||||
|
||||
### SSL 인증서 (외부 접속 시)
|
||||
```bash
|
||||
# Let's Encrypt 인증서 발급
|
||||
certbot certonly --webroot -w /volume2/document-storage/documents -d your-domain.com
|
||||
```
|
||||
|
||||
## 📞 도움말
|
||||
|
||||
### 로그 수집 (문제 보고 시)
|
||||
```bash
|
||||
# 시스템 리포트 생성
|
||||
./scripts/monitor-synology.sh > system-report.txt
|
||||
|
||||
# 로그 파일 위치
|
||||
/volume1/docker/document-server/logs/
|
||||
```
|
||||
|
||||
### 유용한 명령어
|
||||
```bash
|
||||
# Docker 상태 확인
|
||||
docker ps
|
||||
docker stats
|
||||
|
||||
# 디스크 사용량 확인
|
||||
df -h /volume1 /volume2
|
||||
|
||||
# 메모리 사용량 확인
|
||||
free -h
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 요약
|
||||
|
||||
1. **배포**: `./scripts/deploy-synology.sh` (한 번만)
|
||||
2. **업데이트**: `./scripts/update-synology.sh` (필요시)
|
||||
3. **모니터링**: `./scripts/monitor-synology.sh` (상태 확인)
|
||||
4. **접속**: `http://your-nas-ip:24100`
|
||||
|
||||
**🎉 이제 Document Server를 사용할 준비가 완료되었습니다!**
|
||||
Reference in New Issue
Block a user