拓展内容

此部分内容将说明一些额外的操作流程，请根据自己需要进行配置

反向代理

在这里提供 Mix-Space 的反代配置步骤。

当然不管使用哪种方法，都建议用控制面板（如宝塔、1Panel 等）完成配置，手写反代配置的大佬随意。

另外，不管是前端还是后端的域名，都需要配置好 HTTPS 证书以保证网站能正常访问。

图形化界面

现代服务器面板（如 1Panel 和宝塔面板）自带的反向代理已足以满足 Mix-Space 所需的反代要求（包括 Websocket），因此我们更建议非高级用户使用图形化界面来操作和维护

宝塔面板

进入网站，在反向代理栏目下点击添加反代

域名填入你将要使用的域名，目标填写URL地址 + http://127.0.0.1:2333

1Panel

进入网站 > 网站,并创建一个新网站，选择反向代理

主域名填入你将要使用的域名，并勾选监听 IPV6，代理类型选择 http ，地址填入 127.0.0.1:2333

Vane

由于 Vane 是一个新开发的反向代理(2025-09-09)，所以请做好出现异常问题的准备，但是不要担心，出现任何代理问题的时候请携带日志给我们，我们会听取你们的反馈，目前已经测试过了 mx-server + Shiroi 请放心使用

Vane 是一个现代的，100% 使用 Rust 编写的反向代理，其优势是大约 1.5-3MB 的内存占用，整 docker 镜像部署大约占用 5MB 磁盘大小详细步骤：

首先使用 SSL 需要先获取证书，Vane 目前不包含 SSL 证书管理，有2个办法是：

1panel & '宝塔面板' 这些 GUI 运维工具自带了 acme.sh 可以GUI管理了给 Vane 导入证书文件
lazy-acme 这是 Vane 配套的管理工具，后端使用 Lego, 目前只支持 Cloudfalre DNS 验证 + 少量主流免费 CA.

如果使用方法1的话，需要你自行映射证书目录给 ~/vane/cert 或者映射其他任何你喜欢的位置，内部存在的 pem 格式证书在下面 zonefile 内部修改使用

关于 Vane 部署，推荐使用 docker-compose.yml 部署

然后需要编写一个 Zone File 采用 TOML 语法, 配置文件默认存放在 "~/vane/config.toml"，Vane 虽然支持 * wildcard 匹配，但是还是建议分离域名管理会方便一些，例如：

# Vane main configuration file
# This file maps hostnames to their specific configuration files.
[domains]
"example.com" = "example.com.toml"
"api.example.com" = "api.example.com.toml"

这样就创建好了2个独立的域名，接下来，在该文件夹内分别创建 example.com.toml 和 api.example.com.toml 注意请替换为实际域名

# Vane domain configuration for example.com
 
# --- Core Protocol Settings ---
# Enable HTTPS on the standard port (443 by default).
https = true
# Enable HTTP/3 over QUIC on the HTTPS UDP port. Requires `https` to be true.
http3 = true
# Enable HSTS (HTTP Strict Transport Security) header to enforce HTTPS on clients.
hsts = true
# Behavior for plain HTTP requests on port 80:
# "upgrade" (redirects to HTTPS), "reject" (blocks), or "allow".
http_options = "reject"
 
# --- TLS Certificate Settings ---
[tls]
# Path to the PEM-encoded TLS certificate file. Supports '~' for the home directory.
cert = "~/vane/cert/example.com.pem"
# Path to the PEM-encoded private key file. Supports '~' for the home directory.
key = "~/vane/cert/example.com.key"
 
# --- Method Filtering ---
# Optional: Restrict which HTTP methods are allowed for this entire domain.
# This check happens before CORS or routing. Use "*" to allow all methods.
[methods]
allow = "GET, POST, OPTIONS, HEAD"
 
# --- CORS (Cross-Origin Resource Sharing) ---
# Optional: Fine-grained CORS configuration.
# If this section is present, Vane will override any CORS headers from the backend.
[cors]
# Map of allowed origins to their allowed methods.
[cors.origins]
# For methods, use a comma-separated string (e.g., "GET, POST"), or use "*" to allow all methods from that origin.
"https://canmi.net" = "GET, POST, OPTIONS"
 
# --- Rate Limiting ---
[rate_limit]
# Default rate limit applied to all requests for this domain unless a more specific rule matches.
[rate_limit.default]
# The time window for the rate limit (e.g., "1s", "10m", "1h").
period = "1s"
# Number of requests allowed in the period. Set to 0 to disable.
requests = 20
 
# --- Routing Rules ---
# Define how incoming paths are proxied to backend targets.
# Rules are matched from top to bottom.
# [[routes]]
# The URL path to match. Supports wildcards (*) at the end.
# path = "/api/*"
# A list of backend servers. Vane will try them in order.
# If the first target fails (connection error or 5xx response), it will try the second, and so on.
# targets = ["http://12.0.0.1:8000", "http://127.0.0.1:33433"] # Primary and fallback targets
 
[[routes]]
path = "/"
websocket = true
targets = ["http://127.0.0.1:2323"]

以及后端 mx-server

# Vane domain configuration for api.example.com
 
https = true
http_options = "reject"
hsts = true
http3 = false
 
[tls]
cert = "~/vane/cert/api.example.com.pem"
key = "~/vane/cert/api.example.com.key"
 
[methods]
allow = "GET, POST, OPTIONS, HEAD"
 
[rate_limit.default]
period = "1s"
requests = 20
 
[[routes]]
path = "/*"
websocket = true
targets = ["http://localhost:2333"]

注意这里 2333 和 2323 端口可能会需要按照你实际部署的 mx-space 来决定端口，如果你自己修改了的话, 以及端口，这里例示使用了 example.com 这个裸域名作为前端，api.example.com 具体域名可能需要按照实际情况修改，当然如果你前端想要部署在三级域名上比如 blog.example.com上也是可以的，按照上述配置修改即可

Cloudflare Tunnel

除非你在非完整服务器环境(如在 Sealos 或 Huggingface Space 上部署)，否则我们不推荐在容器内使用该功能，而应在宿主机内配置 Cloudflare Tunnel 以避免后期出现管理不方便等问题

启动该功能需要两个环境变量

ENABLE_CLOUDFLARED = true
CF_ZERO_TRUST_TOKEN = Tunnel 给的令牌（删掉 cloudflared.exe service install，只保留令牌部分）

详细步骤：

1.申请 Cloudflare Zero Trust，关于申请方式请自行查找

2.添加一条隧道，连接方式选择 Cloudflared，名称任意

3.添加一个 Public Hostname，回源选择 HTTP，端口选择 2333

一旦启动成功，你应当在日志中看到如下输出，并在 Cloudflare 后台看到客户端正常上线：

============================================
Starting Cloudflared Tunnel
============================================

============================================
2025-06-06T02:22:40Z INF Using SysV
2025-06-06T02:22:41Z INF Linux service for cloudflared installed successfully

手写配置

手写配置文件需要较高的技术功底，请量力而行

双域名

这里假定前端域名为 www.example.com，后端为 server.example.com。

以下是后端 server.example.com 反代配置部分

server {
    ## 反向代理开始
    ## 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; 
      add_header Cache-Control no-cache; 
    }
    ## Others
    location / {
      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; 
      proxy_set_header REMOTE-HOST $remote_addr; 
      add_header X-Cache $upstream_cache_status; 
    }
    ## 反向代理结束
}

前端 www.example.com 反代部分

server{
    location ~* \.(gif|png|jpg|css|js|woff|woff2)$ {
      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;
      expires 30d;
    }
    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;
      add_header Cache-Control no-cache;
      proxy_intercept_errors on;
    }
}

如果您使用此部分示例配置 Nginx 反向代理，您的：

API 地址为 https://server.example.com/api/v2
前端（Kami/Shiro）地址为 https://www.example.com
GateWay 为 https://server.example.com
本地后台为 https://server.example.com/proxy/qaqdmin

单域名

以下配置文件以 Nginx 为例，请自行修改 SSL 证书路径以及自己的网站域名。

若使用 Caddy 进行配置可参考 Caddyfile 文件示例进行相应修改。

server {
    ## 反向代理开始 
    ## WebSocket 地址
    location /socket.io {
        proxy_set_header Upgrade $http_upgrade; 
        proxy_set_header Connection "Upgrade"; 
        proxy_buffering off; 
        proxy_set_header Host $host; 
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
        proxy_set_header X-Forwarded-Proto $scheme; 
        proxy_pass http://127.0.0.1:2333/socket.io; 
    }
    ## API 地址
    location /api/v2 {
        proxy_pass http://127.0.0.1:2333/api/v2; 
    }
    ## 简读 render 地址
    location /render {
        proxy_pass http://127.0.0.1:2333/render; 
    }
    ## Kami 地址
    location / {
        proxy_pass http://127.0.0.1:2323; 
    }
    ## 后台地址
    location /proxy {
        proxy_pass http://127.0.0.1:2333/proxy;
    }
    location /qaqdmin {
        proxy_pass http://127.0.0.1:2333/proxy/qaqdmin;
    }
    ## 反向代理结束
}

完整示例如下

server {
    listen 80;
    listen 443 ssl http2 ; 
    ## 绑定域名 
    server_name www.example.com; 
    index index.html; 
    proxy_set_header Host $host; 
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
    proxy_set_header X-Forwarded-Host $server_name; 
    proxy_set_header Upgrade $http_upgrade; 
    proxy_set_header Connection "upgrade"; 
    error_log /www/sites/www.example.com/log/error.log;
    access_log /www/sites/www.example.com/log/access.log; 
    location /socket.io {
        proxy_set_header Upgrade $http_upgrade; 
        proxy_set_header Connection "Upgrade"; 
        proxy_set_header Host $host; 
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
        proxy_set_header X-Forwarded-Proto $scheme; 
        proxy_pass http://127.0.0.1:2333/socket.io; 
    }
    location /api/v2 {
        proxy_pass http://127.0.0.1:2333/api/v2; 
    }
    location /render {
        proxy_pass http://127.0.0.1:2333/render; 
    }
    location / {
        proxy_pass http://127.0.0.1:2323; 
    }
    location /qaqdmin {
        proxy_pass http://127.0.0.1:2333/proxy/qaqdmin;
    }
    location /proxy {
        proxy_pass http://127.0.0.1:2333/proxy;
    }
 
    ssl_certificate /www/sites/www.example.com/ssl/fullchain.pem; 
    ssl_certificate_key /www/sites/www.example.com/ssl/privkey.pem; 
    ssl_protocols TLSv1.3 TLSv1.2 TLSv1.1 TLSv1; 
    ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!3DES:!MD5:!PSK'; 
    ssl_prefer_server_ciphers on; 
    ssl_session_cache shared:SSL:10m; 
    ssl_session_timeout 10m; 
    error_page 497 https://$host$request_uri; 
    limit_conn perserver 300; 
    limit_conn perip 25; 
    limit_rate 512k; 
}

如果您使用此部分示例配置 Nginx 反向代理，您的：

API 地址为 https://www.example.com/api/v2
前端（Kami/Shiro）地址为 https://www.example.com
GateWay 为 https://www.example.com
本地后台为 https://www.example.com/proxy/qaqdmin

配置其他 Redis 服务

如果你需要使用来自 (远端 / 非容器) 的 Redis 服务，你可以通过使用 argv 来动态传入对应的配置项。

支持传入如下值：

redis_host Redis 服务地址，域名、IP 都可以
redis_port Redis 服务端口
redis_password Redis 服务密码
disable_cache 是否禁用缓存，默认不启用

在默认情况下，我们认为这样已经足够了。

对于 Docker 部署

和编辑其他环境变量一样，在 service.app 的 environment 部分添加你需要传入的值，如下所示：

services:
  app:
    container_name: mx-server
    image: innei/mx-server:latest
    environment:
      - TZ=Asia/Shanghai
      - NODE_ENV=production
      - DB_HOST=mongo
      - REDIS_HOST=远端地址 // [!code highlight]
      - REDIS_PASSWORD=redis?passwd // [!code highlight]
      - ALLOWED_ORIGINS=localhost
      - JWT_SECRET=YOUR_SUPER_SECURED_JWT_SECRET_STRING
    volumes:
      - ./data/mx-space:/root/.mx-space

修改完成后 docker compose up -d 重启服务即可。

对于进阶部署

针对这种部署方式，我们可以修改 ecosystem.config.js 在 12 行，也就是 script 这一项，添加你需要传入的值，如下所示：

const { cpus } = require('os')
const { execSync } = require('child_process')
const nodePath = execSync(`npm root --quiet -g`, { encoding: 'utf-8' }).split(
  '\n',
)[0]
 
const cpuLen = cpus().length
module.exports = {
  apps: [
    {
      name: 'mx-server',
-     script: 'out/index.js,
+     script: 'out/index.js --redis_host=远端地址 --redis_password=redis?passwd',
      autorestart: true,
      exec_mode: 'cluster',

当你修改完成，你需要重启服务：

pnpm prod:pm2

配置其他 MongoDB 服务

如果你需要使用来自 (远端 / 非容器) 的 MongoDB 服务，你可以通过使用 argv 来动态传入对应的配置项。

支持传入如下值：（除 collection_name 外其余变量名在 Docker 中变量均为对应大写）

collection_name 数据库集合名字（Docker 对应变量为 DB_COLLECTION_NAME）
db_host MongoDB 服务地址，域名、IP 都可以
db_port MongoDB 服务端口
db_user MongoDB 服务用户名
db_password MongoDB 服务密码
db_connection_string MongoDB 数据库连接地址（以 mongodb:// 开头的一串内容），此配置项优先级大于上述五项
db_options MongoDB 数据库连接选项

如果你需要使用密码登录，你不仅仅需要传入 password，还需要传入 user，建议你对数据库集合划分好用户权限

对于 Docker 部署

和编辑其他环境变量一样，在 services.app 的 environment 部分添加你需要传入的值，如下所示：

services:
  app:
    container_name: mx-server
    image: innei/mx-server:latest
    environment:
      - TZ=Asia/Shanghai
      - NODE_ENV=production
      - DB_HOST=远端地址 // [!code highlight]
      - DB_USER=mongodb-test // [!code highlight]
      - DB_PASSWORD=db?passwd // [!code highlight]
      - REDIS_HOST=redis
      - ALLOWED_ORIGINS=localhost
      - JWT_SECRET=YOUR_SUPER_SECURED_JWT_SECRET_STRING
    volumes:
      - ./data/mx-space:/root/.mx-space

修改完成后 docker compose up -d 重启服务即可。

对于进阶部署

和 Redis 一样，我们可以修改 ecosystem.config.js 在 12 行，也就是 script 这一项，添加你需要传入的值，如下所示：

const { cpus } = require('os')
const { execSync } = require('child_process')
const nodePath = execSync(`npm root --quiet -g`, { encoding: 'utf-8' }).split(
  '\n',
)[0]
 
const cpuLen = cpus().length
module.exports = {
  apps: [
    {
      name: 'mx-server',
+     script: 'out/index.js --db_host=远端地址 --db_user=mongodb-test --db_password=db?passwd',
      autorestart: true,
      exec_mode: 'cluster',

当你修改完成，你需要重启服务：

pnpm prod:pm2

On this page