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