가이드

작성자 Matt Connor 2026-08-21 · 업데이트됨 2026-10-06

VPS에 Flarum 설치 및 PHP 포럼 서버 구축 가이드

Q: 메인 페이지는 정상인데 게시글 링크에서 404 오류가 발생하는 이유는 무엇입니까?

nginx 서버 블록에 include /srv/flarum/.nginx.conf; 설정이 누락되었기 때문입니다. Flarum은 /d/1-hello-world와 같은 URL을 PHP 내부에서 처리하며, 해당 경로는 디스크상의 실제 파일이 아닙니다. 스니펫의 try_files $uri $uri/ /index.php?$query_string 규칙이 없으면 nginx는 d이라는 디렉터리를 찾다가 실패하고, PHP를 호출하지 않은 채 자체적으로 404 오류를 반환합니다. Apache의 경우 블록에서 AllowOverride All을 설정하지 않으면 public/.htaccess이 무시되어 동일한 라우팅 문제가 발생합니다.

Q: HTTPS를 활성화한 후 포럼의 스타일이 모두 깨지는 이유는 무엇입니까?

Flarum은 설치 시 사용한 주소를 기반으로 config.php에 기본 URL을 저장합니다. 일반 HTTP로 설치했다면 Flarum은 계속해서 http:// 형태의 에셋 URL을 생성하며, 브라우저는 이를 HTTPS 페이지 내의 혼합 콘텐츠(mixed content)로 간주하여 차단하므로 스타일이 적용되지 않은 텍스트만 표시됩니다. /srv/flarum/config.php 파일의 url 키를 https:// 주소로 수정하고, 파일 소유자 계정으로 php flarum cache:clear을 실행하십시오.

Q: 가입 확인 이메일을 아무도 받지 못하는 이유는 무엇입니까?

먼저 메일 드라이버를 확인하십시오. mail 드라이버는 로컬 sendmail 바이너리가 필요한데, 새로 설치한 Ubuntu VPS에는 이 기능이 없습니다. 또한 log 드라이버는 storage/logs/에 로그만 기록할 뿐 실제 메일을 발송하지 않습니다. smtp으로 변경하고, 대부분의 공급자가 아웃바운드 25번 포트를 차단하므로 587번 포트와 tls 암호화를 사용한 뒤 Send Test Mail을 누르십시오. 로그상으로는 발송이 성공했으나 메일이 도착하지 않는다면 설정 문제가 아니라 도메인 신뢰도 문제입니다. 발송 도메인에 대한 SPF 및 DKIM 레코드를 게시하십시오.

Ubuntu 24.04 환경에서 PHP 8.3과 MariaDB를 사용하여 Flarum 1.8을 설치하는 방법을 설명합니다. /public 디렉토리 설정과 TLS 적용, Composer를 이용한 확장 기능 관리 및 메일 서버 설정 시 발생하는 오류 해결법을 상세히 정리했습니다.

PHP와 MariaDB를 사용하여 VPS에 Flarum 설치하기

VPS에 Flarum을 설치하면 Docker, Ruby, 별도의 작업 실행기 없이 PHP와 MariaDB 위에서 동작하는 포럼을 구축할 수 있습니다. 이것이 바로 Flarum을 선택하는 이유입니다. VPS에 Discourse 설치하기는 Ruby, PostgreSQL, Redis, 백그라운드 워커를 포함한 Docker 스택을 의미하며, 백업이나 메일 서비스를 추가하기 전에도 최소 2 GB의 RAM이 필요합니다. Discourse는 하루에 수천 개의 게시물이 올라오는 활발한 커뮤니티에서 그만한 자원 점유의 가치를 증명합니다. 수백 명 규모의 포럼에서는 매달 비용을 지불하면서도 사용하지 않는 과도한 장비일 뿐입니다. Flarum은 이미 운영 중인 PHP 스택 내에 포함될 수 있으므로, nginx와 MariaDB가 설치된 1 GB VPS라면 다른 서비스와 함께 호스팅할 수 있습니다. 아직 선택의 여지가 있다면, 자체 호스팅 포럼 소프트웨어 비교에서 나머지 선택지들을 확인할 수 있습니다.

이 가이드는 Flarum 1.x 버전, 현재 기준 1.8 시리즈 설치를 다룹니다. 2026년 8월 기준으로 Flarum 2.0은 여전히 릴리스 후보(release candidate) 상태이므로, 다른 사용자들이 이용하는 포럼을 운영하려면 1.8 버전을 사용하는 것이 좋습니다. 여기서는 핵심 버전보다 확장 기능이 더 중요하며, 대부분의 확장 기능 개발자는 아직 2.0으로 이전하지 않았습니다.

Flarum 1.8 서버 요구 사항

Flarum의 공식 요구 사항은 PHP 7.3 이상, MySQL 5.6+ 또는 MariaDB 10.0.5+ 버전이며, 웹 서버는 nginx 또는 Apache와 mod_rewrite가 필요합니다. Ubuntu 24.04는 PHP 8.3과 MariaDB 10.11을 기본으로 제공하므로, 별도의 서드 파티 저장소 없이도 배포판 패키지만으로 요구 사항을 충족합니다. Flarum이 요구하는 PHP 확장 모듈은 curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer, zip입니다. 또한 셸 접근 권한이 필수입니다. Flarum의 모든 확장 기능은 Composer 패키지이며, Composer를 실행하지 않고는 기능을 추가할 방법이 없기 때문입니다.

Flarum은 일반적인 PHP 애플리케이션입니다. 만약 이미 Ubuntu 24.04에서 LAMP 스택을 운영 중이라면, 다음 두 섹션의 대부분은 이미 설치된 상태이므로 데이터베이스 설정 단계로 바로 넘어가도 됩니다.

Flarum이 요구하는 PHP 및 확장 모듈 설치

sudo apt update
sudo apt install -y nginx mariadb-server composer
sudo apt install -y php8.3-fpm php8.3-cli php8.3-curl php8.3-gd php8.3-mbstring php8.3-mysql php8.3-xml php8.3-zip
php -m | grep -E 'curl|dom|gd|mbstring|pdo_mysql|zip'
composer --version

패키지 이름이 Flarum의 목록과 일대일로 대응하지 않습니다. dom 확장 모듈은 php8.3-xml 내부에 포함되어 있으며, fileinfo, json, openssl 및 tokenizer은 Ubuntu의 PHP 8.3에 내장되어 있으므로 별도로 설치할 패키지가 없습니다. grep 명령을 실행하면 6줄이 출력되어야 하며, composer --version 명령은 2.x 릴리스를 보고해야 합니다. 누락된 확장 모듈은 지금 해결해야 합니다. Composer는 해당 모듈 없이는 Flarum 설치를 거부하며, 오류 메시지에 필요한 확장 모듈 이름이 표시되기 때문입니다.

  Problem 1
    - flarum/core[v1.8.0, ..., v1.8.17] require ext-gd * -> it is missing from your system.
      Install or enable PHP's gd extension.

명령줄 PHP와 FastCGI 프로세스 관리자(PHP-FPM)의 버전이 동일한지 확인하십시오. Composer는 명령줄 바이너리에서 실행되고 포럼은 FPM에서 실행되므로, php -v와 sudo php-fpm8.3 -v의 버전이 일치해야 합니다. 서드 파티 저장소에서 여러 PHP 버전을 설치한 환경에서는 버전이 서로 달라질 수 있으며, 이 경우 한 버전에 설치한 확장 모듈이 다른 버전에서는 보이지 않게 됩니다.

데이터베이스 및 전용 데이터베이스 사용자 생성

sudo mariadb-secure-installation
sudo mariadb

CREATE DATABASE flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'flarum'@'localhost' IDENTIFIED BY 'use-a-long-random-password';
GRANT ALL PRIVILEGES ON flarum.* TO 'flarum'@'localhost';
FLUSH PRIVILEGES;
EXIT;

root 대신 Flarum 전용 데이터베이스 사용자를 생성하십시오. 권한은 flarum.*에만 부여되므로, 직접 작성하지 않은 확장 기능에서 SQL 인젝션 취약점이 발생하더라도 다른 데이터베이스를 읽을 수 없습니다. 문자 집합 설정도 중요합니다. utf8mb4은 이모지와 비라틴 문자를 올바르게 저장하지만, MySQL의 구형 utf8는 3바이트 인코딩이므로 4바이트 문자가 나타나면 게시글이 잘릴 수 있습니다. 진행하기 전에 사용자가 정상적으로 작동하는지 확인하십시오.

mariadb -u flarum -p flarum -e 'SELECT DATABASE();'

명령을 실행하면 flarum가 출력되어야 합니다. ERROR 1045 (28000): Access denied for user 'flarum'@'localhost'이 출력된다면 비밀번호가 일치하지 않거나, 사용자가 localhost이 아닌 다른 호스트용으로 생성되었음을 의미합니다.

Composer를 사용하여 VPS에 Flarum 1.8 버전 설치하기

먼저 소스 코드를 소유할 시스템 사용자를 생성합니다. root 권한으로 Composer를 실행하면 vendor/ 및 storage/ 디렉터리에 root 소유의 파일이 생성됩니다. 이 경우 나중에 PHP가 자체 캐시를 기록할 수 없어 포럼이 모든 요청에 대해 500 오류를 반환하게 됩니다.

sudo useradd --system --home-dir /srv/flarum --shell /bin/bash flarum
sudo install -d -o flarum -g flarum -m 755 /srv/flarum
sudo -iu flarum

마지막 명령어를 실행하면 flarum 사용자의 셸로 전환되며, 현재 경로는 /srv/flarum가 됩니다. 이 가이드의 끝까지 모든 명령어는 sudo으로 시작하는 경우를 제외하고 해당 사용자 권한으로 실행합니다.

composer create-project flarum/flarum:^1.8.0 .

^1.8.0 제약 조건은 버전을 고정하는 역할을 합니다. 이 설정은 1.8.x 패치 릴리스는 허용하되 2.0 버전은 거부하는데, 2.0이 릴리스 후보(release candidate) 단계인 동안에는 이 방식이 권장됩니다. Composer는 스켈레톤을 다운로드하고 flarum/core 및 그 의존성 패키지를 해결한 뒤, public/, storage/, vendor/, composer.json 및 flarum 명령줄 스크립트를 생성합니다.

소규모 VPS에서는 이 단계에서 문제가 자주 발생하며, 두 가지 서로 다른 실패 유형이 동일한 증상을 보입니다. PHP Fatal error: Allowed memory size of 134217728 bytes exhausted은 PHP 자체의 memory_limit이며, 명령어 앞에 COMPOSER_MEMORY_LIMIT=-1을 추가하면 해당 실행에 한해 메모리 제한이 해제됩니다. PHP 오류 메시지 없이 Killed가 단독으로 출력되는 경우는 커널의 OOM(out-of-memory) 킬러가 작동한 것이며, 이는 dmesg | tail 명령어로 확인할 수 있습니다. 이 경우 시스템의 RAM이 실제로 부족한 상태이므로 스왑(swap)을 추가해야 합니다. PHP 메모리 제한을 높이는 것은 오히려 상황을 악화시킬 수 있는데, 이는 PHP가 커널이 개입하기 전에 더 많은 메모리를 요구하게 만들기 때문입니다.

왜 /public 디렉터리만 웹에 노출해야 하는가

프로젝트 루트에는 데이터베이스 비밀번호가 평문으로 포함된 config.php, 모든 의존성 패키지 정보가 담긴 vendor/, 그리고 로그와 캐시된 세션이 저장되는 storage/이 존재합니다. 이러한 파일들은 외부 인터넷에 노출되어서는 안 됩니다. Flarum은 웹에서 접근 가능한 모든 파일을 하나의 하위 디렉터리인 public/에 보관하며, 여기에는 index.php, assets/ 폴더 및 기타 필수 파일만 포함됩니다. 웹 서버의 루트를 /srv/flarum/public로 설정하면, 별도의 규칙을 기억할 필요 없이 구조적으로 나머지 디렉터리에 대한 HTTP 접근이 차단됩니다.

반대로 루트를 /srv/flarum으로 설정하면 심각한 보안 문제가 발생합니다. /config.php를 요청하면 PHP가 파일을 실행하여 배열만 반환하므로 유용한 정보를 얻을 수 없습니다. 그러나 /storage/logs/flarum.log는 공격자에게 스택 트레이스와 데이터베이스 오류 정보를 그대로 노출하며, /composer.lock은 사용 중인 모든 패키지의 정확한 버전을 알려줍니다. 이는 공격자가 시도할 수 있는 알려진 취약점 목록을 제공하는 것과 다름없습니다.

PHP-FPM에 전용 풀 할당하기

Flarum은 프로젝트 루트(설치 프로그램이 config.php을 생성할 수 있도록), storage/(로그 및 캐시용), assets/(업로드된 아바타 및 로고용) 등 세 가지 경로에 대한 쓰기 권한이 필요합니다. 파일의 소유자는 flarum 사용자이므로, 가장 깔끔한 해결책은 flarum 권한으로 실행되는 PHP-FPM 풀을 구성하는 것입니다. nginx는 www-data 권한으로 계속 실행되며 읽기 전용으로만 동작합니다.

/etc/php/8.3/fpm/pool.d/flarum.conf을 작성합니다:

[flarum]
user = flarum
group = flarum
listen = /run/php/php8.3-fpm-flarum.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm = ondemand
pm.max_children = 10
pm.process_idle_timeout = 30s
php_admin_value[memory_limit] = 256M
php_admin_value[upload_max_filesize] = 16M
php_admin_value[post_max_size] = 17M

sudo systemctl restart php8.3-fpm
ls -l /run/php/php8.3-fpm-flarum.sock

소켓은 srw-rw---- 1 www-data www-data로 지정되어야 합니다. 마스터 프로세스는 root 권한으로 실행되어 소켓을 생성하므로, 워커 프로세스가 flarum 권한으로 실행되는 동안 소켓의 소유권을 www-data에게 넘겨줄 수 있습니다. 소켓이 존재하지 않으면 sudo journalctl -u php8.3-fpm -n 30은 FPM이 요청을 거부했다는 메시지를 출력합니다. pm = ondemand은 요청이 들어올 때만 워커 프로세스를 시작하므로, 방문자가 없는 동안에는 포럼이 거의 메모리를 점유하지 않습니다.

Nginx 서버 블록

Flarum은 프로젝트 루트에 .nginx.conf라는 Nginx 스니펫을 포함하여 배포합니다. 이 파일에는 리라이트 규칙, 캐시 헤더, 압축 설정이 포함되어 있습니다. 내용을 복사하지 말고 include 지시어를 사용하십시오. 그래야 Flarum 업데이트로 스니펫이 변경되어도 별도의 수정 없이 서버에 즉시 반영됩니다.

server {
    listen 80;
    listen [::]:80;
    server_name forum.example.com;

    root /srv/flarum/public;
    index index.php;
    client_max_body_size 16M;

    include /srv/flarum/.nginx.conf;

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm-flarum.sock;
    }
}

이 내용을 /etc/nginx/sites-available/flarum으로 저장한 뒤 활성화하십시오.

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

nginx -t은 syntax is ok 및 test is successful에 응답해야 합니다. include 줄은 사용자가 자주 누락하는 부분입니다. 이 줄을 생략하면 매우 구체적인 증상이 나타납니다. 메인 페이지는 정상적으로 로드되지만, 모든 토론 링크를 클릭하면 Nginx가 404 오류를 반환합니다. Flarum은 /d/1-hello-world와 같은 URL을 PHP 내부에서 라우팅합니다. 해당 경로는 디스크상의 실제 파일이 아니므로, 스니펫의 try_files $uri $uri/ /index.php?$query_string 규칙이 없으면 Nginx는 d이라는 이름의 디렉터리를 찾습니다. 디렉터리를 찾지 못한 Nginx는 PHP에 요청을 전달하기도 전에 404 오류를 응답합니다. Apache의 경우 public/에 이미 존재하는 .htaccess 파일을 통해 동일한 라우팅을 처리합니다. 이 파일은 일치하는 <Directory> 블록에서 AllowOverride All이 설정되어 있을 때만 유효하게 작동합니다.

설치 프로그램을 실행하기 전에 TLS 추가하기

인증서 작업은 나중이 아니라 지금 수행해야 합니다. Flarum은 설치 과정에서 자체 기본 URL을 config.php에 기록하며, 이때 브라우저 주소창에 입력된 URL을 가져옵니다. http://을 통해 설치하면 이후 Flarum이 생성하는 모든 에셋 URL이 http://로 시작하게 됩니다. 따라서 나중에 TLS(전송 계층 보안)를 추가하면 브라우저가 해당 요청을 혼합 콘텐츠(mixed content)로 간주하여 차단하므로, 포럼이 스타일이 적용되지 않은 텍스트와 JavaScript가 없는 상태로 로드됩니다. 먼저 nginx에서 Let's Encrypt를 위한 certbot 설정을 완료하고, https://forum.example.com에서 페이지가 정상적으로 제공되는지 확인한 뒤 돌아오십시오.

이미 일반 HTTP로 설치를 완료했다면 한 줄의 명령어로 복구할 수 있습니다. /srv/flarum/config.php을 편집하여 url 키의 값을 'url' => 'https://forum.example.com',로 변경한 다음, flarum 사용자로 php flarum cache:clear를 실행하십시오.

설치 프로그램을 실행하고 config.php 파일 권한을 제한하기

브라우저에서 https://forum.example.com에 접속합니다. Flarum 웹 설치 프로그램은 데이터베이스 이름, 생성한 데이터베이스 사용자 이름과 비밀번호, 포럼 제목, 관리자 계정 정보를 요구합니다. 설치 프로그램은 config.php 파일을 생성하고 데이터베이스 테이블을 구성합니다. 설치가 완료되면 데이터베이스 비밀번호가 포함된 해당 파일의 권한을 강화해야 합니다.

sudo chmod 640 /srv/flarum/config.php

이 파일은 FPM이 실행되는 계정인 flarum만 읽고 쓸 수 있으며, 서버의 다른 모든 계정은 접근할 수 없게 설정됩니다. 그 후 셸에서 설치 상태를 확인합니다.

php flarum info

이 명령은 코어 버전, PHP 버전, 활성화된 확장 모듈, 메일 드라이버 및 사용 중인 경로 정보를 출력합니다. 문제가 발생했을 때 가장 먼저 실행해야 하는 명령이며, 기술 지원을 요청할 때 상대방이 가장 먼저 요구할 정보이기도 합니다.

가입 및 비밀번호 재설정 이메일이 조용히 실패하는 이유

이 섹션은 포럼이 첫 주를 무사히 넘길 수 있을지 결정합니다. 새로운 포럼이 처음으로 발송하는 두 가지 이메일은 가입 확인 메일과 비밀번호 재설정 메일이며, 이 두 메일은 낯선 방문자가 귀하의 커뮤니티를 신뢰할지 결정하는 바로 그 순간에 발송됩니다. 두 경우 모두 조용히 실패합니다. 메일을 받지 못한 사람은 귀하에게 이를 알릴 수 없으며, 관리자 대시보드에도 경고가 표시되지 않습니다.

Flarum은 관리자 페이지의 이메일 설정에서 smtp, mail, mailgun, log 등 네 가지 메일 드라이버를 제공합니다. smtp을 선택하고 실제로 메일을 전달할 수 있는 메일 서비스로 설정하십시오. mail 드라이버는 메시지를 로컬 sendmail 바이너리로 전달하는데, 이는 초기 상태의 Ubuntu VPS에는 존재하지 않으므로 메시지는 어디로도 가지 않으며 오류도 발생하지 않습니다. log 드라이버는 메시지 본문을 storage/logs/에 기록할 뿐 아무것도 발송하지 않는데, 이는 개발 환경을 위한 것이기 때문입니다.

설정을 저장한 뒤 같은 페이지에 있는 Send Test Mail 버튼을 누르십시오. 이 버튼은 유일한 피드백 수단이므로, 누군가를 초대하기 전에 반드시 사용해 보아야 합니다. 메시지가 도착하지 않는다면 로그를 확인하십시오.

tail -n 50 /srv/flarum/storage/logs/flarum.log

연결 거부, 로그인 거부, TLS 협상 실패 등은 모두 시도된 호스트 및 포트 정보와 함께 로그에 기록됩니다. Connection could not be established with host smtp.example.com라는 문구가 포함된 줄은 포트가 차단되었거나 잘못되었음을 의미하며, 일반적으로는 공급자가 기본적으로 25번 포트의 아웃바운드 트래픽을 차단하기 때문에 발생합니다. 암호화 필드를 tls으로 설정한 587번 포트 조합은 거의 모든 메일 서비스에서 정상적으로 작동합니다.

메일 기능이 작동하지 않으면 가입하려는 방문자는 확인 메일 발송 과정에서 요청이 실패하여 Flarum의 일반적인 실패 배너인 Oops! Something went wrong. Please reload the page and try again.를 보게 됩니다. 어느 경우든 방문자는 서비스에 접속할 수 없으며, 이에 대해 귀하에게 문의하지도 않을 것입니다.

메일이 발송되는 것과 메일이 수신 측에서 허용되는 것은 별개의 문제입니다. SPF나 DKIM 레코드가 게시되지 않은 VPS 주소에서 발송된 메일은 스팸 메일함으로 분류되거나 반송 메시지 없이 삭제됩니다. 이 경우 로그에는 성공적으로 발송된 것으로 기록되지만, 수신자는 메일을 받지 못하게 됩니다. 자체 호스팅 앱에서 안정적으로 메일 발송하기 문서에서 게시해야 할 DNS 레코드와 사용할 가치가 있는 릴레이 서비스를 확인하십시오.

확장 기능은 Composer 패키지이므로 업그레이드는 명령어로 수행합니다

Flarum에서 확장 기능은 Composer 패키지입니다. 업로드 버튼이나 폴더에 넣을 zip 파일은 존재하지 않습니다. 이는 의도적인 설계 결정입니다. 버전 간의 의존성을 해결하고, 정확한 패키지 구성을 composer.lock에 기록하며, PHP 라이브러리에 의존하는 확장 기능이 해당 라이브러리를 올바르게 설치하도록 보장하기 위함입니다. 그 대가로 확장 기능을 추가하려면 flarum 사용자로 세 가지 명령어를 실행해야 합니다.

composer require 'fof/upload:*'
php flarum migrate
php flarum cache:clear

그 후 관리자 페이지의 확장 기능(Extensions) 메뉴에서 해당 기능을 활성화하십시오. 각 명령어는 고유한 역할을 수행합니다. composer require은 코드를 디스크에 내려받습니다. php flarum migrate은 확장 기능에 포함된 데이터베이스 마이그레이션을 실행하며, 이를 통해 필요한 테이블을 생성합니다. php flarum cache:clear는 브라우저가 불러올 JavaScript 및 CSS 번들을 다시 컴파일합니다. 마지막 단계를 건너뛰면 흔히 발생하는 문제가 생깁니다. 확장 기능 목록에 표시되고 토글이 켜져 있음에도 불구하고, 브라우저를 아무리 새로고침해도 아무런 변화가 나타나지 않게 됩니다.

확장 기능을 제거할 때는 반대 순서로 진행합니다. 먼저 관리자 패널에서 기능을 비활성화한 다음 패키지를 제거하십시오. Flarum은 확장 기능의 테이블을 의도적으로 남겨두므로, 나중에 다시 활성화해도 데이터가 손실되지 않습니다. 테이블까지 삭제하려면 코드를 제거하기 전에 마이그레이션을 롤백하십시오.

php flarum migrate:reset --extension fof-upload
composer remove fof/upload
php flarum cache:clear

해당 명령어에 사용되는 확장 기능 ID는 패키지 이름에서 슬래시를 하이픈으로 바꾼 형태입니다. 명령어를 입력하는 대신 클릭으로 처리하고 싶다면, composer require 'flarum/extension-manager:*'을 통해 Composer를 감싸는 공식 관리자 페이지를 추가할 수 있습니다. 이 페이지는 웹 사용자의 권한으로 동일한 작업을 수행하며, 동일한 메모리와 쓰기 권한이 필요하고, 동일한 이유로 실패할 수 있습니다. 따라서 문제가 발생했을 때는 명령줄을 사용하는 것이 가장 확실한 해결 방법입니다.

Composer update가 Flarum 업그레이드를 거부하는 이유

Flarum과 모든 확장 기능을 업그레이드하려면 하나의 Composer 명령어를 실행한 뒤 두 개의 Flarum 명령어를 실행하면 됩니다. 먼저 데이터베이스를 백업하십시오.

composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear

작업이 성공했다고 가정하지 말고 출력 내용을 읽어 보십시오. Composer가 아무런 작업도 수행하지 않는 경우가 중요하기 때문입니다.

Your requirements could not be resolved to an installable set of packages.

이 메시지는 설치된 확장 기능 중 하나가 flarum/core 제약 조건을 선언하여, 이동하려는 릴리스 버전을 제외하고 있음을 의미합니다. Composer는 제약 조건을 위반하지 않으므로, 확장 기능 개발자가 작동하지 않는다고 명시한 조합을 구성하는 대신 전체 설치 상태를 이전 버전으로 유지합니다. 원인이 되는 패키지를 찾으십시오.

composer why-not flarum/core 1.8.17

출력 내용에는 해당 버전을 차단하는 모든 패키지와 각 패키지가 선언한 제약 조건이 나열됩니다. 여기서 선택할 수 있는 방법은 개발자가 호환되는 릴리스를 게시할 때까지 기다리거나, 해당 확장 기능을 제거하고 없이 사용하는 것입니다. 이것이 Composer 모델의 대가이며, 다른 사람들이 의존하는 포럼에 15개의 확장 기능을 설치하기 전에 이해해 두어야 할 부분입니다. 최근에 릴리스를 배포한 확장 기능을 우선적으로 선택하고, 직접 확인할 수 있을 정도로 목록을 짧게 유지하십시오.

백업 대상

데이터베이스와 프로젝트 디렉터리를 백업하십시오. 그 외의 모든 항목은 다시 생성할 수 있습니다.

mariadb-dump -u flarum -p --single-transaction flarum > flarum-$(date +%F).sql
sudo tar czf flarum-files.tgz -C /srv flarum

구형 시스템에서 mariadb-dump는 mysqldump으로 불리기도 하며, Ubuntu 24.04에서는 두 이름 모두 사용할 수 있습니다. 데이터베이스에는 모든 게시물, 모든 사용자, 모든 설정이 저장됩니다. 프로젝트 디렉터리에는 config.php, composer.json(실제로 실행 중인 확장 기능을 기록하는 파일), 그리고 업로드된 아바타와 로고가 포함된 assets/이 있습니다. vendor/은 건너뛰어도 됩니다. composer install이 composer.lock를 기반으로 이를 다시 생성하며, storage/ 또한 스스로 재생성되기 때문입니다. 백업 파일을 서버 외부로 복사하십시오. 보호 대상인 서버 내부에만 존재하는 백업은 진정한 백업이 아닙니다. 복구 과정은 동일한 버전의 Flarum을 새로 설치하고, composer install을 적용한 뒤, 저장해 둔 파일을 제자리에 배치하고 SQL 파일을 불러오는 방식으로 진행합니다.

FAQ

Flarum을 1 GB VPS에서 운영할 수 있습니까?

네, 소규모 커뮤니티라면 가능합니다. Flarum은 정상 작동 시 PHP-FPM이 요청을 처리하고 MariaDB가 데이터를 관리하며, pm = ondemand를 사용하면 사용자가 페이지를 읽는 동안에만 PHP 워커가 활성화됩니다. 가장 많은 자원을 소모하는 시점은 설치 단계입니다. composer create-project은 메모리 내에서 전체 의존성 그래프를 해결하므로, 이때 OOM(Out-of-Memory) 킬러에 의해 프로세스가 종료될 가능성이 가장 높습니다. 설치 전 스왑 파일을 추가하거나, 더 큰 사양의 장비에서 Composer를 실행한 뒤 해당 디렉터리 구조를 복사하십시오.

메인 페이지는 정상인데 게시글 링크에서 404 오류가 발생하는 이유는 무엇입니까?

nginx 서버 블록에 include /srv/flarum/.nginx.conf; 설정이 누락되었기 때문입니다. Flarum은 /d/1-hello-world와 같은 URL을 PHP 내부에서 처리하며, 해당 경로는 디스크상의 실제 파일이 아닙니다. 스니펫의 try_files $uri $uri/ /index.php?$query_string 규칙이 없으면 nginx는 d이라는 디렉터리를 찾다가 실패하고, PHP를 호출하지 않은 채 자체적으로 404 오류를 반환합니다. Apache의 경우 <Directory> 블록에서 AllowOverride All을 설정하지 않으면 public/.htaccess이 무시되어 동일한 라우팅 문제가 발생합니다.

HTTPS를 활성화한 후 포럼의 스타일이 모두 깨지는 이유는 무엇입니까?

Flarum은 설치 시 사용한 주소를 기반으로 config.php에 기본 URL을 저장합니다. 일반 HTTP로 설치했다면 Flarum은 계속해서 http:// 형태의 에셋 URL을 생성하며, 브라우저는 이를 HTTPS 페이지 내의 혼합 콘텐츠(mixed content)로 간주하여 차단하므로 스타일이 적용되지 않은 텍스트만 표시됩니다. /srv/flarum/config.php 파일의 url 키를 https:// 주소로 수정하고, 파일 소유자 계정으로 php flarum cache:clear을 실행하십시오.

가입 확인 이메일을 아무도 받지 못하는 이유는 무엇입니까?

먼저 메일 드라이버를 확인하십시오. mail 드라이버는 로컬 sendmail 바이너리가 필요한데, 새로 설치한 Ubuntu VPS에는 이 기능이 없습니다. 또한 log 드라이버는 storage/logs/에 로그만 기록할 뿐 실제 메일을 발송하지 않습니다. smtp으로 변경하고, 대부분의 공급자가 아웃바운드 25번 포트를 차단하므로 587번 포트와 tls 암호화를 사용한 뒤 Send Test Mail을 누르십시오. 로그상으로는 발송이 성공했으나 메일이 도착하지 않는다면 설정 문제가 아니라 도메인 신뢰도 문제입니다. 발송 도메인에 대한 SPF 및 DKIM 레코드를 게시하십시오.

Flarum 1.8과 2.0 중 무엇을 설치해야 합니까?

1.8 버전을 설치하십시오. 2026년 8월 기준으로 Flarum 2.0은 릴리스 후보(RC) 상태이며, 무엇보다 많은 확장 기능이 1.x 버전까지만 지원하는 flarum/core 제약 조건을 가지고 있습니다. 지금 2.0을 설치하면 확장 기능을 함께 업데이트할 수 없는 상태가 되며, 이는 composer why-not이 진단하고자 하는 전형적인 오류 상황입니다. flarum/flarum:^1.8.0로 버전을 고정하고, 사용하는 확장 기능들이 2.0 릴리스를 지원할 때까지 기다리십시오.

#flarum #forum #php #self-hosting #community