Docker 인스턴스 관리 가이드

Docker 인스턴스는 GIIP 에이전트를 원격 서버/PC에 컨테이너로 배포하고, GIIP 웹에서 생성·조회·폐기할 수 있는 관리자 기능입니다. 인스턴스 토큰을 대상 PC에 전달해 컨테이너를 기동하면, 그 PC가 GIIP 에이전트(1분마다 폴링)와 slack-bot(선택)으로 동작하기 시작합니다.

🏢 Docker 인스턴스 관리 페이지로 이동 →

📋 개요

Docker 인스턴스 관리 페이지에서는 giip-fde-agent Docker 컨테이너를 원격 PC/서버에 배포하기 위한 인스턴스를 생성하고 관리합니다. 인스턴스 생성 시 GIIP 서버가 AES-256-GCM으로 자격증명을 암호화해 저장하고, 토큰을 1회만 표시합니다.

⚠️ 이 화면은 관리자 전용입니다. 접근하려면 관리자 레벨 **uLevel >= 70**이 필요합니다. 그 미만 사용자는 홈으로 리다이렉트됩니다.

🔍 화면 구성

1. 상단 헤더

• 페이지 제목: "Docker 인스턴스 관리"
• + Create Docker instance 버튼: 새 인스턴스 생성 모달을 엽니다.

2. 인스턴스 목록 표

컬럼	설명
Label	인스턴스 이름(설정하지 않았을 경우 #<diSn>)
LSSN	선등록된 lsvr의 일련번호. 생성 직후 토큰 표시 영역과 이 목록에 표시됩니다. 클릭하면 lsvrdetail로 이동
Created	생성 일시
Last fetched	컨테이너가 토큰으로 마지막으로 env를 받아간 시각. 실시간 생존 여부가 아니라 "마지막 기동 시각"에 가까움
Status	Active(초록) 또는 Revoked(빨강) 배지. 소유권 불일치로 CQE 부트스트랩이 실행되지 않을 수 있는 행에는 배지 옆에 경고 아이콘(⚠️)이 붙습니다 — hover로 설명을 보고 클릭하면 해당 lssn의 실행 목록(cqelsvrRunList)으로 이동합니다(giip 3062)
Actions	Revoke 버튼 — 토큰을 무효화(실행 중인 컨테이너는 멈추지 않음)

⚠️ Last fetched가 -인 경우: 컨테이너가 아직 한 번도 기동하지 않은 것입니다. 절차 ①(수동) 또는 ②(Provision now)를 아직 실행하지 않은 상태입니다.

🛠️ 인스턴스 생성 방법

1. + Create Docker instance 버튼을 누릅니다.
2. 필수 필드 3개를 입력합니다.
   • GIIP_LOGIN_ID: GIIP 로그인 계정 (예: user@example.com)
   • GIIP_SK: GIIP 비밀 키 (비밀번호와 다름)
   • GIIP_CSN: CSN 번호 (예: 47)
3. 선택 필드를 입력합니다.
   • Label: 인스턴스 이름 (선택, 예: lowy-dp01-docker)
   • GIIP_PROJECT_NAME: 기본 docker
   • GIIP_WORKDIR: 작업 디렉터리 (선택)
   • GIIP_REST_BRANCH: Git 브랜치 (선택)
   • SLACK_BOT_TOKEN / SLACK_APP_TOKEN / SLACK_CHANNEL_ID: Slack 봇 활성화 (선택 — 둘 다 필요)
   • Enable hourly-issue-scheduler: 체크박스 (기본 on) —매시 :07에 이슈 스케줄러 실행
4. Create를 누릅니다.

토큰은 반드시 복사하세요

생성 직후 딱 1회만 토큰이 표시됩니다.

GIIP_INSTANCE_TOKEN=<토큰>

모달을 닫으면 다시 볼 수 없습니다. 컨테이너를 기동하려면 이 토큰이 필요하므로, 반드시 복사한 뒤 진행하세요.

🛠️ 생성 후 컨테이너 기동 — 절차 ① (수동, 모든 환경)

토큰을 복사한 뒤, 대상 PC/서버에서 다음을 실행합니다.

# 1. giip-fde-agent 저장소를 클론
git clone https://github.com/LowyShin/giip-fde-agent.git
cd giip-fde-agent/docker

# 2. .env 파일에 토큰만 기록
echo 'GIIP_INSTANCE_TOKEN=<복사한 토큰>' > .env

# 3. Docker Compose로 기동
docker compose up -d --build

• .env에 토큰 한 줄이면 충분합니다. 나머지 환경변수는 fetch-instance-env.sh가 dockerInstanceFetch API(토큰 자체가 자격증명)로 서버에서 자동 내려받습니다.
• .env에 직접 키를 적어두면 그 값이 우선합니다(부분 override 가능).

🛠️ 생성 후 컨테이너 기동 — 절차 ② (원격 Provision now)

대상 PC에 이미 GIIP 에이전트가 돌고 있어 lssn이 있는 경우에만 사용 가능합니다. (giip 3043) 드롭다운에는 Docker Desktop이 설치돼 있고 한 번이라도 사용량을 보고한 적 있는 lssn만 후보로 뜹니다 — 방금 만든 인스턴스 자신의(에이전트가 아직 붙은 적 없는) lssn은 원천적으로 나오지 않습니다.

1. 토큰 표시 영역의 드롭다운에서 리소스 여유가 있는 대상(CPU/Mem/Disk 사용률과 실행 중 컨테이너 수가 함께 표시됩니다)을 선택합니다. 후보가 하나도 없으면 드롭다운 대신 안내 문구가 뜨며, 이 경우 절차 ①(수동)을 이용하세요.
2. [Provision now] 버튼을 누릅니다.
3. CQE 큐에 스크립트(mssn=6122)가 등록되고, 즉시 강제 실행(CQERunForce)됩니다.

⚠️ 이 버튼은 GIIP 에이전트가 설치된 PC에서만 동작합니다. 대상 PC에 에이전트가 없으면 이 방법은 쓸 수 없습니다.

ℹ️ 권한: [Provision now]는 서버(DockerInstanceProvision)가 검사합니다. 인스턴스가 속한 csn과 대상 서버가 속한 csn의 구성원이면 누구나 실행할 수 있고, 스크립트 소유자일 필요는 없습니다. 실패하면 화면에 사유가 표시되며(아래 문제 해결 표), 인스턴스 생성은 이미 완료되었고 토큰은 그대로 유효하므로 절차 ①(수동)로 진행할 수 있습니다.

⚠️ 완료까지 최대 1분: 대상 PC의 GIIP 에이전트가 약 60초마다 폴링하므로, 최대 1분 정도 기다려야 합니다.

🔍 생성 후 "접속" 확인 — 3가지 경로

GIIP 웹 안에는 컨테이너에 접속하는 터미널이 없습니다. 확인은 다음 3가지로 합니다.

1. 컨테이너 셸로 직접 접속 (대상 PC에서)

docker exec -it giip-fde-agent bash

컨테이너 이름은 giip-fde-agent로 고정입니다.

2. 로그 확인 (대상 PC에서)

docker compose logs -f          # docker/ 디렉터리에서
docker logs -f giip-fde-agent   # 어디서든

기동이 정상이면 다음 메시지가 보입니다:

• [entrypoint] cloned ...
• [fetch-instance-env] env applied from GIIP_INSTANCE_TOKEN
• [entrypoint] registered giipAgentLinux cron (every 1 min)
• [entrypoint] ready. tailing logs.

3. GIIP 웹에서 확인 — lsvrlist (서버 목록)

이것이 "GIIP 웹에서 접속 확인"하는 정본 방법입니다.

생성 시 lsvr이 선등록됩니다 — 인스턴스를 만드는 순간 lssn이 발급되어 UI에 표시되므로, 컨테이너 기동 전에 lsvr이 lsvrlist에 나타납니다 (giip 2856).

컨테이너 기동 시:

1. giipAgentLinux를 클론합니다.
2. giipAgent.cnf (sk=등록한 GIIP_SK, lssn=GIIP_LSSN 환경변수값)를 생성합니다.
3. 1분마다 giipAgent3.sh를 실행합니다 (단, lssn이 0이 아니므로 CQEQueueGet의 자기등록 경로 대신 기존 lsvr을 유지합니다).
4. 이후 이 컨테이너가 다른 서버와 똑같이 lsvrlist 목록에 나타납니다.

접속 확인 경로: /ko/lsvrlist → 해당 lssn 행 클릭 → lsvrdetail에서 tLSvr.lsChkdt 하트비트로 생존 확인

⚠️ GIIP_SK가 없거나 GIIP_ENABLE_AGENT=false이면 이 등록이 일어나지 않아 GIIP 웹에서 컨테이너 상태를 전혀 볼 수 없습니다.

4. Slack으로 확인 (Slack 봇 설정 시)

SLACK_BOT_TOKEN과 SLACK_APP_TOKEN을 둘 다 입력한 경우에만 slack-bot이 pm2로 기동됩니다. 지정한 채널에서 봇이 응답하면 정상입니다.

⚠️ 둘 중 하나라도 없으면 건너뜁니다 — 하나만 넣고 아무것도 안 뜨는 것은 정상입니다.

🧩 대상 서버를 새로 늘리는 방법 (Docker 설치 → 후보 노출)

Provision now 드롭다운은 서버(lssn) 단위로 후보를 보여 줍니다. csn 단위로 고르는 것이 아니며, 후보는 인스턴스를 만든 csn 소속 서버 중에서만 나옵니다. 대상을 늘리려면 아래 순서로 PC/서버를 준비합니다.

단계	할 일	확인 방법
①	대상 PC/서버에 Docker 설치	docker version이 Client와 Server 버전을 모두 출력
②	GIIP 에이전트 설치·등록(인스턴스 csn 소속)	lsvrdetail에서 해당 lssn의 csn과 마지막 체크인 확인
③	docker_usage 보고 확인	kvslist에서 kKey=<lssn>, kFactor=docker_usage 최신 행에 "dockerInstalled":true
④	후보 노출 확인	인스턴스를 Create한 뒤 드롭다운에 해당 서버가 뜸
⑤	[Provision now] 실행	절차 ②(원격 Provision now) 참조

OS별 Docker 설치

OS	설치 대상	방법
Windows	Docker Desktop	공식 설치 페이지 https://docs.docker.com/desktop/setup/install/windows-install/ 에서 설치하거나 winget install -e --id Docker.DockerDesktop을 사용합니다. WSL 2 또는 Hyper-V(가상화 활성화) 요건이 있습니다.
macOS	Docker Desktop	공식 설치 페이지 https://docs.docker.com/desktop/setup/install/mac-install/
Linux	Docker Engine	공식 설치 문서 https://docs.docker.com/engine/install/ 의 배포판별 절차를 따릅니다. 설치 후 사용자를 docker 그룹에 추가하고(공식 문서 "Linux post-installation steps") 재로그인한 뒤 docker version이 서버 버전까지 나오는지 확인합니다.

Docker 설치 후에는 Docker 데몬이 실행 중이어야 합니다(Docker Desktop은 앱을 켜 둡니다).

⚠️ 현재 Linux(Docker Engine)는 후보 목록에 나타나지 않습니다. 확인 결과 giipAgentLinux(origin/main)에는 docker_usage를 수집·보고하는 코드가 없고, 이를 보고하는 에이전트는 Windows 에이전트(giipAgentWin의 CollectDockerMetrics.ps1)뿐입니다. 따라서 Linux 서버에 Docker를 설치해도 드롭다운 후보가 되지 않으며, 이 경우 **절차 ①(수동)**으로 기동합니다.

후보 판정 조건 (Windows 에이전트)

Windows 에이전트는 실행할 때마다 docker CLI가 PATH에 있는지 확인하고, docker version --format '{{.Server.Version}}'이 서버 버전을 반환하면 dockerInstalled=true로 보고합니다. CLI가 없거나 데몬이 꺼져 있으면 false입니다.

GIIP 에이전트 설치

에이전트 설치는 이 문서가 아니라 아래 가이드를 따릅니다. 에이전트는 인스턴스를 만든 csn에 소속되어야 합니다.

• Windows 에이전트 설치 가이드
• Linux/WSL 에이전트 설치 가이드
• 에이전트 CSN 등록

🤖 AI 에이전트용 연결 매뉴얼 (Provision now 대상 서버가 안 보일 때)

AI 에이전트가 사람 대신 "이 PC를 Docker 인스턴스의 대상으로 연결"할 때 따르는 절차입니다. 모든 단계는 읽기 전용이며, 값을 추측하지 말고 직접 조회합니다.

안내 문구의 뜻

"이 csn에서 Docker Desktop을 감지한 서버가 아직 없습니다"는 오류가 아니라 후보 목록이 비었다는 뜻입니다. 후보가 되려면 다음 셋을 모두 만족해야 합니다.

1. 서버(lssn)가 인스턴스를 만든 csn 소속입니다.
2. 그 서버의 GIIP 에이전트가 docker_usage를 보고했고, 최신 값에 "dockerInstalled":true가 있습니다.
3. 후보 목록 API(DockerCapableLsvrList)가 서버에 배포되어 있습니다.

1. 대상 PC의 lssn과 csn 찾기

• 에이전트 설정 파일 giipAgent.cfg의 lssn을 읽습니다(sk 값은 출력하지 않습니다). Windows 에이전트는 작업 스케줄러 GIIP Agent Task (v3)의 실행 경로에서 폴더를 찾고, 그 부모 폴더의 giipAgent.cfg를 봅니다.
• csn은 GIIP 웹 lsvrdetail에서 그 lssn의 값을 확인합니다. 인스턴스를 만든 csn과 같아야 합니다.

2. 에이전트와 Docker 동작 확인

• Windows: Get-ScheduledTask 'GIIP Agent Task (v3)' | Get-ScheduledTaskInfo에서 LastTaskResult가 0(성공) 또는 267009(실행 중)이어야 합니다.
• 에이전트 로그에 [CollectDockerMetrics] ... Successfully collected and uploaded Docker resource usage가 매 실행마다 있어야 합니다.
• Docker Desktop이 켜져 있어야 합니다. docker version이 서버 버전까지 출력하는지 확인합니다.

3. 보고된 Docker 사용량 확인

GIIP 웹 kvslist에서 kKey=<lssn>, kFactor=docker_usage로 조회합니다. 최신 행에 "dockerInstalled":true가 있어야 후보가 됩니다. 없거나 false이면 2단계로 돌아갑니다.

4. 모두 정상인데 목록이 비어 있으면 (관리자)

후보 목록 API가 배포되지 않은 경우입니다. 예전에는 이때도 같은 안내 문구가 떠서 원인이 가려졌고, 지금은 "후보 목록 API 응답이 올바르지 않습니다" 오류로 표시됩니다. 관리자가 저장 프로시저 pApiDockerCapableLsvrListbyAK의 배포 여부를 확인하고, 없으면 giipdb의 SP/pApiDockerCapableLsvrListbyAK.sql을 mgmt/execSQLFile.ps1로 배포합니다.

5. 연결할 서버가 없을 때

• 대상 PC에 GIIP 에이전트가 없으면 [Provision now]를 쓸 수 없습니다. 에이전트를 먼저 설치·등록하거나 **절차 ①(수동)**을 사용합니다.
• 에이전트가 한 번도 접속한 적 없는 lssn(마지막 체크인이 비어 있음)은 후보가 아닙니다. 인스턴스 생성 때 미리 등록되는 lssn이 이런 경우이니 대상으로 고르지 마세요.

AI가 지켜야 할 것

• sk, 인스턴스 토큰, 큐 본문의 토큰을 출력하거나 기록하지 않습니다.
• 다른 csn의 SK로 조회·기록하지 않습니다(먼저 csn을 확인합니다).
• 값을 추측하지 말고, 위 조회 결과를 근거로 보고합니다.

🤖 AI 에이전트에게 이 문서 URL만 전달하는 경우

사용자가 AI 에이전트에게 이 문서의 URL만 전달해도(https://giip.littleworld.net/ko/guides/docker-instances, 원문은 https://giip.littleworld.net/help/docker-instances.ko.md) 대상 서버를 늘릴 수 있도록, AI는 다음 순서를 따릅니다.

사용자가 알려 줘야 할 것: ① 작업 csn(인스턴스를 만들 csn) ② 대상 PC/서버에 접근하는 방법(이 AI가 그 PC에서 직접 실행하는지, 원격 접속인지).

1. 읽기 전용 조회부터 합니다. 대상 PC의 OS, Docker 설치·데몬 상태(docker version), GIIP 에이전트 설치·동작 상태, giipAgent.cfg의 lssn을 확인합니다(sk는 출력하지 않습니다).
2. 빠진 단계만 설치·설정합니다. 위 "대상 서버를 새로 늘리는 방법"의 ①~③ 중 이미 충족된 것은 건드리지 않습니다. 설치는 사용자 PC를 변경하는 작업이므로 실행 전에 무엇을 설치할지 사용자에게 밝힙니다.
3. csn은 추측하지 않습니다. lsvrdetail로 그 lssn의 csn을 확인하고, 인스턴스를 만든 csn과 같은지 확인합니다.
4. 후보 노출까지 확인한 뒤 보고합니다. kvslist의 docker_usage에서 "dockerInstalled":true를 확인하고, 인스턴스 생성 후 드롭다운에 후보로 뜨는지까지 확인합니다. Linux 서버처럼 구조상 후보가 될 수 없는 경우에는 그 사실과 절차 ①(수동)을 보고합니다.

AI가 지켜야 할 것은 위 "AI가 지켜야 할 것"과 같습니다(sk·인스턴스 토큰 출력 금지, 다른 csn의 SK 사용 금지, 추측 금지).

💡 참고

• Last fetched ≠ 실시간 생존 여부: Last fetched는 "마지막으로 env를 받아간 시각"입니다. 컨테이너가 꺼져도 이 값은 그대로 남아 있습니다. 실시간 상태는 lsvrlist의 하트비트로 확인합니다.
• Revoke는 행을 삭제하지 않습니다: Revoke는 토큰을 무효화할 뿐 목록 행을 지우지 않습니다. 감사 이력이므로 Revoked 배지와 함께 남습니다.
• Revoke해도 실행 중인 컨테이너는 멈추지 않습니다. 실제로 멈추려면 대상 PC에서 docker compose down을 실행해야 합니다.
• 컨테이너 이름: 절차 ①(수동)과 기존 인스턴스는 giip-fde-agent입니다. [Provision now]는 인스턴스마다 giip-fde-agent-<diSn>(compose 프로젝트 giip-fde-<diSn>)로 기동하므로 한 PC에 여러 인스턴스를 띄울 수 있습니다. diSn은 목록 표의 diSn 열에서 확인합니다.

문제 해결

증상	원인	해결
"이 csn에서 Docker Desktop을 감지한 서버가 아직 없습니다"가 뜬다	(a) 대상 PC의 에이전트가 안 돌거나 Docker Desktop이 꺼져 docker_usage가 없음 (b) 서버의 csn이 인스턴스의 csn과 다름 (c) 후보 목록 API가 서버에 배포되지 않음	아래 "AI 에이전트용 연결 매뉴얼" 1~4단계로 확인하세요. 바로 진행하려면 절차 ①(수동)을 사용합니다.
토큰을 못 적어뒀다	재조회 불가	기존 인스턴스를 Revoke하고 새로 생성하세요.
docker compose up은 됐는데 lsvrlist에 안 뜬다	(a) GIIP_ENABLE_AGENT=false 여부 (b) GIIP_SK 비었는지 (c) 1분 Polling 주기 전인지 (d) 인증 오류(401)	docker logs의 /work/giipAgentLinux/log/cron.log에서 401 오류 확인
매 재기동마다 새 lssn으로 등록된다	/work 볼륨이 유실됨	docker-compose.yml의 볼륨이 giip-fde-agent-data:/work 전체인지 확인
[Provision now] 실패	화면에 표시되는 사유: Forbidden: not a member of the instance csn / ...target server csn(해당 csn의 구성원이 아님), Target server has not reported Docker Desktop(대상이 Docker를 보고한 적 없음 — 에이전트와 Docker Desktop 확인), still pending(이전 요청이 대기 중 — 약 5분 뒤 재시도), Docker instance is revoked / not found(폐기되었거나 없는 인스턴스)	사유에 맞게 조치하세요. 바로 진행하려면 절차 ①(수동 docker compose up)을 쓰세요. 토큰은 유효합니다.
[Provision now]는 성공 메시지가 떴는데 몇 분째 lsvrlist에도 컨테이너에도 변화가 없다	(a) 대상 lssn의 에이전트가 죽어있어 애초에 폴링을 안 함 (b) 이 스케줄만 배급 불가(BLOCKED)로 격리됨 (giip #2557류)	(a) lsvrdetail에서 그 lssn의 마지막 체크인 시각 확인 — 오래됐으면 대상 PC의 에이전트/네트워크부터 점검 (b) 관리자에게 해당 lssn/csn 기준으로 배급 불가 스케줄이 있는지 확인 요청. 몇 분 기다려도 안 되면 절차①(수동)으로 전환
Slack 봇이 안 뜬다	SLACK_BOT_TOKEN과 SLACK_APP_TOKEN 둘 다 필요	하나만 있으면 둘 다 건너뜁니다.
접속 즉시 홈으로 튕김	uLevel이 70 미만	관리자 계정(레벨 70+)으로 로그인하세요.

---

버전: 1.3 최종 수정: 2026-10-15 (대상 서버를 새로 늘리는 방법, AI에게 문서 URL만 전달하는 경우 절 추가) 소스 파일: giipv3/public/help/docker-instances.ko.md