배포 체크리스트

이 페이지는 Cloosphere를 운영 환경에 배포할 때 운영자가 점검해야 할 설정을 모아둔 체크리스트입니다.

각 항목을 펼치면 정확한 설정값과 주의사항을 확인할 수 있습니다.

관리자 패널의 설정값(GUI)은 PersistentConfig로 DB에 저장되어 자동 반영됩니다. 이 페이지에서 다루는 항목은 GUI로 변경 불가능한 환경변수 / 외부 의존성 입니다.

필수 모든 환경

CLOOSPHERE_PUBLIC_URL을 외부 HTTPS FQDN으로 지정

변수	용도	예시
`CLOOSPHERE_PUBLIC_URL`	외부 접근 base URL. 임베드 위젯 callback, 매니페스트 validDomains 자동 계산 등에 사용	`https://cloosphere.yourdomain.com`
`CLOOCUS_PUBLIC_URL`	SR(서비스 요청) 기능의 공개 base URL. `SR_KEY`와 함께 설정하면 SR이 활성화됨	`https://cloosphere.yourdomain.com`

CLOOSPHERE_PUBLIC_URL 미설정 시:

임베드 위젯 callback URL이 내부 IP/host로 잘못 노출
Teams 봇 매니페스트의 validDomains 계산 오류

(SR 기능은 CLOOCUS_PUBLIC_URL+SR_KEY로 별도 제어됩니다.)반드시 HTTPS 공개 FQDN으로 지정. 프록시(Nginx/Cloudflare) 뒤에 있으면 외부에서 보이는 URL을 입력.

DATABASE_URL로 PostgreSQL 연결 확인

변수	등급	용도
`DATABASE_URL`	필수	PostgreSQL 연결 문자열
`DATABASE_SCHEMA`	권장	멀티 테넌트 시 스키마 분리 (기본 `public`)

연결이 끊기면 /health/db가 503 + error detail을 반환합니다. 배포 직후 이 endpoint로 연결을 확인하세요.

Alembic 마이그레이션을 올바른 스키마에 최신 버전으로 적용

배포한 코드 버전과 DB 스키마 버전이 일치해야 합니다. 마이그레이션 누락 시 런타임에 컬럼/테이블 부재 오류가 발생합니다.

멀티워커 환경에서는 마이그레이션이 1회만 실행되어야 합니다. 다중 워커가 동시에 마이그레이션을 시도하면 충돌이 발생합니다 (최신 버전에서 자동 lock으로 fix). 자세한 직렬화 방법은 멀티워커 그룹의 “컨테이너 기동 직렬화” 항목을 참조하세요.

PostgreSQL · 파일 스토리지 · AGE 그래프 백업 주기 설정

PostgreSQL — PersistentConfig·사용자·감사 로그 등 핵심 데이터
파일 스토리지 — 업로드 문서·이미지
AGE 그래프 — Knowledge Graph는 PostgreSQL 안에 있지만, 대규모 그래프는 별도 백업 주기를 두는 것이 안전합니다.

세 가지를 모두 포함하는 정기 백업 정책을 수립하세요.

멀티워커 워커 2개 이상이면 필수

REDIS_URL 설정 (PersistentConfig 동기화 · 세션 공유)

변수	등급	용도
`REDIS_URL`	멀티워커	멀티워커 환경 필수, 단일 워커는 선택
`REDIS_SENTINEL_HOSTS`	선택	Redis Sentinel 사용 시
`REDIS_SENTINEL_PORT`	선택	(기본 26379)

멀티워커 환경에서는 REDIS_URL 필수. Redis 없이 운영하면:

PersistentConfig가 워커별 메모리에만 저장되어 워커 간 설정 불일치
사용자별 에이전트 선택 상태 등 세션 데이터 손실
Teams 봇 / 임베드 위젯의 사용자 컨텍스트 분실

Cloosphere는 Redis 연결 실패 시 5초 timeout으로 fast-fail하고 in-memory fallback으로 자동 전환됩니다 (단일 워커 모드용). 멀티워커에서는 health endpoint로 Redis 가용성을 모니터링하세요.

모든 워커가 같은 파일 스토리지 볼륨을 공유하도록 마운트

워커마다 다른 로컬 파일에 접근하면, 한 워커에 업로드한 파일이 다른 워커에서는 존재하지 않습니다. 공유 볼륨(NFS, 오브젝트 스토리지 등)을 모든 워커에 동일하게 마운트하세요.

워커 간 환경변수와 시간대(TZ)를 동일하게 통일

환경변수 불일치 → 사용자가 어느 워커에 붙느냐에 따라 다른 동작
시간대(TZ) 불일치 → 스케줄·감사 로그 시간이 워커마다 어긋남

모든 워커가 같은 환경변수 세트와 같은 TZ로 기동되는지 확인하세요.

컨테이너 기동을 직렬화해 마이그레이션 충돌 방지

항목	미준수 시 영향
Alembic 마이그레이션 1회만	다중 워커 동시 실행 시 충돌 (최신 버전에서 lock으로 fix)

Alembic 마이그레이션 충돌은 최신 버전에서 자동 lock으로 해결되었지만, 컨테이너 시작 순서를 직렬화(예: 첫 워커 시작 후 헬스체크 통과를 기다려 나머지 워커 기동)하면 더 안전합니다.

Redis Sentinel · Cluster로 단일 장애점 제거 (권장)

권장 단일 Redis 인스턴스는 장애 시 전체 서비스 중단으로 이어집니다. Sentinel 또는 Cluster 구성으로 고가용성을 확보하세요. 설정은 REDIS_SENTINEL_HOSTS / REDIS_SENTINEL_PORT를 사용합니다.

선택 사용하는 기능만

SSO / OIDC 연동 설정

OAuth/OIDC SSO를 활성화하려면 다음 환경변수를 설정합니다 (Keycloak, Entra ID, Google 모두 동일 인터페이스).

OPENID_PROVIDER_URL=https://auth.example.com/realms/cloosphere/.well-known/openid-configuration
OAUTH_CLIENT_ID=cloosphere-app
OAUTH_CLIENT_SECRET=<strong-secret>
OAUTH_SCOPES="openid email profile"
OAUTH_PROVIDER_NAME=Keycloak

변수	용도
`OPENID_PROVIDER_URL`	OIDC Discovery URL (`.well-known/openid-configuration`)
`OAUTH_CLIENT_ID`	IdP에 등록한 클라이언트 ID
`OAUTH_CLIENT_SECRET`	클라이언트 시크릿
`OAUTH_SCOPES`	요청 스코프 (`openid email profile`이 기본)
`OAUTH_PROVIDER_NAME`	UI 로그인 화면에 표시될 Provider 이름

Keycloak 조직 동기화(add35ab42 이후): client_credentials grant flow로 동작. 위 환경변수가 모두 설정되어 있으면 조직 관리 화면에서 Keycloak 동기화 옵션이 활성화됩니다.

자세한 내용은 일반 설정의 인증 항목 참조.

Teams 봇 등록 · 매니페스트 업로드

Microsoft Teams 봇을 운영하려면:

TEAMS_BOT_APP_ID=<Azure Bot Client ID>
TEAMS_BOT_APP_PASSWORD=<Client Secret>
TEAMS_BOT_TENANT_ID=common  # 또는 단일 테넌트 GUID
TEAMS_BOT_ENABLED=true
TEAMS_BOT_BACKEND_TIMEOUT=300
TEAMS_BOT_DEFAULT_LOCALE=ko-KR

Teams 봇은 멀티워커 환경에서 Redis 필수. 사용자별 에이전트 선택 상태가 워커 간 공유되어야 합니다.

상세 설정은 Teams 봇 가이드 참조.

AGE 풀 크기를 KG 데이터 규모에 맞춰 조정 (권장)

권장 Knowledge Graph를 사용한다면 데이터 규모에 맞춰 연결 풀을 조정하세요.KG fan-out 추출은 동시 연결을 많이 사용하므로, 데이터 규모가 크면 풀 고갈로 sync가 실패할 수 있습니다. 규모에 맞춰 풀 크기를 조정하세요.

변수	기본값	< 10M 노드	10M~100M 노드	> 100M 노드
`AGE_POOL_MIN`	2	2	4	8
`AGE_POOL_MAX`	32	16	32 (기본값)	64+

풀 고갈 시 Cloosphere는 5회 지수 백오프 재시도 (0.1s × 2^attempt)를 자동 수행합니다. 로그에 [age_service] pool initialized가 보이면 정상 초기화. PoolError 또는 connection pool exhausted가 반복되면 풀 크기를 한 단계 올리세요.

권장 모니터링 · 백업

/health 엔드포인트를 외부 모니터링에 등록

Cloosphere는 외부 모니터링(Prometheus, Datadog, Azure Monitor 등)과 연동할 수 있는 health endpoint를 제공합니다.

Endpoint	용도	인증
`GET /health`	기본 liveness 체크	없음
`GET /health/db`	DB 연결 상태 (503 + error detail if down)	없음
`GET /health/redis`	Redis ping (503 if unavailable)	없음
`GET /health/full`	DB + Redis + TaskQueue 종합 상태	Admin

응답 예시:

GET /health/full

{
  "status": true,
  "components": {
    "db": { "status": true },
    "redis": { "status": true, "mode": "redis" },
    "task_queue": { "status": "connected", "stream": "cloosphere:tasks" }
  }
}

관리자 패널의 System Diagnostics 패널에서 /health/full 결과를 GUI로 확인할 수 있습니다. CI/CD readiness probe는 /health/db를, liveness probe는 /health를 사용하길 권장합니다.

감사 로그 라이선스 피처 확인

라이선스에 감사 로그(audit_log) 피처가 포함되어 있어야 운영 활동이 기록됩니다. 활성화 여부와 사용법은 감사 로그를 참조하세요.

일반

GUI로 관리되는 인증·기능 토글

Teams 봇

Microsoft Teams 통합

알림 설정

이메일·웹훅 알림 채널

트러블슈팅

운영 중 자주 보고된 이슈와 해결책

운영 · 지원

필수 모든 환경

멀티워커 워커 2개 이상이면 필수

선택 사용하는 기능만

권장 모니터링 · 백업

관련 페이지

일반

Teams 봇

알림 설정

트러블슈팅

​필수 모든 환경

​멀티워커 워커 2개 이상이면 필수

​선택 사용하는 기능만

​권장 모니터링 · 백업

​관련 페이지

일반

Teams 봇

알림 설정

트러블슈팅

필수 모든 환경

멀티워커 워커 2개 이상이면 필수

선택 사용하는 기능만

권장 모니터링 · 백업

관련 페이지