Files
platform-core/docs/runbooks/gitea-restore.md
T
DongHyeonka 819f3f14f1 docs(runbooks): add restore, rebuild, upgrade and reboot runbooks
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.
2026-11-12 01:38:58 +09:00

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