CQELSVR 실행 목록 가이드
특정 논리 서버(LSSN)에 등록된 CQE(Custom Query Engine) 스크립트 실행 스케줄을 조회하고, 강제 실행·활성화 전환·삭제·스크립트 확인까지 처리하는 방법을 안내합니다.
📋 개요
CQELSVR 실행 목록은 하나의 논리 서버(LSSN)에 등록된 CQE 스크립트 스케줄(tMgmtScriptList)을 조회하고 직접 제어하는 화면입니다. 서버를 선택하면 해당 서버에 등록된 스케줄 목록이 표시되며, 각 행에서 강제 실행·활성화 전환·삭제·스크립트 본문 확인을 바로 수행할 수 있습니다.
🔄 전체 흐름 (CQE Flow)
flowchart TD
A[관리자: CQERepoPut<br/>스크립트를 repo에 등록] --> B[tMgmtScript<br/>스크립트 저장소]
B --> C[관리자: CQEQueuePut<br/>대상 서버에 스케줄 할당]
C --> D[tMgmtScriptList<br/>lssn별 스케줄]
D --> E[에이전트: CQEQueueGet<br/>주기적 폴링]
E --> F[tMgmtQue<br/>실행 큐에서 ms_body 수신]
F --> G[에이전트: 로컬에서<br/>스크립트 실행]
G --> H[KVSPut<br/>결과 보고]
style A fill:#e1f5fe
style B fill:#b3e5fc
style C fill:#e1f5fe
style D fill:#b3e5fc
style E fill:#e8f5e9
style F fill:#c8e6c9
style G fill:#fff9c4
style H fill:#ffccbc🔍 화면 구성
1. 서버 선택
- LSSN 입력: 상단 입력창에 논리 서버 ID(LSSN)를 직접 입력합니다.
- 서버 선택 버튼: 클릭하면 현재 프로젝트(csn)에 등록된 서버 목록이 팝업으로 표시됩니다. 원하는 서버를 선택하면 LSSN 필드에 자동 입력됩니다.
- 세션 기억: 한 번 선택한 LSSN은 브라우저 sessionStorage에 저장되어 새로고침 후에도 유지됩니다.
2. 실행 목록 조회
- Run 버튼: LSSN을 입력하거나 선택한 후 클릭하면 해당 서버의 스케줄 목록이 하단에 표시됩니다.
- 페이지 이동: Prev / Next 버튼으로 페이지 단위로 이동합니다. Offset 입력창에 숫자를 직접 입력하고 Run을 눌러 특정 오프셋으로 이동할 수도 있습니다. (서버는 한 번에 최대 25건을 반환합니다.)
3. 행별 동작
목록의 각 행(스케줄 = mslsn 1건)에서 다음을 수행할 수 있습니다.
- 강제 실행: 스케줄 주기와 무관하게 즉시 1회 실행 큐에 넣습니다. 이미 대기 중인 큐가 있으면 실패합니다.
- 이 동작의 실체는
tMgmtQue테이블에 실행건 1건을 넣는 것입니다. 에이전트는 이 큐를 폴링해서 가져갑니다. - 1회성(
repeat=1) 스케줄이라면 강제 실행 시active가 0으로 내려갑니다. 이는 "이 스케줄을 다음 주기에 다시 자동 등록하지 말라"는 뜻일 뿐이며, 이미 큐에 들어간 실행건은 그대로 정상 실행됩니다.active=0을 보고 실행이 취소된 것으로 오해하지 마세요.
- 이 동작의 실체는
- 활성화 전환: 해당 스케줄의 활성(Active) 상태를 켜기/끄기로 토글합니다.
- 삭제: 해당 스케줄(
mslsn)을 목록에서 영구히 제거합니다(단순 취소가 아니라 재등록이 필요한 삭제입니다). - 스크립트 보기: 행의 실행 ID(mssn)를 클릭하면 해당 스크립트의 본문이 하단(또는 팝업) 패널에 표시됩니다.
4. 상세 페이지 이동
- Machine Detail 버튼: 선택된 LSSN의 상세 페이지(
/lsvrdetail)로 이동합니다. - Add Queue 버튼:
/ko/cqeQueuePut페이지로 이동하여 이 서버에 새 스케줄을 등록할 수 있습니다. 시작일시의 타임존 규약은 CQE 큐 등록 가이드를 참조하세요.
📊 목록 열 설명
| 열 | 설명 |
|---|---|
| msName | 등록된 스크립트 이름 |
| mssn | 스크립트 고유 ID. 클릭하면 스크립트 본문이 표시됩니다. |
| mslsn | 이 스케줄(서버-스크립트 할당) 고유 ID. 강제 실행/활성화 전환/삭제 대상입니다. |
| lssn | 이 스케줄이 등록된 논리 서버 ID |
| active | 주기 스케줄의 자동 재등록 여부(1=켜짐/0=꺼짐). 이 값이 0이어도 이미 큐에 들어간 실행건의 실행 여부와는 무관합니다. 1회성(repeat=1) 스케줄은 강제 실행 시 이 값이 0으로 내려가는 것이 정상입니다. |
| repeat | 반복 실행 여부/방식(1=1회성) |
| interval | 반복 주기(분) |
| q_flag | 실행 큐 대기중 표시(1=tMgmtQue에 대기중). 에이전트가 큐를 가져가면 0으로 돌아갑니다. 즉 q_flag=1은 "아직 안 가져감", 0은 "가져갔거나 대기건 없음"입니다. |
| lastdate | 마지막 실행(큐 적재) 시각. UTC 기준으로 저장·표시됩니다(로컬 시각과 시차만큼 달라 보이는 것이 정상). |
| regdate | 이 스케줄이 등록된 시각 |
실행 후 상태 전이
강제 실행 또는 주기 실행으로 에이전트가 큐를 가져가면 다음과 같이 값이 바뀝니다.
| 대상 | 변화 |
|---|---|
tMgmtQue.send_flag | 1 로 전환(에이전트가 수령함) |
q_flag | 1 → 0 으로 복귀(대기건 해소) |
lastdate | 실행(큐 적재) 시각으로 갱신 |
active | 자동으로 복구되지 않습니다. |
⚠️ 1회성 스케줄을 강제 실행한 뒤에도 주기 반복을 계속하고 싶다면, 실행이 끝난 후 [활성화 전환]으로
active를 다시 켜야 합니다. 시스템이 알아서 되돌려 주지 않습니다.
⚙️ 요구사항
- **로그인 세션(CSN)**이 필요합니다. 세션이 없으면 서버 목록을 불러올 수 없습니다.
- 조회하려는 LSSN이 현재 프로젝트에 등록되어 있어야 합니다.
- 스케줄에 대한 강제 실행/활성화 전환은 해당 스케줄의 소유자이거나 별도 권한(마켓플레이스 구매 등)이 있어야 합니다.
API 참조
이 기능의 API 상세 사양은 별도 가이드를 참조하세요.
문제 해결
| 증상 | 원인 | 해결 |
|---|---|---|
| 서버 선택 팝업에 목록이 비어 있음 | 현재 선택된 프로젝트(csn)에 등록된 서버가 없음 | 상단에서 올바른 프로젝트를 선택했는지 확인합니다. |
| 강제 실행이 아무 반응 없이 실패함 | 이미 대기 중인 큐가 있거나(중복 실행 방지), 이 스케줄에 대한 권한이 없음 | 잠시 후 다시 시도하거나, 스케줄 소유자에게 확인합니다. |
| 삭제 후에도 목록에 남아 있는 것처럼 보임 | 삭제는 성공했지만 화면이 아직 새로고침되지 않음 | Run을 다시 눌러 최신 목록을 다시 조회합니다. |
| 삭제 버튼을 눌렀는데 아무 반응이 없거나 조용히 실패함(예: 다른 사람이 등록한 스케줄) | 이 스케줄의 소유자가 아니면 삭제 권한이 없음(RstVal=403) | 화면에 에러 알림이 표시됩니다(giip 3042로 개선). 알림 메시지를 확인하고, 필요하면 스케줄 소유자나 상위 권한 계정에 삭제를 요청합니다. |
| 활성화를 켰는데도 실행되지 않음 | 활성화는 예약 스케줄만 재개시키며 즉시 실행은 아님 | 즉시 실행이 필요하면 강제 실행을 사용합니다. |
| 강제실행 후 q_flag=1 인데 active=0 이라 실행 안 될 것 같다 | 1회성 스케줄은 강제실행 시 active 가 0으로 내려가는 것이 정상 | 그대로 두면 다음 에이전트 폴링에 실행된다. 이후에도 주기 반복을 원하면 [활성화 전환]으로 다시 켠다 |
| 큐가 대기중(q_flag=1)인데 몇 분이 지나도 안 가져간다 | 스케줄의 lastdate/시작일시가 미래 시각으로 저장돼 있으면 픽업 후보 정렬에서 영구히 밀린다(로컬시각을 UTC DB에 그대로 저장한 경우) | 해당 스케줄의 시작일시를 확인하고, 미래로 잡혀 있으면 다시 등록한다. 재발 시 giip 이슈로 보고 |
🔌 CQE API (자동화용)
위 UI 동작은 다음 CQE API 버브(byAK/bySk 디스패처)에 대응합니다. 요청은 text(버브+파라미터 이름), jsondata(값), token을 보냅니다. 단, 목록 조회(CQELsvrRunList)만은 예외로 파라미터를 text 문자열에 직접 포함해 보냅니다(jsondata 미사용).
- CQELsvrRunList
lssn <lssn> <offset>— 해당 LSSN에 등록된 스케줄 목록 조회. 서버측에서 오프셋 기준 최대 25건을 반환(고정, 요청으로 조절 불가). 응답 컬럼은 위 "목록 열 설명" 표와 동일. - LSVRList
csn— 해당 csn(프로젝트)에 등록된 논리 서버 목록 조회(서버 선택 팝업에 사용). - CQERunForce
mslsn— 스케줄과 무관하게 즉시 1회 실행 큐(tMgmtQue)에 적재. 1회성(repeat=1) 스케줄은 이때active가 0으로 내려가지만, 적재된 실행건은 그대로 실행됩니다. 응답RstVal:200=성공,300=권한 없음,302=이미 대기 중(충돌),610=권한 부족 또는 잔여 가스 부족. - CQERunActvate
mslsn— 해당 스케줄의active값을 1↔0으로 토글. 응답RstVal은 CQERunForce와 동일한 체계(200/300/302/610). - CQEQueueDel
mslsn— 해당 스케줄을 영구 삭제(단순 취소가 아님, 재등록 필요). 응답RstVal:200=성공,403=권한 없음,404=대상 없음. - CQERepoScript
mssn— 해당 스크립트(mssn)의 본문(msBody)을 조회.
권한 모델: 이 페이지의 API는 giip-issue 스킬의 x-api-key(SK) 방식이 아니라, 로그인 세션의 user_id+token 값을 함께 전송하는 세션 토큰 방식입니다.
인접 기능(스크립트 등록/서버 일괄 배포) 전체 사양: CQE 레포지토리 스크립트 관리 가이드의 "🔌 CQE API (자동화용)" 절, giipdb
docs/30_Specs/CQE_SPECIFICATION.md.
버전: 1.3
최종 업데이트: 2026-09-25
소스 파일: giipv3/public/help/cqelsvrRunList.ko.md