自 Yohaku 主题 5 月初的一次版本更新后，更新版本的 Yohaku 主题将只适用于后端版本为 V12 和 V13 及以后更高版本的 MixSpace，其中 MixSpace V13 的后端版本必须搭配 V8.0.0 或更高版本的 admin 后台仪表盘。因此期间会遇到些许可能因为忽略和误操作导致的问题，在此作非官方的归档记录。

如非特殊声明，本文档的更新仅与 MixSpace 有关，与你的前端主题是 Yohaku、Shiro 或任何其他主题无关。本文章仅提供商业级升级流程记录，重点具体有关于本次更新的技术信息、官方提供的跨版本升级文档可参见如下：

v11 升级到 v12 | Mix Space

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

mx-space.js.orgMix Space Team

Part. 1 备份数据

和使用 WordPress 或其他网站引擎时进行更新一样，在一切跨版本、影响数据结构的更新开始之前，推荐对原有数据库和当前版本程序的备份和归档，以备更新失败时及时回档不影响生产。

以下备份数据相关代码不区分你使用何种方式进行的 MixSpace 部署：

# 进入你放 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 文件大小不为 0；
• mx-space-full-backup-YYYYMMDD.tar.gz 包含 data/mx-space 目录。

Part. 2 版本更新

由于我使用的是 Docker 方式统一部署后台（即安装 MixSpace 后台时同时安装了后台仪表盘），因此在这里仅列出我更新时的流程和注意事项。如有对源码部署或分开部署更新的需要，请参照 MixSpace 官方文档。

停止后台运转

在备份完数据后，立即停止后台运行，避免新数据在更新时写入导致丢失。注意，停止 MixSpace 运行时不要停止 MongoDB 服务运行：

cd ~/mx-space/core

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

确认 MongoDB 仍在运行，并对主机暴露端口：

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 配置）：

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

更新配置文件

执行以下命令，备份原有 docker-compose.yml 并更新配置文件：

# 备份旧配置（以防万一）
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 部分变更为如下：

image: innei/mx-server:12

迁移配置信息

在新的 docker-compose.yml 文件中的下面两条配置信息处填入你原来 docker-compose.yml 的配置信息：

- JWT_SECRET=
- ALLOWED_ORIGINS=

二者为何我在部署 Yohaku 主题的文章中提到过：

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

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

更新并启动新数据库

启动新数据库

docker compose up -d postgres redis

随后等待 30 秒左右，执行下面命令：

docker compose ps && docker port postgres | grep 5432

预期看到 postgres 和 redis 状态都是 healthy 或 Up。同时确认 PostgreSQL 端口 5432 已映射到宿主机。

数据库迁移

官方文档提供了两种方式进行数据库迁移，我们采用更简单的一种方法：

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.

如果报错怎么办？

更新 Yohaku 或前端显示主题

新版本的 MixSpace 不再支持继续使用旧版本的 Yohaku 主题，前往更新你的 Yohaku 主题，或变更、更新你使用的其他主题到明确说明支持 MixSpace V12 的版本，以适应新版本的 MixSpace。

Part. 3 检查更新

启动 MixSpace V12

docker compose up -d

执行上面命令，并检查以下内容：

• 打开首页，文章列表正常显示
•  打开一篇文章，内容和评论都在
•  登录后台（你的域名/proxy/qaqdmin），能正常登录
•  后台「其他 → 备份」页面能正常打开
•  发一篇测试文章，能正常发布和显示
•  删除测试文章，正常删除

Part. 4 关于旧数据库和回滚

有关于旧数据库的删除和回滚，你可以参考官方文档中的解决方案。官方关于这部分的描述十分详细，我不再在此赘述：

v11 升级到 v12 | Mix Space

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

mx-space.js.orgMix Space Team

有关于 MixSpace V13 更新时遇到的各项问题，我也将在这两天内尽快整理完毕并发布于此。