# 내 사이트에서 헬프 센터 제공하기

헬프 센터는 처음부터 `<address>.help.mocco.club`에서 열립니다. 이 주소 대신 내 웹사이트의 `example.com/docs` 같은 곳에 두고 싶다면 헬프 센터에 **경로**를 추가할 수 있습니다. 내 웹사이트가 그 경로를 Mocco로 전달하면, Mocco는 페이지를 내 사이트의 일부처럼 보여 줍니다. 링크, 페이지 주소, 사이트맵, 검색 결과가 모두 `example.com/docs`를 씁니다.

이 방식은 헬프 센터 전체에 별도의 호스트 이름을 주는 [자체 도메인 사용하기](https://www.mocco.club/docs/ko/articles/im56b3-help-center#use-your-own-domain)와 다릅니다. 웹사이트가 이미 있고 도움말을 그 옆에 두고 싶을 때 경로를 사용하세요. 웹사이트가 이미 DNS 레코드와 인증서를 갖고 있으므로 따로 준비할 것은 없습니다.

이렇게 제공할 수 있는 것은 두 가지입니다.

- **헬프 센터 전체**: `/docs` 같은 경로 하나 아래의 모든 페이지.
- **피드백 보드 하나**: `/help` 같은 경로 아래의 공개 보드 하나.

워크스페이스의 소유자나 관리자여야 하고, 웹사이트의 프록시나 리라이트 규칙을 바꿀 수 있어야 합니다.

## 1. 경로 추가하기

프로젝트의 **Help center** 페이지에서 **Your domain**을 찾습니다. **Part of the site**를 고르고, 방문자가 쓸 주소인 **Public URL**(예: `https://example.com/docs`)을 입력한 뒤 **Add path**를 선택합니다.

공개 URL은 `https`여야 하고, 경로는 소문자, 숫자, 점, 하이픈, 밑줄로만 만들 수 있습니다. 포트, 쿼리, `#`은 쓸 수 없습니다. Mocco 주소는 쓸 수 없고, 경로 없이 도메인만 쓸 수도 없습니다.

![공개 URL을 입력해 추가할 준비가 된 Your domain 섹션](https://fi-workers-mocco-storage.s3.ap-northeast-2.amazonaws.com/pub/w/93e11fe8-0494-4e3d-b1cb-fe4dffd3ee7e/p/d64785b8-9a23-4fa1-a81d-550af30e203a/helpcenter/2657a693-5263-42b1-9468-a0a042097541/your-domain-add.png)

경로는 **Waiting for your proxy** 상태로 시작합니다. 이 단계에서는 내 사이트도 Mocco도 달라지는 것이 없습니다.

![프록시를 기다리는 경로와, 복사해서 쓸 Next.js 설정](https://fi-workers-mocco-storage.s3.ap-northeast-2.amazonaws.com/pub/w/93e11fe8-0494-4e3d-b1cb-fe4dffd3ee7e/p/d64785b8-9a23-4fa1-a81d-550af30e203a/helpcenter/75b326b0-3743-41b3-8cee-2a421c263395/your-domain-pending.png)

## 2. 경로를 Mocco로 전달하기

경로 아래에 Next.js, `vercel.json`, Cloudflare, nginx용 설정이 내 주소로 채워져 나옵니다. 아래 네 가지는 `https://example.com/docs`와 주소가 `orbit`인 헬프 센터 기준이며, 콘솔에는 내 값으로 표시됩니다.

모든 설정은 경로를 **그대로** 전달하고(`/docs/en/search`는 Mocco에 `/_proxy/orbit/en/search`로 도착합니다) 쿼리 문자열도 유지합니다.

![복사 버튼이 있는 Cloudflare 설정](https://fi-workers-mocco-storage.s3.ap-northeast-2.amazonaws.com/pub/w/93e11fe8-0494-4e3d-b1cb-fe4dffd3ee7e/p/d64785b8-9a23-4fa1-a81d-550af30e203a/helpcenter/0ff3ba27-8baf-4e92-8e33-c3bc2fdbcee9/your-domain-recipe.png)

**Next.js**

```ts
// next.config.ts
async rewrites() {
  return [
    { source: '/docs', destination: 'https://www.mocco.club/_proxy/orbit' },
    { source: '/docs/:path*', destination: 'https://www.mocco.club/_proxy/orbit/:path*' },
  ];
},
```

**Vercel**

```json
// vercel.json
{
  "rewrites": [
    { "source": "/docs", "destination": "https://www.mocco.club/_proxy/orbit" },
    { "source": "/docs/:path*", "destination": "https://www.mocco.club/_proxy/orbit/:path*" }
  ]
}
```

**Cloudflare**

```js
// Cloudflare Worker. Routes: <your domain>/docs and <your domain>/docs/*
export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname !== '/docs' && !url.pathname.startsWith('/docs/')) {
      return fetch(request);
    }
    const rest = url.pathname.slice(5);
    const target = new URL('https://www.mocco.club/_proxy/orbit' + rest + url.search);
    return fetch(new Request(target, new Request(request, { redirect: 'manual' })));
  },
};
```

**nginx**

```nginx
location /docs/ {
  proxy_pass https://www.mocco.club/_proxy/orbit/;
  proxy_set_header Host www.mocco.club;
  proxy_ssl_server_name on;
}
location = /docs {
  proxy_pass https://www.mocco.club/_proxy/orbit;
  proxy_set_header Host www.mocco.club;
  proxy_ssl_server_name on;
}
```

다음 단계로 가기 전에 변경 사항을 웹사이트에 배포하세요. 경로를 바꾸는 규칙(예: `/docs/*`를 `/_proxy/orbit/*`가 아닌 다른 곳으로 보내는 규칙)은 지원하지 않으며, 아래 확인이 실패합니다.

## 3. 확인하기

**Check now**를 선택합니다. Mocco가 공개 URL의 `/.well-known/mocco-site`에 작은 증표를 요청합니다. 이 증표는 Mocco만, 그것도 내 프록시를 거쳤을 때만 답합니다. 올바른 답을 받으면 경로가 **Active**가 됩니다.

![활성 상태의 경로와, 사이트맵을 등록하라는 안내](https://fi-workers-mocco-storage.s3.ap-northeast-2.amazonaws.com/pub/w/93e11fe8-0494-4e3d-b1cb-fe4dffd3ee7e/p/d64785b8-9a23-4fa1-a81d-550af30e203a/helpcenter/1cd430c9-e44e-4ba8-987a-2a5f526d39d6/your-domain-active.png)

이후 페이지는 내 주소에서 제공됩니다. 헬프 센터의 원래 주소(`<address>.help.mocco.club`)는 방문자를 내 페이지로 영구 리디렉션하므로 기존 링크도 계속 동작합니다. Mocco가 최근 응답을 잠시 보관하기 때문에 리디렉션이 시작되기까지 잠깐 걸릴 수 있습니다.

![고객의 프록시를 거쳐 제공되는 헬프 센터 페이지](https://fi-workers-mocco-storage.s3.ap-northeast-2.amazonaws.com/pub/w/93e11fe8-0494-4e3d-b1cb-fe4dffd3ee7e/p/d64785b8-9a23-4fa1-a81d-550af30e203a/helpcenter/843abd79-4230-4cde-83fd-107ada85c4ef/own-site-served.png)

### 확인이 실패할 때

실패한 경로에는 이유와 함께 **Last check failed**가 표시되고, 상태는 그대로 유지됩니다. 이유는 다음과 같습니다.

- `<url> answered HTTP 404`(또는 다른 상태 코드): 요청이 그 경로를 모르는 서버에 도착했습니다. 웹사이트에 규칙이 아직 배포되지 않았거나, 규칙이 경로와 맞지 않거나, 프록시가 중간에 경로를 바꾸는 경우가 많습니다. 경로에 표시된 설정과 비교해 보세요.
- `Couldn't reach <url>: <error>`: 웹사이트가 응답하지 않았거나 연결이나 인증서에 문제가 있습니다. 브라우저에서 그 주소를 열어 방문자에게 무엇이 보이는지 확인하세요.
- `<url> answered a redirect to <address>; forward the path without redirecting`: 웹사이트가 경로를 전달하지 않고 리디렉션합니다. 끝 슬래시를 붙이거나 떼는 경우, 다른 호스트로 보내는 경우 등입니다. 위 설정처럼 전달하세요.
- `<url> answered another token; it forwards somewhere else`: 경로가 다른 헬프 센터에 도착하거나 예전 규칙이 남아 있습니다. 규칙이 어느 Mocco 주소를 가리키는지 확인하세요.
- `<url> is already served by another help center`: 다른 워크스페이스가 이 경로를 이미 활성화했습니다. 다른 경로를 고르세요.

![실패한 확인: 경로 아래에 이유가 표시됩니다](https://fi-workers-mocco-storage.s3.ap-northeast-2.amazonaws.com/pub/w/93e11fe8-0494-4e3d-b1cb-fe4dffd3ee7e/p/d64785b8-9a23-4fa1-a81d-550af30e203a/helpcenter/7dcb5063-0b5c-471d-bf82-83e173726daf/your-domain-failed.png)

프록시를 고친 뒤 **Check now**를 다시 선택하세요.

### Mocco는 계속 확인합니다

Mocco는 하루에 한 번 모든 활성 경로를 다시 확인합니다. 확인이 연달아 두 번 실패하면 경로가 **Broken**이 되고, 확인이 다시 통과할 때까지 페이지는 헬프 센터의 원래 주소로 돌아갑니다. 한 번 실패한 것만으로는 아무것도 바뀌지 않습니다. 고친 뒤에는 다음 정기 확인을 기다리지 않고 **Check now**를 쓰면 됩니다.

## 알아 둘 점

**프록시를 옮기기 전에 경로를 먼저 지우세요.** 경로가 활성인 상태에서 프록시가 헬프 센터의 원래 주소(`<address>.help.mocco.club`)를 가리키도록 바꾸면, 정기 확인이 두 번 실패할 때까지 방문자가 두 주소 사이를 계속 오갑니다. 그렇게 하지 마세요. 내 사이트에서 헬프 센터 제공을 멈추려면 콘솔에서 경로를 먼저 지우고(**Remove**) 그다음에 프록시를 바꾸세요. 경로를 지우면 1분 안쪽으로 페이지가 헬프 센터의 원래 주소로 돌아갑니다(Mocco는 경로를 30초마다 다시 읽고, 페이지는 최대 60초까지 보관될 수 있습니다).

**Mocco보다 오래 캐시하지 마세요.** 프록시나 CDN이 HTML을 캐시한다면 페이지의 `Cache-Control` 헤더가 정한 시간을 넘기지 말고, 가능하면 캐시하지 마세요. 게시한 내용은 프록시가 통과시키는 속도만큼만 내 사이트에 나타납니다.

**사이트맵을 내 사이트에 등록하세요.** Mocco는 내 사이트의 `robots.txt`나 루트 사이트맵을 바꿀 수 없습니다. 헬프 센터 전체라면 `https://example.com/docs/sitemap.xml`을 `robots.txt`(`Sitemap: https://example.com/docs/sitemap.xml`)나 사이트맵 인덱스에 올리세요. 이 사이트맵에는 헬프 센터가 제공하는 모든 언어의 공개 주소가 들어 있습니다. 활성 경로 아래에 콘솔이 같은 안내를 보여 줍니다.

**검색 엔진에는 내 주소만 보입니다.** 페이지는 자신의 주소로 내 공개 URL을 알리고, 프록시용 Mocco 주소(`www.mocco.club`의 `/_proxy/…`)는 `robots.txt`에서 검색 엔진에 막혀 있습니다.

## 경로 아래의 피드백 보드

보드 경로도 같은 방식입니다. 사이트의 일부로 **Board: <name>**을 고르고 `https://example.com/help` 같은 공개 URL을 추가한 다음, 콘솔이 보여 주는 설정으로 프록시를 설정하세요. 공개 보드만 추가할 수 있고, 같은 웹사이트에서 한 경로가 다른 경로 안에 들어갈 수는 없습니다.

내 사이트에서 보드는 로그인하지 않아도 읽을 수 있습니다. 투표, 글 작성, 댓글은 사용자가 누구인지 알아야 하며, 헬프 센터의 원래 주소에서와 같은 방식으로 동작합니다. 내 서버가 로그인한 사용자를 위한 짧은 수명의 토큰을 서명하고, 앱이 `?token=…`을 붙인 링크로 보드를 엽니다([공개 보드](https://www.mocco.club/docs/ko/articles/zp45zj-public-board)에서 방법을 볼 수 있습니다). 보드는 그 토큰을 브라우저 탭 동안 보관하고 페이지를 새로 고치지 않고 주소에서 지웁니다. Mocco로 가는 요청은 토큰을 쿠키가 아니라 요청 헤더에 실으므로, 내 도메인과 Mocco 사이의 쿠키에 의존하지 않습니다.

## 에이전트나 스크립트에서

경로를 조회, 추가, 확인, 삭제하는 네 가지 동작은 콘솔 밖에서도 할 수 있습니다. [MCP](https://www.mocco.club/docs/ko/articles/frhj3w-connect)로 연결한 에이전트는 도구 `mocco_help_site_mounts_list`, `mocco_help_site_mount_add`, `mocco_help_site_mount_verify`, `mocco_help_site_mount_remove`를 씁니다. `help:write` 키로는 API를, 터미널에서는 CLI(`mocco help mount add`, `verify`, `list`, `remove`)를 쓸 수 있습니다.