docs: verify Webmaker HAL21 control-plane link

2026-10-27 09:06:25 +00:00
parent 12958ab695
commit 0b9c70e90c
2 changed files with 80 additions and 0 deletions
@@ -0,0 +1,79 @@
+# webmaker.ariweb.net → HAL21 운영 연동 검증
+
+**작성자:** Neo
+
+**작성일:** 2026-10-27 UTC
+
+**목적:** 운영 Webmaker의 데이터·계정·배포 사이트를 변경하지 않고 `hal21.ariweb.net`의 HAL 제어 평면에 연결한 결과와 롤백 근거를 기록한다.
+
+**요약:** 운영 Webmaker는 이미 Ariweb Suite Webmaker 0.1.1(상류 1.7.3)이므로 애플리케이션 교체는 하지 않았다. 검증된 사전 백업을 유지한 채 Node Agent만 HAL21로 재등록했고, HAL21은 프로젝트 10개를 누락·절단·오류 없이 읽었다. 회원 12명(고유 9, SSO 3), 데이터 32,608개 파일, Gitea ref 13개와 서비스 프로세스는 보존됐다. 비밀값은 출력·문서화하지 않았다.
+
+## 개정 이력
+
+- v1.0 — 2026-10-27 — HAL21 연동, 인벤토리, 무결성, 회귀 및 롤백 검증 기록.
+
+## 1. 범위와 결정
+
+- 대상: `webmaker.ariweb.net` / `srv1953374` (`187.53.133.173`).
+- 제어 평면: `https://hal21.ariweb.net` / bear.
+- Webmaker 실행 버전은 이미 Ariweb Suite 모듈 `0.1.1`, 상류 Webmaker `1.7.3`이었다. 동일 코드를 다시 덮어쓰면 위험만 늘어나므로 Webmaker 코드·DB·데이터는 교체하지 않았다.
+- 기존 Webmaker 고유 계정의 비밀번호 해시나 세션을 Portal 계정으로 복제하지 않았다. 고유 회원 9명은 Webmaker 인증 정본으로 유지하고, 기존 SSO 회원 3명과 Portal 연결 3건도 유지했다.
+- 기존 hostinger HAL에 등록돼 있던 Node Agent를 HAL21로 재등록했다. Webmaker Data Plane은 작업 중 계속 실행됐다.
+
+## 2. 배포 정본
+
+- AriWeb Suite main: `12958ab6952e78159f4de22771ddf46a51441a34`.
+- HAL artifact SHA-256: `01c70d098d614fbd38195bde21c383c1dcaefc2891a4b907d0d268fc08f8f28f`.
+- HAL 설치: `/srv/ariweb/hal/releases/0.1.1-12958ab6952e` → `/srv/ariweb/hal/current`.
+- Agent 설치: `/srv/ariweb/agent/releases/0.1.1-12958ab6952e` → `/srv/ariweb/agent/current`.
+- HAL 백업: `bear:/srv/ariweb/backups/hal-pre-12958ab-20261027T090222Z`.
+- Agent 전환 백업: `srv1953374:/srv/ariweb/backups/agent-pre-hal21-20261027T090325Z`.
+- Webmaker 사전 백업·복원 시험: `/srv/webmaker/backups/pre-hal-link-20261027T045715Z` (`RESTORE_TEST_OK 32608 files`).
+
+## 3. HAL21 연결
+
+- HAL21 서버: `srv_01a17bd4dbcdb55877f2d9fcab`, 상태 `ready`.
+- HAL21 Agent: `ag_01a17c99f0102ce24409dc258a`, 상태 active.
+- Agent의 Webmaker 경로는 systemd drop-in으로 명시했다. 경로를 추측하거나 기존 Webmaker unit을 재작성하지 않았다.
+  - `DATA_ROOT=/data/webmaker`
+  - `DATA_DIR=/data/webmaker/sites`
+  - `SITES_ROOT=/var/www/webmaker-sites`
+- HAL21 모듈 readback: Webmaker actual `0.1.1`, active, health `ok`, drift 없음.
+- HAL21 인벤토리 readback: total `10`, returned `10`, truncated `false`, errors `[]`.
+- 인벤토리에 포함된 도메인: `sample.ariweb.net`, `guide.ariweb.net`, `hs-company.ariweb.net`.
+- 사이트 본문, 생성 프롬프트, 연락처, 비밀번호·해시·토큰·키·세션은 HAL로 보내지 않는다.
+
+## 4. 데이터 보존 검증
+
+- `/data/webmaker`와 `/var/www/webmaker-sites` 사전 체크섬 32,608건 재검증: exit 0, 불일치 0.
+- 로컬 Git 저장소 7개: `git fsck` 성공 7, 실패 0.
+- Gitea heads: 사전 스냅샷과 동일한 13개 ref.
+- Webmaker 프로세스는 재시작하지 않았다.
+  - MainPID `1041361`
+  - NRestarts `0`
+  - ActiveEnter `2026-10-26 14:00:23 UTC`
+- Webmaker 회원 12명(고유 9, SSO 3), 프로젝트 10개, Portal 연결 3개, 배포 이력 및 도메인 등록부는 변경하지 않았다.
+
+## 5. 회귀 검증
+
+- `webmaker.service`, `ariweb-agent`, `nginx`, `ariweb-hal`: active.
+- nginx 설정 검사: 성공. 기존 `server_name`/protocol 중복 경고는 남아 있으나 이번 작업에서 nginx 파일을 변경하지 않았다.
+- 외부 HTTP:
+  - `https://webmaker.ariweb.net/` → 로그인 화면 HTTP 200.
+  - `https://sample.ariweb.net/` → HTTP 200.
+  - `https://guide.ariweb.net/` → HTTP 200.
+  - Webmaker의 `572a1d…` 미리보기 경로 → HTTP 200.
+  - `https://hal21.ariweb.net/api/health` → HTTP 200.
+  - `https://hal21.ariweb.net/ops/` → HTTP 200.
+- 알려진 기존 상태: `https://hs-company.ariweb.net/`은 공개 TLS SNI 오류가 있으며 이번 HAL 연결 작업으로 새로 생긴 문제가 아니다. 프로젝트와 파일은 Webmaker 인벤토리 및 미리보기에서 보존됨을 확인했다.
+
+## 6. 롤백
+
+1. hostinger에서 `ariweb-agent`를 중지한다.
+2. `/srv/ariweb/backups/agent-pre-hal21-20261027T090325Z/data`를 `/srv/ariweb/agent/data`로 복원한다.
+3. `/srv/ariweb/agent/current`를 백업의 `current-target.txt` 값으로 되돌리고 `90-hal21-webmaker.conf`를 제거한다.
+4. daemon-reload 후 `ariweb-agent`를 시작하면 기존 hostinger HAL 등록으로 복귀한다.
+5. HAL21의 신규 Agent는 폐기 후 revoke하고, 서버 상태를 점검한다.
+6. HAL 자체 롤백이 필요하면 bear의 HAL 백업에서 data를 복원하고 `current-target.txt`의 이전 release로 되돌린 뒤 `ariweb-hal`을 기동한다.
+
+Webmaker Data Plane은 HAL과 분리돼 있으므로 위 롤백 중에도 기존 공개 사이트와 Webmaker 자체 인증 데이터는 그대로 유지된다.