加群联系作者vx：xiaoda0423
仓库地址：https://webvueblog.github.io/JavaPlusDoc/
https://1024bat.cn/
FastAPI 是一个用于构建 API 的现代、快速（高性能）的 web 框架，使用 Python 并基于标准的 Python 类型提示。
关键特性:
快速：可与 NodeJS 和 Go 并肩的极高性能（归功于 Starlette 和 Pydantic）。[最快的 Python web 框架之一]。
高效编码：提高功能开发速度约 200％ 至 300％。*
更少 bug：减少约 40％ 的人为（开发者）导致错误。*
智能：极佳的编辑器支持。处处皆可自动补全，减少调试时间。
简单：设计的易于使用和学习，阅读文档的时间更短。
简短：使代码重复最小化。通过不同的参数声明实现丰富功能。bug 更少。
健壮：生产可用级别的代码。还有自动生成的交互式文档。
标准化：基于（并完全兼容）API 的相关开放标准：[OpenAPI] (以前被称为 Swagger) 和 [JSON Schema]。
FastAPI全栈模板 - 技术栈和特性¶[1]
⚡ FastAPI 用于Python后端API.
-
🧰 SQLModel 用于Python和SQL数据库的集成（ORM）。
🔍 Pydantic FastAPI的依赖项之一，用于数据验证和配置管理。
💾 PostgreSQL 作为SQL数据库。
🚀 React 用于前端。
-
💃 使用了TypeScript、hooks、Vite和其他一些现代化的前端技术栈。
🎨 Chakra UI 用于前端组件。
🤖 一个自动化生成的前端客户端。
🧪 Playwright用于端到端测试。
🦇 支持暗黑主题（Dark mode）。
🐋 Docker Compose 用于开发环境和生产环境。
🔒 默认使用密码哈希来保证安全。
🔑 JWT令牌用于权限验证。
📫 使用邮箱来进行密码恢复。
✅ 单元测试用了Pytest.
📞 Traefik 用于反向代理和负载均衡。
🚢 部署指南（Docker Compose）包含了如何起一个Traefik前端代理来自动化HTTPS认证。
🏭 CI（持续集成）和 CD（持续部署）基于GitHub Actions。
【Python】fastapi框架搭建基础demo
from fastapi import FastAPI
from pydantic import BaseModel
# 创建FastAPI实例
app = FastAPI()
# 定义数据模型
class Item(BaseModel):
name: str
price: float
is_offer: bool = None
# 基础路由
@app.get("/")
def read_root():
return {"Hello": "World"}
# GET请求示例
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q}
# POST请求示例
@app.post("/items/")
def create_item(item: Item):
return item
pip install fastapi
pip install uvicorn
uvicorn main:app --reload
- API服务: http://localhost:8000
- 交互式API文档: http://localhost:8000/docs
- 另一种API文档: http://localhost:8000/redoc下面是一个使用 FastAPI 搭建的基础 Demo，包含：
项目结构
一个 GET 和一个 POST 接口
自动生成的文档（Swagger UI 和 ReDoc）
✅ 1. 安装依赖
pip install fastapi uvicorn开发环境建议加上：
pip install "uvicorn[standard]" python-multipart✅ 2. 项目结构示例
fastapi_demo/
├── main.py # 主程序入口
├── models.py # 数据模型（Pydantic）
├── routers/
│ └── hello.py # 路由模块
└── requirements.txt # 依赖列表（可选）✅ 3. main.py（主入口）
from fastapi import FastAPI
from routers import hello
app = FastAPI(
title="FastAPI Demo",
description="一个简单的 FastAPI 示例项目",
version="0.1.0"
)
app.include_router(hello.router, prefix="/api", tags=["Hello"])✅ 4. routers/hello.py（路由模块）
from fastapi import APIRouter
from models import HelloRequest
router = APIRouter()
@router.get("/hello")
def say_hello(name: str = "World"):
return {"message": f"Hello, {name}!"}
@router.post("/hello")
def receive_hello(data: HelloRequest):
return {"message": f"Received: {data.name}, Age: {data.age}"}✅ 5. models.py（数据模型）
from pydantic import BaseModel
class HelloRequest(BaseModel):
name: str
age: int✅ 6. 启动服务
uvicorn main:app --reload访问：
Swagger 文档: http://127.0.0.1:8000/docs
Redoc 文档: http://127.0.0.1:8000/redoc
# 1) 创建虚拟环境（可选）
python -m venv venv
source venv/bin/activate # Windows 用 venv\Scripts\activate
# 2) 安装依赖
pip install -r requirements.txt
# 3) 启动服务（--reload 自动热重载）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
fastapi-project/
├── app/
│ ├── __init__.py (已创建空文件即可)
│ ├── main.py (已创建)
│ ├── api/
│ │ ├── __init__.py
│ │ ├── endpoints/
│ │ │ ├── __init__.py
│ │ │ └── items.py (创建API端点)
│ ├── core/
│ │ ├── __init__.py
│ │ └── config.py (配置文件)
│ ├── models/
│ │ ├── __init__.py
│ │ └── item.py (数据模型)
│ └── schemas/
│ ├── __init__.py
│ └── item.py (Pydantic模型)
├── tests/
│ ├── __init__.py
│ └── test_main.py
├── .env (环境变量)
├── .gitignore
├── requirements.txt (已创建)
└── README.md
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
python -m app.main你遇到的错误是：
ReadTimeoutError: HTTPSConnectionPool(host='pypi.org', port=443): Read timed out.这说明你的电脑访问 pypi.org（Python 官方包源）时网络连接超时，常见原因有：
网络不稳定或慢（尤其是国内用户）
被墙（访问 pypi.org 不通）
没有科学上网
公司或校园网络限制了 pip 请求
✅ 解决方案（推荐任选其一）：
✅ 方法 1：使用清华大学镜像源（临时方式）
pip install fastapi uvicorn -i https://pypi.tuna.tsinghua.edu.cn/simple如果你使用的是虚拟环境或系统无权限，也可以加 --user：
pip install --user fastapi uvicorn -i https://pypi.tuna.tsinghua.edu.cn/simple✅ 方法 2：配置 pip 默认使用国内源（永久方式）
在你的用户目录下（例如 C:\Users\你的用户名）创建或编辑文件：
pip\pip.ini内容如下：
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
timeout = 60或者使用命令创建配置（推荐）：
mkdir %APPDATA%\pip
notepad %APPDATA%\pip\pip.ini然后粘贴上面的内容保存。
✅ 方法 3：测试 pypi 是否连通
curl https://pypi.org/simple如果这条命令无法获取内容，那就是网络问题，可结合代理/VPN 或镜像源解决。
Nginx-keepalived+Nginx实现高可用集群
要实现 高可用的 Nginx 集群，通常会结合以下两种技术：
Nginx：作为负载均衡器和反向代理
Keepalived：实现主备切换，保证“虚拟 IP”持续可用（即 VIP 高可用）
✅ 一、架构概览图
+-----------------------+
| Client (用户) |
+----------+------------+
|
v
+-----------+-----------+
| VIP（虚拟IP） | ← 由 Keepalived 提供
+-----------+-----------+
|
+----------------------+---------------------+
| |
+-------v-------+ +-------v-------+
| Nginx Master |<---- Keepalived VRRP ---->| Nginx Backup |
+---------------+ +---------------+
| |
| 负载均衡转发后端服务 |
v v
+---------------+ +----------------+
| App Server 1 | | App Server 2 |
+---------------+ +----------------+✅ 二、环境准备（两台机器）
假设：
角色 |
IP |
|---|---|
Nginx-Master |
192.168.1.101 |
Nginx-Backup |
192.168.1.102 |
虚拟IP (VIP) |
192.168.1.100 |
✅ 三、Nginx 配置（主备一样）
配置文件 /etc/nginx/nginx.conf 或自定义转发配置：
http {
upstream backend {
server 192.168.1.201:8000;
server 192.168.1.202:8000;
}
server {
listen 80;
location / {
proxy_pass http://backend;
}
}
}重载配置：
nginx -t && systemctl reload nginx✅ 四、Keepalived 配置
🔸 1. 安装 Keepalived
sudo apt install keepalived # Debian/Ubuntu
sudo yum install keepalived # CentOS🔸 2. 主节点 /etc/keepalived/keepalived.conf
vrrp_instance VI_1 {
state MASTER
interface eth0 # 网卡名，根据实际更换
virtual_router_id 51
priority 100 # 优先级高的为主
advert_int 1
authentication {
auth_type PASS
auth_pass 123456
}
virtual_ipaddress {
192.168.1.100 # 虚拟 IP
}
}🔸 3. 备节点 /etc/keepalived/keepalived.conf
vrrp_instance VI_1 {
state BACKUP
interface eth0
virtual_router_id 51
priority 90 # 优先级低为备
advert_int 1
authentication {
auth_type PASS
auth_pass 123456
}
virtual_ipaddress {
192.168.1.100
}
}✅ 五、启动服务
systemctl enable nginx keepalived
systemctl start nginx keepalived检查 VIP 是否绑定到主节点：
ip addr | grep 192.168.1.100✅ 六、故障切换测试
停掉主节点
keepalived：systemctl stop keepalived用
ping 192.168.1.100观察是否自动转移到备节点。
✅ 七、进阶建议
使用
notify_master、notify_backup脚本自动拉起 Nginx 或做健康检查加防火墙设置允许 VRRP 通信（协议号 112）
可搭配 Redis Sentinel、MySQL MGR 等组件做整套高可用
Nginx + Keepalived 打造高可用反向代理集群
目标：在两台 Nginx 节点之间使用 Keepalived 维护一个虚拟 IP（VIP）。当主节点故障时，VIP 自动漂移到备节点，保证入口层零中断。
1 环境准备
角色 |
主机名 |
IP |
组件 |
|---|---|---|---|
Master |
ngx-ha01 |
192.168.10.11 |
Nginx、Keepalived |
Backup |
ngx-ha02 |
192.168.10.12 |
Nginx, Keepalived |
VIP |
— |
192.168.10.10 |
对外入口 |
操作系统：CentOS 7/Stream 、Rocky Linux 8、Ubuntu 22.04 均可
Nginx：稳定版 ≥ 1.22
Keepalived：≥ 2.2（自带 VRRP + 健康检查脚本功能）
2 安装软件
# 以 RHEL 系列为例
sudo yum install -y epel-release
sudo yum install -y nginx keepalived
sudo systemctl enable nginx keepalived若要自定义 Nginx 编译模块，如
--with-stream，可自行源码安装或使用官方nginx:stable容器镜像配合 Podman/Docker。
3 Nginx 配置（两节点基本一致）
# /etc/nginx/conf.d/upstream.conf ——后端业务池
upstream backend_pool {
server 192.168.10.21:8080 max_fails=3 fail_timeout=15s;
server 192.168.10.22:8080 max_fails=3 fail_timeout=15s;
# 可按需加 backup、weight、health_check 等
}
# /etc/nginx/nginx.conf（仅示例）
http {
include mime.types;
default_type application/octet-stream;
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$request_time"';
access_log /var/log/nginx/access.log main;
sendfile on;
keepalive_timeout 65;
upstream backend_pool; # 引用
server {
listen 80;
server_name _;
location / {
proxy_pass http://backend_pool;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
}# 检查并启动
nginx -t && sudo systemctl restart nginx4 Keepalived 配置
4.1 健康检查脚本（两节点相同）
# /etc/keepalived/check_nginx.sh
#!/bin/bash
pidof nginx >/dev/null 2>&1 || systemctl restart nginx
pidof nginx >/dev/null 2>&1 || exit 1 # 返回 1 触发切换
exit 0chmod +x /etc/keepalived/check_nginx.sh4.2 主节点 /etc/keepalived/keepalived.conf
global_defs {
router_id LVS_NGINX_MASTER
script_user root
}
vrrp_script chk_nginx {
script "/etc/keepalived/check_nginx.sh"
interval 3 # 检查频率
weight -20 # 检查失败扣权重
fall 2 # 连续失败 2 次认为 down
rise 1
}
vrrp_instance VI_1 {
state MASTER
interface eth0 # 网卡名
virtual_router_id 51
priority 100 # 主优先级高
advert_int 1
authentication {
auth_type PASS
auth_pass 123456
}
track_script {
chk_nginx
}
virtual_ipaddress {
192.168.10.10/24 dev eth0 label eth0:vip
}
}4.3 备节点配置
state BACKUPpriority调低，例如90其余保持一致
5 启动服务
sudo systemctl start keepalived
sudo systemctl status keepalived
ip a | grep 192.168.10.10 # 主节点应看到 VIP 绑定6 故障切换验证
Ping VIP：
ping 192.168.10.10停止主节点 Nginx：
sudo systemctl stop nginx # 或模拟停电 `ifdown eth0`1–2 秒内 VIP 应漂移到备节点：
ssh ngx-ha02 "ip a | grep 192.168.10.10" tail -f /var/log/keepalived/keepalived.log恢复主节点后，再次漂移回 Master（优先级高）。
7 进阶与最佳实践
方向 |
关键点 |
推荐 |
|---|---|---|
| 双主模式 | 两节点均 |
若 Front-end 高并发且想把流量平分，可用 Keepalived + LVS-DR 或 layer-4 ECMP |
| 多地域容灾 | Route 53/GTM 或云厂商 GSLB |
按健康探测将流量路由至可用站点 |
| TLS 终端 | 在 Nginx 上启用 |
|
| 状态同步 | Nginx 无状态；若需会话保持，用 JWT／Cookie 粘性、Redis Session、或者后端复制 |
|
| 监控告警 | vrrp_instance 内置通知脚本： |
配合 Prometheus + Alertmanager |
8 常见故障排查
现象 |
可能原因 |
解决方案 |
|---|---|---|
VIP 绑定到两台机器 |
virtual_router_id不一致或多播问题 |
确保两端 |
VRRP 报 “permission denied” |
SELinux / 防火墙阻断 VRRP 112/udp |
firewall-cmd --add-rich-rule='rule protocol value="vrrp" accept' |
健康检查不生效 |
脚本权限 / shebang 失误 |
chmod +x 并在脚本首行 |
Nginx 重启慢导致频繁漂移 |
nginx -s reload耗时或 I/O 阻塞 |
使用更温和的脚本：探测端口 & |
速查清单
安装：
yum install nginx keepalived配置：Nginx 反代 → Keepalived VRRP + 健康脚本
启动：
systemctl enable --now nginx keepalived测试：停止主节点 Nginx → VIP 是否漂移
上线：接入 DNS/CNAME 或负载均衡前端，监控 & 备份配置
在 Nginx 中实现灰度发布（灰度部署 / 灰度路由）主要是通过 请求条件 + 反向代理 来将一部分流量定向到新版本服务（灰度实例），而其它流量仍走旧版本。常见灰度方式如下：
✅ 方式一：基于 IP 做灰度（简单稳定）
map $remote_addr $gray_release {
default 0;
192.168.1.123 1; # 将指定用户 IP 灰度到新版本
}
upstream v1 {
server 10.0.0.1:8000;
}
upstream v2 {
server 10.0.0.2:8000;
}
server {
listen 80;
location / {
if ($gray_release = 1) {
proxy_pass http://v2; # 灰度用户走新服务
}
proxy_pass http://v1; # 默认用户走老服务
}
}✅ 方式二：基于 Cookie 灰度发布（适合 Web 前端）
map $cookie_version $gray_release {
default 0;
v2 1;
}
server {
listen 80;
location / {
if ($gray_release = 1) {
proxy_pass http://v2;
}
proxy_pass http://v1;
}
}前端登录或按钮可以设置 cookie，如：version=v2，即可体验灰度版本。
✅ 方式三：基于 Header 做灰度（适合 API 调试）
map $http_x_gray $gray_release {
default 0;
yes 1;
}
server {
listen 80;
location / {
if ($gray_release = 1) {
proxy_pass http://v2;
}
proxy_pass http://v1;
}
}只需在请求头中添加：X-Gray: yes，即可被路由到新版本。
✅ 方式四：按百分比灰度（高级）
适合做 10%、20% 等比例灰度发布，需用
$request_id或$remote_addrhash 分流。
# hash remote_addr 取模实现分流
map $remote_addr $gray_release {
default 0;
~^.*$ "${remote_addr_hash}"; # 伪代码演示
}
# 或使用第三方模块，例如 openresty + lua 支持👉 推荐使用 OpenResty 或 Nginx + Lua 脚本，进行哈希分桶或自定义规则实现精准灰度。
✅ 补充建议
灰度流量需接入监控、指标、日志追踪
灰度入口需配置超时时间、熔断回退机制
灰度目标建议独立部署（便于动态上线 / 回滚）
以下是完整的 Keepalived + Nginx 高可用集群搭建笔记，适合生产环境部署、测试或笔试复习，含架构、配置、命令步骤。
📘 Keepalived + Nginx 高可用集群搭建笔记
✅ 一、部署目标
实现 Nginx 主备双机热备（高可用）
使用 Keepalived 提供 VIP，客户端始终通过 VIP 访问
任一节点宕机时，自动切换至另一节点
✅ 二、基础架构图
+---------------------+
| 客户端用户 |
+----------+----------+
|
v
虚拟IP（VIP：192.168.1.100）
|
+-----------------+-----------------+
| |
+-------v--------+ +--------v-------+
| Nginx + Keepalived(Master) | Nginx + Keepalived(Backup) |
| IP: 192.168.1.101 | IP: 192.168.1.102 |
+--------------------------------+-----------------------------+✅ 三、环境准备
两台服务器安装好 Linux（如 Ubuntu / CentOS）
已安装 Nginx
安装 Keepalived：
# Ubuntu
sudo apt update && sudo apt install keepalived
# CentOS
sudo yum install keepalived✅ 四、Nginx 配置（主备相同）
编辑 /etc/nginx/nginx.conf（或单独写 upstream）：
http {
upstream backend {
server 192.168.1.201:8000;
server 192.168.1.202:8000;
}
server {
listen 80;
location / {
proxy_pass http://backend;
}
}
}检查并启动：
nginx -t && systemctl restart nginx✅ 五、Keepalived 配置
🔹 主节点 /etc/keepalived/keepalived.conf
vrrp_instance VI_1 {
state MASTER
interface eth0 # 替换为实际网卡名（如 ens33）
virtual_router_id 51
priority 100
advert_int 1
authentication {
auth_type PASS
auth_pass 123456
}
virtual_ipaddress {
192.168.1.100 # 虚拟IP
}
}🔹 备节点配置相同，区别是：
state BACKUP
priority 90说明：
virtual_router_id必须主备一致，priority主 > 备，auth_pass必须一致
✅ 六、启动服务
systemctl enable keepalived
systemctl start keepalived查看 VIP 是否绑定成功：
ip addr | grep 192.168.1.100✅ 七、故障转移测试
关闭主节点 keepalived：
systemctl stop keepalived用客户端
ping 192.168.1.100，应能继续通，说明备节点接管 VIP 成功恢复主节点后，VIP 会自动抢占回来（前提是默认开启
nopreempt = false）
✅ 八、附加配置（推荐）
🔹 健康检查：检测 nginx 状态
/etc/keepalived/keepalived.conf 添加：
vrrp_script chk_nginx {
script "/etc/keepalived/chk_nginx.sh"
interval 2
weight -20
}
vrrp_instance VI_1 {
...
track_script {
chk_nginx
}
}创建脚本 /etc/keepalived/chk_nginx.sh：
#!/bin/bash
pidof nginx >/dev/null || exit 1chmod +x /etc/keepalived/chk_nginx.sh✅ 九、常见问题排查
问题 |
原因 |
解决方案 |
|---|---|---|
VIP 没绑定 |
网卡名错误 |
用 |
不能访问 VIP |
防火墙阻挡 VRRP |
开放协议号 112，或关闭 firewalld |
抢占不生效 |
主机未恢复 |
查看是否开启 |
主备都绑定 VIP |
优先级一样或 VRID 冲突 |
保证 |
✅ 十、延伸：搭配 Nginx 负载均衡 + 灰度发布 + HTTPS
Keepalived 仅负责 IP 高可用
灰度发布策略用 Nginx map + header/cookie 实现
多站点、HTTPS 支持可继续按需配置
做好一次故障演练（Chaos Drill） ，核心目的是验证系统的可用性、监控/告警能力、容灾/自动恢复机制是否健全。下面是一次标准、专业的故障演练流程，适用于互联网后台系统、分布式服务或运维平台：
✅ 一、明确演练目标
不要为了演练而演练，要围绕“验证系统韧性”。
示例目标：
验证主备切换是否可靠（如 Keepalived、Redis Sentinel）
验证服务实例宕机是否能被自动恢复（K8s、容器编排）
验证数据库故障是否被应用正确处理（超时、重试）
验证告警系统是否及时准确（含日志、指标、邮件、钉钉）
✅ 二、制定演练计划（方案模板）
项目 |
内容 |
|---|---|
| 演练名称 | 如：Nginx主备切换演练 |
| 影响范围 | 哪些系统 / 服务 / 网络段 |
| 参与角色 | 运维、后端、前端、业务方、监控人员 |
| 演练内容 | 如：模拟主节点故障，VIP 是否切换 |
| 演练步骤 | 按顺序列清楚操作点，如：停掉 |
| 预期结果 | 如：10s 内备节点接管 VIP，日志报错但业务不中断 |
| 回滚机制 | 如何恢复服务、执行脚本、人工干预 |
✅ 建议准备“演练记录表”与“演练复盘模板”
✅ 三、演练前准备 checklist
[x] 所有人知情（演练通知）
[x] 设置维护窗口时间
[x] 业务是否允许演练期内出错（如只做在灰度机）
[x] 保留监控面板、日志分析入口
[x] 设置钉钉/企业微信预警群、录屏或日志记录
✅ 四、开始执行演练操作（实战样例）
示例：Keepalived 主节点故障演练
# Step 1: 在主节点手动停止 keepalived 服务
sudo systemctl stop keepalived
# Step 2: 在备节点 ping VIP 看是否接管
ping 192.168.1.100
# Step 3: 检查 Nginx 是否继续转发请求
curl http://192.168.1.100/
# Step 4: 检查日志、告警、监控平台是否捕捉其他演练示例：
Redis 主节点 kill 掉 → 看 Sentinel 是否自动切换
MySQL 宕机 → 观察连接池重连、报警
下游服务不可用 → 模拟熔断 + 重试行为
磁盘打满 → 看系统异常捕捉是否生效
✅ 五、收尾与复盘
收集内容：
各角色操作时间点
系统告警记录截图
Grafana/Prometheus 监控截图
异常日志片段
是否符合预期？有无遗漏？
复盘模板：
### 🎯 演练目标
### ✅ 结果概览
- 是否达到预期：
- 业务是否受影响：
### 🔍 发现的问题
- 告警不及时 / 无法自动恢复 / 日志不清晰 等
### 🛠 后续改进项
- 修复哪些配置、增强自动化等
### 📸 演练截图 / 指标图✅ 六、建议实践模式
类型 |
推荐频率 |
场景 |
|---|---|---|
手工演练 |
每月 |
灰度、重要节点切换 |
自动故障注入 |
每周/持续集成 |
可用性/韧性测试（如 Chaos Mesh） |
业务高峰前的压力演练 |
大促前 |
Double 11、618、发版本 |
参考资料
[1]
Permanent link: https://fastapi.tiangolo.com/zh/project-generation/#fastapi-