Skip to content
Internal Engineering Docs

Governance v3 + Cloudflare 재구성

Governance v3 + Cloudflare 재구성

본 문서는 Astro + Starlight 내부 위키에 둔다. DataStax Astra DB와 혼동하지 말 것.

외부 Governance 정책 원문은 그린필드 싱글 모노레포(/apps/web + /apps/docs)를 가정한다. apibay-labs는 멀티레포 + 다중 Worker/Pages이며, Hono RPC·drizzle-zod·RBAC·Astro Starlight가 이미 동작한다.

확정 적용:

  • 레포 통합 금지. 서비스 경계 유지.
  • Worker/Pages 이름은 v6 유지. D1/KV/R2/Queue/Vectorize만 정책 문법.
  • Phase 2–6 앱 스캐폴드 없음. users.role을 ADMIN/MANAGER/USER로 재정의하지 않음 (owner|admin|member|viewer 유지).
  • labs-core는 범위 밖.

교차 참조: core-platform CLOUDFLARE_SETUP.

토폴로지

Browsers: core-admin / app-dashboard / app-portal
    → edge-gateway (공개 인그레스)
    → core-api (테넌트 SSOT, JWT)
         → ops-control (HMAC compile)
         → infra-email (q-email-outbound)
         → infra-git-sync (q-gateway-compile)

Worker / Pages (이름 변경 없음)

Wrangler name 변경은 새 Cloudflare 프로젝트를 만든다. 롤백은 DNS/라우트를 이전 이름으로 되돌린 뒤 신규 프로젝트를 폐기한다.

Cloudflare name레포종류
core-apicore-platformWorker API
ops-controlinfra-control-planeWorker API (내부)
edge-gatewayedge-api-gatewayWorker API (인그레스)
infra-emailinfra-emailWorker Jobs
infra-git-syncinfra-git-syncWorker Jobs
core-adminweb-public/apps/adminPages
app-dashboardweb-public/apps/dashboardWorker (OpenNext)
web-publicweb-public/apps/webWorker (OpenNext)
docs-publicweb-public/apps/docsPages
docs-internalweb-public/apps/internal-docsPages
app-portalweb-public/apps/customer-portalPages
core-flow-editorweb-public/apps/flow-editorPages

스토리지 (정책 문법)

바인딩 키(DB, KV_SESSION 등)는 코드 호환을 위해 유지한다. ID가 REPLACE_WITH_*이면 첫 생성 시 정책명으로 만든다.

이전 이름정책명바인딩소유편입
core-d1apibay-core-dbDBcore-api테넌트 SSOT
ops-d1apibay-ops-dbDBops-controlSTOP-AND-ASK #1. HMAC 경계. 병합 비권장
core-r2r2-platform-filesBUCKETcore-api
admin-assetsr2-admin-assetsADMIN_ASSETScore-api + edge-gateway공유 1버킷
(이름 미기재)kv-platform-sessionKV_SESSIONcore-api
(이름 미기재)kv-gateway-rate-limitKV_RATE_LIMITcore-api + edge-gateway공유 1개
(이름 미기재)kv-gateway-routesKV_TENANTS / KV_ROUTE_TABLEops-control + edge-gateway공유 1개
email-queueq-email-outbound + -dlqQUEUE_EMAILcore-api produce, infra-email consume
gateway-compile-queueq-gateway-compile + -dlqQUEUE_COMPILEinfra-git-sync
core-ai기존 384d면 재사용VECTOR_INDEXcore-api없으면 vec-platform-v1

편입 절차

  1. Cloudflare 계정에서 D1 / KV / R2 / Queue / Vectorize 목록을 확인한다.
  2. 기존 자원이 있으면 바인딩 ID만 갱신하고 정책명을 wrangler 주석에 기록한다.
  3. 없으면 정책명으로 생성한다. 신규 D1은 STOP-AND-ASK #1.
  4. Queue는 primary와 -dlq를 동시에 만든다.
  5. 프로비저닝·wrangler deploy는 GitHub Actions(ops-ci-workflows)만. 로컬 wrangler deploy 금지.

STOP-AND-ASK

  1. 신규 D1 — apibay-core-db / apibay-ai-db 편입 불가를 확인한 뒤에만. 권고: apibay-ops-db를 별도로 유지.
  2. .env.example에 없는 Secret 키 이름. JWT_SECRET / DATABASE_URL을 새로 만들지 말 것 (AUTH_SECRET + D1).
  3. CODEOWNERS 실계정 — 지금은 @CHANGE_ME-platform-owners.

CI/CD

배포는 apibay-labs/ops-ci-workflows reusable workflow + secrets: inherit만 사용한다. 린트·보안 스캔은 ops-ci-workflows/governance를 extend한다. 레포에 자체 ESLint/Prettier/보안 설정을 신규 생성하지 않는다.

E2E 타입 체인 (기존 유지)

Drizzle schema → drizzle-zod → Hono zValidator → AppType RPC → hc<AppType>() → RHF + zodResolver

정책 역할 ADMIN|MANAGER|USER는 auth-kit owner|admin|member|viewer에 매핑한다.

Branch Protection (수동)

GitHub Settings → Branches → main:

  • Require a pull request before merging
  • Require status checks to pass (ci workflow)
  • Require branches to be up to date before merging
  • Do not allow bypassing the above settings
  • Restrict who can push to matching branches

에이전트는 GitHub 보호 규칙을 변경하지 않는다.

완료 체크리스트

  • Phase 0 정책 킷 (제품 레포)
  • D1/Queue/Vectorize 편입 검토 문서화
  • 하이브리드 네이밍 준수 (Worker/Pages v6, 스토리지 정책식)
  • wrangler deploy는 GitHub Actions 경유만
  • Secret 하드코딩 없음, 기존 키만 .env.example
  • ops-ci-workflows/governance 상속 (자체 lint 신규 파일 없음)
  • E2E 타입 체인 기존 구현 유지
  • ProtectedRoute / RBAC 기존 연결 유지
  • UI 토큰 규칙 문서화 (신규 hex 금지)
  • Astro(문서) ≠ Astra DB
  • CODEOWNERS 실계정 (플레이스홀더만 삽입)
  • Branch Protection 수동 설정

비범위

  • 멀티레포를 /apps/web + /apps/docs로 합치기
  • Worker/Pages v6 이름 변경
  • GitHub 레포 슬러그 rename (core-platform → core) — 2차 웨이브
  • labs-core 키트 전면 개편