The review found no procedure for losing the host, restoring the k3s datastore or Gitea, upgrading k3s, or checking the platform after a reboot, and the existing runbooks live outside version control. Add five runbooks and a restart-window procedure in docs/runbooks: after-reboot-checks (clock, k3s and certificates, node, pods in dependency order, public paths, Prometheus, alerts, runner), k3s-datastore-restore, gitea-restore (file-only vs full restore, with the warning that a PITR of the shared database also rewinds Keycloak and tech-log), k3s-upgrade (patch within a minor), host-rebuild (order and the easy-to-miss parts: host name for PV node affinity, Tailscale address in the DNS config, time sync before the first k3s start), and k3s-restart-window (what to apply in the one restart window, with the PriorityClasses first). The docs map gains runbooks/ and design/. Each runbook starts with its preconditions and the commands that check them; on 2026-11-12 the backups they need are not installed yet, and they say so. Risk: documentation only. Restores and the rebuild were not executed. Verification: a fresh subagent with only these files ran every command in after-reboot-checks on the desktop and walked the others read-only; its findings (about 60, e.g. a READY check that missed 0/1 Running pods, `stable` pointing to another minor, a missing pgAdmin directory, time sync after the first k3s start) are fixed here. The revised after-reboot commands were rerun on the desktop and match the text. Every repository path the runbooks name exists on main or in the named PR.
8.3 KiB
Gitea 복원
Gitea의 파일(저장소, 패키지, 첨부, Actions 산출물, app.ini)을 주간 dump에서 되살리는 절차다.
Gitea DB는 dump에 없다(--skip-db). DB는 CNPG 백업에 있다.
전제와 확인 — 하나라도 아니면 이 문서는 아직 못 쓴다
| 전제 | 확인 |
|---|---|
| platform-core checkout이 최신 main이고 호스트 백업(PR #6)이 들어 있다 | cd /home/donghyeon/workspace/platform && git pull --ff-only && ls scripts/validate/gitea-backup-restore-drill.sh |
호스트 백업이 설치됐다(/usr/local/lib/platform-backup, /etc/platform-backup/aistor.env) |
sudo ls /usr/local/lib/platform-backup/lib/host-backup.sh /etc/platform-backup/aistor.env |
| Gitea dump가 하나 이상 있다 | systemctl list-timers platform-gitea-backup.timer --no-pager와 journalctl -u platform-gitea-backup -n 3 --no-pager의 uploaded |
DB까지 되살릴 때: CNPG 백업이 있다(W1, services/platform-postgres-backup) |
kubectl -n platform-data get backup |
| k3s·AIStor가 정상 | after-reboot-checks.md 2~4 |
2026-11-12 현재는 호스트 백업(PR #6)과 CNPG 백업(W1)이 설치되기 전이라 되살릴 백업이 없다.
어느 경우인가
| 경우 | DB | 이 문서 |
|---|---|---|
| A. Gitea PV만 잃었다(DB는 멀쩡) | 그대로 둔다 | 1~6 |
| B. DB도 잃었다(루트 SSD 전체 등) | CNPG로 먼저 되살린다 | 0 → 1~6 |
B의 경고: platform-postgres 하나에 Gitea·Keycloak·tech-log DB가 같이 있다. CNPG를 어떤 시점으로 되돌리면 세 DB가 모두 그 시점으로 간다. dump 시각(일요일 04:00 KST)에 맞추려고 과거로 PITR하면 Keycloak 사용자 변경과 tech-log 글도 그 시각으로 돌아간다. 그래서 B에서도 DB는 가장 최근 시점으로 되살리고, dump 뒤에 만든 저장소는 파일이 없다는 것을 받아들인다(6단계에서 찾아낸다).
0. (B만) DB를 되살린다
W1의 CNPG 백업 문서를 따른다. 끝나면 kubectl -n platform-data get cluster platform-postgres -o jsonpath='{.status.phase}'가
Cluster in healthy state여야 한다.
1. dump를 내려받고 확인한다
sudo -i
TS=$(date +%Y%m%d%H%M)
. /usr/local/lib/platform-backup/lib/host-backup.sh && hb_load_aistor_env
W=$(mktemp -d /var/lib/platform-backup/work/gitea-restore.XXXXXX)
hb_mc "$W" ls "backup/$AISTOR_BUCKET/gitea/"
D=$(hb_mc "$W" ls "backup/$AISTOR_BUCKET/gitea/" | awk '{print $NF}' | grep -E '^gitea-dump-.*\.tar\.gz$' | sort | tail -1); echo "$D"
hb_mc "$W" cp "backup/$AISTOR_BUCKET/gitea/$D" "backup/$AISTOR_BUCKET/gitea/$D.sha256" "backup/$AISTOR_BUCKET/gitea/$D.meta" /work/
[ "$(sha256sum "$W/$D" | awk '{print $1}')" = "$(cat "$W/$D.sha256")" ] && echo checksum-ok
cat "$W/$D.meta"
bash /home/donghyeon/workspace/platform/scripts/validate/gitea-backup-restore-drill.sh --from-file "$W/$D"
hb_mc <폴더> <mc 인자>는 고정된 AIStor client를 그 폴더를/work로 붙여 돌린다.checksum-ok, 그리고 리허설 끝의repositories in dump: N, fsck failures: 0과GITEA RESTORE DRILL PASS..meta의gitea_image가 지금 Deployment 이미지와 같아야 한다:kubectl -n gitea get deploy gitea -o jsonpath='{.spec.template.spec.containers[0].image}'. 다르면 먼저 Gitea를 그 버전으로 맞춘다 (dump를 만든 버전보다 낮은 Gitea로 올리면 DB·파일 형식이 안 맞을 수 있다).
2. 창을 잡고 Gitea를 멈춘다
docker exec gitea-runner docker ps -q | wc -l # 0이어야 한다(CI job 없음)
curl -s -o /dev/null -D - 'https://git.learn.hyeonworks.com/api/v1/repos/search?limit=1' | grep -i '^x-total-count' # 복원 전 공개 저장소 수를 적어 둔다
kubectl -n gitea scale deploy/gitea --replicas=0
kubectl -n gitea wait --for=delete pod -l app.kubernetes.io/name=gitea --timeout=5m
이때부터 git.learn.hyeonworks.com이 내려간다(CI 포함).
3. 지금 PV를 복사해 둔다 (덮어쓰기 전에)
df -h /srv/k3s/ssd # Gitea 데이터는 2026-11 기준 약 370MB
cp -a /srv/k3s/ssd/gitea /srv/k3s/ssd/gitea.before-restore-$TS
PV를 완전히 잃은 경우(빈 폴더)는 건너뛴다.
4. 임시 파드로 PV에 푼다
dump 안의 경로와 PV(/data) 경로:
| dump | PV |
|---|---|
app.ini |
/data/gitea/conf/app.ini |
data/* |
/data/* (actions_artifacts, actions_log, packages, attachments, avatars …) |
repos/* |
/data/git/gitea-repositories/* |
custom/* |
/data/gitea/* (있을 때만) |
IMAGE=$(kubectl -n gitea get deploy gitea -o jsonpath='{.spec.template.spec.containers[0].image}')
kubectl -n gitea run gitea-restore --image="$IMAGE" --restart=Never --overrides='{
"spec": {
"securityContext": {"runAsUser": 1000, "runAsGroup": 1000, "fsGroup": 1000, "runAsNonRoot": true,
"seccompProfile": {"type": "RuntimeDefault"}},
"containers": [{"name": "restore", "image": "'"$IMAGE"'", "command": ["sleep", "3600"],
"securityContext": {"allowPrivilegeEscalation": false, "capabilities": {"drop": ["ALL"]}},
"volumeMounts": [{"name": "data", "mountPath": "/data"}]}],
"volumes": [{"name": "data", "persistentVolumeClaim": {"claimName": "gitea-data"}}]}}'
kubectl -n gitea wait --for=condition=Ready pod/gitea-restore --timeout=2m
kubectl -n gitea cp "$W/$D" gitea-restore:/data/restore.tar.gz
kubectl -n gitea exec gitea-restore -- sh -ec '
cd /data && rm -rf restore && mkdir restore && tar -C restore -xzf restore.tar.gz
mkdir -p /data/gitea/conf /data/git/gitea-repositories
[ -f /data/gitea/conf/app.ini ] && cp /data/gitea/conf/app.ini /data/gitea/conf/app.ini.before-restore || true
cp restore/app.ini /data/gitea/conf/app.ini
cp -a restore/data/. /data/
cp -a restore/repos/. /data/git/gitea-repositories/
[ -d restore/custom ] && cp -a restore/custom/. /data/gitea/ || true
rm -rf restore restore.tar.gz
find /data/git/gitea-repositories -mindepth 2 -maxdepth 2 -name "*.git" -type d | wc -l'
kubectl -n gitea delete pod gitea-restore
- 마지막 숫자가 1단계 리허설의
N과 같아야 한다. - PV에 옛 파일이 남아 있는 경우(A에서 일부만 잃음)
cp -a는 덮어쓰고 지우지는 않는다. dump에 없는 옛 저장소를 남기고 싶지 않으면tar줄 앞에rm -rf /data/git/gitea-repositories/* /data/packages/*를 넣는다(3의 사본이 있을 때만).
5. Gitea를 다시 띄운다
kubectl -n gitea scale deploy/gitea --replicas=1
kubectl -n gitea rollout status deploy/gitea --timeout=10m
kubectl -n gitea exec deploy/gitea -c gitea -- gitea admin regenerate hooks
kubectl -n gitea exec deploy/gitea -c gitea -- gitea doctor check --all 2>&1 | tail -20
chart의 init 컨테이너가 시작할 때 Secret 값으로 app.ini를 다시 맞춘다. dump의 app.ini에서 오는 것은 Secret에 없는 생성 값
(INTERNAL_TOKEN, SECRET_KEY, JWT 키)이다. 이것이 맞아야 2FA·토큰이 계속 쓰인다.
6. 확인
curl -fsS -o /dev/null -w '%{http_code}\n' https://git.learn.hyeonworks.com/api/healthz
curl -s -o /dev/null -D - 'https://git.learn.hyeonworks.com/api/v1/repos/search?limit=1' | grep -i '^x-total-count'
git ls-remote https://git.learn.hyeonworks.com/donghyeon.kang/platform-core.git HEAD
kubectl -n gitea exec deploy/gitea -c gitea -- gitea doctor check --run check-db-consistency 2>&1 | tail -5
200, 2단계에서 적어 둔 공개 저장소 수와 같은 수,HEAD해시.- 웹에서 로그인(Keycloak OIDC), 패키지 화면의
grpc-library·messaging-library(1.0.0,dev.cakit.*), Actions 기록을 한 번씩 본다. - DB에는 있는데 파일이 없는 저장소(dump 뒤에 만든 것)는 웹에서 열면 오류가 난다. 노트북 clone에서 다시 push한다.
- runner가 다시 붙었는지 본다(
infrastructure/ci/gitea-runner/README.md).
되돌리기
- 4 도중 실패: Gitea를 0으로 둔 채 임시 파드를 다시 띄워
cp /data/gitea/conf/app.ini.before-restore /data/gitea/conf/app.ini(4의kubectl run명령,exec부분만 바꿔서). - 4를 끝낸 뒤: Gitea를 0으로 줄이고
rm -rf /srv/k3s/ssd/gitea && mv /srv/k3s/ssd/gitea.before-restore-$TS /srv/k3s/ssd/gitea후 1로.
끝나면
rm -rf "$W" # 하루 지켜본 뒤: rm -rf /srv/k3s/ssd/gitea.before-restore-$TS