# 호스트 재구축 (루트 SSD를 잃었을 때) desktop의 루트 SSD를 잃고 HDD(WDC 2TB, AIStor 파티션 라벨 `AISTOR_DATA`)는 살아 있을 때, 새 SSD에서 플랫폼을 되살리는 순서다. 각 단계의 자세한 명령은 링크한 문서를 따른다. 이 문서는 **순서와 빠지기 쉬운 것**을 정한다. ## 전제와 확인 — 하나라도 아니면 4·7·8단계에서 멈춘다 | 전제 | 확인 | | --- | --- | | HDD의 k3s datastore 로컬 사본이 있다(PR #6 호스트 백업이 설치돼 돌았다) | 2단계 mount 뒤 `sudo ls /srv/k3s/aistor/host-backups/k3s-datastore/` | | CNPG 백업이 AIStor에 있다(W1) | 6단계 뒤 AIStor `platform-postgres-backups` bucket | | Gitea dump가 AIStor에 있다(PR #6) | 6단계 뒤 AIStor `platform-host-backups/gitea/` | 2026-11-12 현재는 세 백업 모두 설치되기 전이다. 그 전에는 datastore 대신 이 저장소의 bootstrap 절차(`bootstrap/manual/phase1~4`)로 처음부터 다시 세워야 하고, Secret은 소유자가 새로 넣어야 한다. ## 무엇이 남고 무엇을 잃나 | 남음 (HDD, xfs `AISTOR_DATA`) | 잃음 (루트 SSD) | | --- | --- | | AIStor 데이터(`/srv/k3s/aistor/data`): Loki·Tempo, CNPG 백업, Gitea dump | OS, k3s, Docker(`/var/lib/docker`: runner, `workmachine`, `*cloudflared` 컨테이너), 모든 SSD Local PV | | k3s datastore 로컬 사본(`/srv/k3s/aistor/host-backups/k3s-datastore/`) | `/etc`(nginx, certbot 인증서, dnsmasq, `/etc/platform-backup`), `~/.secrets` | | | `/etc/rancher/k3s/platform-post-bundle.env`, `platform-restore-evidence.env`(2026-08 Secret 암호화 hardening의 증거 표시. 운영에는 필요 없고, `bootstrap/manual/k3s-secret-encryption.md` 검사기가 「증거 없음」으로 볼 뿐이다) | desktop 전체를 잃으면 HDD도 잃는다. 그때는 off-host 사본이 있어야 한다(`services/platform-host-checks/README.md`). ## 시작 전에 소유자가 따로 가지고 있어야 하는 것 k3s datastore를 복원하면 쿠버네티스 Secret은 모두 돌아온다. 아래는 그 밖의 것이다. - platform-core 저장소 사본(Gitea가 내려가 있으므로 노트북 clone이나 off-host 사본). 이 문서는 desktop의 `/home/donghyeon/workspace/platform`에 clone했다고 보고, 모든 상대경로는 거기 기준이다. - Tailscale 계정(사설 DNS가 Tailscale 주소를 쓴다), Cloudflare API token(certbot DNS 인증), certbot 연락 email - Slack webhook 복구 경로(KeePass, `scripts/bootstrap/backup-slack-webhook-recovery.sh`) - off-host 백업을 쓴다면 그 개인 키 - hyeonworks.com 앞단 설정과 tech-log 이미지·매니페스트: **이 저장소에 없다.** tech-log-backend·tech-log-frontend 저장소를 따른다. - `workmachine`과 `*cloudflared` 컨테이너: 소유자의 별도 설정이다. 이 저장소에 재구축 절차가 없다. ## 순서 ```text 1 OS·이름·도구·시계 → 2 HDD mount → 3 k3s 설치(시작 안 함) + 시간 동기화 drop-in → 4 datastore 복원(첫 시작) → 5 Local PV 폴더 → 6 AIStor 확인 → 7 Postgres 복원(CNPG) → 8 호스트 백업 다시 설치 → 9 Gitea 파일 복원 → 10 호스트 설정(Tailscale·DNS·nginx·TLS·Docker·runner·재시작 묶음) → 11 확인(Gitea 확인 포함) ``` ### 1. OS, 호스트 이름, 도구, 시계 - Ubuntu 24.04, 사용자 `donghyeon`(uid 1000. Gitea rootless와 AIStor 폴더 소유자가 1000이다). - **호스트 이름을 `donghyeon-system-product-name`으로 둔다.** 모든 Local PV의 `nodeAffinity`가 `kubernetes.io/hostname=donghyeon-system-product-name`을 본다. 이름이 다르면 PV를 쓰는 파드가 전부 Pending이다. ```bash sudo hostnamectl set-hostname donghyeon-system-product-name ``` - 패키지: `git jq ripgrep sqlite3 curl openssl python3-yaml nginx dnsmasq`, snap `certbot`과 `certbot-dns-cloudflare`. Docker는 공식 apt 저장소로 설치하고 `donghyeon`을 `docker` 그룹에 넣는다. Helm `v3.19.4`를 `~/.local/bin/helm`에 둔다 (렌더 스크립트가 정확한 버전을 요구한다). - 시계: `sudo timedatectl set-local-rtc 0`, `sudo timedatectl set-ntp true`. Windows 쪽 `RealTimeIsUniversal`은 W1 `infrastructure/host/README.md` 3단계(W1 PR). ### 2. HDD mount 새 SSD를 달면 디스크 이름(sda·sdb·sdc)이 바뀔 수 있다. 이름이 아니라 라벨로 찾는다. ```bash lsblk -o NAME,SIZE,FSTYPE,LABEL,MODEL # LABEL=AISTOR_DATA, xfs, WDC 2TB 쪽 echo 'LABEL=AISTOR_DATA /srv/k3s/aistor xfs defaults,noatime 0 2' | sudo tee -a /etc/fstab # 2026-11-12 live fstab과 같은 줄 sudo findmnt --verify # 오류가 없어야 한다. 있으면 fstab 줄을 고치고 다시 본다(틀린 fstab은 다음 부팅을 emergency mode로 보낸다) sudo mkdir -p /srv/k3s/aistor && sudo mount /srv/k3s/aistor ls /srv/k3s/aistor # data host-backups ``` ### 3. k3s 설치 (시작하지 않은 채로) + 시간 동기화 drop-in 먼저 HDD의 백업에서 버전을 본다(`k3s-datastore-restore.md` 1단계: `cat "$D/META"`의 `k3s_version`). 아래 ``에 넣는다. ```bash curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION='' INSTALL_K3S_SKIP_START=true \ INSTALL_K3S_EXEC='server --disable=servicelb' sh - cd /home/donghyeon/workspace/platform sudo install -D -m 0644 infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml /etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml sudo install -D -m 0644 infrastructure/security/k3s/40-secrets-encryption.yaml /etc/rancher/k3s/config.yaml.d/40-secrets-encryption.yaml ``` **k3s를 처음 시작하기 전에** W1의 시간 동기화 drop-in을 깐다(`infrastructure/host/README.md` 2단계, W1 PR). 11-11 사고는 틀린 시계로 k3s가 인증서를 만든 것이었다. 재시작 묶음(PR #5)은 클러스터가 떠 있어야 도는 스크립트라 10단계에서 깐다. ### 4. datastore 복원 (k3s 첫 시작) `k3s-datastore-restore.md` 1·3·4·5단계(2단계는 「새로 설치한 호스트」 경우). 이때 PV 폴더가 없어 Postgres·Gitea 파드는 뜨지 못한다. 정상이다. ### 5. Local PV 폴더 ```bash sudo bash scripts/bootstrap/prepare-ssd-local-paths.sh sudo bash scripts/bootstrap/prepare-observability-local-paths.sh --execute # 인자 없으면 dry run이다 sudo install -d -o root -g root -m 0750 /srv/k3s/ssd/pgadmin # 위 둘이 만들지 않는다(apply-admin-services.sh가 만들던 것) ``` 빈 폴더가 생긴다. 관측 스택(Prometheus·Loki 캐시·Grafana)은 빈 PV로 다시 쌓인다. Grafana 대시보드는 repo의 ConfigMap에서 다시 생긴다. ### 6. AIStor AIStor의 PV는 HDD라 데이터가 그대로다. Secret(라이선스, root 설정)도 datastore에서 돌아왔다. ```bash kubectl -n object-storage get pods kubectl -n object-storage get objectstore -o wide bash scripts/validate/aistor-s3-smoke.sh --execute # 임시 bucket을 만들고 쓰고 지운다(쓰기 작업) ``` `Initialized/green`, 마지막 줄 `AISTOR_S3_SMOKE_PASS bucket-create object-write object-read object-delete bucket-delete`. ### 7. platform-postgres 복원 datastore에는 `Cluster` 정의가 있지만 PV는 비어 있다. CNPG를 AIStor 백업(`platform-postgres-backups`)에서 되살린다. Gitea·Keycloak·tech-log DB가 모두 여기 있다. 먼저 원본 정의를 남긴다(되살린 Cluster가 원래와 같은지 비교할 기준이다): ```bash kubectl -n platform-data get cluster platform-postgres -o yaml > /root/platform-postgres-cluster-before-rebuild.yaml ``` - W1의 `services/platform-postgres-backup/README.md`(W1 PR)에는 임시 Cluster로 하는 「복원 리허설」이 있다. 그 `restore-drill/cluster.yaml`의 `bootstrap.recovery`를 쓰는 방식이다. - **운영 Cluster를 백업으로 갈아 끼우는 절차(빈 PV의 `platform-postgres`를 지우고 같은 이름으로 recovery bootstrap)는 아직 문서가 없다(W1 몫).** 그 문서가 생기기 전에는 리허설 절차를 이름만 `platform-postgres`로 바꿔 따르고, 위에서 남긴 원본과 `pg_hba`(techlog 두 줄 포함)· Secret 참조·resources가 같은지 비교한다. ### 8. 호스트 백업 다시 설치 `/etc/platform-backup/aistor.env`와 `/usr/local/lib/platform-backup`은 SSD와 함께 잃었다. 9단계(Gitea 복원)가 이것을 쓴다. `services/platform-host-checks/README.md` 「적용」의 `create-host-backup-credentials.sh`(AIStor에 새 사용자를 하나 더 만든다)와 `install-host-checks.sh --execute`를 돈다. 첫 실행 백업은 「복원 직후 상태」의 백업이 된다. ### 9. Gitea 파일 복원 `gitea-restore.md`의 경우 B(DB는 7에서 되살렸다), 1~5단계. **6단계 확인 중 https·로그인은 10단계(nginx·TLS·DNS) 뒤로 미룬다.** 그 전에는 `kubectl -n gitea get pods`와 저장소 수만 본다. ### 10. 호스트 설정 | 무엇 | 문서 | | --- | --- | | Tailscale 설치·로그인 | 사설 DNS(`infrastructure/networking/private-dns/host/dnsmasq-tailscale.conf`)가 Tailscale 주소 `100.92.240.34`를 고정해 쓴다. 새로 로그인해 주소가 바뀌면 이 파일의 `listen-address`·`address=` 줄을 새 주소로 바꾸는 PR을 낸다 | | 사설 DNS(dnsmasq LAN·Tailscale) | `infrastructure/networking/private-dns/host/README.md` | | Host Nginx와 TLS | `infrastructure/networking/host-nginx/README.md`는 전환 기록이라 빈 호스트 설치 절차가 아니다. 이 저장소의 `learn-services*.conf`를 `/etc/nginx/sites-available/`에 두고, 인증서는 `bootstrap/manual/phase3-admin-surfaces.md`의 certbot 절차로 다시 받는다. 빈 호스트용 절차는 아직 없다 | | Docker daemon.json, runner 상한·정리 | W1 `infrastructure/host/README.md` 4단계, `infrastructure/ci/gitea-runner/README.md` | | Gitea Actions runner 재등록 | `infrastructure/ci/gitea-runner/README.md` | | k3s 재시작 묶음(kubelet 예약·audit·PSA) | `infrastructure/host/k3s/README.md`(PR #5) | | tech-log 운영 이미지 | Gitea 패키지 레지스트리에서 다시 받는다(W1의 레지스트리 전환 뒤). 9단계 dump에 패키지가 들어 있다 | ### 11. 확인 `after-reboot-checks.md`를 처음부터 끝까지 돈다(8단계의 `workmachine`·`*cloudflared`는 이 저장소 밖이라 없을 수 있다). `gitea-restore.md` 6단계를 마저 한다. 그다음 repo와의 차이를 본다: ```bash cd /home/donghyeon/workspace/platform PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm bash scripts/validate/live-drift-check.sh --accepted scripts/validate/live-drift-accepted.txt ```