저장 공간과 백업

OwnGit 서버를 운영하는 사람을 위한 안내입니다. OwnGit이 데이터를 어디에 두는지, 어떻게 백업하고 검사하며 복원하는지 설명합니다. 백업 폴더를 정하기 전에는 OwnGit이 백업을 만들지 않으니 처음 설정을 마치면 바로 예약 백업부터 켜 두세요.

보관된 기록은 강제 푸시나 브랜치 삭제로 작업을 잃지 않게 해 주지만 백업은 아닙니다.

OwnGit이 데이터를 두는 곳

OwnGit을 제거해도 둘 다 남습니다. 더 필요 없으면 직접 지우세요.

상태 디렉터리

• 로컬 디스크에 두세요. 네트워크 공유, FUSE나 9P 파일 시스템, 가상 머신의 공유 폴더에 있는 상태 디렉터리는 거부합니다. WSL에서 보이는 /mnt/c 같은 Windows 드라이브와 Docker Desktop 바인드 마운트도 여기에 해당합니다. 대신 WSL 자체 파일 시스템의 폴더나 Docker 이름 있는 볼륨(named volume)을 쓰세요.
• 비밀번호처럼 보호하세요. 가져오기 인증 정보가 암호화되지 않은 채 들어 있습니다. 이 정보는 OwnGit을 실행하는 계정만 읽을 수 있습니다.
• macOS와 Linux에서는 다른 계정이 바꿔치기할 수 있는 상태 디렉터리를 거부합니다. 출력되는 chmod 명령을 실행하거나 다른 곳을 고르세요.

저장소 폴더

• 다른 디스크나 마운트한 SMB, NFS 공유에 두어도 됩니다.
• 한 번에 OwnGit 서버 하나만 쓸 수 있습니다. 실행 중인 서버가 폴더 안의 .owngit-serve.lock을 잡고 있어서 같은 폴더를 쓰려는 두 번째 서버는 시작하지 않습니다.
• OwnGit을 시작할 때 폴더가 비어 있으면(예: 아직 공유를 마운트하지 않은 마운트 지점) 그 폴더에 처음 저장소를 쓸 때 잠금을 잡습니다.
• OwnGit이 실행 중일 때 폴더나 그 안의 .owngit-serve.lock이 바뀌거나 사라지면 OwnGit은 그 폴더에 쓰기를 멈춥니다. 공유를 그 위에 마운트하거나, 마운트를 해제하거나, 다시 마운트한 경우가 여기에 해당합니다. 이때 푸시, 풀 리퀘스트 변경, 가져오기, 복원, 유지 관리, 저장소 만들기와 삭제, 이름 바꾸기, 기본 브랜치 변경은 모두 거부되고 "OwnGit을 시작한 뒤 저장소 폴더가 바뀌어서 쓰기를 멈췄습니다"라는 안내가 나옵니다. Git과 API에는 HTTP 409로 답하고, 가져오기는 미해결로 기록됩니다. 저장소를 둘러보거나 클론하는 일은 계속됩니다. 쓰려던 폴더가 제자리에 있는지 확인한 다음 OwnGit을 다시 시작하세요. OwnGit이 스스로 폴더를 다시 잡지는 않습니다.
• OwnGit은 자기가 만들지 않은 파일은 건드리지 않습니다. 다만 다음 폴더를 만들 수 있습니다.

저장소 유지 관리

저장소가 바뀐 뒤 5분 동안 아무도 쓰지 않으면 OwnGit이 ref와 객체를 묶어 정리합니다. 매일 정해진 시간대(현지 시각 03:00부터 05:00까지)에는 팩이 20개보다 많은 저장소의 팩을 하나로 합칩니다. 유지 관리는 ref나 보관된 기록을 지우지 않습니다.

설정, 보관과 복구, 저장소 유지 관리에서 바꾸거나 owngit settings set을 쓰세요.

쓰지 않는 객체 정리

쓰지 않는 객체 정리는 어떤 ref로도 닿지 않는 Git 객체를 지웁니다. 보관된 기록을 꺼 둔 상태에서 강제 푸시가 남긴 커밋이 그런 예입니다. 기본값은 꺼짐입니다. 설정, 보관과 복구, 쓰지 않는 객체 정리에서 켜거나 다음 명령을 실행하세요.

owngit settings set --unused-object-cleanup on --cleanup-grace-days 14

• 유예 기간이 지난 객체만 지웁니다. 기본 14일이며 2일부터 365일까지 정할 수 있습니다. 지운 객체는 되살릴 수 없습니다.
• 브랜치, 태그, 보관된 기록, 풀 리퀘스트가 아직 닿는 것은 지우지 않습니다.
• 유지 관리가 켜져 있을 때만 매일 밤 유지 관리 시간대에 실행됩니다.
• 서버에 Git 2.37 이상이 있어야 합니다.

푸시한 비밀값에 보관된 기록이 아직 닿으면 정리해도 남습니다. 푸시한 비밀값을 보세요.

예약 백업

백업 폴더를 정하고 예약 백업을 켜세요. 대시보드에서는 설정, 보관과 복구, 백업에서 합니다. 명령줄에서는 다음과 같이 합니다.

owngit backup schedule set \
  --destination /absolute/path/to/backups \
  --server http://127.0.0.1:7654 --accept-insecure-http \
  --password-file /path/to/admin-password.txt

저장하면 첫 백업이 바로 시작됩니다.

owngit backup의 schedule, now, status, runs, check, download, upload 명령은 실행 중인 서버에 요청을 보냅니다. 모두 --server와, 관리자 비밀번호를 담은 --password-file이 필요합니다(비밀번호 파일은 운영 안내에 있습니다). http:// 주소라면 --accept-insecure-http도 붙여야 합니다. 아래 예시에서는 이 옵션들을 생략합니다.

• owngit backup schedule show는 예약 설정을 보여 줍니다. owngit backup schedule off는 예약 백업을 멈춥니다. 이미 만든 백업은 남습니다.
• 예약 백업은 OwnGit이 실행 중일 때만 돕니다. 예정 시각에 OwnGit이 꺼져 있었다면 다시 켤 때 백업을 한 번 합니다.
• 실패한 예약 백업은 다음 간격이 될 때까지 다시 시도하지 않습니다. 바로 다시 하려면 owngit backup now를 실행하세요.
• --verify on이면 새 백업마다 시스템 임시 폴더에서 복원을 연습해 봅니다. 그 디스크에 저장소가 다 들어갈 공간이 있어야 합니다. 2시간 안에 끝나지 않은 검사는 실패로 처리합니다.

지금 백업하기

보관과 복구 탭에서 "지금 백업"을 누르거나 다음을 실행하세요.

owngit backup now

예약 백업을 꺼 두었어도 예약 설정의 폴더로 백업합니다. 명령은 끝나기를 기다리지 않고 바로 돌아옵니다. 백업, 검사, 올리기는 한 번에 하나만 진행됩니다.

백업 확인하기

status는 running, succeeded, failed, interrupted 중 하나입니다. verification은 passed, failed, not_run 중 하나이고 passed일 때만 검사를 통과한 백업입니다. 대시보드의 현재 상태와 백업 기록에도 같은 내용이 나옵니다.

OwnGit이 남기는 백업

백업 하나는 대상 폴더 안에 새 폴더 owngit-backup-YYYYMMDD-HHMMSS-XXXXXXXX로 생깁니다(시각은 UTC 기준 시작 시각). 백업이 성공하면 가장 최근 백업을 --keep개, 그리고 검사를 통과한 가장 최근 백업을 하나 남기고 그 폴더에서 OwnGit이 만든 더 오래된 백업을 지웁니다.

• OwnGit은 자기가 만들고 기록한 백업만 지웁니다. 폴더의 다른 파일은 그대로 둡니다. 파일을 추가하는 식으로 손댄 백업 폴더도 지우지 않고 다음 백업의 메시지에 그 이름을 적습니다.
• 검사에 실패한 백업은 --keep 개수에 넣지 않으며, 검사를 통과한 백업 대신 남는 일도 없습니다. 살펴볼 수 있게 가장 최근 것 하나만 남기고 그보다 오래된 실패 백업은 지웁니다. 남긴 실패 백업도 다음에 검사를 통과한 백업이 생기면 지웁니다. 시간 제한을 넘기거나 임시 공간이 모자라 끝나지 못한 검사도 실패로 봅니다.
• 오래된 실패 백업을 지우지 못하면 실패한 백업의 메시지에서 실패 이유 뒤에 그 사실을 적습니다. 다음 백업 때 다시 지워 봅니다.
• 다른 이유로 실패하거나 중단된 백업 뒤에는 아무것도 지우지 않습니다.
• 새 백업을 다 쓴 뒤에 옛 백업을 지우므로 폴더에는 백업 하나가 더 들어갈 공간이 있어야 합니다. 여유 공간이 마지막 백업 크기보다 작으면 백업은 not enough free space in DIR 메시지와 함께 바로 실패합니다.

백업 내려받기

백업 기록에서 원하는 백업의 내려받기를 누르거나 다음을 실행하세요.

owngit backup download --run ID --output /path/to/new-file.tar

이 .tar 파일에는 모든 저장소와 OwnGit 기록, 비밀번호 해시가 들어 있습니다. 백업 폴더처럼 다른 사람이 볼 수 없는 곳에 두세요. 다른 컴퓨터에서 검사하려면 tar -xf FILE로 푼 뒤 생긴 폴더에 owngit backup verify를 실행하세요.

멈춘 OwnGit 백업하기

OwnGit이 꺼져 있을 때는 직접 백업합니다. 출력 폴더는 아직 없어야 합니다.

owngit backup --state-dir /path/to/owngit-state --output /path/to/new-backup

그 상태 디렉터리로 OwnGit이 실행 중이면 이 명령은 offline_required로 거부됩니다. 그때는 owngit backup now를 쓰세요.

백업에 들어가는 것

백업은 manifest.json 하나와 저장소마다 하나씩 있는 Git 번들이 든 폴더입니다. 다음이 들어갑니다.

• 모든 브랜치와 태그, 그 밖의 ref, 보관된 기록, 저장소별 HEAD와 설정
• 풀 리퀘스트, 리뷰, 작업(task), 체크, 체크 정책, 가져오기 원본
• 접근 방식과 비밀번호 해시

ref나 HEAD가 닿는 커밋만 백업에 들어갑니다. 보관된 기록을 꺼 두었다면 강제 푸시로 덮어쓴 커밋은 이후 백업에 없습니다.

로그인 상태, 네트워크 설정, 체크 에이전트 토큰, 러너 토큰, 가져오기 인증 정보와 예약, 공유 링크, 자동 체크 실행 동의, 원본 체크 로그, 백업 예약과 기록, 서버 전체 설정은 백업에 들어가지 않습니다. 다시 설정하는 방법은 복원한 뒤에 할 일에 있습니다.

별칭 브랜치(다른 브랜치를 가리키는 브랜치, 곧 Git의 symbolic ref)는 보통 브랜치로 저장됩니다. 백업 메시지에 별칭마다 복원 뒤 다시 연결하는 git symbolic-ref 명령이 나옵니다. 백업 자체에는 대상이 기록되지 않으니 이 메시지를 따로 보관하세요.

다른 저장소의 객체를 빌려 쓰는 저장소(objects/info/alternates)나 부분 클론(partial clone)은 백업할 수 없습니다. 거부 메시지에 해당 저장소 이름이 나옵니다.

푸시한 비밀값

한 번 푸시한 비밀값은 강제 푸시나 브랜치 삭제 뒤에도 저장소의 Git 데이터에 남습니다. ref나 보관된 기록이 그 값에 닿는 동안에는 이후 백업에도 모두 들어갑니다. 저장소를 파일까지 삭제하면 OwnGit에서는 없어지지만 그 전에 만든 백업에는 남아 있습니다. 실수로 푸시한 비밀값은 새것으로 바꾸세요.

백업 검사하기

백업과 실행 중인 서버를 건드리지 않고 그 백업이 복원되는지 확인합니다.

owngit backup verify /path/to/backup

시스템 임시 폴더 안의 비공개 폴더에 복원 전체를 연습해 본 뒤 그 폴더를 지웁니다. 번들마다 SHA-256 해시, ref, git fsck, 데이터베이스를 확인합니다. 서버 비밀번호는 필요 없고 백업을 읽을 수만 있으면 됩니다.

• 종료 상태 0은 검사 통과, 1은 통과하지 못함, 130은 Ctrl+C로 멈춤을 뜻합니다.
• 임시 폴더가 있는 디스크에 저장소가 다 들어갈 공간이 있어야 합니다. 다른 곳에서 연습하려면 --temp-dir DIR을 쓰세요.
• --json을 붙이면 결과를 JSON으로 출력합니다.

해시로 손상은 알아내지만 매니페스트까지 함께 바꿔치기한 백업은 알아내지 못합니다. 백업은 다른 사람이 쓸 수 없는 곳에 두세요.

백업 복원하기

복원은 이미 있는 폴더에는 쓰지 않습니다. 새 상태 디렉터리와 새 저장소 폴더를 만듭니다.

owngit restore \
  --input /path/to/backup \
  --state-dir /path/to/new-owngit-state \
  --repository-root /path/to/new-repositories \
  --verify

--verify를 붙이면 먼저 복원을 연습해서 통과한 백업만 복원합니다. 복원도 끝내기 전에 번들, ref, 기록을 모두 확인하며 실패한 저장소가 있으면 이름을 알려 줍니다.

• 새 저장소 폴더가 있는 디스크에는 모든 번들에 가장 큰 번들 하나를 더한 만큼의 공간이 있어야 합니다. 복원은 이를 먼저 확인합니다.
• Ctrl+C로 복원을 멈추면 만든 것을 지우고 종료 상태 130으로 끝납니다.
• OwnGit은 같은 버전이나 이전 버전이 만든 백업을 복원합니다. 이전 버전은 더 새 버전이 만든 백업을 거부할 수 있습니다.

쓰던 설치를 백업으로 바꾸기

백업 기록에서 원하는 백업의 "이 백업으로 복원"을 누르면 이 서버의 폴더 경로가 채워진 다음 단계가 나옵니다.

1. OwnGit을 멈춥니다. owngit service stop을 실행하거나 owngit serve를 Ctrl+C로 끝냅니다.
2. 지금 쓰는 상태 디렉터리와 저장소 폴더 이름 뒤에 .before-restore를 붙입니다.
3. 화면에 나온 owngit restore ... --verify 명령을 실행합니다. 원래 폴더 이름이 복원 대상입니다. Linux에서 root로 설치해 OwnGit이 owngit 계정으로 실행된다면 명령이 runuser -u owngit --로 시작하니 root로 실행하세요. Windows에서는 PowerShell에서 실행하세요.
4. 리버스 프록시 뒤에서 쓴다면 owngit network set --state-dir <상태 폴더> --base-url <공개 주소> --trusted-proxy <프록시 주소>로 공개 주소와 프록시를 다시 저장합니다. 복원 단계 화면에 상태 폴더를 채운 이 명령이 나오니 복사해서 쓰세요. --state-dir을 붙여야 복원한 상태 폴더에 저장됩니다. 복원하면 네트워크 설정이 초기화되고, 저장한 설정은 다음에 시작할 때부터 적용됩니다.
5. OwnGit을 다시 시작합니다. owngit service start를 실행하거나 전에 시작하던 방법을 쓰세요.

명령은 owngit을 직접 입력하지 말고 화면에서 복사하세요. 압축 파일이나 소스로 설치해서 PATH의 owngit이 지금 OwnGit을 실행하는 프로그램이 아니면, 화면은 프로그램을 전체 경로로 적습니다.

.before-restore 폴더는 직접 지울 때까지 남습니다. 복원한 서버를 확인할 때까지는 지우지 마세요.

내려받은 백업 파일로 복원하기

보관과 복구 탭의 "백업 파일로 복원"에서 .tar 파일을 올리거나 다음을 실행하세요.

owngit backup upload --input /path/to/backup.tar

OwnGit은 올린 백업을 검사합니다. 통과하면 화면에 위의 복원 단계가 나옵니다. 실행할 명령은 owngit backup status의 upload_restore_command에도 나옵니다. 그 명령을 실행하기 전에는 아무것도 바뀌지 않습니다.

• 올린 백업은 상태 디렉터리 안 backup-uploads에 하나만 둡니다. 24시간이 지나거나, OwnGit이 시작하거나, 검사에 실패하면 지웁니다. 그러니 OwnGit을 다시 켜기 전에 복원을 실행하세요.
• 상태 디렉터리가 있는 디스크에 파일 크기보다 1 GiB 이상 여유가 있어야 합니다.
• 브라우저가 이유 대신 연결 오류만 보여 주면 owngit backup upload로 다시 올려 보세요. 이 명령은 이유를 출력합니다.

복원한 뒤에 할 일

복원한 폴더는 다른 용도로 쓰기 전에 먼저 OwnGit으로 한 번 시작하세요. 그런 다음 백업에 들어 있지 않은 것을 다시 설정합니다. owngit restore가 끝날 때 항목마다 어디서 다시 설정하는지 출력합니다.

• 모두 다시 로그인합니다.
• 네트워크 설정, Tailscale 공유, 공유 링크
• 체크 에이전트 토큰과 러너 토큰. 예전 것은 거부되니 새로 만드세요.
• 자동 체크 실행 동의
• 가져오기 인증 정보, 원본별 연결 설정, 가져오기 예약
• 백업 예약. 예전 백업은 목록에서 사라지지만 폴더는 남아 있고 owngit restore로 여전히 복원할 수 있습니다.
• 업그레이드 전 백업이 다시 켜집니다. 꺼 두었었다면 다시 끄세요.
• 서버 전체 설정이 기본값으로 돌아갑니다. 설정 화면이나 owngit settings set으로 다시 정하세요.

리버스 프록시 뒤에서는 네트워크 설정을 다시 저장하기 전까지 OwnGit이 프록시를 거친 화면과 Git 요청을 거부합니다. 응답은 421(unrecognized host)이나 403(origin does not match this server)입니다. owngit network set --state-dir <상태 폴더> --base-url <공개 주소> --trusted-proxy <프록시 주소>로 공개 주소와 프록시를 저장한 뒤 OwnGit을 다시 시작하세요. OwnGit이 기본 위치가 아닌 상태 폴더를 쓴다면 --state-dir을 꼭 붙이세요.

백업이나 복원이 중간에 멈추면

정전 등으로 복원이 뒷정리를 못 하고 멈췄다면 다음과 같이 하세요.

1. 두 복원 대상 어느 쪽으로도 OwnGit을 시작하지 마세요. .owngit-restore-pending 파일도 지우지 마세요.
2. 두 대상과 그 옆의 TARGET.owngit-restore-... 폴더를 모두 다른 곳으로 옮깁니다.
3. 새 폴더로 다시 복원합니다.

멈춘 백업은 interrupted로 기록되며 디스크에 무엇이 남았든 완성된 백업이 아닙니다. 그 옆의 숨김 폴더 .NAME.owngit-backup-...에 끝나지 않은 부분이 들어 있습니다. 중단된 실행이 남긴 폴더가 완전해 보여도 검사를 거치지 않았으니 쓰기 전에 owngit backup verify로 확인하세요.

백업을 둘 수 있는 곳

• macOS와 Linux에서는 백업 폴더와 그 위의 모든 폴더를 다른 계정이 바꿀 수 없어야 합니다. /tmp처럼 sticky 비트가 있는 폴더는 괜찮습니다. 조건에 맞지 않으면 OwnGit이 그 폴더 이름과 고치는 chmod 명령을 알려 줍니다.
• OwnGit을 root나 Windows 관리자 권한으로 실행하는 경우가 아니라면 네트워크 공유에도 백업할 수 있습니다.
• exFAT, FAT, NFS에도 백업은 됩니다. 하지만 저장소를 그런 파일 시스템으로 복원할 수는 없습니다. owngit restore는 파일 시스템 이름을 알리고 아무것도 바꾸지 않은 채 멈춥니다. 저장소는 다른 디스크로 복원하세요. 백업 폴더가 그런 디스크에 있으면 대시보드의 현재 상태에 경고가 나옵니다.
• 복원한 상태 디렉터리는 다른 상태 디렉터리처럼 로컬 디스크에 있어야 합니다.

업그레이드 전 백업

더 새 버전의 OwnGit이 이전 버전의 상태로 시작하면 먼저 상태와 모든 저장소를 백업하고 나서 업그레이드합니다. 백업이 끝나야만 업그레이드합니다.

• 백업은 상태 디렉터리 옆, 그 이름 뒤에 -backups를 붙인 폴더에 생깁니다. 예를 들면 ~/.config/owngit-backups입니다. 그 디스크에 모든 저장소가 들어갈 공간이 있어야 합니다.
• 서버 로그에 백업 위치와 복원 명령이 나옵니다. 백업 안의 owngit-upgrade-backup.txt에도 같은 내용이 있습니다.
• 디스크가 가득 차는 등의 이유로 백업에 실패하면 업그레이드하지 않고 이유를 알리며 멈춥니다. 이전 버전은 그 상태를 그대로 쓸 수 있습니다. 원인을 고친 뒤 다시 시작하세요.
• 이전 버전은 새 버전이 업그레이드한 상태를 거부합니다. 되돌리려면 OwnGit을 멈추고 상태 디렉터리를 다른 곳으로 옮긴 뒤, 출력된 복원 명령을 이전 버전으로 실행하세요.

다른 방법으로 백업하고 있어서 이 백업 없이 업그레이드하려면 다음을 실행하세요.

owngit upgrade-backup off

owngit upgrade-backup on으로 다시 켜고 owngit upgrade-backup으로 지금 설정을 봅니다. 꺼 두었다면 새 버전을 설치하기 전에 직접 백업하세요.

백업을 볼 수 있는 사람

백업은 관리자만 관리합니다. 대시보드의 백업 항목은 관리자로 확인한 브라우저에만 보입니다. 서버에 요청하는 owngit backup 명령에는 관리자 비밀번호가 필요합니다. 코딩 도구는 backup_status MCP 도구로 요약만 받습니다. 이 요약에는 폴더나 저장소 이름, 오류가 나오지 않습니다. owngit backup --output, owngit backup verify, owngit restore는 서버 비밀번호 없이 이 컴퓨터의 파일에 접근할 수 있으면 됩니다.