socai-io/socai

socai 사이트 배포

이 스킬은 socai 웹사이트 배포, Vercel 구성, socai.io, www.socai.io, /download, /github 또는 PR 미리보기 배포와 관련된 작업을 할 때 사용합니다.

이 스킬은 배포 런북의 진실 공급원입니다. ../../../docs/website-deployment.md는 의도적으로 간결하게 유지하며, 중복된 지시 사항이 생기지 않도록 여기를 참조합니다.

프로젝트 컨텍스트

• 웹사이트 소스: site/
• 프레임워크: Astro 정적 사이트
• Vercel 팀/범위: socai-d83824c8 (socai)
• Vercel 프로젝트: socai-site
• 프로덕션 도메인: https://socai.io
• 문서 라우트: https://socai.io/docs/ (Astro 사이트로 빌드된 Starlight 페이지)
• 표준 호스트: socai.io
• www 동작: https://www.socai.io/*는 https://socai.io/*로 308/리디렉션되어야 함
• 다운로드 라우트: https://socai.io/download는 socai OSS 릴리스 미러의 최신 범용 macOS DMG로 리디렉션
• GitHub 라우트: https://socai.io/github는 https://github.com/socai-io/socai로 리디렉션

예상 Vercel 프로젝트 설정:

설정	값
프레임워크 프리셋	Astro
루트 디렉토리	site
설치 명령어	pnpm install
빌드 명령어	pnpm build
출력 디렉토리	dist
Node.js 버전	24.x

안전 규칙

• 모든 Vercel 프로젝트/도메인 명령어에는 socai-d83824c8 범위를 사용합니다.
• 잘못된 Vercel 팀이나 개인 프로젝트에서 배포하지 마십시오.
• site/.vercel/, site/dist/, site/.astro/, site/node_modules/를 커밋하지 마십시오.
• 사용자가 명시적으로 승인하지 않는 한 분석을 활성화하지 마십시오.
• 웹사이트 배포 작업 중에는 앱 릴리스 자산을 편집하지 마십시오.
• 이슈 작업은 전용 브랜치에서 수행하고, 리포지토리 변경 사항에 대해 PR을 열거나 업데이트하십시오.
• 수동 배포를 위해 Vercel 프로젝트 설정을 임시로 변경한 경우, 완료 후 복원하십시오.

로컬 검증

배포 또는 배포 관련 코드/구성에 대한 PR을 열기 전:

cd site
pnpm install
pnpm build

JSON/XML 구성을 건드린 경우 검증:

python3 -m json.tool site/vercel.json >/dev/null
python3 -m json.tool site/public/site.webmanifest >/dev/null
python3 - <<'PY'
import xml.etree.ElementTree as ET
ET.parse('site/dist/sitemap-index.xml')
ET.parse('site/dist/sitemap-0.xml')
PY

Vercel 상태 확인

vercel whoami
vercel teams ls
vercel projects ls --scope socai-d83824c8
vercel project inspect socai-site --scope socai-d83824c8 --yes
vercel domains inspect socai.io --scope socai-d83824c8
vercel domains inspect www.socai.io --scope socai-d83824c8

프로젝트 설정에서 루트 디렉토리가 site, 프레임워크가 Astro, 빌드 명령어가 pnpm build, 출력이 dist, 설치가 pnpm install인지 확인합니다.

선호하는 프로덕션 배포

Git 통합 활성화 후 선호하는 경로:

1. 웹사이트 변경 사항을 main에 병합합니다.
2. Vercel이 site 루트 디렉토리에서 socai-site 프로젝트를 빌드하도록 합니다.
3. 아래 명령어로 프로덕션 URL을 확인합니다.

PR 미리보기도 Vercel 대시보드에서 Git 통합이 연결되어 있어야 합니다.

긴급/수동 CLI 프로덕션 배포

Vercel 프로젝트가 루트 디렉토리 site로 구성되어 있기 때문에 site/에서 직접 로컬 배포를 시도하면 site/site 루트 디렉토리 오류로 실패할 수 있습니다. Git 통합을 사용할 수 없고 CLI 배포가 필요한 경우, 이 임시 루트 해결 방법을 사용하고 나중에 루트 디렉토리를 복원하십시오.

set -euo pipefail

cat > /tmp/vercel-root-null.json <<'EOF'
{
  "rootDirectory": null
}
EOF
cat > /tmp/vercel-root-site.json <<'EOF'
{
  "rootDirectory": "site"
}
EOF

restore_root() {
  vercel api /v10/projects/socai-site \
    --scope socai-d83824c8 \
    -X PATCH \
    --input /tmp/vercel-root-site.json \
    --silent || true
}
trap restore_root EXIT

vercel api /v10/projects/socai-site \
  --scope socai-d83824c8 \
  -X PATCH \
  --input /tmp/vercel-root-null.json \
  --silent

cd site
vercel deploy --prod --scope socai-d83824c8 --project socai-site --yes

배포 후 루트 디렉토리가 복원되었는지 확인:

vercel project inspect socai-site --scope socai-d83824c8 --yes

프로젝트를 Root Directory . 또는 null로 두지 마십시오. Git 미리보기는 site에 의존합니다.

URL 확인

먼저 HEAD 검사를 사용합니다:

curl -I https://socai.io/
curl -I https://socai.io/docs/
curl -I https://socai.io/docs/quickstart/
curl -I https://www.socai.io/
curl -I https://socai.io/sitemap.xml
curl -I https://socai.io/sitemap-index.xml
curl -I https://socai.io/download
curl -I https://socai.io/github

예상되는 첫 홉 동작:

• https://socai.io/는 200을 반환합니다.
• https://socai.io/docs/는 200을 반환하고, 중첩 페이지(예: /docs/quickstart/)도 200을 반환해야 합니다.
• https://www.socai.io/는 308을 반환하며 location: https://socai.io/여야 합니다.
• https://socai.io/sitemap.xml은 /sitemap-index.xml로 영구 리디렉션되며, 이는 200을 반환해야 합니다.
• https://socai.io/download는 구성된 OSS 릴리스 미러의 최신 범용 macOS DMG로 Vercel 리디렉션(307)을 반환합니다.
• https://socai.io/github는 https://github.com/socai-io/socai로 Vercel 리디렉션(307)을 반환합니다.

체인을 따라가려는 경우에만 -L을 사용합니다:

curl -I -L --max-time 30 -o /dev/null -w 'code=%{http_code}\nfinal=%{url_effective}\n' https://socai.io/download

Git 미리보기 설정

시도:

cd site
vercel link --yes --scope socai-d83824c8 --project socai-site
vercel git connect https://github.com/socai-io/socai --scope socai-d83824c8

Vercel이 다음을 반환하는 경우:

Failed to link socai-io/socai. You need to add a Login Connection to your GitHub account first.

Vercel/GitHub 계정 소유자가 Vercel 대시보드에서 GitHub 로그인/통합을 연결한 다음, socai-site를 socai-io/socai에 루트 디렉토리 site로 연결해야 합니다.

문제 해결

여러 커밋 푸시 후 웹사이트 변경 사항이 건너뛰어짐

site/vercel.json의 무시된 빌드 단계는 HEAD를 HEAD^가 아닌 VERCEL_GIT_PREVIOUS_SHA(이 프로젝트 및 브랜치의 마지막 성공적인 배포)와 비교해야 합니다. 푸시의 마지막 커밋은 Rust 코드만 변경할 수 있지만, 이전 커밋은 웹사이트를 변경합니다. 이전 배포 SHA가 얕은 클론에서 누락되었거나 사용할 수 없는 경우, 건너뛰지 말고 빌드해야 합니다. 종료 코드 0은 빌드를 건너뛰고, 종료 코드 1은 진행합니다.

루트 디렉토리 'site'가 존재하지 않음

이는 일반적으로 site/에서 로컬 CLI 배포를 실행하는 동안 원격 프로젝트에도 루트 디렉토리 site가 있을 때 발생합니다. 위의 긴급/수동 CLI 배포 해결 방법을 사용하거나 Git 배포를 선호하십시오.

너무 많은 파일이 업로드됨

리포지토리 루트에서 배포하면 Rust/Python 빌드 아티팩트가 포함되어 Vercel의 파일 수 제한을 초과할 수 있습니다. 테스트된 무시/아카이브 전략 없이 리포지토리 루트를 직접 배포하지 마십시오. Git 배포나 임시 루트 재설정을 통한 site/의 긴급/수동 배포를 선호하십시오.

www.socai.io가 리디렉션 대신 200을 제공함

최신 프로덕션 배포에 site/vercel.json의 호스트 리디렉션이 포함되어 있는지 확인한 후 재배포하십시오. 다음으로 확인:

curl -I https://www.socai.io/

GitHub 최신 릴리스 메타데이터를 사용할 수 없음

웹사이트는 여전히 일반적인 비-오래된 복사본(latest release)을 표시해야 하며, /download는 여전히 GitHub의 최신 릴리스 자산으로 리디렉션되어야 합니다.

보고

배포 작업을 보고할 때 다음을 포함합니다:

• 리포지토리 파일이 변경된 경우 브랜치/PR
• 확인된 Vercel 프로젝트 설정
• 배포 URL 및 프로덕션 도메인
• 실행된 명령어
• /, /docs/, /docs/quickstart/, www, /download, /github에 대한 확인 출력 요약
• 특히 Git 통합/PR 미리보기와 관련된 해결되지 않은 수동 차단 요인