yuanboot-python

作者：jackson liang。Copyright (c) 2026 jackson liang。

简单、轻量、快速的 Python 微服务框架，基于 FastAPI、Uvicorn 和依赖注入构建，支持 Web API、MVC、gRPC 与后台服务。Python 3.11+。

框架特色

• 路由分组、MVC 控制器、请求校验、OpenAPI 和 WebSocket。
• Singleton、Scoped、Transient 依赖注入与资源自动释放。
• 统一宿主、应用生命周期、后台服务和优雅退出。
• YAML / JSON、多环境配置、环境变量和远程配置热更新。
• MySQL、Redis、Nacos 配置中心、服务注册与发现。
• 统一启动版权信息、zap / logrus 文本与 JSON 日志、请求追踪、健康检查、Prometheus 和 JWT。
• Swagger 展示框架版本、版权、联系信息与 MIT 许可，并保留业务文档配置。
• HTTP 客户端、定时任务、SMTP、gRPC 和 XXL-Job BEAN 执行器。
• yuanbootctl-python 提供七类项目模板、运行和构建命令。

下载命令行工具

从 GitHub Releases 下载对应系统和架构的压缩包，解压后即可执行，无需预装 Python。

例如 Linux amd64：

VERSION=0.2.0
curl -fLO "https://github.com/liangboceo/yuanboot-python/releases/download/v${VERSION}/yuanbootctl-python_${VERSION}_linux_amd64.tar.gz"
tar -xzf "yuanbootctl-python_${VERSION}_linux_amd64.tar.gz"
chmod +x yuanbootctl-python
./yuanbootctl-python --version
./yuanbootctl-python new webapi -n demo
cd demo
../yuanbootctl-python run --profile dev

访问 API 文档。Windows 使用 yuanbootctl-python.exe。 Release 同时提供 SHA256SUMS、wheel 和源码包。

独立可执行文件包含 Python 运行时、框架和标准组件，可以直接创建、运行模板项目。 业务增加其他 Python 依赖后，可使用 run --python /path/to/.venv/bin/python 选择业务环境。 build 打包 Python 项目，需要业务环境安装 build，详见 命令行与发布说明。

安装框架

从公开 PyPI 安装框架或项目工具：

python -m pip install 'yuanboot[all]==0.2.0'
# 也可通过工具包安装同版本框架和命令：
python -m pip install yuanbootctl-python==0.2.0
yuanbootctl-python --version

yuanbootctl-python 自动依赖同版本的 yuanboot，命令入口和模板资源统一由框架提供。 yuanbootctl-python[all] 会安装全部标准组件。PyPI 安装方式需要 Python 3.11+。

创建业务项目并安装依赖：

python -m venv .venv
source .venv/bin/activate
python -m pip install 'yuanbootctl-python[all]==0.2.0'
yuanbootctl-python new mvc -n orders
cd orders
python -m pip install -e '.[dev,components]'
yuanbootctl-python run --reload

按需选择 mysql、redis、nacos、grpc 等 extras；all 安装全部标准组件。 框架和业务项目分别管理版本，业务项目提交自己的依赖锁文件。 生成项目默认从 PyPI 安装，基础依赖固定 yuanboot==0.2.0， 组件固定 yuanboot[all]==0.2.0，gRPC 固定 yuanboot[grpc]==0.2.0。 版本自动读取生成工具内置的框架版本；升级工具后新生成项目使用新版本，已有项目保留原固定版本。 可用 --framework-version 选择其他 PyPI 版本，或显式用 --framework-ref v0.2.0 切换为 Git tag 依赖。

框架版本通过 GitHub Actions → Build Release 填写 version 发布。 公开的 Release/tag 创建成功后会自动启动 Publish PyPI，将两个同版本包上传到公开 PyPI。 草稿 Release 在公开发布时触发同步；上传失败可手动重跑 Publish PyPI。详见发布说明。

PyCharm 调试与直接运行

模板提供项目根目录 main.py 和 .run/yuanboot.run.xml。 使用项目虚拟环境安装 pip install -e '.[dev]' 后，直接运行或 Debug 根目录 main.py， 也可从项目根目录执行 python -m demo.main（将 demo 替换为业务包名）。 PyCharm 手动配置使用 Module name demo.main，Working directory 选择项目根目录。 包内入口使用绝对导入，业务项目安装后也支持直接运行 demo/main.py。 配置优先读取当前目录的 config.yml，当前目录没有配置时回退到项目根目录。

项目模板

模板包含项目元数据、配置、Dockerfile、Compose、README 和 spec 开发文档。 每个新项目默认提供以下文档，可离线查阅：

README.md
spec/
├── yuanboot-python.md             # 框架使用说明
├── components.md                 # 核心组件配置与使用
└── backend-module-development.md  # 后端模块开发规范

yuanbootctl-python new --list
yuanbootctl-python new mvc -n my-app
yuanbootctl-python new grpc -n rpc-demo
yuanbootctl-python run --profile fat --port 9000
yuanbootctl-python run --workers 2
yuanbootctl-python build
yuanbootctl-python version

管理后台

python -m pip install 'yuanbootctl-python[admin]==0.2.0'
yuanbootctl-python new admin -n my-admin
cd my-admin/my-admin-server
python -m pip install -e '.[dev]'
yuanbootctl-python run

另开终端，在 my-admin/my-admin-web 执行 pnpm install --frozen-lockfile && pnpm dev。 访问 http://127.0.0.1:8848/，开发初始账号 admin / admin123。 默认使用 SQLite 和本地会话，支持切换 MySQL、Redis、Nacos。模板包含完整前后端源码与离线文档，详见 管理后台。

简单示例

from yuanboot.web import create_default_builder
from yuanboot.web.endpoints import use_actuator


def endpoints(router):
    use_actuator(router)

    @router.get("/info")
    def info():
        return {"info": "ok"}


host = create_default_builder(endpoints).build()
app = host.app

if __name__ == "__main__":
    host.run()

默认监听 0.0.0.0:8080。可通过宿主构建器配置服务注册、中间件、路由和生命周期。

环境与配置

支持 dev / fat / uat / pro，默认 dev。通过 --profile 或 YUANBOOT_PROFILE 选择环境。

config.yml
config_dev.yml
config_fat.yml
config_uat.yml
config_pro.yml

配置优先级：默认值 < 基础配置 < 环境配置 < 远程配置 < 环境变量 < 命令行。 MySQL、Redis 和 Nacos 等组件按配置启用；Nacos 注册 metadata 的 yuanboot_env 使用当前环境名。

yuanboot:
  application:
    name: orders
    server:
      address: ":8080"

支持 ${ENV:default} 插值和 Pydantic 模型绑定，敏感信息通过环境变量提供。

核心组件

组件配置和使用方法见 组件文档。

发布

在 Actions → Build Release 手动填写 version，选择 prerelease、draft。 构建通过后，自动同步版本、创建 Git tag 和 GitHub Release，上传各平台可执行文件、wheel、源码包和校验文件。 默认分支为 master，已发布 tag 保持不变。

文档

• 框架开发指南
• 组件配置与使用
• 管理后台模板
• 命令行、发布与依赖管理

启动控制台显示 yuanboot logo 与彩色启动信息，保留版本及版权标识。日志支持 color: auto / always / never、banner: false；文件和 JSON 日志不含框架颜色码。详见日志配置。

License

MIT