happybell80 68c40c0973 docs: Gmail 아이템 구현 및 Gitea Actions 트러블슈팅 문서 작성

- robeing-monitor 구현 과정
- Gitea Actions YAML 오류 해결
- heredoc 들여쓰기 이슈 정리
- 환경변수 관리 교훈

2025-08-19 10:28:57 +09:00

4.9 KiB

Raw Blame History

Gmail 아이템 구현 및 Gitea Actions 설정 트러블슈팅

날짜: 2025-08-19
작업자: happybell80 & Claude
관련 서비스: robeing-monitor, robeing-gateway, 51123/51124 서버

오전 7시 30분

Gmail 아이템 구현 계획 수립

상황: Gmail OAuth 토큰을 "아이템"으로 관리하는 시스템 구현 필요

구현 계획:

robeing-monitor(9024) - 아이템 상태 관리
robeing-gateway - API 프록시
프론트엔드 - 인벤토리 UI
skill-email - DB 기반 토큰 조회

아키텍처 결정:

프론트 → Gateway(8100) → robeing-monitor(9024)
                           ↓
                    PostgreSQL(gmail_tokens)

오전 8시 00분

테이블 생성 및 Gateway 수정

51123 서버 작업:

-- 생성된 테이블들
- robeing_stats (레벨 관리)
- gmail_tokens (is_equipped, equipped_to 컬럼 추가)
- gmail_audit_logs (감사 로그)

Gateway 수정:

# robeing-gateway/app/main.py에 추가
@app.api_route("/api/items/{path:path}", methods=["GET", "POST", "DELETE"])
async def items_proxy(...):
    monitor_url = os.getenv("MONITOR_URL", "http://192.168.219.52:9024")
    # 프록시 로직

오전 8시 30분

robeing-monitor 구현

구현 내용:

FastAPI 기반 서비스 (포트 9024)
Gmail 아이템 CRUD API
PostgreSQL 연결 (asyncpg 사용)
레벨 체크 및 장착/해제 로직

주요 API:

GET /api/items/gmail - 아이템 목록
POST /api/items/gmail/{user_id}/equip - 장착
POST /api/items/gmail/{user_id}/unequip - 해제
POST /api/items/gmail/{user_id}/reauth - 재인증
DELETE /api/items/gmail/{user_id} - 철회

오전 9시 00분

Gitea Actions 설정 오류 연쇄

1차 오류 - YAML 문법 오류 (line 87):

# ❌ 잘못된 heredoc
cat > .env << 'ENV_FILE'
SERVICE_NAME=robeing-monitor  # 들여쓰기 없음
ENV_FILE

# ✅ 수정된 heredoc
cat > .env << 'ENVFILE'
            SERVICE_NAME=robeing-monitor  # 들여쓰기 추가
            ENVFILE

원인:

heredoc 구분자에 하이픈 사용 (ENV_FILE)
heredoc 내용에 들여쓰기 없음

오전 9시 30분

브랜치 및 환경변수 이슈

문제 1 - 브랜치명:

로컬: master 브랜치 사용 중
원격: main 브랜치 기대
해결: git branch -m master main 및 Actions 파일에 둘 다 지원

문제 2 - .env 파일:

초기 계획: Actions에서 자동 생성
실제: 51124 서버에 이미 .env 존재
해결: 자동 생성 코드 제거, 서버 .env 사용

51124 서버 실제 .env 구조:

# 개별 URL 변수 사용
BRAIN_SERVICE_URL=http://localhost:8001
SKILL_EMAIL_URL=http://localhost:8501
# (ROBING_URLS, SKILL_URLS 형태 아님)

오전 10시 00분

2차 YAML 오류 (line 157)

문제: heredoc 종료 태그 들여쓰기 오류

# ❌ 잘못된 종료
            fi
            
DEPLOY_SCRIPT  # 들여쓰기 없음

# ✅ 올바른 종료
            fi
          DEPLOY_SCRIPT  # 정확한 들여쓰기

핵심 교훈: YAML heredoc 종료 태그는 시작할 때와 동일한 들여쓰기 필요

오전 10시 30분

최종 성공

완료된 작업:

✅ robeing-monitor 서비스 구현
✅ Gateway 프록시 설정
✅ Gitea Actions 파이프라인 구성
✅ 51124 서버 배포 준비

교훈

1. Gitea Actions YAML 작성 원칙

필수 사항:

runs-on: self-hosted (NOT ubuntu-latest)
SSH 포트 명시 (51124)
조직 시크릿 사용
gitea.event 문법 (NOT github.event)

heredoc 주의사항:

# 올바른 heredoc 사용법
ssh user@host << 'DELIMITER'
  명령들...
DELIMITER  # 시작과 같은 들여쓰기

2. 환경변수 관리

원칙:

서버 .env 우선 사용
Actions에서 .env 생성 지양
실제 서버 설정 확인 후 코드 작성

3. 브랜치 전략

on:
  push:
    branches:
      - main      # 우선
      - master    # fallback

4. 트러블슈팅 체크리스트

Gitea Actions 오류 시:

YAML 문법 검증: python3 -c "import yaml; yaml.safe_load(open('파일.yml'))"
heredoc 들여쓰기 확인
브랜치명 확인
runner 설정 확인 (self-hosted)
시크릿 설정 확인

5. 서비스 통합 아키텍처

51123 서버:
  - Gateway(8100) → 라우팅
  - PostgreSQL → 데이터
  
51124 서버:
  - robeing-monitor(9024) → 아이템 관리
  - 로빙들(8001, 10508, 10408)
  - 스킬들(8501, 8505, 8503)

다음 단계

51124 서버 배포 확인
프론트엔드 인벤토리 UI 개발
skill-email DB 연결 전환
전체 통합 테스트

참고 문서

/plans/250819_gmail_item_implementation_plan.md
/plans/250819_gmail_item_detailed_tasks.md
/troubleshooting/250722_happybell80_skill-email_Actions설정실패.md
/troubleshooting/250714_gitea_actions_setup.md

4.9 KiB Raw Blame History