NOTE

这篇文章写给所有被 Yohaku 的美打动过，却在部署的岔路口犹豫驻足的你。不需要多深的技术背景——跟着一步步来，你的博客就会在某个下午，安静地亮起来 🌸

---

Yohaku，取自日文「余白」，意为留白——画面中那些有意空出的地方，往往比填满的部分更有分量。

这是 Mix Space 生态中最新一代的前端主题。它的故事从开源的 Shiro 开始，经由闭源赞助版 Shiroi 的沉淀，一路演进至今日的 Yohaku——三代传承，设计语言与实现在每一步都在悄然迭代。整站以书写为隐喻，页面像一封徐徐展开的信纸，用克制的色彩和呼吸式的动画，让阅读本身成为主角。

三代主题的关系，简单梳理一下：

• Shiro → Mix Space 最初的开源前端主题，代码公开在 GitHub
• Shiroi → Shiro 的闭源捐赠版，在 Shiro 基础上演进，赞助后可访问
• Yohaku（余白） → 由 Shiro / Shiroi 进一步演进而来的全新设计，同样以闭源赞助形式维护，是目前最新的一代

本文部署的主角是 Yohaku。由于它是闭源主题，需要自行构建 Docker 镜像，下文会手把手带你完成。（本教程亦兼容Shiroi）

::: banner {note} 前提说明：本文假设你拥有闭源版仓库的访问权限，且已完成 Mix Space 后端的部署，手边备好了两个地址：

• 后端 API 地址：形如 https://你的域名/api/v2
• 后端网关地址：形如 https://你的域名

如尚未部署后端，请先参阅 Mix Space 官方文档 完成。 :::

---

第一步 · 安装 1Panel 面板

如果你的服务器已经安装了 1Panel，可以直接跳到第二步。

1Panel 是一款现代化的开源 Linux 服务器运维面板，界面清爽、操作直观，是管理容器应用最顺手的工具之一。

安装前的小小确认

检查项	要求
操作系统	主流 Linux 发行版（Debian / Ubuntu / CentOS 等）
服务器架构	x86_64、aarch64、armv7l 等均支持
可用内存	建议 1 GB 以上
网络环境	需能正常访问互联网
浏览器	Chrome、Firefox、Edge 等现代浏览器

一行命令，完成安装

SSH 登录你的服务器，执行：

bash -c "$(curl -sSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh)"

按照命令行提示操作，耐心等待安装完成。成功后，控制台会打印出类似这样的访问信息：

面板地址：http://你的服务器IP:端口/安全入口

::: warning 云服务器用户请注意：记得在安全组中开放对应端口，否则浏览器将无法访问面板。 :::

忘记安全入口了？SSH 回到服务器，执行 1pctl user-info，找到 entrance 字段的值就是了。

如果 Docker 安装失败，先单独运行这条命令修复：

bash <(curl -sSL https://linuxmirrors.cn/docker.sh)

---

第二步 · 构建 Docker 镜像

由于 Shiroi / Yohaku 均为闭源赞助主题，作者没有提供预构建的 Docker 镜像，需要我们自行构建。但请不要在低配服务器上直接构建——服务器的内存会被撑爆 💥

我们的方案是借助 GitHub Actions 在云端完成构建，然后把镜像推送到 GitHub Packages（ghcr.io）私有仓库里。服务器只需要拉取现成的镜像，非常轻盈。

2.1 Fork 构建仓库

访问以下仓库，点击右上角的 Fork：

https://github.com/IPF-Sinon/yohaku-docker-build

2.2 申请 GitHub 经典访问令牌（Classic Token）

Actions 需要有权限读取 Shiroi 私有仓库、并将构建好的镜像推送到 GitHub Packages。我们要提前准备一个经典令牌（Classic Token）。

访问路径：

GitHub 头像 → Settings → Developer Settings
→ Personal access tokens → Tokens (classic)
→ Generate new token (classic)

填写备注（例如 shiroi-build），有效期可设为永久，然后勾选以下权限：

权限	用途说明
repo	读写仓库，含私有仓库访问
write:packages	将镜像推送到 GitHub Packages
read:packages	从 GitHub Packages 拉取镜像

点击 Generate token，立即将生成的 Token 复制保存好——它只显示这一次！

2.3 配置仓库 Actions 变量

进入你 Fork 好的仓库，依次点击：

Settings → Secrets and variables → Actions → Repository secrets

添加以下两个变量：

变量名	填写内容
DOCKER_NAMESPACE	你的 GitHub 用户名（必须全部小写）
GH_PAT	上一步申请的 Personal Access Token

2.4 启用并触发构建

进入仓库的 Actions 标签页，如有提示请点击启用。然后找到构建 Workflow，点击右侧的 Run workflow 手动触发一次。

构建过程通常需要 5 ~ 10 分钟，可以去泡杯茶等待 ☕

构建完成后，在仓库侧边栏的 Packages 中就能看到你的镜像，地址格式为：

ghcr.io/你的用户名(全小写)/shiroi:latest

::: warning GitHub Actions 规定：仓库若连续 3 个月无活动，工作流将被自动停用。构建仓库内置了哈希文件更新机制来维持活跃，但若真被停用了，进入 Actions 页重新启用即可。 :::

2.5 在 1Panel 中配置 ghcr.io 私有仓库

由于镜像存放在私有 GitHub Container Registry，1Panel 需要先登录认证才能拉取。

登入 1Panel 面板，前往 容器 → 仓库 → 创建仓库，填写：

字段	内容
名称	ghcr.io（任意便于识别的名字）
仓库地址	ghcr.io
用户名	你的 GitHub 用户名
密码	你的 Personal Access Token（GH_PAT）

保存后，1Panel 会自动验证连接。这样以后拉取私有镜像就畅通无阻了 🔐

---

第三步 · 通过 1Panel 安装 Yohaku

3.1 上传应用包

登入 1Panel 面板，在左侧菜单进入 主机 → 文件，导航到路径：

/opt/1panel/resource/apps/local

点击上传，选择你从 Fork 的仓库下载的 yohaku.zip 文件。

3.2 解压，注意路径！

上传完成后，点击 yohaku.zip，选择解压。

::: banner {error} 这一步是新手最常踩的坑，请务必注意！

解压时需要手动将目标路径补全为：

/opt/1panel/resource/apps/local/yohaku

路径不对，可能产生一堆位于错误目录的文件，应用商店将无法识别此本地应用。 :::

3.3 同步本地应用

前往 1Panel 应用商店，点击右上角的同步本地应用按钮，稍等片刻后在搜索框输入 yohaku，便能看到刚刚添加的应用了。

点击安装，进入配置页面。

3.4 填写安装配置项

安装页面共有四个必填项（另有一条只读说明），从上到下依次填写：

🐳 镜像地址（Image Address）

这里填写容器镜像。根据你部署的版本选择：

开源版 Shiro（直接使用官方预构建镜像）：

innei/shiro:latest

闭源版 Shiroi / Yohaku（填写第二步自行构建的私有镜像）：

ghcr.io/你的用户名(全小写)/shiroi:latest

📡 公开 API 地址（PUBLICAPIURL）

填写你的 Mix Space 后端 API 地址：

https://你的后端域名/api/v2

注意保留末尾的 /api/v2 路径。

🌐 公开网关地址（PUBLICGATEWAYURL）

填写你的 Mix Space 后端网关地址（即后端根域名）：

https://你的后端域名

不需要加任何路径后缀。

🔗 API URL 与客户端 API 地址

API_URL 与 NEXT_PUBLIC_CLIENT_API_URL 这两项的值与公开 API 地址保持一致，填入相同内容即可：

https://你的后端域名/api/v2

3.5 开始安装 🎉

确认配置无误，点击开始安装。

1Panel 会自动拉取镜像并启动容器，此过程根据网络状况可能需要几分钟。当状态显示为运行中（Running），Yohaku 就正式上线了！

---

第四步 · 后续配置

配置反向代理与 HTTPS

为了通过域名访问博客，需要在 1Panel 中配置网站：

前往网站 → 创建网站 → 反向代理，填写你的域名，代理目标设为容器的本地端口，例如：

http://127.0.0.1:2323

建议同时开启 HTTPS——1Panel 支持一键申请 Let's Encrypt 证书，非常方便。

在 Mix Space 后台同步地址

(一般不用进行此操作) 登入 Mix Space 管理后台，进入设置 → 系统设置，更新以下字段：

字段	填写内容
前端地址	https://你的博客域名
管理后台地址	https://后端域名/proxy/qaqdmin
API 地址	https://后端域名/api/v2
Gateway 地址	https://后端域名

---

附：Yohaku 支持的扩展 Markdown 语法

Yohaku 继承自 Shiro 体系，支持一套丰富的扩展 Markdown 语法，让你的博文不止于纯文字。以下是写作时可以使用的特色语法——

数学公式（KaTeX）

行内公式：

质能方程 $E = mc^2$ 改变了人类对宇宙的认知。

块级公式：

$$
\int_{-\infty}^{+\infty} e^{-x^2} dx = \sqrt{\pi}
$$

提示横幅（Notice / Banner）

::: warning
这里是警告内容，背景会呈现醒目的颜色。
:::

::: banner {note}
这里是备注，适合附加额外说明。
:::

::: banner {error}
这里是错误提示，用于强调危险操作。
:::

GFM Alert 语法

> [!NOTE]
> 这是一条备注，提醒读者注意某些事项。

> [!IMPORTANT]
> 这是重要信息，不容忽视。

> [!WARNING]
> 这是警告，可能涉及潜在风险。

剧透遮罩（Spoiler）

这部电影的结局是 ||主角其实已经死了||，令人意想不到。

注意：这与删除线 ~~文字~~ 的效果不同，Spoiler 会用遮罩隐藏内容，鼠标悬停后才显示。

富链接（Rich Link）

对于单独成行的链接，Yohaku 会自动渲染为带封面和摘要的卡片样式：

https://github.com/Innei/Yohaku

支持识别的平台包括 GitHub 仓库、Commit、Issue、Gist，以及 YouTube、Twitter 等。

内联链接图标

行内链接会自动附上对应网站的 Favicon：

访问 [Innei 的主页](https://innei.in) 了解更多。

Mention（提及）

感谢 [Innei]{GH@Innei} 创作了这么美的主题。

GH@用户名 会自动渲染为带头像的 GitHub 用户卡片。

折叠块（Collapse）

<details>
<summary>点击展开查看详细内容</summary>

这里是折叠起来的详细说明……

</details>

---

常见问题

Q：镜像拉取速度极慢或失败怎么办？

国内服务器拉取 ghcr.io 时可能较慢。可以在 GitHub Actions 的构建 Workflow 中添加同步推送至阿里云 ACR 的步骤，再从阿里云拉取。具体配置可参考薄荷の小屋的教程。

Q：Actions 构建失败，如何排查？

进入仓库的 Actions 页面，点击失败的 Workflow 查看详细日志，常见原因：

• GH_PAT 权限不够，检查是否勾选了 repo 和 write:packages
• DOCKER_NAMESPACE 没有全部小写
• 仓库被设为公开，导致权限冲突

Q：解压后应用商店搜不到 yohaku？

大概率是解压路径不对。请确认解压目标为 /opt/1panel/resource/apps/local/yohaku（不是 /opt/1panel/resource/apps/local）。确认后重新点击「同步本地应用」。

Q：忘记 1Panel 安全入口了？

1pctl user-info

entrance 字段的值就是你的安全入口路径。

---

参考资料

本文写作过程中参考了以下资料，感谢各位博主的慷慨分享 💝

• 1Panel 在线安装文档
• GitHub Action 构建 Shiroi Docker 镜像 · Mikuの极光星
• Mix Space + Shiro 全容器化部署指南 · 薄荷の小屋
• 自助创建 1Panel 应用 · FIT2CLOUD 社区论坛
• 自助创建 1Panel 应用工具
• Shiro Markdown 扩展语法文档
• Yohaku 主题文档
• 添加NEXT_PUBLIC_CLIENT_API_URL
• 添加API_URL

---

余白，是一种态度。
愿你的博客，也能成为那封值得被细细展开的信纸 🌿

前言

最近发现一台价格更低的云服务器，于是决定把原有服务整体迁移过去。\ 本来打算直接使用 1Panel 快照功能一键迁移，但实际操作后发现：

博客空间（MX Space）无法完整通过快照迁移

因此只能手动迁移，顺便把整个流程记录下来，供以后参考。

---

一、DNS 解析迁移

首先需要让域名指向新服务器。

1. 登录你的域名 DNS 服务商\
2. 修改 A 记录 → 指向新服务器 IP\
3. 建议设置较低 TTL（如 600 秒），方便快速生效

示例：

记录类型 主机记录 记录值 ---------- ---------- ------------- A @ 新服务器 IP A www 新服务器 IP

等待解析生效（通常 1~30 分钟）。

---

二、迁移 MX Space 服务端

1. 打包旧服务器数据

MX Space 的核心数据全部在 mx-space 目录中。

例如目录结构： /root/mx-space

旧服务器执行： cd /root tar -czvf mx-space.tar.gz mx-space

---

2. 上传到新服务器

scp mx-space.tar.gz root@新服务器IP:/root/ cd /root tar -xzvf mx-space.tar.gz

---

3. 启动 Docker 服务

cd /root/mx-space/core docker compose pull docker compose up -d docker ps

---

4. 常见补充检查

ufw allow 80 ufw allow 443 ufw allow 22

apt update apt install docker-compose-plugin -y

---

三、部署 Shiroi 主题（GitHub Actions）

进入：Settings → Secrets and variables → Actions

需要更新： HOST / USER / PASSWORD / PORT / KEY / GH_PAT

然后运行 Actions → Run workflow

---

四、迁移完成验证

1. 打开博客域名\
2. 查看是否可正常访问\
3. 检查后台管理\
4. 测试文章、图片、评论功能

---

迁移总结

1. 修改 DNS\
2. 迁移 /root/mx-space\
3. Docker 拉起服务\
4. 更新 GitHub Actions