• LINKS 1.0.11 — 게임 링크 Open Graph 임베드와 공개 표지 route

    hanyul released this 2026-10-15 23:56:44 +09:00

    1.0.11 8484a44e3d 1388 commits

    LINKS 1.0.11

    이 릴리스는 이전 릴리스 1.0.10(6a9d016126) 위에 게임 링크의 Open Graph 미리보기(Discord 등 임베드)와 세션 없는 공개 표지 route를 얹었습니다. 최종 소스는 8484a44e3d, 루트 패키지는 1.0.11, ARCA pin은 exact 0.1.19(1.0.10과 같음)입니다. schema 변경이 없어 migration이 없습니다.

    업그레이드: 1.0.10 → 1.0.11은 sh update.sh만 실행합니다

    1. 갱신 방법: 배포 디렉터리에서 sh update.sh만 실행합니다. reset.sh는 실행하지 않습니다.
    2. schema 변경 없음: DB schema는 1.0.10과 같습니다(f7fe92f3…). update.sh는 Pending migrations: 줄을 출력하지 않습니다(대기 migration 0개).
    3. 배포 파일 변경 없음: update.sh가 받는 5개 파일(compose.yaml, infra/docker/Caddyfile, update.sh, reset.sh, ops/runtime-package-coordinator.sh)은 1.0.10과 byte 단위로 같습니다. 그래서 아무 파일도 설치하지 않고 image만 바뀝니다. .env.example도 바뀌지 않아 .env.production에 할 일이 없습니다.
    4. 되돌리기: schema가 같으므로 문제가 생기면 1.0.10 image로 고정해 되돌릴 수 있습니다(update.sh가 실패할 때 출력하는 Rollback: LINKS_REGISTRY_TAG=…@sha256:…).
    cd /volume1/docker/links
sh update.sh

    성공하면 단계 표시 6줄 뒤에 Updated to 1.0.11 (catalog 47795342a79b), runtime.package ready.가 출력됩니다. postgres 정의가 1.0.10과 같아 격리 gate에서 postgres container는 다시 만들어지지 않았습니다(DB 중단 0초). 원본 game library는 읽기 전용으로 유지합니다. 이번 게시 작업에서 개발·운영 DB 초기화나 NAS 배포는 실행하지 않았습니다.

    Discord 등은 이미 올린 링크의 미리보기를 캐시합니다. 배포 전에 올린 게임 링크는 예전(미리보기 없음) 모습으로 남을 수 있으니, 배포 뒤 링크를 다시 올려야 새 임베드가 나옵니다.

    변경 내용

    게임 링크 미리보기(Open Graph·twitter:card)

    • /games/<id>, /library?game=<id>, /play/<id>, /play/<공유 링크 token> 문서가 서버에서 Open Graph·twitter:card=summary tag를 담습니다. 제목은 catalog와 같은 표시 제목, 설명은 확인된 엔진(RPG Maker MZ 등)·제작사·LINKS에서 브라우저로 실행, 이미지는 그 게임의 공개 표지 URL(표지가 없으면 사이트 기본 이미지)입니다.
    • 로그인 여부와 무관하게 같은 미리보기를 보냅니다(사용자 결정 2026-10-15). 미리보기용으로 공개하는 것은 제목·표지·엔진(과 제작사)뿐이며, 목록·검색·상세 API와 실행은 여전히 로그인 또는 공유 링크 token이 필요합니다.
    • 없는 게임, 꺼진·없는 공유 링크, 형식이 잘못된 값, /와 그 밖의 문서는 사이트 기본 임베드(og:title LINKS, og:image /og-default.png, 512×512 자체 제작 PNG)로 200입니다. /play/ 뒤의 형식 오류·없는·꺼진 링크는 서로 구별되지 않는 같은 응답입니다.
    • 공유 링크 문서의 tag에는 token·hash가 없고 og:url도 넣지 않습니다(경로가 credential). og:image는 설치본 UUID 경로입니다. 미리보기 DB 조회는 한 번의 경량 조회이며 client 주소별 분당 설치본 120회·공유 링크 30회 예산을 쓰고, 넘으면 DB 조회 없이 사이트 기본 tag로 200을 보냅니다(문서 자체에 429 없음).
    • 구 VNDB cache만 있는 승인 VNDB 작품도 catalog 요약과 같은 제작사를 미리보기에 씁니다(R62b-01 수정).

    공개 표지 route

    • 새 API GET /api/v1/public/installations/<id>/cover(선택 ?variant=w320|w640)는 세션 없이 그 설치본의 현재 표지를 돌려줍니다. Cache-Control: public, max-age=3600, ETag(If-None-Match → 304), Cross-Origin-Resource-Policy: cross-origin, nosniff, client 주소별 분당 60회입니다. 없는 설치본·표지 없음은 404, 모르는 variant·query는 400입니다.
    • 공급자 표지를 미리보기로 재배포하는 조건과 아직 정하지 않은 age/content gating은 보안 문서에 기록했습니다.

    호환

    • API의 기존 응답은 바뀌지 않았습니다. 공유 링크 조회 API는 1.0.10과 같이 기본 네 key, ?include=cover에서만 cover를 더합니다.
    • 1.0.10에서 만든 공유 링크는 1.0.11에서 그대로 쓰이며 미리보기도 나옵니다(격리 gate에서 확인).

    검증과 남은 범위

    • PASS: 브랜치 gate(최종 1.0.11 소스, 고유 Compose project)
      • static(Prettier·ESLint·typecheck·docs-static), 전체 unit 153 files·1,257 tests, 문서 검사, git diff --check.
      • schema gate 34 files·235 tests(빈 DB fresh 적용과 1.0 기준 schema + 0001+0002 적용 결과의 구조 등가, 사슬, 링크 미리보기 4개 포함 — 새 회귀: 구 VNDB cache만 있는 승인 작품의 요약·미리보기 첫 제작사 일치).
      • deploy 기록기 96·reset 기록기 30 synthetic case, Compose config 3조합(19·19·30 services)과 Watchtower label, foundation.
      • browser acceptance mz-chromium: 12개 단언과 공유 링크 게스트 29개 단언(guestLinkPreviewMeta: 링크 문서 og:title=조회 제목, og:image=공개 표지 경로·cookie 없이 200 image, og:url·token 없음) PASS.
    • PASS: 릴리스 gate(Compose v2.20.1, NAS 조건)
      • 환경: 격리 docker:24.0.2-dind, 공식 Docker Compose v2.20.1 binary(게시 checksum 일치), stager 1026:100, ./data bind store, library 최상위 0:0 000 + 1026 ACL. 합성 HTTPS release 서버와 합성 TLS registry에 게시된 1.0.10 image와 이 릴리스의 1.0.11 image를 넣었습니다.
      • 1.0.10 설치 → reset.sh → update.sh, 합성 MZ ready build, 로그인 사용자 세이브, 표지 asset, 관리자 공유 링크 1개.
      • 설치된 1.0.10 sh update.sh → 1.0.11: exit 0(48초), Pending migrations: 줄 없음(대기 0, schema current f7fe92f3…, migration 이력 변화 없음), 5개 배포 파일이 1.0.10과 같아 설치 0·크기·mtime 불변, .tmp 0. 12개 service network 불일치 0·unhealthy 0·모두 Watchtower 제외, readiness PASS, catalog·Player 1.0.11. postgres container 재생성 없음(DB 중단 0초). 세이브·MZ ready·row count 불변.
      • 세션 없는 curl: /games/<id>·/library?game=<id>·/play/<id>·/play/<token>이 합성 제목 og:title·공개 표지 og:image·twitter:card=summary(token 문서는 og:url 없음, 본문에 token·hash 없음). 없는 UUID·꺼진 token·/는 og:image /og-default.png 기본 임베드이고 본문은 주소별 og:url tag만 다르며, 꺼진·없는·형식 오류 token 문서는 byte 단위로 같습니다. /og-default.png 200 image/png(8,678 bytes). 공개 표지 200(seed bytes, public, max-age=3600, ETag → 304), 없는 id 404, variant=w480 400. 서비스 로그(catalog·gateway·Player·broker) 전체에 token·hash 0건. 기존 공유 링크 확인(네 key, include=cover, token 표지, 게스트 실행, Player /save 403)도 PASS.
      • 재-update: exit 0(18초), 배포 파일 변경 없음, 위 확인 모두 반복 PASS.
    • 리뷰: R62(P2 무제한 공개 문서 DB 조회 → T62b 해소)·R62b 최종 '병합 가능'. R62b의 P3 2건(구 VNDB cache 제작사 누락, API 계약 fallback 문장)은 이 릴리스에서 고쳤습니다.
    • 알려진 제한·NOT RUN: 실제 Discord·Slack 미리보기 표시(NOT RUN, 합성 curl·browser 확인만), age/content gating 미결(제목·표지·엔진은 미리보기용으로 누구에게나 공개), 실제 NAS 갱신, 실제 Cloudflare 경유, live provider, browser matrix의 mv-chromium·mz-firefox·mv-firefox.

    배포 이미지와 파일

    • Git annotated tag는 1.0.11이고 최종 소스는 8484a44e3d입니다(branch release-1.0.11).
    • 단일 linux/amd64 이미지: git.2ex.dev/hanyul/links:1.0.11 = git.2ex.dev/hanyul/links:latest
    • 원격 digest: sha256:47795342a79bda7254342e80c9c4e6077252ea3eeaee29fea6f1281472836a69
    • release asset은 없습니다. update.sh가 tag 1.0.11의 5개 배포 파일을 HTTPS로 받습니다(1.0.10과 같은 내용). 대응은 update.sh=ops/deploy-registry.sh, reset.sh=ops/reset-registry.sh이고, 나머지는 compose.yaml·infra/docker/Caddyfile·ops/runtime-package-coordinator.sh입니다.
    Downloads 2