MixSpace 업데이트 및 Yohaku 테마 호환 관련 자주 묻는 질문

Yohaku 테마의 5월 초 버전 업데이트 이후, 새로운 버전의 Yohaku 테마는 백엔드 버전이 V12 및 V13 및 이후 상위 버전의 MixSpace, 그중 MixSpace V13의 백엔드 버전은 반드시 V8.0.0 이상 버전의 admin 백엔드 대시보드와 함께 사용해야 합니다. 따라서 이 과정에서 무시나 잘못된 조작으로 인해 발생할 수 있는 몇 가지 문제가 있을 수 있으며, 이를 비공식적으로 기록해 둡니다.

v12는 주요 버전 업그레이드로, 기본 데이터베이스가 MongoDB에서 PostgreSQL로 변경됩니다. 게시글, 댓글, 설정 등의 데이터는 모두 유지되지만, 업그레이드 과정에서 데이터 마이그레이션을 한 번 실행해야 하며, 짧은 사이트 중단이 필요합니다.

새 버전의 MixSpace는 구버전의 Yohaku 또는 사용 중인 프론트엔드 테마와 호환되지 않을 수 있습니다. 테마의 최신 버전이 MixSpace V12를 지원한다고 명확히 명시된 후에 업데이트를 진행하시기 바랍니다.

특별한 언급이 없는 한, 이 문서의 업데이트는 MixSpace에만 관련되며, 사용자의 프론트엔드 테마가 Yohaku, Shiro 또는 다른 테마인 것과는 무관합니다. 이 글은 상용 수준의 업그레이드 절차 기록만 제공하며, 이번 업데이트의 기술 정보 및 공식 제공 교차 버전 업그레이드 문서에 대한 자세한 내용은 다음을 참조하십시오:

v11 升级到 v12 | Mix Space

从 v11 升级到 v12 的完整指南，包含 MongoDB 到 PostgreSQL 的迁移步骤

mx-space.js.orgMix Space Team

Part. 1 데이터 백업

WordPress나 다른 웹사이트 엔진을 업데이트할 때와 마찬가지로, 모든 교차 버전 및 데이터 구조에 영향을 미치는 업데이트를 시작하기 전에 기존 데이터베이스와 현재 버전 프로그램을 백업하고 보관하여 업데이트 실패 시 신속하게 롤백하여 운영에 영향을 주지 않도록 권장합니다.

다음 백업 데이터 관련 코드는 MixSpace 배포 방식을 구분하지 않습니다:

BASH

# 进入你放 docker-compose.yml 的文件夹，或者 core 源码文件夹
cd ~/mx-space/core

# 备份 MongoDB 数据
docker exec -i $(docker ps -q -f name=mongo) mongodump --archive > backup-mongo-$(date +%Y%m%d).archive

# 同时打包整个数据目录（包含配置文件、图片等）
tar czvf mx-space-full-backup-$(date +%Y%m%d).tar.gz ./data

그리고 백업이 유효한지 확인하십시오:

backup-mongo-YYYYMMDD.archive 파일 크기가 00
mx-space-full-backup-YYYYMMDD.tar.gz이 아님;data/mx-space 디렉토리.

Part. 2 버전 업데이트

저는 Docker 방식으로 백엔드를 통합 배포했기 때문에(즉, MixSpace 백엔드 설치 시 백엔드 대시보드도 함께 설치됨), 여기에는 제 업데이트 과정과 주의사항만 나열합니다. 소스 코드 배포 또는 분리 배포 업데이트가 필요한 경우 MixSpace 공식 문서를 참조하십시오.

백엔드 중지

데이터 백업 후 즉시 백엔드를 중지하여 업데이트 중 새 데이터가 기록되어 손실되는 것을 방지하십시오. 참고: MixSpace 실행을 중지할 때 MongoDB 서비스를 중지하지 마십시오:

BASH

cd ~/mx-space/core

# 只停业务进程，让 mongo 继续跑
docker compose stop app

MongoDB가 여전히 실행 중이고 호스트에 포트가 노출되어 있는지 확인하십시오:

BASH

docker ps | grep mongo
docker port $(docker ps -q -f name=mongo) | grep 27017
# 期望看到类似  27017/tcp -> 0.0.0.0:27017

예상한 내용이 보이지 않으면, docker-compose.yml 파일의 해당 위치를 다음과 같이 수정하십시오(추가: port 구성):

YML

mongo:
  container_name: mongo
  image: mongo:7
  volumes:
    - ./data/db:/data/db
  networks:
    - mx-space
  port: ["27017:27017"]
  restart: unless-stopped

구성 파일 업데이트

다음 명령을 실행하여 기존 docker-compose.yml 을 백업하고 구성 파일을 업데이트하십시오:

BASH

# 备份旧配置（以防万一）
cp docker-compose.yml docker-compose.yml.v11.backup

# 拉取 v12 的 docker-compose.yml（已内置 PostgreSQL）
wget -O docker-compose.yml https://fastly.jsdelivr.net/gh/mx-space/core@master/docker-compose.yml

필요시 구성 파일 변경

새로 가져온 docker-compose.yml 파일에서 image: innei/mx-server:latest 부분을 다음과 같이 변경하십시오:

YML

image: innei/mx-server:12

구성 정보 마이그레이션

새 docker-compose.yml 파일의 다음 두 구성 정보에 원래 docker-compose.yml 의 구성 정보를 입력하십시오:

YML

- JWT_SECRET=
- ALLOWED_ORIGINS=

이 두 가지는 제가 Yohaku 테마 배포에 관한 글에서 언급한 내용입니다:

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

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

새 데이터베이스 업데이트 및 시작

새 데이터베이스 시작

BASH

docker compose up -d postgres redis

그런 다음 약 30초 정도 기다린 후 아래 명령을 실행하십시오:

BASH

docker compose ps && docker port postgres | grep 5432

예상 결과: postgres 와 redis 상태가 모두 healthy 또는 Up 입니다. 또한 PostgreSQL 포트 5432가 호스트에 매핑되었는지 확인하십시오.

데이터베이스 마이그레이션

공식 문서에서는 두 가지 방법으로 데이터베이스 마이그레이션을 제공하며, 우리는 더 간단한 방법을 사용합니다:

BASH

docker run --rm --network host \
  -e MONGO_URI="mongodb://127.0.0.1:27017/mx-space" \
  -e PG_URL="postgres://mx:[email protected]:5432/mx_core" \
  node:22-alpine \
  npx -y @mx-space/mongo-pg-cli@latest --mode apply

만약 --network host 을 사용할 수 없는 경우, --network <v12 compose 网络名> 으로 변경하고 먼저 기존 mongo 컨테이너를 해당 네트워크에 연결하십시오(docker network connect mx-space_mx-space mongo), 그런 다음 컨테이너 이름 mongo:27017 와 postgres:5432 을 사용하여 연결하십시오.

예상 출력

Rows allocated: XXXX이며, 숫자는 게시물/댓글 수와 비슷합니다
Missing refs: 0(소량의 고아 데이터는 허용 가능)
마지막에 ✅ Migration finished without missing references.

오류가 발생하면 어떻게 해야 합니까?

오류 메시지	원인	해결 방법
MongoServerSelectionError	mongo 포트가 노출되지 않음 / 네트워크 연결되지 않음	mongo 컨테이너가 27017을 매핑했는지 확인하거나 --network 설정이 올바른지 확인하십시오
Connection refused (postgres)	PG가 아직 시작되지 않음	30초 기다린 후 재시도
Missing refs > 0	고아 데이터 있음	일반적으로 무시 가능, 스크린샷 기록 후 계속
기타 오류	알 수 없는 문제	계속하지 말고 로그를 보관한 후 v11로 롤백하십시오(아래 롤백 섹션 참조).

Yohaku 또는 프론트엔드 테마 업데이트

새 버전의 MixSpace는 더 이상 이전 버전의 Yohaku 테마를 지원하지 않습니다. Yohaku 테마를 업데이트하거나, 사용 중인 다른 테마를 MixSpace V12를 지원한다고 명시된 버전으로 변경/업데이트하여 새 버전의 MixSpace에 적응하십시오.

Part. 3 업데이트 확인

MixSpace V12 시작

BASH

docker compose up -d

위 명령을 실행하고 다음 내용을 확인하십시오:

홈페이지 열기, 게시물 목록 정상 표시
게시물 하나 열기, 내용과 댓글 모두 있음
백엔드 로그인(你的域名/proxy/qaqdmin), 정상적으로 로그인 가능
백엔드 「기타 → 백업」 페이지가 정상적으로 열림
테스트 게시물 작성, 정상 발행 및 표시
테스트 게시물 삭제, 정상 삭제

Part. 4 구 데이터베이스 및 롤백에 관하여

구 데이터베이스의 삭제 및 롤백에 관해서는 공식 문서의 해결 방법을 참조하십시오. 공식 문서에서 이 부분에 대한 설명이 매우 자세하므로 여기서는 다시 설명하지 않겠습니다:

v11 升级到 v12 | Mix Space

从 v11 升级到 v12 的完整指南，包含 MongoDB 到 PostgreSQL 的迁移步骤

mx-space.js.orgMix Space Team

MixSpace V13 업데이트 시 발생하는 각종 문제에 대해서도 이틀 내로 최대한 빨리 정리하여 여기에 게시하겠습니다.