Docker+FastAPI+MySQL 项目部署报错汇总

整理说明：本文档汇总今日部署项目全程遇到的所有致命报错、底层原因、完整修复方案、避坑注意点，全部为实操踩坑总结，可直接复用排查问题。

一、Docker 存储引擎核心踩坑（最关键）

1. 问题现象

本地同时存在 aufs（旧引擎） 和 overlay2（新版默认引擎），想切回旧引擎读取历史镜像数据，修改 daemon.json 后 Docker 直接启动失败。

2. 报错根本原因

新版 Docker（20.10+）彻底废弃不兼容 aufs，强行配置会直接启动失败
两种存储引擎数据完全不互通、不兼容，无法直接切换复用数据
每个 Docker 主机只能同时启用一种存储引擎

3. 最终正确解决方案

禁止手动切换存储引擎，放弃 aufs 旧数据模式
清空损坏的 Docker 临时文件、旧引擎残留文件，重置 Docker 环境
通过重新构建、拉取镜像的方式恢复项目，而非切换引擎

4. 避坑重点

不要修改 /etc/docker/daemon\.json 切换 aufs，新版系统百分百报错；旧镜像数据只能通过 save/load 迁移，无法引擎切换复用。

二、Docker 启动失败、文件损坏问题

1. 问题现象

手动删除 /var/lib/docker 内部文件后，Docker 无法正常启动、拉取镜像报错：no such file or directory（tmp 目录缺失）

2. 原因

手动删除 Docker 内部目录，导致 Docker 运行依赖的 tmp、network 等核心目录缺失，镜像拉取临时读写文件失败。

3. 修复命令

Plain 复制代码

sudo mkdir -p /var/lib/docker/tmp
sudo chmod 700 /var/lib/docker/tmp
sudo chown root:root /var/lib/docker/tmp
sudo systemctl restart docker
sudo docker system prune -f

三、3306 端口占用报错

1. 报错信息

failed to bind host port for 0\.0\.0\.0:3306: address already in use

2. 原因

宿主机本地安装了 MySQL，占用默认 3306 端口，Docker 容器无法绑定端口。

3. 解决方案

修改容器端口映射，主机端口改为 3307，容器内部保留 3306

Plain 复制代码

ports:
  - "3307:3306"

4. 优势

不关闭本地 MySQL，互不冲突，项目可正常运行。

四、MySQL 容器启动报错：MYSQL_USER=root 非法配置

1. 报错核心

MYSQL\_USER=\&\#34;root\&\#34; cannot be used for the root user

2. 错误配置（坑点）

Plain 复制代码

environment:
  MYSQL_ROOT_PASSWORD: 826160
  MYSQL_USER: root      # 致命错误
  MYSQL_PASSWORD: 826160# 致命错误

3. 原因

MySQL 官方规则：MYSQL_USER、MYSQL_PASSWORD 仅用于创建普通用户 ，root 超级管理员只能通过 MYSQL\_ROOT\_PASSWORD 配置。

4. 正确配置

Plain 复制代码

environment:
  MYSQL_ROOT_PASSWORD: 826160
  MYSQL_DATABASE: student_management

五、YAML 语法报错：mapping values are not allowed

1. 原因

docker-compose.yml 缩进混乱、冒号后无空格、混用 Tab 和空格，YAML 对格式极度敏感。

2. 解决方案

全程使用空格缩进，禁止 Tab
所有冒号 : 后面必须加一个空格
使用标准化无语法错误的 compose 配置模板

六、FastAPI 连接 MySQL 127.0.0.1 连接拒绝

1. 报错信息

Can\&\#39;t connect to MySQL server on \&\#39;127\.0\.0\.1\&\#39;

2. 核心大坑（90% 人踩）

Docker 容器内部的 127.0.0.1 是容器自身，不是宿主机，也不是数据库容器。

3. 正确规则

Docker 多容器通信：直接使用服务名通信

数据库服务名：db
连接地址必须为：db:3306

4. 正确数据库链接

Plain 复制代码

DATABASE_URL: mysql+aiomysql://root:826160@db:3306/student_management

七、cryptography 加密依赖报错

1. 报错信息

RuntimeError: \&\#39;cryptography\&\#39; package is required for sha256\_password

2. 原因

MySQL8.0 默认采用 caching\_sha2\_password 加密认证方式，aiomysql 必须依赖 cryptography 库才能连接。

3. 解决方案

在 requirements\.txt 添加依赖：

Plain 复制代码

cryptography>=3.4.7

八、浏览器无法访问 FastAPI 8000 端口

1. 原因

uvicorn 默认监听 127\.0\.0\.1，仅容器内部可访问，外部浏览器无法穿透。

2. 修复（Dockerfile 关键配置）

Plain 复制代码

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

--host 0.0.0.0：允许所有外部IP访问，浏览器可正常打开项目。

九、最终可直接运行的完整配置文件

1. docker-compose.yml（最终无错版）

Plain 复制代码

services:
  db:
    image: swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: 826160
      MYSQL_DATABASE: student_management
    ports:
      - "3307:3306"
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: mysql+aiomysql://root:826160@db:3306/student_management
    depends_on:
      db:
        condition: service_healthy

volumes:
  mysql_data:

2. Dockerfile 最终无错版

Plain 复制代码

FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

3. requirements.txt 必备依赖

Plain 复制代码

fastapi
uvicorn[standard]
sqlalchemy
aiomysql
cryptography>=3.4.7
pydantic

十、项目重启标准命令（最终万能流程）

Plain 复制代码

sudo docker compose down
sudo docker compose up --build -d
sudo docker compose logs -f web

十一、今日核心总结（必记）

新版 Docker 彻底放弃 aufs，禁止手动切换存储引擎
MySQL8.0 不能配置 MYSQL_USER=root
Docker 容器互联必须用服务名，禁止用 127.0.0.1
FastAPI 必须监听 0.0.0.0 才能被浏览器访问
MySQL8.0 连接必须安装 cryptography 依赖
端口冲突直接改宿主机端口，不改动容器内部端口

练习docker部署的链接

https://gitee.com/hajimi1024/docker-practice