HAProxy 로드 밸런서 뒤에서 ONLYOFFICE Document Server를 실행하는 방법

가장 중요한 규칙은 다음과 같습니다. ONLYOFFICE Document Server를 HAProxy 뒤에 배치하는 것은 단일 백엔드의 경우 간단하지만, 다중 노드 편집기 클러스터의 경우 단순한 라운드 로빈 방식 이상의 조치가 필요합니다. ONLYOFFICE의 최신 API 문서에 따르면 공동 편집 중에 동일한 문서에 대한 요청은 동일한 Document Server 노드에 도달해야 합니다. 최신 통합 환경에서는 shardkey로드 밸런서가 문서 인식 선호도를 위해 사용할 수 있는 쿼리 매개변수를 활용하는 것이 권장됩니다.

문서 서버가 하나만 있고 HTTPS 종료, 안정적인 공용 호스트 이름 또는 중앙 집중식 상태 확인을 위해 HAProxy를 사용하려는 경우 구성이 간단합니다. 문서 서버 노드가 두 개 이상인 경우 동일한 프록시 기본 설정을 사용하되 shardkey일반적인 라운드 로빈 방식만으로는 충분하지 않다고 가정하고 노드 수에 따른 라우팅을 추가하십시오.

아래 예제는 현재 ONLYOFFICE 프록시 문서 , ONLYOFFICE 샤드 키 문서 및 현재 HAProxy WebSocket 지침을 기준으로 검증되었습니다 .

이러한 설정이 적합할 때

HAProxy는 하나의 공용 URL(예: `/etc/document_server.com`)을 사용하고 https://docs.example.com, 로드 밸런서에서 TLS 연결을 종료하고, 능동적인 상태 점검을 수행하거나, 하나의 엔드포인트 뒤에 여러 Document Server 노드를 연결하려는 경우에 적합한 프런트엔드입니다. 또한 Nextcloud, ownCloud, 사용자 지정 DMS 또는 애플리케이션이 개별 Document Server 노드에 직접 연결해서는 안 되는 경우에도 유용합니다.

이 가이드는 다음 사항을 전제로 합니다.

• HAProxy는 내부 네트워크를 통해 각 문서 서버에 접근할 수 있습니다.
• 로드 밸런서가 도입되기 전에도 각 문서 서버는 이미 직접 작동하고 있습니다.
• 공용 호스트 이름은 HAProxy로 확인됩니다.
• TLS 인증서는 공개 호스트 이름을 포함합니다.
• 여러 노드를 실행하는 경우, 단순히 로드 밸런서를 공유하는 서로 관련 없는 독립형 서버가 아니라, 지원되는 멀티 서버 ONLYOFFICE 아키텍처로 배포됩니다.

1단계: HAProxy를 추가하기 전에 모든 문서 서버를 확인하십시오.

로드 밸런싱부터 시작하지 마십시오. 먼저 HAProxy 호스트에서 모든 백엔드가 정상인지 확인하십시오. ONLYOFFICE 문서를 /healthcheck편집기 가용성 확인 엔드포인트로 사용합니다. 정상적인 서버는 를 반환합니다 true. 이 검사는 데이터베이스, 메시지 브로커, Redis 연결 및 스토리지와 같은 핵심 종속성을 확인합니다.

curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheck

예상 결과:

true
true

백엔드 중 하나라도 오류가 발생하면 해당 노드부터 먼저 문제를 해결하십시오. 일반적인 원인으로는 방화벽 규칙, 잘못된 내부 포트, 문서 서버 서비스 실행 안 됨 또는 지원 서비스 사용 불가 등이 있습니다.

2단계: 편집기 연결을 허용하는 HTTP 모드 및 시간 제한을 설정합니다.

ONLYOFFICE는 HTTP 애플리케이션이며 편집 중에 장시간 유지되는 WebSocket 연결을 사용합니다. HAProxy는 HTTP 업그레이드 후 WebSocket 연결을 자동으로 프록시할 수 있지만, 타임아웃 정책은 여전히 ​​중요합니다. HAProxy 자체 문서에서는 timeout tunnel업그레이드된 WebSocket 연결에 대한 권장 값을 제시하고 있습니다.

실질적인 기준은 다음과 같습니다.

global
    log /dev/log local0
    log /dev/log local1 notice
    daemon
    maxconn 4096

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5s
    timeout client 60s
    timeout server 60s
    timeout tunnel 1h

1시간 터널 타임아웃은 예시일 뿐이며, 보편적인 요구 사항은 아닙니다. 조직의 편집 작업 패턴, 보안 정책 및 리소스 제한에 맞는 값을 선택하십시오. 편집자가 매우 규칙적인 간격으로 연결을 끊는 경우, 해당 간격을 HAProxy 및 상위 방화벽 또는 역방향 프록시의 유휴 타임아웃과 비교해 보십시오.

3단계: HTTPS 연결을 종료하고 원래 요청 컨텍스트를 유지합니다.

ONLYOFFICE는 프록시 뒤에서 실행될 때 전달된 헤더를 명시적으로 요구합니다. 특히, X-Forwarded-Proto원래 클라이언트가 HTTP를 사용했는지 HTTPS를 사용했는지 여부를 문서 서버에 알려주고, X-Forwarded-Host클라이언트가 요청한 호스트 이름을 유지합니다.

깔끔한 HAProxy 프런트엔드는 다음과 같습니다.

frontend onlyoffice_http
    bind *:80
    mode http
    http-request redirect scheme https code 301

frontend onlyoffice_https
    bind *:443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    mode http
    option httplog

    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]

    default_backend onlyoffice_docs

Upgrade최신 HAProxy HTTP 모드에서는 일반적으로 NGINX 스타일 의 헤더 규칙을 수동으로 다시 생성할 필요가 없습니다 Connection. HAProxy는 HTTP에서 WebSocket으로의 업그레이드를 인식하고 연결을 터널 모드로 전환합니다. 중요한 것은 업그레이드 요청을 제거하거나 방해하는 규칙을 삽입하지 않는 것입니다.

클라이언트 IP 주소를 확인하려면 option forwardfor백엔드에 해당 기능을 추가하세요. 그러면 X-Forwarded-For클라이언트 소스 주소에서 헤더가 생성됩니다.

4단계: 상태 점검을 추가하고 적절한 균형 조정 규칙을 선택합니다.

단일 문서 서버

HAProxy가 문서 서버 하나를 앞에 두고 사용하는 경우 백엔드는 간단하게 구성할 수 있습니다.

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    server ds1 10.0.10.21:80 check

이 설계에서 HAProxy는 주로 리버스 프록시, TLS 엔드포인트 및 상태 게이트 역할을 합니다.

여러 개의 문서 서버 노드

실제 멀티 노드 배포 환경에서는 공동 편집에 일반적인 라운드 로빈 방식에 의존하지 마십시오. ONLYOFFICE의 최신 문서에 따르면 동일한 문서에 대한 모든 요청은 동일한 서버에 도달해야 합니다. 브라우저에서 서버로 전송되는 편집기 요청에는 자동으로 샤드 키가 포함되며, 애플리케이션은 ?shardkey=<document-key>명령, 변환 및 문서 빌더 요청에도 관련 문서에 명시된 대로 샤드 키를 추가해야 합니다.

HAProxy는 URL 쿼리 매개변수에 대한 해싱을 지원하므로 표준 ONLYOFFICE Docs API에 적합한 백엔드는 다음과 같습니다.

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    balance url_param shardkey

    server ds1 10.0.10.21:80 check
    server ds2 10.0.10.22:80 check

HAProxy의 url_param알고리즘은 선택된 쿼리 문자열 매개변수를 해싱합니다. 해당 매개변수가 없으면 HAProxy는 일반적인 로드 밸런싱 동작으로 돌아갑니다. 따라서 ONLYOFFICE에서 권장하는 경우 통합 시 요청에 샤드 키를 전송하는 것이 특히 중요합니다.

WOPI는 다릅니다. ONLYOFFICE에 따르면 WOPI 통합은 WOPISrc동일한 라우팅 목적으로 쿼리 매개변수를 사용합니다. 따라서 해당 balance url_param shardkey라인을 변경 없이 WOPI 설계에 복사하여 필요한 어피니티를 제공한다고 가정해서는 안 됩니다.

HAProxy를 안전하게 검증하고 다시 로드하세요

서비스를 다시 로드하기 전에 구성을 검증하십시오.

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

구문 유효성 검사가 성공한 후에만 새로 고침하세요.

sudo systemctl reload haproxy
sudo systemctl status haproxy

사용하는 배포판에서 다른 서비스 관리자 또는 구성 경로를 사용하는 경우 해당 명령을 적절히 수정하십시오. HAProxy 패키지가 정상적인 구성 재로드를 지원하는 경우 불필요한 강제 재시작보다는 재로드가 더 바람직합니다.

백엔드 네트워크 내부뿐만 아니라 공개 URL을 통해서도 테스트하십시오.

이제 사용자와 문서 관리 플랫폼이 실제로 어떤 결과를 가져올지 테스트해 보세요.

curl -sS https://docs.example.com/healthcheck

예상되는 신체 부위는 다음과 같습니다:

true

다음으로 TLS 인증서를 확인하십시오.

openssl s_client -connect docs.example.com:443   -servername docs.example.com </dev/null 2>/dev/null   | openssl x509 -noout -subject -issuer -dates

마지막으로 통합 애플리케이션을 통해 실제 문서를 열어보세요. 상태 점검은 문서 서버 엔드포인트가 준비되었는지 여부만 확인할 뿐, 콜백 URL, JWT 구성, 문서 다운로드, 저장 콜백 또는 다중 노드 선호도 설정이 모두 올바른지 여부는 보장하지 않습니다.

에디터가 로드되지만 연결이 끊기거나 저장에 실패할 경우 확인해야 할 사항은 무엇인가요?

끈적끈적한 세션이 필요하신가요?

ONLYOFFICE에서는 기존의 소스 IP 고정 방식이 최적의 기본 설정이 아닙니다. 동일한 파일을 편집하는 여러 사용자가 각기 다른 클라이언트 IP 주소를 가질 수 있고, 한 사용자가 서로 다른 노드에 있을 필요가 없는 여러 문서를 열 수도 있기 때문입니다. ONLYOFFICE의 샤드 키를 기반으로 하는 문서 인식 선호 방식은 라우팅 키가 사용자의 네트워크 주소가 아닌 편집 중인 문서를 나타내므로 더욱 정확합니다.

이러한 차이점은 간단한 쿠키 기반 스티키 세션이 ONLYOFFICE에서 문서화한 라우팅 동작을 대체할 수 없는 이유를 설명합니다. 다중 노드 Docs API 배포를 구축할 때는 애플리케이션에서 문서화된 샤드 키를 사용하십시오.

최종 구성 체크리스트

• 모든 문서 서버는 HAProxy에 추가되기 전의 true상태 를 반환합니다./healthcheck
• HAProxy는 ONLYOFFICE 프런트엔드 및 백엔드에 대해 HTTP 모드로 실행됩니다.
• HTTPS는 공개 문서 서버 호스트 이름에 유효한 인증서로 종료됩니다.
• X-Forwarded-Proto그리고 X-Forwarded-Host올바르게 전달됩니다.
• WebSocket 터널 타임아웃은 실제 편집 세션을 진행하기에 충분히 깁니다.
• 백엔드 상태 점검을 통해 실패한 노드를 서비스에서 제거합니다.
• 멀티 노드 Docs API 트래픽은 shardkey일반적인 라운드 로빈 방식이 아닌 노드 기반 선호도를 사용합니다.
• WOPI 배포는 에 적합한 라우팅을 사용합니다 WOPISrc.
• 공중 보건 검사 기능은 정상적으로 작동하며, 통합 기능을 통해 실제 문서를 열고 편집하고 저장할 수 있습니다.

문서 서버가 하나인 경우, HAProxy는 주로 깔끔한 리버스 프록시 및 TLS 계층 역할을 합니다. 하지만 문서 서버 노드가 여러 개인 경우에는 문서 인식 라우팅이 결정적인 차이점입니다. 따라서 먼저 이러한 요구 사항을 중심으로 프록시를 구축한 다음, 상태 확인, HTTPS 및 타임아웃 설정을 추가해야 합니다.