문서·관리자 독립 운영

이 문서는 #1463 / 앱 v0.17.7 저장소 분리의 현행 운영 기준이다. 이전의 앱 release 큐에서 docs/admin을 함께 빌드하고 DB·Edge 이후 같은 SHA로 배포하던 절차를 대체한다. 앱·백엔드의 release 검증과 배포 순서는 유지한다.

코드와 실제 전환 상태

항목	상태
문서 원본	후속 앱 main 문서의 3-way 통합은 docs PR #11 / main `63e3ef59`에 반영. 최종 Production 게시 소스는 다른 담당자의 후속 기록과 PR #6을 포함한 docs main `7e19213d01eca078db756f9c94a9fdc1138daea5`
독립 문서 빌드	최종 Production 소스 `7e19213`의 클라우드 빌드에서 메뉴 304개·공개/정책 자산 31개·약관 4개 버전 쌍 확인. 초기 통합 로컬 검사와 별도의 실제 게시 증거
관리자	자체 설치·strict TS·109 단위 테스트·브라우저/로컬 DB 2개 시나리오 성공. 별도 Vercel 프로젝트를 이 저장소에 연결
CI	초기 독립 CI와 문서 동기화 PR #11 CI 성공. docs/admin 경로 각각 선택하며 문서만 바꾼 PR #11에서는 admin 제외, 앱 CI 호출 없음
배포	독립 관리자와 문서 custom staging/Production을 CLI로 배포하고 기존 관리자·문서·약관 주소를 확인했다. 서비스 전환 완료. Docs/Admin Deploy 자동 실행은 PAT 미설정으로 비활성
운영 전환	앱 코드는 HQ PR #1484 → staging #1488 → main #1489로 반영. 앱 main `937042d7` 배포·smoke 성공 뒤 Production docs를 새 관리자에 연결했다. 아래 실제 API·주소 검증과 자동배포 미설정을 구분
공개 주소	2026-09-15 #1666: 문서 `https://docs.barbelic.com`, 관리자 `https://admin.barbelic.com/`(루트). 옛 `barbelic-docs.vercel.app`·`barbelic-admin.vercel.app`은 별칭으로 유지, 옛 `/admin*` 경로는 308. 아래 2026-09-15 전환 기록

원격 전환 담당자는 마지막 표를 실제 실행 링크·SHA·안정 도메인·시각으로 갱신한다. 설정만 저장한 상태와 배포 성공을 구분한다.

로컬 검사

Node는 .nvmrc의 22 계열과 package.json engines를 따른다. Vercel CLI는 기존 핀 59.11.7을 유지한다. 루트 패키지는 명령 모음이고 문서/관리자 의존성은 각 lockfile로 설치한다.

# 문서만
npm ci --prefix docs --no-audit --no-fund
npm run check
npm run build:docs
npm run check:docs-artifact

# 관리자만
npm ci --prefix admin --no-audit --no-fund
npm run check:admin
BARBELIC_TARGET=local npm run build:admin

npm run build도 문서만 빌드한다. PowerShell에서 관리자 로컬 빌드는 $env:BARBELIC_TARGET='local'을 설정한 뒤 npm run build:admin으로 실행한다. 문서 산출물은 docs/.vitepress/dist, 관리자 산출물은 admin/dist다. 문서 산출물에 관리자 번들이 들어가면 자산 검사가 실패한다. 공개 약관·계정 삭제 페이지와 정책 JSON/CSV는 복사 후 원문과 바이트를 비교한다.

check:docs는 사이트 메뉴 경로와 이 저장소의 약관 메타데이터·버전 쌍·게시 이력을 검사한다. PR에서는 LEGAL_BASE_REF로 고정 base SHA를 제공한다. 최초 저장소 import에는 이전 이력이 없으며 메타데이터·버전 쌍을 확인한다. 변경 가능한 앱 checkout을 읽지 않는다. 과거 앱과 결합한 검사 원본은 archived-source/에 보존하며 실행 게이트로 등록하지 않는다.

역사 문서에는 이전 저장소 소스나 명세 JSON을 가리키는 링크가 남아 있다. 기존 VitePress의 ignoreDeadLinks 설정은 유지하고, 현행 메뉴의 로컬 페이지는 별도 검사한다. 모든 과거 본문 링크를 교정하거나 검증한 것으로 보고하지 않는다.

PR와 범위 선택

이 저장소의 작업 PR은 최신 main에서 분기해 main으로 제출한다. 관리자 변경의 staging 검증이 필요하면 staging으로 PR을 제출해 배포하고 같은 변경을 main으로 승격한다. 앱의 release 큐에 이 저장소 PR을 넣지 않는다. 서버 계약이 함께 바뀌면 앱 변경과 문서/관리자 PR을 연결하고, 호환 가능한 백엔드 배포를 먼저 확인한다.

CI는 admin/**의 실행 입력 변경에 관리자 검사를, Markdown 및 나머지 문서·게시 입력 변경에 문서 검사를 선택한다. admin/README.md 같은 Markdown만 바뀌어도 관리자 빌드를 실행하지 않는다. 공통 CI·루트 package·Node 설정 변경은 양쪽을 확인한다. 문서만 변경하면 관리자 npm install/check/build와 앱 CI를 실행하지 않는다. verify는 선택한 검사의 성공 및 선택하지 않은 검사의 skipped 상태를 확인한다. GitHub 필수 검사로 verify를 사용한다.

관리자 선택적 수동 E2E — #1478 v0.17.9

2026-09-10 사용자 결정으로 와드업·관리자 CASE·단위·컴포넌트·DB 검사가 모두 자동 실행에서 제외됐다. 현재 필수 범위는 75 CASE다. 관리자 check는 타입 검사만 실행하며 빌드를 유지한다. 단위·컴포넌트 검사는 npm run test:optional --prefix admin으로 수동 실행한다. 아래 backend 준비와 실행 도구는 선택적 수동 검증용이다. 관리자 디렉터리에서 npm run test:e2e:optional로 실행하거나, backend-fixture의 resolve/prepare 후 node admin/scripts/run-backend-e2e.mjs run --runtime <격리 런타임 경로>를 사용한다. 선택 실행에서도 두 시나리오의 필수 단언·대표 결함·정리, 60초·10초·자동 재시도 0을 유지한다.

백엔드의 정본은 앱 저장소에 유지한다. 앱의 Export admin backend fixture는 커밋된 local 설정과 migration SQL만 artifact로 발행한다. 선택적 수동 준비 도구는 admin/e2e/backend-fixture.lock.json에 고정한 저장소·workflow·커밋·성공 실행·artifact ID·SHA-256을 확인하고, 각 파일의 해시와 허용된 파일 목록을 다시 검사한다. 앱 checkout이나 앱 의존성 설치, 운영 DB dump와 seed, 운영 키를 사용하지 않는다. 실행별 독립 DB에 migration을 적용하고 빈 사용자/기록 상태를 확인한 뒤 테스트하며, 실패해도 해당 실행의 DB 컨테이너만 종료한다.

최초 발행은 앱 실행 34390999912, 소스 5c30f61311c8848ad0c6cc0239db8b0ddf6adde7, artifact 10119614649다. 내려받은 SQL 188개와 설정의 해시 검증도 통과했다. 발행 성공과 관리자 hosted E2E 성공은 별도 증거다. 이 기록 시점에는 관리자 hosted 실행은 미검증이다.

실제 발행 artifact의 독립 로컬 실증은 관리자 9c40033f731e9ed12ca81b8d1c3d9c947141d831, run 7b3e6b8a-ba69-4830-beac-60851f4de457에서 두 시나리오·품질 reporter가 최초 통과했다(각 2.135초·0.513초). 새 프로젝트 admin673624486f의 초기 Auth 사용자와 session은 각각 0개였고, 종료 뒤 해당 컨테이너 0개를 확인했다. 이 실행은 기존 앱 DB를 공유하지 않았다.

최종 관리자 실행 후보 37aa8f0는 check155/155 및 local build를 통과했다. 원자성·권한의 두 SQL 결함 실험에서 각 필수2시나리오×3단계=6개씩, 총12개 native결과와 SQL·소유권·권한 원복·정리 완료를 확인했다. 제외 전 품질 판정은 v0.17.9 감사를 따른다.

선택적 private artifact 내려받기에는 대상 앱 저장소의 Actions: read 권한을 가진 인증이 필요하다. 도구는 BARBELIC_BACKEND_ARTIFACTS_READ_TOKEN 환경변수를 사용하지만, 필수 CI에는 이 secret이 필요하지 않으며 오너의 토큰 등록은 #1478의 완료 조건이 아니다. 자격·고정 정보 누락이나 artifact 만료 시 선택 실행 자체는 실패한다. 값은 채팅·문서·로그에 넣지 않는다. backend 계약 갱신 시 실제 성공 artifact의 식별자·해시로 lock을 갱신한다. artifact 보관은 90일이며 만료된 증거를 재사용하지 않는다.

Vercel 프로젝트 설정

설정	문서 프로젝트	관리자 프로젝트
Git repository	`dekerd/Barbelic-docs`	`dekerd/Barbelic-docs`
Root Directory	저장소 루트(빈 값)	`admin`
설치	`npm ci --prefix docs --no-audit --no-fund`	`npm ci`
빌드	`npm run check:docs && npm run build:docs`	`npm run build`
출력	`docs/.vitepress/dist`	`dist`
Node	기존 프로젝트의 24.x 유지	24.x
Production branch	`main`	`main`
Custom environment	`staging`	`staging`

문서 프로젝트는 기존 ID prj_TICRkuQZtwN3mKfAUen635jEcyfO를 유지하며, 공개 주소는 2026-09-15 #1666부터 https://docs.barbelic.com이고 barbelic-docs.vercel.app은 별칭으로 남는다. 관리자 프로젝트 barbelic-admin(prj_Altwy1s03Zv5hNrrdebulwwabuLw)의 공개 주소는 https://admin.barbelic.com/(루트)이고 barbelic-admin.vercel.app은 별칭으로 남는다. 기존 docs/ Root Directory를 루트로 바꾸고 앱 저장소와의 연결을 해제한다. "Include source files outside of the Root Directory"는 문서 빌드에 필요하지 않다. 도메인의 실제 적용 상태는 전환 담당자가 확인한다. 기존 /admin/ 주소는 2026-08-22 배포 기록에 있다.

문서와 관리자 모두 Git 직접 배포를 끄고 이 저장소의 Actions에서 pinned CLI로 prebuilt 배포한다. 그래야 문서 /admin 연결 설정을 누락한 별도 배포나 중복 배포가 생기지 않는다.

Vercel 명령은 저장소 루트에서 실행한다. 관리자 프로젝트의 Root Directory가 admin이므로 --local-config admin/vercel.json으로 관리자 설정을 지정한다. admin 안으로 다시 이동하여 프로젝트 Root Directory를 중복 적용하지 않는다. 일반 npm run check --prefix admin과 관리자 로컬 개발은 이와 별개다.

GitHub 배포 설정

공통 repository secrets는 VERCEL_TOKEN, VERCEL_ORG_ID다. production과 staging GitHub Environment에 다음 변수를 설정한다.

변수	값의 의미
`VERCEL_DOCS_PROJECT_ID`	해당 문서 Vercel 프로젝트 ID
`VERCEL_ADMIN_PROJECT_ID`	독립 관리자 Vercel 프로젝트 ID
`BARBELIC_ADMIN_ORIGIN`	해당 환경의 관리자 안정 HTTPS origin. 경로·인증정보 없이 지정. production = `https://admin.barbelic.com`(2026-09-15 #1666), staging = 관리자 custom staging 별칭

문서 배포는 scripts/write-docs-vercel-config.mjs가 /admin 및 /admin/:path*를 관리자 origin의 루트 기준 같은 경로로 308 이동시키는 .vercel-docs.generated.json을 만든다(#1666부터 rewrite가 아니라 redirect). BARBELIC_ADMIN_ORIGIN이 비어 있으면 게시를 거부한다. 생성 파일은 Git에 넣지 않는다. origin은 매번 바뀌는 임시 배포 URL이 아니라 해당 환경의 안정 도메인이어야 한다.

관리자 Vercel 환경에는 VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, VITE_APP_API_BASE_URL을 환경별로 설정한다. 필요하면 VITE_SOCIAL_AUTH_PROVIDERS를 지정한다. VITE_APP_API_BASE_URL은 인증된 관리자 서버 API를 제공하는 앱 origin이다. 서비스 역할 키와 서버 비밀은 공개 빌드 변수로 넘기지 않는다. 배포 workflow는 BARBELIC_TARGET=production|staging을 명시한다. 관리자 빌드는 target과 Supabase 환경이 다르면 실패하고 산출물에 대상 도장을 남긴다. CI의 compile 검사는 BARBELIC_TARGET=local로 실행한다.

repository variable DOCS_DEPLOYMENT_ENABLED=true, ADMIN_DEPLOYMENT_ENABLED=true를 각각 설정한 뒤 해당 환경 브랜치에서 수동 실행해 검증할 수 있다. 설정 전에는 배포 job이 skipped이며 연결 완료를 의미하지 않는다. 앱 v0.17.7 전환 시점에 맞춰 활성화한다. Docs Deploy는 문서/게시 입력 push에만, Admin Deploy는 관리자 입력 push에만 자동 실행한다. 두 workflow는 Supabase migration·Edge 배포·앱 빌드를 실행하지 않는다.

배포 직전 branch의 최신 SHA와 빌드 SHA가 다르면 오래된 배포를 거부한다. main은 Production, staging은 custom staging으로 배포하며 GitHub Environment 승인 정책은 설정된 값을 따른다.

기존 주소와 전환 검증

문서 페이지와 sidebar 주소를 유지한다. /admin은 별도 관리자 프로젝트의 자체 origin(BARBELIC_ADMIN_ORIGIN, Production은 https://admin.barbelic.com) 루트로 308 이동한다(#1666). 관리자 프로젝트는 루트에서 산출물을 내보내고 옛 /admin/*를 루트로 308 이동시킨다.
public/legal/**는 /legal/**에, public/account/delete.html은 /account/delete.html에 게시한다. 기존 버전 내용·메타데이터·동의 의미를 유지한다.
앱의 /legal/**와 /account/delete.html은 전환 당시 안정 문서 origin으로 rewrite했다. 2026-09-15 사용자 결정 #1643(앱 v0.19.3)부터는 앱이 같은 원문의 사본을 자체 public/legal/·public/account/에서 직접 제공하고 rewrite와 개발 서버 프록시를 제거했다. 이 저장소의 게시본은 공개 웹용이며, 새 버전은 이 저장소에 게시한 뒤 사본을 복사한 앱 릴리스가 나가고 나서 서버 요구 버전을 전환한다. 두 사본이 같은지는 게시 담당자가 앱 origin의 URL을 직접 열어 응답 내용과 이 저장소 원문(Git blob)을 대조해 확인한다.
원격 검증은 문서 /, 기존 메뉴 URL, /legal/terms-v1.html부터 현재 버전까지, /account/delete.html, /admin/ 진입·자산·로그인·서버 API를 확인한다. 문서와 관리자 배포 SHA, 앱 연결 SHA를 각각 기록한다.

실제 실행 기록

2026-09-09, #1463 Phase 1~3 구현 완료 / Phase 4 진행 중. 전체 릴리스 완료가 아니다.

재개 시 읽기 확인: 앱 v0.17.6 main 승격 #1481이 df394f77ab0efe16ad018aecf2799a2306b10731에 도달했고 #1460의 통합 커밋 4b726b96c가 그 조상이다. 개명된 명령·워크플로는 main에 존재한다. 이번 문서 통합은 운영 배포의 성공을 새로 판정하거나 #1463 큐 호환·배포 설정을 활성화하지 않았다.
문서 repo 초기 main 65b739c00b78b4610a5eca61aa06482bc58bd37c, 후행 슬래시 경로 수정 ac99d43. 앱 코드 PR #1466 / feat/1463-repository-split의 a0dbed5a1과 연결한다.
관리자 Vercel 프로젝트 barbelic-admin, ID prj_Altwy1s03Zv5hNrrdebulwwabuLw, Git repository dekerd/Barbelic-docs, Root Directory admin, Node 24.x.
Preview 배포 성공. 기존 형식의 관리자 주소에서 배포 보호를 거친 인증 조회로 HTML 200·preview/staging 대상 도장·JavaScript 200 application/javascript를 확인했다. Preview에는 staging 공개 설정만 적용했으며 실제 외부 OAuth 성공을 뜻하지 않는다.
첫 Preview에서 /admin과 중첩 경로는 200인데 /admin/만 404가 됐다. 관리자 config와 문서 proxy 생성기에 후행 슬래시 경로를 명시하고 새 Preview로 수리를 확인했다. 최초 새 프로젝트 CLI 시도는 기본 Production 선택 및 target 미설정으로 빌드 거부됐다. 이후 모든 검증 배포는 --target preview를 명시했다. 기존 운영 사이트는 변경하지 않았다.
Windows의 로컬 vercel build는 spawn cmd.exe ENOENT로 끝났으므로 성공 증거로 쓰지 않는다. 실제 Vercel Linux Preview 빌드 및 이 저장소의 GitHub CI 성공을 따로 기록했다. Actions의 prebuilt 배포 전체는 아직 실증하지 않았다.
앱 clean checkout의 npm run check: 3,265 pass / 기존 DB 조건부 skip 27 / fail 0. 앱 빌드·대상 검사·unused 검사 성공. 관리자 로컬 실제 업로드, 중복 배치 원자 거부, 정정 재시도 및 일반 사용자 UI/RPC 거부 2개와 계정·기록 정리 확인. 앱 full queue CI는 아직 실행하지 않았다.

HQ 통합 PR 관측

2026-09-09 최초 조회 시 통합 PR #1484는 release/v0.17.7 대상 OPEN·Draft이며 head는 5c8920400163f222dd024d440d5ae7f2f83c6498이었다. 당시 앱 Vercel Preview는 SUCCESS, 기존 barbelic-docs 연결의 Preview는 FAILURE를 확인했다. 문서 프로젝트의 Git/RootDirectory 전환 전 관측이며, 이 조회에서 배포 로그의 세부 실패 원인을 별도로 조사하거나 재실행하지 않았다. 독립 관리자 staging의 성공과 이 기존 문서 Preview의 실패를 구분한다.

HQ 보고 기준 위 초기 통합 후보의 핵심 6개·구조 3개 검사는 통과했다. 이후 큐 호환 main 65a12274671e0daabb23774c7d32cc9ecca85e63을 포함한 head 5c460a14fbd961eb35018e698df3b9235ce8e4d1이 Ready로 전환됐다. HQ는 이 head를 동결하고 사용자가 승인한 통합 precheck 생략·full CI 1회 요청을 진행 중이라고 보고했다. 이것을 full 성공이나 앱 배포 완료로 기록하지 않는다. 통합 PR 큐 진입과 앱 staging/main 승격은 HQ가 담당한다. #1463 담당은 그 staging 시점에 새 앱 API·관리자 연결과 기존 문서 origin 전환을 검증한다.

관리자 호환 근거도 HQ에 전달했다. #1463은 기존 백엔드 API·RPC/RLS·관리자 권한 판정을 유지하고 신규 DB 마이그레이션을 추가하지 않는다. 추가한 읽기 전용 /api/admin/deployment-manifest는 기존 verifyAdmin·Bearer 인증과 명시적 CORS 허용 목록을 사용한다. 기존 로컬 관리자 109개 테스트·DB/브라우저 2개 시나리오와 독립 staging 자산 응답은 호환 근거이며, 새 앱 staging의 실제 API·CORS 성공을 뜻하지 않는다. 통합 후보의 별도 SQL 변경 영향은 해당 작업 담당자/HQ가 확인한다.

전환 완료와 남은 운영 설정

2026-09-10 Production 준비: docs main 63e3ef598fe565c3dcba132e9d5760656aa0326d에서 독립 관리자 배포 dpl_5gqCyyrNKRE1ELHV9Pqe57WMLakq가 READY이고 관리자 Production에 연결됐다. 이전 검증 소스 bb40643 대비 admin/ 코드 차이가 없음을 확인해 같은 테스트·로컬 빌드를 반복하지 않고 최초 정상 Production 클라우드 배포만 진행했다. 공개 HTTP로 HTML·JavaScript 각각 200, 도장 production, Production Supabase 및 https://www.barbelic.com API 대상을 확인했다. 관리자 인증·서버 API 성공이나 기존 문서 주소 전환 완료를 뜻하지 않는다.

HQ는 앱 full CI 34372922344 성공, release merge e56604cb0ae4d9fcaa361fbd99c3978dabb60535, staging merge 213aaeb7c21598e3023cf47d16ec756feabad80a의 tree 12d339cd21d807000671f80e69de477e4d592d64 일치를 보고했다. 앱 staging 배포 34374171430의 frontend/smoke 성공 신호 뒤 관리자 API와 기존 docs 연결을 전환한다. 이 기록 시점에는 기존 docs Git/RootDirectory와 운영 origin을 유지했다.

후속 staging 배포 성공 신호를 받은 뒤 다음을 확인했다.

확인 대상	실제 결과
앱 관리자 API	`213aaeb7` 기준 admin/docs staging origin 양쪽에서 OPTIONS 204, 비허용 origin 403, 무인증 401, 일반 사용자 403, 관리자 200 및 정확한 migration `20260914000000`·Edge 3개 기대값·CORS·no-store, 총 12개 확인 통과
임시 인증 fixture	고유한 시험 계정 2개만 생성·로그인하고 삭제. 각각 Auth admin 조회 404로 부재 확인, 정리 실패 0. 실사용자·기존 관리자 권한·운동 기록 변경 없음
문서 Git/RootDirectory	기존 프로젝트 ID·도메인을 유지하며 `dekerd/Barbelic-docs`와 저장소 루트로 전환. 당시 Production 배포 포인터는 기존 배포 유지
문서 staging	clean docs main `63e3ef59`를 CLI 배포한 `dpl_EHhxB72jtdaSbz8PugYxekv1MtFD` READY, custom environment `staging` 확인. `/`와 기존 `/process/deployment-pipeline` 200
staging 기존 `/admin/`	두 Vercel 프로젝트의 정상 보호 인증을 함께 제공한 요청에서 HTML·JavaScript 200, 독립 관리자 원문과 바이트 일치, staging 도장 확인. docs 자격만 제공했을 때의 Vercel 로그인 이동과 구분하며 보호 해제·공개 예외 추가 없음
약관·계정 삭제 주소	docs staging의 약관/개인정보 4개 버전 쌍·서비스 정보·CSS·계정 삭제 총 11개 파일이 200이며 저장소 원문과 바이트 일치

Vercel 배포 보호 인증과 앱의 Supabase 관리자 Bearer 인증은 별개다. 위 API의 12개 확인에는 양쪽 인증을 구분해 적용했다. 외부 OAuth 제공자의 로그인 전체를 새로 검증한 것으로 보고하지 않는다.

HQ가 앱 main 937042d775049b96ad00438fbe4019e1ec464e0c의 Production 배포 34375087828에서 DB·Edge·frontend·smoke 및 태그 성공을 확인한 뒤 Production 문서 연결을 게시했다. 앱의 검증 tree는 staging과 같은 12d339cd21d807000671f80e69de477e4d592d64다.

Production 확인 대상	실제 결과
문서 배포	docs main `7e19213d01eca078db756f9c94a9fdc1138daea5`에서 배포 3S3U2Dti3wHevNaijjjbLPPvmAJ1 READY, 기존 `barbelic-docs.vercel.app` 및 팀 도메인에 연결. VitePress 304개 경로·공개 자산 31개 빌드 검사 통과
기존 관리자 주소	공개 HTTP에서 `/admin`·`/admin/` HTML 200, 독립 Production 관리자 원문과 바이트 일치. JavaScript 200 및 SHA-256 일치, Production Supabase·`www.barbelic.com` 도장 확인
기존 문서·앱 주소	문서 홈·기존 메뉴 200. docs와 `www.barbelic.com` 양쪽에서 약관/개인정보 4개 버전 쌍·서비스 정보·CSS·계정 삭제 11개 파일씩 원문과 바이트 일치. 관리자·문서·자산 합계 27개 확인 통과
앱 API 경계	docs/admin Production origin 양쪽 OPTIONS 204·GET/Authorization 허용·무인증 GET 401·no-store, 비허용 origin GET/OPTIONS 403. 관리자 Bearer 양성은 동일 tree의 staging에서 검증했고 Production 시험 계정·권한을 추가 생성하지 않음
로그인 시작	기존 docs `/admin/`와 독립 admin `/admin/`를 복귀 주소로 요청한 Kakao·Google·Apple 각각 302로 제공자에 이동, 총 6개 확인. 반환 state에서 최종 복귀 주소를 확인할 수 없으므로 callback 허용 목록·로그인 완료를 검증한 것으로 보고하지 않음

두 환경 전환 중 Vercel 보호 해제·공개 예외 추가·앱 권한 검사 완화는 없었다. 초기 staging의 Vercel 로그인 화면은 두 프로젝트 중 docs 인증만 제공한 검사 조건 때문이었고, 두 정상 인증을 함께 사용한 후 동일 배포의 proxy 연결을 확인했다. 이를 앱 결함이나 코드 수리로 기록하지 않는다.

초기 2026-09-09 환경 준비 당시에는 관리자 custom staging 배포 dpl_Da6Ze77Awe1i4digFruajRhh2Vst의 안정 주소 /admin/와 JavaScript 200·staging 도장만 확인했다. 소스는 docs bb406438a499a519c3e0fa028ddcdeee7c2225ca였고 당시에는 기존 문서 연결을 유지했다. 위 2026-09-10 검증·연결 전환은 이 초기 준비 이후의 결과다.

문서 저장소의 GitHub production·staging Environment에 문서/관리자 프로젝트 ID와 각각의 관리자 안정 origin을 설정했고, 조직 ID도 배포 설정에 연결했다. 앱 Vercel의 ADMIN_ALLOWED_ORIGINS는 새 staging/Production 배포에서 위 API 요청으로 적용을 확인했다. 자동배포 활성화 변수는 아직 켜지 않았다.

독립 Actions 배포 인증 VERCEL_TOKEN은 아직 없다. 현재 CLI 로그인은 만료·갱신되는 OAuth 자격증명이며 이를 GitHub에 복사하지 않았다. Vercel의 공식 tokens 안내에 따라 OAuth 로그인으로는 새 CI 토큰을 발급할 수 없다. 해당 팀의 배포용 Access Token을 이 저장소의 VERCEL_TOKEN secret에 연결하는 오너 입력을 HQ에 보고했다. 비밀 값은 문서·로그·Git에 기록하지 않는다. 기존 CLI로 검증 가능한 독립 배포와 지속적인 자동배포 완료를 구분한다.

이번 서비스 연결 전환은 완료했다. 남은 운영 설정은 독립 Actions용 VERCEL_TOKEN 연결과 그 이후의 자동배포 활성화다. 그 전에는 기존 인증된 CLI로 환경을 명시해 게시하며, OAuth 로그인 자격을 GitHub secret으로 복사하지 않는다. 외부 제공자 로그인 전체와 최종 callback 성공은 위 관측 범위에 포함하지 않는다.

최종 전환 기록은 이 문서와 기존 #1463 후속 문서 통합 기록 두 파일에만 추가하며, HQ의 통합 릴리스 보고서와 한 문서 PR·CI로 반영한다. 앱 커밋·CI·재배포를 기록 목적으로 추가하지 않는다. main 기준 큐 선행 패치와 이전 v0176 패치는 이력으로 보존한다.

2026-09-15 문서·관리자 하위 도메인 전환 (#1666)

오너 요청(2026-09-15)으로 문서를 https://docs.barbelic.com, 관리자를 https://admin.barbelic.com/(루트)으로 옮겼다. 코드는 문서 저장소 PR #127(2920e3b4): 관리자 Vite base /, 옛 /admin* 경로 308, 문서 /admin* → 관리자 origin 루트 308(rewrite 대신 redirect), 산출물 검사는 /assets/ 경로 요구. 전체 기록은 작업 기록.

확인 대상	실제 결과
Vercel 도메인	팀 `dekerds-projects-4f9780ee`의 등록 도메인 `barbelic.com` 하위라 `docs.barbelic.com` → `barbelic-docs`, `admin.barbelic.com` → `barbelic-admin` 배정 즉시 검증, Let's Encrypt 인증서 자동
관리자 게시	`dpl_3VmSCFw4PKoTG8J6nKZNbW2cPTWp`(docs main `a1905bf`, 그 뒤 `admin/` 변경 없음), `admin.barbelic.com`에 별칭. `/` 200, 도장 `appApiBaseUrl=https://app.barbelic.com`, `/assets/*` 200, nosniff·referrer 헤더, `/admin`·`/admin/`·`/admin/assets/x.js` 308 → 루트 경로, `barbelic-admin.vercel.app/admin/` 308 → `/`
문서 게시	`barbelic-docs-beuytuv1z-dekerds-projects-4f9780ee.vercel.app`(main `be233ed`), `docs.barbelic.com`에 별칭. `/`·문서 페이지·`/legal/terms-v4`·`/account/delete` 200, `/admin`·`/admin/`·`/admin/x/y` 308 → `https://admin.barbelic.com/…`(경로 유지), `barbelic-docs.vercel.app/` 200·`/admin/` 308 → 관리자
환경 변수	관리자 Production `VITE_APP_API_BASE_URL` `https://www.barbelic.com`(#1619 뒤 랜딩이라 308로 실패하던 값) → `https://app.barbelic.com`. 앱 Production `ADMIN_ALLOWED_ORIGINS`에 `https://admin.barbelic.com` 추가(config 형식으로 되읽어 확인). GitHub `production` `BARBELIC_ADMIN_ORIGIN` → `https://admin.barbelic.com`
로그인 시작	복귀 주소 `https://admin.barbelic.com/`로 카카오·Google·Apple 각 302. Supabase 복귀 허용 목록(`https://admin.barbelic.com/**`)은 오너가 추가했고 밖에서 확인할 수 없다
앱 API CORS	`app.barbelic.com/api/admin/deployment-manifest` OPTIONS: 옛 origin 204 유지, `admin.barbelic.com`은 v0.19.3 배포가 변수 변경보다 먼저 나가 403 — v0.19.4 배포 실행의 확인 단계가 204를 자동 확인(Phase 4, 아래)

Actions 배포(Docs Deploy·Admin Deploy)는 여전히 VERCEL_TOKEN 미설정으로 비활성이며 이번 게시도 CLI 로그인으로 했다. 옛 *.vercel.app 주소는 별칭으로 남기고 통째로 redirect하지 않았다(앱 main의 /legal/* rewrite가 아직 barbelic-docs.vercel.app을 가리킴).

앱 쪽 마무리(오너 결정 2026-09-15 "배포 19.4에 넣어줘"): 앱 PR #1682(release/v0.19.4 큐 병합 14171482)가 deployment-targets.json에 환경별 adminOrigin(production https://admin.barbelic.com, staging은 관리자 custom staging 별칭)을 두고, check:deployment가 값의 모양을, 배포 뒤 deploy-steps.yml frontend 잡이 그 주소로 보낸 관리자 API CORS 사전 요청이 204인지 확인한다. 새 주소의 403은 v0.19.4 Production 배포에서 이 단계가 204로 닫는다.

문서·관리자 독립 운영 ​

코드와 실제 전환 상태 ​

로컬 검사 ​

PR와 범위 선택 ​

관리자 선택적 수동 E2E — #1478 v0.17.9 ​

Vercel 프로젝트 설정 ​

GitHub 배포 설정 ​

기존 주소와 전환 검증 ​

실제 실행 기록 ​

최신 main 통합 후 준비 상태 ​

HQ 통합 PR 관측 ​

전환 완료와 남은 운영 설정 ​

2026-09-15 문서·관리자 하위 도메인 전환 (#1666) ​