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>)
Created	생성 일시
Last fetched	컨테이너가 토큰으로 마지막으로 env를 받아간 시각. 실시간 생존 여부가 아니라 "마지막 기동 시각"에 가까움
Status	Active(초록) 또는 Revoked(빨강) 배지
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이 있는 경우에만 사용 가능합니다.

1. 토큰 표시 영역의 lssn 입력란에 대상 PC의 lssn을 입력합니다.
2. [Provision now] 버튼을 누릅니다.
3. CQE 큐에 스크립트(mssn=6122)가 등록되고, 즉시 강제 실행(CQERunForce)됩니다.

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

⚠️ 스크립트 소유권 제약: 부트스트랩 스크립트는 특정 소유자 계정으로 실행됩니다. 다른 계정에서 이 버튼을 누르면 실패하지만, 인스턴스 생성 자체는 이미 완료되었고 토큰은 그대로 유효합니다. 이 경우 절차 ①(수동)으로 진행하세요.

⚠️ 완료까지 최대 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 웹에서 접속 확인"하는 정본 방법입니다.

컨테이너 기동 시:

1. giipAgentLinux를 클론합니다.
2. giipAgent.cnf (sk=등록한 GIIP_SK, lssn="0")를 생성합니다.
3. 1분마다 giipAgent3.sh를 실행합니다.
4. GIIP가 lssn을 자동 배정하고, 이후 같은 lssn으로 하트비트를 보냅니다.
5. 이후 이 컨테이너가 다른 서버와 똑같이 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로 기동됩니다. 지정한 채널에서 봇이 응답하면 정상입니다.

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

💡 참고

• Last fetched ≠ 실시간 생존 여부: Last fetched는 "마지막으로 env를 받아간 시각"입니다. 컨테이너가 꺼져도 이 값은 그대로 남아 있습니다. 실시간 상태는 lsvrlist의 하트비트로 확인합니다.
• Revoke는 행을 삭제하지 않습니다: Revoke는 토큰을 무효화할 뿐 목록 행을 지우지 않습니다. 감사 이력이므로 Revoked 배지와 함께 남습니다.
• Revoke해도 실행 중인 컨테이너는 멈추지 않습니다. 실제로 멈추려면 대상 PC에서 docker compose down을 실행해야 합니다.
• 컨테이너 이름은 항상 giip-fde-agent: docker-compose.yml의 container_name으로 고정입니다.

문제 해결

증상	원인	해결
토큰을 못 적어뒀다	재조회 불가	기존 인스턴스를 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] 실패	부트스트랩 스크립트 소유자 계정 불일치	절차 ①(수동 docker compose up)으로 진행하세요.
Slack 봇이 안 뜬다	SLACK_BOT_TOKEN과 SLACK_APP_TOKEN 둘 다 필요	하나만 있으면 둘 다 건너뜁니다.
접속 즉시 홈으로 튕김	uLevel이 70 미만	관리자 계정(레벨 70+)으로 로그인하세요.

---

버전: 1.0 최종 수정: 2026-09-22 (giip #2847) 소스 파일: giipv3/public/help/docker-instances.ko.md