Mothership
운영
환경 변수 이름, 회사 SSO, 상태 확인, 백업과 복구, 업그레이드, 회사 데이터 내보내기를 다뤄요.
환경 변수 이름
제품군과 같은 설정은 갈피의 이름을 받아요. 예전 MOTHERSHIP_… 이름도 계속 되고, 둘 다 있으면 예전 이름이 이겨요. 전체 목록은 .env.example과 저장소의 docs/operations.md에 있어요.
| 제품군 이름 | Mothership의 예전 이름 | 뜻 |
|---|---|---|
PUBLIC_URL |
MOTHERSHIP_PUBLIC_URL |
사람들이 여는 주소. 로그인 링크도 이 주소 |
SECRETS_KEY |
MOTHERSHIP_SECRET_ENCRYPTION_KEYS |
회사 자격과 OIDC 비밀을 봉인하는 키. 갈피 모양(openssl rand -base64 32) 또는 Fernet 키, 쉼표로 여러 개(첫 키로 잠그고 나머지로 풀어요) |
ADMIN_EMAILS |
(새로) | 시작할 때마다 운영자가 되는 사람 |
SMTP_URL, MAIL_FROM |
MOTHERSHIP_EMAIL_*, MOTHERSHIP_DEFAULT_FROM_EMAIL |
메일 |
APP_LANG |
(새로) | 기본 언어 ko(기본), en |
S3_* |
MOTHERSHIP_S3_* |
파일 보관소 |
LLM_*, MODE_*_MODEL |
MOTHERSHIP_AI_* |
모델(LLM_API_FORMAT=openai일 때만 읽어요) |
GALPI_URL |
MOTHERSHIP_GALPI_ALLOWED_ORIGINS에 더해요 |
이 갈피가 개발 연결을 요청할 수 있어요 |
NARU_URL |
MOTHERSHIP_TENANT_ALLOWED_INTEGRATION_ORIGINS에 더해요 |
회사 관리자가 이 나루로 외부 도구 연결을 만들 수 있어요 |
그 밖에 자주 쓰는 것: DATABASE_URL(운영은 PostgreSQL), DATABASE_POOL_MAX(프로세스마다 풀, 기본 10), MOTHERSHIP_PROCESS_ROLE(all, web, workers), MOTHERSHIP_TRUSTED_PROXIES, MOTHERSHIP_TENANT_AI_ALLOWED_ORIGINS.
회사 SSO
회사마다 OIDC를 따로 등록해요. 서비스 운영자가 서비스 관리 → 회사에서 회사를 골라 Issuer URL, Client ID, Client secret을 넣고, 공급자에 등록할 Callback URL(…/api/auth/v1/sso/<회사>/callback)을 받아요. 인증된 이메일로 구성원 자동 등록을 켜면 IdP가 확인한 이메일의 사람이 그 회사 구성원이 돼요. 회사 SSO 세션은 그 회사에만 쓰이고, 다른 회사의 접근이나 운영자 권한을 주지 않아요. SSO를 켠 회사가 하나면 로그인 카드 맨 위에 그 버튼이 있고, 둘 이상이면 회사 주소를 물어요.
상태 확인
| 주소 | 확인하는 것 |
|---|---|
GET /healthz/live |
프로세스가 살아 있는지만 |
GET /healthz/ready |
DB, 객체 저장소, 모든 종류의 워커. 안 되면 503과 이유(database_pool_exhausted, workers_unavailable …) |
GET /api/admin/v1/health |
운영자용 워커 상태와 마지막 진행 시각 |
워커는 10초마다 심장 박동을 남겨요. 준비 상태에는 runtime, documents, automation, Knowledge 워커가 하나씩은 살아 있어야 해요(MOTHERSHIP_HEALTH_WORKER_MAX_AGE, 기본 90초).
백업과 복구
암호화 키는 백업과 따로 보관해요. 원래 키 없이 DB만 되살리면 회사 자격을 풀 수 없어요.
# 일관된 백업: 먼저 쓰는 쪽을 모두 멈춰요
docker compose -f deploy/compose.production.yaml stop web workers
docker compose -f deploy/compose.production.yaml run --rm tools manage backup_installation \
--output /backups/before-upgrade --writers-stopped
docker compose -f deploy/compose.production.yaml up -d web workers
docker compose -f deploy/compose.production.yaml run --rm tools manage restore_installation \
--input /backups/before-upgrade --verify-only
PostgreSQL 덤프, S3 객체, 모든 파일의 SHA-256을 남기고, 비밀번호와 키는 넣지 않아요. 되살릴 때는 빈 DB와 빈 버킷·접두어에, 같은 키로, 쓰는 쪽을 멈춘 채 restore_installation을 돌려요. 되살리기 전에 마이그레이션하지 않아요.
정기 백업, 보관 기간, 서명된 운영 알림은 docs/operations-automation.md, 고객 환경의 연동을 확인하는 수락 검사는 docs/deployment-acceptance.md에 있어요.
업그레이드
- DB, 객체 버킷, 비밀값을 백업하고, 되살린 사본에서 마이그레이션을 먼저 확인해요.
- 새 이미지를 빌드하고, 이전 버전의 프로세스를 모두 멈춰요.
migrate를 돌리고web과workers를 띄워요.
이전 릴리스로 돌아갈 때는 그 릴리스가 모르는 마이그레이션이 있는지 확인해요. 앱 릴리스는 회사와 환경마다 고정돼 있어서 플랫폼을 올려도 회사의 앱 버전은 바뀌지 않아요.
회사 데이터
회사 소유자는 회사 관리 → 회사 데이터에서 회사의 데이터 목록을 보고 서명된 내보내기를 받아요. 직원의 회사 전용 레코드도 두 환경 모두 들어가요. 큰 내보내기, 영구 삭제, 선택 복구는 운영자의 export_company, erase_company, restore_company 명령으로 해요(docs/company-data.md).