Skip to content

운영인수인계.md

Latest commit

 

History

History
532 lines (409 loc) · 16.6 KB

운영인수인계.md

File metadata and controls

532 lines (409 loc) · 16.6 KB

SatoShop 운영 인수인계 문서

이 문서는 시스템 운영을 다른 담당자에게 인수인계하기 위해 운영자가 무엇을 먼저 이해하고 어디를 봐야 하는지 중심으로 정리한 인수인계 전용 문서입니다.

작성 기준일: 2026-03-31
코드 기준 브랜치: 현재 로컬 코드베이스

1. 운영자가 제일 먼저 알아야 할 것

서비스 성격

  • SatoShop은 Django 기반 비트코인 라이트닝 전자상거래 플랫폼입니다.
  • 단순 쇼핑몰이 아니라 아래 기능이 한 프로젝트에 함께 들어 있습니다.
    • 일반 상품 판매
    • 메뉴판 판매
    • 밋업 신청
    • 라이브 강의 신청
    • 디지털 파일 판매
    • LNURL-auth / Nostr 로그인
    • Minihome 홍보 랜딩
    • 외부 API
    • Discord 봇
    • Expert 계약/결제/문서 기능

운영 우선순위

운영자가 실제로 자주 봐야 하는 순서는 아래입니다.

  1. Render 서비스 상태와 최근 배포 성공 여부
  2. 핵심 환경 변수 누락 여부
  3. Blink 결제와 webhook 정상 동작 여부
  4. PostgreSQL 연결과 마이그레이션 상태
  5. S3 스토리지 접근 가능 여부
  6. 환율 업데이트 웹훅/외부 크론 정상 동작 여부
  7. Discord 봇과 slash command 동기화 상태

현재 배포 방식 핵심

  • 현재 Render 운영 기준의 실제 배포 진입점은 render.yaml + Dockerfile + scripts/docker-entrypoint.sh입니다.
  • build.sh는 과거 빌드 스크립트 성격이 강하고, 현재 render.yaml이 env: docker를 사용하므로 기본 배포 경로의 중심은 아닙니다.
  • 컨테이너 시작 시 아래 작업이 자동으로 실행될 수 있습니다.
    • uv run python manage.py migrate --noinput
    • uv run python manage.py collectstatic --noinput --clear
    • uv run python manage.py check --deploy 또는 생략

2. 시스템 전체 구조

런타임 구조

사용자 브라우저 / 모바일 웹
  ↓
Django 템플릿 + 정적 파일 + 일부 JSON API
  ↓
Django 앱 계층
  ├─ accounts      인증
  ├─ stores        스토어 관리
  ├─ products      일반 상품
  ├─ orders        장바구니/주문
  ├─ ln_payment    Blink 결제
  ├─ menu          메뉴판
  ├─ meetup        밋업
  ├─ lecture       라이브 강의
  ├─ file          디지털 파일
  ├─ api           외부 API
  ├─ minihome      랜딩/도메인 매핑
  ├─ satoshop_bot  Discord
  ├─ expert        계약/문서/채팅
  ├─ storage       오브젝트 스토리지
  ├─ boards        공지/커뮤니티
  └─ myshop        홈/환율/사이트 설정
  ↓
PostgreSQL / S3 호환 스토리지 / 외부 API

요청 흐름 핵심

  • 메인 라우팅: satoshop/urls.py
  • 설정 진입점: satoshop/settings.py
  • ASGI/WebSocket 진입점: satoshop/asgi.py
  • Render 컨테이너 진입점: scripts/docker-entrypoint.sh

앱별 역할 요약

앱 운영 관점 핵심 역할
accounts 일반 로그인, 라이트닝 로그인, Nostr 로그인, 계정 연결
stores 스토어 생성/관리, BAH 홍보 요청
products 일반 상품 판매
orders 장바구니, 주문, 배송, 인보이스
ln_payment Blink 결제, 단계 로그, webhook
menu 메뉴판 판매
meetup 오프라인 모임 신청/체크인
lecture 라이브 강의 신청/참가자 관리
file 디지털 파일 판매/다운로드
minihome 랜딩 페이지, 도메인 매핑
api 외부 API, API 키/Nostr 인증
satoshop_bot Discord 인터랙션, slash command
expert 계약/결제/PDF/실시간 채팅
storage S3 파일 저장, 임시 업로드, 미디어 프록시
myshop 홈, 환율, 사이트 전역 설정, PWA
boards 공지, 댓글, 밈, 명예의 전당

3. 운영자가 먼저 읽어야 할 파일

최우선

  • render.yaml
    • Render에 어떤 서비스와 DB가 붙는지 확인
  • Dockerfile
    • 실제 이미지 빌드 방식 확인
  • scripts/docker-entrypoint.sh
    • 시작 시 migrate/collectstatic/check가 자동 실행되는지 확인
  • satoshop/settings.py
    • 환경 변수, DB, S3, LNURL, 채널 레이어, 보안 설정 확인
  • satoshop/urls.py
    • 주요 엔드포인트 라우팅 확인

기능 운영

  • ln_payment/views.py
    • Blink webhook 처리
  • ln_payment/services.py
    • 5단계 결제 플로우 로직
  • minihome/middleware.py
    • Minihome 도메인 라우팅
  • api/authentication.py
    • 외부 API 인증 로직
  • storage/backends.py
    • S3 백엔드 동작

운영 스크립트

  • scripts/CRON_EXCHANGE_RATE_SETUP.md
    • 외부 크론 환율 업데이트 운영 방식
  • scripts/exchange_rate_updater.py
    • 외부 서버가 실제로 호출하는 웹훅 업데이터
  • scripts/manage_webhook_token.sh
    • 환율 웹훅 토큰 조회/테스트
  • scripts/render_setup_signer.sh
    • Expert 서명용 인증서 복원

4. 외부 연동 구조

4-1. Blink 결제

연동 목적:

  • 상품/메뉴/밋업/강의/디지털 파일 결제
  • Expert 결제 위젯

관련 코드:

  • ln_payment/
  • expert/payment_service.py

운영 체크포인트:

  • 스토어별 Blink API 키/월렛 ID가 정상 저장되어 있는지
  • Blink webhook이 /ln_payment/webhook/blink/로 유입되는지
  • 결제 실패 시 PaymentTransaction과 단계 로그가 남는지

주의:

  • 코드상 BLINK_WEBHOOK_SECRET을 사용해 webhook 검증이 가능함
  • 하지만 현재 render.yaml에는 이 변수가 기본 선언되어 있지 않음
  • 따라서 운영 Render 환경에 이 값을 수동으로 넣었는지 반드시 확인해야 함

4-2. Upbit 환율 + 외부 웹훅

연동 목적:

  • BTC/KRW 환율 저장
  • 스토어 가격 환산
  • 홈 화면 지표 표시

관련 코드:

  • myshop/management/commands/update_exchange_rate.py
  • myshop/views.py의 /webhook/update-exchange-rate/
  • scripts/exchange_rate_updater.py

운영 방식:

  • 애플리케이션 내부 스케줄러보다 외부 서버의 crontab + 웹훅 호출을 중심으로 운용
  • 웹훅 인증은 WEBHOOK_TOKEN 환경 변수 기반
  • 이 외부 환율 갱신 시스템은 운영자 자체 서버에 별도로 구축해 사용 중인 구조다
  • 따라서 Render 애플리케이션만 인수인계하면 운영이 완결되지 않으며, 외부 서버의 crontab, updater 스크립트, 토큰 관리까지 함께 넘겨야 한다

운영 체크포인트:

  • WEBHOOK_TOKEN이 Render에 설정되어 있는지
  • 외부 크론 서버에 같은 토큰이 설정되어 있는지
  • 최근 환율 데이터가 DB에 계속 쌓이는지

4-3. S3 호환 오브젝트 스토리지

연동 목적:

  • 스토어 이미지
  • 상품 이미지
  • 미니홈 이미지
  • 첨부 파일
  • 디지털 파일

관련 코드:

  • storage/backends.py
  • storage/models.py

운영 체크포인트:

  • S3_ACCESS_KEY_ID
  • S3_SECRET_ACCESS_KEY
  • S3_BUCKET_NAME
  • S3_ENDPOINT_URL
  • S3_REGION_NAME
  • S3_CUSTOM_DOMAIN

특징:

  • 필수 S3 값이 모두 없으면 로컬 파일 저장소로 폴백
  • 운영 환경에서는 사실상 S3 정상 연결이 전제라고 보는 편이 맞음
  • 현재 사용 중인 S3 호환 오브젝트 스토리지는 iwinv 기반이다
  • 운영 이관 후 다른 오브젝트 스토리지로 전환해야 할 가능성이 있다
  • 이 경우 기존에 이미 서비스 중인 정적 이미지와 업로드 자산은 최대한 유지하고, 신규 업로드부터 새 스토리지로 단계 전환하는 전략을 우선 검토하는 편이 안전하다
  • 기존 자산 URL이 이미 노출되어 있을 수 있으므로, 이관 전에는 S3_CUSTOM_DOMAIN, 버킷 경로, 미디어 URL 호환성부터 먼저 검토해야 한다

4-4. Gmail SMTP

연동 목적:

  • 스토어 메일
  • 송장 안내 메일
  • 기타 운영 메일

관련 설정:

  • EMAIL_HOST_USER
  • EMAIL_HOST_PASSWORD
  • DEFAULT_FROM_EMAIL

4-5. Discord

연동 목적:

  • BAH 홍보 요청 알림
  • 슬래시 명령어 운영

관련 코드:

  • satoshop_bot/
  • satoshop_bot/management/commands/sync_discord_commands.py

운영 체크포인트:

  • Admin에 활성 DiscordBot이 있는지
  • application_id, token, 인터랙션 공개키가 정상인지
  • 길드 명령어 동기화가 필요한 시점에 수동 sync를 실행했는지

4-6. LNURL-auth / Nostr

연동 목적:

  • 사용자 로그인
  • API Nostr 인증

관련 코드:

  • accounts/
  • api/nostr_auth.py
  • api/authentication.py

운영 체크포인트:

  • LNURL_AUTH_ROOT_DOMAIN이 실제 서비스 도메인과 맞는지
  • Nostr 로그인 장애 시 모바일 복귀 세션과 캐시 동작을 함께 점검해야 함

5. Render 운영 방식

현재 Render 구성

render.yaml 기준:

  • Web Service: satoshop-django
  • Environment: Docker
  • Plan: starter
  • Region: singapore
  • Branch: main
  • Auto Deploy: true
  • DB: satoshop-postgres

Render 배포 흐름

  1. main 브랜치에 변경 반영
  2. Render가 Docker 이미지 빌드
  3. 컨테이너 시작 시 scripts/docker-entrypoint.sh 실행
  4. 환경 변수에 따라 migrate / collectstatic / deploy check 수행
  5. Gunicorn으로 서비스 시작

Render에서 반드시 확인할 것

1. 서비스

  • 최근 배포 성공 여부
  • Health check 통과 여부
  • 로그에 migration 실패가 없는지
  • collectstatic 실패가 없는지

2. 환경 변수

최소 필수:

  • SECRET_KEY
  • DEBUG=False
  • ALLOWED_HOSTS
  • DB_NAME
  • DB_USER
  • DB_PASSWORD
  • DB_HOST
  • DB_PORT

기능별 중요 변수:

  • BLINK_API_KEY
  • BLINK_WALLET_ID
  • EXPERT_BLINK_API_KEY
  • EXPERT_BLINK_WALLET_ID
  • EXPERT_SIGNER_CERT_BASE64
  • EXPERT_SIGNER_CERT_PASSWORD
  • S3_ACCESS_KEY_ID
  • S3_SECRET_ACCESS_KEY
  • S3_BUCKET_NAME
  • S3_ENDPOINT_URL
  • S3_REGION_NAME
  • S3_CUSTOM_DOMAIN
  • LNURL_AUTH_ROOT_DOMAIN
  • HOTLINK_PROTECTION_ENABLED
  • HOTLINK_ALLOWED_DOMAINS
  • WEBHOOK_TOKEN

운영 권장 추가 점검:

  • BLINK_WEBHOOK_SECRET
  • MINIHOME_LIST_DOMAIN
  • CSRF_TRUSTED_ORIGINS

3. DB

  • Render Postgres 연결 상태
  • 최근 migration 후 schema mismatch가 없는지
  • 주문/결제 데이터가 계속 적재되는지

Render 운영 팁

  • 현재 render.yaml에는 RUN_SYSTEM_CHECK=false로 들어가 있음
  • 배포 직전 강한 점검이 필요하면 일시적으로 true로 올리고 배포 로그를 보는 방식이 가능
  • EXPERT_SIGNER_CERT_BASE64를 사용하는 경우 scripts/render_setup_signer.sh가 런타임에서 파일로 복원함
  • Render는 Docker 배포라서 로컬 build.sh를 기준으로 이해하면 오해할 수 있음

6. 코드 구조 인수인계 포인트

설정

  • satoshop/settings.py
    • 환경 변수 로드 규칙
    • DB 연결
    • S3 연결
    • 보안 헤더
    • Channels 설정

핵심 포인트:

  • 로컬은 .env.local 우선
  • 클라우드(Render/Railway/Heroku)에서는 .env 파일을 읽지 않고 환경 변수 메뉴를 전제로 함

라우팅

  • satoshop/urls.py
    • 모든 앱 엔트리포인트
    • sw.js, manifest.json
    • media/ 프록시 라우팅

실시간

  • satoshop/asgi.py
  • expert/routing.py

핵심 포인트:

  • WebSocket은 현재 Expert 계약 채팅 한 군데가 핵심
  • 설정에는 Redis 채널 레이어 분기가 있으나 현재 잠금 의존성에는 channels-redis가 없음
  • 따라서 기본 이해는 “현재는 인메모리 레이어 기준”으로 하면 됨

결제

  • ln_payment/services.py
  • ln_payment/views.py

핵심 포인트:

  • 결제는 5단계 상태 전환으로 관리됨
  • 운영 장애 시 PaymentTransaction과 stage log를 먼저 보는 구조

Minihome 도메인

  • minihome/middleware.py

핵심 포인트:

  • 특정 도메인을 Minihome 랜딩 또는 Minihome 목록으로 직접 라우팅함
  • 도메인 장애는 일반 URL 문제가 아니라 middleware 라우팅 이슈일 수 있음

API 인증

  • api/authentication.py
  • api/models.py

핵심 포인트:

  • Bearer API 키와 Nostr 서명 인증이 둘 다 존재
  • 파트너 연동 장애 시 키 인증 방식부터 먼저 확인해야 함

7. 운영자가 평소에 해야 할 일

매일

  • Render 최근 배포 실패 여부 확인
  • 에러 로그 확인
  • 최근 주문/결제 정상 적재 여부 확인
  • 환율 최신 갱신 시각 확인
  • Blink webhook 관련 오류 로그 확인

매주

  • Admin에서 비정상 스토어/결제/주문 데이터 점검
  • Discord 명령어가 필요한 길드에 정상 노출되는지 확인
  • S3 업로드/다운로드 오류 로그 확인
  • Minihome 도메인 연결 상태 점검

변경 배포 전

  • 환경 변수 추가/변경 여부 확인
  • 마이그레이션 포함 여부 확인
  • collectstatic 영향 확인
  • 결제/로그인/업로드/환율 관련 코드 touched 여부 확인

8. 자주 쓰는 운영 명령

모든 Django 명령은 프로젝트 규칙상 uv run으로 실행합니다.

기본 점검

uv run python manage.py check
uv run python manage.py migrate
uv run python manage.py collectstatic --noinput

환율

uv run python manage.py update_exchange_rate --force

결제/예약 정리

uv run python manage.py expire_invoices --dry-run
uv run python manage.py cleanup_expired_reservations --dry-run

임시 업로드 정리

uv run python manage.py cleanup_temp_uploads --dry-run

Discord 명령 동기화

uv run python manage.py sync_discord_commands --all-guilds
uv run python manage.py sync_discord_commands --global-only

9. 장애가 났을 때 어디부터 볼지

결제가 안 된다

  1. 스토어 Blink 자격 정보 존재 여부 확인
  2. ln_payment 로그 확인
  3. Blink webhook 유입 여부 확인
  4. PaymentTransaction과 단계 로그 확인
  5. 주문 생성 직전에서 멈췄는지 확인

로그인 장애

  1. 일반 로그인인지, LNURL인지, Nostr인지 구분
  2. accounts 관련 로그 확인
  3. 도메인/LNURL 설정값 확인
  4. Nostr의 경우 pending session / callback 복구 흐름 점검

이미지/파일 업로드 장애

  1. S3 환경 변수 확인
  2. storage/backends.py 관련 로그 확인
  3. 특정 파일만 실패하는지 전체 실패인지 구분
  4. S3_CUSTOM_DOMAIN와 실제 버킷 접근 정책 확인

Minihome 도메인 장애

  1. DNS/도메인 연결 확인
  2. MINIHOME_LIST_DOMAIN 값 확인
  3. minihome.middleware.MinihomeDomainMiddleware 기준 라우팅 점검

환율이 안 갱신된다

  1. Render의 WEBHOOK_TOKEN 확인
  2. 외부 크론 서버 토큰 일치 여부 확인
  3. /webhook/update-exchange-rate/ 수동 호출 테스트
  4. update_exchange_rate --force 수동 실행 가능 여부 확인

10. 현재 운영 리스크 메모

  • render.yaml에는 BLINK_WEBHOOK_SECRET가 기본 선언되어 있지 않음
    • 운영 환경에서 수동으로 넣지 않았으면 webhook 검증이 비활성 또는 느슨해질 수 있음
  • 설정에는 Redis 채널 레이어 분기가 있으나 channels-redis는 현재 잠금 의존성에 없음
    • WebSocket 확장을 본격 운영하려면 의존성 추가 여부를 먼저 판단해야 함
  • 환율 갱신은 애플리케이션 내부 스케줄러보다 외부 크론/웹훅 의존도가 높음
    • 현재는 운영자 자체 서버에 구축한 외부 시스템이 실제 갱신을 담당하므로, 외부 서버 운영 인계가 함께 이뤄져야 안정적임
  • 현재 S3 호환 오브젝트 스토리지는 iwinv 기반임
    • 스토리지 이관이 필요해질 경우 기존 정적 이미지/기존 업로드 자산을 유지한 채 신규 업로드부터 단계 전환하는 방식이 더 안전할 수 있음
  • 기능 범위가 넓어서 장애 원인이 앱별로 크게 다름
    • 결제, 로그인, 스토리지, Minihome 도메인, Discord는 서로 다른 축으로 봐야 함

11. 인수인계 직후 추천 점검 순서

  1. Render Dashboard 접속 권한 확인
  2. Render 환경 변수 전체 백업
  3. PostgreSQL 접근 가능 여부 확인
  4. Admin 로그인 확인
  5. 최근 결제 1건, 최근 주문 1건, 최근 환율 1건 확인
  6. S3 업로드 가능한지 확인
  7. Discord 봇 활성 상태 확인
  8. Minihome 도메인 하나 열어보기
  9. 외부 API 문서(/api/v1/docs/) 열어보기
  10. 환율 웹훅 수동 호출 경로 확인

12. 수동 검증 방법

자동 테스트는 여기서 실행하지 않았습니다. 운영 인수인계 문서를 검증하려면 아래 순서로 수동 확인하면 됩니다.

  1. uv sync
  2. docker compose up -d postgres
  3. .env.local 작성
  4. uv run python manage.py migrate
  5. uv run python manage.py runserver
  6. /admin/, /api/v1/docs/, /expert/, /minihome/ 접근 확인
  7. Blink 설정 후 인보이스 생성까지 확인
  8. S3 설정 후 이미지 업로드 확인