Conduit을 사용하여 Raspberry Pi 4에 Matrix 서버를 설정하는 방법

라즈베리 파이 4는 가정, 개인 그룹 또는 연구실에서 사용하기에 적합한 소형 Matrix 홈서버이며, Conduit는 경량 하드웨어를 염두에 두고 설계되었습니다. Matrix는 분산 통신을 위한 개방형 프로토콜입니다. 사용자는 계정과 방 데이터가 저장된 홈서버 에 연결하고 , 연합 기능을 통해 해당 홈서버는 다른 Matrix 서버와 이벤트를 교환할 수 있습니다.

이 가이드에서는 Docker 환경에서 Conduit를 사용하고, HTTPS 연결을 위해 NGINX를 앞에 두고 사용합니다. 이를 통해 Matrix 서비스를 Raspberry Pi에 격리하면서 공용 웹 포트만 노출할 수 있습니다. 본 가이드의 지침은 2026년 10월 기준으로 제공된 Conduit, Matrix, Raspberry Pi, Docker 및 NGINX 문서를 기준으로 검증되었습니다. 먼저 중요한 제한 사항을 알려드립니다. Conduit는 아직 베타 버전 이므로 Matrix의 일부 기능이나 이전 버전의 룸이 안정적인 Synapse 환경에서와 동일하게 작동하지 않을 수 있다는 점을 감수할 수 있는 사용자에게 적합합니다. 중요한 서비스에 Conduit를 사용하기 전에 공식 Conduit 프로젝트 문서를 확인하시기 바랍니다 .

1. 설치하기 전에 먼저 설치 방법을 이해하십시오.

최종 경로는 간단합니다. Element와 같은 Matrix 클라이언트가 연결하면 https://matrix.example.comNGINX가 TLS를 종료하고 요청을 Raspberry Pi의 Conduit로 전달합니다. Conduit는 데이터베이스를 영구 Docker 스토리지에 저장합니다. 페더레이션이 활성화된 경우 다른 홈 서버도 동일한 공용 HTTPS 엔드포인트에 접근할 수 있습니다.

Matrix 서버를 장기간 사용하려면 Raspberry Pi 4, 안정적인 전원 공급 장치, microSD 카드 또는 SSD, 그리고 64비트 운영 체제가 필요합니다. Matrix는 데이터베이스와 미디어 데이터를 지속적으로 기록하기 때문에 장기간 사용할 서버에는 SSD를 사용하는 것이 좋습니다. 또한, 서버를 공용 인터넷에서 접속할 수 있도록 하려면 도메인 이름도 필요합니다.

2026년 9월 15일 현재, 최신 Raspberry Pi OS 64비트 버전은 Debian 13 “Trixie”를 기반으로 하며, Raspberry Pi 4용 Raspberry Pi OS Lite도 제공됩니다. 공식 Raspberry Pi OS 다운로드 페이지를 참조하세요 . 이 서버에는 불필요한 데스크톱 환경을 제공하지 않는 Lite 버전이 적합합니다.

Matrix 서버 이름을 신중하게 선택하세요.

이 가이드에서 서버 이름은 입니다 matrix.example.com. 결과로 생성되는 Matrix 사용자 ID는 와 같은 형식입니다 @alice:matrix.example.com. 이 이름을 장기적인 ID로 사용하십시오. Matrix ID와 페더레이션 참조에는 서버 이름이 포함되므로 나중에 서버 이름을 변경하는 것은 단순히 웹 호스트 이름을 바꾸는 것과는 다릅니다.

2. 라즈베리 파이 OS를 설치하고 파이를 업데이트합니다.

Raspberry Pi Imager를 사용하여 Raspberry Pi OS Lite 64비트 버전을 SD 카드 또는 SSD에 기록하고, 헤드리스 설치를 원하는 경우 이미징 중에 SSH를 활성화한 다음 Pi를 부팅합니다. 64비트 ARM 시스템인지 확인하십시오.

uname -m
cat /etc/os-release

uname -m일반적으로 다음과 같은 오류가 발생합니다 aarch64. 그런 다음 최신 업데이트를 설치하세요.

sudo apt update
sudo apt full-upgrade -y
sudo reboot

3. Docker Engine 및 Compose를 설치합니다.

Docker 문서에 따르면 64비트 Raspberry Pi OS 사용자는 기존의 32비트 Raspberry Pi OS 경로 대신 지원되는 Debian ARM64 패키지를 사용해야 합니다. 가장 정확한 절차는 Debian용 Docker Engine 페이지 에 나와 있습니다 . 다음 저장소 설정은 해당 접근 방식을 따릅니다.

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg   -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io   docker-buildx-plugin docker-compose-plugin

sudo docker run --rm hello-world

마지막 명령이 Docker의 "hello-world" 확인 메시지를 출력하면 컨테이너 런타임이 정상적으로 작동하는 것입니다. sudo docker이후 가이드의 나머지 부분에서도 해당 컨테이너를 계속 사용할 수 있습니다. 계정을 docker그룹에 추가하는 것은 선택 사항이지만, Docker 그룹 멤버십을 통해 호스트에 대한 루트 수준의 제어 권한을 얻게 된다는 점을 기억하세요.

4. 도관 구성 생성

Conduit는 TOML 파일 또는 환경 변수를 사용하여 구성할 수 있습니다. 공식 Conduit 구성 참조에서는server_name , database_backend, 및 를 database_path필수 필드로 나열 하고 RocksDB 사용을 권장합니다.

작업 디렉토리를 생성하세요:

sudo mkdir -p /opt/conduit
sudo chown "$USER":"$USER" /opt/conduit
cd /opt/conduit
nano conduit.toml

다음 초기 구성을 사용하고 호스트 이름과 등록 토큰을 교체하십시오.

[global]
server_name = "matrix.example.com"
database_backend = "rocksdb"
database_path = "/var/lib/matrix-conduit/"
address = "0.0.0.0"
port = 6167

allow_registration = true
registration_token = "replace-with-a-long-random-secret"
allow_federation = true
trusted_servers = ["matrix.org"]

왜 0.0.0.0여기일까요? 컨테이너 내부에서 Conduit는 Docker가 접근할 수 있도록 컨테이너 인터페이스에서 수신 대기해야 합니다. 호스트 측 포트는 여전히 특정 포트에만 바인딩되므로 127.0.0.16167번 포트는 인터넷에 직접 노출되지 않습니다.

5. Docker Compose를 사용하여 Conduit 실행

만들다 /opt/conduit/docker-compose.yml:

services:
  conduit:
    image: registry.gitlab.com/famedly/conduit/matrix-conduit:latest
    container_name: matrix-conduit
    restart: unless-stopped
    ports:
      - "127.0.0.1:6167:6167"
    volumes:
      - ./conduit.toml:/etc/conduit.toml:ro
      - conduit-data:/var/lib/matrix-conduit/
    environment:
      CONDUIT_CONFIG: /etc/conduit.toml

volumes:
  conduit-data:

GitLab 레지스트리의 안정적인 이미지는 Conduit Docker 공식 문서 에서 권장하는 이미지입니다 . 임의의 튜토리얼에서 오래된 이미지 태그를 복사하지 마시고, 공식 레지스트리를 이용하고 업그레이드 전에 릴리스 노트를 검토하십시오.

서비스를 시작하고 점검하십시오:

cd /opt/conduit
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=100 conduit

Up컨테이너가 반복적인 재시작 없이 실행 상태를 유지하도록 하려면 NGINX를 구성하기 전에 로컬 API를 확인하십시오.

curl http://127.0.0.1:6167/_matrix/client/versions

6. DNS를 라즈베리 파이로 지정하고 NGINX를 Conduit 앞에 배치합니다.

공용 IPv4 주소를 가리키는 A레코드를 생성하세요 . 레코드를 게시할 때는 IPv6가 실제로 Raspberry Pi에 도달하는지 확인해야 합니다. IPv6 레코드가 잘못되면 IPv4는 정상적으로 작동하더라도 클라이언트가 작동하지 않을 수 있습니다.matrix.example.comAAAA

일반 가정용 공유기에서는 TCP 포트 80과 443을 라즈베리 파이로 포트 포워딩하세요. 인터넷 서비스 제공업체(ISP)에서 캐리어급 NAT(CGNAT)를 사용하는 경우 일반적인 인바운드 포트 포워딩이 작동하지 않을 수 있습니다. 이 경우 공용 IP 주소, VPS/리버스 터널링 구성 또는 다른 호스팅 방식이 필요합니다.

NGINX를 설치하세요:

sudo apt install -y nginx

만들다 /etc/nginx/sites-available/matrix:

server {
    listen 80;
    server_name matrix.example.com;

    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:6167;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

NGINX의 공식 리버스 프록시 가이드 문서 proxy_pass와 여기에 사용된 전달 헤더를 참조하십시오.

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/matrix
sudo nginx -t
sudo systemctl reload nginx

7. HTTPS 및 Matrix 검색을 활성화합니다.

Matrix를 일반적인 공개 환경에 배포하려면 유효한 HTTPS가 필요합니다. DNS가 Raspberry Pi로 확인되고 80번 포트에 접근 가능한 경우에만 인증서를 발급받으세요. Debian Trixie는 Certbot 패키지를 제공하며, Certbot 프로젝트는 certbot.eff.org 에서 플랫폼별 최신 지침을 게시하고 있습니다 .

일반적인 Debian/NGINX 경로는 다음과 같습니다.

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d matrix.example.com

Certbot이 NGINX 가상 호스트를 업데이트한 후 구성을 다시 테스트하십시오.

sudo nginx -t
sudo systemctl reload nginx

이 가이드에서는 Matrix 서버 이름과 공용 엔드포인트에 동일한 호스트 이름을 사용하므로 Conduit는 /.well-known리버스 프록시를 통해 Matrix 검색 경로에 응답할 수 있습니다. Matrix 사양은 클라이언트와 다른 서버가 올바른 홈 서버 URL을 검색할 수 있도록 이러한 엔드포인트를 정의합니다. Matrix 클라이언트-서버 사양을 참조하십시오 .

8. 첫 번째 계정을 생성한 다음 서버를 인증하세요.

Conduit의 Docker 문서에 따르면 새 홈서버에 처음 생성된 계정이 관리자가 됩니다. 등록 토큰을 지원하는 Matrix 클라이언트를 열고 사용자 지정 홈서버를 선택한 다음 다음 명령어를 입력하세요.

https://matrix.example.com

에서 받은 토큰을 사용하여 첫 번째 계정을 등록하세요 conduit.toml. 서비스를 온라인 상태로 전환한 직후에 이 작업을 수행해야 합니다. 더 이상 계정 등록을 원하지 않는 경우, 구성을 수정하여 해당 설정을 적용 allow_registration = false하고 컨테이너를 재시작하세요.

cd /opt/conduit
sudo docker compose restart conduit

이제 도메인에 접속할 수 있는 모든 컴퓨터에서 다음 세 가지 검사를 실행하십시오.

curl https://matrix.example.com/_matrix/client/versions

curl https://matrix.example.com/.well-known/matrix/client

curl https://matrix.example.com/.well-known/matrix/server

첫 번째 요청은 지원되는 Matrix 클라이언트 API 버전을 설명하는 JSON을 반환해야 합니다. 잘 알려진 요청은 유효한 JSON 검색 정보를 반환해야 합니다. 페더레이션의 경우 Matrix 페더레이션 테스터를 사용하여 새 계정으로 페더레이션된 방에 참여해 보세요.

라즈베리 파이 매트릭스 서버 작동을 방해하는 일반적인 오류

• 불필요하게 32비트 운영체제를 사용하지 마세요. 라즈베리 파이 4의 경우, 64비트 라즈베리 파이 OS와 Docker에서 지원하는 Debian ARM64 패키지를 사용하십시오.
• Conduit를 직접 노출하려면127.0.0.1 호스트에서 6167 포트를 바인딩된 상태로 유지하고 NGINX를 통해 HTTPS를 노출하십시오.
• 등록을 보호 장치 없이 열어두는 경우: 초기 설정 시 강력한 등록 토큰을 사용하고, 필요하지 않을 경우 등록 기능을 비활성화하십시오.
• 잘못된 DNS 레코드 게시: IPv4 및 IPv6 레코드를 모두 게시하는 경우 두 레코드 모두 정상적으로 작동하는 엔드포인트를 가리켜야 합니다.
• 라우터 또는 방화벽 규칙을 잊어버린 경우: 올바른 컨테이너를 사용하더라도 차단된 인바운드 TCP 80/443 포트를 해결할 수는 없습니다.
• 메시징과 음성 통화가 동일하다고 가정할 때, Matrix 메시징은 통화가 실패하더라도 작동할 수 있습니다. Conduit의 문서에 따르면 음성 통신에는 Coturn과 같은 TURN 서버가 필요합니다.
• 백업 건너뛰기: Conduit FAQ에서는 적절한 파일 시스템 스냅샷을 사용하지 않는 한, 데이터베이스를 일반 파일 시스템 복사본으로 만들기 전에 Conduit를 중지할 것을 권장합니다. 업그레이드하기 전에 Docker 볼륨과 구성을 백업하십시오.

성공적인 설치의 모습

다음 조건을 모두 충족하면 작업이 완료된 것입니다. Conduit 컨테이너가 재부팅 후에도 계속 실행되고, https://matrix.example.com/_matrix/client/versionsJSON 형식의 응답을 반환하며, Matrix 클라이언트가 사용자 지정 홈서버에 등록하거나 로그인할 수 있고, 계정이 방을 만들고 메시지를 보낼 수 있으며, 연동 기능이 활성화된 경우 연동 테스터가 서버에 접속할 수 있고 사용자가 다른 홈서버의 계정과 통신할 수 있어야 합니다.

소규모 라즈베리 파이 배포 환경에서는 이것이 관리의 끝이 아니라 깔끔한 기본 설정 단계라고 볼 수 있습니다. 사용 가능한 저장 공간을 모니터링하고, 라즈베리 파이 OS와 Docker에 최신 패치를 적용하고, 데이터베이스를 백업하고, 추가 기능을 활성화하기 전에 Conduit 공식 문서를 읽어보세요 . Conduit는 라즈베리 파이급 하드웨어에 적합한 가볍고 매력적인 옵션이지만, 베타 버전이라는 점은 단순한 참고 사항이 아니라 실제 운영 과정에서 고려해야 할 중요한 요소입니다.