🚀 LiteStar + Knife4j Vue3 生产部署指南

项目概述

这是一个基于 LiteStar 2.17.0 框架的生产就绪 API 应用，集成了 Knife4j Vue3 前端文档界面。

功能特性

✅ 完整的 OpenAPI 3.0 文档
✅ HTTP Basic 认证保护
✅ 环境变量配置支持
✅ API 端点分组标签
✅ 增强的大数据显示 (支持500KB)
✅ JSON 响应格式化 (4空格缩进)
✅ 右键菜单功能

快速开始

1. 环境准备

# 安装依赖
pip install litestar uvicorn[standard]

# 复制环境变量配置
copy .env.example .env

2. 配置认证

编辑 .env 文件：

AUTH_USERNAME=your_username
AUTH_PASSWORD=your_password
HOST=0.0.0.0
PORT=8000

3. 启动应用

# 开发环境
python main.py

# 生产环境
uvicorn main:app --host 0.0.0.0 --port 8000

4. 访问文档

• API 文档: http://localhost:8000/api/doc/doc.html
• OpenAPI Schema: http://localhost:8000/schema/openapi.json

部署方式

Docker 部署

FROM python:3.11-slim

WORKDIR /app
COPY . .
RUN pip install litestar uvicorn[standard]

EXPOSE 8000

ENV AUTH_USERNAME=admin
ENV AUTH_PASSWORD=your_secure_password

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Kubernetes 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: litestar-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: litestar-app
  template:
    metadata:
      labels:
        app: litestar-app
    spec:
      containers:
      - name: litestar-app
        image: your-registry/litestar-app:latest
        ports:
        - containerPort: 8000
        env:
        - name: AUTH_USERNAME
          value: "admin"
        - name: AUTH_PASSWORD
          valueFrom:
            secretKeyRef:
              name: app-secrets
              key: password
        - name: HOST
          value: "0.0.0.0"
        - name: PORT
          value: "8000"

API 端点说明

用户管理 (/users)

• GET /users - 获取用户列表
• POST /users - 创建用户
• GET /users/{user_id} - 获取用户详情

产品管理 (/products)

• GET /products - 获取产品列表
• POST /products - 创建产品
• GET /products/large-data - 大数据测试端点 (500KB)

系统信息 (/system)

• GET /health - 健康检查
• GET /info - 系统信息

前端特性

大数据显示

• 支持显示高达 500KB 的响应数据
• 大于 1MB 的数据会显示简化信息
• 保持原始数据格式和可读性

JSON 格式化

• 自动 4 空格缩进
• 语法高亮显示
• 支持复制和下载

右键菜单

• 标签页右键菜单
• 快速操作选项

安全配置

认证保护的端点

• /api/doc/** - API 文档
• /schema/** - OpenAPI Schema
• /swagger-resources/** - Swagger 资源
• /v3/api-docs/** - API 文档

认证方式

• HTTP Basic Authentication
• 用户名和密码通过环境变量配置

故障排除

常见问题

1. 认证失败

   • 检查 AUTH_USERNAME 和 AUTH_PASSWORD 环境变量
   • 确保浏览器清除了缓存的认证信息

2. 大数据不显示

   • 已修复：现在支持显示 500KB 数据
   • 检查浏览器开发者工具确认数据已接收

3. API 路径重复

   • 已修复：移除了重复的 /api 前缀

4. 端点分组问题

   • 已实现：使用 tags 参数对 API 进行分组

技术架构

• 后端: LiteStar 2.17.0
• 前端: Knife4j Vue3 + Vite
• 文档: OpenAPI 3.0
• 认证: HTTP Basic Auth
• 配置: 环境变量

版本信息

• LiteStar: 2.17.0
• Python: 3.11+
• Node.js: 16+ (前端构建)

更新日志

v1.0.0 (2025-01-10)

• ✅ 初始发布
• ✅ 环境变量配置支持
• ✅ HTTP Basic 认证
• ✅ API 端点分组
• ✅ 大数据显示优化 (500KB)
• ✅ JSON 格式化增强
• ✅ 前端菜单功能

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License