• LINKS 1.0.1 — ARCA 0.1.18·Docker 24 호환 Builder·byedpi latest

    hanyul released this 2026-10-11 04:04:41 +09:00

    1.0.1 9cdd56ca4e 1518 commits

    LINKS 1.0.1

    이 patch 릴리스는 이전 릴리스 1.0(edac251454)부터 최종 소스 9cdd56ca4e까지를 묶었습니다. 루트 패키지는 1.0.1이고, ARCA pin은 exact 0.1.17 → 0.1.18으로 올렸습니다. ARCA 0.1.18의 Builder archive는 Docker 24와 호환되므로 Synology Docker 24.0.2에서도 VX/VX Ace package 기능을 쓸 수 있습니다. byedpi image는 digest pin 대신 :latest tag를 따릅니다. schema는 바뀌지 않았으므로 DB 초기화와 migration이 필요 없습니다.

    업그레이드 주의 — 1.0 → 1.0.1은 sh update.sh로 갱신합니다(초기화 없음)

    1. ARCA 0.1.18과 Builder image 참조: Builder archive는 Docker 24 호환 형식(OCI layout + manifest.json)입니다. coordinator는 daemon이 해석한 image ID로 Builder를 실행합니다. Docker 24 graphdriver에서는 config digest, Docker 25 이상의 containerd store에서는 manifest digest입니다. native runtime은 0.1.17과 같습니다. 다만 Builder digest가 바뀌었으므로 기존 RGSS active build는 다음 실행 준비 때 새 generation이 됩니다. 0.1.17 pin 때와 같은 규칙이며, 실행 중 session을 끝내거나 save를 지우지 않습니다. coordinator script(ops/runtime-package-coordinator.sh)·compose.yaml·image는 같은 release로 함께 교체합니다. 0.1.17 image에 새 script를 쓰면 Docker 24의 load 단계에서 실패합니다.
    2. coordinator 운영 전제:
      • 같은 daemon에서 rgss23-builder:<version> tag를 바꾸는 작업이 load 시작부터 image ID 취득까지의 구간과 겹치면 안 됩니다. 다른 디렉터리의 coordinator나 수동 docker load·docker tag도 여기에 해당합니다.
      • Docker 24는 coordinator 시작 때와 job마다 Builder archive(약 62 MB)를 TMPDIR(기본 /tmp)을 거쳐 다시 load합니다. TMPDIR은 배포 디렉터리 밖의 쓰기 가능한 절대 경로여야 합니다. tmpfs라면 archive와 동시 사용분을 담을 용량이 있는지 확인합니다.
      • load 단계가 실패하면 sh coordinator가 실패를 보존합니다. 시작 단계에서는 종료하고, claim 뒤에는 attempt 실패로 기록합니다. 실패 단계마다 진단 한 줄을 stderr에 남깁니다.
    3. byedpi :latest: byedpi service는 git.2ex.dev/hanyul/2ex-hentai-byedpi:latest(pull_policy: always)를 씁니다. update.sh의 compose pull과 개발 기동은 매번 최신 image를 받습니다. registry에 접속할 수 없으면 provider-live profile 기동이 실패합니다. 1.0의 compose.yaml은 registry에서 사라진 digest를 가리키므로, byedpi image가 없는 host에서는 pull이 실패합니다. 1.0.1의 compose.yaml로 교체합니다.
    4. DB 초기화 불필요: 기준 schema checksum은 14481d17c5947342be029bf6f850d2f862372b988dcbc1809360cdd7b333c918(infra/migrations/base.sha256)로 1.0과 같고 migration은 0개입니다. reset.sh를 실행하지 않습니다. 1.0 backup은 1.0.1 image로 복구할 수 있습니다.

    NAS 절차:

    1. package coordinator(Task Scheduler 작업)를 정상 정지합니다. docker ps --filter name=links-arca-에 남은 Builder container가 있으면 정지합니다.
    2. 1.0.1 태그의 배포 파일 7개를 받아 아래 SHA-256과 모두 같을 때만 교체합니다. 운영 가이드 운영 배포의 받기·대조 블록에 release_version='1.0.1'을 넣어 씁니다.
    3. sh update.sh
    4. coordinator를 시작합니다.
    5. update.sh가 마지막 줄에 출력한 --package readiness 명령을 실행합니다. 종료 코드가 0이어야 배포가 완료된 것입니다.
    cd /volume1/docker/links
sh update.sh
# coordinator 시작 뒤
docker compose --env-file '.env.production' exec -T catalog node apps/worker/dist/runtime-readiness-command.js --package

    원본 game library는 읽기 전용으로 유지합니다. 이번 게시 작업에서 개발·운영 DB 초기화나 NAS 배포는 실행하지 않았습니다.

    ARCA 0.1.18과 Docker 24 호환 Builder image 참조

    • @rgss23/arca를 exact 0.1.18로 올렸습니다(package.json·pnpm-lock.yaml·pnpm-workspace.yaml minimumReleaseAgeExclude). lockfile integrity는 registry, ARCA 게시 identity, 로컬 tarball과 일치합니다. SDK module은 0.1.17과 같습니다.

    • coordinator(ops/runtime-package-coordinator.sh·.ps1)는 Builder image를 다음 순서로 정합니다.

      1. release의 manifest digest가 daemon에서 해석되면 load 없이 그 값을 씁니다.
      2. 해석되지 않으면 검증된 archive를 다시 load합니다.
      3. load 뒤에는 package worker image의 exact pin으로 붙은 rgss23-builder:<version> tag의 image ID를 씁니다.

      Builder 실행에는 이렇게 정한 ID를 넘깁니다. pin이 정확한 숫자.숫자.숫자가 아니면 거부합니다. worker 출력 형식과 claim 4필드는 바뀌지 않았습니다.

    • Builder 검사 runner(tests/run-rgss23-builder.ps1·run-rgss23-builder-input.ps1)도 같은 image ID 규칙을 따릅니다. 0.1.18 archive의 load 출력에는 digest가 없기 때문입니다.

    • sh coordinator가 Builder 선택 단계의 one-shot 실패를 보존합니다. pin 조회 Compose 실패, archive reader 실패, load 실패가 있으면 종료하거나 attempt 실패로 기록합니다. archive는 mktemp -d 임시 디렉터리를 거쳐 load하고 그 디렉터리는 즉시 지웁니다.

    byedpi image :latest

    • compose.yaml의 byedpi는 digest pin(registry에서 삭제됨) 대신 :latest tag와 pull_policy: always를 씁니다. 2ex-hentai registry는 최신 image만 보관합니다. 보안 정책의 base image digest pin 규칙에 byedpi 예외를 적었습니다.

    문서

    • Docker 24 host의 Builder archive load 불가를 BLOCKED 항목으로 기록했고, ARCA 0.1.18 반영으로 해제했습니다. NAS의 실제 Docker 24 확인은 개발 계획의 완료 gate로 옮겼습니다.
    • 런타임 계약과 운영 가이드에 다음을 적었습니다.
      • Builder image 참조 규칙
      • coordinator 운영 전제(tag 변경 배제, TMPDIR 용량, 실패 진단)
      • stage handoff의 보장 범위: claim과 stage가 같은 release인지만 검사합니다.
    • 완료 기준선의 dind 판정 수치를 정정했습니다(판정 그룹 10개 PASS, failed assertions 0).

    알려진 제한(후속 과제)

    • Docker 24 graphdriver에서는 Builder config digest를 pin과 직접 대조하지 않습니다. tag에서 고른 image가 그 release라는 점은 위 운영 전제로 보장합니다. 이를 강화하려면 ARCA가 config digest를 공개 API로 제공해야 합니다(개발 계획의 비차단 후속).
    • 1.0과 같은 제한:
      • Player 세이브 관리 listener(3005)는 catalog caller token으로만 보호되며 edge network에서 TCP로 닿을 수 있습니다.
      • catalog·Player의 일반 egress를 network가 제한하지 않습니다.
      • update.sh는 opt-in profile container(translation-import 등)를 갱신하지 않습니다. 갱신 뒤 직접 다시 기동해야 합니다.

    검증과 남은 범위

    • PASS — arca-0118 브랜치(병합 8529256)에서 통과한 gate:
      • 빌드·정적 검사: cache 없는 test image build, lockfile 재해석, static, unit 149 files / 1,122 tests
      • ARCA 결속: arca-npm-check, release-set, runtime-binding
      • Builder: builder-input, builder(합성 VX Ace, 원본 save 제외), Builder 격리
      • worker·harness: runtime-workers, PowerShell coordinator harness 11/11
      • browser: 합성 0.1.18 SDK sandbox-rgss, player-restart Chromium·Firefox, run-browser mz·mv × Chromium·Firefox
      • 문서 검사
      • dind: Docker 24.0.2(overlay2)·29(containerd)에서 sh coordinator와 실제 compose.yaml Builder inspect의 판정 그룹 10개가 PASS했습니다(각 daemon, failed assertions 0).
    • PASS — byedpi-pin 브랜치(병합 73d998a): compose config 3개 조합, 격리 project의 pull·기동·1080 접속, 문서 검사.
    • PASS — docs-arca-docker24(dca1f00)·docs-dind-count(c975897): 문서 검사, git diff --check.
    • PASS — 최종 1.0.1 소스: 릴리스 커밋 두 개(root version, 완료 기준선 version 문구) 뒤 다음을 다시 통과했습니다.
      • 문서 검사(756개 파일 / Markdown 32개)
      • static(Prettier·ESLint·typecheck·docs-static)
      • git diff --check
    • 게시 이미지: 같은 최종 소스에서 build했습니다. image 안에서 root version 1.0.1, ARCA pin·설치본 0.1.18, base.sha256을 확인했습니다.
    • PARTIAL — 전체 UI/제품 acceptance: 화면·fixture·package/build 성공을 실제 browser play PASS로 기록하지 않습니다.
    • NOT RUN:
      • Synology NAS 실제 Docker 24(btrfs)에서 coordinator --once·load·package·--package readiness. dind는 대리 검증입니다.
      • Docker 24에서 Builder package 전체 실행(dind는 inspect까지)
      • Docker 24 재load 시간 측정
      • 동시 retag 경쟁 재현
      • byedpi를 거친 실제 provider 요청과 NAS pull
      • 실제 library/private game과 실제 scan
      • 입력·오디오·save/reload의 실제 게임 acceptance
      • 실제 모바일 기기·보조 기술
      • live provider
      • 개발 rebuild

    배포 이미지와 파일

    • Git annotated tag는 1.0.1이고 최종 소스는 9cdd56ca4e입니다.
    • 단일 linux/amd64 이미지: git.2ex.dev/hanyul/links:1.0.1 = git.2ex.dev/hanyul/links:latest
    • 원격 digest: sha256:5f76bc224504ad4c46c2146645849ec247ae2b1e8a19b0aec7a311e773034467
    • 아래 SHA-256은 checkout의 CRLF 변환본이 아니라 1.0.1 태그의 Git blob 원본 byte로 계산했습니다.
    • NAS 배포 목록은 7개입니다(update.sh=ops/deploy-registry.sh, reset.sh=ops/reset-registry.sh, backup.sh=ops/backup-registry.sh).
    • 1.0 대비 바뀐 파일은 **compose.yaml**과 ops/runtime-package-coordinator.sh 두 개입니다. 둘을 image와 함께 반드시 교체합니다.
    SHA-256 파일 1.0 대비
    4ea38db6094a01d77d80b93b6048f47377dd0354a1e8e2ec7b8008b5c233c042 compose.yaml 변경 (byedpi :latest·pull_policy: always)
    6e1fd3f2f73faee52abca28c8552cde417f496d86fc3d78c7001dec480e171a3 infra/docker/Caddyfile 동일
    39a4c55050e76043c8ca70f11f59dbdf08fff7ef38c1f1ec878f96194988d9d8 ops/backup-verify.compose.yaml 동일
    e516bea3688ad135556105772b5b8d603795bb04c7d7ce6ca760cbcf15714d52 ops/deploy-registry.sh 동일
    88d7b26d510ee67a25760dae8a9611be25592ea651a8d9870afaf9e714f37c54 ops/reset-registry.sh 동일
    89375a986b3cb64cf74145541701b32c6a0e983a72ca46be21a8bcfad7beaa3d ops/backup-registry.sh 동일
    50d3bb374dde35464f8e2d2c07a7dda95771149e7f2e8727bf03237e444ce8ab ops/runtime-package-coordinator.sh 변경 (daemon이 해석한 Builder image ID, one-shot 실패 보존) 
    4ea38db6094a01d77d80b93b6048f47377dd0354a1e8e2ec7b8008b5c233c042  compose.yaml
6e1fd3f2f73faee52abca28c8552cde417f496d86fc3d78c7001dec480e171a3  infra/docker/Caddyfile
39a4c55050e76043c8ca70f11f59dbdf08fff7ef38c1f1ec878f96194988d9d8  ops/backup-verify.compose.yaml
e516bea3688ad135556105772b5b8d603795bb04c7d7ce6ca760cbcf15714d52  ops/deploy-registry.sh
88d7b26d510ee67a25760dae8a9611be25592ea651a8d9870afaf9e714f37c54  ops/reset-registry.sh
89375a986b3cb64cf74145541701b32c6a0e983a72ca46be21a8bcfad7beaa3d  ops/backup-registry.sh
50d3bb374dde35464f8e2d2c07a7dda95771149e7f2e8727bf03237e444ce8ab  ops/runtime-package-coordinator.sh
    Downloads 2