1. 树莓派环境准备与系统配置在树莓派上部署Django-Vue3-Admin项目前需要先完成基础环境配置。树莓派官方推荐的Raspberry Pi OS是基于Debian的Linux发行版与常见的Ubuntu系统存在一些差异这里我整理了实际部署时遇到的典型问题。1.1 系统镜像选择与初始化推荐使用64位Raspberry Pi OS Lite版本无桌面环境通过以下命令检查系统版本cat /etc/os-release系统初始化建议使用raspi-config工具扩展文件系统设置合适的时区Asia/Shanghai启用SSH远程访问部署必备配置静态IP避免开发过程中IP变化注意树莓派4B/5的性能足够运行完整项目但建议分配至少2GB交换空间sudo nano /etc/dphys-swapfile # 修改CONF_SWAPSIZE2048 sudo systemctl restart dphys-swapfile1.2 必备软件包安装树莓派默认源可能缺少部分依赖建议先更新源sudo apt update sudo apt upgrade -y sudo apt install -y git python3-pip mariadb-server libmariadb-dev \ libjpeg-dev zlib1g-dev libpq-dev libffi-dev与常规Linux环境的主要差异MariaDB替代MySQL树莓派官方源已移除MySQLARM架构兼容性部分Python包需要从源码编译硬件性能限制编译安装时建议添加-j4参数利用多核2. 数据库部署与配置2.1 MariaDB安装与安全设置执行安装后会遇到第一个坑——默认无密码登录sudo mysql -u root在MariaDB控制台执行ALTER USER rootlocalhost IDENTIFIED BY 你的密码; FLUSH PRIVILEGES; exit2.2 创建项目数据库为Django-Vue3-Admin创建专用数据库CREATE DATABASE dvadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;关键参数说明utf8mb4支持完整的Unicode字符包括emojiCOLLATE设置正确的字符串比较规则实测发现树莓派上的MariaDB默认配置需要调整sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf # 在[mysqld]下添加 innodb_file_per_table1 innodb_buffer_pool_size256M3. Python环境配置技巧3.1 虚拟环境创建与激活在项目目录中创建隔离环境python3 -m venv dvadmin_env source dvadmin_env/bin/activate验证激活成功which python # 应显示虚拟环境路径3.2 解决树莓派特有的pip安装问题树莓派默认使用piwheels源但某些包需要从源码编译。建议修改pip配置pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple关键故障排查点检查/etc/pip.conf是否被系统锁定安装失败时尝试指定平台pip install --platform linux_armv7l --only-binary:all: mysqlclient编译安装前确保已安装开发工具sudo apt install build-essential python3-dev4. 项目部署实战流程4.1 源码获取与目录结构克隆项目并检查关键目录git clone https://gitee.com/huge-dream/django-vue3-admin.git cd django-vue3-admin/backend tree -L 2典型结构├── application # 应用模块 ├── conf # 配置文件 │ ├── env.example.py ├── static # 静态资源 └── requirements.txt4.2 依赖安装的避坑指南分步安装依赖更易排查问题# 先安装基础依赖 pip install -r requirements.txt --no-deps # 单独处理问题包 pip install mysqlclient --no-cache-dir常见错误解决方案mysqlclient报错确保已安装libmariadb-devPillow安装失败先安装libjpeg-devcryptography编译错误升级setuptools4.3 环境配置文件调整复制并修改环境配置cp conf/env.example.py conf/env.py nano conf/env.py关键配置项DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: dvadmin, USER: root, PASSWORD: 你的密码, HOST: localhost, PORT: 3306, OPTIONS: {charset: utf8mb4} } }5. 数据库迁移与初始化5.1 执行数据迁移在虚拟环境中依次执行python manage.py makemigrations python manage.py migrate可能遇到的问题表已存在错误删除migrations目录后重试字符集不匹配检查数据库创建时的参数5.2 初始化基础数据加载预置的权限数据和地区信息python manage.py init python manage.py init_area初始化过程可能较慢树莓派性能限制建议耐心等待。6. 服务启动与测试6.1 开发模式运行启动测试服务器python manage.py runserver 0.0.0.0:8000访问测试本地访问http://127.0.0.1:8000/api/admin/局域网访问http://树莓派IP:80006.2 生产环境建议对于长期运行的服务推荐使用nohup python manage.py runserver 0.0.0.0:8000 django.log 21 或者配置为systemd服务sudo nano /etc/systemd/system/django.service服务文件示例[Unit] DescriptionDjango Vue3 Admin Afternetwork.target [Service] Userpi WorkingDirectory/home/pi/django-vue3-admin/backend ExecStart/home/pi/django-vue3-admin/backend/dvadmin_env/bin/python manage.py runserver 0.0.0.0:8000 Restartalways [Install] WantedBymulti-user.target7. 性能优化技巧7.1 数据库连接优化在conf/env.py中添加DATABASES[default][OPTIONS] { connect_timeout: 10, read_default_file: /etc/mysql/my.cnf }7.2 静态文件处理生产环境建议python manage.py collectstatic sudo apt install nginx配置nginx反向代理静态文件减轻树莓派负载。我在实际部署中发现树莓派的I/O性能是主要瓶颈建议使用高速SD卡或外接SSD定期清理/var/log目录禁用不必要的后台服务sudo systemctl disable bluetooth.service