当 FastAPI 应用在 Docker 中因内部错误主动退出（如调用 os.kill(..., SIGTERM)）时，即使配置了 restart: always，容器仍可能无法重启——根本原因在于 Uvicorn 主进程未真正退出，导致 Docker 无法感知到容器已终止。本文提供可靠、生产就绪的修复方案。
当 fastapi 应用在 docker 中因内部错误主动退出（如调用 `os.kill(..., sigterm)`）时，即使配置了 `restart: always`，容器仍可能无法重启——根本原因在于 uvicorn 主进程未真正退出，导致 docker 无法感知到容器已终止。本文提供可靠、生产就绪的修复方案。
在 FastAPI + Docker 场景中，单纯使用 os.kill(os.getpid(), signal.SIGTERM) 并不能保证容器重启，原因在于：Uvicorn 默认以多进程模式运行（主进程 + worker 进程），os.kill() 仅终止当前 Python 线程/进程，而 Uvicorn 主进程可能继续存活，使容器状态保持为 running，Docker 因此不会触发 restart: always 策略。
✅ 正确做法是让应用优雅退出并确保主进程彻底终止。以下是推荐的三步解决方案：
1. 使用 sys.exit(1) 替代 os.kill()
在 startup_event 的异常处理中，应直接退出整个进程，而非仅发送信号：
import sys
import logging
import asyncio
from fastapi import FastAPI
app = FastAPI()
@app.on_event("startup")
async def startup_event() -> None:
logging.info("VP: Starting Server")
task = asyncio.create_task(task_func())
try:
await task
except Exception as error:
logging.error(f"Following exception has occurred: {error}")
logging.info("Shutting down server due to unrecoverable error")
sys.exit(1) # ✅ 强制终止主进程，触发 Docker 重启
@app.on_event("shutdown")
async def shutdown_event() -> None:
logging.info("Shutting down gracefully")
⚠️ 注意：sys.exit(1) 会触发 Uvicorn 的标准退出流程，确保所有资源释放，并使容器进程真实退出（exit code 1），Docker 才能识别并按 restart: always 重启。
2. 补充健康检查端点（增强可观测性与编排兼容性）
虽然 sys.exit(1) 已解决重启问题，但建议添加标准化健康检查接口，便于 Docker、Kubernetes 或负载均衡器进行状态探测：
from fastapi import APIRouter, HTTPException
from typing import Dict
status_router = APIRouter(prefix="/status", tags=["Status"])
@status_router.get("/health")
def health() -> Dict[str, str]:
"""Liveness probe: confirms the app is running and responsive."""
return {"status": "ok"}
@status_router.get("/readiness")
async def readiness() -> Dict[str, str]:
"""Readiness probe: confirms app is ready to serve traffic (e.g., DB reachable)."""
# 示例：替换为实际依赖检查逻辑
if await check_external_dependencies(): # 如数据库连接、缓存等
return {"status": "ok"}
raise HTTPException(status_code=503, detail="Dependency unavailable")
app.include_router(status_router)
3. 配置 Docker Compose 的重启策略与健康检查（可选但强烈推荐）
在 docker-compose.yml 中明确声明重启策略，并启用健康检查以实现更精细的生命周期管理：
services:
events_consumer:
build:
context: ./events_consumer
target: dev
restart: always # ✅ 保持原有配置
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/status/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 40s
? 提示：healthcheck 可辅助监控，但不替代 sys.exit(1)；它主要用于服务发现和流量路由，而非触发重启。重启行为仍由进程退出码决定。
总结
- ❌ 错误方式：os.kill(..., SIGTERM) → 仅终止当前协程或 worker，Uvicorn 主进程可能残留。
- ✅ 正确方式：sys.exit(1) → 终止主进程，Docker 捕获非零退出码，立即执行 restart: always。
- ? 最佳实践：结合 sys.exit(1) + 健康检查端点 + docker-compose 健康探针，构建高可用、可观测、符合云原生规范的 FastAPI 服务。
通过以上调整，您的 FastAPI 容器将在任务函数异常时可靠重启，同时具备生产环境所需的健壮性与运维友好性。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
