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시간 동안 한 번 쓸 수 있는 로그인 링크를 찍어요.
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이면 한도가 없어요. - 어느 값이든 채팅이 지금 쓰는 것(지금 보관본과 그것이 가리키는 파일)은 지우지 않아요.
업데이트
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 <출력 폴더>(이미지, 런타임 번들, 체크섬을 한 번에)로 묶어요. 받는 서버에서는 이렇게 해요.
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에 있어요.
# PostgreSQL: 설치마다 전용 DB와 사용자를 미리 만들고, 주소는 비밀 설정으로 넣어요
DATABASE_URL=postgresql://galpi:…@db:5432/galpi
- DB 하나에는 갈피 서버 프로세스를 하나만 띄워요. 서버는 시작할 때 DB에 잠금을 잡고, 다른 갈피 서버가 살아 있으면 30초쯤 기다려 본 뒤 시작하지 않아요. 죽은 서버의 잠금은 길어야 30초쯤 뒤에 넘겨받아요.
DATABASE_URL은 PostgreSQL에 직접 연결하거나 세션 모드 풀러여야 해요. 트랜잭션 모드 풀러(PgBouncerpool_mode = transaction등)로는 잠금을 지킬 수 없어서, 갈피가 시작할 때 알아보고 시작하지 않아요.- 갈피의 PostgreSQL 사용자는 슈퍼유저가 아니어도 돼요. 자기 DB의 소유자면 충분해요.
관리자 권한을 잃었을 때 · 관리자 복구 · 로그인이 안 될 때 · 비밀번호 · 비밀번호 찾기 · 잠김