Django-Vue3-Admin 实战指南（一） 树莓派环境下的后端部署与排错

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_SWAPSIZE=2048 sudo systemctl restart dphys-swapfile

1.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：树莓派官方源已移除MySQL
• ARM架构兼容性：部分Python包需要从源码编译
• 硬件性能限制：编译安装时建议添加-j4参数利用多核

2. 数据库部署与配置

2.1 MariaDB安装与安全设置

执行安装后会遇到第一个坑——默认无密码登录：

sudo mysql -u root

在MariaDB控制台执行：

ALTER USER 'root'@'localhost' IDENTIFIED BY '你的密码'; FLUSH PRIVILEGES; exit

2.2 创建项目数据库

为Django-Vue3-Admin创建专用数据库：

CREATE DATABASE dvadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

关键参数说明：

• utf8mb4：支持完整的Unicode字符（包括emoji）
• COLLATE：设置正确的字符串比较规则

实测发现树莓派上的MariaDB默认配置需要调整：

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf # 在[mysqld]下添加： innodb_file_per_table=1 innodb_buffer_pool_size=256M

3. 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

关键故障排查点：

1. 检查/etc/pip.conf是否被系统锁定
2. 安装失败时尝试指定平台：

   pip install --platform linux_armv7l --only-binary=:all: mysqlclient

3. 编译安装前确保已安装开发工具：

   sudo apt install build-essential python3-dev

4. 项目部署实战流程

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.txt

4.2 依赖安装的避坑指南

分步安装依赖更易排查问题：

# 先安装基础依赖 pip install -r requirements.txt --no-deps # 单独处理问题包 pip install mysqlclient --no-cache-dir

常见错误解决方案：

• mysqlclient报错：确保已安装libmariadb-dev
• Pillow安装失败：先安装libjpeg-dev
• cryptography编译错误：升级setuptools

4.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:8000

6.2 生产环境建议

对于长期运行的服务，推荐使用：

nohup python manage.py runserver 0.0.0.0:8000 > django.log 2>&1 &

或者配置为systemd服务：

sudo nano /etc/systemd/system/django.service

服务文件示例：

[Unit] Description=Django Vue3 Admin After=network.target [Service] User=pi 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 Restart=always [Install] WantedBy=multi-user.target

7. 性能优化技巧

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性能是主要瓶颈，建议：

1. 使用高速SD卡或外接SSD
2. 定期清理/var/log目录
3. 禁用不必要的后台服务：

   sudo systemctl disable bluetooth.service