CQE 레포지토리 스크립트 관리 가이드

CQE(Custom Query Engine) 레포지토리에서 스크립트를 관리하고, 여러 서버에 등록하며, 실행 상태를 모니터링하는 방법을 안내합니다.

🤖 CQE 레포지토리 목록 페이지로 이동 →

📋 개요

CQE Repo List는 유지보수 및 진단용 스크립트를 중앙에서 관리하는 저장소입니다. 한 번 저장된 스크립트는 여러 논리 서버(LSVR)에 서로 다른 실행 파라미터로 배포하여 실행할 수 있습니다.

🔍 스크립트 상세 및 실행 설정

목록에서 스크립트를 클릭하면 상세 모달이 열리며, 다음 기능을 수행할 수 있습니다.

1. 스크립트 본문 확인

스크립트의 소스 코드를 전체 화면으로 확인합니다. (목록에서는 읽기 전용이며, 수정이 필요한 경우 편집 기능을 이용하세요.)

2. 실행 설정 (신규)

서버에 스크립트를 등록하기 전에 실행 방식을 설정할 수 있습니다.

• 활성 (Active): 선택한 서버에서 스크립트 실행을 활성화할지 여부를 결정합니다.
• 반복 (Repeat): 활성화 시 스크립트가 주기적으로 반복 실행됩니다.
• 실행 간격 (분): 반복 실행 시의 주기(분 단위)를 설정합니다.
• 시작 일시: 첫 실행이 시작될 시점을 지정합니다.

3. 서버 등록 (LSVR 큐 등록)

현재 프로젝트의 서버 중 원하는 서버를 선택하여 스크립트를 배포할 수 있습니다.

• LSVR 선택기: 체크박스를 통해 대상 서버들을 선택합니다.
• 큐 등록: 버튼을 클릭하면 정의된 설정으로 선택된 모든 서버에 스크립트가 등록됩니다.

📊 스크립트 등록 현황

모달 하단의 스크립트 등록 현황 테이블에서 현재 이 스크립트를 사용 중인 모든 서버 목록을 실시간으로 확인할 수 있습니다.

• 호스트명: 스크립트가 등록된 서버의 이름입니다.
• 용도: 해당 논리 서버의 정의된 용도입니다.
• 설정 정보: 각 서버별로 설정된 활성/반복/간격 상태를 보여줍니다.
• 마지막 실행: 해당 서버에서 스크립트가 마지막으로 실행된 시각을 추적합니다.

API 참조

이 기능의 API 상세 사양은 별도 가이드를 참조하세요.

📘 시스템 관리 API 레퍼런스

문제 해결

증상	원인	해결
큐 등록 후에도 스크립트가 실행되지 않음	실행 설정에서 활성(Active) 이 꺼져 있음	상세 모달에서 Active를 켠 뒤 다시 큐에 등록합니다.
LSVR 선택기에 대상 서버가 보이지 않음	현재 선택된 프로젝트에 서버가 없거나 서버가 다른 프로젝트에 속함	상단에서 올바른 프로젝트를 선택했는지 확인합니다.
반복 실행이 동작하지 않음	반복(Repeat) 은 켰지만 실행 간격(분) 이 비어 있음	실행 간격을 1 이상으로 설정한 뒤 다시 등록합니다.
등록 현황의 마지막 실행 이 갱신되지 않음	대상 서버의 에이전트가 아직 큐를 수신하지 못함	에이전트 연결 상태와 시작 일시가 과거 시각인지 확인합니다.

🔌 CQE API (자동화용)

위 UI 동작은 다음 CQE API 버브(byAK/bySk 디스패처)에 대응합니다. 요청은 text(버브+파라미터 이름), jsondata(값), token을 보냅니다.

• CQERepoPut msName msDetail msBody msPer msPrice msType — 스크립트를 repo에 등록.

  • text 에는 파라미터 이름만 담습니다: CQERepoPut msName msDetail msBody msPer msPrice msType
  • jsondata 에 실제 값을 담습니다: {"msName":"...","msDetail":"...","msBody":"#!/bin/sh\n...","msPer":0,"msPrice":0,"msType":"sh"}
  • msType 은 5자 이내입니다(varchar(5)). powershell·expect·cmdwin 같은 긴 이름은 저장되지 않으니 아래 표의 짧은 코드를 씁니다.

  msType	실행 대상 OS	에이전트가 실제로 실행하는 방법
  ps1	Windows	powershell.exe (창 없이)
  cmd	Windows	cmd.exe
  bat	Windows	cmd 로 정규화된 뒤 cmd.exe
  wsf	Windows	wscript.exe //B //Nologo
  ps1ui / cmdui	Windows	데스크톱 세션에서 창을 띄워 실행
  sh	Linux	sh <임시파일>
  py	Linux	python3 <임시파일>
  ps1	Linux	pwsh <임시파일>

  OS 를 섞지 마세요. Windows 에이전트는 위 Windows 타입만 실행하고 그 밖의 값은 unsupported_script_type 오류로 기록만 하고 실행하지 않습니다. Linux 에이전트는 반대로 모르는 타입을 전부 sh 로 실행합니다 — bat/wsf 스크립트를 Linux 서버에 할당하면 조용히 sh 로 돌아가 깨집니다. 할당할 서버의 OS 에 맞는 타입으로 등록하세요.

  • Linux 셸 스크립트 등록: msType 에 sh, msBody 에 셸 스크립트 전문을 넣습니다. Linux 에이전트는 받은 본문을 임시 파일로 저장한 뒤 sh 로 실행하므로 #!/bin/bash 셰뱅은 무시됩니다. bash 전용 문법([[ ]], 배열 등)은 쓰지 말고 POSIX 셸로 작성하거나, 본문 첫 줄에서 exec bash "$0" "$@" 로 bash 에 넘기세요.

    #!/bin/sh
    # sh 로 실행되므로 POSIX 문법만 씁니다. sk/lssn/apiaddrv2 는 환경변수로 들어옵니다.
    curl -s -H "Authorization: Bearer $sk" "$apiaddrv2/health" | jq -r .status

  • 스크립트 본문을 어디에 둘지: 두 방식 모두 동작합니다.

    • 본문 전체를 msBody 에 넣기 — 호스트에 파일을 미리 깔지 않아도 되고 giip 쪽 변경만으로 전체 서버에 배포됩니다. 권장합니다.
    • 호스트에 둔 스크립트를 호출만 하기 — 호스트에 jq·curl 등 전제가 있거나 본문이 아주 길 때 씁니다. 대신 호스트별 배포 상태를 따로 관리해야 합니다.
    • msBody 는 ntext 라 실용적인 길이 제한이 없습니다(실측 최대 20,883자).

• CQEQueuePut mssn lssngroup csn interval active script_type custom_values repeat startdate auid — 서버에 스크립트 할당.

  • lssngroup: 콤마 구분 LSSN 목록(서버마다 1건 할당).
  • interval: 분. repeat: 0/1 = 일회성, 2 = 재귀(interval마다 반복).
  • custom_values: 서버별 주입값 → 스크립트 본문의 {{CustomVariables}}로 치환.

• CQEQueueGet lssn hostname os op — 에이전트가 폴링해 다음 스크립트 본문을 수신.

스크립트 본문 치환자: {{CustomVariables}}(할당별 custom_values, 서버측 주입), {{sk}}(에이전트 토큰), {{lssn}}(에이전트 LSSN).

Linux 에이전트는 sk, lssn, apiaddrv2 를 환경변수로도 export 합니다. {{sk}}/{{lssn}} 치환자 대신 스크립트에서 $sk·$lssn·$apiaddrv2 를 그대로 써도 됩니다.

실행 제한

구분	Windows 에이전트	Linux 에이전트
실행 시간 제한	기본 600초. giipAgent.cfg 의 cqetimeoutsec 로 변경합니다. 초과하면 강제 종료됩니다	제한 없습니다
실행 방식	임시 파일을 만들어 창 없이 실행	임시 파일을 만들어 sh 로 실행
본문 길이	제한 없음(ntext)	같음

실행 간격: interval 은 분 단위입니다. 실제 재실행 주기는 에이전트 폴링 주기에 좌우됩니다 — interval=0 은 "주기 없음" 이 아니라 폴링 로테이션마다 재배급 입니다. 활성 큐가 여러 건이면 로테이션으로 돌아가므로 큐가 N건일 때 체감 주기가 약 N배로 늘어납니다(giipdb docs/30_Specs/SPEC_AND_CHECKLIST.md 실측). 간격을 1분으로 둬도 폴링보다 자주 실행되지는 않습니다.

실행 결과 저장: 스크립트의 표준출력·표준오류는 에이전트가 돌아가는 서버의 로컬 로그 파일에 쌓입니다. giip 쪽으로는 요약만 올라갑니다 — KVSPut(kType=lssn, kKey=<lssn>, kFactor=giipagent) 로 event_type="script_execution" 레코드가 만들어지고 그 안에 script_type, exit_code, execution_time_seconds, mslsn, mssn 이 담깁니다. 출력 본문 자체는 giip 에 저장되지 않습니다. 출력을 giip 에서 보려면 스크립트가 직접 KVSPut 으로 올려야 합니다(보존 기간은 그 KVS 설정을 따릅니다).

실패 알림: 자동 알림 기능은 없습니다. exit_code 가 0이 아닌 script_execution 레코드를 조회해 감지하거나, 스크립트 안에서 직접 알림을 보내도록 만드세요.

전체 사양: giipdb docs/30_Specs/CQE_SPECIFICATION.md.

---

버전: 1.3 최종 업데이트: 2026-10-19 소스 파일: giipv3/public/help/cqerepolist.ko.md