전체 설치 스크립트 GitHub 릴리스 에셋 검증 및 폴백 다운로드 방어 로직 적용

2026-10-31 04:54:34 +09:00
1 parent 5a67e7bbcf
commit b41d2f68f3
@@ -0,0 +1,54 @@
+# 전체 설치 스크립트 다운로드 안정성 강화 계획 (HARDEN-INSTALL-LINKS-IMP-PLAN)
+
+## 1. 개요
+외부 오픈소스 저장소의 릴리스 정책 변경(서브 크레이트 태그 발행, 빌드 진행 중 빈 에셋 상태, 파일명 변경) 및 GitHub API Rate Limit(시간당 60회 제한)으로 인해 설치 스크립트가 실패하는 문제를 방지하기 위해 모든 설치 스크립트(`install-*.sh`, `install-*.ps1`)에 **3단계 방어 로직(Asset-aware Lookup + Fallback Tag + URL Fallback)**을 일괄 적용합니다.
+
+```mermaid
+flowchart TD
+    Start([설치 스크립트 실행]) --> API[GitHub Releases API 조회<br/>User-Agent 헤더 포함]
+    API --> CheckAPI{API 응답 성공?}
+    CheckAPI -- Yes --> AssetSearch["릴리스 목록에서 현재 플랫폼 에셋이<br/>실제로 존재하는(assets > 0) 최신 릴리스 탐색"]
+    AssetSearch --> FoundAsset{에셋 URL 발견?}
+    FoundAsset -- Yes --> DownloadPrimary[1차: 에셋 URL 다운로드 시도]
+    FoundAsset -- No --> FallbackBuild[2차: FALLBACK_TAG 기반 URL 생성]
+    CheckAPI -- No (Rate Limit 등) --> FallbackBuild
+    DownloadPrimary --> CheckDL{다운로드 성공?}
+    CheckDL -- Yes --> ExtractInstall[압축 해제 및 바이너리 설치]
+    CheckDL -- No (404 등) --> FallbackBuild
+    FallbackBuild --> DownloadFallback[FALLBACK_TAG URL로 재시도]
+    DownloadFallback --> ExtractInstall
+    ExtractInstall --> Done([설치 완료])
+```
+
+## 2. 작업 단계 및 체크리스트
+
+### 단계 1: 실행 계획 수립
+- [x] 작업 계획서(`VIBE-WORK/261031/HARDEN-INSTALL-LINKS-IMP-PLAN.md`) 작성
+
+### 단계 2: Unix / macOS용 Bash 설치 스크립트(`.sh`) 방어 로직 적용
+- [x] `install-all-smi.sh`: 에셋 존재 검증, User-Agent 헤더, 다운로드 실패 시 `FALLBACK_VERSION` 자동 재시도 적용
+- [x] `install-bottom.sh`: `assets` 배열 내 현재 플랫폼 파일(`bottom_${triple}.${ext}`) 존재 여부 확인 및 `FALLBACK_TAG="0.12.3"` / `"nightly"` 폴백 적용
+- [x] `install-ctop.sh`: `assets` 존재 여부 필터링 및 `FALLBACK_TAG="v0.7.7"` 폴백 다운로드 적용
+- [x] `install-dua.sh`: 다운로드 실패 시 `FALLBACK_TAG="v2.46.0"` 자동 재시도 보강
+- [x] `install-helix.sh`: `/releases` 목록에서 `assets`가 존재하는 최신 릴리스 탐색 및 `FALLBACK_TAG="25.07.1"` 폴백 적용
+- [x] `install-lazydocker.sh`: `assets` 존재 여부 필터링 및 `FALLBACK_TAG="v0.25.2"` 폴백 다운로드 적용
+- [x] `install-lazygit.sh`: `assets` 존재 여부 필터링, 중복 함수 정리 및 `FALLBACK_TAG="v0.61.1"` 폴백 다운로드 적용
+- [x] `install-ocr.sh`: 에셋 존재 검증 및 다운로드 실패 시 `FALLBACK_VERSION="v1.3.19"` 자동 재시도 적용
+- [x] `install-ttyd.sh`: 에셋 존재 검증 및 `FALLBACK_TAG="1.7.7"` 폴백 다운로드 적용
+
+### 단계 3: Windows용 PowerShell 설치 스크립트(`.ps1`) 방어 로직 적용
+- [x] `install-all-smi.ps1`: 에셋 검증 및 다운로드 실패 시 `FALLBACK_VERSION` 자동 재시도 적용
+- [x] `install-bottom.ps1`: 에셋 존재 검증 및 `FALLBACK_TAG` 폴백 다운로드 적용
+- [x] `install-ctop.ps1`: 에셋 존재 검증 및 `FALLBACK_TAG="v0.7.7"` 폴백 다운로드 적용
+- [x] `install-dua.ps1`: 다운로드 실패 시 `FALLBACK_TAG="v2.46.0"` 자동 재시도 보강
+- [x] `install-helix.ps1`: API 실패 또는 에셋 미발견 시 `FALLBACK_TAG="25.07.1"` 폴백 다운로드 적용
+- [x] `install-lazydocker.ps1`: 에셋 존재 검증 및 `FALLBACK_TAG="v0.25.2"` 폴백 다운로드 적용
+- [x] `install-lazygit.ps1`: Git for Windows 및 lazygit 에셋 검증, `FALLBACK_TAG="v0.61.1"` 폴백 다운로드 적용
+- [x] `install-ocr.ps1`: 다운로드 실패 시 `FALLBACK_VERSION="v1.3.19"` 자동 재시도 적용
+- [x] `install-ttyd.ps1`: API 실패 또는 에셋 미발견 시 `FALLBACK_TAG="1.7.7"` 폴백 다운로드 적용
+
+### 단계 4: 문법 검증, 완료 보고서 작성 및 Git 푸시
+- [x] 모든 `.sh` 스크립트 `bash -n` 문법 검사 통과 확인
+- [x] 완료 보고서(`VIBE-WORK/261031/HARDEN-INSTALL-LINKS-PHASE01.md`) 작성
+- [x] `uv tool run --from graphifyy graphify update .` 실행
+- [x] Git commit 및 push
@@ -0,0 +1,28 @@
+# 전체 설치 스크립트 다운로드 안정성 강화 완료 보고서 (HARDEN-INSTALL-LINKS-PHASE01)
+
+## 1. 개요
+외부 오픈소스 저장소들의 릴리스 정책 변화(서브 크레이트 릴리스 혼재, CI 빌드 중 빈 에셋 상태, 파일명 변경)나 GitHub API Rate Limit(시간당 60회 제한)이 발생하더라도 모든 설치 스크립트가 중단 없이 정상 설치되도록 **3단계 방어 로직**을 전체 스크립트(`install-*.sh`, `install-*.ps1`)에 일괄 적용하였습니다.
+
+```mermaid
+flowchart LR
+    Step1["1단계: 에셋 존재 검증<br/>(assets 배열이 비어있지 않은<br/>릴리스만 선택)"] --> Step2["2단계: API 폴백<br/>(API Rate Limit/오류 시<br/>검증된 FALLBACK_TAG 사용)"]
+    Step2 --> Step3["3단계: 다운로드 폴백<br/>(최신 URL 404/실패 시<br/>FALLBACK_TAG URL로 자동 재시도)"]
+```
+
+## 2. 도구별 적용 내역 및 Fallback 버전
+
+| 도구 | 대상 스크립트 | 에셋 필터링 조건 | 검증된 Fallback 태그 |
+| :--- | :--- | :--- | :--- |
+| **all-smi** | `install-all-smi.{sh,ps1}` | `assets.length > 0` | `v0.25.0` |
+| **bottom** | `install-bottom.{sh,ps1}` | `assets.length > 0` (Nightly & Stable) | `0.12.3` |
+| **ctop** | `install-ctop.{sh,ps1}` | `prerelease == false && assets.length > 0` | `v0.7.7` |
+| **dua** | `install-dua.{sh,ps1}` | `prerelease == false && startswith("v") && assets.length > 0` | `v2.46.0` |
+| **Helix** | `install-helix.{sh,ps1}` | `prerelease == false && assets.length > 0` | `25.07.1` |
+| **lazydocker** | `install-lazydocker.{sh,ps1}` | `prerelease == false && assets.length > 0` | `v0.25.2` |
+| **lazygit** | `install-lazygit.{sh,ps1}` | `prerelease == false && assets.length > 0` | `v0.61.1` |
+| **ocr** | `install-ocr.{sh,ps1}` | `assets.length > 0` | `v1.3.19` |
+| **ttyd** | `install-ttyd.{sh,ps1}` | `assets.length > 0` | `1.7.7` |
+
+## 3. 추가 개선 사항
+- `jq`와 `python3`가 모두 없는 최소 리눅스 컨테이너 환경에서도 `grep`/`sed` 폴백 및 `FALLBACK_TAG`를 통해 설치가 중단되지 않도록 개선했습니다.
+- 모든 GitHub API 요청에 `User-Agent` 헤더와 타임아웃(`--connect-timeout 10` / `-TimeoutSec 15`)을 명시하여 무한 대기 현상을 방지했습니다.