https://github.com/jongha/notion-embedded-lambda

This project is an AWS Lambda function that allows you to embed Notion pages on other webpages using a custom domain. It serves Notion content through your own domain instead of Notion's default URL, maintaining URL paths for better SEO and branding.
https://github.com/jongha/notion-embedded-lambda

embedded notion

Last synced: 2 months ago
JSON representation

This project is an AWS Lambda function that allows you to embed Notion pages on other webpages using a custom domain. It serves Notion content through your own domain instead of Notion's default URL, maintaining URL paths for better SEO and branding.

• Host: GitHub
• URL: https://github.com/jongha/notion-embedded-lambda
• Owner: jongha
• Created: 2025-06-08T07:53:16.000Z (about 1 year ago)
• Default Branch: main
• Last Pushed: 2025-06-09T10:41:36.000Z (about 1 year ago)
• Last Synced: 2025-12-31T11:42:43.542Z (6 months ago)
• Topics: embedded, notion
• Language: JavaScript
• Homepage:
• Size: 18.6 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.ko.md

Awesome Lists containing this project

README

          
# notion-embeded-lambda

이 프로젝트는 Notion 페이지를 사용자 정의 도메인을 사용하여 다른 웹페이지에 임베드할 수 있도록 하는 AWS Lambda 함수입니다. Notion의 기본 URL 대신 자체 도메인을 통해 Notion 콘텐츠를 제공하며, SEO 및 브랜딩에 유리하도록 URL 경로를 유지합니다.

## 이 프로젝트가 필요한 이유

Notion은 강력한 문서 및 협업 도구이지만, Notion 페이지를 자체 웹사이트나 서비스에 직접 임베드하여 사용할 때 몇 가지 제약 사항이 있습니다. 이 프로젝트는 다음과 같은 문제를 해결하고 추가적인 이점을 제공합니다:

- **사용자 정의 도메인 사용:** Notion 페이지를 `your-domain.com/my-page`와 같이 자체 도메인으로 제공하여 브랜드 일관성을 유지하고 사용자 경험을 향상시킬 수 있습니다.

- **SEO 최적화:** Notion의 기본 URL(`notion.site`) 대신 자체 도메인을 사용하면 검색 엔진 최적화(SEO)에 더 유리합니다. 검색 엔진은 자체 도메인의 콘텐츠를 더 신뢰하는 경향이 있습니다.

- **URL 경로 유지 및 제어:** Notion 페이지의 원래 URL 경로 구조를 그대로 유지하거나 원하는 대로 변경하여 프록시할 수 있어, 사용자가 익숙한 URL 구조를 유지하면서 콘텐츠를 제공할 수 있습니다.

- **임베딩 제한 극복:** 일부 플랫폼이나 웹사이트 빌더는 Notion 페이지의 직접적인 임베딩을 제한하거나 iframe 사용 시 스타일 및 기능적 제약이 있을 수 있습니다. 이 프로젝트는 이러한 제한을 우회하여 Notion 콘텐츠를 더 자유롭게 통합할 수 있도록 합니다.

- **성능 및 로딩 속도 개선 (CloudFront 사용 시):** Amazon CloudFront와 같은 CDN과 함께 사용하면 전 세계 사용자에게 더 빠른 페이지 로딩 속도를 제공하고, 불필요한 Notion API 호출을 차단하여 성능을 개선할 수 있습니다.

- **콘텐츠 접근 제어 및 커스터마이징:** Lambda 함수를 통해 Notion 페이지로 가는 요청을 중간에서 가로채므로, 필요에 따라 특정 콘텐츠를 필터링하거나, 스타일을 추가로 변경하거나, 접근 권한을 제어하는 등의 고급 커스터마이징이 가능합니다.

- **다크 모드 비활성화 및 라이트 모드 강제:** 사용자의 시스템 설정과 관계없이 일관된 라이트 모드 경험을 제공하여 가독성을 높일 수 있습니다.

이러한 이유로, Notion 콘텐츠를 자체 브랜드와 통합하고, SEO를 강화하며, 사용자 경험을 개선하고자 하는 경우 이 프로젝트가 유용할 수 있습니다.

## 주요 기능

- Notion 페이지를 지정된 도메인으로 프록시

- 이미지 및 정적 자산 경로 자동 변환

- HTML 내 절대 경로를 상대 경로로 수정하여 올바른 리소스 로딩 지원

- 특정 API 경로 차단 및 모의 응답 처리

- 라이트 모드 강제 적용 (CSS 및 JavaScript)

- 클릭 가능한 링크의 경로를 프록시 경로로 자동 변환

## 사전 준비물

- AWS 계정

- Node.js 및 npm (Lambda 패키지 생성 시 로컬 환경에 필요할 수 있음)

- 사용자 정의 도메인 (선택 사항, ELB 또는 CloudFront 사용 시)

- Notion 페이지 (공개적으로 공유된 페이지)

## 설정 방법

### 1. Lambda 함수 설정 (`index.js`)

1.  `index.js` 파일을 열고 `CONFIG` 객체 내의 `NOTION_DOMAIN` 값을 자신의 Notion 도메인으로 변경합니다.

    - 예시: `your-workspace.notion.site`

    - `NOTION_BASE_URL`은 `NOTION_DOMAIN`을 기반으로 자동으로 설정됩니다.

    ```javascript

    // 설정 변수

    const CONFIG = {

      NOTION_DOMAIN: '[YOUR_NOTION_DOMAIN].notion.site', // 예: 'myworkspace.notion.site'

      NOTION_BASE_URL: 'https://[YOUR_NOTION_DOMAIN].notion.site', // 자동으로 'https://myworkspace.notion.site'로 설정됨

    };

    ```

### 2. 배포 옵션

#### 옵션 A: AWS Lambda + API Gateway

가장 기본적인 설정 방법입니다.

1.  **Lambda 함수 생성:**

    - AWS Management Console에 로그인하여 Lambda 서비스로 이동합니다.

    - "함수 생성"을 클릭합니다.

    - "새로 작성"을 선택합니다.

    - 함수 이름: (예: `notion-embed-proxy`)

    - 런타임: `Node.js` (최신 LTS 버전 권장, 예: Node.js 20.x)

    - 아키텍처: (기본값 또는 `arm64` 선택 가능)

    - 권한: 기본 Lambda 권한으로 새 역할 생성을 선택합니다.

    - "함수 생성"을 클릭합니다.

2.  **코드 업로드:**

    - 생성된 Lambda 함수의 "코드 소스" 섹션으로 이동합니다.

    - `index.js` 파일의 내용을 `index.mjs` 또는 `index.js` (런타임 설정에 따라) 파일에 붙여넣습니다.

      - `require` 대신 `import`를 사용하려면 파일 확장자를 `.mjs`로 변경하고, `package.json`에 `"type": "module"`을 추가하거나, 코드 내 `require`를 `import`로 수정해야 할 수 있습니다. 현재 코드는 CommonJS (`require`) 기준입니다.

    - `https://` 모듈은 Node.js 기본 모듈이므로 별도 설치가 필요 없지만, 만약 다른 외부 라이브러리를 사용한다면 `node_modules` 폴더와 함께 zip 파일로 압축하여 업로드해야 합니다. (이 프로젝트는 현재 외부 라이브러리 의존성이 없습니다.)

    - "배포" 또는 "변경 사항 저장"을 클릭합니다.

3.  **API Gateway 트리거 설정:**

    - Lambda 함수 페이지에서 "트리거 추가"를 선택합니다.

    - 소스 선택에서 `API Gateway`를 선택합니다.

    - "새 API 생성"을 선택합니다.

    - API 유형: `HTTP API` (더 간단하고 저렴) 또는 `REST API` (더 많은 기능 제공)

      - **HTTP API 사용 시:**

        - 보안: `열기` (나중에 사용자 지정 도메인 및 인증을 추가할 수 있음)

        - "추가 설정"에서 기본 스테이지 이름(`$default`)과 자동 배포가 활성화되어 있는지 확인합니다.

      - **REST API 사용 시:**

        - 보안: `열기`

        - "API 생성" 클릭 후, "작업" -> "메서드 생성" -> `ANY` 선택 -> 통합 유형 `Lambda 함수`, Lambda 프록시 통합 사용 체크, 생성한 Lambda 함수 선택.

        - "작업" -> "API 배포" -> 새 스테이지 생성 (예: `prod`).

    - "추가"를 클릭합니다.

4.  **API Gateway 엔드포인트 확인:**

    - 트리거 설정 후 API Gateway에서 생성된 API 엔드포인트 URL을 확인합니다. 이 URL을 통해 Notion 페이지가 프록시됩니다.

5.  **Lambda 함수 제한 시간 설정:**

    - Lambda 함수 구성 > 일반 구성에서 메모리 및 제한 시간을 적절히 설정합니다. Notion 페이지 로딩 시간에 따라 제한 시간을 넉넉하게 (예: 15초 ~ 30초) 설정하는 것이 좋습니다.

#### 옵션 B: AWS Lambda + API Gateway + Application Load Balancer (ALB)

사용자 지정 도메인, SSL/TLS 인증서 관리, 고정 IP (필요시) 또는 다른 AWS 서비스와의 통합을 위해 ALB를 사용할 수 있습니다.

1.  **Lambda 및 API Gateway 설정:** 옵션 A와 동일하게 설정합니다. HTTP API를 사용하는 것이 ALB와 통합하기 더 간편할 수 있습니다.

2.  **대상 그룹 생성:**

    - EC2 서비스 > 로드 밸런싱 > 대상 그룹으로 이동합니다.

    - "대상 그룹 생성"을 클릭합니다.

    - 대상 유형 선택: `Lambda 함수`

    - 대상 그룹 이름: (예: `notion-lambda-tg`)

    - 프로토콜 및 포트는 Lambda 대상 유형에서는 설정하지 않습니다.

    - VPC를 선택합니다.

    - 상태 검사: Lambda 대상 유형에는 기본 상태 검사가 적용됩니다.

    - "다음"을 클릭하고, 생성한 Lambda 함수를 선택한 후 "대상 그룹 생성"을 클릭합니다.

3.  **Application Load Balancer (ALB) 생성:**

    - EC2 서비스 > 로드 밸런싱 > 로드 밸런서로 이동합니다.

    - "로드 밸런서 생성"을 클릭하고 `Application Load Balancer`를 선택합니다.

    - 로드 밸런서 이름: (예: `notion-embed-alb`)

    - 체계: `인터넷 경계`

    - IP 주소 유형: `ipv4`

    - VPC 및 서브넷: Lambda 함수가 접근 가능한 VPC와 최소 2개 이상의 가용 영역에 있는 서브넷을 선택합니다.

    - 보안 그룹: HTTP (80) 및 HTTPS (443) 트래픽을 허용하는 보안 그룹을 생성하거나 선택합니다.

    - 리스너 및 라우팅:

      - 프로토콜 `HTTPS`, 포트 `443`으로 리스너를 추가합니다. (HTTP 리스너는 HTTPS로 리디렉션하도록 설정할 수 있습니다.)

      - 기본 작업: "다음으로 전달"을 선택하고 위에서 생성한 Lambda 대상 그룹을 선택합니다.

      - 보안 리스너 설정: AWS Certificate Manager (ACM)에서 SSL/TLS 인증서를 선택하거나 요청합니다.

    - "로드 밸런서 생성"을 클릭합니다.

4.  **DNS 설정:**

    - 사용자 정의 도메인이 있다면, DNS 공급자(예: Amazon Route 53)에서 CNAME 또는 Alias 레코드를 생성하여 도메인이 ALB의 DNS 이름을 가리키도록 설정합니다.

#### 옵션 C: AWS Lambda + API Gateway + Amazon CloudFront

콘텐츠 전송 네트워크(CDN)를 사용하여 전 세계 사용자에게 더 빠른 로딩 속도를 제공하고, 캐싱, SSL/TLS, 웹 애플리케이션 방화벽(WAF) 등의 추가 기능을 활용할 수 있습니다.

1.  **Lambda 및 API Gateway 설정:** 옵션 A와 동일하게 설정합니다. API Gateway의 엔드포인트 URL이 필요합니다.

2.  **CloudFront 배포 생성:**

    - CloudFront 서비스로 이동하여 "배포 생성"을 클릭합니다.

    - **원본 설정:**

      - 원본 도메인: API Gateway에서 얻은 엔드포인트 URL을 입력합니다. (예: `xxxxxxxxx.execute-api.region.amazonaws.com`)

      - 프로토콜: `HTTPS 전용`

      - 최소 원본 SSL 프로토콜: (기본값 또는 `TLSv1.2` 권장)

      - 원본 경로: API Gateway 스테이지 이름을 포함해야 할 수 있습니다 (예: `/prod`). REST API를 사용하고 스테이지가 있다면 입력합니다. HTTP API의 `$default` 스테이지는 일반적으로 경로가 필요 없습니다.

    - **기본 캐시 동작:**

      - 뷰어 프로토콜 정책: `HTTPS로 리디렉션`

      - 허용된 HTTP 메서드: `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE` (Lambda 함수가 처리하는 모든 메서드 허용)

      - 캐시 키 및 원본 요청:

        - `Cache policy and origin request policy (recommended)` 선택

        - 캐시 정책: `CachingDisabled` (Notion 콘텐츠는 동적이므로 캐싱하지 않는 것이 안전) 또는 매우 짧은 TTL로 사용자 지정 캐시 정책 생성.

        - 원본 요청 정책: `AllViewer` (모든 헤더, 쿼리 문자열, 쿠키 전달) 또는 필요한 최소한의 정보만 전달하도록 사용자 지정 정책 생성 (예: `Forward all query strings and cookies, and specific headers like 'Host', 'User-Agent'`). `Host` 헤더를 전달해야 Notion이 올바르게 응답할 수 있습니다.

      - 응답 헤더 정책: (선택 사항) 보안 헤더(HSTS, X-Content-Type-Options 등)를 추가할 수 있습니다.

    - **설정:**

      - 가격 책정 클래스: (필요에 따라 선택)

      - AWS WAF: (선택 사항) 웹 애플리케이션 방화벽을 사용하여 보호 계층을 추가할 수 있습니다.

      - 대체 도메인 이름 (CNAMEs): 사용자 정의 도메인을 입력합니다. (예: `notion.yourdomain.com`)

      - 사용자 지정 SSL 인증서: ACM에서 사용자 정의 도메인에 대한 SSL 인증서를 선택합니다. (필수)

      - 기본 루트 객체: (비워둠)

    - "배포 생성"을 클릭합니다. 배포가 완료되는 데 몇 분 정도 소요될 수 있습니다.

3.  **DNS 설정:**

    - 사용자 정의 도메인이 있다면, DNS 공급자(예: Amazon Route 53)에서 CNAME 또는 Alias 레코드를 생성하여 도메인이 CloudFront 배포 도메인 이름(예: `dxxxxxxxxxxxxx.cloudfront.net`)을 가리키도록 설정합니다.

## 중요 참고 사항

- **Notion 페이지 공개 설정:** 임베드하려는 Notion 페이지는 웹에서 공개적으로 공유되어 있어야 합니다 (`Share` -> `Share to web`).

- **URL 경로:** 이 Lambda 함수는 요청된 경로를 Notion URL에 그대로 전달합니다. 예를 들어 `https://your-custom-domain.com/my-notion-page-path`로 접속하면 `https://[YOUR_NOTION_DOMAIN].notion.site/my-notion-page-path`로 프록시됩니다.

- **스타일 및 스크립트:** `index.js`에는 Notion 페이지의 다크 모드를 비활성화하고 라이트 모드를 강제하는 CSS와 JavaScript가 포함되어 있습니다. 필요에 따라 수정하거나 제거할 수 있습니다.

- **API 경로 차단:** `index.js`의 `blockedPaths` 배열에 정의된 Notion 내부 API 경로는 200 OK와 빈 JSON 객체 `{}`를 반환하도록 설정되어 있습니다. 이는 불필요한 API 호출을 줄이고 로딩 속도를 개선하기 위함입니다.

- **CORS (Cross-Origin Resource Sharing):** Lambda 응답 헤더에 `Access-Control-Allow-Origin: '*'`가 포함되어 있어 대부분의 CORS 문제를 해결하지만, 특정 상황에서는 추가 설정이 필요할 수 있습니다.

- **제한 사항:** Notion의 구조나 HTML 마크업이 변경되면 이 프록시 함수가 정상적으로 작동하지 않을 수 있습니다. 주기적인 확인 및 업데이트가 필요할 수 있습니다.

## 문제 해결

- **502 Bad Gateway 오류 (API Gateway):** Lambda 함수 실행 시간 초과, Lambda 함수 오류, 잘못된 Lambda 프록시 통합 설정 등이 원인일 수 있습니다. CloudWatch Logs에서 Lambda 함수 로그를 확인하세요.

- **이미지 또는 CSS가 깨져 보이는 경우:** `index.js` 내의 URL 변환 로직이 Notion의 현재 URL 구조와 맞지 않을 수 있습니다. `processHtmlResponse` 함수와 `processOtherResponse` 함수의 URL 교체 로직을 확인하고 업데이트해야 할 수 있습니다.

- **CloudFront에서 `Host` 헤더 전달:** CloudFront를 사용할 경우, 원본 요청 정책에서 `Host` 헤더를 원본(API Gateway)으로 전달하도록 설정해야 Notion이 올바른 페이지를 반환합니다.

- **CloudFront 캐싱:** Notion 페이지는 동적이므로 CloudFront 캐시 정책을 `CachingDisabled`로 설정하거나 매우 짧은 TTL을 사용하는 것이 좋습니다. 그렇지 않으면 이전 버전의 페이지가 표시될 수 있습니다.