整理說明：本文檔匯總今日部署項目全程遇到的所有致命報錯、底層原因、完整修復(fù)方案、避坑注意點，全部為實操踩坑總結(jié)，可直接復(fù)用排查問題。

一、Docker 存儲引擎核心踩坑（最關(guān)鍵）

1. 問題現(xiàn)象

本地同時存在 aufs（舊引擎） 和 overlay2（新版默認(rèn)引擎），想切回舊引擎讀取歷史鏡像數(shù)據(jù)，修改 daemon.json 后 Docker 直接啟動失敗。

2. 報錯根本原因

• 新版 Docker（20.10+）徹底廢棄不兼容 aufs，強行配置會直接啟動失敗
• 兩種存儲引擎數(shù)據(jù)完全不互通、不兼容，無法直接切換復(fù)用數(shù)據(jù)
• 每個 Docker 主機只能同時啟用一種存儲引擎

3. 最終正確解決方案

• 禁止手動切換存儲引擎，放棄 aufs 舊數(shù)據(jù)模式
• 清空損壞的 Docker 臨時文件、舊引擎殘留文件，重置 Docker 環(huán)境
• 通過重新構(gòu)建、拉取鏡像的方式恢復(fù)項目，而非切換引擎

4. 避坑重點

不要修改 /etc/docker/daemon\.json 切換 aufs，新版系統(tǒng)百分百報錯；舊鏡像數(shù)據(jù)只能通過 save/load 遷移，無法引擎切換復(fù)用。

二、Docker 啟動失敗、文件損壞問題

1. 問題現(xiàn)象

手動刪除 /var/lib/docker 內(nèi)部文件后，Docker 無法正常啟動、拉取鏡像報錯：no such file or directory（tmp 目錄缺失）

2. 原因

手動刪除 Docker 內(nèi)部目錄，導(dǎo)致 Docker 運行依賴的 tmp、network 等核心目錄缺失，鏡像拉取臨時讀寫文件失敗。

3. 修復(fù)命令

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，占用默認(rèn) 3306 端口，Docker 容器無法綁定端口。

3. 解決方案

修改容器端口映射，主機端口改為 3307，容器內(nèi)部保留 3306

ports:
  - "3307:3306"

4. 優(yōu)勢

不關(guān)閉本地 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 官方規(guī)則：MYSQL_USER、MYSQL_PASSWORD 僅用于創(chuàng)建普通用戶，root 超級管理員只能通過 MYSQL\_ROOT\_PASSWORD 配置。

4. 正確配置

environment:
  MYSQL_ROOT_PASSWORD: 826160
  MYSQL_DATABASE: student_management

五、YAML 語法報錯：mapping values are not allowed

1. 原因

docker-compose.yml 縮進(jìn)混亂、冒號后無空格、混用 Tab 和空格，YAML 對格式極度敏感。

2. 解決方案

• 全程使用空格縮進(jìn)，禁止 Tab
• 所有冒號 : 后面必須加一個空格
• 使用標(biāo)準(zhǔn)化無語法錯誤的 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 容器內(nèi)部的 127.0.0.1 是容器自身，不是宿主機，也不是數(shù)據(jù)庫容器。

3. 正確規(guī)則

Docker 多容器通信：直接使用服務(wù)名通信

• 數(shù)據(jù)庫服務(wù)名：db
• 連接地址必須為：db:3306

4. 正確數(shù)據(jù)庫鏈接

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 默認(rèn)采用 caching\_sha2\_password 加密認(rèn)證方式，aiomysql 必須依賴 cryptography 庫才能連接。

3. 解決方案

在 requirements\.txt 添加依賴：

cryptography>=3.4.7

八、瀏覽器無法訪問 FastAPI 8000 端口

1. 原因

uvicorn 默認(rèn)監(jiān)聽 127\.0\.0\.1，僅容器內(nèi)部可訪問，外部瀏覽器無法穿透。

2. 修復(fù)（Dockerfile 關(guān)鍵配置）

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

十、項目重啟標(biāo)準(zhǔn)命令（最終萬能流程）

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

十一、今日核心總結(jié)（必記）

1. 新版 Docker 徹底放棄 aufs，禁止手動切換存儲引擎
2. MySQL8.0 不能配置 MYSQL_USER=root
3. Docker 容器互聯(lián)必須用服務(wù)名，禁止用 127.0.0.1
4. FastAPI 必須監(jiān)聽 0.0.0.0 才能被瀏覽器訪問
5. MySQL8.0 連接必須安裝 cryptography 依賴
6. 端口沖突直接改宿主機端口，不改動容器內(nèi)部端口

到此這篇關(guān)于Docker+FastAPI+MySQL項目部署報錯匯總的文章就介紹到這了,更多相關(guān)Docker+FastAPI+MySQL部署報錯內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論