Docker에서 ONLYOFFICE Docs에 대한 HTTPS 구성

ONLYOFFICE Docs에 직접 연결하려면 컨테이너 포트 443을 공개하고, 마운트된 데이터 디렉터리 아래에 인증서 파일을 저장한 다음, 컨테이너가 해당 파일을 가리키도록 설정하십시오. 리버스 프록시에서 이미 HTTPS를 제공하는 경우, 기본적으로 두 번째 TLS 엔드포인트를 활성화하는 대신 해당 프록시에서 TLS를 유지하고 원래 호스트와 프로토콜을 ONLYOFFICE로 포워딩하십시오.

예를 들어, 공용 호스트 이름이 인 경우 docs.example.com, 먼저 해당 호스트 이름이 문서 서버를 직접 가리키는지 아니면 프록시를 가리키는지 확인하십시오. 아래와 같이 일치하는 구성만 사용하십시오.

1. HTTPS 연결이 끝나는 지점을 결정합니다.

TLS는 HTTPS 복호화가 완료되는 지점, 즉 ONLYOFFICE 컨테이너 내부 또는 역방향 프록시에서 종료됩니다. 공용 연결을 수신할 구성 요소를 선택하십시오.

• 직접 접속: 클라이언트는 https://docs.example.com호스트의 443번 포트(컨테이너의 443번 포트에 매핑됨)를 통해 접속합니다. 문서 서버 컨테이너에는 인증서와 해당 인증서에 맞는 개인 키가 필요합니다.
• 프록시 액세스: 클라이언트는 HTTPS를 통해 프록시에 연결하고, 프록시는 내부 네트워크를 통해 문서 서버로 트래픽을 전달합니다. 이 설정에서 인증서는 일반적으로 프록시에 있어야 합니다. ONLYOFFICE의 프록시 지침에 따르면 애플리케이션이 공개 요청 스키마와 호스트 이름을 식별할 수 있도록 `<hostname>` X-Forwarded-Proto및 `<hostname>` 헤더를 사용해야 합니다.X-Forwarded-Host

포트 매핑은 443:443HTTPS를 생성하는 것이 아니라 단순히 포트를 매핑하는 것입니다. 직접 액세스를 위해서는 컨테이너가 인증서와 키를 읽어야 합니다. 프록시가 공용 URL을 소유하는 경우 ONLYOFFICE의 공식 리버스 프록시 지침을 따르세요 .

2. Docker Compose에서 직접 HTTPS 구성

컨테이너가 HTTPS를 직접 제공하는 경우 이 경로를 사용하십시오. 공개 액세스의 경우 클라이언트가 신뢰하는 공개 호스트 이름에 대한 인증서를 사용하십시오. 자체 서명 인증서는 트래픽을 암호화할 수 있지만, 클라이언트가 별도로 신뢰하도록 구성하지 않으면 클라이언트 ID에 대한 경고가 표시됩니다.

ONLYOFFICE Docs는 /var/www/onlyoffice/Data/certs기본적으로 인증서를 아래 경로에 저장하며, 현재 Docker 구성에서는 기본 인증서 및 키 경로로 tls.crt와 를 지정합니다 tls.key. 문서 예제에서 항상 동일한 파일 이름을 사용하지는 않았으므로, 이 예제에서는 두 경로를 명시적으로 설정합니다.

services:
  documentserver:
    # Keep your existing image, environment, networks, and other settings.
    ports:
      - "443:443"
    volumes:
      - ./documentserver-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, 네트워크 및 볼륨 설정을 그대로 유지하십시오. Compose 파일을 기준으로 인증서를 에, ./documentserver-data/certs/tls.crt해당 키를 에 배치하십시오 ./documentserver-data/certs/tls.key. 공급업체에서 제공한 인증서 체인을 포함하고, 인증서가 를 포함하는지 확인하십시오 docs.example.com.

바인드 마운트를 사용하면 파일을 교체 가능한 컨테이너 외부에 보관할 수 있습니다. 컨테이너가 개인 키를 읽을 수 있도록 하면서도 개인 키 접근을 제한해야 합니다. 그렇지 않으면 HTTPS 시작에 실패할 수 있습니다. 지원 요청 시 개인 키를 절대 공유하지 마십시오.

3. 배포를 실수로 덮어쓰지 않고 변경 사항을 적용합니다.

1. Compose 파일과 인증서 디렉터리를 백업한 다음, 인증서와 키가 공개 호스트 이름과 일치하는지 확인하십시오.
2. 기존 서비스에서 포트, 볼륨 및 경로를 변경하십시오. 동일한 호스트 포트를 사용하는 두 번째 컨테이너를 시작하거나 TLS를 적용하기 위해 기존 볼륨을 삭제하지 마십시오.
3. 포트, 마운트 또는 환경 변수를 변경한 경우 서비스를 다시 생성하십시오. Compose를 사용하는 경우 docker compose up -d documentserverCompose 파일이 있는 디렉터리에서 실제 서비스 이름으로 바꿔 실행하십시오. 이미 마운트된 디렉터리에서 인증서 파일만 교체한 경우 서버가 파일을 다시 로드하도록 기존 컨테이너를 다시 시작하십시오 docker restart <container_name>.
4. HTTPS 연결이 되지 않으면 시작 로그를 확인하세요 docker logs <container_name>. 관련 없는 설정을 변경하기 전에 누락된 파일, 권한 또는 인증서/키 오류가 있는지 확인하십시오.

재시작으로는 마운트를 추가하거나 게시된 포트를 변경할 수 없습니다. 이러한 변경 사항을 적용하려면 서비스를 다시 생성하십시오. 기존 영구 마운트의 파일을 교체하는 데에는 Compose 변경이 필요하지 않습니다.

4. 리버스 프록시가 이미 해당 도메인을 서비스하고 있는 경우 TLS를 유지하십시오.

리버스 프록시가 이미 종료된 경우 https://docs.example.com, 프록시에 개인 키를 보관하십시오. 제어된 네트워크를 통해 트래픽을 전달하고, 공용 호스트 이름을 X-Forwarded-Proto: https설정 하십시오. 사용하는 프록시 소프트웨어의 공식 샘플을 활용하십시오.X-Forwarded-Host

브라우저 자물쇠 아이콘은 클라이언트와 프록시 간의 연결을 보호하며, 모든 내부 연결을 보호하는 것은 아닙니다. 제어된 Docker 네트워크에서 HTTP를 사용하는 것이 일부 배포 환경에 적합할 수 있지만, 신뢰할 수 없는 네트워크를 거치는 경우 프록시에서 컨테이너로의 연결을 보호해야 합니다.

또 다른 제한 사항은 TLS를 변경해도 유효하지 않은 JWT, 차단된 방화벽 포트 또는 통합 설정의 잘못된 공용 문서 서버 주소가 수정되지 않는다는 것입니다. 인증서가 유효한데도 문서 로드 또는 편집이 계속 실패하는 경우, 인증서를 반복적으로 재생성하기보다는 관련 애플리케이션 및 프록시 로그를 확인하십시오.

결과를 ​​확인하세요

공용 서비스에 접속할 수 있는 클라이언트에서 https://docs.example.com브라우저를 열고 인증서 세부 정보를 확인하십시오. 호스트 이름이 일치하는지, 인증서 유효 기간이 지나지 않았는지, 브라우저에 신뢰할 수 없는 발급자 또는 이름 불일치 오류가 표시되지 않는지 확인하십시오. 터미널에서 `tls` 명령어를 사용하여 TLS 핸드셰이크를 검사할 수도 있습니다 curl -Iv https://docs.example.com. 페이지 로드 여부에만 의존하지 말고 인증서 및 연결 출력 내용을 검토하십시오.

마지막으로 통합 애플리케이션에서 문서를 엽니다. 브라우저에서 성공적으로 열렸다면 공용 엔드포인트가 제대로 연결된 것이지, 모든 통합 설정이나 내부 경로가 제대로 연결된 것은 아닙니다. 인증서 관련 경고가 있는 경우 호스트 이름, 인증서 체인, 경로, 권한 및 TLS 종료 설정을 다시 확인하십시오. HTTPS는 확인되었지만 편집에 실패하는 경우 로그와 인증 또는 라우팅 설정을 확인하십시오.

지원되는 Docker 경로, 인증서 변수 및 내장 Let's Encrypt 옵션에 대한 자세한 내용은 ONLYOFFICE의 Docker 설치 및 HTTPS 문서를 참조하십시오 . 기존 배포를 업데이트하는 정확한 명령은 원래 생성 방식에 따라 다릅니다. 관련 TLS 변경 사항을 적용하는 동안 해당 배포의 현재 볼륨 및 통합 설정을 유지하십시오.