Since a version update of the Yohaku theme in early May, newer versions of the Yohaku theme will only be applicable to backend versions V12 and V13 and later versions of MixSpace, where MixSpace V13 backend version must be paired with V8.0.0 or higher version of the admin dashboard. Therefore, some issues may arise due to oversight or misoperation, and here is an unofficial archive record.

Unless otherwise stated, the updates in this document are only related to MixSpace, and have nothing to do with whether your frontend theme is Yohaku, Shiro, or any other theme. This article provides a record of the commercial-grade upgrade process, focusing on the technical information of this update. The official cross-version upgrade documentation can be found below:

v11 升级到 v12 | Mix Space

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

mx-space.js.orgMix Space Team

Part. 1 Backup Data

Just like updating with WordPress or other site engines, before starting any cross-version update that affects the data structure, it is recommended to back up and archive the original database and current version program, so that you can roll back in time without affecting production if the update fails.

The following code for backing up data does not distinguish the method you use for MixSpace deployment:

# 进入你放 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

And verify that your backup is valid:

• backup-mongo-YYYYMMDD.archive File size is not 0;
• mx-space-full-backup-YYYYMMDD.tar.gz contains data/mx-space directory.

Part. 2 Version Update

Since I use Docker to deploy the backend in a unified manner (i.e., the admin dashboard is also installed when installing the MixSpace backend), I only list the procedures and considerations during my update here. If you need to deploy from source or deploy separately, please refer to the official MixSpace documentation.

Stop Backend Operation

After backing up data, immediately stop the backend operation to prevent new data from being written during the update and lost. Note: Do not stop the MongoDB service when stopping MixSpace:

cd ~/mx-space/core

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

Confirm MongoDB is still running and expose ports to the host:

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

If you do not see the expected content, make the following changes in the docker-compose.yml file at the corresponding location (add port configuration):

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

Update Configuration File

Run the following commands to back up the original docker-compose.yml and update the configuration file:

# 备份旧配置（以防万一）
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

If necessary, modify the configuration file

In the newly pulleddocker-compose.yml file, change the image: innei/mx-server:latest part to the following:

image: innei/mx-server:12

Migrate Configuration Information

In the new docker-compose.yml file, fill in your original docker-compose.yml configuration information:

- JWT_SECRET=
- ALLOWED_ORIGINS=

I have mentioned both of these in the article about deploying the Yohaku theme:

A Record of Deploying Yohaku as a Personal Space

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

Update and Start New Database

Start the new database

docker compose up -d postgres redis

Then wait about 30 seconds and execute the following command:

docker compose ps && docker port postgres | grep 5432

Expect to see postgres and redis status are both healthy or Up. Also confirm that PostgreSQL port 5432 is mapped to the host.

Database Migration

The official documentation provides two ways to perform database migration. We use the simpler method:

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

If --network host is unavailable, change to --network <v12 compose 网络名> and first connect the old mongo container to that network (docker network connect mx-space_mx-space mongo), then use the container names mongo:27017 and postgres:5432 to connect.

Expected output

• Rows allocated: XXXX, the number should be close to your article/comment count
• Missing refs: 0(a small number of orphan data is acceptable)
• Finally, the output shows ✅ Migration finished without missing references.

What if errors occur?

Update Yohaku or Frontend Display Theme

New versions of MixSpace no longer support using older versions of the Yohaku theme. Go update your Yohaku theme, or change/update the theme you are using to a version that explicitly states support for MixSpace V12, to be compatible with the new version of MixSpace.

Part. 3 Check Update

Start MixSpace V12

docker compose up -d

Execute the above command and check the following:

• Open the homepage, the article list displays normally
• Open an article, the content and comments are there
• Log in to the backend (你的域名/proxy/qaqdmin), able to log in normally
• The backend 'Other → Backup' page can be opened normally
• Publish a test article, it can be published and displayed normally
• Delete the test article, it can be deleted normally

Part. 4 About the Old Database and Rollback

Regarding the deletion and rollback of the old database, you can refer to the solutions in the official documentation. The official description of this part is very detailed, and I will not elaborate here:

v11 升级到 v12 | Mix Space

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

mx-space.js.orgMix Space Team

As for the various issues encountered during the MixSpace V13 update, I will also sort them out as soon as possible within the next two days and publish them here.