0부터 시작하는 개인 사이트 구축

2026년을 기점으로 개인 사이트 열풍이 다시 불고 있다. 나만의 개인 홈페이지를 만들고 싶어 하는 사람도 점점 늘고 있다. 기술 문서는 지나치게 세세하게 다루기 어렵고, 기존 글 가운데는 설명이 충분하지 않은 경우도 많아 이 글을 쓰게 되었다. 이 글에서는 iCerya Space를 예로 들어 아무런 기초가 없는 상태에서 개인 사이트를 구축하는 방법을 설명한다. 어느 정도 기초가 있거나 직접 이것저것 알아보고 싶다면 다음 글을 참고하기 바란다:

이 사이트와 비슷한 Yohaku 테마를 배포할 계획이라면 다음 글을 참고하기 바란다:

记一次部署 Yohaku 作为个人空间

本文详细介绍了在 OpenCloudOS 9 云服务器环境下，利用宝塔面板手动部署 MixSpace 后端及 Yohaku 前端主题的全过程。作者针对从传统PHP开发转向现代前端工程化过程中遇到的路径冲突、环境变量配置等问题提供了实践解决方案。文中涵盖了 Node.js、pnpm、pm2 及 Docker 等基础环境的安装调试，深入解析了利用 GitHub Actions 进行前端预构建的流程，并针对可能出现的构建错误提供了魔改版的 deploy.yml 配置建议。文章通过明确 INFO、TIP、WARNING 等文档规范，不仅记录了技术细节，更分享了跨技术栈部署的心得，旨在为开发者提供一份严谨的生产环境部署指南。

0. 준비 작업

iCerya Space는 NextJS와 Docker Compose V2 기술 스택을 기반으로 한 개인 공간 엔진으로, x86 64비트 또는 ARM 64비트의 Windows, Linux, macOS에서 실행을 기본 지원한다. 다만다른 사람이 정상적으로 접속할 수 있으면서 직접 유지보수하기도 쉬운 환경을 원한다면 Linux 계열 기술 스택을 선택하는 것을 추천한다.

본격적으로 시작하기에 앞서, 웹사이트를 성공적으로 배포하려면 다음 기본 준비물이 필요하다:

• 독립된 도메인 하나
• 클라우드 서버 한 대(또는 직접 보유한 서버)
• 공인 IP 하나
• 웹 번역을 지원하는 브라우저(영어를 못하는 경우)
• 결제 수단(알리페이, 위챗, 은행카드. Cloudflare에서 도메인을 직접 구매하거나 해외 클라우드 서버 제공업체를 이용하려면 VISA, Mastercard 또는 국제 결제를 지원하는 주요 신용카드가 필요하다)

1. 클라우드 서버 구매

클라우드 서버는 클라우드 서버 제공업체가 제공하는 '서비스'로, 보통 공인 IP가 함께 딸려 온다. 이들의 서버로 테스트와 배포 같은 작업을 처리할 수 있고, 물리 장비를 직접 관리할 필요도 없다. 서버도 없고 공인 IP도 없다면 클라우드 서버를 이용하면 된다. 일부 제공업체는 '경량 애플리케이션 서버'를 내놓는데, 보통 월 단위로 과금하며 일반 클라우드 서버보다 저렴해 개인용으로 더 적합하다.

클라우드 서버는 다음과 같은 방법으로 구할 수 있다. 여러 제공업체를 비교해 보고 가장 적합하다고 생각되는 곳을 고르면 된다. ICP 등록(비안)을 할 생각이 없다면 중국 본토 이외 지역의 서버를 구매해야 하는데, 이때는 국내외 클라우드 제공업체를 선택하는 데 큰 차이가 없다. 아래 목록이 전부는 아니므로 알고 있는 다른 클라우드 서버 제공업체를 골라도 된다:

국내 클라우드 서버 제공업체

• 텐센트 클라우드(텐센트가 운영하며, 현재 국내에서 그나마 합리적인 가격에 인터페이스도 깔끔하고 쓰기 좋은 클라우드 서버 제공업체이지만 알리페이 직접 결제는 지원하지 않는다)
• 알리 클라우드(알리바바가 운영하며 알리페이를 지원한다)
• 바이두 클라우드
• 화산엔진(Volcano Engine, 해외 리전이 비교적 적다)
• 징둥 클라우드
• 화웨이 클라우드
• UCloud

해외 클라우드 서버 제공업체

해외 클라우드는 보통 가입할 때 큰 금액의 쿠폰(예: $200)을 제공하며, 학생이라면 GitHub 계정으로 학생 인증을 받아 Microsoft Azure를 아주 저렴한 가격에, 심지어 무료로 사용할 수 있다.

• Google Cloud
• Microsoft Azure
• Amazon

클라우드 서버를 구매한 뒤에는 함께 제공되는 公网 IPv4 地址

2. 도메인 확보

현재 주류 도메인 등록 경로로는 국내의 텐센트 클라우드, 알리 클라우드, 바이두 클라우드와 해외의 Cloudflare, GoDaddy, DynaDot이 있다. 여기서는 개인적으로 Cloudflare에서 등록하는 것을 추천하며 이를 예로 든다. 물론 마음에 드는 도메인 등록업체를 골라도 되며, 이 점에는 차이가 없다.

Cloudflare를 예로 들면, 브라우저(예: Microsoft Edge, Google Chrome)를 열고 주소창에 cloudflare.com을 입력해 접속한 다음 이메일로 계정을 등록한다.

Cloudflare 콘솔을 열고 '도메인'의 '등록'을 선택한 뒤 오른쪽 내용에서 'Buy domain'을 클릭한다. 새로 열린 페이지의 입력란에 좋아하는 영문 단어, 하이픈(-), 숫자로 이루어진 조합을 입력하고 마음에 드는 접미사를 골라 구매하면 된다. 원하는 도메인이 '이미 등록됨'으로 표시된다면 자본의 힘으로 사들여도 되고…… 아니면 다른 단어로 바꾸면 된다.참고로 도메인 등록은 보통 연 단위로 구매하며, 등록 후에는 변경이나 환불이 불가능하다. 나중에 도메인을 바꾸게 되면 아무도 사용하지 않는 새 도메인을 등록해야 하고, 기존 도메인은 만료일까지 계속 본인 소유로 남는다.

도메인을 등록한 뒤에는 도메인 등록업체의 'DNS 레코드' 관리 화면으로 들어간다(참고: 텐센트 클라우드의 도메인 관리는 DNSPod에서 한다). Cloudflare Dashboard 사이드바에서 '도메인'의 '개요'를 선택하고 방금 구매한 도메인을 클릭한 다음, 사이드바에서 'DNS'의 '레코드'를 선택한다. 다음 A 레코드를 추가하고, 레코드 주소에는 서버의 公网 IP:

• 이름:@
• 유형:A
• IPv4 주소:你的服务器公网 IPv4 地址
• 프록시 상태: 켜기
• TTL: 자동 또는 600

레코드 이름은 도메인의 3차, 4차 또는 그 이상 하위 도메인을 가리킨다. 예를 들어 example.com에 대해 A 레코드로 주소 1.1.1.1를 지정했을 때 레코드가 api라면, DNS 서버는 api.example.com을 1.1.1.1로 해석한다. 참고로 @는 도메인의 root를 가리키며, @ 레코드는 도메인 그 자체를 의미한다.

3. 환경 구성

임대한 클라우드 서버는 보통 VNC 또는 SSH 통로를 제공한다. 이 방법으로 서버 터미널에 원격 접속하면 열린 터미널 패널에서 곧바로 서버 조작을 시작할 수 있다. 초보자가 쓰기 편한 바오타(BaoTa) 패널이나 1Panel을 설치해도 되고, 이 글 뒤에 나오는 리버스 프록시 설정과 Nginx 설정은 바오타 패널을 예로 든다. 경험이 있다면 터미널에서 직접 진행해도 된다.

Docker 구성

iCerya Space를 예로 들면, iCerya Space는 Docker에 의존해 실행되는 사전 빌드 소프트웨어이므로 서버에 Docker가 동작 중인지 확인해야 한다. 터미널에 다음 명령을 입력한다:

docker version

출력에 Server 관련 문구가 보이면 정상이며, 그렇지 않으면 아래 명령을 실행해야 한다:

# 如果你的服务器在国内，建议使用阿里云的安装脚本
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

# 在国外，可以直接使用官方脚本安装
curl -fsSL https://get.docker.com | bash -s docker

# 查询版本以验证安装
docker -v

4. iCerya Space 다운로드 및 설치

모든 준비가 끝났다면 이제 iCerya Space를 내려받아 설치할 차례다. iCerya Space 공식 사이트에서 iCerya ID로 로그인한 뒤 'iCerya Space 받기'에서 Linux x86-64 사양의 이미지 패키지를 내려받아 서버의 ～/ 아래(즉 /<你的用户名> 아래, 클라우드 서버를 구매할 때 사용자 지정 이름의 계정을 만들라는 요구가 없었다면 /root 아래)에 업로드한 다음, 아래 명령을 실행해 압축을 푼다:

mkdir -p ~/icerya-space-install && cd ~/icerya-space-install && tar -xf ~/ICSPACE-IMG_preview_0-20-12_103_63_linux_x86-64.tar

압축을 푸는 동안 콘솔에는 아무 출력도 없으며, 프롬프트 커서가 다시 나타나면 설치 명령을 입력한다:

./install.sh

5. 도메인 및 리버스 프록시 구성

설치가 끝나면 콘솔에 iCerya Space is now available at "http://192.168.1.20:5500" 문구가 나타날 것이다. 클라우드 서버에 설치했고 도메인도 연결할 계획이라면 지금 당장 열어 보지는 말자. 남에게 보여줄 생각이 없거나 로컬에만 설치했다면 뒤에 나오는 도메인 연결 부분은 신경 쓰지 않아도 된다.

도메인 구성

iCerya Space는 활성화 코드로 도메인을 연결해 정품 인증을 하는 웹사이트 엔진이므로, 먼저 iCerya Space 공식 사이트의 제품 센터에서 연결하려는 도메인을 키 이름 아래에 입력해야 한다.

바오타 패널의 '웹사이트'에서 새 사이트를 만들고 다음 정보를 입력한다:

• 도메인: Cloudflare 또는 도메인 등록업체에서 앞서 설정한 도메인(앞뒤에 아무것도 붙이지 않는다. 예를 들어 레코드 설정 시 @를 입력했다면 여기에는 your-domain를 입력하고, 설정할 때 다른 문자(예: ABC)를 입력했다면 여기에는 ABC.your-domain를 입력한다. 여기서 your-domain 부분에는 마지막 점과 접미사가 포함되어야 한다(예: .com,.cn,.top,.xyz 등)
• 비고: 알아보기 쉬운 아무 텍스트
• 루트 디렉터리: 그대로 둔다
• FTP, 데이터베이스, PHP: 모두 不创建 또는 纯静态
• 웹사이트 분류: 관심 있으면 알아봐도 되고, 사이트 운영에는 영향이 없다

생성한 뒤 '웹사이트'에서 방금 만든 도메인을 찾아 항목 오른쪽의 '설정'을 클릭하고, 뜬 창의 아래쪽에서 '리버스 프록시'를 찾은 다음 오른쪽 내용에서 '리버스 프록시 추가'를 찾는다.

• 프록시 켜기: 켜기
• 캐시 및 고급 기능 켜기: 그대로 두거나 끄기
• 프록시 이름: iCerya Space
• 대상 URL:http://127.0.0.1:5500
• 전송 도메인:$host
• 콘텐츠 대체: 입력할 필요 없음

위 내용대로 입력한 뒤 '확인'을 클릭하고, '설정' 창은 닫지 않는다.

도메인 인증서 구성

'설정'에서(이미 닫았다면 바오타 패널의 '웹사이트'에서 방금 구성한 사이트 오른쪽의 '설정'을 다시 눌러 열면 된다) 'SSL'을 찾는다. SSL 관련 서비스를 구매하거나 신청한 적이 없다면 오른쪽 영역에서 'Let's Encrypt'를 찾아 '인증서 신청'을 누르고, 새로 뜬 창에서 '파일 검증'을 선택한 뒤 아래 항목을 모두 체크하고 '인증서 신청'을 누른다. 별도의 도메인 인증서 서비스를 구매했다면, 구매한 서비스 사이트에서 인증서 파일을 내려받아 여기에 구성하는 방법을 확인하면 된다.

Let's Encrypt 도메인 인증서를 구성할 때 이미 '리버스 프록시'를 설정해 두었다면, 잠시 리버스 프록시 상태를 '끄기'로 돌려 두고 Let's Encrypt가 파일 검증을 마친 뒤에 다시 '리버스 프록시'를 켠다.

6. 모든 창조의 작업이 끝났다

위 내용을 마쳤다면 이제 도메인을 열고 iCerya Space 설치 마법사를 따라 설정을 완료한 뒤, 나만의 개인 공간을 표현하는 여정을 시작하면 된다.