Mjolnir 봇을 사용하여 Matrix Room에서 관리자 권한을 설정하는 방법

Mjolnir는 Matrix 기반의 관리 봇으로, 공유 차단 정책 적용, 메시지 수정, 보호된 방 모니터링 등의 기능을 제공하며, 관리자가 개인 계정 없이도 조치를 취할 수 있도록 지원합니다. 안전한 설정은 봇 실행 위치, 봇에 명령을 내릴 수 있는 사용자, 그리고 각 보호된 방에서 봇이 부여받을 권한이라는 세 가지 요소에 달려 있습니다. 제어실은 비공개로 유지하고, 보호하려는 방만 보호하며, 문제 발생 시 봇을 사용하기 전에 권한을 반드시 확인하십시오.

이 가이드는 상위 프로젝트인 Mjolnir의 설정 및 관리자 문서와 Matrix 커뮤니티 관리자 지침(2026년 10월 6일 기준)을 따릅니다. 프로젝트 릴리스 페이지에는 검토 시점을 기준으로 v1.12.1이 최신 릴리스로 표시되어 있습니다. 컨테이너 태그 및 지원 옵션은 변경될 수 있으므로 설치 시 상위 프로젝트 릴리스 페이지와 구성 샘플을 다시 확인하십시오.

묠니르가 매트릭스 커뮤니티에 적합할까요?

Mjolnir는 관리자가 여러 방에서 관리 규칙을 공유하거나, 공통 정책 목록을 구독하거나, 반복적인 작업을 일관되게 적용해야 할 때 사용하세요. Matrix의 방 권한 설정에 따라 봇의 권한이 결정되며, Mjolnir가 방에 참여했다고 해서 자동으로 권한이 부여되는 것은 아닙니다. 일반적인 소규모 방 관리에는 내장된 방 관리 도구로도 충분할 수 있습니다. Mjolnir는 동일한 커뮤니티에서 여러 방을 운영하거나 통제된 공유 워크플로가 필요한 경우에 가장 유용합니다.

방 관리와 홈서버 관리는 별개의 권한 범위입니다. Mjolnir는 적절한 방 권한이 있으면 방 수준의 차단 및 게시물 삭제를 관리할 수 있습니다. 사용자 비활성화, 별칭 이동, 방 종료와 같은 서버 전체에 영향을 미치는 명령을 실행하려면 Mjolnir에게 Synapse 서버 관리자 권한이 필요합니다. 관리자가 이러한 작업에 특별히 필요한 경우가 아니라면 홈서버 관리자 권한을 부여하지 마십시오.

설치하기 전에 무엇을 준비해야 할까요?

봇 전용 Matrix 홈서버 계정(예: @mjolnir:example.org).
권한을 부여받은 관리자가 명령을 내리고 상태 메시지를 받을 수 있는 비공개 관리실입니다.
Mjolnir의 구성 및 상태를 저장하는 영구 디렉터리 또는 볼륨입니다.
암호화된 회의실을 위한 계획입니다. 현재 Mjolnir 구성은 네이티브 암호화를 지원하며, Pantalaimon은 별도의 사용 중단된 옵션으로 문서화되어 있습니다. 두 가지 방식을 동시에 활성화하지 마십시오.
사용 중인 계정이 많은 실제 운영 공간을 보호하기 전에 초대, 권한 및 목록 동작을 확인할 수 있는 테스트룸입니다.

Mjolnir는 어떻게 설치하나요?

상위 프로젝트 문서에는 Docker 및 자체 빌드 설치 방법이 나와 있습니다. 컨테이너를 이미 실행 중인 대부분의 관리자에게는 Docker Compose가 편리합니다. 대화형 터미널을 열어두지 않고도 봇을 재시작하고 로그를 표시할 수 있기 때문입니다. 프로젝트의 Docker 설정 지침을 따르고 , 유동적인 태그에 무기한 의존하는 대신 검토된 릴리스를 프로덕션 환경에 고정하세요 latest. 공식 이미지는 입니다 matrixdotorg/mjolnir.

컨테이너를 시작하기 전에 구성을 준비하십시오. Docker 공식 가이드에서는 구성 파일이 `/etc/config.js` 경로의 영구 데이터 디렉터리에 저장되어 있을 것으로 예상합니다 config/production.yaml. 해당 디렉터리는 관리자와 필요한 서비스만 읽을 수 있도록 유지하십시오. 파일에는 액세스 토큰이나 기타 로그인 자격 증명이 포함될 수 있습니다. 이러한 파일을 공개 저장소에 커밋하거나, 지원 게시판에 붙여넣거나, 로그에 포함하지 마십시오.

옵션 이름은 프로젝트의 현재 기본 설정과 주석을 기준으로 삼으세요. 최소한 홈서버 URL과 관리룸을 설정한 다음, 선택한 배포 환경에 맞게 인증 및 암호화를 구성해야 합니다. 토큰 기반 설정을 사용하는 경우 토큰을 비밀번호처럼 취급하세요. 상위 설정 가이드에서는 Element에서 별도의 브라우저 프로필을 통해 봇으로 로그인한 후 설정, 도움말 및 정보, 액세스 토큰 섹션을 열어 토큰을 얻는 방법을 설명합니다. 로그아웃하면 토큰이 무효화될 수 있으므로 로그아웃하지 말고 해당 브라우저 프로필을 닫으라고 경고합니다. 암호화된 관리룸의 경우, 관리룸에서 명령어를 사용하기 전에 Mjolnir의 암호화 지원을 활성화하고 테스트해야 합니다.

# Illustrative values only; use the exact keys and authentication method
# from the current upstream configuration sample. Never share real secrets.
homeserverUrl: https://matrix.example.org
managementRoom: '!privateRoomId:example.org'
accessToken: '[STORE A SECRET HERE, NOT IN PUBLIC]'

위 발췌 부분은 완전한 설정 내용이 아닙니다. 특히 암호화 및 로그인 설정은 기본 암호화를 사용할지 또는 선택 사항인 Pantalaimon 경로를 사용할지에 따라 달라집니다. 이전 블로그나 작성 파일을 복사하지 말고 최신 샘플을 참조하십시오. Mjolnir 설정 가이드에서는 응답 지연 시간을 줄이기 위해 봇을 홈서버 네트워크와 가까운 위치에 두는 것을 권장합니다.

관리자실은 어떻게 보안해야 할까요?

신뢰할 수 있는 운영진을 위한 방을 만들고, 봇 계정을 초대하고, 운영진 전용으로 비공개 설정하세요. 방 ID 또는 별칭은 에 입력합니다 managementRoom. 현재 설정에서는 이 방을 명령어 발신처로 지정하고, 해당 방에서 명령어를 보낼 수 있는 사람은 누구나 Mjolnir를 제어할 수 있다고 경고합니다. 따라서 명령어별로 세분화된 접근 제어 기능은 제공하지 않습니다. 그러므로 멤버십 검토가 필수적입니다. 이전 운영진은 즉시 해임하고, 봇 제어실을 일반 커뮤니티 채팅방으로 사용하지 마세요.

관리실에는 암호화를 권장합니다. 암호화를 적용한 경우, Mjolnir가 설정된 암호화 방식으로 메시지를 읽고 응답할 수 있는지 확인하십시오. 암호화된 방에 참여했지만 이벤트를 해독할 수 없는 봇은 명령을 무시하면서도 온라인 상태로 표시될 수 있습니다. 이 문제를 진단할 때는 방 암호화를 해제하는 것보다 상위 시스템의 암호화 구성 및 로그를 활용하는 것이 좋습니다.

묠니르에게 어떤 권한을 부여해야 할까요?

봇을 보호해야 할 각 방에 초대하고, 원하는 관리 작업을 수행할 수 있도록 충분한 방 권한을 부여하세요. Matrix는 차단, 강퇴, 다른 사용자의 이벤트 삭제, 방 상태 변경 등의 작업에 방 권한 레벨을 사용합니다. 필요한 값은 방의 권한 레벨 이벤트에서 정의됩니다. 차단, 강퇴, 삭제에 대한 Matrix의 기본값은 일반적으로 지정하지 않으면 50이지만, 각 방에서 변경할 수 있습니다.

Matrix 커뮤니티 가이드라인에서는 Mjolnir 계정의 일반적인 설정으로 권한 레벨 100을 권장하며, 이를 통해 관리자 권한을 행사할 수 있다고 설명합니다. 하지만 이 레벨은 상당히 높은 수준입니다. Mjolnir 계정을 효과적으로 제어할 수 있는 사람은 누구나 보호된 방에서 해당 권한을 가지게 되며, 봇이 사실상 방의 소유자가 될 수도 있습니다. 각 방의 권한 레벨을 검토하여 봇에게 필요한 작업은 허용하면서 불필요한 권한은 제한하는 레벨을 선택하십시오. 일반적인 방 관리에는 홈서버 관리자 권한을 부여하지 마십시오.

Element에서는 방의 멤버 패널에서 봇을 초대하거나 `mjolnir.com`과 같은 초대 명령어를 입력하여 봇을 초대할 수 있습니다 /invite @mjolnir:example.org. 봇이 참여하면 방의 멤버 목록에서 봇의 역할을 조정하세요. 보호해야 할 모든 방에 대해 이 과정을 반복합니다. Mjolnir는 Matrix의 분산형 방별 권한 모델에 따라 자신이 참여하지 않은 방은 보호할 수 없습니다.

차단 목록을 만들고 보호된 방을 추가하는 방법은 무엇인가요?

봇이 시작되어 관리실에 상태를 게시하면, 관리실에서 정책 목록을 생성하세요. Mjolnir의 상위 프로젝트 빠른 시작 가이드에서 이 예시를 사용합니다.

!mjolnir list create COC code-of-conduct-ban-list
!mjolnir default COC
!mjolnir rooms add #community:example.org
!mjolnir verify
!mjolnir status

첫 번째 명령어는 단축 코드 `<b>`를 사용하여 차단 목록 방을 생성합니다 COC. 방을 생성한 사람은 초대되어 방의 공개 여부를 관리할 수 있습니다. 두 번째 명령어는 해당 목록을 이후 관리 명령어의 기본 목록으로 선택합니다. 세 번째 명령어는 Mjolnir의 보호된 방 목록에 방을 추가합니다. `verification` 명령어는 봇이 모든 보호된 방에서 필요한 권한을 가지고 있는지 확인하고, `status` 명령어는 봇이 예상대로 실행 중인지 확인합니다. !mjolnir help설치된 버전에서 사용 가능한 명령어 구문을 보려면 `sudo`를 사용하세요.

정책 목록은 내부 메모가 포함되어 있거나 팀에서만 사용할 목적으로 작성된 경우 비공개로 유지하세요. 다른 커뮤니티에서 규칙을 검색하고 구독할 수 있도록 하려면 공개로 설정해야 합니다. Mjolnir의 규칙은 목록 간에 누적되므로 감시 목록을 사용하기 전에 검토하세요. 다른 목록에서 중복된 규칙을 제거하더라도 한 목록에서 사용자 또는 서버와 계속 일치할 수 있습니다.

실제 사고 상황에서 사용하기 전에 무엇을 테스트해야 할까요?

봇이 설정된 관리실에 시작 및 상태 메시지를 게시하는지 확인하십시오.
!mjolnir verify테스트룸에 초대하고 선택한 역할을 부여한 후 실행하세요 .
실행 !mjolnir rooms후 의도한 방이 나타나는지, 관련 없는 방이 포함되지 않는지 확인하십시오.
본인이 이해하는 보호 기능만 검토 !mjolnir protections하고 활성화하십시오. 자동 보호 기능은 정상적인 사용자에게 영향을 미칠 수 있습니다.
팀의 차단, 차단 해제 및 정보 삭제 절차를 실제 구성원에게 적용하기 전에 테스트 계정과 임시 방을 사용하여 유효성을 검사하십시오.
봇이 명령을 놓치거나 권한 누락을 보고하는 경우 컨테이너 로그와 Mjolnir의 관리실 메시지를 확인하십시오.

실제 커뮤니티 회원을 차단하거나 라이브 서버에서 와일드카드를 사용하여 테스트하지 마십시오. 와일드카드 차단은 많은 사용자에게 영향을 미칠 수 있으며, 현재 기본 설정에서는 와일드카드 차단에 추가 확인 플래그가 필요합니다. 자동 보호 기능을 활성화하기 전에 관리자 가이드를 읽고, 영향력이 큰 조치를 승인할 수 있는 사람을 명시하십시오.

흔히 발생하는 설치 오류는 무엇인가요?

편의를 위해 봇 서버 관리자 권한을 부여합니다. 일반적으로 방 수준의 관리에는 Synapse 관리자 권한이 아닌 방 운영 권한이 필요합니다.
관리실에 누구나 접근할 수 있도록 개방합니다. 명령을 내릴 수 있는 모든 구성원에게 봇의 관리 제어 권한을 부여합니다.
보호된 방의 권한을 잊어버리는 경우: 봇의 권한 수준이 너무 낮으면 봇이 온라인 상태이더라도 차단이나 콘텐츠 삭제에 실패할 수 있습니다.
암호화 설정을 하지 않고 암호화된 방을 사용하는 경우: 단순히 회원 자격만으로는 봇이 암호화된 명령어를 읽을 수 없습니다.
이전 설정 레시피를 복사하는 경우: Mjolnir의 구성 및 암호화 지원 기능이 발전했으므로 현재 기본 샘플 및 설정 문서를 사용하십시오.
감시 목록에서 삭제되면 모든 금지 조치가 해제된다고 가정하더라도, 다른 감시 목록에서는 여전히 동일한 규칙이 적용될 수 있습니다.

현재 정보를 어디에서 확인할 수 있나요?

먼저 Mjolnir 설정 가이드 , 관리자 가이드 및 릴리스 내역을 참조하십시오 . 방 권한에 대해서는 Matrix 커뮤니티 관리자 가이드 와 Matrix 방 권한 수준 사양을 참조하십시오 . 정확한 설치 명령 및 암호화 설정은 홈 서버, 컨테이너 설정 및 Mjolnir 릴리스에 따라 다릅니다. 이러한 상위 참조 자료의 지침이 변경될 경우 해당 자료를 우선적으로 참조하십시오.