chongming 视一个专注企业级应用快速落地的全栈脚手架，深度整合 FastAPI、SQLModel、Vue 3、APScheduler 和自研 模块银行(Module-Bank) 技术，让你能够更快完成开发，并最终产出一个 体积不足 30 MB 的单文件可执行程序。从本地开发到镜像化部署，一条命令完成。

作者: chakcy

版本: 0.1.0

[TOC]

核心亮点

特性	描述
单文件交付	通过 PyInstaller 打包，最终产物为单个可执行文件 (`chongming`/`chongming.exe`)
模块加密	业务代码使用 Module-Bank 技术加密打包至 SQLite，运行时动态加载，有效保护源码
前端内嵌	Vue 3 前端构建为 SQLite VFS 虚拟文件系统，无须额外部署 Nginx 或静态文件服务
开箱即用	内置认证 (JWT)、权限 (RBAC)、任务调度、日志、缓存、10 分钟搭建业务骨架
极简容器	Docker 镜像基于 `scratch`，总大小 30.4 MB，内存占用约 120 MB
多环境配置	通过 `config.toml` 区分 developmetn / production，开发热重载、生产 Gunicorn 多进程无缝切换

方案对比

chongming 与传统 Python Web 部署方式及当今流行的单文件分发方式相比，再交付体积、部署复杂度、源码保护和集成方面具有显著优势。

对比维度	chongming	FastAPI + pip/venv	FastAPI + Docker (python:slim)	Nginx + uWSGI + Django
最终交付物	单文件可执行程序(~30MB)	源代码 + 虚拟环境 + pip 依赖	镜像 >= 150 MB	多组件组合部署
部署命令	`./chongming`	`source venv/bin/activate && uvicorn main:app`	`docker run ...`	多部 Nginx/uWSGI 配置
运行环境要求	仅需 glibc (Linux发行版自带)	需要 Python + pip + 虚拟环境	需要 Docker 引擎	Python + 系统服务
Python 源码保护	Module-Bank 加密 + PyArmor 混淆，磁盘无明文	源码完全暴露	镜像层内源码可见	源码暴露
前端集成	前端自动嵌入，单进程服务	需要单独部署前端或挂载静态目录	同左	需 Nginx 配置静态文件
容器镜像体积	30.4 MB (`scratch` 基镜像)	不适用	>=150 MB(`python:slim`)	多容器组合体积庞大
运行时内存	~120 MB (4 Gunicorn workers)	~150 MB (单 uvicorn)	~200 MB	~500 MB + (含数据库)
多环境切换	同一份 config.toml，开发/生产平滑切换	环境变量 + 配置文件切换	环境变量 + 多 Dockerfile	多套配置文件
依赖管理	打包后无外部 Python 依赖	pip requirements.txt	镜像层安装	pip + 系统包

总结: chongming 在 Python 生态中实现了类似 Go 的单文件交付体验，同时保留了 Python 快速开发的灵活性和丰富的异步生态。其独有的模块加密与前端内置能力，让企业级应用的交付从“配置说明书”简化为“拷贝-执行-访问”，且运行时资源占用远低于传统 Python 容器化方案。

项目架构

chongming/
├── public/                  # 公开可执行程序的启动模板
│   ├── main.py              # 打包后的主入口（PyInstaller 入口）
│   ├── server.py            # ASGI 应用加载器（从模块银行动态导入）
│   ├── config.toml           # 生产配置（打包时自动注入密钥）
│   └── utils/               # 轻量工具（配置加载、模块银行初始化）
├── src/
│   ├── chongming/           # 核心 FastAPI 应用
│   │   ├── app/             # 业务逻辑：API、模型、服务、核心组件
│   │   ├── scripts/         # 构建脚本（编码、混淆、数据库初始化）
│   │   └── __init__.py      # 服务启动入口 (uvicorn/gunicorn)
│   ├── plugins/             # 可热插拔的插件模块
│   │   ├── jwt/             # JWT 认证与缓存
│   │   ├── scheduler/       # 基于 APScheduler 的持久化任务调度
│   │   ├── mqtt/            # (预留) MQTT 客户端
│   │   └── websocket/       # (预留) WebSocket 服务
│   └── chongming-web/       # Vue 3 + Element Plus 前端
├── build/                   # 打包输出目录（可执行程序、静态文件、数据库）
├── Dockerfile               # 多阶段构建，最终基于 scratch
├── deploy.sh                # 一键部署脚本（数据持久化、端口映射）
└── pyproject.toml           # 项目与构建依赖定义

运行原理

开发时通过 uv run serve 直接启动 uvicon。打包后，chongming 可执行文件内嵌了经过混淆的引导程序，引导程序从加密的 Module-Bank 文件 (app.mbank, plugins.mbank) 中动态加载应用模块，同时从 SQLite VFS (static.svfs) 提供前端静态文件。所有 Python 业务代码不暴露于明文磁盘。

快速开始

环境要求

Python >= 3.8 (推荐 3.11+)
uv (推荐) 或普通 pip
Node.js >= 20.19 (仅开发前端时需要)

1. 克隆并安装依赖

git clone https://github.com/caixinp/chongming.git
cd chongming

# 适用 uv (自动创建虚拟环境并安装)
uv sync

# 或传统方式
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

2. 开发模式运行

uv run serve

此时系统使用 config.toml 中的 [development] 配置: 热重载开启，调试日志，CORS 全允许。

前端开发 (独立启动)

cd src/chongming-web
# 下载依赖
npm install
# 生成 api
npm run openapi
# 启动
npm run dev

配置体系

项目通过 config.toml 实现环境分离，核心节点说明:

[default]
env = "development"          # 当前环境：development 或 production

[database]
type = "sqlite"
url = "sqlite+aiosqlite:///./data/database.db"

[development.server]
host = "127.0.0.1"
port = 8000
reload = true                # 开发热重载

[production.server]
host = "0.0.0.0"
port = 8000
workers = 4                  # Gunicorn 多进程（打包后自动使用）

[production.module_system]   # 打包后从 mbank 加载模块
path = ["resources/app.mbank", "resources/plugins.mbank"]

[production.file_system]     # 打包后从 svfs 提供前端
path = "static.svfs"

打包脚本会自动将 secret_key 注入到 build/config.toml 中，开发者无需手动处理敏感信息。

构建与打包

chongming 的打包流程集成了加密、混淆、静态资源嵌入等步骤，最终生成独立可执行文件。

uv run build

构建产物

位于 build 目录下

build/
├── chongming           # 单文件可执行程序 (Linux) 或 chongming.exe (Windows)
├── config.toml         # 生产配置（密钥已注入）
├── resources/          # 加密的模块银行 (.mbank) 和图标
├── static.svfs         # Vue 前端虚拟文件系统
└── data/               # 初始 SQLite 数据库

打包过程详解：

模块加密

使用 module_bank.PythonToSQLite 将 src/chongming/app 和 src/plugins 目录分别打包为加密的 .mbank 文件，密钥随机生成并注入启动脚本。
代码混淆

对 main.py，server.py，utils/*.py 使用 PyArmor 进行代码保护。
PyInstaller 打包

编译为单文件可执行程序，隐藏导入所有依赖项。
Vue 前端构建

npm run build 后将 dist 目录打包到 SQLite VFS (static.svfs)。
数据库初始化 自动创建初始 SQLite 数据库 (WAL 模式)，包含管理员账户 (admin/admin) 和基础权限集。

Docker 部署

Docker 镜像采用多阶段构建 + scratch 基础镜像，真正做到最小化。同时支持 x86_64 与 aarch64 (ARM64) 双架构。

构建镜像

# 默认构建 x86_64 架构
docker build -t chongming:latest .

# 在 ARM64 设备上构建
docker build --build-arg TARGETARCH=aarch64 -t chongming:arm64 .

# 使用 Docker Buildx 构建多架构镜像（推送到仓库）
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg TARGETARCH \
  -t your-registry/chongming:latest \
  --push .

执行部署脚本

sudo chmod +x deploy.sh
./deploy.sh

部署脚本会：

在 $HOME/chongming-data 下创建 data/, uploads/, logs/ 目录
若首次运行，从镜像提取初始数据库
启动容器并挂载上述目录，端口 8000 映射
自动设置 --restart unless-stopped

镜像特性

基础镜像：scratch（零额外依赖）
仅需拷贝 glibc 动态库、时区数据、CA 证书
最终尺寸 30.4 MB
运行时内存占用 ~120 MiB

核心组件说明

1. 认证与权限 (JWT + RBAC)

使用 bcrypt 密码加密
基于磁盘缓存 (diskcache) 的 JWT 管理，支持多设备登录、会话限制
刷新 Token 机制
完整的 RBAC 模型: 用户、角色、权限，支持用户专属角色直接分配权限

2. 任务调度 (APScheduler)

异步调度器，支持 interval, cron, date 触发器
持久化至独立 SQLite 数据库，重启不丢失
基于文件锁的多进程互斥，避免重复执行

3. 静态文件服务

开发期间直接使用 StaticFiles 指向本地目录
打包后通过 SVFSStaticFiles 从 SQLite VFS 读取，实现前端内嵌
支持 SPA 路由回退 (index.html)

4. 日志系统

按天自动轮转，文件大小限制（默认 10 MB）和历史备份
控制台带 HTTP 状态码颜色输出
过滤第三方库 (SQLAlchemy, watchfiles 等) 噪音

5. 缓存

基于 diskcache 的本地持久化缓存，API 兼容 Redis 常用操作
提供 @cached 装饰器透明缓存函数结果

性能指标

指标	数值
Docker 镜像体积	30.4 MB
运行时内存	~121 MiB (含 Gunicorn 4 workers)
数据库模式	SQLite WAL + NORMAL synchronous (写性能提升)
连接池	最大 20，支持池预热和连接回收
静态文件处理	SQLite VFS 内存级读取，无磁盘 I/O 开销

设计理念

1. 极致的便携性

一切皆文件，一个可执行程序 + 配置文件即可运行完整 Web 应用。告别复杂的依赖安装与环境配置。

2. 源码深度保护

业务逻辑通过 Module‑Bank 加密存储于 SQLite，运行时动态导入内存，不落盘明文。配合 PyArmor 混淆，有效防止逆向。

3. 插件化架构

认证、调度、缓存等通用能力剥离为独立插件 (plugins/)，可插拔可替换，确保核心应用的简洁。

4. 渐进式架构

同一套代码支持从开发热重载到生产 Gunicorn 多进程的平滑过渡。配置即环境，无代码分支。

5. 最小基础设施依赖

无需 Redis、Nginx、外部数据库。SQLite 满足绝大多数中低并发场景，简化运维。

6. 前端一体化

Vue 前端自动打包进可执行程序，用户通过浏览器访问 http://host:8000/static/ 即可使用，真正单进程部署。

开发指南

目录约定

业务 API：src/chongming/app/api/routers/
数据模型：src/chongming/app/model/
服务逻辑：src/chongming/app/service/
核心组件：src/chongming/app/core/
插件扩展：src/plugins/

添加新路由

在 src/chongming/app/api/__init__.py 中引入你的路由模块并挂载。

前端开发

前端代码位于 src/chongming-web/，基于 Vite + Vue 3 + Element Plus。 API 客户端由 @hey-api/openapi-ts 自动生成，重新生成命令：

cd src/chongming-web
npm run openapi   # 需要先启动后端

打包注意事项

打包前务必确保没有语法错误
新增 Python 依赖需要在 pyproject.toml 的 dev.dependencies 添加 pyarmor 和 pyinstaller（已默认包含）
若添加了新的第三方库，需在 scripts/build.py 的 run_pyinstaller() 中声明对应的 --hidden-import
Windows 下打包需事先安装 pyarmor 和 pyinstaller

许可证

本项目基于 MIT License 开源。

chongming —— 让事情更简单

README.md Unescape Escape

chongming