taxbaik/DEPLOYMENT_GUIDE.md

TaxBaik 배포 가이드

서버 초기 설정

1. PostgreSQL 데이터베이스 생성

ssh kjh2064@178.104.200.7

# PostgreSQL 접속
sudo -u postgres psql

# 데이터베이스 및 사용자 생성
CREATE USER taxbaik WITH PASSWORD 'secure_password_here';
CREATE DATABASE taxbaikdb OWNER taxbaik;
GRANT ALL PRIVILEGES ON DATABASE taxbaikdb TO taxbaik;
\q

2. 환경 변수 설정

Web 서비스 (/etc/systemd/system/taxbaik.service, 백엔드 전용):

[Service]
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=ASPNETCORE_URLS=http://127.0.0.1:5004
Environment=ConnectionStrings__Default=Host=localhost;Database=taxbaikdb;Username=taxbaik;Password=your_secure_password

프록시 서비스 (/etc/systemd/system/taxbaik-proxy.service, 5001 진입점):

[Service]
ExecStart=/usr/bin/dotnet TaxBaik.Proxy.dll
WorkingDirectory=/home/kjh2064/taxbaik_active
Restart=always

3. systemd 서비스 파일 설치

sudo cp deploy/taxbaik.service /etc/systemd/system/
sudo cp deploy/taxbaik-proxy.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable taxbaik
sudo systemctl enable taxbaik-proxy

4. Nginx 설정

# Nginx 도메인 기반 가상 호스트 설정 복사
sudo cp deploy/nginx-taxbaik-domains.conf /etc/nginx/sites-available/taxbaik-domains.conf

# 기존 설정(IP 기반 및 default) 활성화 해제
sudo rm -f /etc/nginx/sites-enabled/default
sudo rm -f /etc/nginx/sites-enabled/gitea-ip.conf

# 새 설정 활성화 (심링크 생성)
sudo ln -sfn /etc/nginx/sites-available/taxbaik-domains.conf /etc/nginx/sites-enabled/taxbaik-domains.conf

# 설정 문법 테스트 및 Nginx 서비스 리로드
sudo nginx -t
sudo systemctl reload nginx

배포 프로세스

Gitea Actions 준비

1. Gitea 저장소 Secrets 추가:

   • DEPLOY_USER: kjh2064
   • DEPLOY_HOST: 178.104.200.7
   • DEPLOY_SSH_KEY_B64: base64로 인코딩한 SSH 개인키
   • TAXBAIK_ADMIN_TEST_PASSWORD: 배포 검증용 관리자 비밀번호
   • Admin__PasswordResetToken: 관리자 비밀번호 재설정 API용 서버 비밀값

2. 배포 워크플로우는 자동으로 실행:

   master 브랜치 push → build → test → publish → restart → health check → Playwright
   

수동 배포는 사용하지 않습니다. deploy_gb.sh는 TAXBAIK_DEPLOY_FROM_CI=1이 없으면 즉시 종료하므로, 배포는 반드시 Gitea Actions에서만 실행됩니다.

마이그레이션 자동 실행

애플리케이션 시작시 자동으로 마이그레이션이 실행됩니다:

1. schema_migrations 테이블 생성 (없으면)
2. 실행된 마이그레이션 확인
3. 미실행 마이그레이션 순서대로 실행

로그 확인:

journalctl -u taxbaik -n 50

검증

E2E 테스트

# 공개 사이트 접근
curl -I http://178.104.200.7/taxbaik/

# 관리자 로그인 페이지
curl -I http://178.104.200.7/taxbaik/admin/login

# 로그인 API 확인
curl -X POST http://178.104.200.7/taxbaik/api/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"<TAXBAIK_ADMIN_TEST_PASSWORD>\"}"

# Playwright 브라우저 검증
npm run test:e2e

# 필요한 경우 개별 테스트 실행
npx playwright test tests/e2e/admin-login.spec.ts
npx playwright test tests/e2e/admin-smoke.spec.ts
npx playwright test tests/e2e/public-smoke.spec.ts
npx playwright test tests/e2e/blog-seo.spec.ts
npx playwright test tests/e2e/contact-submit.spec.ts

블로그 포스트 확인

# 초기 5개 포스트 확인
curl http://178.104.200.7/taxbaik/blog

# 첫 번째 포스트 상세
curl http://178.104.200.7/taxbaik/blog/accountant-mistakes-5

롤백

# 이전 버전으로 복귀
ssh kjh2064@178.104.200.7

# 이전 배포 디렉토리 확인
ls -la ~/deployments/ | grep taxbaik

# 심링크 변경 (예: 이전 버전이 taxbaik_20260626_140000)
ln -sfn ~/deployments/taxbaik_20260626_140000 ~/taxbaik_active
sudo systemctl restart taxbaik-proxy
sudo systemctl restart taxbaik

모니터링

서비스 상태 확인

ssh kjh2064@178.104.200.7

# 서비스 상태
systemctl status taxbaik taxbaik-proxy

# 포트 확인
netstat -tlnp | grep -E '5001|5004'

# 프로세스 확인
ps aux | grep TaxBaik

성능 모니터링

# Nginx 프록시 로그
tail -f /var/log/nginx/access.log | grep taxbaik

# 애플리케이션 로그
journalctl -u taxbaik -f

트러블슈팅

증상	원인	해결
404 /taxbaik	Nginx 설정 미적용	sudo nginx -t && sudo systemctl reload nginx
Blazor WebSocket 안 됨	/taxbaik location에 proxy_http_version 1.1, Upgrade, Connection \"Upgrade\" 헤더가 모두 있는지 확인
DB 연결 오류	환경 변수 미설정	systemd service 파일의 ConnectionStrings__Default 확인
503 Service Unavailable	백엔드 또는 프록시 미시작	sudo systemctl restart taxbaik-proxy taxbaik
마이그레이션 실패	DB 권한 문제	GRANT ALL PRIVILEGES ON DATABASE taxbaikdb TO taxbaik;

운영 복구 순서

ssh kjh2064@178.104.200.7
sudo cp /home/kjh2064/taxbaik.service /etc/systemd/system/taxbaik.service
sudo cp /home/kjh2064/taxbaik-proxy.service /etc/systemd/system/taxbaik-proxy.service
sudo systemctl daemon-reload
sudo systemctl restart taxbaik-proxy
sudo systemctl restart taxbaik
curl -I http://127.0.0.1:5001/taxbaik/admin/login

원라인 점검

ssh kjh2064@178.104.200.7 'systemctl status taxbaik taxbaik-proxy --no-pager --lines=3 && ss -tlnp | grep -E ":5001 |:5004 " && curl -fsSI http://127.0.0.1:5001/taxbaik/admin/login && curl -fsS http://127.0.0.1:5001/taxbaik/favicon.svg >/dev/null && curl -fsS http://127.0.0.1:5001/taxbaik/robots.txt >/dev/null'

초기 데이터

관리자 계정

• username: admin
• password: <TAXBAIK_ADMIN_TEST_PASSWORD> (운영 검증용 비밀번호, Secrets로 관리)
• 초기 로그인 후 비밀번호 즉시 변경 권장

블로그 포스트

V003 마이그레이션에서 5개 포스트 자동 생성:

1. 사업자 기장 시 자주 하는 실수 5가지
2. 부동산 양도세 계산하기
3. 프리랜서를 위한 종합소득세 신고
4. 부가가치세 간이과세 vs 일반과세
5. 가족 자산 증여세 절세 방법

차후 작업

• SSL 인증서 적용 (Let's Encrypt)
• 도메인 연결 (현재는 IP 기반)
• 관리자 인증 보안 고도화 (rate limit, 비밀번호 교체 절차)
• 블로그 포스트 수정 화면 완성
• Naver/Google Search Console 등록
• 운영 관리자 비밀번호를 초기 시드값에서 교체하고 TAXBAIK_ADMIN_TEST_PASSWORD 갱신