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

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

이 방식은 헬프 센터 전체에 별도의 호스트 이름을 주는 자체 도메인 사용하기와 다릅니다. 웹사이트가 이미 있고 도움말을 그 옆에 두고 싶을 때 경로를 사용하세요. 웹사이트가 이미 DNS 레코드와 인증서를 갖고 있으므로 따로 준비할 것은 없습니다.

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

• 헬프 센터 전체: /docs 같은 경로 하나 아래의 모든 페이지.

• 피드백 보드 하나: /help 같은 경로 아래의 공개 보드 하나.

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

1. 경로 추가하기

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

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

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

2. 경로를 Mocco로 전달하기

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

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

Next.js

// 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

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

Cloudflare

// 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

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가 됩니다.

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

확인이 실패할 때

실패한 경로에는 이유와 함께 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: 다른 워크스페이스가 이 경로를 이미 활성화했습니다. 다른 경로를 고르세요.

프록시를 고친 뒤 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=…을 붙인 링크로 보드를 엽니다(공개 보드에서 방법을 볼 수 있습니다). 보드는 그 토큰을 브라우저 탭 동안 보관하고 페이지를 새로 고치지 않고 주소에서 지웁니다. Mocco로 가는 요청은 토큰을 쿠키가 아니라 요청 헤더에 실으므로, 내 도메인과 Mocco 사이의 쿠키에 의존하지 않습니다.

에이전트나 스크립트에서

경로를 조회, 추가, 확인, 삭제하는 네 가지 동작은 콘솔 밖에서도 할 수 있습니다. MCP로 연결한 에이전트는 도구 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)를 쓸 수 있습니다.