물리/클라우드 서버 목록 가이드

GIIP 플랫폼에서 관리하는 모든 서버(물리 IDC 서버 및 공용 클라우드 VM) 인벤토리를 확인하고 필터링하는 방법을 안내합니다.

🏢 서버 목록 페이지로 이동 →

📋 개요

서버 목록 화면은 귀하의 모든 컴퓨팅 자산을 통합하여 보여줍니다. 여기에서 각 서버의 가동 상태를 실시간으로 확인하고, 필요한 자산을 빠르게 검색하여 상세 페이지로 이동할 수 있습니다.

🔍 주요 기능 및 화면 구성

1. 통합 필터 및 검색

• 프로젝트 필터: 특정 프로젝트에 속한 서버만 골라볼 수 있습니다.
• 상태 필터: Running, Stopped, Warning, Unknown 상태별로 필터링이 가능합니다.
• 검색 바: 호스트명(Hostname) 또는 IP 주소로 즉시 검색하세요.

2. 에이전트 상태 (Agent Icon)

서버 목록의 아이콘 색상을 통해 에이전트 연결 상태를 직관적으로 파악합니다.

• 🟢 초록색: 정상 연결 및 메트릭 수집 중
• 🟡 노란색: 지연 발생(네트워크 불안정)
• 🔴 빨간색: 연결 끊김 (에이전트 재시작 필요)

3. 자산 속성 요약

각 행(Row)에서 OS 버전, CPU Core 수, 가동 시간(Uptime) 등의 핵심 사양을 즉시 확인할 수 있습니다.

🛠️ 작업 도구 (Action Bar)

• 일괄 명령: 여러 서버를 선택한 후 상단의 [명령 실행] 버튼을 눌러 동시에 패키지를 업데이트하거나 서비스를 재시작할 수 있습니다.
• 엑셀 다운로드: 현재 필터링된 서버 목록을 CSV 또는 Excel 파일로 내보냅니다.

💡 활용 팁

• 태그 활용: 서버에 Web, DB, Staging 등의 태그를 지정해 두면 목록에서 용도별로 훨씬 빠르게 분류할 수 있습니다.

API 참조

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

📘 인프라 관리 API 가이드

문제 해결

증상	원인	해결
서버 아이콘이 🔴 빨간색으로 표시됨	에이전트 연결 끊김	해당 서버에서 에이전트를 재시작합니다
서버 아이콘이 🟡 노란색으로 표시됨	네트워크 불안정으로 인한 지연	네트워크 상태를 확인한 후 잠시 뒤 다시 확인합니다
찾는 서버가 목록에 보이지 않음	프로젝트/상태 필터 또는 검색어가 적용됨	필터를 초기화하거나 호스트명/IP 주소로 검색합니다
일괄 명령이 일부 서버에 적용되지 않음	대상 서버의 에이전트 연결이 끊긴 상태	에이전트 아이콘이 🟢 초록색인 서버만 선택하여 다시 실행합니다

🤖 AI Agent를 lsvr로 등록하는 방법

이 섹션은 AI 에이전트가 이 문서만 보고 스스로를 서버 목록(lsvr)에 등록할 수 있도록 하는 완결된 실행 절차다. 아래 명령을 그대로 복사해서 실행하면 된다(판단·추가 조사 불필요).

전제조건

• 등록 대상 csn(프로젝트)용 **SK(Secret Key)**가 있어야 한다. SK가 없으면 등록 자체가 불가능하다 — /svclist(로그인 후 프로젝트 설정 화면)에서 먼저 발급/확인할 것. SK 발급 절차 자체는 이 가이드 범위 밖이다. 상세는 에이전트 등록 및 큐 API 명세를 참고.

실행 — curl

curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "text=AgentAutoRegister hostname jsondata" \
  --data-urlencode "jsondata={\"hostname\":\"<서버 고유 호스트명>\",\"os\":\"<OS 설명>\",\"agent_version\":\"<버전>\"}" \
  --data-urlencode "token=<SK>"

실행 — PowerShell

$jsonData = '{"hostname": "<서버 고유 호스트명>", "os": "<OS 설명>", "agent_version": "<버전>"}'
$form = New-Object System.Collections.Specialized.NameValueCollection
$form.Add('text', 'AgentAutoRegister hostname jsondata')
$form.Add('token', '<SK>')
$form.Add('jsondata', $jsonData)
$wc = New-Object System.Net.WebClient
$wc.Encoding = [System.Text.Encoding]::UTF8
$resp = $wc.UploadValues('https://giipfaw.azurewebsites.net/api/giipApiSk2', 'POST', $form)
[System.Text.Encoding]::UTF8.GetString($resp)

<서버 고유 호스트명>, <OS 설명>, <버전>, <SK>는 실제 값으로 반드시 치환할 것. hostname은 필수이며 이 csn 안에서 유일해야 한다.

응답 해석

HTTP 상태는 항상 200이므로 성공 여부는 반드시 응답 JSON의 data[0].RstVal로 판단할 것.

RstVal	의미	응답 예시
200(신규)	신규 서버로 등록 성공, action: "new"	{"data":[{"Proc_MSG":"200|Server auto-registered successfully","lssn":71290,"action":"new","RstVal":200,"RstMsg":"Server auto-registered successfully"}]}
200(기존)	이미 등록된 hostname → 하트비트 갱신, action: "update"	{"data":[{"Proc_MSG":"200|Server updated successfully (heartbeat)","lssn":71290,"action":"update","RstVal":200,"RstMsg":"Server updated successfully (heartbeat)"}]}
400	hostname 누락	{"data":[{"Proc_MSG":"400|Hostname required","RstVal":400,"RstMsg":"Hostname required"}]}
401	SK 무효	{"data":[{"Proc_MSG":"401|Unauthorized - Invalid SK","RstVal":401,"RstMsg":"Unauthorized - Invalid Secret Key"}]}

등록 성공 시 응답의 lssn이 이 서버의 고유 번호다 — 이후 이 lssn으로 다른 giip API(예: 큐 폴링)를 호출할 수 있다.

멱등성(반복 호출 안전)

동일한 요청(같은 hostname, 같은 SK)을 반복 호출해도 안전하다 — 최초 호출은 신규 등록(INSERT), 이후 호출은 전부 하트비트(UPDATE, 마지막 체크 시각 갱신)로 처리된다. 주기적인 헬스체크/하트비트 용도로 그대로 재사용 가능하다.

선택 필드 (인벤토리를 더 풍부하게 표시)

jsondata에 아래 필드를 추가할 수 있다(모두 선택, 없어도 등록 자체는 성공):

필드	타입	설명
os	string	OS 설명
kernel	string	커널 버전
cpu	string	CPU 모델명
cpu_cores	number	CPU 코어 수
memory_gb	number	메모리(GB)
disk_gb	number	디스크(GB)
agent_version	string	에이전트/클라이언트 버전 문자열
ipv4_global	string	공인 IPv4
ipv4_local	string	사설 IPv4
network	array	[{"name":"eth0","ipv4":"...","mac":"..."}]
software	array	[{"name":"nginx","version":"1.18.0","vendor":"Ubuntu","type":"DEB"}]
services	array	[{"name":"nginx","status":"running","start_type":"enabled","port":80}]

에이전트 타입별 표시·명명 규칙 (자기등록 컨벤션)

⚠️ 개념 변경(2026-09-12): LSvr(lssn)은 "PC 한 대"가 아니라 "에이전트(역할) 하나"를 의미한다. 한 물리 PC에 여러 에이전트가 뜨면, 그만큼 여러 개의 서로 다른 lssn이 생긴다 — 예를 들어 같은 PC(Lowy-DP01)에 Windows 모니터링 에이전트(giipAgentWin, lssn=71197)와 gissue 자동처리 스케줄러(hostname Lowy-DP01-gissue-hourly-scheduler, lssn=71291)가 서로 다른 두 개의 LSvr로 각각 등록되어 있다. "이 PC의 lssn"이라는 단일 값을 가정하지 말고, 항상 "어느 에이전트/역할의 lssn인지"를 명확히 구분할 것.

lsvrlist는 이제 물리 giipAgent만이 아니라 여러 에이전트 타입을 함께 표시한다. AI가 이 문서만 보고 스스로 등록할 때 아래 컨벤션을 지키면, hostname과 agent_version만으로 "어떤 머신의 · 어떤 도구(모델/버전)가 · 어떤 실행모드로" 도는지 분리되어 읽힌다.

에이전트 타입(3종)

타입	대상	agent_version 표기 예
giipAgentWin	윈도우 물리/VM 에이전트	giipAgentWin 5.3.1
giipAgentLinux	리눅스 물리/VM 에이전트	giipAgentLinux 2.4.0
AI	AI 코딩/작업 에이전트(Claude Code, GPT 등)	claude-opus-4-8 (모델 ID)

hostname 명명 규칙 — <머신>-<도구슬러그>[-<실행모드>]

• 머신: 실제 호스트/PC 이름 (예: Lowy-DP01)
• 도구슬러그: 에이전트를 식별하는 소문자-하이픈 슬러그 (예: claude-code, giipagentwin, gissue-hourly-scheduler)
• 실행모드(선택): console(상시 콘솔 세션) · scheduler(크론/스케줄러 구동) · service(OS 서비스/데몬)
• 실측 예: Lowy-DP01-claude-code(콘솔로 도는 AI), Lowy-DP01-gissue-hourly-scheduler(스케줄러로 도는 AI)

타입별 "모델 - 버전 - 실행모드" 표기 권장

항목	giipAgentWin / giipAgentLinux	AI
agent_version	"<타입> <버전>" (예: giipAgentWin 5.3.1)	모델 ID (예: claude-opus-4-8, gpt-5)
os	실제 OS (예: Windows Server 2022, Ubuntu 22.04)	구동 OS + 도구 (예: Windows 10 / Claude Code)
실행모드	hostname 접미 (예: -service)	hostname 접미 (예: -console, -scheduler)

이 컨벤션대로 등록하면 목록에서 각 행의 타입·모델/버전·실행모드를 hostname과 agent_version만으로 구분해 읽을 수 있다 — 예: AI · claude-opus-4-8 · scheduler, giipAgentWin · 5.3.1 · service.

AI 자기등록 예시 (스케줄러로 도는 Claude Code)

{"hostname":"Lowy-DP01-claude-code-scheduler","os":"Windows 10 / Claude Code","agent_version":"claude-opus-4-8"}

등록 후 🏢 서버 목록 페이지에서 방금 등록한 hostname을 검색하면 신규 lsvr로 나타난다.

등록 → 큐 폴링 → 결과 보고까지 이어지는 전체 흐름은 에이전트 등록 및 큐 API 명세를 참고할 것.

---

버전: 1.1 최종 업데이트: 2026-09-10 소스 파일: giipv3/public/help/lsvrlist.ko.md