> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aeolo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 기존 도메인의 서브폴더 연결

> /articles 같은 경로에 Aeolo 관리형 콘텐츠를 제공합니다.

기존 사이트를 유지하면서 `https://www.example.com/articles`에 Aeolo가 렌더링하는 글을 제공합니다. 고객 서버나 CDN에서 해당 경로만 Aeolo HTTPS 원본으로 전달하며 방문자 주소창에는 고객 주소가 유지됩니다.

자체 앱에서 글 데이터를 받아 직접 화면을 구성하려면 [콘텐츠 피드 안내](/ko/guides/custom-website)를 사용합니다.

## 시작 전 확인

정본 호스트(`www` 포함 여부), 기존 서비스와 충돌하지 않는 경로, 서버·CDN 담당자를 정합니다. Aeolo에 호스트를 경로 연결 방식으로 등록하고 생성된 경로 설정을 제공해 달라고 요청합니다. 검증 전 연결은 대기 상태입니다.

아래 `example`과 `/articles`는 예시입니다. 전달받은 사이트별 설정으로 바꿉니다. Drive 원문 폴더와 웹사이트 경로는 서로 다른 설정이며, 원문을 가져오거나 글을 작성해도 자동 발행되지 않습니다.

## 양측 담당 작업

| 순서 | 담당 | 작업과 완료 증거 |
| - | - | - |
| 1 | 고객 개발팀 | 정본 호스트, `/articles` 사용 가능 여부, 서버/CDN 종류 확인 |
| 2 | Aeolo | 기존 사이트의 폴더 연결 방식으로 해당 호스트 등록. 연결 상태는 검증 전 `pending` |
| 3 | Aeolo → 고객 개발팀 | 등록 후 생성되는 최신 경로 설정 제공 |
| 4 | 고객 개발팀 | 아래 경로 전달 규칙을 테스트·배포하고 결과 공유 |
| 5 | 고객 검토자 | 글의 근거·법률 검토 및 명시적 발행 승인. 실제 승인 계정·시각 기록 |
| 6 | Aeolo·고객 개발팀 | 승인된 공개 글로 연결 검증 및 화면·링크 확인 |
| 7 | 고객·Aeolo | 검색 노출 승인 후 인덱싱 설정, robots.txt 및 사이트맵 점검 |

승인된 공개 글이 없다면 최종 연결 검증은 해당 글이 준비될 때까지 대기합니다. 연결을 위해 초안을 임의 발행하지 않습니다.

## 서버/CDN에서 전달할 경로

현재 `/articles` 기준 매핑입니다. 실제 적용본은 호스트 등록 후 Aeolo가 제공하는 최신 `path_setup` 응답으로 확정합니다. 폴더 경로를 변경하면 이 규칙도 다시 받아야 합니다.

| 고객 요청 경로 | Aeolo 원본 요청 경로 |
| - | - |
| `/articles` | `https://example.aeolo.site/__aeolo_path/articles` |
| `/articles/{slug}` | `https://example.aeolo.site/__aeolo_path/articles/{slug}` |
| `/articles/__aeolo/sitemap.xml` | `https://example.aeolo.site/__aeolo_path/articles/__aeolo/sitemap.xml` |
| `/articles/__aeolo/*` | `https://example.aeolo.site/__aeolo_path/articles/__aeolo/*` |

* `/articles`와 `/articles/*`를 모두 처리합니다. 기존 SPA/catch-all보다 우선해야 합니다.
* 고객에게 외부 원본으로 이동시키는 redirect가 아니라, 서버/CDN의 rewrite 또는 reverse proxy를 사용합니다.
* 하위 경로와 query string을 보존합니다. `/articles`를 잘라내지 않습니다.
* 원본 HTTPS의 SNI와 Host는 `example.aeolo.site`를 사용하고 TLS 인증서 검증을 유지합니다.
* root `/`, `/robots.txt`, `/sitemap.xml`, `/google*.html`과 기존 로그인·서비스 경로는 고객이 계속 처리합니다.
* 로그인 쿠키·Authorization 등 사용자 인증정보는 공개 콘텐츠 제공에 필요하지 않습니다. 사용하는 프록시의 전달 정책을 확인하고 원본으로 불필요한 인증정보를 보내지 않도록 설정합니다.
* 원본의 `Cache-Control: no-store`를 고객 CDN 캐시 정책으로 덮어쓰지 않습니다. Aeolo 내부 렌더 캐시와 고객 CDN 캐시는 별개입니다.

### Vercel 예시

기존 `vercel.json` 전체를 교체하지 말고 아래 두 규칙을 기존 rewrites에 병합합니다. 기존 catch-all보다 먼저 적용되는지 테스트합니다.

```json theme={null}
{
  "rewrites": [
    {
      "source": "/articles",
      "destination": "https://example.aeolo.site/__aeolo_path/articles"
    },
    {
      "source": "/articles/:path*",
      "destination": "https://example.aeolo.site/__aeolo_path/articles/:path*"
    }
  ]
}
```

프로젝트에 기존 프레임워크 라우팅이나 인증 미들웨어가 있으면 rewrite 우선순위와 인증 헤더 전달 정책을 함께 확인합니다. 다른 CDN을 사용한다면 해당 플랫폼의 HTTPS 원본 프록시 기능으로 같은 매핑을 적용합니다. Cloudflare Pages의 외부 `_redirects 200` 규칙만으로는 이 프록시를 구성할 수 없습니다. Worker/Function 등 별도 프록시 경로가 필요합니다.

### Nginx 예시

고객의 해당 HTTPS virtual host에 추가합니다. CA 파일 경로는 서버 배포판에 맞게 지정합니다.

```nginx theme={null}
location = /articles {
    proxy_pass https://example.aeolo.site/__aeolo_path/articles;
    proxy_ssl_server_name on;
    proxy_ssl_verify on;
    proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
    proxy_set_header Host example.aeolo.site;
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
}

location ^~ /articles/ {
    proxy_pass https://example.aeolo.site/__aeolo_path/articles/;
    proxy_ssl_server_name on;
    proxy_ssl_verify on;
    proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
    proxy_set_header Host example.aeolo.site;
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
}
```

`nginx -t`로 설정을 검증한 뒤 고객의 배포 절차에 따라 반영합니다. 예시는 고객 서버에서 실행·검증된 설정이 아닙니다.

## 연결 검증과 검색 노출

설정 반영 후 Aeolo는 **승인된 실제 공개 글의 고객 URL**로 연결을 검증합니다. 홈이나 임의 확인 경로의 HTTP 200만으로 완료 처리하지 않습니다.

* HTTPS, redirect 없이 200 HTML 응답
* 요청별 검증 challenge 및 고객/해당 글 식별 확인
* 고객 공개 URL과 일치하는 단일 canonical
* 데스크톱·모바일 본문, 이미지, 메뉴, 목록 복귀 및 관련 글 링크
* 기존 사이트의 다른 경로가 정상 동작하는지 확인

자동 검증이 성공해야 연결이 `serving`으로 바뀝니다. 연결 성공은 검색 노출 허용과 별개입니다. 인덱싱 보류 상태라면 `noindex, nofollow`가 남고 사이트맵이 제공되지 않을 수 있습니다. 검색 노출을 승인한 뒤 다음을 확인합니다.

1. Aeolo의 인덱싱 설정을 활성화합니다.
2. 고객의 robots.txt가 `/articles`를 차단하지 않는지 확인합니다.
3. `https://{확정한-고객-호스트}/articles/__aeolo/sitemap.xml`을 기존 사이트맵 또는 Search Console에 등록합니다. 최종 URL은 Aeolo가 제공한 설정 응답을 사용합니다.

고객 root 도메인의 Search Console 소유권은 이 연결로 자동 이전되지 않습니다. 연결·사이트맵 제출·수집·색인·AI 검색 인용은 서로 다른 상태입니다.

## 수정·해제와 오류 확인

| 현상 | 먼저 확인할 항목 |
| - | - |
| 고객 기존 화면 또는 404가 나옴 | rewrite 경로 두 개, catch-all 순서, 폴더/slug, 공개 승인 상태 |
| 원본 사이트로 주소가 바뀜 | redirect 대신 rewrite/proxy인지 |
| 연결 검증이 실패함 | 정본 호스트, 실제 공개 글, canonical, 원본 응답 헤더·challenge, 고객 CDN 캐시 |
| 사이트맵이 404임 | 인덱싱 보류 상태인지 확인. 승인 없이 검색 노출을 켜지 않음 |
| 이미지·메뉴가 깨짐 | 캡처 템플릿, 외부 리소스, 모바일/데스크톱 화면을 별도 점검 |

문제가 생기면 기존 서버 설정을 복구하고 Aeolo에 연결 해제를 요청합니다. 고객 프록시 규칙 제거와 Aeolo 연결 해제는 별도 작업입니다. 공개 URL이 이미 운영 중이면 제거 시 404가 발생할 수 있으므로 전환 주소·리다이렉트 계획을 먼저 합의합니다. 전체 DNS 이전이나 기존 콘텐츠 삭제는 이 작업에 포함되지 않습니다.

## 관련 안내

* [콘텐츠 피드로 자체 화면에 연결](/ko/guides/custom-website)
* [Drive 원문 폴더 리라이팅](/ko/guides/drive-folder-rewriting)

## 플랫폼 참고 문서

* [Vercel rewrites](https://vercel.com/docs/routing/rewrites)
* [Cloudflare Pages proxy limits](https://developers.cloudflare.com/pages/configuration/redirects/#proxying)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.