# chongming

**基于 module_bank 的 FastAPI 快速打包脚手架 —— 一体化开发与部署方案**

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 容器化方案。

---

## 项目架构

```text
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](https://docs.astral.sh/uv/) (推荐) 或 普通 pip
- Node.js >= 20.19 (仅开发前端时需要)

### 1. 克隆并安装依赖
```bash
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. 开发模式运行
```bash
uv run serve
```
此时系统使用 `config.toml` 中的 `[development]` 配置: 热重载开启，调试日志，CORS 全允许。

前端开发 (独立启动)
```bash
cd src/chongming-web
# 下载依赖
npm install
# 生成 api
npm run openapi
# 启动
npm run dev
```

---

## 配置体系

项目通过 `config.toml` 实现环境分离，核心节点说明:
```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 的打包流程集成了加密、混淆、静态资源嵌入等步骤，最终生成独立可执行文件。

```bash
uv run build
```

### 构建产物

位于 `build` 目录下

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

### 打包过程详解：

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

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

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

4. **Vue 前端构建**

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

---

## Docker 部署

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

### 构建镜像

```bash
# 默认构建 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 .
```

### 执行部署脚本
```bash
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` 自动生成，重新生成命令：
```bash
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](./LICENSE) 开源。

---

**chongming** —— 让事情更简单