简介: 本教程将带你从一台空白服务器开始，搭建一套基于 MixSpace (后端) 和 Shiro (前端) 的现代化个人博客系统。我们将采用 Docker 部署后端 + GitHub Actions 自动构建前端 的最佳实践方案。

适用人群: 有基础 Linux 操作能力的博客爱好者 所需时间: 约 30-60 分钟

仅仅适用于赞助（闭源）系统，官方有docker不适用于这套操作，望知悉。

🛠️ 第一章：准备工作

在开始之前，请确保你拥有：

1. 一台 VPS 服务器
   • 推荐配置：2核 2G 内存及以上 (构建前端较吃内存，建议使用 Swap)
   • 系统：Debian 11/12 或 Ubuntu 20.04+
2. 两个域名 (建议托管在 Cloudflare)
   • 前端域名：blog.example.com (用于访问博客)
   • 后端域名：api.example.com (用于管理后台和数据接口)
3. GitHub 账号

🐳 第二章：后端部署 (MixSpace Core)

我们将使用 Docker 快速部署后端。

2.1 环境安装

连接到你的服务器，安装 Docker 和 Docker Compose：

# 更新系统
apt update && apt upgrade -y

# 安装 Docker (使用官方脚本)
curl -fsSL https://get.docker.com | bash

# 启动 Docker
systemctl start docker
systemctl enable docker

2.2 部署 Core

1. 创建部署目录：

   mkdir -p /root/mx-space && cd /root/mx-space
   

2. 创建 docker-compose.yml 文件：

   YAML

   version: "3"
   services:
     mx-server:
       image: innei/mx-server:latest
       container_name: mx-server
       restart: always
       command: /bin/sh -c "exec node apps/core/server.js"
       environment:
         # 替换为你自己的域名
         - ALLOWED_ORIGINS=https://blog.example.com,https://api.example.com
         - JWT_SECRET=你的超长随机字符串
         - ENCRYPT_KEY=你的超长随机字符串(需16位以上)
         - REDIS_HOST=redis
         - DB_URL=mongodb://mongo:27017/mx-space
       ports:
         - "2333:2333"
       depends_on:
         - mongo
         - redis
       links:
         - mongo
         - redis
       volumes:
         - ./data/mx-space:/root/.mx-space
   
     mongo:
       image: mongo:latest
       container_name: mongo
       restart: always
       volumes:
         - ./data/db:/data/db
   
     redis:
       image: redis:latest
       container_name: redis
       restart: always
   

3. 启动后端：

   docker compose up -d
   

4. 初始化： 后端启动后，访问 http://你的服务器IP:2333/proxy/qaqdmin 进入初始化向导，设置管理员账号。

2.3 配置 Shiro 主题 (关键步骤!)

进入后台 -> 配置与云函数 -> 新建配置：

• 名称: shiro (必须全小写)
• 引用: theme (必须全小写)
• 数据类型: 选择 JSON
• 数据内容: (这里可以去 Shiro 官方文档 复制一份默认配置，或者使用你自己的配置 JSON)

⚠️ 注意: 配置保存后，必须执行 docker restart mx-server 重启后端容器才能生效。

⚡ 第三章：前端部署 (Shiro)

为了方便更新维护，我们使用 GitHub Actions 将前端自动部署到你的服务器。

3.1 准备仓库

1. Fork 主题仓库: 访问 https://github.com/innei/Shiroi，点击右上角 Fork。
2. Fork 部署脚本: 访问 https://github.com/innei/shiroi-deploy-action，点击 Fork。

3.2 服务器环境准备

前端运行需要 Node.js 环境。

# 安装 Node.js 20 (使用 nvm 或直接安装)
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs

# 安装进程管理工具 PM2
npm install -g pnpm pm2

创建部署目录：

mkdir -p /root/shiro

创建环境变量文件 /root/shiro/.env：

# 修改为你自己的域名
NEXT_PUBLIC_API_URL=https://api.example.com/api/v2
NEXT_PUBLIC_GATEWAY_URL=https://api.example.com

3.3 配置 GitHub Actions

1. 生成 Token: 在 GitHub Settings -> Developer settings -> Personal access tokens -> Generate new token (Classic)。

   • 勾选 repo 权限。
   • 保存好这个 Token (ghp_xxxx)。

2. 配置 Secrets: 进入你 Fork 的 shiroi-deploy-action 仓库 -> Settings -> Secrets and variables -> Actions。 添加以下 Repository secrets：

   • HOST: 你的服务器 IP
   • USER: root
   • PASSWORD: 服务器密码 (或配置 SSH Key)
   • PORT: 22
   • GH_PAT: 刚刚生成的 GitHub Token

3.4 开始部署

在 shiroi-deploy-action 仓库中，找到 build_hash 文件，点击编辑，随意修改里面的内容 (比如改成 v1.0.0 )，然后 Commit。

GitHub Actions 会自动开始构建，约 5-10 分钟后，你的服务器上就会运行起 Shiro 前端 (默认端口 2323)。

🌐 第四章：Nginx 反向代理配置 (终极版)

这是最重要的一步，配置不好会出现 404 或者跨域错误。假设你使用宝塔面板或手动管理 Nginx。

4.1 后端配置 (api.example.com)

此配置解决了 WebSocket 连接和 CORS 跨域问题。

server {
    listen 80;
    listen 443 ssl http2;
    server_name api.example.com; # 替换你的域名

    # SSL 证书配置 (略)...

    # WebSocket 必须配置!
    location /socket.io {
        proxy_pass http://127.0.0.1:2333/socket.io;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header REMOTE-HOST $remote_addr;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off;
        proxy_http_version 1.1;
    }

    # API 接口 (CORS 修复终极方案)
    location / {
        # 1. 隐藏后端可能返回的头，防止重复
        proxy_hide_header 'Access-Control-Allow-Origin';
        proxy_hide_header 'Access-Control-Allow-Credentials';
        proxy_hide_header 'Access-Control-Allow-Methods';
        
        # 2. Nginx 强制添加标准头
        add_header 'Access-Control-Allow-Origin' 'https://blog.example.com' always; # 你的前端域名
        add_header 'Access-Control-Allow-Credentials' 'true' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS, PATCH' always;
        add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Accept, Origin, User-Agent, DNT, Cache-Control, X-Mx-Cache-Mx, X-Requested-With, x-session-uuid' always;

        # 3. 处理 OPTIONS 预检请求
        if ($request_method = 'OPTIONS') {
            return 204;
        }

        proxy_pass http://127.0.0.1:2333;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

4.2 前端配置 (blog.example.com)

server {
    listen 80;
    listen 443 ssl http2;
    server_name blog.example.com; # 替换你的域名

    location / {
        proxy_pass http://127.0.0.1:2323; # Shiro 默认端口
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

🛑 第五章：常见“坑”与解决方案

Q1: 前端提示 "Initial data fetch fail"，API 404 怎么办？

原因: 后端还没有读取到主题配置。 解决:

1. 检查后台是否正确添加了 name=shiro, ref=theme 的配置。
2. 一定要重启后端容器: docker restart mx-server。

Q2: 浏览器报 CORS 跨域错误？

原因: 前端域名 (blog) 请求后端域名 (api) 时，响应头不对。 解决: 请务必使用本文第四章提供的 Nginx 配置。它使用了“隐藏+覆盖”的策略，能解决绝大多数 CORS 问题（包括“缺少头”和“重复头”）。

Q3: 修改了 .env 但前端没变化？

原因: Next.js 是构建时注入环境变量的。 解决: 修改服务器上的 .env 文件后，必须去 GitHub 仓库修改 build_hash 文件，触发重新构建和部署。单纯重启 PM2 是没用的。

Q4: 部署脚本提示连不上服务器？

解决: 检查 GitHub Secrets 中的 HOST 是否正确，如果改了 SSH 端口，记得更新 PORT 变量。

祝你的博客搭建顺利！🍻