当然，下面我帮你整理成一版更像博客正文的润色版。整体风格会更自然一些，尽量少堆砌说明，直接讲重点，同时把需要安装的依赖和命令也一并写进去。

用 1Panel 部署 Mix-Space 与 Shiro：一套相对省心的前后端分离方案

之前我的博客一直用的是 Typecho。后来偶然接触到 Mix-Space，这种前后端分离的个人空间方案一下就吸引了我：后端专注内容管理，前端负责展示，整体更灵活，也更方便后期折腾。

这篇文章就记录一下我目前这套部署方案，也顺手给自己留个备忘。

我现在采用的是下面这套组合：

• 后端 Core：用 Docker Compose 部署
• 前端 Shiro：用 GitHub Actions 自动构建并上传服务器
• 反向代理与证书：交给 1Panel 和 OpenResty
• 前端进程管理：使用 PM2

这样做的好处很直接：后端好维护，前端更新也方便，整体结构比较清晰。

先说一下整体思路

Mix-Space 不是传统的一体式博客，它是前后端分离的。

简单理解就是：

• Mix-Space Core 负责后台、API、内容数据、管理功能
• Shiro 负责把这些数据渲染成你看到的网页
• Nginx / OpenResty 负责把不同路径转发到前端或后端
• SSL 证书 负责让网站走 HTTPS

所以最终访问时虽然只有一个域名，但实际上请求会被分发：

• / 走前端
• /api/v2 走后端
• /socket.io 走后端 WebSocket
• /proxy 或你自定义的后台地址，也走后端

理解这一点后，整个部署过程就不会乱。

一、先安装 1Panel

我这里用的是 Ubuntu，直接执行官方安装脚本即可：

安装过程中会提示你设置面板账号、密码和端口。一路按提示走就行，默认值大多也能用，后面都可以在面板里改。

安装完成后，它会输出一份登录信息，记得保存好。后面 Docker、网站、证书、文件管理基本都可以在 1Panel 里完成。

二、后端部署：Mix-Space Core

后端我比较推荐直接用 Docker Compose。这样 MongoDB、Redis 和 Core 可以一起编排，升级和迁移也都方便。

1. 创建目录并拉取配置文件

先在服务器上准备目录：

然后下载官方提供的 docker-compose.yml：

2. 修改后端配置

docker-compose.yml 里有几个地方是必须改的。

ALLOWED_ORIGINS

这个用来控制允许哪些来源访问后端接口。 至少要填上你自己的博客域名，不然前端请求 API 时很容易出现跨域问题。

例如：

JWT_SECRET

这是后台登录和认证相关的密钥，必须自己生成，并且一定要保存好。长度建议按官方要求来，别太短，也不要泄露。

例如：

时区

国内一般直接写：

端口映射

我比较建议不要把 Core 端口直接暴露到公网，而是只监听本地：

这样只有本机上的 OpenResty/Nginx 能访问，更安全一点。

3. 启动后端

修改完配置后，直接启动：

如果没有报错，正常会看到这几个容器跑起来：

• mx-server
• mongo
• redis

到这里，后端就算部署完成了。

4. 后端为什么这样部署

这里简单说一下原理。

Mix-Space Core 本身只是一个服务，它需要：

• MongoDB 存内容数据
• Redis 提供缓存和部分运行支持

Docker Compose 的意义，就是把这三部分一次性编排好，让它们在同一个网络里通信。这样部署的优点就是：

• 环境统一
• 不容易因为系统差异出问题
• 更新时只需要重新拉镜像
• 迁移服务器也方便

三、配置 HTTPS 和反向代理

后端启动后，还不能直接拿来用。因为你还需要：

• 给域名配证书
• 设置 HTTPS
• 把不同路径转发给前端和后端

这些都可以在 1Panel 里做。

1. 申请证书

在 1Panel 里进入：

网站 → 证书

先创建一个 Acme 账户，然后申请证书。

如果你用的是 Cloudflare，建议直接用 DNS 验证，会比较省事。 Cloudflare 那边准备一个 API Token，通常给“区域 DNS 编辑”权限就够用了。

证书申请成功后，绑定到你的网站即可。

2. 创建网站

在 1Panel 里创建一个站点，域名填你自己的。 第一次用通常会提示安装 OpenResty，直接装就行。

这里即使你选择“静态网站”也没关系，因为后面真正的内容访问都靠反向代理。

3. 配置反向代理

核心思路很简单：

• /socket.io 转发到后端
• /api/v2 转发到后端
• /render 转发到后端
• /proxy 和后台路径转发到后端
• / 转发到前端 Shiro

一个常见配置示例如下，直接放到站点配置文件中：

这里的 /qaqdmin 就是后台入口路径，你也可以改成自己喜欢的名字。

配置保存并重载后，后台一般就能通过下面这个地址访问：

四、前端部署：Shiro

后端跑起来后，接下来就是前端。

我这里没有用 Docker 跑前端，而是采用 GitHub Actions 自动构建 + 服务器 PM2 运行 的方式。这样做最大的好处就是更新方便，推一次代码或者手动触发工作流，就能自动部署。

1. 前端部署的大致流程

前端部分其实就几步：

1. Fork 用于部署的 GitHub Actions 仓库
2. 修改 workflow，让它拉取你要构建的 Shiro 仓库
3. GitHub Actions 自动打包前端
4. 通过 SCP 上传到服务器
5. 在服务器解压并切换到新版本
6. 用 PM2 重载服务

说白了，就是把“本地打包上传”这件事交给 GitHub 自动做。

2. 需要安装哪些依赖

因为前端最终是在服务器上运行的，所以服务器还需要装一些运行环境。

我这里用的是 nvm + Node.js + pnpm + pm2 + sharp + unzip。

安装 nvm

安装完成后重新加载 shell：

安装 Node.js

这里我更建议直接装 LTS 版本：

检查版本：

安装 pnpm

安装 pm2 和 sharp

安装 unzip

这些依赖的作用分别是：

• Node.js：运行前端服务
• pnpm：安装项目依赖
• pm2：管理前端进程
• sharp：Next.js 图片处理常用依赖
• unzip：解压 GitHub Actions 上传的构建产物

如果少了其中任何一个，前端部署都可能出问题。

3. 配置 GitHub Actions

接下来需要 Fork 一个用于部署的仓库，比如 shiroi-deploy-action，然后修改里面的 deploy.yml。

这部分最关键的地方有几个。

指定要构建的仓库

如果你用的是闭源版，就填闭源仓库地址；如果是开源版，就改成对应的开源仓库。

配置服务器部署路径

workflow 里会把打包好的 release.zip 传到服务器，再解压到指定目录。 这一步你需要改成自己的路径，比如：

配置 .env 的挂载位置

部署脚本里通常会把固定位置的 .env 文件软链接到当前版本目录中，所以这里的路径必须和你服务器实际存放位置一致。

4. 配置 GitHub Secrets

工作流要能连上服务器、拉取仓库，就必须先配好 Secrets。

常用的有这些：

• HOST：服务器 IP 或域名
• USER：SSH 用户名
• PASSWORD：SSH 密码
• PORT：SSH 端口
• KEY：SSH 私钥，可选
• GH_PAT：用于访问目标仓库的 GitHub Token

一般来说：

• 密码登录和 SSH Key 选一个就够了
• GH_PAT 如果仓库有权限要求，那就是必须的

5. 配置前端 .env

前端运行时还需要 .env 文件，告诉它后端接口在哪里。

例如：

这几个变量分别表示：

• NEXT_PUBLIC_API_URL：后端 API 地址
• NEXT_PUBLIC_GATEWAY_URL：网站主地址
• TMDB_API_KEY：影视信息接口需要时使用
• GH_TOKEN：有些功能会用到 GitHub token

建议把这个 .env 放在一个固定目录，比如：

然后把内容写进去保存即可。

6. 启动工作流部署前端

到这里就差最后一步了：去 GitHub Actions 手动运行 workflow。

如果整套流程没有报错，工作流会自动完成：

• 拉取代码
• 安装依赖
• 构建前端
• 打包上传
• 服务器解压
• PM2 重载

部署完成后，首页就应该能正常打开了。

五、后台里别忘了配置 Shiro 主题

前端虽然已经跑起来了，但 Shiro 还需要一份主题配置，不然页面内容可能不会完整显示。

进入 Mix-Space 后台：

附加功能 → 配置与云函数

新增一项配置：

• 名称：shiro
• 引用：theme
• 数据类型：JSON

然后把你的主题 JSON 填进去。

这里一般会配置：

• 页脚信息
• 链接分组
• 配色
• 背景图
• favicon
• 首页 Hero 文案
• 模块开关

这一部分本质上就是在告诉前端：页面该怎么展示、显示什么内容。

六、让 PM2 开机自动恢复

为了防止服务器重启后前端没有自动起来，建议顺手把 PM2 开机自启也配好。

执行：

如果你后面想手动启动或者查看前端状态，也可以用：

七、这套方案里最容易出错的地方

我自己部署下来，最容易踩坑的基本就是下面这些：

后端配置问题

• ALLOWED_ORIGINS 没写对，导致前端请求失败
• JWT_SECRET 随便填，后面又忘了保存
• 2333 端口直接暴露公网，不够安全

反代问题

• /socket.io 没有正确处理 Upgrade 头
• /api/v2 配错路径
• / 没有转发到前端服务端口

前端部署问题

• workflow 里仓库地址写错
• Secrets 没配全
• .env 路径和部署脚本里写的不一致
• 服务器没安装 unzip 或 sharp

主题配置问题

• 后台没有新增 shiro 配置
• JSON 格式错误
• 填完配置后没有等缓存刷新

参考网址

https://mx-space.js.org/docs/core/docker https://www.vlo.cc/posts/jc/shiroi-deploy-action https://blog.lolita.best/posts/blog/MxspaceDeployShiro