MacCMS Tools 安装部署指南

本文将详细介绍如何在基于 Debian 12 的服务器环境中部署 MacCMS Tools —— 一款面向 Apple CMS（苹果CMS）生态的现代化维护与管理平台。本教程以宝塔面板（BT Panel）为操作界面，兼顾命令行用户需求。

系统环境要求

✅ 支持的操作系统

操作系统	最低版本要求	说明
Ubuntu	22.04 +	原生支持
Debian	12 +	原生支持
Rocky Linux	9 +	原生支持
CentOS Stream	9 +	原生支持
AlmaLinux	9 +	原生支持

⚠️ 注意：CentOS 7、Ubuntu 20.04、Debian 11 等旧版系统因依赖库兼容性问题，可能导致安装失败，不建议使用。

一键安装 MacCMS Tools

执行以下命令完成程序自动部署：

curl -sSL https://miui.ink/cdn/maccmstools/sh/install_maccms_tools.sh | sudo bash

当终端提示 “安装完成” 后，程序已成功部署至默认路径 /www/wwwroot/MacCmsTools

在宝塔面板中配置 Python 项目

添加虚拟环境

进入 网站 → Python 项目 → 虚拟环境管理；
点击“添加”，路径填写：/www/wwwroot/MacCmsTools/venv
📌 注意：必须选择项目目录下的 venv 虚拟环境，而非系统级 Python 此设计确保依赖隔离，便于后续卸载（仅需删除项目目录即可，无残留）。

创建新项目

项目名称：MacCmsTools
Python 环境：选择刚添加的 (venv)
启动方式：命令行启动
项目路径：/www/wwwroot/MacCmsTools/backend
启动命令：gunicorn --bind 0.0.0.0:5000 --workers 3 --worker-class uvicorn.workers.UvicornWorker --worker-connections 1000 --threads 2 --timeout 120 --keep-alive 5 --access-logfile /www/wwwroot/MacCmsTools/logs/gunicorn_access.log --error-logfile /www/wwwroot/MacCmsTools/logs/gunicorn_error.log --log-level info --max-requests 1000 --max-requests-jitter 50 --pid /tmp/gunicorn_maccms_tools.pid app_web:app
环境变量：AUTH_RSA_PUBLIC_KEY_PATH=/www/wwwroot/MacCmsTools/auth_public_key.pem
启动用户：www
安装依赖：留空（若宝塔自动填充，请手动清除）

⚠️ 切勿勾选“自动安装依赖”，否则可能覆盖虚拟环境中的正确依赖。

点击“确定”后，宝塔将自动初始化并启动服务。首次启动可能需要数十秒。

域名绑定与反向代理配置

绑定域名

在宝塔面板中为该项目绑定您的自定义域名（如 tools.yourdomain.com）。

开放端口

确保服务器防火墙及安全组已放行 5000 端口（程序监听端口）。

配置 Nginx 反向代理

编辑站点的 Nginx 配置文件，在 server 块底部找到 # proxy 注释区域，替换为以下内容：

⚠️ 未配置此项会导致程序无法授权

location / {
    proxy_pass http://127.0.0.1:5000;
    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 X-Forwarded-Proto $scheme;
    proxy_set_header REMOTE-HOST $remote_addr;
    add_header X-Cache $upstream_cache_status;
    proxy_set_header X-Host $host:$server_port;
    proxy_set_header X-Scheme $scheme;
    proxy_connect_timeout 30s;
    proxy_read_timeout 86400s;
    proxy_send_timeout 30s;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

保存并重载 Nginx 配置。

设置协程

项目名称：MacCmsTools-Scheduler
启动命令：gunicorn --bind 0.0.0.0:5001 --workers 1 --worker-class uvicorn.workers.UvicornWorker --worker-connections 1000 --threads 2 --timeout 120 --keep-alive 5 app_scheduler:app

⚠️ 未设置协程将导致定时任务无法执行，同时程序首页也会提示你调度器未运行

添加协程后如果显示未启动请手动点击启动，并确保主程序和协程都处于运行状态