hyungi/tk-factory-services
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d827f22f4df1c910287198154c8ddb3e184ef35f
tk-factory-services/DEPLOY-GUIDE.md
Hyungi Ahn d827f22f4d feat: tkreport/tkqc UX 개선 - 신고 완료 모달, 크로스시스템 배너, AI 도우미 가시성 
- 신고 제출 후 alert → 성공 모달로 교체 (신고현황/새신고 버튼)
- cross-nav.js: tkreport 페이지 상단 크로스시스템 네비게이션 배너
- report-status.html: AI 신고 도우미 버튼 추가
- common-header.js: tkqc 헤더에 "신고" 외부 링크 추가
- 배포 스크립트/가이드 추가

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-12 08:00:14 +09:00

317 lines
9.6 KiB
Markdown
Raw Blame History

# TK Factory Services - NAS 배포 가이드
> 최종 업데이트: 2026-03-12
## 아키텍처 개요
```
Cloudflare Tunnel
|
+--------------+--------------+
| | |
tkfb.techni.. tkreport.techni.. tkqc.techni..
| | |
tk-gateway:80 tk-system2-web:80 tk-system3-web:80
(포털+S1) (S2 신고) (S3 부적합)
| | |
system1-api:3005 system2-api:3005 system3-api:8000
| | |
+--- MariaDB --+ PostgreSQL
(공유)
```
### 서브도메인 라우팅
| 서브도메인 | Cloudflare Tunnel 대상 | 역할 |
|-----------|----------------------|------|
| `tkfb.technicalkorea.net` | `http://tk-gateway:80` | 통합 포털 + System 1 (공장관리) |
| `tkreport.technicalkorea.net` | `http://tk-system2-web:80` | System 2 (신고) |
| `tkqc.technicalkorea.net` | `http://tk-system3-web:80` | System 3 (부적합관리) |
### SSO 인증 방식
- 로그인: `tkfb.technicalkorea.net/login`에서 통합 로그인
- 토큰 저장: 쿠키 (`domain=.technicalkorea.net`, 7일 만료) + localStorage 이중 저장
- 시스템 간 이동: 쿠키가 서브도메인 간 자동 공유되므로 재로그인 불필요
### Docker 서비스 (13개)
| 서비스 | 컨테이너명 | 포트 |
|--------|-----------|------|
| MariaDB | tk-mariadb | 30306:3306 |
| PostgreSQL | tk-postgres | 30432:5432 |
| Redis | tk-redis | - |
| SSO Auth | tk-sso-auth | 30050:3000 |
| System 1 API | tk-system1-api | 30005:3005 |
| System 1 Web | tk-system1-web | 30080:80 |
| System 1 FastAPI | tk-system1-fastapi | 30008:8000 |
| System 2 API | tk-system2-api | 30105:3005 |
| System 2 Web | tk-system2-web | 30180:80 |
| System 3 API | tk-system3-api | 30200:8000 |
| System 3 Web | tk-system3-web | 30280:80 |
| phpMyAdmin | tk-phpmyadmin | 30880:80 |
| Cloudflared | tk-cloudflared | - |
| Gateway | tk-gateway | 30000:80 |
---
## 배포 전 준비 (로컬)
### 1. .env 파일 생성
```bash
cp .env.example .env
vi .env
```
필수 설정값:
```
# NAS 기존 TK-FB의 DB 패스워드와 동일하게 설정
MYSQL_ROOT_PASSWORD=<기존 tkfb_db root 패스워드>
MYSQL_PASSWORD=<기존 tkfb_db hyungi_user 패스워드>
# 새로 생성할 SSO 시크릿 (32자 이상 랜덤 문자열)
SSO_JWT_SECRET=<openssl rand -hex 32 로 생성>
SSO_JWT_REFRESH_SECRET=<openssl rand -hex 32 로 생성>
# NAS 기존 TKQC의 DB 패스워드와 동일하게 설정
POSTGRES_PASSWORD=<기존 tkqc-db mproject 패스워드>
# System 3 관리자 (기존 TKQC 관리자)
SYSTEM3_ADMIN_USERNAME=hyungi
SYSTEM3_ADMIN_PASSWORD=<기존 TKQC 관리자 비밀번호>
# Cloudflare Tunnel 토큰
CLOUDFLARE_TUNNEL_TOKEN=<Cloudflare Zero Trust 대시보드에서 확인>
```
기존 패스워드 확인 방법 (NAS SSH):
```bash
# TK-FB MariaDB 패스워드
cat "/volume1/Technicalkorea Document/tkfb-package/.env" | grep MYSQL
# TKQC PostgreSQL 패스워드
cat /volume1/docker/tkqc/tkqc-package/.env | grep POSTGRES
# Cloudflare Tunnel 토큰
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker inspect tkfb_cloudflared | grep TUNNEL_TOKEN
```
---
## NAS 배포 절차
### Step 1: 기존 서비스 백업
```bash
# NAS SSH 접속
ssh hyungi@192.168.0.3
# 백업 디렉토리 생성
mkdir -p /volume1/docker/backups/$(date +%Y%m%d)
# MariaDB 백업
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker exec tkfb_db \
mysqldump -u root -p<ROOT_PASSWORD> --all-databases > \
/volume1/docker/backups/$(date +%Y%m%d)/mariadb-all.sql
# PostgreSQL 백업
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker exec tkqc-db \
pg_dumpall -U mproject > \
/volume1/docker/backups/$(date +%Y%m%d)/postgres-all.sql
# uploads 백업
cp -r "/volume1/Technicalkorea Document/tkfb-package/uploads" \
/volume1/docker/backups/$(date +%Y%m%d)/tkfb-uploads
cp -r /volume1/docker/tkqc/tkqc-package/uploads \
/volume1/docker/backups/$(date +%Y%m%d)/tkqc-uploads
```
### Step 2: 프로젝트 NAS 전송 (git 기반)
NAS에 git이 설치되어 있으므로, Gitea에서 직접 clone/pull 합니다.
**최초 설정 (1회):**
```bash
# NAS SSH 접속
ssh hyungi@192.168.0.3
# git credential 저장 설정
git config --global credential.helper store
# 기존 배포 디렉토리 백업 후 clone
cd /volume1/docker_1/
mv tk-factory-services tk-factory-services.bak
git clone https://git.hyungi.net/hyungi/tk-factory-services.git
# 기존 .env 복원
cp tk-factory-services.bak/.env tk-factory-services/.env
# 확인 후 백업 삭제
cd tk-factory-services && git log -1
rm -rf ../tk-factory-services.bak
```
**이후 배포 (맥북에서 원커맨드):**
```bash
# 맥북에서 실행 - 자동으로 push 확인, NAS 비교, 빌드, health check 수행
./scripts/deploy-remote.sh
```
> **참고**: 설정 파일 `~/.tk-deploy-config` 필요 (아래 "원격 배포 스크립트" 섹션 참고)
### Step 3: 기존 서비스 중지
```bash
# NAS SSH
# TK-FB 중지
cd "/volume1/Technicalkorea Document/tkfb-package"
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker compose down
# TKQC 중지
cd /volume1/docker/tkqc/tkqc-package
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker compose down
```
### Step 4: 통합 서비스 기동
```bash
cd /volume1/docker/tk-factory-services
# Docker 이미지 빌드 + 서비스 기동
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker compose up --build -d
# 로그 확인
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker compose logs -f --tail=50
```
### Step 5: DB 마이그레이션
```bash
# SSO 유저 테이블은 docker-compose.yml에 의해 자동 실행됨
# (scripts/migrate-users.sql → MariaDB init)
# PostgreSQL 마이그레이션도 자동 실행됨
# (system3-nonconformance/api/migrations/ → PostgreSQL init)
# 헬스체크 확인
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker compose ps
```
### Step 6: Cloudflare Tunnel 설정
Cloudflare Zero Trust 대시보드 (`https://one.dash.cloudflare.com/`)에서:
1. **Networks → Tunnels** → 기존 터널 선택
2. **Public Hostname** 탭에서 3개 서브도메인 설정:
| Subdomain | Domain | Service |
|-----------|--------|---------|
| tkfb | technicalkorea.net | `http://tk-gateway:80` |
| tkreport | technicalkorea.net | `http://tk-system2-web:80` |
| tkqc | technicalkorea.net | `http://tk-system3-web:80` |
> 기존 `tkfb.technicalkorea.net`과 `tkqc.technicalkorea.net`은 대상 서비스만 변경
### Step 7: 테스트
```bash
# 1. 헬스체크
curl -s http://localhost:30005/api/health # System 1 API
curl -s http://localhost:30105/api/health # System 2 API
curl -s http://localhost:30200/api/health # System 3 API
curl -s http://localhost:30050/api/health # SSO Auth
# 2. 웹 접속 테스트 (브라우저)
# - https://tkfb.technicalkorea.net/ → 포털 표시
# - https://tkfb.technicalkorea.net/login → 로그인 페이지
# - 로그인 후 → 대시보드 이동
# - https://tkreport.technicalkorea.net/ → System 2 (재로그인 없이)
# - https://tkqc.technicalkorea.net/ → System 3 (재로그인 없이)
# 3. SSO 쿠키 확인 (브라우저 개발자 도구)
# - Application → Cookies에서 sso_token, sso_user 확인
# - domain이 .technicalkorea.net인지 확인
```
---
## 원격 배포 스크립트
맥북에서 원커맨드로 배포/확인/롤백할 수 있는 스크립트입니다.
### 설정 파일
`~/.tk-deploy-config` 생성 (git 추적 안 함):
```bash
NAS_HOST=100.71.132.52
NAS_USER=hyungi
NAS_DEPLOY_PATH=/volume1/docker_1/tk-factory-services
NAS_SUDO_PASS=<sudo 비밀번호>
```
### 사용법
```bash
# 배포 (pre-flight 체크 → NAS 비교 → 빌드 → health check → 로그 기록)
./scripts/deploy-remote.sh
# 배포 상태 확인 (NAS 버전, origin 대비 차이, 컨테이너 상태)
./scripts/check-version.sh
# 특정 커밋으로 롤백
./scripts/rollback-remote.sh <commit-hash>
```
### 배포 흐름
1. 로컬에서 코드 수정 → `git commit` → `git push`
2. `./scripts/deploy-remote.sh` 실행
3. 스크립트가 자동으로: 로컬 clean 확인 → origin push 확인 → NAS 버전 비교 → 배포될 커밋 표시 → 사용자 확인 → git pull → docker build → nginx 재시작 → health check
---
## 롤백 방법
### git 기반 롤백 (권장)
```bash
# 맥북에서 실행 - 특정 커밋으로 롤백
./scripts/rollback-remote.sh <commit-hash>
# 최근 커밋 목록 확인
git log --oneline -10
```
### 레거시 서비스 복원 (통합 이전으로)
문제 발생 시 기존 개별 서비스로 복원:
```bash
# 통합 서비스 중지
cd /volume1/docker_1/tk-factory-services
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker compose down
# TK-FB 복원
cd "/volume1/Technicalkorea Document/tkfb-package"
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker compose up -d
# TKQC 복원
cd /volume1/docker/tkqc/tkqc-package
echo 'fukdon-riwbaq-fiQfy2' | sudo -S /usr/local/bin/docker compose up -d
```
---
## 트러블슈팅
| 증상 | 원인 | 해결 |
|------|------|------|
| 403 Forbidden (nginx) | Docker 내부 IP 차단 | nginx.conf에 `allow 172.16.0.0/12` 추가 |
| SSO 로그인 후 다른 시스템에서 미인증 | 쿠키 domain 설정 오류 | 브라우저 쿠키에서 domain이 `.technicalkorea.net`인지 확인 |
| DB 연결 실패 | 패스워드 불일치 | `.env`의 DB 패스워드가 기존과 동일한지 확인 |
| Cloudflare 502 | 컨테이너 미기동 | `docker compose ps`로 상태 확인, `docker compose logs <서비스>` |
| SCP 실패 | Synology subsystem | `scp -O` 옵션 사용 |
| sudo 파이프 실패 | Synology 제한 | `echo 'password' \| sudo -S` 패턴 사용 |
Reference in New Issue View Git Blame Copy Permalink