Note

这是「Mix Space + Yohaku 部署系列」的第二篇，专注于前端主题 Yohaku 的安装。如尚未部署后端，请先阅读第一篇——《从零开始 · 用 1Panel 部署 Mix Space 后端》

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

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

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

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

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

第一步 · 构建 Docker 镜像

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

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

1.1 Fork 构建仓库

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

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

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

访问路径：

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

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

1.3 配置仓库 Actions 变量

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

添加以下两个变量：

1.4 启用并触发构建

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

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

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

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

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

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

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

第二步 · 通过 1Panel 安装 Yohaku

2.1 上传应用包

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

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

2.2 解压，注意路径！

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

2.3 同步本地应用

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

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

2.4 填写安装配置项

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

🐳 镜像地址（Image Address）

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

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

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

📡 公开 API 地址（PUBLICAPIURL）

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

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

🌐 公开网关地址（PUBLICGATEWAYURL）

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

不需要加任何路径后缀。

🔗 API URL 与客户端 API 地址

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

2.5 开始安装 🎉

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

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

第三步 · 配置反向代理与 HTTPS

参见上篇博客，若已配置可略过。

附：Yohaku 支持的扩展 Markdown 语法

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

数学公式（KaTeX）

行内公式：

块级公式：

提示横幅（Notice / Banner）

GFM Alert 语法

剧透遮罩（Spoiler）

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

富链接（Rich Link）

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

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

内联链接图标

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

Mention（提及）

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

折叠块（Collapse）

常见问题

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：页面能访问，但提示后端连接失败？

检查以下几点：

• 四个 API 地址配置项是否填写正确，尤其是 /api/v2 路径不能遗漏
• Mix Space 后端的 ALLOWED_ORIGINS 中是否已包含 Yohaku 前端的域名
• 后端反向代理和 HTTPS 证书是否正常工作

参考资料

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

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

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