오프라인망 운영 가이드

오프라인 운영 경계

jupiq 컨테이너는 인터넷을 요구하지 않습니다. React 자산, Go API, timezone·CA 기반은 이미지 안에 포함됩니다. 다음 내부 대상만 방화벽 정책에 따라 접근합니다.

방향	대상	목적
jupiq → PostgreSQL	`POSTGRES_DSN`	필수 상태·설정·감사 저장
jupiq → Keycloak	관리자 UI 설정	선택 SSO
jupiq → Hub/Prometheus/K8s	연동별 설정	Hub 수집·서버 제어와 선택형 자원 수집
jupiq → AI/Webhook	관리자 UI 설정	선택 AI SSE proxy·Webhook 연결 시험
사용자 → jupiq	Reverse Proxy HTTPS	UI·REST·MCP

Keycloak·AI·Webhook 등 선택 연동이 없어도 Bootstrap 관리자와 핵심 Hub 관리가 기동합니다. Prometheus·Kubernetes·LLM 같은 선택 수집의 오류는 로그에 남고 해당 수집 주기만 실패하며, 서비스 프로세스와 Hub 수집은 계속 동작합니다.

반입·기동 전 점검표

파일명이 정확히 jupiq-vX.Y.Z.tar.gz인지 확인
Release 본문의 SHA-256과 반입 파일을 대조하고 승인 기록 보관
gzip -t 성공 및 조직 승인 기록 보관
docker load 후 태그가 jupiq:vX.Y.Z인지 확인
OCI version/revision/created label 기록
PostgreSQL TLS·계정·용량·백업 상태 확인
네 환경변수만 전달되고 로그·Compose에 비밀이 노출되지 않는지 확인
외부 egress 차단 상태에서 /readyz 성공
로그인 화면과 프로필 메뉴의 버전이 태그와 일치

JUPIQ_ARCHIVE_SHA256='릴리스-본문의-SHA256'
printf '%s  %s\n' "${JUPIQ_ARCHIVE_SHA256}" jupiq-v1.8.7.tar.gz | sha256sum -c -
docker image inspect jupiq:v1.8.7 \
  --format '{{.RepoTags}} {{index .Config.Labels "org.opencontainers.image.version"}}'
docker inspect jupiq --format '{{range .Config.Env}}{{println .}}{{end}}'

docker inspect jupiq --format '{{range .Config.Env}}...' 명령에는 실제 비밀값이 출력될 수 있습니다. 보안 터미널에서만 실행하고 결과를 티켓이나 채팅에 붙여넣지 마세요. 키 이름 검증 자동화는 값이 아닌 이름만 마스킹해 기록해야 합니다.

PostgreSQL과 키 백업·복구

컨테이너는 상태를 갖지 않으므로 백업 대상은 PostgreSQL과 ENCRYPTION_KEY, Reverse Proxy 설정입니다.

일관된 DB 백업
조직 표준 pg_dump/물리 백업과 PITR 정책을 적용합니다.
키 별도 보관
DB 백업과 다른 보안 매체 또는 HSM 절차로 암호화 키를 보관합니다.
격리 복구 시험
복원 DB에 동일 키를 주입해 연동 secret 복호화와 감사로그 조회를 확인합니다.
결과 기록
RPO/RTO, 복원 시각, 담당자, 검증 항목을 감사 가능한 Runbook에 남깁니다.

ENCRYPTION_KEY를 잃으면 DB에 암호화된 Hub token·client secret·AI key를 복구할 수 없습니다. DB만 백업해서는 완전한 복구가 되지 않습니다.

업그레이드와 롤백

릴리스 안내 검토
DB migration, 지원 버전, 보안 변경과 알려진 제한을 확인합니다.
백업과 이전 이미지 보존
DB 복구 지점을 만들고 현재 jupiq:v이전버전을 삭제하지 않습니다.
새 tar.gz 반입·로드
새 태그가 이전 태그를 덮어쓰지 않는지 검사합니다.
점검 환경 검증
복원 DB 또는 스테이징에서 migration, 로그인, 연동 테스트, 주요 화면을 확인합니다.
Compose 이미지 태그 교체
maintenance 공지 후 새 컨테이너를 기동하고 /readyz와 버전을 확인합니다.
Rollback 판단
migration이 역호환이면 이전 태그로 복귀하고, 아니면 사전 DB 복원 절차를 따릅니다.

latest 태그는 사용하지 않습니다. 이미지와 archive 모두 vX.Y.Z를 포함해 변경 불가능한 배포 단위를 유지합니다.

대상 망 단절 시 동작

상태	UI	다음 수집	데이터
Healthy	정상 배지·마지막 성공 시각	Hub별 설정 주기	최신 성공본
Degraded	성능 저하 배지·최근 오류	같은 고정 주기에 다시 시도	마지막 성공 snapshot과 시각 유지
Session stale	경고와 데이터 기준 시각	같은 고정 주기에 다시 시도	stale 세션은 현재 KPI에서 제외
Recovered	다음 조회에서 정상 상태	사용자·서버 전체 snapshot sync	새 성공본으로 전환

현재 버전 수집기는 지수 backoff, circuit breaker probe, 별도 disconnected 상태 또는 Delta Sync를 제공하지 않습니다. 반복 실패 시 Hub 연결 테스트와 네트워크 경로를 확인하세요.

GPU/LLM 모니터링을 OFF로 전환하면 관련 메뉴·KPI·query·collector만 멈추고 과거 데이터는 보존합니다. ON으로 돌아올 때 새 수집부터 이어가며 OFF 기간을 0 사용량으로 해석하지 않습니다.

빠른 장애 Runbook

증상	확인	조치
컨테이너 재시작 반복	`docker logs jupiq`, 네 env 존재 여부	DSN/TLS·키 형식 수정 후 재기동
`/healthz` 실패	프로세스·포트·OOM	컨테이너 상태와 호스트 자원 확인
`/readyz` 실패	PostgreSQL DNS·TLS·권한·migration	DB 연결 복구, 로그의 secret은 공유 금지
특정 Hub Stale	연결 테스트의 TLS/버전/인증/권한/지연	대상만 수정, 다른 Hub 재시작 불필요
SSO 실패	issuer·redirect URI·시간 동기화	Bootstrap 관리자로 진단
선택 메트릭 오류	Prometheus query·label·샘플	기능 OFF 후 핵심 서비스 유지

외부 연결 없이도 예측 가능한 배포와 복구

오프라인 운영 경계

반입·기동 전 점검표

PostgreSQL과 키 백업·복구

업그레이드와 롤백

대상 망 단절 시 동작

빠른 장애 Runbook