개발팀 문서 접근 제어

문서 사이트는 애플리케이션 사용자 인증과 분리된 Cloudflare Pages 프로젝트로 배포하고, Cloudflare Access가 모든 요청을 인증합니다.

Developer
  -> Cloudflare Access (GitHub organization/team + independent MFA)
  -> eduboard-docs Pages
  -> Docusaurus static assets

Access는 정적 파일이 전달되기 전에 동작하므로 Docusaurus 코드에서 문서 링크만 숨기는 방식보다 안전합니다.

권장 배포 경계

항목	값
Pages project	`eduboard-docs`
Production branch	`main`
Build command	`npm ci && npm run typecheck && npm run build`
Build output	`build`
Production hostname	`docs.<company-domain>`
Docusaurus URL variable	`DOCS_SITE_URL=https://docs.<company-domain>`

문서 프로젝트는 Frontend 애플리케이션 Pages 프로젝트와 분리합니다. 문서 장애나 Access 정책 변경이 사용자용 애플리케이션 배포에 영향을 주지 않고, 호스트 전체에 단일 Access 정책을 적용할 수 있습니다.

GitHub에서 OAuth App을 생성합니다.
Homepage URL은 https://<team-name>.cloudflareaccess.com으로 설정합니다.
Authorization callback URL은 https://<team-name>.cloudflareaccess.com/cdn-cgi/access/callback으로 설정합니다.
Cloudflare Zero Trust의 Integrations > Identity providers에서 GitHub를 추가합니다.
GitHub 조직과 팀 정보를 읽을 수 있도록 OAuth App을 승인하고 연결 테스트를 실행합니다.

GitHub client secret은 Cloudflare에만 저장하고 저장소나 Pages 환경 변수에 넣지 않습니다.

로컬에서 직접 배포할 때는 다음 명령을 사용합니다.

npm run docs:deploy

Zero Trust의 Access controls > Applications에서 Self-hosted 애플리케이션을 만들고 docs.<company-domain> 전체를 보호합니다.

권장 정책:

조직 전체가 문서를 봐야 한다면 Include에 GitHub organization만 사용합니다. 최소 권한이 필요하면 docs-readers 같은 전용 GitHub team을 Require 조건으로 추가합니다.

GitHub IdP는 Access의 IdP 기반 MFA method claim 강제 대상이 아니므로 Cloudflare Access의 independent MFA를 사용합니다.

이 설정은 GitHub 계정의 2FA 여부와 별개로 문서 접근 시 두 번째 인증을 강제합니다.

Custom domain만 보호하면 Pages 기본 도메인이나 preview URL로 문서를 우회할 수 있습니다.

모든 주소는 인증 전 문서 HTML, JavaScript, 검색 인덱스, source map을 반환하지 않아야 합니다.

Backend 문서 원본은 ../Backend/docs에 유지합니다. Docs 저장소의 배포 가능한 복사본은 다음 명령으로 생성합니다.

npm run docs:sync
npm run docs:sync:check

기본적으로 Docs와 Backend 저장소가 같은 상위 디렉터리에 있다고 가정합니다. 다른 위치에서는 BACKEND_REPO_DIR을 지정합니다.

BACKEND_REPO_DIR=/path/to/Backend npm run docs:sync

docs/backend 파일은 생성 결과이므로 직접 수정하지 않습니다. Backend 문서를 변경한 커밋에는 동기화된 Docs 문서 변경도 함께 포함해야 합니다.