zioinfo-mail/skills/guardia-deploy/SKILL.md

name	description
guardia-deploy	GUARDiA 프로젝트에서 SSH/SFTP 기반 에이전트리스 배포 엔진 코드를 작성하거나 수정할 때 사용하는 스킬. 다음 경우에 반드시 먼저 읽어라: - paramiko 관련 코드 작성/수정 - 롤링 배포 로직 구현 - 헬스체크 / 롤백 로직 작성 - 배포 파이프라인 API 엔드포인트 작성 - 파일 무결성(MD5/SHA-256) 검증 코드

GUARDiA 배포 엔진 스킬

핵심 원칙

1. 백업 우선: 배포 전 반드시 타임스탬프 포함 백업 (app.jar.bak_YYYYMMDD_HHMMSS)
2. 무결성 검증: SFTP 전송 후 MD5 로컬 vs 원격 비교 필수
3. 헬스체크 강제: 재기동 후 30초 이내 HTTP 200 미확인 시 즉시 롤백
4. 롤링 배포: WAS #1 완료·검증 후 WAS #2 시작 (동시 배포 금지)
5. 감사 로그: 성공/실패 모두 log_execution() 호출 필수

환경 변수

SSH_TIMEOUT = 300       # SSH 명령 실행 타임아웃 (초)
HEALTH_TIMEOUT = 30     # 헬스체크 최대 대기 (초)
HEALTH_INTERVAL = 2     # 헬스체크 폴링 간격 (초)
DISK_THRESHOLD = 90     # 배포 전 디스크 임계치 (%)
MAX_BATCH_SIZE = 50     # 티어2 병렬 배포 단위

금지 사항

• root 계정으로 SSH 접속 금지 → opsagent + sudoers 사용
• rm -rf, mkfs, format, drop table 등 Blacklist 명령 차단
• 자격증명(비밀번호) 로그 출력 금지
• 헬스체크 없이 다음 노드 진행 금지
• 라이선스 미등록/만료 상태에서 CICD 기능 실행 금지 (ENTERPRISE 에디션 전용)

코드 패턴

SSH 실행

result = executor.execute_command("sh /app/scripts/startup.sh")
if result["exit_code"] != 0:
    raise DeploymentError(f"startup 실패: {result['stderr']}")

파일 전송 + 무결성

remote_md5 = executor.upload_file(local_path, remote_path)
local_md5 = hashlib.md5(open(local_path, 'rb').read()).hexdigest()
assert local_md5 == remote_md5, "MD5 불일치"

헬스체크

deadline = time.time() + HEALTH_TIMEOUT
while time.time() < deadline:
    try:
        r = requests.get(f"http://{ip}:8080", timeout=3)
        if r.status_code == 200:
            return True
    except:
        pass
    time.sleep(HEALTH_INTERVAL)
return False  # 실패 → 즉시 rollback 트리거

에러 처리 표준

try:
    # 배포 로직
except DeploymentError as e:
    self._rollback(executor, node, backup_ts)
    log_execution(sr_id, node["ip"], "DEPLOY_FAILED", 1, str(e))
    messenger.notify_failure(sr_id, str(e))
    return False
finally:
    executor.close()

정적 vs 동적 자원 판별

STATIC_EXTENSIONS  = {".html", ".js", ".css", ".png", ".jpg", ".gif", ".svg"}
DYNAMIC_EXTENSIONS = {".class", ".jar", ".war", ".properties"}

def requires_restart(filename: str) -> bool:
    ext = Path(filename).suffix.lower()
    return ext in DYNAMIC_EXTENSIONS

라이선스 확인

CICD/배포 기능은 ENTERPRISE 에디션 전용이다. 배포 시작 전 라이선스를 검증한다:

from routers.license import get_license_status

async def verify_license_for_deploy(db):
    status = await get_license_status(db)
    if not status.get("valid"):
        raise DeploymentError(f"라이선스 오류: {status.get('message', '미등록')}")
    features = (status.get("limits") or {}).get("features", [])
    if "CICD" not in features:
        raise DeploymentError(
            f"CICD 기능은 ENTERPRISE 에디션에서만 사용 가능합니다 (현재: {status.get('edition')})"
        )