편집 기능을 유지하면서 ONLYOFFICE 문서를 HAProxy 뒤에 배치하는 방법

HAProxy 뒤에서 ONLYOFFICE Docs를 실행하려면 프록시에서 HTTPS 연결을 종료하고 원래 호스트와 스키마를 전달하며 장시간 WebSocket 연결을 허용해야 합니다. 처음에는 정상적인 문서 서버 하나로 시작하고, HAProxy가 요청을 분산할 수 있다는 이유만으로 추가 백엔드를 추가하기보다는 ONLYOFFICE 배포 환경이 지원되는 다중 노드 운영을 지원하도록 구성된 경우에만 백엔드를 추가하십시오.

HAProxy는 두 개의 독립적인 문서 서버에 대해 로드 밸런싱을 수행할 수 있습니까?

HAProxy는 HTTP 요청을 노드 간에 분산할 수 있지만, 그렇다고 해서 두 개의 독립적인 ONLYOFFICE 설치 환경이 통합된 편집 클러스터가 되는 것은 아닙니다. 편집기 세션은 영구적인 연결과 애플리케이션 상태를 유지합니다. 공식 ONLYOFFICE 액티브-액티브 샘플은 백엔드 상태 확인과 영구 쿠키를 사용합니다. 이는 라우팅 메커니즘일 뿐이며, 사용자의 에디션에 필요한 공유 서비스 및 애플리케이션 수준 아키텍처를 대체하는 것은 아닙니다.

일반적인 단일 서버 설치의 경우 docs1아래 백엔드에서만 사용하십시오. 두 개의 노드를 사용하는 경우 먼저 ONLYOFFICE 배포 문서 또는 공급업체 지원을 통해 클러스터 아키텍처, 지원되는 에디션, 공유 종속성, 버전 호환성 및 JWT 구성을 확인하십시오. 예시 주소( 및 )는 예시를 위한 개인 IP 주소이며, 검색된 호스트가 아닙니다 10.0.10.21.10.0.10.22

HAProxy를 편집하기 전에 무엇이 정상적으로 작동해야 합니까?

공개 이름은 docs.example.comHAProxy 엔드포인트로 확인되어야 합니다. HAProxy는 수신 TCP 포트 80과 443이 필요하며, 각 문서 서버에 대한 사설 네트워크 액세스(포트 80)도 필요합니다. 문서 관리 애플리케이션 또한 공개 Docs 주소에 접근할 수 있어야 하며, ONLYOFFICE는 문서를 가져와 애플리케이션으로 콜백을 보낼 수 있어야 합니다. 백엔드 HTTP는 비공개로 유지하고, 신뢰할 수 없는 네트워크를 거치는 경우 백엔드 홉을 별도로 암호화하십시오.

1. 프록시 호스트에서 각 문서 서버를 확인하십시오.curl -i http://10.0.10.21/healthcheck 및 (있는 경우) 명령을 실행하십시오 curl -i http://10.0.10.22/healthcheck. 정상 작동 상태 엔드포인트는 일반적으로 본문에 HTTP 200 응답을 반환합니다 true. 라우팅, 방화벽 또는 서버 상태가 실패하는 경우 로드 밸런싱을 구성하기 전에 해당 문제를 조사하십시오.
2. 고정된 JWT 비밀 키를 확인하십시오. 문서 서버와 커넥터는 토큰 비밀 키에 대해 일치해야 합니다. Docker 설치의 경우 ONLYOFFICE는 JWT_SECRET환경 변수에 대한 문서를 제공합니다. Docs 7.2 버전부터는 자동으로 생성된 비밀 키를 사용할 경우 재구성 또는 재시작 후 통합 오류가 발생할 수 있습니다. 지원되는 다중 노드 배포 환경에서는 공급업체의 아키텍처에 따라 노드 간 비밀 키를 일관되게 설정하십시오.

이러한 검사는 공급업체의 Docker 설치 지침 및 JWT 구성 지침을 따릅니다 . 프록시 오류를 해결하기 위해 JWT를 비활성화하지 마십시오.

HTTPS를 구성하고 올바른 헤더를 전달하는 방법은 무엇입니까?

1단계: 증명서를 준비하세요

신뢰할 수 있는 인증서를 발급받으세요 docs.example.com. 이 Linux 예제에서는 HAProxy가 인증서 체인과 개인 키가 포함된 PEM 파일을 읽습니다. 인증서가 이미 다른 위치에 있는 경우 해당 경로를 입력하세요. 결합된 PEM 파일에 대한 접근을 제한하고 인증서 갱신 시 다시 생성되도록 설정하세요.

sudo install -d -m 700 /etc/haproxy/certs
sudo sh -c 'umask 077; cat /etc/letsencrypt/live/docs.example.com/fullchain.pem /etc/letsencrypt/live/docs.example.com/privkey.pem > /etc/haproxy/certs/docs.example.com.pem'

2단계: 프런트엔드와 백엔드를 추가합니다.

기존 설정을 백업하고 /etc/haproxy/haproxy.cfg다음 섹션을 참조하여 수정하십시오. 배포판별 로깅 또는 서비스 설정을 그대로 교체하지 마십시오. 다음은 최신 HAProxy 릴리스를 위한 예시 구성입니다. 이 구성은 리디렉션에 HTTP만 허용하고, 443번 포트에서 HTTPS 연결을 종료하며, 공용 호스트 및 스키마를 포워딩하고, 애플리케이션 상태 엔드포인트를 모니터링합니다.

global
    log /dev/log local0

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

frontend docs_http
    bind :80
    http-request redirect scheme https code 301

frontend docs_https
    bind :443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    default_backend docs_nodes

backend docs_nodes
    option http-server-close
    balance roundrobin
    cookie SERVERID insert indirect nocache
    option httpchk GET /healthcheck
    http-check expect string true
    server docs1 10.0.10.21:80 check cookie docs1
    server docs2 10.0.10.22:80 check cookie docs2

두 번째 노드가 완전히 준비되지 않은 경우 해당 줄을 제거하십시오 docs2. 지속성 쿠키는 후속 HTTP 요청이 선택된 노드로 돌아가는 데 도움이 됩니다. HAProxy는 특별한 URL 재작성 없이 HTTP WebSocket 업그레이드를 처리하며, timeout tunnel 1h업그레이드된 유휴 연결이 일반 요청보다 더 오래 열려 있도록 허용합니다. HAProxy WebSocket 설명서에서 이 동작에 대해 자세히 설명합니다.

X-Forwarded-Proto이 프런트엔드가 공용 HTTPS를 종료하므로 이 설정 이 https올바릅니다. 인터넷에 연결된 에지에서 클라이언트가 임의로 제공한 포워딩 스키마나 호스트를 신뢰하지 마십시오. ONLYOFFICE 프록시 설명서에서는X-Forwarded-Proto 외부 URL 컨텍스트를 유지 하도록 명시적으로 요구하고 있습니다 X-Forwarded-Host.

로드 밸런서를 어떻게 재로드하고 테스트해야 합니까?

3단계: 트래픽 전환 전 유효성 검사

다시 로드하기 전에 구문을 확인하십시오. 0이 아닌 종료 상태 코드는 진행하기 전에 보고된 구성 또는 인증서 오류를 해결해야 함을 의미합니다.

sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxy
curl -i https://docs.example.com/healthcheck

공개 상태 점검 응답은 true백엔드가 정상일 경우 HTTP 200을 표시해야 합니다. HAProxy는 `--check` 및 `--request` 지시문을 사용하여 option httpchk실패한 http-check expect노드를 새 요청 순환에서 제거합니다. 자세한 내용은 상태 점검 참조를 확인하세요 . 상태 점검을 통과했다고 해서 문서 편집이나 콜백 전달이 정상적으로 작동한다는 것을 보장하는 것은 아닙니다.

4단계: 편집, 웹소켓 설정 및 저장을 확인합니다.

ONLYOFFICE Docs에 연결된 문서 관리 시스템과 같은 통합 애플리케이션을 통해 문서를 엽니다. 브라우저 개발자 도구의 네트워크 패널에서 WebSocket 연결을 검사합니다. 업그레이드 핸드셰이크는 일반적으로 HTTP 상태 코드 0으로 성공적으로 완료되어야 합니다 101 Switching Protocols. 간단한 편집을 수행한 후 편집기를 닫고 문서를 다시 열어 변경 사항이 저장되었는지 확인합니다. 제대로 지원되는 2노드 배포 환경에서는 두 번째 공동 작업자를 추가하고 유지 관리 기간 동안 계획된 단일 노드 드레인 테스트도 수행하십시오.

공용 상태 점검은 성공했지만 편집기가 로딩 중이거나 연결이 끊어지는 경우, 혼합 콘텐츠 경고, WebSocket 오류, JWT 불일치 및 문서 애플리케이션이 광고된 Docs URL에 연결할 수 있는지 여부를 확인하십시오. 문서가 열리지만 저장되지 않는 경우, HAProxy의 라운드 로빈 정책을 변경하기보다는 문서 서버에서 소스 애플리케이션으로의 콜백 연결 가능성을 조사하십시오. 활성 WebSocket 세션이 중단된 경우 클라이언트 재연결이 필요할 수 있으며, 백엔드 상태 점검은 원활한 편집 장애 조치를 보장하지 않습니다.

최종 검증: 공용 상태 엔드포인트와 실제 편집 및 재개 테스트 모두 통과해야 합니다. 검증되고 지원되는 노드만 순환 관리하고, 인증서 갱신 시 올바른 PEM 파일이 다시 로드되는지 확인하며, HAProxy 로그를 모니터링하여 502/503 응답이 반복적으로 발생하거나 예기치 않은 WebSocket 연결이 끊어지는지 확인하십시오.