Kopano 웹 앱 "Kopano 코어에 연결할 수 없습니다" 오류 해결

Kopano 웹 애플리케이션에서 발생하는 "Kopano Core에 연결할 수 없습니다" 오류를 해결하는 가장 빠른 방법은 세 가지 계층 중 어느 계층에 실제로 문제가 있는지 파악하는 것입니다. Kopano Core 자체 , 웹 애플리케이션과 Core 간의 엔드포인트 , 또는 웹 애플리케이션이 Core와 통신하는 데 사용하는 PHP-MAPI 계층 중 어느 쪽에 문제가 있는지 확인해야 합니다. 모든 것을 재시작하면 문제가 해결되는 것처럼 보일 수 있지만, 이는 근본적인 원인을 숨기고 반복적인 오류 발생 시 진단을 더욱 어렵게 만들 수 있습니다.

Kopano의 공식 웹 애플리케이션 문서에 따르면 웹 애플리케이션은 Kopano Core에 의존하며 php-mapi, 해당 DEFAULT_SERVER설정은 웹 애플리케이션이 Kopano Core에 연결하는 방식을 제어합니다. 문서에 명시된 연결 방식에는 로컬 Unix 소켓, 236번 포트의 HTTP, 237번 포트의 HTTPS가 있습니다. 자세한 내용은 Kopano 웹 애플리케이션 구성 문서 와 Kopano Core 관리자 설명서를 참조하십시오 .

중요 버전 참고: 이 글을 작성하는 시점에서 제공되는 Kopano의 공개 관리자 설명서는 최신 Linux 배포판보다 오래된 버전입니다. 따라서 패키지 이름, PHP 버전, 서비스 래퍼 및 로그 위치는 설치 환경에 따라 다를 수 있습니다. 아래에 설명된 연결 모델 및 구성 옵션은 Kopano에서 공개한 문서를 기반으로 하지만, 운영 서버를 변경하기 전에 로컬 경로 및 패키지 버전을 확인해야 합니다.

어떤 해결책을 먼저 시도해야 할까요?

한 번에 모든 변경 사항을 적용하기보다는 시스템에 가장 적합한 증상부터 시작하십시오.

1. 코파노 코어가 실제로 실행 중인가요?

웹 애플리케이션 설정을 편집하기 전에 서버 프로세스를 확인하십시오. systemd 기반 배포판에서는 다음 명령어를 사용하십시오.

sudo systemctl status kopano-server

장치가 고장났거나 비활성화된 경우, 재시작하기 전에 최근 로그를 확인하십시오.

sudo journalctl -u kopano-server -n 100 --no-pager

데이터베이스 연결 오류, 구성 구문 분석 실패, 권한 문제, 파일 누락 또는 시작 오류를 확인하십시오. Kopano Core 문서에서는 구성 변경 후 일반적으로 해당 구성 요소를 다시 시작해야 한다고 명시하고 있습니다(예: `restart` 명령 사용) systemctl restart kopano-<component>. 또한 `restart` 명령이 /etc/kopano/server.cfg일반적인 구성 파일이라고 설명합니다 kopano-server. KC 구성 요소 구성하기를 참조하십시오 .

서비스가 명백히 중단되었거나, 시작 후 충돌이 발생하거나, 다른 Kopano 도구도 Core와 통신할 수 없는 경우 이 방법을 선택하십시오 . 웹 애플리케이션을 먼저 수정하는 것은 하위 단계의 증상만 해결하는 것입니다.

절충점: 재시작은 가장 빠른 복구 시도이지만, 프로세스가 즉시 다시 실패하는 경우 저널 출력이 필요합니다. 운영 시스템에서는 재시작하기 전에 실패 세부 정보를 캡처하여 가장 명확한 증거를 잃지 않도록 해야 합니다.

2. 웹 애플리케이션이 올바른 Kopano Core 엔드포인트를 가리키고 있습니까?

WebApp에서 키 설정은 DEFAULT_SERVER에 있습니다 config.php. Kopano의 공식 WebApp 설명서에는 이러한 예제가 나와 있습니다.

define("DEFAULT_SERVER", "default:");
define("DEFAULT_SERVER", "file:///var/run/kopano/server.sock");
define("DEFAULT_SERVER", "http://localhost:236/kopano");
define("DEFAULT_SERVER", "https://localhost:237/kopano");

문서에 명시된 기본 매핑은 로컬 소켓입니다 file:///var/run/kopano/server.sock. 웹 애플리케이션과 코어가 동일한 머신에서 실행되는 경우 일반적으로 가장 간단한 선택입니다. 하지만 서로 다른 머신에서 실행되는 경우 로컬 Unix 소켓은 작동하지 않으며, 대신 접근 가능한 HTTP 또는 HTTPS 엔드포인트가 필요합니다. Kopano의 성능 튜닝 문서에서는 웹 애플리케이션 호스트가 포트 236(SSL의 경우 포트 237)을 통해 별도의 Kopano 서버에 연결하는 방법을 설명합니다. Kopano 성능 튜닝 및 분할 서버 구성 문서를 참조하십시오 .

로컬 유닉스 소켓: 일반적으로 단일 호스트에서 오버헤드가 가장 적은 옵션이며, 로컬 웹 애플리케이션 접근을 위해 TCP 서비스를 노출하지 않아도 됩니다. 단점은 소켓이 존재해야 하고 웹 서버 프로세스가 해당 소켓을 사용할 수 있어야 한다는 것입니다.

HTTP 236 포트 사용: 호스트 간 테스트가 용이하고 보안 아키텍처가 허용하는 경우 신뢰할 수 있는 내부 네트워크에 적합합니다. 단, 코파노 전송 계층에서 트래픽이 암호화되지 않는다는 단점이 있습니다.

포트 237의 HTTPS: 웹 애플리케이션과 코어 간에 암호화된 전송이 필요한 경우에 적합합니다. 이 경우 인증서 설정 및 유효성 검사 요구 사항이 발생합니다. Kopano의 특별 구성 문서에는 웹 애플리케이션이 HTTPS를 사용하고 DEFAULT_SERVER, 일부 시나리오에서는 클라이언트 인증서를 사용하는 방법이 나와 있습니다. Kopano의 특별 코어 구성 문서를 참조하십시오 .

3. 유닉스 소켓을 사용하는 경우, 해당 소켓이 존재하며 웹 서버에서 접근할 수 있습니까?

동일 호스트 배포의 경우 소켓 자체를 확인하십시오.

ls -l /var/run/kopano/server.sock
file /var/run/kopano/server.sock
ss -xl | grep kopano

해당 파일이 없는 경우, 그 이름으로 일반 파일을 생성하지 마십시오. 소켓은 실행 중인 Kopano 서버에서 생성됩니다. 따라서 소켓이 없는 문제는 일반적으로 코어 시작, 소켓 경로 변경 또는 구성 불일치와 관련이 있습니다.

소켓이 존재한다면 소유권과 모드를 확인하십시오. 웹 서버 사용자는 해당 디렉터리 경로를 통해 소켓에 접근할 수 있어야 합니다. 사용하는 배포판에 따라 웹 서버 계정은 `<사용자 이름>` www-data, apache`<사용자 이름>` 또는 다른 서비스별 사용자일 수 있습니다. `<사용자 이름>`과 같은 포괄적인 모드를 사용하여 권한 오류를 해결하지 마십시오. chmod 777이는 취약점을 증가시키고 서비스가 다음에 소켓을 생성할 때 덮어쓰여질 수 있습니다.

더 나은 방법은 Kopano에서 생성된 소켓 위치에 맞춰 WebApp을 정렬한 다음 배포판에서 의도한 그룹 또는 서비스 권한을 사용하는 것입니다. 서버가 사용자 지정된 경우 소유권을 변경하기 전에 Core 구성과 WebApp 엔드포인트를 비교하십시오.

4. 코어는 정상인데 웹 애플리케이션에서 연결할 수 없다고 표시되는 경우는 어떻게 해야 하나요?

다음으로 PHP-MAPI를 확인하세요. Kopano는 웹 애플리케이션이 PHP-MAPI에 의존한다고 명시적으로 밝히고 있습니다 . 웹 애플리케이션 구성 검사에서 PHP 및 PHP-MAPI의 사용 가능 여부도 확인할 수 있습니다. WebApp Config.php 문서를php-mapi 참조하세요 .

간단한 CLI 점검은 다음과 같습니다.

php -m | grep -i mapi

하지만 이 테스트에는 중요한 한계가 있습니다. PHP 명령줄 인터페이스(CLI)는 Apache PHP, PHP-FPM 또는 다른 웹 서버 통합과 동일한 구성을 사용하지 않을 수 있습니다. CLI 테스트에서 양성 결과가 나왔다고 하더라도 이는 CLI 환경에서 해당 모듈을 인식한다는 의미일 뿐입니다.

유용한 후속 점검 사항은 다음과 같습니다.

php --ini
php -i | grep -i mapi

그런 다음 웹 서버 또는 FPM 풀에서 사용하는 PHP 구성과 비교하십시오. 패키지가 없거나 버전이 호환되지 않는 경우, 사용 중인 배포판 및 Kopano 릴리스에 맞는 저장소에서 해당 Kopano Core/PHP-MAPI 패키지 세트를 설치하십시오. 확장 프로그램이 .php 파일에 나타나도록 하기 위해 관련 없는 PHP-MAPI 빌드를 혼합하여 사용하지 마십시오 php -m.

다음과 같은 경우에 이 경로를 선택하십시오. kopano-server 웹 애플리케이션이 정상 작동하고 엔드포인트가 올바르며 접근 가능하지만, PHP 측 연결 또는 구성 검사 중에 오류가 발생하는 경우입니다.

절충점: 바이너리 버전이 일치하지 않을 경우 패키지를 재설치하거나 업그레이드하는 것이 적절한 해결 방법일 수 있지만, 단일 엔드포인트를 수정하는 것보다 시스템 전체를 변경하게 됩니다. 따라서 먼저 패키지 버전을 확인하고 적절한 시기에 프로덕션 환경으로 업그레이드를 진행해야 합니다.

Apache, PHP-FPM 또는 Kopano 서버를 재시작해야 할까요?

구성이나 모듈이 실제로 변경된 구성 요소를 다시 시작하십시오.

• 설정을 변경했다면 /etc/kopano/server.cfg다시 시작하세요 kopano-server.
• PHP 확장 프로그램을 설치했거나 활성화한 경우, 웹 애플리케이션에서 사용하는 PHP 서버(예: Apache 또는 관련 PHP-FPM 서비스)를 다시 시작하십시오.
• 웹 애플리케이션의 PHP 설정 파일만 변경한 경우, Kopano Core 엔드포인트 자체가 변경되지 않았다면 일반적으로 Kopano Core를 완전히 재시작할 필요는 없습니다.

웹 서비스 명령어는 배포판 및 PHP 패키징에 따라 다릅니다. 예를 들어 `/php`, `/php` 또는 버전이 지정된 PHP-FPM 유닛일 수 있습니다 systemctl restart apache2. systemctl restart httpd명령어를 무작정 복사하지 말고 호스트에 있는 서비스 이름을 사용하십시오.

원격 코어 서버와 방화벽은 어떻습니까?

WebApp과 Kopano Core가 분리되어 있는 경우, WebApp에 문제가 있다고 단정하기 전에 먼저 라우팅 및 구성된 리스너를 확인하십시오. Kopano 설명서에는 HTTP 액세스는 236번 포트, SSL 액세스는 237번 포트를 사용한다고 나와 있습니다. 따라서 원격 배포는 로컬 Unix 소켓 배포에는 없는 방화벽 규칙, 리스너 바인딩, DNS, TLS 인증서, 역방향 프록시 및 중간 네트워크 정책과 같은 여러 가지 오류 발생 가능성을 추가합니다.

HTTP 엔드포인트의 경우, 적어도 웹 애플리케이션 호스트에서 TCP 리스너에 접근할 수 있는지 여부를 확인할 수 있습니다.

nc -vz core.example.net 236

HTTPS의 경우, 인증서 정책에 맞는 도구를 사용하여 TLS 엔드포인트를 별도로 확인하십시오. TCP 연결이 성공했다고 해서 웹 애플리케이션 인증이나 MAPI 작업이 성공한다는 것을 보장하는 것은 아니지만, 연결 실패는 PHP-MAPI가 해당 주소와 포트를 통해 구성된 서비스에 도달할 수 없음을 의미합니다.

리버스 프록시를 사용하는 경우 Kopano 문서에서는 프록시 경로와 백엔드 매핑이 웹 애플리케이션에서 사용하는 URL과 일치해야 한다고 명시하고 있습니다. 또한 공식 코어 매뉴얼에는 Kopano 트래픽 프록싱을 위한 HTTP/1.1 고려 사항이 나와 있습니다. Kopano 코어 구성 요소 구성을 참조하세요 .

불필요한 변경을 최소화하는 실용적인 진단 순서

1. 상태를 확인하세요 kopano-server. 실패한 경우, 먼저 코어 문제를 해결하세요.
2. 코어 로그를 확인하세요. 웹 애플리케이션이 연결되기 전에 데이터베이스 또는 구성 오류를 해결해야 합니다.
3. 검증하십시오 DEFAULT_SERVER. 로컬 소켓 또는 올바른 원격 HTTP/HTTPS 엔드포인트와 일치하는지 확인하십시오.
4. 실제 소켓 또는 네트워크 리스너를 테스트하십시오. 이렇게 하면 전송 오류와 PHP 문제를 구분할 수 있습니다.
5. 웹 런타임 환경에서 PHP-MAPI를 검증하십시오. CLI PHP 환경에만 의존하지 마십시오.
6. 영향을 받는 서비스만 재시작하십시오. 그런 다음 웹 애플리케이션을 다시 테스트하고 오류가 계속되면 로그를 검토하십시오.

이 순서는 패키지 재설치부터 시작하는 것보다 더 안전합니다. 증거를 보존하고 각 테스트의 의미를 부여할 수 있기 때문입니다. 또한 Kopano Core 자체가 시작되지 않을 때 WebApp이나 Apache를 반복적으로 재시작하는 정반대의 실수를 방지할 수 있습니다.

DEFAULT_SERVER를 변경하는 것이 잘못된 해결책인 경우는 언제입니까?

DEFAULT_SERVER로그인 페이지에 연결 오류가 표시된다는 이유만으로 값을 변경하지 마십시오 . 현재 값이 의도한 Core 인스턴스를 올바르게 가리키는 경우, 값을 변경하면 원래 문제가 가려지거나 사용자가 잘못된 백엔드로 이동할 수 있습니다.

예를 들어, default:를 로 교체하는 http://localhost:236/kopano것은 본질적으로 업그레이드가 아닙니다. 이는 문서화된 로컬 기본 소켓에서 TCP로 전송 방식을 변경하는 것입니다. 디버깅이나 TCP가 필요한 토폴로지에는 유용할 수 있지만, 보안 및 운영 측면에서도 변화가 생깁니다. 동일 호스트 설정의 경우, 누락되거나 접근할 수 없는 소켓을 수정하는 것이 다른 리스너를 여는 것보다 깔끔한 해결책인 경우가 많습니다.

오류가 계속 발생하면 어떻게 해야 하나요?

그 시점에서 관계의 양측으로부터 증거를 수집하십시오.

• DEFAULT_SERVER자격 증명이나 비밀 키를 제거한 정확한 값입니다.
• systemctl status kopano-server그리고 최근 Kopano 서버 로그 항목들;
• 소켓 소유권 또는 원격 리스너 정보;
• 웹 서버 런타임에 로드된 PHP 버전 및 MAPI 확장 프로그램;
• 웹 애플리케이션/PHP 로그인 시도 실패와 관련된 오류 로그입니다.

Kopano의 웹 애플리케이션 문서에 따르면 PHP 오류 로깅은 PHP 설정에서 활성화할 수 있으며 , 오류를 직접 표시하면 JSON 응답이 손상될 수 있으므로 서버 측 로그를 통해 진단하는 것이 더 적절하다고 합니다. 로깅 수준을 높이기 전에 공식 웹 애플리케이션 로깅 설정을config.php 참조하십시오 .

Kopano Core 시작, 전송, 권한, PHP-MAPI 또는 원격 네트워킹 중 어떤 문제로 인해 오류가 발생하는지 파악한 후에는 해당 계층에 맞는 가장 작은 수정 사항부터 적용하십시오. "Kopano Core에 연결할 수 없습니다"라는 오류를 하나의 만능 해결책으로 취급하는 것보다 이 방법이 훨씬 더 안정적입니다.