bigscreen/backend

灵境万象 FastAPI 标准项目模板

基于 FastAPI + PostgreSQL + Redis 的现代化 Python Web 应用架构模板。

✨ 特性

• ✅ FastAPI - 高性能异步 Web 框架
• ✅ PostgreSQL - 强大的关系型数据库（psycopg 驱动）
• ✅ Redis - 高性能缓存和消息队列
• ✅ .env 配置 - 环境变量统一管理
• ✅ 热更新 - 开发环境自动重载
• ✅ Docker 支持 - 一键容器化部署
• ✅ 类型提示 - 完整的 Python 类型注解
• ✅ 异步优先 - 全面使用 async/await
• ✅ API 文档 - 自动生成 Swagger/ReDoc 文档
• ✅ 远程访问 - 支持 CORS 跨域访问
• ✅ Python 3.14 - 支持最新 Python 版本

📁 项目结构

ljwx-fastapi/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 应用主入口
│   ├── core/                   # 核心配置
│   │   ├── config.py          # 配置管理
│   │   ├── database.py        # 数据库连接
│   │   └── redis.py           # Redis 客户端
│   ├── api/                    # API 路由
│   │   └── v1/
│   │       └── endpoints/
│   │           └── health.py   # 健康检查接口
│   ├── models/                 # 数据库模型
│   ├── schemas/                # Pydantic 模型
│   ├── services/               # 业务逻辑
│   └── utils/                  # 工具函数
├── static/                     # 静态文件
├── templates/                  # HTML 模板
│   └── dashboard.html         # Dashboard 页面
├── tests/                      # 测试文件
├── .env                        # 环境变量配置
├── .env.example               # 环境变量示例
├── requirements.txt           # Python 依赖
├── Dockerfile                 # Docker 镜像配置
├── docker-compose.yml         # Docker Compose 配置
├── docker-compose.dev.yml     # 开发环境配置
└── run.py                     # 启动脚本

🚀 快速开始

方式一：本地运行（推荐开发）

1. 准备环境

确保本地已安装：

• Python 3.11+
• PostgreSQL 15+
• Redis 7+

2. 安装依赖

cd ljwx-fastapi

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

3. 配置环境变量

# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，配置数据库和 Redis 连接信息
# 默认配置使用本地 127.0.0.1 的 PostgreSQL (database: template) 和 Redis

4. 启动应用

# 方式 1: 使用启动脚本（支持热更新）
python run.py

# 方式 2: 使用 uvicorn 直接启动
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

5. 访问应用

• Dashboard: http://localhost:5115
• API 文档 (Swagger): http://localhost:5115/docs
• API 文档 (ReDoc): http://localhost:5115/redoc
• 健康检查: http://localhost:5115/api/v1/health/full

方式二：Docker 部署

开发环境（支持热更新）

# 启动开发环境（包含 PostgreSQL + Redis + FastAPI）
docker-compose -f docker-compose.dev.yml up -d

# 查看日志
docker-compose -f docker-compose.dev.yml logs -f app

# 停止服务
docker-compose -f docker-compose.dev.yml down

生产环境

# 启动生产环境
docker-compose up -d

# 查看日志
docker-compose logs -f app

# 停止服务
docker-compose down

🧪 API 测试

项目提供了测试脚本：

# 本地测试
./test_api.sh

# 远程测试
./test_api.sh http://your-server-ip:5115

测试所有端点：

• /ping - 基础 ping 测试
• /info - 应用信息
• /api/v1/health/ - 基础健康检查
• /api/v1/health/redis - Redis 健康检查
• /api/v1/health/db - 数据库健康检查
• /api/v1/health/full - 完整系统健康检查

🌐 远程访问

应用已配置支持远程访问：

• 监听地址: 0.0.0.0 (所有网络接口)
• 端口: 5115
• CORS: 默认允许所有来源 (*)

从其他设备访问

# 浏览器访问
http://YOUR_SERVER_IP:5115
http://YOUR_SERVER_IP:5115/docs

# API 调用
curl http://YOUR_SERVER_IP:5115/ping

生产环境安全建议

在生产环境中，修改 .env:

# 限制 CORS 来源
ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

# 关闭调试模式
DEBUG=false
ENVIRONMENT=production

📝 环境变量说明

.env 文件配置项：

# 应用配置
APP_NAME="灵境万象FastAPI"
APP_VERSION="1.0.0"
DEBUG=true                      # 开发模式
ENVIRONMENT=development         # 环境标识

# 服务器配置
HOST=0.0.0.0
PORT=5115
RELOAD=true                     # 热更新开关

# PostgreSQL 数据库配置
DATABASE_HOST=127.0.0.1         # 本地使用 127.0.0.1
DATABASE_PORT=5432
DATABASE_NAME=template          # 数据库名称
DATABASE_USER=postgres
DATABASE_PASSWORD=postgres
DATABASE_POOL_SIZE=10
DATABASE_MAX_OVERFLOW=20

# Redis 配置
REDIS_HOST=127.0.0.1            # 本地使用 127.0.0.1
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=                 # 可选
REDIS_POOL_SIZE=10

# 安全配置
SECRET_KEY=your-secret-key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# CORS 配置（远程访问支持）
ALLOWED_ORIGINS=*  # 开发环境允许所有来源，生产环境应限制

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=logs/app.log

# 公司配置
COMPANY_NAME=灵境万象

🔧 开发指南

添加新的 API 端点

1. 在 app/api/v1/endpoints/ 创建新的路由文件
2. 在 app/api/v1/__init__.py 中注册路由

示例：

# app/api/v1/endpoints/users.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/")
async def get_users():
    return {"users": []}

# app/api/v1/__init__.py
from app.api.v1.endpoints import users

api_router.include_router(users.router, prefix="/users", tags=["users"])

添加数据库模型

# app/models/user.py
from sqlalchemy import Column, Integer, String
from app.core.database import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(100), nullable=False)
    email = Column(String(255), unique=True, index=True)

使用 Redis 缓存

from fastapi import Depends
from app.core.redis import RedisClient, get_redis

@router.get("/cached-data")
async def get_cached_data(redis: RedisClient = Depends(get_redis)):
    # 尝试从缓存获取
    cached = await redis.get_json("my_key")
    if cached:
        return cached

    # 计算数据
    data = {"result": "computed"}

    # 缓存 60 秒
    await redis.set_json("my_key", data, expire=60)
    return data

🧪 测试

# 运行测试
pytest

# 运行测试并查看覆盖率
pytest --cov=app tests/

📊 API 健康检查

应用提供多个健康检查端点：

• GET /api/v1/health/ - 基础健康检查
• GET /api/v1/health/db - 数据库健康检查
• GET /api/v1/health/redis - Redis 健康检查
• GET /api/v1/health/full - 完整系统健康检查

🐛 调试

开启调试模式：

1. 设置 .env 中 DEBUG=true
2. 设置 LOG_LEVEL=DEBUG
3. 重启应用

📚 技术栈

• FastAPI >=0.115.0 - Web 框架
• Uvicorn >=0.32.0 - ASGI 服务器
• SQLAlchemy >=2.0.36 - ORM
• psycopg >=3.2.0 - PostgreSQL 异步驱动（支持 Python 3.14）
• Redis >=5.2.0 - Redis 客户端
• Pydantic >=2.10.0 - 数据验证
• Jinja2 >=3.1.4 - 模板引擎

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📧 联系方式

• 公司：灵境万象
• 项目：FastAPI 标准模板