Spug 源码部署 FAQmysqlclient 编译安装完整指南CentOS 7 及多平台详解【免费下载链接】spugSpug is a lightweight agent-free automatic operation and maintenance platform designed for small and medium-sized enterprises. It integrates host management, host batch execution, host online terminal, file management, application release and deployment, pipelines, online task planning, configuration center, monitoring, alarm and so on.项目地址: https://gitcode.com/gh_mirrors/sp/spug导读本文围绕 Spug 官方文档 docs/FQA.md 中关于mysqlclient安装的 FAQ 展开系统讲解为何 Spug 后端需要 mysqlclient、在 CentOS 7 上编译安装的完整命令与依赖原理并延伸覆盖 Debian/Ubuntu、Docker 镜像等场景帮助你在源码部署 Spug 时一次性解决 MySQL 驱动安装问题。一、FAQ 原文与问题背景Spug 官方文档 docs/FQA.md 中记录了最常被问到的部署问题之一——如何安装mysqlclient原文如下# for centos 7 yum install mariadb-devel python3-devel gcc pip install mysqlclient虽然只有两条命令但背后涉及 Spug 数据库驱动的编译链路、Django ORM 的底层依赖以及不同操作系统的差异。下文将结合仓库源码逐一拆解并给出可直接复制的完整方案。二、为什么 Spug 需要 mysqlclientSpug 后端基于 Django 构建见 spug_api/requirements.txt 中的Django 4.2.0, 4.3.0。Django 操作 MySQL 数据库时需要通过 MySQLdb 协议层与数据库通信而mysqlclient正是 Django 官方推荐的 MySQLdb 实现。在 spug_api/spug/settings.py 中可以看到默认数据库配置为 SQLiteDATABASES { default: { ENGINE: django.db.backends.sqlite3, NAME: BASE_DIR / db.sqlite3, } }而生产部署时docs/install.sh 会生成spug/overrides.py覆盖为 MySQLDATABASES { default: { ATOMIC_REQUESTS: True, ENGINE: django.db.backends.mysql, NAME: spug, USER: spug, PASSWORD: ${DB_PASSWORD}, HOST: 127.0.0.1, OPTIONS: { charset: utf8mb4, sql_mode: STRICT_TRANS_TABLES, } } }该文件由 spug_api/spug/settings.py 在启动时通过from spug.overrides import *自动加载。一旦ENGINE为django.db.backends.mysqlDjango 就会尝试导入MySQLdb模块若环境中缺少 mysqlclient 则直接报错如ModuleNotFoundError: No module named MySQLdb这正是 FAQ 存在的意义。注意requirements.txt中并未显式列出 mysqlclient因为安装脚本将其作为单独的附加包安装见下文这是为了让只用 SQLite 的开发环境保持最小依赖。三、CentOS 7 安装步骤FAQ 原文详解3.1 安装编译依赖mysqlclient 没有提供覆盖所有平台的预编译 wheel在 CentOS 7 上需要从源码编译因此必须先安装三件套yum install mariadb-devel python3-devel gcc三者作用如下包名作用mariadb-devel提供 MySQL 客户端库的头文件与mariadb_config编译 mysqlclient 时通过它探测连接库路径与编译参数python3-devel提供 Python 头文件Python.h编译 C 扩展的必需依赖gccC 编译器mysqlclient 本质是 Python 的 C 扩展这也是 docs/install.sh 中注释所强调的要点mysqlclient 需要 mariadb_configRHEL 8/9 系对应mariadb-connector-c-develCentOS 7 则是mariadb-devel安装脚本用以下命令做了兼容兜底yum install -y mariadb-connector-c-devel || yum install -y mariadb-devel3.2 安装 mysqlclientpip install mysqlclient在 docs/install.sh 中Spug 的正式安装流程是连同项目依赖一起安装并可选指定镜像源加速pip install -U pip wheel -i $PIP_INDEX pip install -r requirements.txt mysqlclient -i $PIP_INDEX国内网络环境下可追加-i https://mirrors.aliyun.com/pypi/simple/等镜像参数以显著加快下载与编译速度。3.3 验证安装安装成功后进入 Spug 后端虚拟环境验证驱动可正常导入cd /data/spug/spug_api # 实际目录以你的安装路径为准 source venv/bin/activate python -c import MySQLdb; print(MySQLdb.__version__)能打印出版本号即说明驱动就绪随后python manage.py migrate等命令即可正常连接 MySQL。四、其他平台的安装差异4.1 Debian / Ubuntu 系在 Debian/Ubuntu 上安装脚本 docs/install.sh 使用 apt 安装等价依赖apt-get install -y git mariadb-server libmariadb-dev python3-dev python3-venv gcc \ pkg-config libsasl2-dev libldap2-dev libssl-dev redis-server nginx supervisor \ rsync sshfs iputils-ping pip install mysqlclient其中libmariadb-dev老版本为libmysqlclient-dev对应 CentOS 7 的mariadb-develpython3-dev对应python3-devel。同时可以注意到该命令还安装了libldap2-dev、libsasl2-dev、libssl-dev这是为了编译 spug_api/requirements.txt 中的python-ldap3.4.3LDAP 登录对接——这也是源码部署时另一类常见的编译报错点建议一并装齐。4.2 Docker 镜像场景官方 Docker 镜像 docs/docker/Dockerfile 预先安装了gcc、pkg-config、default-libmysqlclient-dev等编译依赖并在 docs/docker/Dockerfile 中通过 pip 预装 mysqlclient 及全部运行时依赖RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ \ ... mysqlclient \ cryptography对应的 docs/docker/docker-compose.yml 使用mariadb:10.8镜像作为数据库并以utf8mb4/utf8mb4_unicode_ci字符集初始化。也就是说使用 Docker Compose 部署时无需手动安装 mysqlclient镜像已内置只有走源码部署docs/install.sh或自建虚拟环境时才需要按本文手动安装。五、常见问题排查5.1mariadb_config not found报错编译时提示找不到mariadb_config说明缺少开发头文件包。CentOS 7 安装mariadb-develRHEL 8/9 安装mariadb-connector-c-develDebian/Ubuntu 安装libmariadb-dev然后重新执行pip install mysqlclient。5.2 编译报gcc: error或缺少Python.h说明缺少 C 编译器或 Python 头文件确认gcc与python3-devel已安装。注意若系统同时存在多个 Python 版本需使用与 Spug 虚拟环境一致的 Python 对应版本的python3-devel。5.3 pip 版本过旧导致编译失败建议先升级构建工具链再安装pip install -U pip wheel setuptools pip install mysqlclient5.4 验证数据库连通安装好驱动后可通过 Django 检查命令确认数据库配置无误需先按 docs/install.sh 创建好数据库与账号python manage.py check六、总结mysqlclient是 Spug 源码部署接入 MySQL 的必经环节其安装要点可归纳为三句话先装编译依赖CentOS 7 为mariadb-devel python3-devel gccRHEL 8/9 用mariadb-connector-c-develDebian/Ubuntu 用libmariadb-dev python3-dev gcc再装 Python 包pip install mysqlclient配合-i镜像参数可加速Docker 部署免安装官方镜像 docs/docker/Dockerfile 已内置编译依赖与 mysqlclient直接使用 docs/docker/docker-compose.yml 拉起即可。完整安装流程可参考 docs/install.sh数据库切换逻辑见 spug_api/spug/settings.pyFAQ 原文见 docs/FQA.md。【免费下载链接】spugSpug is a lightweight agent-free automatic operation and maintenance platform designed for small and medium-sized enterprises. It integrates host management, host batch execution, host online terminal, file management, application release and deployment, pipelines, online task planning, configuration center, monitoring, alarm and so on.项目地址: https://gitcode.com/gh_mirrors/sp/spug创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考