mx-spaceの構築プロセス記録

前言#

如你所见，我的个人主页进行了一点点改动。之前是站长用 MDUI 完全手搓的页面 (存档)，但是很明显，这玩意非常的粗糙，而且并没有发布内容的功能。而前不久，看到有朋友在玩 mx-space，看了一下感觉挺不错的，于是乎就花了一点时间部署到了咱的个人主页上。

写这篇文章主要是想记录一下，搭建这玩意把我从晚上折腾到早上六点钟，因为官方文档的坑太多了（这点真的要吐槽，按照文档都不一定能把站建出来），所以还是把自己搭建的过程写出来，一来是让自己的博客上能有点东西（这应该是第一篇文章了），二来也能让后来人少踩点坑

另，本文主要算是对官方文档的补充，所以很多内容都和官方文档一致。由于官方文档在不断更新，遇到本文所述内容与文档存在出入，请优先参考官方文档。

环境准备#

笔者这里使用的是腾讯云轻量新加坡 2C4G，系统是 Debian 10，安装了宝塔面板（当然你也可以不用宝塔，那你得自己会配置反代）

官方文档给的要求是 Linux 内核版本不小于 4.19，且内存大于 1 GiB

Linux 内核版本可以使用命令 uname -r 检查，如果版本要求不符，请自行更换内核 / 系统，这里不再赘述。

因笔者使用的是 Debian 10 系统，包管理器为 apt，这里的教程可能仅适用于 Debian/Ubuntu 及其衍生发行版，其他发行版请自行解决可能遇到的问题

笔者建议安装过程全程在 root 用户下执行（普通用户可使用 sudo -i 切换 root 用户），在普通用户下安装笔者不保证能够成功

依赖安装#

安装所需软件包#

ssh 或其他方式连接终端，执行下述命令

apt update && apt install git curl vim wget git-lfs -y

等待安装完成

安装 Docker（后端依赖）#

使用 Docker 官方提供的一键脚本可以快速安装

curl -fsSL https://get.docker.com | bash -s docker

# 中国大陆服务器请执行以下命令以使用镜像源
curl -fsSL https://get.docker.com | bash -s docker --mirror AzureChinaCloud

安装完成后，请执行 docker compose version 检查输出内容是否正常

安装 Node.js 及依赖模块（前端依赖）#

这里的话按照 mx-space 官方文档安装 nvm 以便管理 Node.js

如果您和笔者一样使用宝塔面板，请前往宝塔面板 - 软件商店 - 运行环境，安装 PM2管理器

如果您并非宝塔面板用户，请执行以下命令安装 nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

# 中国大陆服务器请执行以下命令以使用镜像源
bash -c "$(curl -fsSL https://gitee.com/RubyKids/nvm-cn/raw/master/install.sh)"

安装完后请重启终端，然后执行 npm -v 检查是否输出内容

接着安装 Node.js

nvm install --lts
# 宝塔面板用户请跳过，安装 PM2管理器 时会自动安装 Node.js

安装所需模块

#中国大陆服务器请先执行以下命令切换镜像源
npm config set registry http://mirrors.cloud.tencent.com/npm/

npm install -g pnpm pm2

部署后端#

拉取 Docker 配置文件#

# 新建文件夹
cd && mkdir -p mx-space/core && cd $_

# 拉取docker-compose.yml 文件
wget https://fastly.jsdelivr.net/gh/mx-space/core@master/docker-compose.yml

# 拉取 Core 配置文件
wget https://fastly.jsdelivr.net/gh/mx-space/core@master/.env.example -O .env

编辑后端 `.env` 环境配置文件#

使用 vim 编辑: vim .env

按下 i 进入编辑模式
然后按照下文进行修改:

# THIS ENV FILE EXAMPLE ONLY FOR DOCKER COMPOSE
# SEE https://docs.docker.com/compose/environment-variables/#the-env-file

#此处填写一个长度不小于16个字符，不大于32个字符的字符串
JWT_SECRET=7294c34e0b28ad28

# 将这里换成你的前端域名。如果允许多个域名访问，用英文逗号,分隔
ALLOWED_ORIGINS=example.com,www.example.com

# must be 64bit
# ===
# 这里并未被新版的文档定义，不推荐修改，如有需要可以尝试：
# openssl rand -hex 32
# 来生成新的 Encrypt_Key。
# ===
ENCRYPT_KEY=593f62860255feb0a914534a43814b9809cc7534da7f5485cd2e3d3c8609acab

修改完成，按下 ESC 退出编辑模式，然后键入 :wq 并回车离开 vim

启动后端#

docker compose up -d

使用 curl 测试后端状态#

执行命令: curl http://127.0.0.1:2333/api/v2
如果正常，那你会看到输出如下所示

root@mx-space:~/mx-space/core# curl http://127.0.0.1:2333/api/v2
{"name":"@mx-space/core","author":"Innei <https://innei.ren>","version":"3.41.2","homepage":"https://github.com/mx-space/core#readme","issues":"https://github.com/mx-space/core/issues"}

到这里，后端部署完成

部署前端#

拉取 Kami 源码#

Kami 是 mx-space 的默认前端，你也可以使用 mx-web-yun 等其他风格的前端

# 拉取源文件
cd && cd mx-space
git clone https://github.com/mx-space/kami.git --depth 1
git clone https://ghproxy.com/github.com/mx-space/kami.git --depth 1 # 中国大陆服务器请执行此命令以使用镜像源

# 切换到最新的 tag
cd kami && git fetch --tags && git checkout $(git rev-list --tags --max-count=1)

#拉取图片文件
git lfs fetch --all
git lfs pull

注意：如果无法正常拉取，可以到 GitHub 上手动下载文件并放到相应目录。

编辑前端 `.env` 环境配置文件#

复制 .env.example 为 .env

cp .env.example .env

使用 vim 编辑: vim .env

它看起来应该是这样的:

# API 地址
NEXT_PUBLIC_API_URL=https://server.test.cn/api/v2
# GATEWAY 地址
NEXT_PUBLIC_GATEWAY_URL=https://server.test.cn
#前端使用的配置项名字
NEXT_PUBLIC_SNIPPET_NAME=kami
# 如果使用 CDN, 修改产物前缀；一般留空
ASSETPREFIX=

在 vim 下，我们可以使用查找替换功能进行快速修改，只需输入 :g/server.test.cn/s//你的域名/g 并回车即可替换原域名

完成后按下 ESC 退出编辑模式，然后键入 :wq 并回车离开 vim

构建 Kami#

# 安装必需的模块
pnpm i
# 构建
pnpm build

编译过程需要一段时间，请保持终端正常连接

启动 Kami#

pnpm prod:pm2

使用 curl 测试前端状态#

执行命令: curl http://127.0.0.1:2333/api/v2
如果有返回结果，则认为正常。

配置反向代理#

笔者这里使用的是宝塔面板且安装了 Nginx，如果您使用的是 Caddy 等其他服务端或未使用宝塔面板请自行摸索

进入宝塔面板 — 网站，设置网站地址并自行解析

新建完成站点到设置 - 反向代理 - 添加反向代理

代理名字随意

目标 URL: http://127.0.0.1:2333 发送域名: $host

保存后点击 配置文件 删除全部内容，并将下方配置文件内容复制进去

#PROXY-START/
# generated 2023-01-25
# by bdovo.cc

location ~* \/(feed|sitemap|atom.xml)
{
    proxy_pass http://127.0.0.1:2333/$1;
    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;
    
    add_header X-Cache $upstream_cache_status;
     
    add_header Cache-Control max-age=60;
} 

location /socket.io {
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_pass http://127.0.0.1:2333/socket.io;
}

location /api
{
    proxy_pass http://127.0.0.1:2333/api;
    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;

    add_header X-Cache $upstream_cache_status;

    #Set Nginx Cache


    set $static_fileJsNv8TWb 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_fileJsNv8TWb 1;
        expires 12h;
        }
    if ( $static_fileJsNv8TWb = 0 )
    {
    add_header Cache-Control no-cache;
    }
}

location /proxy
{
    proxy_pass http://127.0.0.1:2333/proxy;
    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;

    add_header X-Cache $upstream_cache_status;

    #Set Nginx Cache


    set $static_fileJsNv8TWb 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_fileJsNv8TWb 1;
        expires 12h;
        }
    if ( $static_fileJsNv8TWb = 0 )
    {
    add_header Cache-Control no-cache;
    }
}

location /admin #这里可以改成你想要的后台访问路径
{
    proxy_pass http://127.0.0.1:2333/proxy/qaqdmin;
    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;

    add_header X-Cache $upstream_cache_status;

    #Set Nginx Cache


    set $static_fileJsNv8TWb 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_fileJsNv8TWb 1;
        expires 12h;
        }
    if ( $static_fileJsNv8TWb = 0 )
    {
    add_header Cache-Control no-cache;
    }
}

location /
{
    proxy_pass http://127.0.0.1:2323;
    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;

    add_header X-Cache $upstream_cache_status;

    #Set Nginx Cache


    set $static_fileSw1Jy3nG 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_fileSw1Jy3nG 1;
        expires 12h;
    }
    if ( $static_fileSw1Jy3nG = 0 )
    {
    add_header Cache-Control no-cache;
    }
}
#PROXY-END/

配置 SSL 证书#

这里和平常网站搭建一样，以你喜欢的方式配置 SSL 证书

使用宝塔面板的话也可以直接使用面板自带的 Let's Encrypt（配置反代后请使用 DNS 验证）

这里不再赘述，需要的可以自行搜索相关教程

后端初始化#

访问后端地址进行初始化

如果您直接使用的笔者在上文提供的 Nginx 反代配置，那么您应该访问 https://你的域名/admin

然后填写相关信息

你的 API 端点是：

API 地址：https://你的域名/api/v2
Gateway 地址：https://你的域名

而后按照引导，进入初始化流程。如没有顺利进入，尝试刷新 / 退回上一级。

完成#

到这里，你应该可以通过访问域名进入前端页面了。这里部署阶段就告一段落，如果需要进阶设置，请参阅官方文档。

那么，开始使用你的 mx-space 吧。

Enjoy it~

参考资料#

mx-space 官方文档: https://mx-space.js.org
超可爱的前后端分离博客 Mix-space 搭建 - 喵二の小博客: https://www.miaoer.xyz/posts/blog/mx-install
哈喽，Mix Space。- 椎名雪的 Blog: https://shiinayuki.me/posts/experiences/hello_mx-space

此文由 Mix Space 同步更新至 xLog
原始链接为 https://bdovo.cc/posts/experiences/build_mx-space