> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 배포 체크리스트

> 운영 환경 배포 시 반드시 점검해야 할 환경변수, 멀티워커 설정, 외부 의존성, 모니터링 endpoint 가이드.

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

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

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

***

### <span className="cloo-badge cloo-badge--required">필수</span> 모든 환경

<AccordionGroup>
  <Accordion title="CLOOSPHERE_PUBLIC_URL을 외부 HTTPS FQDN으로 지정" icon="square-check">
    | 변수                          | 용도                                                              | 예시                                  |
    | --------------------------- | --------------------------------------------------------------- | ----------------------------------- |
    | **`CLOOSPHERE_PUBLIC_URL`** | 외부 접근 base URL. 임베드 위젯 callback, 매니페스트 validDomains 자동 계산 등에 사용 | `https://cloosphere.yourdomain.com` |
    | **`CLOOCUS_PUBLIC_URL`**    | SR(서비스 요청) 기능의 공개 base URL. `SR_KEY`와 함께 설정하면 SR이 활성화됨          | `https://cloosphere.yourdomain.com` |

    <Warning>
      `CLOOSPHERE_PUBLIC_URL` 미설정 시:

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

      (SR 기능은 `CLOOCUS_PUBLIC_URL`+`SR_KEY`로 별도 제어됩니다.)

      반드시 **HTTPS 공개 FQDN**으로 지정. 프록시(Nginx/Cloudflare) 뒤에 있으면 외부에서 보이는 URL을 입력.
    </Warning>
  </Accordion>

  <Accordion title="DATABASE_URL로 PostgreSQL 연결 확인" icon="square-check">
    | 변수                |                               등급                               | 용도                            |
    | ----------------- | :------------------------------------------------------------: | ----------------------------- |
    | `DATABASE_URL`    |   <span className="cloo-badge cloo-badge--required">필수</span>  | PostgreSQL 연결 문자열             |
    | `DATABASE_SCHEMA` | <span className="cloo-badge cloo-badge--recommended">권장</span> | 멀티 테넌트 시 스키마 분리 (기본 `public`) |

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

  <Accordion title="Alembic 마이그레이션을 올바른 스키마에 최신 버전으로 적용" icon="square-check">
    배포한 코드 버전과 DB 스키마 버전이 일치해야 합니다. 마이그레이션 누락 시 런타임에 컬럼/테이블 부재 오류가 발생합니다.

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

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

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

***

### <span className="cloo-badge cloo-badge--multiworker">멀티워커</span> 워커 2개 이상이면 필수

<AccordionGroup>
  <Accordion title="REDIS_URL 설정 (PersistentConfig 동기화 · 세션 공유)" icon="square-check">
    | 변수                     |                                등급                                | 용도                    |
    | ---------------------- | :--------------------------------------------------------------: | --------------------- |
    | `REDIS_URL`            | <span className="cloo-badge cloo-badge--multiworker">멀티워커</span> | 멀티워커 환경 필수, 단일 워커는 선택 |
    | `REDIS_SENTINEL_HOSTS` |    <span className="cloo-badge cloo-badge--optional">선택</span>   | Redis Sentinel 사용 시   |
    | `REDIS_SENTINEL_PORT`  |    <span className="cloo-badge cloo-badge--optional">선택</span>   | (기본 26379)            |

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

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

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

  <Accordion title="모든 워커가 같은 파일 스토리지 볼륨을 공유하도록 마운트" icon="square-check">
    워커마다 다른 로컬 파일에 접근하면, 한 워커에 업로드한 파일이 다른 워커에서는 존재하지 않습니다. 공유 볼륨(NFS, 오브젝트 스토리지 등)을 모든 워커에 동일하게 마운트하세요.
  </Accordion>

  <Accordion title="워커 간 환경변수와 시간대(TZ)를 동일하게 통일" icon="square-check">
    * **환경변수 불일치** → 사용자가 어느 워커에 붙느냐에 따라 다른 동작
    * **시간대(`TZ`) 불일치** → 스케줄·감사 로그 시간이 워커마다 어긋남

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

  <Accordion title="컨테이너 기동을 직렬화해 마이그레이션 충돌 방지" icon="square-check">
    | 항목                 | 미준수 시 영향                              |
    | ------------------ | ------------------------------------- |
    | Alembic 마이그레이션 1회만 | 다중 워커 동시 실행 시 충돌 (최신 버전에서 lock으로 fix) |

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

  <Accordion title="Redis Sentinel · Cluster로 단일 장애점 제거 (권장)" icon="square-check">
    <span className="cloo-badge cloo-badge--recommended">권장</span> 단일 Redis 인스턴스는 장애 시 전체 서비스 중단으로 이어집니다. Sentinel 또는 Cluster 구성으로 고가용성을 확보하세요. 설정은 `REDIS_SENTINEL_HOSTS` / `REDIS_SENTINEL_PORT`를 사용합니다.
  </Accordion>
</AccordionGroup>

***

### <span className="cloo-badge cloo-badge--optional">선택</span> 사용하는 기능만

<AccordionGroup>
  <Accordion title="SSO / OIDC 연동 설정" icon="square-check">
    OAuth/OIDC SSO를 활성화하려면 다음 환경변수를 설정합니다 (Keycloak, Entra ID, Google 모두 동일 인터페이스).

    ```bash theme={null}
    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 이름                              |

    <Note>
      **Keycloak 조직 동기화**(`add35ab42` 이후): client\_credentials grant flow로 동작. 위 환경변수가 모두 설정되어 있으면 [조직 관리](/ko/admin/organizations) 화면에서 Keycloak 동기화 옵션이 활성화됩니다.
    </Note>

    자세한 내용은 [일반](/ko/admin/settings/general#인증-설정) 설정의 인증 항목 참조.
  </Accordion>

  <Accordion title="Teams 봇 등록 · 매니페스트 업로드" icon="square-check">
    Microsoft Teams 봇을 운영하려면:

    ```bash theme={null}
    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
    ```

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

    상세 설정은 [Teams 봇 가이드](/ko/admin/teams-bot) 참조.
  </Accordion>

  <Accordion title="AGE 풀 크기를 KG 데이터 규모에 맞춰 조정 (권장)" icon="square-check">
    <span className="cloo-badge cloo-badge--recommended">권장</span> Knowledge Graph를 사용한다면 데이터 규모에 맞춰 연결 풀을 조정하세요.

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

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

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

***

### <span className="cloo-badge cloo-badge--recommended">권장</span> 모니터링 · 백업

<AccordionGroup>
  <Accordion title="/health 엔드포인트를 외부 모니터링에 등록" icon="square-check">
    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 |

    응답 예시:

    ```json theme={null}
    GET /health/full

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

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

  <Accordion title="감사 로그 라이선스 피처 확인" icon="square-check">
    라이선스에 감사 로그(`audit_log`) 피처가 포함되어 있어야 운영 활동이 기록됩니다. 활성화 여부와 사용법은 [감사 로그](/ko/monitoring/audit-logs)를 참조하세요.
  </Accordion>
</AccordionGroup>

***

## 관련 페이지

<Columns>
  <Card title="일반" icon="sliders" href="/ko/admin/settings/general">
    GUI로 관리되는 인증·기능 토글
  </Card>

  <Card title="Teams 봇" icon="microsoft" href="/ko/admin/teams-bot">
    Microsoft Teams 통합
  </Card>

  <Card title="알림 설정" icon="bell" href="/ko/admin/notifications">
    이메일·웹훅 알림 채널
  </Card>

  <Card title="트러블슈팅" icon="wrench" href="/ko/troubleshooting">
    운영 중 자주 보고된 이슈와 해결책
  </Card>
</Columns>