도메인 분리 WebFinger

Hollo는 도메인 분리 WebFinger 설정을 지원합니다. 페디버스 핸들은 한 도메인 아래(예: @alice@example.com)에 있고, 실제 ActivityPub 서버는 다른 도메인(예: https://ap.example.com) 에서 동작하는 방식입니다. Mastodon이 “루트 도메인에서 WebFinger 호스팅하기”라는 문서로 설명하는 패턴, 그리고 GoToSocial이 host-meta 기반 호스트 스왑이라고 부르는 것과 같은 패턴입니다.

이 기능은 Fedify의 origin 옵션 위에 구현되어 있습니다.

왜 도메인을 분리할까요?

전형적인 동기는 이미 짧고 좋은 도메인(example.com)을 가지고 있고 핸들을 @alice@example.com처럼 보여주고 싶지만, 그 도메인의 루트 자체에는 Hollo를 두기 어려운 경우입니다. 루트 도메인은 홈페이지, 다른 웹 앱, 또는 기존 서비스가 차지하고 있기 마련이지요.

도메인 분리 설정에서는:

사용자는 페디버스 어디서든 @alice@example.com이라는 형태로 여러분을 부릅니다.
Hollo 자체는 https://ap.example.com에서 동작합니다. 웹 UI, Mastodon 호환 API, OAuth, 액터 URI가 모두 이 도메인에 있습니다.
루트 도메인 example.com은 단 한 가지 일만 하면 됩니다: /.well-known/webfinger 요청을 ap.example.com으로 리다이렉트하는 것.

설정 방법

다음 두 환경 변수를 Hollo 인스턴스에 설정하세요:

HANDLE_HOST — 핸들에 사용할 호스트명만(스킴 없음, 경로 없음). 예: example.com.
WEB_ORIGIN — Hollo가 실제로 동작하는 스킴+호스트. 예: https://ap.example.com.

두 변수는 반드시 함께 설정해야 합니다. 한 쪽만 설정하면 Hollo가 시작에 실패합니다.

HANDLE_HOST=example.com
WEB_ORIGIN=https://ap.example.com

이렇게 설정하면 나머지는 Fedify가 알아서 처리합니다:

WebFinger 응답의 subject는 acct:alice@example.com.
액터 URI는 https://ap.example.com/@alice 형식으로 만들어집니다.
Mastodon 호환 /api/v1/instance, /api/v2/instance 엔드포인트는 인스턴스 도메인을 example.com으로 알려주므로, 클라이언트가 정확한 핸들을 표시합니다.

리버스 프록시 리다이렉트

Hollo는 WEB_ORIGIN 호스트에서만 응답합니다. 원격 서버가 @alice@example.com을 조회할 때는 https://example.com/.well-known/webfinger로 WebFinger 요청을 보내므로, 해당 도메인의 리버스 프록시가 그 요청을 Hollo로 리다이렉트하도록 설정해야 합니다.

쿼리스트링을 보존하는 301 리다이렉트면 충분합니다. 일부 구현체가 디스커버리 중에 /.well-known/nodeinfo와 /.well-known/host-meta도 조회하므로 함께 리다이렉트해 두는 것이 좋습니다.

nginx
Caddy

server {
  listen 443 ssl;
  server_name example.com;
  # … 일반적인 사이트 설정 …

  location /.well-known/webfinger {
    return 301 https://ap.example.com$request_uri;
  }
  location /.well-known/nodeinfo {
    return 301 https://ap.example.com$request_uri;
  }
  location /.well-known/host-meta {
    return 301 https://ap.example.com$request_uri;
  }
}

example.com {
  # … 일반적인 사이트 설정 …

  redir /.well-known/webfinger* https://ap.example.com{uri} permanent
  redir /.well-known/nodeinfo*  https://ap.example.com{uri} permanent
  redir /.well-known/host-meta* https://ap.example.com{uri} permanent
}

/@username 경로나 액터 URL은 리다이렉트하지 않아도 됩니다. 이 URL들은 ap.example.com에 있고, 원격 서버는 WebFinger 응답을 해석한 뒤 곧장 그쪽으로 갑니다.

설정 검증

배포 후 다음 세 가지를 확인하면 모든 것이 제대로 연결됐는지 알 수 있습니다:

핸들 도메인의 WebFinger가 리다이렉트되는지:
```
curl -i "https://example.com/.well-known/webfinger?resource=acct:alice@example.com"
```
https://ap.example.com/.well-known/webfinger?...로 가는 301 응답이 반환되어야 합니다.
서버 도메인의 WebFinger가 응답하는지:
```
curl "https://ap.example.com/.well-known/webfinger?resource=acct:alice@example.com"
```
subject가 acct:alice@example.com이고 self 링크가 https://ap.example.com/@alice를 가리키는 JRD 응답이 반환되어야 합니다.
인스턴스 엔드포인트가 핸들 도메인을 알려주는지:
```
curl https://ap.example.com/api/v2/instance | jq .domain
```
"example.com"이 출력되어야 합니다.

더 꼼꼼히 확인하고 싶다면 Julian Fietkau가 만든 WebFinger Canary를 핸들 도메인에 돌려보세요. 현재 Mastodon과 Fedify 기반 서버는 도메인 분리 설정을 잘 처리하지만, Misskey와 Pixelfed는 아직 그렇지 않습니다.