백업은 만드는 것보다 되돌릴 수 있는지 확인하는 일이 더 중요합니다. 복원해 본 적이 없는 백업은 백업이라고 부르기 어렵습니다. restic은 파일을 암호화해서 저장하고, 같은 내용은 한 번만 저장하며(중복 제거), 저장소가 망가졌는지 점검하는 기능까지 갖춘 오픈소스 백업 도구입니다. 실행 파일 하나로 동작하고 저장소의 모든 데이터가 비밀번호로 암호화됩니다. 이 글에서는 도커로 restic을 실행해 백업, 증가분, 복원 비교, 비밀번호 오류, 오래된 백업 정리, 저장소 손상 감지를 차례로 해 봅니다.
준비물
| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11) |
| restic | 0.19.1 (restic/restic 이미지) |
모든 데이터는 도커 볼륨 안에서만 다룹니다. 백업 원본은 osk_rs_src, 저장소는 osk_rs_repo, 복원 위치는 osk_rs_out입니다. 내 PC의 폴더를 건드리지 않으므로 지우기도 쉽습니다. 실제로 쓸 때는 -v 내폴더:/data:ro처럼 원본을 읽기 전용으로 연결하고, 저장소는 다른 디스크나 다른 장비에 둡니다.
1. 원본 만들기
백업할 파일 일곱 개를 만들었습니다. 문서 다섯 개(한글 한 줄씩), 무작위 내용의 사진 파일 두 개(3MB, 2MB)이고 전체 4,920KB입니다. 무작위 바이트는 압축이나 중복 제거가 되지 않으므로 증가분 시험에 맞습니다.
2. 저장소 만들기와 첫 백업
restic -r /repo init
restic -r /repo backup --host lab /data
비밀번호는 환경 변수 RESTIC_PASSWORD로 넘깁니다(이 글에서는 실습용 값을 썼습니다). init이 저장소를 만들고(created restic repository ...), 첫 백업 결과는 다음과 같았습니다.
| 항목 | 값 |
|---|---|
| 파일 | 7개 새로 추가, 변경 0, 그대로 0 |
| 저장소에 더해진 양 | 4.772 MiB (실제 저장 4.771 MiB) |
--host lab은 호스트 이름을 고정하는 옵션입니다. 도커는 실행할 때마다 컨테이너 이름(호스트 이름)이 달라지는데, restic은 같은 호스트와 같은 경로의 이전 스냅샷을 기준으로 바뀐 파일을 가려냅니다. 이름을 고정하지 않으면 두 번째 백업에서 매번 "전부 새 파일"로 보입니다. 처음에 이름 없이 시험했을 때 "8 new, 0 unmodified"가 나와서 알게 된 점입니다.
3. 저장소 안은 암호화되어 있습니다
저장소 폴더에는 config, data, index, keys, locks, snapshots가 있었습니다. 저장소 전체에서 원본에 들어 있던 한글 문자열 "회의록"을 찾았더니 이 문자열이 든 파일은 0개였습니다. 파일 내용뿐 아니라 이름과 구조도 암호화되어 있다는 뜻입니다. 저장소 파일을 누가 가져가도 비밀번호 없이는 읽을 수 없습니다. 그만큼 비밀번호를 잃으면 복구할 방법이 없습니다. keys 폴더의 키 파일도 비밀번호로 보호됩니다.
4. 두 번째 백업: 바뀐 부분만 저장됩니다
문서 하나를 추가하고(note6.txt) 다른 문서 하나에 한 줄을 덧붙인(note1.txt) 뒤 다시 백업했습니다.
| 항목 | 첫 백업 | 두 번째 백업 |
|---|---|---|
| 파일 | 7 새로 | 1 새로, 1 변경, 6 그대로 |
| 저장소에 더해진 양 | 4.772 MiB | 3.146 KiB (실제 저장 1.431 KiB) |
원본은 약 4.8MB 그대로인데 두 번째 백업은 3KB만 더했습니다. 사진 두 개는 바뀌지 않았으므로 다시 저장되지 않았습니다. 매일 백업해도 저장소가 원본 크기의 며칠 치만큼 불어나지 않는 이유입니다. 스냅샷 목록은 각 시점이 4.769 MiB 전체를 가리키지만 실제 데이터는 공유합니다.
5. 복원하고 원본과 비교하기
restic -r /repo restore latest --target /out
diff -r /data /out/data
복원은 11개 파일과 폴더(4.769 MiB)를 1초 안에 끝냈고, diff -r은 아무 차이도 출력하지 않았습니다. 백업 점검에서 가장 기본이 되는 일입니다. 복원해서 원본과 비교하는 일을 주기적으로 자동화합니다.
6. 비밀번호가 틀리면
틀린 비밀번호로 snapshots를 부르자 Fatal: wrong password or no key found로 끝났고, 저장소 내용은 아무것도 보이지 않았습니다.
7. 오래된 스냅샷 정리
스냅샷을 세 개로 늘린 뒤 forget --keep-last 2 --prune을 실행했습니다.
| 단계 | 결과 |
|---|---|
| 정리 전 | 3 snapshots |
| 정책 | keep 2 latest snapshots |
forget |
1개 제거, 이어서 prune이 쓰이지 않는 데이터 3개(1007바이트) 제거 |
| 정리 후 | 2 snapshots |
forget은 스냅샷 목록에서 지우는 것이고, 실제로 공간을 돌려받는 것은 prune입니다. --prune을 붙이면 한 번에 둘 다 합니다. 이 글의 데이터가 작아서 줄어든 용량은 1KB 남짓이었습니다. 정책은 --keep-daily 7 --keep-weekly 4처럼 기간으로도 정합니다. 이 글에서는 --keep-last만 시험했습니다.

8. 저장소가 망가지면: check와 check --read-data
저장소가 저장 장치 오류나 전송 중 문제로 상하는 일에 대비한 점검입니다. 가장 큰 데이터 파일(사진 조각이 든 파일)의 한가운데(100,000바이트 위치)를 영(0) 8바이트로 덮어 일부러 망가뜨렸습니다.
| 점검 | 손상 전 | 손상 뒤 |
|---|---|---|
restic check |
no errors were found | no errors were found |
restic check --read-data |
(시험하지 않음) | 오류 감지: 데이터 파일 하나에 오류 2건, Fatal: repository contains errors |
restic restore latest |
성공 | 일부 실패: pic2.bin을 복호화하지 못함, Fatal: There were 1 errors |
가장 중요한 결과는 첫 줄입니다. 기본 check는 구조(색인과 파일 목록)만 보기 때문에 파일 안쪽이 상한 것을 잡지 못해 "오류 없음"이라고 했습니다. 내용을 다시 읽어 확인하는 --read-data만 ciphertext verification failed로 손상을 찾았습니다. 암호화 저장소는 한 군데만 틀어져도 해당 조각을 복호화하지 못하므로, 상한 조각이 든 파일(pic2.bin)만 복원에 실패하고 나머지는 복원되었습니다.
운영에서는 매일 check를, 주 1회 정도 check --read-data(모든 데이터를 읽어 시간이 걸림)나 일부만 읽는 --read-data-subset=10%를 돌립니다. --read-data-subset은 이 글에서 시험하지 않았습니다.

9. 운영 전에 정할 것
| 항목 | 내용 |
|---|---|
| 비밀번호 보관 | 잃으면 복구 방법 없음. 비밀번호 관리자나 별도 안전한 곳에 보관. 앞의 Vaultwarden 글의 서버도 후보 |
| 저장소 위치 | 원본과 같은 디스크에 두면 디스크 고장에 함께 사라짐. 다른 디스크나 다른 장비, 원격 저장소 사용. 원격 저장소는 이 글에서 시험하지 않음 |
| 복원 연습 | 5절의 복원과 비교를 정해진 주기로 자동 실행 |
| 일정 | restic은 정해진 시간에 스스로 실행되지 않음. 작업 스케줄러나 cron으로 backup, forget --prune, check 호출 |
| 읽기 전용 원본 | 백업 도구가 원본을 바꾸지 못하게 읽기 전용(:ro)으로 연결 |
전체 코드
위 1~8절을 한 번에 실행하는 파일입니다. restic_demo.sh로 저장하고 bash restic_demo.sh로 실행합니다. 이 PC에서는 약 1분이 걸렸습니다. 볼륨 세 개(osk_rs_repo, osk_rs_src, osk_rs_out)를 만들고 끝에서 지웁니다. 같은 이름의 볼륨이 있으면 먼저 지우므로 다른 용도로 쓰는 볼륨과 이름이 겹치지 않는지 확인합니다. 비밀번호는 실습용 값입니다.
#!/usr/bin/env bash
# restic 으로 암호화 백업을 만들고, 두 번째 백업의 증가분, 복원 검증, 저장소 손상 감지, 오래된 스냅샷 정리까지 한다.
# 준비: Docker. restic 은 컨테이너(restic/restic)로 실행하고 모든 데이터는 도커 볼륨 안에서만 다룬다.
# 주의: 볼륨 osk_rs_repo, osk_rs_src, osk_rs_out 을 만들고 끝에서 지운다. 비밀번호는 실습용 값이다.
# 실행(Git Bash): bash restic_demo.sh (약 1분)
set -u
export MSYS_NO_PATHCONV=1
PW="lab-only-restic-pass"
R() { docker run --rm -e RESTIC_PASSWORD="$PW" -v osk_rs_repo:/repo -v osk_rs_src:/data -v osk_rs_out:/out restic/restic -r /repo "$@"; }
SH() { docker run --rm -v osk_rs_repo:/repo -v osk_rs_src:/data -v osk_rs_out:/out alpine sh -c "$1"; }
docker volume rm osk_rs_repo osk_rs_src osk_rs_out >/dev/null 2>&1
docker volume create osk_rs_repo >/dev/null; docker volume create osk_rs_src >/dev/null; docker volume create osk_rs_out >/dev/null
echo "## 1. 백업할 원본 파일 만들기"
SH 'mkdir -p /data/docs /data/photos
for i in 1 2 3 4 5; do echo "회의록 $i: 이 파일은 실습용입니다." > /data/docs/note$i.txt; done
head -c 3000000 /dev/urandom > /data/photos/pic1.bin
head -c 2000000 /dev/urandom > /data/photos/pic2.bin
du -sk /data | cut -f1 | sed "s/^/원본 크기(KB): /"; find /data -type f | wc -l | sed "s/^/파일 수: /"'
echo "## 2. 저장소 만들기(init)와 첫 백업(--host lab 으로 이름을 고정해 이전 스냅샷과 비교되게 한다)"
R init 2>&1 | grep -E 'created restic repository'
R backup --host lab /data 2>&1 | grep -E 'Files:|Added to the repository|snapshot .* saved'
echo "## 3. 저장소 안을 들여다보기: 평문이 보이는가"
SH 'ls /repo | tr "
" " "; echo; grep -r -l "회의록" /repo 2>/dev/null | wc -l | sed "s/^/저장소 파일 중 평문 \"회의록\"이 든 것: /"'
echo "## 4. 파일 하나를 추가하고 하나를 고친 뒤 두 번째 백업(증가분만 저장되는가)"
SH 'echo "회의록 6: 새로 추가한 파일" > /data/docs/note6.txt; echo "수정함" >> /data/docs/note1.txt'
R backup --host lab /data 2>&1 | grep -E 'Files:|Added to the repository|snapshot .* saved'
echo "## 5. 복원하고 원본과 비교(diff)"
R restore latest --target /out 2>&1 | tail -1
SH 'diff -r /data /out/data && echo "원본과 복원본이 같다(diff 결과 없음)"'
echo "## 6. 잘못된 비밀번호"
docker run --rm -e RESTIC_PASSWORD="wrong" -v osk_rs_repo:/repo restic/restic -r /repo snapshots 2>&1 | tail -1
echo "## 7. 스냅샷을 세 개로 늘리고 두 개만 남기도록 정리(forget --keep-last 2 --prune)"
SH 'echo "회의록 7" > /data/docs/note7.txt'
R backup --host lab /data 2>&1 | grep -E 'snapshot .* saved'
R snapshots 2>&1 | grep -E 'snapshots$'
R forget --keep-last 2 --prune 2>&1 | grep -E 'keep|remove|snapshots$'
R snapshots 2>&1 | grep -E 'snapshots$'
echo "## 8. 저장소 점검(check)과 손상 감지(check --read-data)"
R check 2>&1 | tail -1
SH 'f=$(ls -S /repo/data/*/* | head -1); echo "가장 큰 데이터 파일을 손상시킨다: $(basename $f | cut -c1-16)..."; head -c 8 /dev/zero | dd of=$f bs=1 seek=100000 conv=notrunc 2>/dev/null'
echo "-- 기본 check (구조만 본다)"
R check 2>&1 | tail -1
echo "-- check --read-data (내용까지 읽는다)"
R check --read-data 2>&1 | grep -E 'Fatal|ciphertext verification failed' | head -2 | cut -c1-150
echo "-- 손상된 저장소에서 복원 시도"
R restore latest --target /out2 2>&1 | grep -E 'Fatal|error|ciphertext' | head -2 | cut -c1-150
docker volume rm osk_rs_repo osk_rs_src osk_rs_out >/dev/null && echo "## 정리: 시험 볼륨 삭제"
자주 막히는 곳
| 증상 | 원인과 해결 |
|---|---|
| 두 번째 백업에서도 모든 파일이 "새 파일"로 나옴 | 도커가 호스트 이름을 매번 바꾸기 때문. --host 이름을 고정 |
Fatal: wrong password or no key found |
비밀번호가 틀렸거나 저장소가 아닌 폴더를 가리킴. -r 경로 확인 |
| Git Bash에서 볼륨 경로가 이상하게 바뀜 | export MSYS_NO_PATHCONV=1을 먼저 실행 |
check는 통과했는데 복원이 실패함 |
check --read-data로 내용까지 확인. 8절 참고 |
| 한글이 깨져 보임 | 터미널 인코딩 문제. 저장된 데이터와는 무관 |
확인 범위
- 해 본 것: 2026-10-29, Windows 11 · Docker 29.5.3 · restic 0.19.1에서 저장소 만들기, 백업 두 번(증가분 확인), 복원과
diff -r, 틀린 비밀번호, 세 번째 백업과forget --keep-last 2 --prune, 일부러 손상시킨 저장소에서check,check --read-data, 복원을 실행했습니다. 끝난 뒤 볼륨을 모두 지웠습니다. - 해 보지 않은 것: 원격 저장소(SFTP, S3 등), 기간 기반 보관 정책,
--read-data-subset, 마운트(restic mount), 대용량 데이터의 속도, 저장소 비밀번호 변경, 여러 키 관리, Linux와 macOS. - 읽을 때 주의: 원본이 4.8MB뿐이라 속도와 용량 수치는 참고만 합니다. 손상은 파일 한 곳을 덮어쓴 인위적인 시험이며, 실제 저장 장치 오류의 모양은 다를 수 있습니다.
이 글은 스타트업·소규모 조직 보안 구축 로드맵의 한 단계입니다.
이 글의 다음 단계
- Open WebUI Ollama 연결: host.docker.internal:11434 고치기Docker로 Open WebUI를 띄워 호스트의 Ollama에 연결하고, 주소를 localhost로 잘못 넣어 모델 목록이 비는 상태를 만든 뒤 원인을 찾아 고칩니다. 환경 변수를 바로잡아도 저장된 설정이 우선해 되돌아오지 않는 동작도 직접 확인합니다.
- Hermes Agent를 호스트가 아닌 Docker 컨테이너에 설치하고 첫 실행하기명령을 직접 실행하는 오픈소스 에이전트 Hermes Agent를 Ubuntu 컨테이너 안에 설치 스크립트로 설치하고, 첫 실행 화면, hermes doctor 점검, ~/.hermes 데이터 폴더 구조, 웹 대시보드 로그인까지 직접 확인합니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com