자주 묻는 질문

일반적인 확장 설치 오류

/private/tmp/pear/install/mongodb/php_phongo.c:24:10: fatal error: 'php.h' file not found
#include <php.h>
         ^~~~~~~

php vendor/mongodb/mongodb/tools/detect-extension.php

<pre><?php require(...); ?></pre>

PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

연결 처리 및 지속성

MongoDB deployment 에 대한 연결은 libmongoc 라이브러리와 PHP 확장에 의해 처리됩니다. 인스턴스 를 MongoDB\Client 구성하면 PHP 라이브러리는 동일한 연결 문자열 과 옵션을 사용하여 MongoDB\ 드라이버\ 관리자 인스턴스 를 생성합니다. 또한 확장 프로그램은 이러한 생성자 인수를 사용하여 영구 클라이언트에 대한 해시 키를 libmongoc libmongoc 파생합니다. 이전에 키를 사용하여 클라이언트 를 유지한 경우 해당 키가 재사용됩니다. 그렇지 않으면 새 libmongoc 클라이언트 가 생성되어 PHP 작업자 프로세스 의 수명 동안 유지됩니다. 이 프로세스 에 대한 학습 내용은 PHP 확장 문서에서 확인할 수 있습니다.

각 libmongoc 클라이언트 는 MongoDB deployment 에 대한 자체 연결과 해당 토폴로지 뷰를 유지 관리합니다. 영구 libmongoc 클라이언트 를 재사용하면 PHP 라이브러리를 통해 새 연결을 설정하고 토폴로지 를 재발견하는 오버헤드 를 피할 수 있습니다. 이 접근 방식은 일반적으로 성능을 향상시키며 드라이버의 기본값 동작입니다.

영구 libmongoc 클라이언트는 PHP 작업자 프로세스 가 종료될 때까지 해제되지 않습니다. 즉, MongoDB\Driver\Manager 객체 가 범위를 벗어난 후에도 MongoDB deployment 에 대한 연결이 열린 상태로 유지될 수 있습니다. 이는 일반적으로 하나의 MongoDB deployment 에 연결하는 애플리케이션에서는 문제가 되지 않지만, 다음 목록에 설명된 일부 상황에서는 문제가 될 수 있습니다.

• PHP -FPM은 pm.max_requests=0로 구성되어 작업자가 다시 생성되지 않으며, MongoDB 연결 문자열 또는 옵션을 약간 변경하여 PHP 애플리케이션 이 여러 번 배포됩니다. 이로 인해 각 작업자 프로세스 에 libmongoc 클라이언트 객체가 누적될 수 있습니다.

• 요청 지연 시간 이 가장 중요하지 않은 백엔드 구성 요소에서 애플리케이션 이 별도의 MongoDB deployment 에 연결되는 경우가 있습니다.

첫 번째 경우, 애플리케이션 배포서버 의 일부로 PHP -FPM을 다시 시작하면 애플리케이션 에서 사용하지 않는 libmongoc 클라이언트를 출시하다 하면서도 최신 연결 문자열 에 대해 영구 클라이언트 를 계속 사용할 수 있습니다.

두 번째 경우에는 다른 솔루션이 필요합니다. disableClientPersistence 운전자 옵션에 true 를 지정하면 PHP 라이브러리에 새 libmongoc 클라이언트 를 생성하고 해당 MongoDB\Driver\Manager 가 범위를 벗어날 때 해제되도록 합니다.

다음 코드는 클라이언트 를 만들 때 disableClientPersistence 옵션을 true 로 설정하다 하는 방법을 보여 줍니다.

<?php
$client = new MongoDB\Client(
    uri: getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/',
    uriOptions: [],
    driverOptions: ['disableClientPersistence' => true],
);

클라이언트 지속성을 옵트아웃하면 MongoDB deployment 에 대한 연결을 설정하고 토폴로지 를 검색하는 데 더 많은 시간이 필요하므로 신중하게 고려한 후 disableClientPersistence 운전자 옵션을 사용합니다.

서버 선택 실패

다음은 서버 선택 실패의 모든 예입니다.

No suitable servers found (`serverSelectionTryOnce` set):
  [connection refused calling hello on 'a.example.com:27017']
  [connection refused calling hello on 'b.example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [socket timeout calling hello on 'example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [connection timeout calling hello on 'a.example.com:27017']
  [connection timeout calling hello on 'b.example.com:27017']
  [TLS handshake failed: -9806 calling hello on 'c.example.com:27017']
No suitable servers found: `serverselectiontimeoutms` timed out:
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'a.example.com:27017']
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'b.example.com:27017']

이러한 오류는 일반적으로 MongoDB\ 드라이버\Exception\ConnectionTimeoutException 확장자에서 예외가 발생합니다. 실제 예외 메시지는 확장 프로그램에서 사용하는 기본 시스템 라이브러리인 libmongoc에서 발생합니다. 이러한 메시지는 다양한 형태를 취할 수 있으므로 애플리케이션 의 오류를 더 잘 진단할 수 있도록 메시지 구조를 세분화하는 것이 도움이 됩니다.

메시지는 일반적으로 "적합한 서버를 찾을 수 없음"으로 시작합니다. 메시지의 다음 부분은 서버 선택이 실패한 방법 을 나타냅니다. 기본값 확장 프로그램은 서버 선택 루프를 피하고 대신 한 번만 시도합니다(serverSelectionTryOnce 연결 string 옵션에 따라). 확장 프로그램이 루프를 사용하도록 구성된 경우 "serverSelectionTimeoutMS expires"와 같은 메시지가 시간 제한을 소진했음을 알려줍니다.

메시지의 마지막 구성 요소에는 서버 선택이 실패한 이유 가 나와 있으며, 각 호스트에 대한 연결 및 모니터링을 담당하는 서비스인 토폴로지 스캐너에서 직접 발생하는 하나 이상의 오류가 포함되어 있습니다. 모니터링 중에 오류가 마지막으로 발생한 모든 호스트가 이 목록에 포함됩니다. 이러한 메시지는 일반적으로 낮은 수준의 소켓 또는 TLS 함수에서 발생합니다.

다음 내용이 포괄적인 것은 아니지만, 서버 선택 실패의 원인이 되는 요인을 분석하는 데 점 방향을 제시하기를 바랍니다.

• "connection 거부됨"은 원격 호스트가 예상 포트에서 수신 대기하고 있지 않음을 나타냅니다.

• '연결 시간 초과'는 라우팅 또는 방화벽 문제이거나 지연 시간으로 인한 시간 초과일 수 있습니다.

• '소켓 시간 초과'는 연결 이 점 설정되었지만 지연 시간 인해 끊어지거나 시간이 초과되었음을 나타냅니다.

• "TLS 핸드셰이크 실패"는 TLS 또는 OCSP 확인과 관련된 내용을 나타내며 경우에 따라 TLS 인증서가 잘못 구성되었음을 나타냅니다.

연결에 실패하는 경우 connect 도구를 사용하여 추가 정보를 받을 수 있습니다. 이 도구는 소켓 함수를 사용하여 연결 문자열의 각 호스트에 연결을 시도하여 연결 설정, 데이터 전송 및 수신이 가능한지 확인합니다. 이 도구는 MongoDB 배포에 대한 연결 문자열을 유일한 인수로 사용합니다. 컴포저를 통해 라이브러리를 설치했다고 가정하고 공급업체 디렉토리에서 스크립트를 호출합니다.

php vendor/mongodb/mongodb/tools/connect.php mongodb://127.0.0.1:27017

서버가 연결을 허용하지 않는 경우 출력은 다음과 같습니다.

Looking up MongoDB at mongodb://127.0.0.1:27017
Found 1 host(s) in the URI. Will attempt to connect to each.
Could not connect to 127.0.0.1:27017: Connection refused