Galpi

운영

시스템 관리 화면, 로그인과 OIDC, 예산, 백업과 복원, 업데이트, 점검 모드, 관리자 복구, 데이터베이스를 다뤄요.

시스템 관리

계정 메뉴의 시스템 관리는 따로 여는 영역이에요("Galpi / 시스템 관리"). 왼쪽 목록은 이렇게 묶여 있어요.

묶음 항목
개요(서비스 상태: VM, 모델, 메일, 보관소, VM 풀, 노드 알림, 오류 보고)
사람과 프로젝트 프로젝트, 사람, 지운 채팅, 접근 잃은 채팅
자원 VM(또는 노드), 사용량
운영 스킬, 연동 서비스, MCP, 시크릿, 감사 기록, 설정
시스템 관리 → 개요. 설정이 빠진 곳은 "알 수 없음"으로 보여요.시스템 관리 → 개요. 설정이 빠진 곳은 "알 수 없음"으로 보여요.
시스템 관리 → 개요. 설정이 빠진 곳은 "알 수 없음"으로 보여요.
시스템 관리 → 사용량.시스템 관리 → 사용량.
시스템 관리 → 사용량.

로그인: 이메일 코드와 OIDC

사람에게 비밀번호가 없어요. 로그인 방식(LOGIN_METHODS)은 email(기본), oidc, email,oidc 중에서 골라요.

  • 이메일 코드: 6자리 코드와 링크를 같이 보내요. 링크는 여는 것만으로 로그인시키지 않고, 누가 요청했는지(브라우저, 운영체제, IP, 시각)를 보여 준 뒤 "예, 로그인할게요"를 물어요. SMTP_URL이 없으면 메일은 서버 로그에 남아요.
  • OIDC(사내 계정): OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET을 넣어요. 콜백은 <PUBLIC_URL>/api/auth/oidc/callback이에요. email_verified가 true인 주소만 받아요.
설정 뜻
OIDC_SCOPES 기본 openid email profile. 그룹이 범위를 요구하면 더해요
OIDC_LABEL 버튼 이름. 비우면 "사내 계정으로 로그인"
OIDC_ALLOWED_DOMAINS 받을 이메일 도메인
OIDC_PROVISION auto: 처음 온 사람의 계정을 바로 만들어요. invite: 초대받았거나 계정이 있는 사람만

세션은 쓰는 동안 이어지고 30일 동안 쓰지 않으면 끝나요. 바로 내보내야 하는 사람은 시스템 관리 → 사람에서 정지해요.

관리자

시작할 때 ADMIN_EMAILS(쉼표로 여러 개)의 사람이 시스템 관리자가 돼요. 화면에서는 시스템 관리 → 설정 → 시스템 관리자에서 더해요.

관리자가 모두 잠겼을 때(메일이 안 오거나, OIDC가 깨졌거나, 정지됐을 때)는 서버 안에서 복구 명령을 써요. 1시간 동안 한 번 쓸 수 있는 로그인 링크를 찍어요.

bash
docker compose exec galpi galpi-recover admin@example.com

예산

프로젝트와 사람마다 기간(하루, 한 주, 한 달)별로 쓸 양을 정해요. 기본은 꺼져 있고, 시스템 관리 → 설정 → 예산에서 켜요.

항목 세는 법
토큰 입력 + 출력(추론 포함) + 캐시 쓰기 + 캐시 읽기의 1/10. OpenCode가 센 값과 모델 중계가 센 값 가운데 큰 쪽
VM CPU 켜져 있던 시간 × vCPU
VM 메모리 켜져 있던 시간 × 메모리
저장 공간 지금 쥔 파일(첨부, 공유, 보관본)

경고 비율에 닿으면 알리고, 한도에 닿으면 새 질문을 받지 않아요. 답하는 도중에 닿으면 중계가 다음 모델 호출을 거절해 그 답은 거기서 끝나요. 기간은 UTC 기준이에요.

모델 호출은 시작할 때 쓸 양을 미리 잡아 둬요(예약). 쓴 양은 한도 아래인데 같은 프로젝트에서 돌고 있는 다른 답변들의 예약까지 더하면 넘을 때는, 채팅에 "이 프로젝트의 다른 답변이 예산을 잡고 있어서 기다리는 중이에요"가 보이고 잠시 뒤 다시 불러요. 5분 넘게 기다리면 그 답변을 멈추고 다시 보내 달라고 알려요. 지금 잡혀 있는 예약은 시스템 관리 → 상태의 "모델 호출 예약"에 보여요.

점검 모드

시스템 관리 → 설정 → 점검 모드를 켜면 바로 적용돼요. 시스템 관리자만 들어오고, 다른 사람은 점검 안내를 보며 API는 503(code: maintenance)으로 답해요.

백업과 복원

S3가 있으면 갈피 DB(SQLite)를 두 가지로 지켜요. 시스템 관리 → 설정 → DB 백업에서 보고 정해요.

계속 복제 (Litestream) 전체 사본
무엇 바뀐 내용을 1초쯤 뒤에 올려요 DB 전체를 정해진 간격마다
서버를 잃으면 마지막 몇 초만 잃어요 마지막 사본 뒤를 잃어요
되돌릴 수 있는 때 최근 LITESTREAM_RETENTION_HOURS(기본 168시간) 안의 아무 시점 남은 사본의 시각
보관 스냅샷 LITESTREAM_SNAPSHOT_HOURS(기본 24)마다 최근 BACKUP_KEEP(4), 하루 BACKUP_KEEP_DAILY(7), 주 BACKUP_KEEP_WEEKLY(4), 달 BACKUP_KEEP_MONTHLY(6)

둘 다 잠긴 비밀값을 그대로 담아요. 되살리려면 같은 SECRETS_KEY가 필요해요. 채팅 VM의 보관본은 VM이 S3와 바로 주고받고, 서버는 몇 분짜리 링크에 서명만 해요. 갈피 안 저장소(Forgejo)는 forgejo-backup이 따로 S3에 올려요.

노드(E2B·Sysbox)에서는 잠든 VM의 사본도 호스트 밖 S3에 떠 둬요. 사본은 줄을 서서 만들어요. 노드마다 한 번에 2개씩, 깨어 있는 VM부터 만들고, 잠든 VM은 사람이 쓸 자리를 남겨 두고 깨워요. 새 VM을 기다리는 사람이 있으면 그 노드에서는 사본을 시작하지 않아요. **시스템 관리 → 설정 → 파일 저장소(S3)**에 "VM 사본: 채팅 M개 중 N개가 최신이에요"와 노드마다 기다리는 수와 까닭이 보여요.

  • 30분 넘게 기다린 사본은 먼저 만들어요. 60분 넘게 기다리면 장애 기록(copies_overdue)과 서비스 상태에 나와요.
  • 기다린 시간은 서버 메모리에만 있어서, 서버가 다시 시작하면 처음부터 세요.

보관소에서 지운 것 남겨 두기

갈피가 보관소에서 지우기로 정한 것은 바로 지우지 않고 정한 기간(기본 7일) 동안 남겨 두었다가 매시간 정리 때 지워요. 새 사본이 바꾼 예전 보관본, 어느 사본도 쓰지 않는 files/의 파일, 정리 작업이 지운 채팅의 보관본 같은 것들이에요. 사람이 직접 지운 채팅은 언제나 바로 지워요.

기간과 한도는 시스템 관리 → 설정 → 보관과 한도의 "보관소에서 지운 것을 실제로 지우기까지(일)"과 "남겨 둔 지운 것 전체의 한도(GB)"에서 바꿔요. 환경 변수 RETAINED_DELETION_DAYS, RETAINED_DELETION_MAX_GB로도 정할 수 있고, 화면에서 저장한 값이 환경 변수보다 앞서요. 저장하면 칸 옆에 "다시 시작하면 적용"이 붙고, 같은 화면의 서버 다시 시작으로 적용해요.

시스템 관리 → 설정 → 보관과 한도. 남겨 두는 기간과 한도를 여기서 바꿔요.시스템 관리 → 설정 → 보관과 한도. 남겨 두는 기간과 한도를 여기서 바꿔요.
시스템 관리 → 설정 → 보관과 한도. 남겨 두는 기간과 한도를 여기서 바꿔요.
  • 그동안 시스템 관리자는 채팅 보기에서 예전 사본으로 이 사본으로 되살리기(다음 질문 때 그 사본으로 돌아가요)나 남겨 두기(놓아 줄 때까지 지우지 않아요)를 할 수 있어요.
  • 남겨 둔 것은 어느 예산에도 세지 않고 시스템 관리 → 사용량의 "남겨 둔 지운 것"에 따로 보여요. 보관소 크기를 정할 때 일주일 치 바뀐 양을 더해 두세요.
  • 모두 합해 한도(기본 100GB)를 넘으면 가장 오래된 것부터 일찍 지우고 장애 기록(retained_capped)으로 알려요. 기간이 0이면 바로 지우고, 한도가 0이면 한도가 없어요.
  • 어느 값이든 채팅이 지금 쓰는 것(지금 보관본과 그것이 가리키는 파일)은 지우지 않아요.

업데이트

bash
cd <갈피 저장소> && git pull          # 노드 소프트웨어(node-kit/)도 같이 와요
deploy/build.sh && cd deploy && docker compose up -d --build

CI는 이미지를 만들어 확인만 하고 어디에도 올리지 않아요. 다른 곳에서 만든 이미지를 받아 쓰려면, 만드는 쪽이 깨끗하게 커밋한 저장소에서 deploy/offline-images.sh --out galpi-images.tar(이미지 파일 하나)나 deploy/package-release.sh <출력 폴더>(이미지, 런타임 번들, 체크섬을 한 번에)로 묶어요. 받는 서버에서는 이렇게 해요.

bash
docker load -i galpi-images.tar      # 들인 이미지의 이름을 알려 줘요
# deploy/.env의 GALPI_IMAGE, FORGEJO_BACKUP_IMAGE를 그 이름으로 바꾸고
cd deploy && docker compose up -d    # 사내 이미지 저장소에서 받으면 먼저 docker compose pull

버전을 고정하려면 이미지에 버전 태그를 붙여 만들고(GALPI_IMAGE=galpi:1.2.3 deploy/build.sh) 그 태그를 써요. 되돌릴 때도 태그만 바꿔요.

  • DB 변경(마이그레이션)은 갈피가 뜨면서 해요. SQLite면 그 전에 DATA_DIR/pre-migration/에 사본을 떠 둬요(최근 3개).
  • 노드 소프트웨어는 시스템 관리 → 노드에서 노드마다 올려요.
  • 화면의 다시 시작은 서버를 종료 코드 75로 끝내고 컨테이너의 재시작 정책이 다시 띄워요.

데이터베이스

DATABASE_URL이 없으면 DATA_DIR의 SQLite를 쓰고, S3가 있으면 Litestream으로 복제해요. PostgreSQL 주소를 넣으면 SQLite용 백업은 저절로 꺼지고 PostgreSQL의 백업을 써요. 큰 설치(수천 명)는 PostgreSQL을 권해요. 기존 SQLite에서 옮기는 도구와 순서는 갈피 저장소의 docs/database.md에 있어요.

bash
# PostgreSQL: 설치마다 전용 DB와 사용자를 미리 만들고, 주소는 비밀 설정으로 넣어요
DATABASE_URL=postgresql://galpi:…@db:5432/galpi
  • DB 하나에는 갈피 서버 프로세스를 하나만 띄워요. 서버는 시작할 때 DB에 잠금을 잡고, 다른 갈피 서버가 살아 있으면 30초쯤 기다려 본 뒤 시작하지 않아요. 죽은 서버의 잠금은 길어야 30초쯤 뒤에 넘겨받아요.
  • DATABASE_URL은 PostgreSQL에 직접 연결하거나 세션 모드 풀러여야 해요. 트랜잭션 모드 풀러(PgBouncer pool_mode = transaction 등)로는 잠금을 지킬 수 없어서, 갈피가 시작할 때 알아보고 시작하지 않아요.
  • 갈피의 PostgreSQL 사용자는 슈퍼유저가 아니어도 돼요. 자기 DB의 소유자면 충분해요.
Esc