물리/클라우드 서버 목록 가이드
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 상세 사양은 별도 가이드를 참조하세요.
문제 해결
| 증상 | 원인 | 해결 |
|---|---|---|
| 서버 아이콘이 🔴 빨간색으로 표시됨 | 에이전트 연결 끊김 | 해당 서버에서 에이전트를 재시작합니다 |
| 서버 아이콘이 🟡 노란색으로 표시됨 | 네트워크 불안정으로 인한 지연 | 네트워크 상태를 확인한 후 잠시 뒤 다시 확인합니다 |
| 찾는 서버가 목록에 보이지 않음 | 프로젝트/상태 필터 또는 검색어가 적용됨 | 필터를 초기화하거나 호스트명/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 자동처리 스케줄러(hostnameLowy-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