Matrix에서 브리지를 설정하는 방법: WhatsApp, Telegram 및 Discord

Matrix를 WhatsApp, Telegram 또는 Discord와 연동하려면 홈서버와 함께 호환되는 브리지 서비스를 실행하고, 해당 서비스를 Matrix 애플리케이션 서비스로 등록한 다음 외부 계정을 연결하거나 인증해야 합니다. 각 네트워크에는 고유한 브리지 구성 및 자격 증명이 필요합니다. 실행 중인 프로세스만으로는 방이 연동되었다고 볼 수 없습니다. 설정 후 양방향으로 메시지를 주고받으며 테스트하십시오.

이 가이드에서는 mautrix-whatsapp 및 mautrix-telegram 과 Discord 용 Matrix.org 프로젝트인 matrix-appservice-discord를 사용합니다 . 브리지는 Element의 스위치가 아니라 별도의 서버 측 프로그램입니다. Matrix 사양에서는 이러한 유형의 통합을 애플리케이션 서비스라고 부릅니다. 애플리케이션 서비스는 관련 홈서버 이벤트를 수신하고 등록된 네임스페이스 내에 사용자 또는 방을 생성할 수 있습니다. Matrix 기술 개요 및 애플리케이션 서비스 API 사양을 참조하십시오 .

브리지를 자체 호스팅해야 할까요, 아니면 공용 인스턴스를 사용해야 할까요?

자체 호스팅을 사용하면 브리지 실행 위치, 로그 및 자격 증명 저장 방식, 접속 가능 사용자 등을 직접 제어할 수 있습니다. 하지만 세 가지 서비스를 유지 관리하고, 업데이트하고, 데이터베이스를 보호하고, 연결 문제를 해결해야 한다는 의미이기도 합니다. 공용 브리지는 테스트 속도가 빠를 수 있지만, 가용성, 액세스 정책 및 데이터 처리는 운영자가 관리합니다. 인스턴스를 선택하기 전에 브리지의 최신 문서와 지원 자료를 확인하세요. 가용성 및 기능은 변경될 수 있습니다.

이러한 연결은 메시징 서비스에서 기본적으로 지원하는 기능과 동일하지 않습니다. 브리지 기능은 네트워크에 따라 다를 수 있으며, 음성/영상 통화, 반응, 수정, 스레드, 읽음 확인, 대화 기록 또는 그룹 관리 기능이 불완전할 수 있습니다. 중요한 대화를 옮기기 전에 커뮤니티에서 실제로 필요한 기능을 테스트해 보세요.

무엇을 설치하기 전에 무엇이 필요합니까?

• Matrix 홈서버는 애플리케이션 서비스를 지원하고 관리자가 해당 서비스를 등록할 수 있도록 합니다. 아래 예시에서는 Synapse를 사용하며, 다른 홈서버는 자체적인 등록 절차를 가지고 있습니다.
• 홈서버와 각 브리지 간의 도달 가능한 네트워크 경로. Docker에서 localhost컨테이너 내부는 해당 컨테이너 자체를 의미합니다. 홈서버가 다른 컨테이너에 접근해야 하는 경우에는 공유 Docker 네트워크와 브리지 서비스의 네트워크 이름을 사용하십시오.
• 각 브리지마다 별도의 구성 파일, 등록 파일, 영구 데이터 위치 및 비밀 저장소가 필요합니다. 지원되는 데이터베이스, 런타임 버전 및 컨테이너 이미지에 대해서는 현재 프로젝트 지침을 따르십시오. 요구 사항은 프로젝트마다 다르며 변경될 수 있습니다.
• WhatsApp의 경우, 연결하려는 계정이 있는 휴대전화가 필요합니다. Telegram의 경우, 공식 Telegram 클라이언트를 통해 이미 로그인된 계정이 필요합니다. Discord의 경우, Discord 애플리케이션/봇과 서버 소유자 또는 관리자의 권한이 필요합니다.

Synapse에 브리지를 등록하는 방법은 무엇인가요?

1. 브리지는 한 번에 하나씩 배포하십시오. 최신 릴리스와 샘플 구성을 시작으로, 해당 프로젝트 가이드에 따라 홈서버 주소, 공용 서버 이름, 브리지 리스너 주소, 데이터베이스 및 스토리지 경로를 설정하십시오. 서로 관련 없는 브리지 서비스 간에 데이터베이스를 공유하지 않도록 하십시오.
2. 등록 파일을 생성합니다. 브리지 설정 프로세스는 애플리케이션 서비스 ID와 인증 토큰이 포함된 등록 YAML 파일을 생성합니다. 이러한 토큰은 암호처럼 취급해야 합니다. 파일 권한을 제한하고, Git에 커밋하지 말고, 공개 채팅방, 스크린샷 또는 지원 게시물에 붙여넣지 마십시오.
3. Synapse에서 해당 파일을 볼 수 있도록 설정하십시오. Synapse 프로세스가 읽을 수 있는 위치에 등록 파일을 복사하거나 마운트하십시오. app_service_config_filesSynapse의 설정 파일에 해당 파일의 경로를 추가하십시오 homeserver.yaml. 각 브리지에 대해 별도의 목록 항목을 추가하고, 다른 서비스의 항목을 덮어쓰지 마십시오. Mautrix 앱 서비스 등록 가이드에서 이 과정을 설명하고 있으며, 등록 목록 변경 후 Synapse를 다시 시작해야 한다고 명시하고 있습니다.
4. Synapse 를 재시작하고 로그를 확인하십시오. 등록 변경 후 Synapse를 재시작한 다음 브리지를 시작하십시오. Synapse 시작에 실패하면 먼저 YAML 들여쓰기, 컨테이너 내 파일 경로 및 읽기 권한을 확인하십시오. 브리지가 시작되지만 연결할 수 없는 경우 홈서버 URL, 네트워크 경로, TLS 인증서 및 수신자 주소를 확인하십시오.

Docker 배포의 경우, 브리지에 구성된 애플리케이션 서비스 주소는 홈서버 컨테이너에서 접근 가능해야 합니다. Mautrix 초기 구성 노트에는 공유 네트워크에서 컨테이너 이름이 작동하는 경우와 작동 localhost하지 않는 경우가 있는 이유가 설명되어 있습니다. Discord 프로젝트에서도 자체 등록 워크플로 및 샘플 구성을 업스트림 README 파일에 문서화하고 있습니다 .

WhatsApp 계정을 어떻게 연결하나요?

mautrix-whatsapp이 등록되고 실행되면, 브리지 봇이 있는 비공개 Matrix 채팅방을 열고 메시지를 보내세요 login qr. 계정 소유자의 휴대폰에서 WhatsApp을 열고 '연결된 기기' 로 이동하여 브리지에서 제공하는 코드를 스캔하세요. 브리지 문서에는 전화번호 페어링 코드 옵션도 설명되어 있습니다. 설치된 버전에 따라 현재 지원되는 방법을 사용하세요. 로그인 코드나 QR 이미지를 공용 채팅방에 복사하지 마세요.

페어링하는 동안 휴대폰과 계정을 연결 가능한 상태로 유지하고, 포털 룸을 열기 전에 브리지에서 로그인 성공 여부를 확인하세요. 이 과정은 컴패니언 디바이스 방식의 세션을 통해 계정을 연결하는 것이며, 브리지를 공식 WhatsApp Business API 통합으로 전환하는 것은 아닙니다. WhatsApp의 기기 연결 방식은 변경될 수 있으므로, 최신 mautrix-whatsapp 인증 지침을 따르세요 . 브리지는 외부 서비스에서 연결된 기기에 제공하고 브리지에서 구현한 기록만 동기화할 수 있습니다.

텔레그램에 어떻게 연결하나요?

mautrix-telegram 봇과 비공개 채팅을 시작하세요. 이 브리지는 QR 코드 로그인과 이미 로그인한 텔레그램 클라이언트로 전송되는 6자리 로그인 코드를 지원하며, 새로운 텔레그램 계정을 생성하지는 않습니다. QR 코드 로그인을 사용하려면 휴대폰에서 텔레그램을 열고 설정 > 기기 > 데스크톱 기기 연결 로 이동한 다음 login qr브리지 봇으로 코드를 전송하고 스캔하세요. 텔레그램 계정에 2단계 인증이 활성화되어 있는 경우 봇의 안내에 따라 진행하세요.

기존에 생성된 계정을 사용하고 텔레그램의 로그인 규칙을 준수하세요. 브리지 관리자는 타사 클라이언트를 사용하여 생성된 새 계정을 텔레그램이 의심스러운 계정으로 간주할 수 있다고 경고합니다. 이는 플랫폼 측의 위험이며, Matrix 관리자가 완전히 해결할 수 있는 문제는 아닙니다. 로그인하기 전에 mautrix-telegram 인증 가이드를 검토하고 , 일회용 코드나 비밀번호는 봇의 비공개 채팅방 내에 보관하세요.

디스코드 설정은 어떻게 하나요?

matrix-appservice-discord 프로젝트는 Discord 애플리케이션과 봇을 사용합니다. Discord 개발자 포털 에서 애플리케이션을 생성하고 , 봇 사용자를 생성/구성한 다음, 프로젝트의 최신 샘플을 사용하여 브리지 구성에서 봇 자격 증명을 설정하세요. 봇 토큰은 노출하지 마세요. 브리지에 설명된 authorization-link 명령 또는 플로우를 실행한 다음, Discord 서버 소유자가 브리지에 필요한 권한만 부여하여 해당 서버에 대한 봇 권한을 승인하도록 하세요.

특정 채널에 접속하려면 Discord에서 지원하는 개발자 도구를 사용하여 서버 및 채널 ID를 확인하고, Matrix 측 브리지 봇을 Matrix 방으로 초대한 다음, 브리지에 문서화된 방 명령어를 사용하십시오. 상위 README 파일에는 예시 명령어가 나와 있으며 !discord bridge ServerID ChannelID, 링크를 완료하려면 관리자 승인이 필요할 수 있습니다. 예시의 ID를 사용하지 말고 실제 식별자로 대체하십시오. 또한 설치된 릴리스의 README 파일을 참조하여 명령어와 권한을 확인하십시오.

Discord는 특히 봇 권한과 서버 정책에 크게 의존합니다. 봇이 참여는 되지만 메시지가 전송되지 않는 경우, 봇이 해당 채널을 볼 수 있는지, 필요한 메시지 전송 권한이 부여되었는지, 그리고 브리지가 관리자 승인을 완료했는지 확인하세요. 해당 프로젝트는 README 파일에 베타 버전이라고 명시되어 있으므로, 모든 Discord 기능이 동일하게 구현되었다고 가정하기보다는 현재 프로젝트 상태와 지원되는 동작을 확인하는 것이 중요합니다.

다리가 제대로 작동하는지 어떻게 확인할 수 있나요?

먼저 소규모 비공개 테스트룸과 위험도가 낮은 채널을 사용하세요. Matrix에서 고유한 일반 텍스트 메시지를 보내고 원격 서비스에 메시지가 표시되는지 확인합니다. 그런 다음 원격 측에서 답장을 보내고 Matrix에 답장이 표시되는지 확인합니다. 사용 사례에 따라 발신자 표시, 답글 스레드, 첨부 파일, 수정 사항 및 반응을 개별적으로 확인하세요. 프로세스 상태가 녹색으로 표시되는 것은 프로그램이 실행 중임을 의미할 뿐이며, 로그인 성공, 봇의 채널 접근 권한 또는 룸과 채널 매핑의 정확성을 보장하는 것은 아닙니다.

테스트가 실패하면 메시지의 정확한 시간을 브리지 및 홈서버 로그와 비교하십시오. 로그를 공유하기 전에 액세스 토큰, 전화번호, Discord ID(민감한 정보인 경우) 및 연락처 이름을 삭제하십시오. 컨테이너 배포의 경우 등록 파일이 Synapse 내부에 마운트되었는지, 브리지 엔드포인트가 공유 네트워크에서 확인되는지, 방화벽이 구성된 리스너를 차단하지 않는지도 확인하십시오.

암호화와 개인정보 보호에 대해 무엇을 알아야 할까요?

애플리케이션 서비스는 구성된 네임스페이스와 룸에서 이벤트를 수신합니다. 암호화된 Matrix 룸이 모든 브리지에서 자동으로 읽을 수 있다고 가정하지 마십시오. 일부 Mautrix 브리지는 종단 간 암호화를 지원하며, 이는 의도적인 구성이 필요하고 자체적인 키 관리 요구 사항이 있습니다. Mautrix 종단 간 암호화 가이드를 참조하여 특정 브리지의 지원 여부를 확인하십시오. Discord 브리지의 암호화 기능은 다를 수 있습니다. 브리지가 룸의 암호화 모드를 처리할 수 없는 경우, 적절한 암호화되지 않은 테스트 룸을 사용하거나 지원이 문서화된 브리지를 선택하여 프로덕션 룸의 보안을 추측으로 약화시키지 마십시오.

마지막으로, 메시지 내용과 계정 자격 증명은 사용자가 운영하는 소프트웨어 또는 공용 브리지 운영자가 운영하는 소프트웨어를 통해 전달된다는 점을 기억하십시오. 브리지 봇 초대 권한을 제한하고, 데이터베이스와 백업을 보호하며, 토큰이 유출될 경우 즉시 교체하고, 브리지의 최신 개인정보 보호 및 보안 지침을 검토하십시오. 업그레이드 전에 상위 프로젝트 문서를 다시 확인하십시오. 구성 키, 로그인 흐름, 종속성 및 플랫폼 정책은 독립적으로 변경될 수 있습니다.

빠른 의사 결정 체크리스트

• 운영자와 액세스 정책을 신뢰할 수 있는 브리지 인스턴스를 선택하십시오.
• 모든 브리지를 개별적으로 등록하고 생성된 각 토큰을 보호하십시오.
• 배포 후 홈서버가 브리지 주소에 연결할 수 있는지 확인하십시오.
• WhatsApp/Telegram 계정을 비공개로 연결하고 Discord 봇에 서버 관리자 권한을 부여하세요.
• 양방향 메시지 테스트를 먼저 수행한 다음, 필요한 추가 기능만 테스트하세요.
• 중요하거나 필수적인 통신에 브리지를 사용하기 전에 암호화 지원 여부, 과거 이력 및 유지 관리 상태를 확인하십시오.