# fs-k8s-fastapi-helper
一个专为Kubernetes环境设计的FastAPI应用健康检查探针助手。
## 项目简介
FS K8s Python Helper 是一个轻量级的Python库，专门为在Kubernetes环境中运行的FastAPI应用提供标准化的健康检查探针。它简化了K8s健康检查的配置，提供了开箱即用的存活探针(liveness probe)和就绪探针(readiness probe)实现。
## 功能特性
- 🚀 **快速集成**: 一行代码即可为FastAPI应用添加K8s健康检查探针
- 🔍 **智能检测**: 支持自定义目标路径的就绪检查
- 🛡️ **完整探针**: 提供启动、存活和就绪三种探针
## 安装
### 从PyPI安装
```bash
pip install fs-k8s-fastapi-helper
```
### 从源码安装
```bash
git clone https://git.firstshare.cn/devops/fs-k8s-fastapi-helper.git
cd fs-k8s-fastapi-helper
pip install -e .
```
### 依赖要求
- Python 3.7+
- FastAPI >= 0.100.0
## 快速开始
### 基本使用
```python
from fastapi import FastAPI
from fs_k8s_fastapi_helper import install_k8s_health_probes
app = FastAPI()
# 安装基本的健康检查探针
install_k8s_health_probes(app)
# 你的应用路由
@app.get("/")
def index():
return {"message": "Welcome to FS K8s Python Helper Demo"}
@app.get("/health")
def ping():
return {"status": "healthy", "service": "demo-app"}
```
> 💡 **更多示例**: 查看 [examples/demo_app.py](examples/demo_app.py) 获取完整的示例应用。
### 自定义配置
```python
from fastapi import FastAPI
from fs_k8s_fastapi_helper import install_k8s_health_probes
app = FastAPI()
# 自定义就绪检查目标路径
install_k8s_health_probes(
app,
custom_readiness_path="/health" # 就绪检查的目标路径
)
```
## API 文档
### 探针端点
#### 启动探针 (Startup Probe)
- **路径**: `/k8s-helper/startup`
- **方法**: GET
- **响应**:
```json
{
"status": "ok"
}
```
#### 存活探针 (Liveness Probe)
- **路径**: `/k8s-helper/liveness`
- **方法**: GET
- **响应**:
```json
{
"status": "ok"
}
```
#### 就绪探针 (Readiness Probe)
- **路径**: `/k8s-helper/readiness`
- **方法**: GET
- **响应**:
```json
{
"status": "ok"
}
```
或当目标路径检查失败时:
```json
{
"status": "degraded",
"target_status": 503
}
```
### 函数参数
#### `install_k8s_health_probes()`
| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `app` | FastAPI | 必需 | FastAPI应用实例 |
| `custom_readiness_path` | Optional[str] | None | 就绪检查的目标路径，如果有自定义的状态检测可传递路径 |
### 常量定义
```python
STARTUP_PATH = "/k8s-helper/startup"
LIVENESS_PATH = "/k8s-helper/liveness"
READINESS_PATH = "/k8s-helper/readiness"
```
## Kubernetes 配置示例
## 使用场景
### 场景1: 基本健康检查
```python
# 仅验证应用是否正常运行
install_k8s_health_probes(app)
```
### 场景2: 依赖服务检查
```python
# 检查应用是否能正常访问数据库或其他依赖服务
install_k8s_health_probes(app, custom_readiness_path="/health")
```
### 场景3: 自定义健康检查
```python
# 检查特定的业务逻辑端点
install_k8s_health_probes(app, custom_readiness_path="/health")
```
## 开发
### 项目结构
```
fs-k8s-fastapi-helper/
├── fs_k8s_fastapi_helper/ # 📦 包源码目录
│ ├── __init__.py # 包初始化文件
│ └── service.py # 核心服务模块
├── tests/ # 🧪 测试目录
├── docs/ # 📚 文档目录
├── examples/ # 🎯 示例应用目录
│ ├── demo_app.py # 🚀 完整示例应用
│ └── README.md # 📖 示例说明文档
├── pyproject.toml # ⚙️ 项目配置（现代化）
├── MANIFEST.in # 📋 文件清单
├── LICENSE # 📄 许可证
└── README.md # 📖 项目文档
```
### 开发环境设置
```bash
# 克隆项目
git clone https://git.firstshare.cn/devops/fs-k8s-fastapi-helper.git
cd fs-k8s-fastapi-helper
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或 venv\Scripts\activate # Windows
# 安装开发依赖
pip install -e .[dev]
# 运行代码格式化
black .
# 运行导入排序
isort .
# 运行测试
pytest
# 运行示例应用
python examples/demo_app.py
```
### 构建和发布
```bash
# 构建包
python -m build --no-isolation --sdist
# 检查包
twine check dist/*
# 上传到TestPyPI（测试）
twine upload --repository testpypi dist/*
# 上传到正式PyPI
twine upload dist/*
```
### 测试健康检查端点
```bash
# 启动示例应用
python examples/demo_app.py
# 或者使用uvicorn
uvicorn examples.demo_app:app --host 0.0.0.0 --port 8000
# 测试启动探针
curl http://localhost:8000/k8s-helper/startup
# 测试存活探针
curl http://localhost:8000/k8s-helper/liveness
# 测试就绪探针
curl http://localhost:8000/k8s-helper/readiness
# 测试自定义健康检查
curl http://localhost:8000/health
```
## 工作原理
1. **启动探针**: 简单的状态检查，确认应用是否已启动完成
2. **存活探针**: 简单的状态检查，确认应用进程是否正常运行
3. **就绪探针**:
- 如果没有设置 `custom_readiness_path`，仅验证应用路由是否注册
- 如果设置了 `custom_readiness_path`，会使用 `TestClient` 在内部发起请求到指定路径
- 如果目标路径返回 4xx 或 5xx 状态码，就绪探针会返回 503 状态码
- 如果请求过程中发生异常，会捕获异常并返回错误信息
## 错误处理
- **目标路径不可达**: 返回 503 状态码和 `degraded` 状态
- **网络异常**: 捕获异常并返回异常类型信息
- **应用异常**: 通过 HTTP 状态码判断服务健康状态
Raw data
{
"_id": null,
"home_page": null,
"name": "fs-k8s-fastapi-helper",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "wuzh <wuzh@fxiaoke.com>",
"keywords": "kubernetes, k8s, fastapi, health-check, probe, liveness, readiness, microservices",
"author": null,
"author_email": "wuzh <wuzh@fxiaoke.com>",
"download_url": "https://files.pythonhosted.org/packages/6f/31/878016b37fcd190a407cb472757d09977c5807b581b4b634ae84f418eedd/fs_k8s_fastapi_helper-0.1.0.tar.gz",
"platform": null,
"description": "# fs-k8s-fastapi-helper\n\n\u4e00\u4e2a\u4e13\u4e3aKubernetes\u73af\u5883\u8bbe\u8ba1\u7684FastAPI\u5e94\u7528\u5065\u5eb7\u68c0\u67e5\u63a2\u9488\u52a9\u624b\u3002\n\n## \u9879\u76ee\u7b80\u4ecb\n\nFS K8s Python Helper \u662f\u4e00\u4e2a\u8f7b\u91cf\u7ea7\u7684Python\u5e93\uff0c\u4e13\u95e8\u4e3a\u5728Kubernetes\u73af\u5883\u4e2d\u8fd0\u884c\u7684FastAPI\u5e94\u7528\u63d0\u4f9b\u6807\u51c6\u5316\u7684\u5065\u5eb7\u68c0\u67e5\u63a2\u9488\u3002\u5b83\u7b80\u5316\u4e86K8s\u5065\u5eb7\u68c0\u67e5\u7684\u914d\u7f6e\uff0c\u63d0\u4f9b\u4e86\u5f00\u7bb1\u5373\u7528\u7684\u5b58\u6d3b\u63a2\u9488(liveness probe)\u548c\u5c31\u7eea\u63a2\u9488(readiness probe)\u5b9e\u73b0\u3002\n\n## \u529f\u80fd\u7279\u6027\n\n- \ud83d\ude80 **\u5feb\u901f\u96c6\u6210**: \u4e00\u884c\u4ee3\u7801\u5373\u53ef\u4e3aFastAPI\u5e94\u7528\u6dfb\u52a0K8s\u5065\u5eb7\u68c0\u67e5\u63a2\u9488\n- \ud83d\udd0d **\u667a\u80fd\u68c0\u6d4b**: \u652f\u6301\u81ea\u5b9a\u4e49\u76ee\u6807\u8def\u5f84\u7684\u5c31\u7eea\u68c0\u67e5\n- \ud83d\udee1\ufe0f **\u5b8c\u6574\u63a2\u9488**: \u63d0\u4f9b\u542f\u52a8\u3001\u5b58\u6d3b\u548c\u5c31\u7eea\u4e09\u79cd\u63a2\u9488\n\n## \u5b89\u88c5\n\n### \u4ecePyPI\u5b89\u88c5\n\n```bash\npip install fs-k8s-fastapi-helper\n```\n\n### \u4ece\u6e90\u7801\u5b89\u88c5\n\n```bash\ngit clone https://git.firstshare.cn/devops/fs-k8s-fastapi-helper.git\ncd fs-k8s-fastapi-helper\npip install -e .\n```\n\n### \u4f9d\u8d56\u8981\u6c42\n\n- Python 3.7+\n- FastAPI >= 0.100.0\n\n## \u5feb\u901f\u5f00\u59cb\n\n### \u57fa\u672c\u4f7f\u7528\n\n```python\nfrom fastapi import FastAPI\nfrom fs_k8s_fastapi_helper import install_k8s_health_probes\n\napp = FastAPI()\n\n# \u5b89\u88c5\u57fa\u672c\u7684\u5065\u5eb7\u68c0\u67e5\u63a2\u9488\ninstall_k8s_health_probes(app)\n\n# \u4f60\u7684\u5e94\u7528\u8def\u7531\n@app.get(\"/\")\ndef index():\n return {\"message\": \"Welcome to FS K8s Python Helper Demo\"}\n\n@app.get(\"/health\")\ndef ping():\n return {\"status\": \"healthy\", \"service\": \"demo-app\"}\n```\n\n> \ud83d\udca1 **\u66f4\u591a\u793a\u4f8b**: \u67e5\u770b [examples/demo_app.py](examples/demo_app.py) \u83b7\u53d6\u5b8c\u6574\u7684\u793a\u4f8b\u5e94\u7528\u3002\n\n### \u81ea\u5b9a\u4e49\u914d\u7f6e\n\n```python\nfrom fastapi import FastAPI\nfrom fs_k8s_fastapi_helper import install_k8s_health_probes\n\napp = FastAPI()\n\n# \u81ea\u5b9a\u4e49\u5c31\u7eea\u68c0\u67e5\u76ee\u6807\u8def\u5f84\ninstall_k8s_health_probes(\n app,\n custom_readiness_path=\"/health\" # \u5c31\u7eea\u68c0\u67e5\u7684\u76ee\u6807\u8def\u5f84\n)\n```\n\n## API \u6587\u6863\n\n### \u63a2\u9488\u7aef\u70b9\n\n#### \u542f\u52a8\u63a2\u9488 (Startup Probe)\n- **\u8def\u5f84**: `/k8s-helper/startup`\n- **\u65b9\u6cd5**: GET\n- **\u54cd\u5e94**: \n ```json\n {\n \"status\": \"ok\"\n }\n ```\n\n#### \u5b58\u6d3b\u63a2\u9488 (Liveness Probe)\n- **\u8def\u5f84**: `/k8s-helper/liveness`\n- **\u65b9\u6cd5**: GET\n- **\u54cd\u5e94**: \n ```json\n {\n \"status\": \"ok\"\n }\n ```\n\n#### \u5c31\u7eea\u63a2\u9488 (Readiness Probe)\n- **\u8def\u5f84**: `/k8s-helper/readiness`\n- **\u65b9\u6cd5**: GET\n- **\u54cd\u5e94**:\n ```json\n {\n \"status\": \"ok\"\n }\n ```\n \u6216\u5f53\u76ee\u6807\u8def\u5f84\u68c0\u67e5\u5931\u8d25\u65f6:\n ```json\n {\n \"status\": \"degraded\",\n \"target_status\": 503\n }\n ```\n\n### \u51fd\u6570\u53c2\u6570\n\n#### `install_k8s_health_probes()`\n\n| \u53c2\u6570 | \u7c7b\u578b | \u9ed8\u8ba4\u503c | \u63cf\u8ff0 |\n|------|------|--------|------|\n| `app` | FastAPI | \u5fc5\u9700 | FastAPI\u5e94\u7528\u5b9e\u4f8b |\n| `custom_readiness_path` | Optional[str] | None | \u5c31\u7eea\u68c0\u67e5\u7684\u76ee\u6807\u8def\u5f84\uff0c\u5982\u679c\u6709\u81ea\u5b9a\u4e49\u7684\u72b6\u6001\u68c0\u6d4b\u53ef\u4f20\u9012\u8def\u5f84 |\n\n### \u5e38\u91cf\u5b9a\u4e49\n\n```python\nSTARTUP_PATH = \"/k8s-helper/startup\"\nLIVENESS_PATH = \"/k8s-helper/liveness\"\nREADINESS_PATH = \"/k8s-helper/readiness\"\n```\n\n## Kubernetes \u914d\u7f6e\u793a\u4f8b\n\n\n## \u4f7f\u7528\u573a\u666f\n\n### \u573a\u666f1: \u57fa\u672c\u5065\u5eb7\u68c0\u67e5\n```python\n# \u4ec5\u9a8c\u8bc1\u5e94\u7528\u662f\u5426\u6b63\u5e38\u8fd0\u884c\ninstall_k8s_health_probes(app)\n```\n\n### \u573a\u666f2: \u4f9d\u8d56\u670d\u52a1\u68c0\u67e5\n```python\n# \u68c0\u67e5\u5e94\u7528\u662f\u5426\u80fd\u6b63\u5e38\u8bbf\u95ee\u6570\u636e\u5e93\u6216\u5176\u4ed6\u4f9d\u8d56\u670d\u52a1\ninstall_k8s_health_probes(app, custom_readiness_path=\"/health\")\n```\n\n### \u573a\u666f3: \u81ea\u5b9a\u4e49\u5065\u5eb7\u68c0\u67e5\n```python\n# \u68c0\u67e5\u7279\u5b9a\u7684\u4e1a\u52a1\u903b\u8f91\u7aef\u70b9\ninstall_k8s_health_probes(app, custom_readiness_path=\"/health\")\n```\n\n## \u5f00\u53d1\n\n### \u9879\u76ee\u7ed3\u6784\n\n```\nfs-k8s-fastapi-helper/\n\u251c\u2500\u2500 fs_k8s_fastapi_helper/ # \ud83d\udce6 \u5305\u6e90\u7801\u76ee\u5f55\n\u2502 \u251c\u2500\u2500 __init__.py # \u5305\u521d\u59cb\u5316\u6587\u4ef6\n\u2502 \u2514\u2500\u2500 service.py # \u6838\u5fc3\u670d\u52a1\u6a21\u5757\n\u251c\u2500\u2500 tests/ # \ud83e\uddea \u6d4b\u8bd5\u76ee\u5f55\n\u251c\u2500\u2500 docs/ # \ud83d\udcda \u6587\u6863\u76ee\u5f55\n\u251c\u2500\u2500 examples/ # \ud83c\udfaf \u793a\u4f8b\u5e94\u7528\u76ee\u5f55\n\u2502 \u251c\u2500\u2500 demo_app.py # \ud83d\ude80 \u5b8c\u6574\u793a\u4f8b\u5e94\u7528\n\u2502 \u2514\u2500\u2500 README.md # \ud83d\udcd6 \u793a\u4f8b\u8bf4\u660e\u6587\u6863\n\u251c\u2500\u2500 pyproject.toml # \u2699\ufe0f \u9879\u76ee\u914d\u7f6e\uff08\u73b0\u4ee3\u5316\uff09\n\u251c\u2500\u2500 MANIFEST.in # \ud83d\udccb \u6587\u4ef6\u6e05\u5355\n\u251c\u2500\u2500 LICENSE # \ud83d\udcc4 \u8bb8\u53ef\u8bc1\n\u2514\u2500\u2500 README.md # \ud83d\udcd6 \u9879\u76ee\u6587\u6863\n```\n\n### \u5f00\u53d1\u73af\u5883\u8bbe\u7f6e\n\n```bash\n# \u514b\u9686\u9879\u76ee\ngit clone https://git.firstshare.cn/devops/fs-k8s-fastapi-helper.git\ncd fs-k8s-fastapi-helper\n\n# \u521b\u5efa\u865a\u62df\u73af\u5883\npython -m venv venv\nsource venv/bin/activate # Linux/Mac\n# \u6216 venv\\Scripts\\activate # Windows\n\n# \u5b89\u88c5\u5f00\u53d1\u4f9d\u8d56\npip install -e .[dev]\n\n# \u8fd0\u884c\u4ee3\u7801\u683c\u5f0f\u5316\nblack .\n\n# \u8fd0\u884c\u5bfc\u5165\u6392\u5e8f\nisort .\n\n# \u8fd0\u884c\u6d4b\u8bd5\npytest\n\n# \u8fd0\u884c\u793a\u4f8b\u5e94\u7528\npython examples/demo_app.py\n```\n\n### \u6784\u5efa\u548c\u53d1\u5e03\n\n```bash\n# \u6784\u5efa\u5305\npython -m build --no-isolation --sdist\n\n# \u68c0\u67e5\u5305\ntwine check dist/*\n\n# \u4e0a\u4f20\u5230TestPyPI\uff08\u6d4b\u8bd5\uff09\ntwine upload --repository testpypi dist/*\n\n# \u4e0a\u4f20\u5230\u6b63\u5f0fPyPI\ntwine upload dist/*\n```\n\n### \u6d4b\u8bd5\u5065\u5eb7\u68c0\u67e5\u7aef\u70b9\n\n```bash\n# \u542f\u52a8\u793a\u4f8b\u5e94\u7528\npython examples/demo_app.py\n\n# \u6216\u8005\u4f7f\u7528uvicorn\nuvicorn examples.demo_app:app --host 0.0.0.0 --port 8000\n\n# \u6d4b\u8bd5\u542f\u52a8\u63a2\u9488\ncurl http://localhost:8000/k8s-helper/startup\n\n# \u6d4b\u8bd5\u5b58\u6d3b\u63a2\u9488\ncurl http://localhost:8000/k8s-helper/liveness\n\n# \u6d4b\u8bd5\u5c31\u7eea\u63a2\u9488\ncurl http://localhost:8000/k8s-helper/readiness\n\n# \u6d4b\u8bd5\u81ea\u5b9a\u4e49\u5065\u5eb7\u68c0\u67e5\ncurl http://localhost:8000/health\n\n```\n\n## \u5de5\u4f5c\u539f\u7406\n\n1. **\u542f\u52a8\u63a2\u9488**: \u7b80\u5355\u7684\u72b6\u6001\u68c0\u67e5\uff0c\u786e\u8ba4\u5e94\u7528\u662f\u5426\u5df2\u542f\u52a8\u5b8c\u6210\n2. **\u5b58\u6d3b\u63a2\u9488**: \u7b80\u5355\u7684\u72b6\u6001\u68c0\u67e5\uff0c\u786e\u8ba4\u5e94\u7528\u8fdb\u7a0b\u662f\u5426\u6b63\u5e38\u8fd0\u884c\n3. **\u5c31\u7eea\u63a2\u9488**: \n - \u5982\u679c\u6ca1\u6709\u8bbe\u7f6e `custom_readiness_path`\uff0c\u4ec5\u9a8c\u8bc1\u5e94\u7528\u8def\u7531\u662f\u5426\u6ce8\u518c\n- \u5982\u679c\u8bbe\u7f6e\u4e86 `custom_readiness_path`\uff0c\u4f1a\u4f7f\u7528 `TestClient` \u5728\u5185\u90e8\u53d1\u8d77\u8bf7\u6c42\u5230\u6307\u5b9a\u8def\u5f84\n - \u5982\u679c\u76ee\u6807\u8def\u5f84\u8fd4\u56de 4xx \u6216 5xx \u72b6\u6001\u7801\uff0c\u5c31\u7eea\u63a2\u9488\u4f1a\u8fd4\u56de 503 \u72b6\u6001\u7801\n - \u5982\u679c\u8bf7\u6c42\u8fc7\u7a0b\u4e2d\u53d1\u751f\u5f02\u5e38\uff0c\u4f1a\u6355\u83b7\u5f02\u5e38\u5e76\u8fd4\u56de\u9519\u8bef\u4fe1\u606f\n\n## \u9519\u8bef\u5904\u7406\n\n- **\u76ee\u6807\u8def\u5f84\u4e0d\u53ef\u8fbe**: \u8fd4\u56de 503 \u72b6\u6001\u7801\u548c `degraded` \u72b6\u6001\n- **\u7f51\u7edc\u5f02\u5e38**: \u6355\u83b7\u5f02\u5e38\u5e76\u8fd4\u56de\u5f02\u5e38\u7c7b\u578b\u4fe1\u606f\n- **\u5e94\u7528\u5f02\u5e38**: \u901a\u8fc7 HTTP \u72b6\u6001\u7801\u5224\u65ad\u670d\u52a1\u5065\u5eb7\u72b6\u6001\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Kubernetes health check probe helper for FastAPI applications",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://git.firstshare.cn/devops/fs-k8s-fastapi-helper/-/issues",
"Documentation": "https://git.firstshare.cn/devops/fs-k8s-fastapi-helper",
"Homepage": "https://git.firstshare.cn/devops/fs-k8s-fastapi-helper",
"Repository": "https://git.firstshare.cn/devops/fs-k8s-fastapi-helper"
},
"split_keywords": [
"kubernetes",
" k8s",
" fastapi",
" health-check",
" probe",
" liveness",
" readiness",
" microservices"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6f31878016b37fcd190a407cb472757d09977c5807b581b4b634ae84f418eedd",
"md5": "b17be131f509332a2567508745711024",
"sha256": "a7d870cbcbd062218e630cab1c20553a048acdbfa3afbc6bb487869896c91485"
},
"downloads": -1,
"filename": "fs_k8s_fastapi_helper-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b17be131f509332a2567508745711024",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7968,
"upload_time": "2025-08-28T07:28:07",
"upload_time_iso_8601": "2025-08-28T07:28:07.637977Z",
"url": "https://files.pythonhosted.org/packages/6f/31/878016b37fcd190a407cb472757d09977c5807b581b4b634ae84f418eedd/fs_k8s_fastapi_helper-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 07:28:07",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "fs-k8s-fastapi-helper"
}
JSON