Corrigir erro "Não foi possível conectar ao Kopano Core" no aplicativo web Kopano

A maneira mais rápida de corrigir o erro "Não foi possível conectar ao Kopano Core" em um aplicativo web Kopano é determinar qual das três camadas está realmente com problemas: o próprio Kopano Core , o endpoint entre o aplicativo web e o Core ou a camada PHP-MAPI que o aplicativo web usa para se comunicar com o Core. Reiniciar tudo pode ocasionalmente parecer resolver o problema, mas isso mascara a causa e pode dificultar o diagnóstico de falhas recorrentes.

A documentação oficial do WebApp do Kopano afirma que o WebApp depende do Kopano Core php-mapie que suas DEFAULT_SERVERconfigurações controlam a conexão do WebApp com o Kopano Core. As opções documentadas incluem o socket Unix local, HTTP na porta 236 e HTTPS na porta 237. Consulte a documentação de configuração do Kopano WebApp e o Manual do Administrador do Kopano Core .

Nota importante sobre a versão: Os manuais públicos do administrador do Kopano disponíveis no momento da redação deste documento são mais antigos do que muitas distribuições Linux atuais. Portanto, os nomes dos pacotes, as versões do PHP, os wrappers de serviço e os locais dos logs podem ser diferentes na sua instalação. O modelo de conexão e as opções de configuração descritas abaixo são baseados na documentação publicada pelo próprio Kopano, mas você deve confirmar os caminhos locais e as versões dos pacotes antes de fazer alterações em um servidor de produção.

Qual solução você deve tentar primeiro?

Comece pelo sintoma que melhor se adequa ao seu sistema, em vez de aplicar todas as mudanças de uma vez.

1. O Kopano Core está realmente em execução?

Verifique o processo do servidor antes de editar a configuração do WebApp. Em uma distribuição baseada em systemd, use:

sudo systemctl status kopano-server

Se a unidade estiver com falha ou inativa, verifique seu registro recente antes de reiniciá-la:

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

Procure por erros de conexão com o banco de dados, falhas na análise da configuração, problemas de permissão, arquivos ausentes ou erros de inicialização. A documentação do Kopano Core observa que as alterações de configuração geralmente exigem que o componente afetado seja reiniciado, por exemplo, com `kopano restart` systemctl restart kopano-<component>. Ela também documenta `kopano.config` /etc/kopano/server.cfgcomo o arquivo de configuração usual para `kopano.config` kopano-server. Consulte Configurar componentes do Kopano .

Escolha esta abordagem quando: o serviço estiver claramente inativo, apresentar falhas após a inicialização ou outras ferramentas do Kopano também não conseguirem se comunicar com o Core. Corrigir o WebApp primeiro apenas trataria um sintoma secundário.

Compensação: reiniciar é a tentativa de recuperação mais rápida, mas se o processo falhar novamente imediatamente, você precisará da saída do registro de eventos (journal). Em sistemas de produção, registre os detalhes da falha antes de reiniciar para não perder a evidência mais clara.

2. O WebApp aponta para o endpoint correto do Kopano Core?

No WebApp, a configuração principal está DEFAULT_SERVERem config.php. O manual oficial do WebApp do Kopano documenta estes exemplos:

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");

O padrão documentado mapeia para o socket local file:///var/run/kopano/server.sock. Essa geralmente é a opção mais simples quando o WebApp e o Core são executados na mesma máquina. Se forem executados em máquinas separadas, um socket Unix local não funcionará; você precisará de um endpoint HTTP ou HTTPS acessível. A documentação de otimização de desempenho do Kopano descreve um host WebApp conectando-se a um servidor Kopano separado pela porta 236 ou pela porta 237 para SSL. Consulte Otimização de desempenho do Kopano e configuração de servidor dividido .

Socket Unix local: geralmente a opção com menor sobrecarga em um único host, evitando expor um serviço TCP apenas para acesso local do aplicativo web. A desvantagem é que o socket precisa existir e o processo do servidor web precisa ser capaz de usá-lo.

HTTP na porta 236: mais fácil de testar em diferentes hosts e adequado para redes internas confiáveis ​​quando sua arquitetura de segurança permite. A desvantagem é que o tráfego não é criptografado na camada de transporte do Kopano.

HTTPS na porta 237: apropriado quando você precisa de transporte criptografado entre o WebApp e o Core. Isso introduz requisitos de configuração e validação de certificados. A documentação de configuração especial do Kopano mostra o WebApp usando HTTPS DEFAULT_SERVERe, em alguns cenários, certificados de cliente. Consulte Configurações especiais do Kopano Core .

3. Se você usar um socket Unix, ele existe e o servidor web consegue acessá-lo?

Para uma implementação no mesmo host, verifique o próprio socket:

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

Se o arquivo estiver faltando, não crie um arquivo normal com esse nome. O socket é criado pelo servidor Kopano em execução. Portanto, a ausência de um socket geralmente indica um problema na inicialização do Core, uma alteração no caminho do socket ou uma incompatibilidade de configuração.

Se o socket existir, verifique sua propriedade e permissões. O usuário do servidor web deve ter permissão para acessar o socket através do seu caminho de diretório. Dependendo da sua distribuição, a conta do servidor web pode ser `user` www-data, apache`username` ou outro usuário específico do serviço. Evite resolver erros de permissão com permissões amplas como chmod 777`username`, pois isso aumenta a exposição e pode ser sobrescrito na próxima vez que o serviço recriar o socket.

Uma abordagem melhor é alinhar o WebApp com a localização do socket gerada pelo Kopano e, em seguida, usar as permissões de grupo ou serviço pretendidas pela distribuição. Se o seu servidor foi personalizado, compare a configuração do Core com o endpoint do WebApp antes de alterar a propriedade.

4. E se o Core estiver íntegro, mas o WebApp ainda indicar que não consegue se conectar?

Verifique o PHP-MAPI em seguida. O Kopano afirma explicitamente que o WebApp depende dele php-mapi. A verificação de configuração do WebApp também pode testar a disponibilidade do PHP e do PHP-MAPI. Consulte a documentação do arquivo WebApp Config.php .

Uma verificação rápida via linha de comando é:

php -m | grep -i mapi

No entanto, este teste tem uma limitação importante: a interface de linha de comando do PHP pode não usar a mesma configuração que o Apache PHP, PHP-FPM ou outra integração com servidor web. Um resultado positivo na CLI comprova apenas que o ambiente da CLI reconhece o módulo.

Algumas verificações de acompanhamento úteis incluem:

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

Em seguida, compare isso com a configuração do PHP usada pelo seu servidor web ou pool FPM. Se o pacote estiver faltando ou as versões forem incompatíveis, instale o conjunto de pacotes Kopano Core/PHP-MAPI correspondente do repositório destinado à sua distribuição e versão do Kopano. Não misture versões incompatíveis do PHP-MAPI apenas para que a extensão apareça no repositório php -m.

Escolha esta rota quando: kopano-server o servidor estiver íntegro, o endpoint estiver correto e acessível, mas o WebApp falhar durante a conexão ou as verificações de configuração do lado PHP.

Compensação: reinstalar ou atualizar o pacote pode ser a solução correta quando os binários são incompatíveis, mas isso altera mais o sistema do que corrigir um único ponto de extremidade. Confirme as versões dos pacotes primeiro e agende as atualizações de produção adequadamente.

Você deve reiniciar o Apache, o PHP-FPM ou o servidor Kopano?

Reinicie o componente cuja configuração ou módulo foi alterado.

• Se você fez alguma alteração /etc/kopano/server.cfg, reinicie kopano-server.
• Se você instalou ou ativou uma extensão PHP, reinicie a camada de serviço PHP usada pelo WebApp, como o Apache ou o serviço PHP-FPM relevante.
• Se você alterou apenas o arquivo de configuração PHP do WebApp, geralmente não é necessário reiniciar o Kopano Core por completo, a menos que o próprio endpoint do Core também tenha sido alterado.

O comando exato do serviço web varia de acordo com a distribuição e o pacote PHP. Exemplos podem ser `php.php` systemctl restart apache2, systemctl restart httpd`php.php`, ou uma unidade PHP-FPM com versão específica. Use o nome do serviço presente em seu host em vez de copiar um comando cegamente.

E quanto aos servidores Core remotos e firewalls?

Se o WebApp e o Kopano Core estiverem separados, verifique primeiro o roteamento e o listener configurado antes de culpar o WebApp. A documentação do Kopano descreve o acesso HTTP na porta 236 e o ​​acesso SSL na porta 237. Portanto, uma implantação remota adiciona vários modos de falha que uma implantação local com socket Unix não possui: regras de firewall, vinculação de listener, DNS, certificados TLS, proxies reversos e política de rede intermediária.

Para um endpoint HTTP, você pode pelo menos verificar se um listener TCP está acessível a partir do host do aplicativo web:

nc -vz core.example.net 236

Para HTTPS, verifique o endpoint TLS separadamente com uma ferramenta adequada à sua política de certificados. Uma conexão TCP bem-sucedida não comprova que a autenticação do WebApp ou as operações MAPI serão bem-sucedidas, mas uma falha na conexão comprova que o PHP-MAPI não consegue alcançar o serviço configurado nesse endereço e porta.

Se você usa um proxy reverso, lembre-se de que a documentação do Kopano exige que o caminho do proxy e o mapeamento do backend sejam consistentes com a URL usada pelo WebApp. O manual oficial do Core também menciona considerações sobre HTTP/1.1 para o proxy do tráfego do Kopano. Consulte a configuração do componente Kopano Core .

Uma ordem diagnóstica prática que minimiza alterações desnecessárias.

1. Verifique kopano-servero status. Se falhar, corrija o núcleo primeiro.
2. Leia os logs principais. Problemas no banco de dados ou na configuração devem ser resolvidos antes que o WebApp possa se conectar.
3. Verifique DEFAULT_SERVER. Confirme se corresponde a um socket local ou ao endpoint HTTP/HTTPS remoto correto.
4. Teste o socket ou o listener de rede real. Isso diferencia falhas de transporte de problemas do PHP.
5. Verifique o PHP-MAPI no ambiente de execução web. Não confie apenas no ambiente PHP da linha de comando.
6. Reinicie apenas os serviços afetados. Em seguida, teste novamente o aplicativo Web e verifique os registros se o erro persistir.

Essa ordem é mais segura do que começar reinstalando pacotes, pois preserva as evidências e torna cada teste significativo. Também evita o erro oposto: reiniciar repetidamente o WebApp ou o Apache quando o próprio Kopano Core não consegue iniciar.

Quando alterar o DEFAULT_SERVER é a solução errada?

Não altere o valor DEFAULT_SERVERapenas porque a página de login exibe um erro de conexão. Se o valor atual apontar corretamente para a instância Core desejada, alterá-lo pode mascarar o problema original ou direcionar os usuários para o backend errado.

Por exemplo, substituir default:não http://localhost:236/kopanoé inerentemente uma atualização. Isso altera o transporte do socket local padrão documentado para TCP. Isso pode ser útil para depuração ou para uma topologia que exige TCP, mas também altera a segurança e a superfície operacional. Para uma configuração no mesmo host, corrigir o socket ausente ou inacessível geralmente é mais adequado do que abrir outro listener.

O que você deve fazer se o erro persistir?

Nesse ponto, colete evidências de ambos os lados da conexão:

• o DEFAULT_SERVERvalor exato, sem credenciais ou segredos;
• systemctl status kopano-servere entradas recentes do diário do servidor Kopano;
• as informações de propriedade do socket ou do ouvinte remoto;
• a versão do PHP e a extensão MAPI carregada no ambiente de execução do servidor web;
• O registro de erros do WebApp/PHP referente a uma tentativa de login falha.

A documentação do WebApp do Kopano informa que o registro de erros do PHP é habilitado por meio das configurações do PHP config.phpe alerta contra a exibição direta de erros, pois isso pode corromper as respostas JSON. Isso torna os logs do lado do servidor a melhor fonte de diagnóstico. Consulte as configurações oficiais de registro do WebApp antes de aumentar o nível de detalhamento.

Após identificar se a falha está relacionada à inicialização do Core, ao transporte, às permissões, ao PHP-MAPI ou à rede remota, aplique a correção mais simples que atenda a essa camada. Isso é mais confiável do que tratar "Não foi possível conectar ao Kopano Core" como um único erro com uma solução universal.