ONLYOFFICE Docker에서 HTTPS 및 SSL 인증서를 구성하는 방법

Docker 환경에서 ONLYOFFICE Docs를 HTTPS로 접속할 수 있도록 하려면, 공개 호스트 이름과 일치하는 인증서를 사용하고, 해당 인증서를 컨테이너 내부에서 사용할 수 있도록 설정한 다음, 컨테이너의 HTTPS 포트를 공개해야 합니다. HTTPS는 암호화된 웹 연결이며, TLS 인증서는 브라우저가 예상 서버에 제대로 연결되었는지 확인하는 데 도움이 됩니다. 이 가이드에서는 신뢰할 수 있는 인증 기관(CA)에서 발급받은 인증서와 개인 키를 사용합니다. 리버스 프록시를 사용하는 경우, 프록시에서 HTTPS를 처리할 수 있으므로 아래의 별도 옵션을 따르세요.

어떤 HTTPS 설정이 배포 환경에 적합합니까?

ONLYOFFICE Docs는 Docker 컨테이너에서 직접 HTTPS를 제공하거나, NGINX 또는 Traefik과 같은 리버스 프록시를 통해 HTTPS 요청을 수락하고 Docs로 전달할 수 있습니다. 공용 포트 80과 443을 사용할 수 있는 독립형 서버의 경우 직접 TLS를 사용하는 것이 간단한 선택입니다. 다른 웹 서비스에서 이미 해당 포트를 사용하고 있거나 여러 사이트가 하나의 서버를 공유하는 경우에는 리버스 프록시를 사용하는 것이 더 간단할 수 있습니다. 두 계층을 모두 맹목적으로 구성하지 않도록 주의하고, 어떤 구성 요소가 TLS 연결을 종료할지 결정하고, 프록시와 컨테이너 간의 연결이 HTTP인지 HTTPS인지 문서화해야 합니다.

이 가이드에서는 CA에서 발급한 인증서를 사용하여 직접 HTTPS를 구성하는 방법을 설명합니다. ONLYOFFICE는 또한 Let's Encrypt를 자동으로 사용하는 옵션에 대해서도 설명합니다. 이 옵션을 사용하려면 LETS_ENCRYPT_DOMAIN포트 LETS_ENCRYPT_MAIL80과 443에 접근이 가능하고 프록시에서 이미 사용 중이 아니어야 합니다. 자체 서명 인증서는 개인 테스트 네트워크에 유용하지만, 공용 브라우저와 연결된 스토리지 서비스는 이를 자동으로 신뢰하지 않습니다.

무엇을 먼저 준비해야 할까요?

• Docker Engine과 Docker Compose 플러그인이 설치된 Linux 호스트.
• 호스트 이름에 대한 DNS A 레코드(예: )는 docs.example.com호스트의 공용 IPv4 주소를 가리킵니다. IPv6가 구성되어 있고 연결 가능한 경우에만 AAAA 레코드를 추가하십시오.
• TCP 443 포트를 허용하는 인바운드 방화벽 및 클라우드 방화벽 규칙이 필요합니다. HTTP 유효성 검사를 통해 인증서를 요청하거나 갱신하는 경우 TCP 80 포트도 필요할 수 있습니다.
• 정확한 호스트 이름과 해당 개인 키에 대한 인증서 체인입니다. 인증 기관은 일반적으로 전체 체인 파일과 개인 키 파일을 제공합니다.
• ONLYOFFICE 데이터 볼륨용 영구 호스트 디렉터리와 강력한 JWT 비밀 키가 필요합니다. JWT(JSON Web Token)는 Docs와 통합 애플리케이션 간의 요청을 인증하는 데 사용되는 공유 비밀 키입니다.

1단계: 호스트에 인증서와 개인 키를 배치합니다.

이 예시에서는 호스트가 영구 데이터를 에 저장합니다 /srv/onlyoffice/data. 샘플 호스트 이름과 경로를 실제 호스트 이름과 경로로 바꾸세요. 인증서의 전체 체인은 에 tls.crt, 해당 개인 키는 하위 디렉터리 tls.key에 에 저장합니다 certs.

sudo mkdir -p /srv/onlyoffice/data/certs
sudo install -m 0644 /path/to/fullchain.pem /srv/onlyoffice/data/certs/tls.crt
sudo install -m 0600 /path/to/privkey.pem /srv/onlyoffice/data/certs/tls.key
sudo chown root:root /srv/onlyoffice/data/certs/tls.key

개인 키는 해당 키가 필요한 계정 또는 서비스만 읽을 수 있도록 관리해야 합니다. Compose 파일, 문제 보고서 또는 공개 저장소에 개인 키를 붙여넣지 마십시오. 소유권이나 권한 문제로 Docker가 키를 읽을 수 없는 경우, 키를 모든 사용자가 읽을 수 있도록 허용하는 대신 컨테이너 런타임에 대한 액세스 권한을 제한적으로 조정하십시오.

서비스를 시작하기 전에 인증서의 날짜와 호스트 이름을 확인하십시오.

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -noout -subject -issuer -dates -ext subjectAltName

SAN(Subject Alternative Name) 목록에는 사용자가 방문할 정확한 호스트 이름이 포함되어야 합니다. 인증서와 개인 키에서 파생된 공개 키를 비교하여 두 해시 값이 일치하는지 확인할 수 있습니다.

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -pubkey -noout | openssl sha256
openssl pkey -in /srv/onlyoffice/data/certs/tls.key -pubout | openssl sha256

2단계: Docker Compose 서비스 구성

ONLYOFFICE의 Docker 문서에서는 인증서를 `/certificate` 디렉터리에 저장합니다 /var/www/onlyoffice/Data/certs. 현재 환경 변수 목록에서는 기본 인증서 파일 이름을 `/certificate`와 `/certificate`로 지정하고 있으며 tls.crt, tls.key설치 예제에서도 `/certificate`와 `/certificate`를 사용합니다 onlyoffice.crt. onlyoffice.key경로를 명시적으로 설정하면 파일 이름 규칙에 의존하지 않아도 됩니다. 호스트 디렉터리는 해당 컨테이너 데이터 디렉터리에 바인드 마운트되고, 포트 443은 호스트 포트 443으로 공개됩니다.

다음과 같은 파일을 생성하고 compose.yaml, 샘플 JWT 값을 설치 환경에 맞게 생성된 비밀 키로 바꾸십시오. 아래 이미지 태그는 예시 버전이며, 공식 이미지 목록을 확인하고 유지 관리할 버전을 사용하십시오.

services:
  documentserver:
    image: onlyoffice/documentserver:9.4.0
    container_name: onlyoffice-documentserver
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - /srv/onlyoffice/data:/var/www/onlyoffice/Data
    environment:
      SSL_CERTIFICATE_PATH: /var/www/onlyoffice/Data/certs/tls.crt
      SSL_KEY_PATH: /var/www/onlyoffice/Data/certs/tls.key
      JWT_SECRET: replace_with_a_long_random_secret

강력한 비밀 키를 생성하여 openssl rand -hex 32적절한 파일 권한으로 환경 변수 파일이나 Compose 구성 파일에 저장하십시오. 다른 앱이 Docs와 통합되는 경우, 해당 앱에도 동일한 JWT 비밀 키와 공개 HTTPS 주소를 구성하십시오. 기존 설치 환경인 경우, 기존 Compose 파일을 편집할 때 볼륨, 네트워크, 기타 환경 변수 및 통합 설정을 유지하십시오. 정상적으로 작동하는 서비스 정의를 이 최소 예제로 대체하지 마십시오.

Compose 파일이 있는 디렉터리에서 서비스를 시작하거나 다시 생성하십시오.

docker compose up -d
docker compose ps
docker compose logs --tail=100 documentserver

3단계: HTTPS 및 인증서 테스트

호스트 이름을 바꿔 브라우저에서 엽니다 https://docs.example.com. 브라우저에 안전한 연결이 표시되고 이름 불일치, 만료된 인증서 또는 신뢰할 수 없는 발급자 오류가 발생하지 않는지 확인합니다. ONLYOFFICE Docs 시작 페이지가 제대로 로드되는지 확인합니다. Docs가 Nextcloud, ownCloud 또는 다른 플랫폼에 연결된 경우 문서 열기 및 저장 기능도 테스트합니다. 브라우저 잠금 표시만으로는 통합 콜백 요청이나 JWT 구성이 제대로 작동하는지 확인할 수 없습니다.

셸에서 서버에 TLS 인증서를 요청하고 HTTPS 응답을 테스트합니다.

openssl s_client -connect docs.example.com:443 -servername docs.example.com </dev/null
curl -I https://docs.example.com/

이 -servername옵션은 SNI(Server Name Indication)를 사용하여 호스트 이름을 전송합니다. 이를 통해 여러 호스트 이름이 동일한 주소를 공유하는 경우 서버가 올바른 인증서를 선택할 수 있습니다. 인증서 날짜, 발급자 및 SAN(인증서 주소 체계)은 설치한 인증서와 일치해야 합니다. docker compose logs브라우저 연결 불가 또는 컨테이너 반복 재시작 문제가 발생하는 경우 이 부분을 검토하십시오.

리버스 프록시가 이미 HTTPS를 처리하고 있다면 어떻게 될까요?

NGINX, Traefik, Caddy 또는 호스팅 게이트웨이가 이미 공용 포트 80과 443을 사용하고 있다면 해당 프록시에 공용 인증서를 설치하는 것이 좋습니다. 이 경우 Docs 컨테이너를 프라이빗 Docker 네트워크에만 게시하거나 HTTP 포트를 루프백에 바인딩한 다음, 필요한 요청과 WebSocket 트래픽을 전달하도록 프록시를 구성하십시오. 통합 애플리케이션의 ONLYOFFICE 주소를 공용 https://URL로 설정합니다. 전달 헤더 및 업스트림 TLS에 대해서는 프록시와 ONLYOFFICE의 최신 지침을 따르십시오. 프록시가 이미 사용 중인 호스트 포트와 동일한 포트에 컨테이너의 443 포트를 게시하지 마십시오.

여러 서비스에 대한 트래픽을 하나의 프록시로 라우팅할 때 이 패턴을 선택하십시오. Docs가 공용 HTTPS 엔드포인트를 소유하고 필요한 포트가 사용 가능한 경우 위의 직접 컨테이너 설정을 사용하십시오. 프록시가 HTTP를 통해 컨테이너에 연결하는 경우 해당 내부 홉은 암호화되지 않으므로 신뢰할 수 있는 사설 네트워크에 유지하거나 보안 요구 사항에 따라 업스트림 TLS를 구성하십시오.

흔히 발생하는 문제와 해결 방법

• 브라우저에서 인증서가 유효하지 않다고 표시됩니다. SAN 호스트 이름, 인증서 만료일, 전체 인증서 체인, 그리고 DNS가 의도한 호스트를 가리키는지 확인하십시오. 도메인 인증서가 서브도메인을 자동으로 포함하지는 않습니다.
• 컨테이너에서 인증서 또는 키가 누락되었다는 오류가 발생합니다. 호스트 소스 경로, 바인드 마운트 대상, 정확한 파일 이름 및 두 SSL_..._PATH값을 확인하십시오. Docker --mount구문에서는 소스 경로가 존재해야 하며, Compose 바인드 마운트 또한 의도한 기존 디렉터리를 가리켜야 합니다.
• 포트 443은 이미 사용 중입니다. 충돌하는 서비스를 중지하거나, 리버스 프록시를 사용하거나, 다른 공용 호스트 포트를 선택하고 URL 및 방화벽 설정이 변경되었는지 확인하십시오. 프록시 서버를 사용하는 경우 일반적으로 프록시 서버가 공용 포트 443을 소유합니다.
• HTTPS는 작동하지만 문서 편집이 실패합니다. 통합 URL, 양쪽 서비스의 JWT 비밀 키, 프록시 포워딩 규칙, 그리고 Docs가 스토리지 플랫폼에 연결할 수 있는지 확인하십시오. 실제 열기 및 저장 과정을 테스트해 보세요.
• 인증서가 갱신되었지만 사이트가 여전히 이전 인증서를 사용하고 있는 경우, 갱신 후 호스트에 마운트된 파일이 업데이트되었는지, 그리고 ONLYOFFICE가 해당 파일을 다시 로드했는지 확인하십시오. 필요한 경우, 갱신 후 서비스를 재시작하십시오. 예를 들어, docker compose restart documentserverCompose 프로젝트 디렉터리에서 실행되는 Certbot 배포 후크를 사용할 수 있습니다. 자동화를 사용하기 전에 Certbot의 드라이런 옵션을 사용하여 갱신을 테스트하십시오.

인증서를 최신 상태로 유지하세요.

HTTPS 설정은 갱신 계획이 수립될 때까지 완료된 것이 아닙니다. 인증서를 발급하고 갱신하는 담당자, 개인 키 저장 위치, 갱신된 파일을 마운트된 디렉터리로 복사하는 프로세스, 그리고 서비스가 해당 파일을 다시 로드하는 방법을 기록해 두십시오. 갱신 클라이언트의 모의 실행 테스트를 수행하고, 인증서 만료를 모니터링하며, 갱신 후에는 공개 엔드포인트를 확인하십시오. 호스트 관리형 인증서 대신 ONLYOFFICE의 내장 Let's Encrypt 변수를 사용하는 경우, 해당 방식에 대한 최신 Docker 지침을 따르고 실행하는 정확한 이미지 및 배포 환경에 대한 갱신 동작을 확인하십시오.

자세한 내용은 ONLYOFFICE Docs의 Docker 설치 및 HTTPS 가이드 , Docker 바인드 마운트 문서 , Docker Compose 문서 , ONLYOFFICE 공식 Docker 이미지 태그 및 Certbot의 공식 지침을 참조하십시오 . 사용 가능한 태그 및 인터페이스 세부 정보는 변경될 수 있으므로 새 배포를 준비할 때 확인하십시오.