Cloudflare에 배포하기

Cloudflare Workers는 EmDash를 위한 빠르고 전 세계적으로 분산된 런타임을 제공합니다. 이 가이드는 데이터베이스용 D1과 미디어 저장소용 R2를 사용한 배포를 다룹니다.

전제 조건

• Cloudflare 계정
• Wrangler CLI 설치 (npm install -g wrangler)
• Cloudflare로 인증 (wrangler login)

바인딩 구성

프로젝트 루트에 D1 및 R2 바인딩이 포함된 wrangler.jsonc를 생성합니다. Wrangler는 아직 존재하지 않는 경우 첫 번째 배포 시 두 리소스를 모두 프로비저닝합니다.

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "my-emdash-site",
	"compatibility_date": "2025-01-15",
	"compatibility_flags": ["nodejs_compat"],

	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "emdash-db",
		},
	],

	"r2_buckets": [
		{
			"binding": "MEDIA",
			"bucket_name": "emdash-media",
		},
	],
}

EmDash 구성

D1 및 R2를 사용하도록 Astro 구성을 업데이트합니다:

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import emdash from "emdash/astro";
import { d1, r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
	output: "server",
	adapter: cloudflare(),
	integrations: [
		emdash({
			database: d1({ binding: "DB" }),
			storage: r2({ binding: "MEDIA" }),
		}),
	],
});

첫 번째 부팅

데이터베이스 마이그레이션은 배포 후 첫 번째 요청 시 자동으로 실행되며, 적용할 새로운 내용이 있는 경우 이후 부팅 시마다 실행됩니다.

데이터베이스가 비어 있고(컬렉션 없음) 설정 마법사가 완료되지 않은 경우, EmDash는 첫 번째 부팅 시 시드 파일도 적용합니다. 시드는 빌드 시 .emdash/seed.json, package.json#emdash.seed의 경로 또는 seed/seed.json에서 읽습니다 — 먼저 발견되는 것을 사용 — 번들에 인라인됩니다. 없는 경우 내장된 기본 시드가 사용됩니다. 기존 데이터베이스에 대한 후속 배포는 콘텐츠를 그대로 둡니다.

배포

Cloudflare Workers에 배포:

wrangler deploy

사이트는 이제 https://my-emdash-site.<your-subdomain>.workers.dev에서 활성화됩니다.

읽기 복제본

전 세계적으로 분산된 사이트의 경우, D1 읽기 복제를 활성화하여 항상 기본 데이터베이스에 액세스하는 대신 가까운 복제본으로 읽기 쿼리를 라우팅합니다. 이는 기본 지역에서 멀리 떨어진 방문자의 지연 시간을 크게 줄입니다.

emdash({
	database: d1({
		binding: "DB",
		session: "auto",
	}),
	storage: r2({ binding: "MEDIA" }),
}),

또한 Cloudflare 대시보드 또는 REST API를 통해 D1 데이터베이스 자체에서 읽기 복제를 활성화해야 합니다.

세션 모드 및 북마크 기반 일관성 작동 방식은 데이터베이스 옵션 — 읽기 복제본을 참조하십시오.

커스텀 도메인

Cloudflare 대시보드에서 커스텀 도메인을 추가합니다:

1. Workers & Pages > 워커로 이동
2. Custom Domains > Add Custom Domain 클릭
3. 도메인을 입력하고 DNS 설정 지침을 따릅니다

공개 R2 액세스

R2에서 직접 미디어를 제공하려면(성능을 위해 권장):

1. Cloudflare 대시보드에서 R2 > 버킷으로 이동
2. Settings > Public access 클릭
3. 공개 액세스를 활성화하고 공개 URL을 기록합니다
4. 스토리지 구성을 업데이트합니다:

storage: r2({
  binding: "MEDIA",
  publicUrl: "https://pub-xxx.r2.dev"
}),

Cloudflare Access 인증

조직에서 Cloudflare Access를 사용하는 경우, 패스키 대신 인증 공급자로 사용하여 기존 ID 공급자를 통해 Single Sign-On을 제공할 수 있습니다. 다음 구성으로 활성화됩니다:

emdash({
  database: d1({ binding: "DB" }),
  storage: r2({ binding: "MEDIA" }),
  auth: access({
    teamDomain: "myteam.cloudflareaccess.com",
    audience: "your-app-audience-tag",
    roleMapping: {
      "Admins": 50,
      "Editors": 40,
    },
  }),
}),

전체 구성 옵션은 인증 가이드를 참조하십시오.

환경 변수

권장: 암호화 키

EMDASH_ENCRYPTION_KEY는 저장된 플러그인 시크릿(웹훅 토큰, Turnstile 키 등)을 암호화하는 키입니다. 키는 시작 시 검증되며, 플러그인 시크릿 암호화는 활성화되면 이를 사용합니다. 나중에 구성을 변경하지 않고도 시크릿이 보호되도록 모든 배포에서 설정하십시오.

키는 사용자가 제공하며 데이터베이스에 저장되지 않습니다. 암호화된 암호문만 저장됩니다. 키를 잃으면 그것으로 암호화된 모든 시크릿을 잃게 됩니다.

다음 명령으로 키를 생성하고 Worker 시크릿으로 저장합니다:

npx emdash secrets generate
wrangler secret put EMDASH_ENCRYPTION_KEY

선택 사항: 안정적인 값 재정의

EmDash는 미리보기 HMAC 시크릿과 댓글 작성자 IP 해시 솔트를 자동 생성하고 첫 사용 시 데이터베이스에 유지합니다. 아래 환경 변수는 값을 직접 고정해야 하는 경우를 위한 재정의입니다 — 예를 들어 별도의 프로세스에서 미리보기 Worker가 메인 사이트와 시크릿을 공유해야 하는 경우입니다.

구성에서 import.meta.env 또는 Cloudflare env 바인딩을 사용하여 환경 변수에 액세스합니다.

미리보기 배포

미리보기 브랜치를 배포합니다:

wrangler deploy --env preview

wrangler.jsonc에 환경 섹션을 추가합니다:

{
	"env": {
		"preview": {
			"d1_databases": [
				{
					"binding": "DB",
					"database_name": "emdash-db-preview",
				},
			],
		},
	},
}

문제 해결

”D1 binding not found”

wrangler.jsonc의 바인딩 이름이 데이터베이스 구성과 일치하는지 확인합니다:

// Must match: d1({ binding: "DB" })
"binding": "DB"

“R2 binding not found”

R2 버킷이 올바르게 바인딩되었는지 확인합니다:

// Must match: r2({ binding: "MEDIA" })
"binding": "MEDIA"

마이그레이션 오류

스키마 오류가 표시되면 Worker 로그(wrangler tail)를 추적하고 오류를 재현하여 기본 메시지를 캡처한 다음 해당 출력으로 이슈를 제출하십시오.