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. 修复命令

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

ports:
  - "3307:3306"

4. 优势

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

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

1. 报错核心

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

2. 错误配置（坑点）

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

3. 原因

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

4. 正确配置

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. 正确数据库链接

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 添加依赖：

cryptography>=3.4.7

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

1. 原因

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

2. 修复（Dockerfile 关键配置）

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

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

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

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

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 最终无错版

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 必备依赖

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

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

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

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

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

到此这篇关于Docker+FastAPI+MySQL项目部署报错汇总的文章就介绍到这了,更多相关Docker+FastAPI+MySQL部署报错内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

最新评论