---
# System prepended metadata

title: "\U0001F433 Docker 教學指南：Python / FastAPI 專案實作"

---

# 🐳 Docker 教學指南：Python / FastAPI 專案實作

筆記：如何將 Python（例如 FastAPI）專案使用 Docker 部署，並整合 Docker Compose 管理服務。

---

## 📦 一、建立 Dockerfile

在你的專案根目錄新增 `Dockerfile`：

```Dockerfile
# 使用官方 Python 映像（建議使用 slim 或 alpine 減少體積）
FROM python:3.11-slim

# 安裝必要系統套件
RUN apt-get update && apt-get install -y \
    git wget curl build-essential \
    && rm -rf /var/lib/apt/lists/*

# 設定容器內工作目錄
WORKDIR /app

# 複製 requirements 並安裝套件（建議優先做，利於快取）
COPY requirements.txt .
RUN pip install --upgrade pip \
 && pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

# 複製專案其他程式碼
COPY . .

# 預設啟動 FastAPI API（可根據你的主程式路徑調整）
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```
## 二、撰寫 .dockerignore
與 .gitignore 類似，避免把無關或敏感資料打包進 image：

```.dockerignore
__pycache__/
*.pyc
.venv/
.env
.git/
*.log
*.pkl
*.ipynb
```

## 三、建立 requirements.txt
```bash
pip freeze > requirements.txt
```

## 四、使用 Docker Compose

```docker-compose.yml
version: "3.9"

services:
  rag-app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: rag-app
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
    env_file:
      - .env
``` 

## 五、啟動與關閉container
啟動
```bash
docker-compose up --build
```

關閉
```bash
docker-compose down
```

## 六、常用 Docker 指令

以下是開發與部署常用的 Docker 指令對照表：

| 功能說明           | 指令 |
|--------------------|------|
| 建立映像（Image）      | `docker build -t my-image-name .` |
| 執行容器（啟動應用）   | `docker run -it -p 8000:8000 my-image-name` |
| 進入容器內部（互動模式）| `docker run -it my-image-name bash` |
| 查看所有容器           | `docker ps -a` |
| 停止容器              | `docker stop <容器ID或名稱>` |
| 刪除容器              | `docker rm <容器ID或名稱>` |
| 刪除映像              | `docker rmi <imageID或名稱>` |
| 查看 Image 清單        | `docker images` |
| 查看容器日誌           | `docker logs <容器ID或名稱>` |
| 清理未使用映像/容器    | `docker system prune -f` |

## 七、專案建議架構
```css
project-root/
├── app/
│   └── main.py
├── src/
├── data/
├── .env
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── .dockerignore
```


