Synology NAS Headless WordPress 설치 및 설정 가이드

본 가이드는 Synology NAS (DS920+) 환경에서 Headless WordPress를 구축하기 위한 절차입니다. React 앱(sokuree.com)이 데이터를 가져오기 위해 필요한 백엔드 설정을 다룹니다.

1. 사전 준비 (Synology 패키지 센터)

다음 패키지들이 설치되어 있어야 합니다.

Web Station
Apache HTTP Server 2.4 (또는 Nginx)
PHP 8.3 이상 (Headless 모드는 최신 PHP 권장)
MariaDB 10 (데이터베이스)
phpMyAdmin (DB 관리용, 선택사항이나 강력 추천)

2. 데이터베이스 생성 (MariaDB 10)

Synology에서 MariaDB 10을 실행하고 root 비밀번호를 설정합니다.
phpMyAdmin을 실행하여 root로 로그인합니다.
상단 메뉴의 [데이터베이스] 탭을 클릭합니다.
새 데이터베이스 만들기:
- 데이터베이스 이름: sokuree
- 데이터와(collation): utf8mb4_unicode_ci (한글 및 이모지 지원)
- [만들기] 클릭.
(보안 권장) wp_user 같은 전용 사용자를 만들고 sokuree DB에 대한 모든 권한을 부여합니다.

3. WordPress 파일 설치

WordPress.org에서 최신 zip 파일을 다운로드합니다.
Synology File Station을 통해 /web 폴더 아래에 새 폴더 sokuree_wp를 만듭니다. (React 앱과 구분하기 위해 이름 뒤에 _wp 추천)
zip 파일을 sokuree_wp 폴더에 업로드하고 압축을 풉니다.
최종 경로가 /web/sokuree_wp/index.php 등이 보이도록 정리합니다.

4. Web Station 설정

Web Station 실행 -> 웹 서비스 포털 -> 생성 -> 웹 서비스 포털.
서비스: 가상 호스트 선택.
호스트 이름 기반:
- 호스트 이름: api.sokuree.com (React 앱은 sokuree.com을 쓸 것이므로, WP는 서브도메인이나 별도 포트 추천. 여기서는 API 전용임을 명확히 하기 위해 api 예시)
- 포트: 80 / 443
문서 루트: 찾아보기 -> /web/sokuree_wp 선택.
백엔드 서버: Apache HTTP Server 2.4 / PHP 8.x 프로필 선택.
확인을 눌러 저장합니다.

주의: 도메인 api.sokuree.com의 DNS A 레코드가 Synology NAS의 공인 IP를 가리키고 있어야 합니다. 공유기 포트포워딩(80, 443)도 필수입니다.

5. WordPress 설치 진행

브라우저에서 http://api.sokuree.com (설정한 주소) 접속.
언어 선택 (한국어).
DB 연결 정보 입력:
- 데이터베이스 이름: sokuree
- 사용자명: root 또는 생성한 유저
- 비밀번호: MariaDB 비밀번호
- 데이터베이스 호스트: localhost:/run/mysqld/mysqld10.sock (Synology MariaDB 10 소켓 경로. 보통 localhost로 안 되면 127.0.0.1:3307 등을 시도)
사이트 제목, 관리자 계정 생성 후 설치 완료.

6. Headless 설정 (필수!)

React 앱이 데이터를 잘 가져오기 위해 다음 설정이 필요합니다.

A. 고유주소 (Permalinks) 설정

워드프레스 관리자 -> 설정 -> 고유주소.
글 이름 (Post name) 선택.
[변경 사항 저장].
- 이 설정을 안 하면 JSON API가 404 에러를 낼 수 있습니다.

B. CORS 허용 (중요)

React 앱(다른 도메인)에서 WP(API 도메인)로 요청을 보내려면 CORS 허용이 필요합니다. functions.php 파일은 워드프레스 최상위 폴더가 아니라, 테마 폴더 안에 있습니다.

[추천] Headless용 테마 선택

Headless 방식에서는 테마의 디자인이 사용자에게 보이지 않습니다. (우리가 만든 React 앱이 보이기 때문입니다.) 따라서 관리자 페이지가 빠르고 가벼운 테마가 가장 좋습니다.

추천 테마:

Twenty Twenty-Four (기본 테마): 가장 무난하고 관리가 잘 됩니다. 기본 설치되어 있으니 그대로 쓰셔도 충분합니다.
Ollie: 매우 가볍고 모던한 블록 테마입니다.
Frost: WP Engine에서 만든 미니멀 테마로 불필요한 기능이 없어 Headless용으로 인기가 많습니다.

설정 방법:

wp-content 폴더 더블클릭.
themes 폴더 더블클릭.
선택한 테마(예: twentytwentyfour) 폴더로 들어갑니다.
그 안에 있는 functions.php 파일을 엽니다.
파일 맨 끝에 다음 코드를 추가합니다:

add_action( 'init', function() {
    header("Access-Control-Allow-Origin: *"); // 실제 운영 시 https://sokuree.com 으로 변경 권장
    header("Access-Control-Allow-Methods: GET, POST, OPTIONS");
    header("Access-Control-Allow-Headers: Content-Type");
});

7. React 앱 연결 확인

React 앱의 src/config/wordpress.js 파일에서 BASE_URL이 위에서 설정한 워드프레스 주소와 맞는지 확인합니다. 예: https://api.sokuree.com/wp-json

이제 모든 준비가 되었습니다! React 앱에서 글을 불러올 수 있습니다.

8. 문제 해결 (Troubleshooting)

Q. 테마/플러그인 삭제 시 FTP/SSH 정보를 물어봅니다.

이것은 워드프레스가 파일 권한 문제로 직접 쓰기를 못할 때 발생합니다. wp-config.php 파일에 한 줄만 추가하면 해결됩니다.

Synology File Station에서 /web/sokuree_wp/wp-config.php 파일을 엽니다.
파일 맨 마지막 또는 /* That's all, stop editing! ... */ 위에 다음 줄을 추가하세요:

define('FS_METHOD', 'direct');

저장하면 더 이상 FTP 정보를 묻지 않습니다.

5.5 KiB Raw Blame History