1：FastAPI 项目结构

my-fastapi-app/
├── main.py             # 你的 FastAPI 主程序
├── requirements.txt    # 依赖列表
└── Dockerfile          # Docker 构建指令

1.1： main.py

# main.py
import os

from dotenv import load_dotenv
from fastapi import FastAPI
from config import config
from ctl.routers import api_router

app = FastAPI(
    title="ChimichangApp",                    # 标题
    description="学习代码",                  # 描述（支持 Markdown）
    summary="Deadpool 的最爱应用",             # 简介
    version="1.0.0",                          # 版本号
    terms_of_service="http://example.com/terms/",  # 服务条款链接
    contact={                                 # 联系方式
        "name": "开发1",
        "url": "http://mywebsite.com/contact/",
        "email": "li@example.com",
    },
    license_info={                            # 许可证
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
)

# ========= 挂载路由，并统一添加 /api 前缀 =========
app.include_router(
    api_router,
    prefix="/api"
)


# ======== 打印当前注册的路由 ========
print("🔍 当前注册的路由：")
for route in app.routes:
    if hasattr(route, "path"):
        methods = getattr(route, "methods", "N/A")
        if methods != "N/A":
            methods = ", ".join(sorted(methods))
        print(f"  → {route.name} [{methods}] = {route.path}")



# ======== 打印配置 ========
env = config.get("app.profile", "dev")
log_level = config.get("app.log_level", "info")
db_url = config.get("database.url")

print(f"当前环境: {env}")
print(f"日志级别: {log_level}")


# ===================================================
# 🚀 主程序入口：这里是唯一可以“设置环境”的地方
# ===================================================
if __name__ == "__main__":
    import uvicorn

    # ✅ 明确在这里设置环境（你可以注释/修改这行来切换环境）
    os.environ["ENVIRONMENT"] = "test"  # 👈 开发时切换这里，或用命令行传

    # 💡 提示：你也可以注释上一行，改用命令行传：
    #       ENVIRONMENT=prod python main.py

    uvicorn.run("main:app", host="127.0.0.1", port=8084, reload=True)

1.2:requirements.txt

# 工程所有的依赖版本清单 -生成命令
pip freeze > requirements.txt


#内容 -生成内容
aiohappyeyeballs==2.6.1
aiohttp==3.13.1
aiosignal==1.4.0
annotated-types==0.7.0
anyio==4.11.0
attrs==25.4.0
bcrypt==5.0.0
beautifulsoup4==4.14.2
certifi==2025.10.5
cffi==2.0.0
click==8.3.0
colorama==0.4.6
cryptography==46.0.3

2：编写dockerfile

行	指令	作用
FROM ...	选择基础镜像	使用 FastAPI 官方推荐的高性能镜像
WORKDIR /app	设置工作目录	后续操作都在 /app 下进行
COPY requirements.txt .	复制文件	把 requirements.txt 拷贝进容器
RUN pip install ...	安装依赖	安装所有 Python 包
COPY . .	复制代码	把项目所有文件复制进容器
EXPOSE 80	声明端口	说明这个服务监听 80 端口

2.1：tiangolo/uwsgi-nginx-fastapi。

# 1. 基础镜像：使用 tiangolo/uwsgi-nginx-fastapi 镜像
# 它已经预装了 Nginx + uWSGI + FastAPI，开箱即用，性能好
FROM tiangolo/uwsgi-nginx-fastapi:python3.9

# 2. 设置工作目录（容器内的路径）
WORKDIR /app

# 3. 复制依赖文件到容器
COPY requirements.txt .

# 4. 安装 Python 依赖
RUN pip install --no-cache-dir -r requirements.txt

# 5. 复制所有源代码到容器
COPY . .

# 6. （可选）声明运行时端口（只是说明，不是绑定）
EXPOSE 80

生产环境建议用 tiangolo/uwsgi-nginx-fastapi。

2.2:使用 python + uvicorn 的简单 Dockerfile

FROM python:3.9

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# 使用 uvicorn 直接运行
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]

3：构建 Docker 镜像

打开终端，进入你的项目目录：

cd my-fastapi-app

docker build -t my-fastapi-app .

• docker build：构建镜像
• -t my-fastapi-app：给镜像起个名字（tag）
• .：当前目录作为构建上下文

构建成功后，你可以用以下命令查看镜像：

docker images

你会看到类似：

REPOSITORY        TAG       IMAGE ID       CREATED         SIZE
my-fastapi-app    latest    abc123def456   2 minutes ago   150MB

4：运行容器

docker run -d -p 8000:80 --name myapp my-fastapi-app

参数	作用
docker run	运行一个容器
-d	后台运行（detached）
-p 8000:80	端口映射：把宿主机的 8000 映射到容器的 80
--name myapp	给容器起个名字
my-fastapi-app	使用哪个镜像

总结：Docker 部署 FastAPI 的 5 个步骤

步骤	命令/文件	作用
1️⃣ 准备项目	main.py, requirements.txt	写好代码和依赖
2️⃣ 写 Dockerfile	Dockerfile	定义构建流程
3️⃣ 构建镜像	docker build -t name .	打包应用
4️⃣ 运行容器	docker run -p 8000:80 image_name	启动服务
5️⃣ 访问测试	http://localhost:8000	验证是否成功