# Fast Tailor `fast-tailor` 是一个基于 FastAPI 的插件化应用框架。它提供了清晰的运行时边界和统一的装配方式，用来组织插件、admin、web、schema、data init、异步任务等核心能力。 ## Current Status 当前仓库的核心设计包括： - 插件加载走 `manifest.py + build_plugin() + bootstrap.py` - 数据模型统一走 SQLAlchemy + `core.db.schema` - admin 和 model API 已经切到 schema 驱动 - 启动时不再自动 `create_all`，数据库结构由 Alembic 管理 - 默认数据初始化统一走 `data_init_registry` - auth refresh token 已接入服务端 cache 存储语义 ## Project Layout - `core/`: 应用工厂、配置、插件注册、数据库底座、cache、registry - `core/db/`: model、schema、crud、session、lifecycle - `plugins/`: 业务插件 - `settings/`: 运行配置说明和环境相关文件 - `tests/`: core 测试与共享 pytest fixtures；插件测试放在 `plugins//tests` 常见入口： - `main.py`: 应用启动入口 - `core/app.py`: FastAPI app factory、插件加载、lifespan - `core/config.py`: 运行配置 - `core/plugin_registry.py`: 插件 manifest / plugin 注册与装配 ## Frontend Style 当前仓库前端以服务端渲染为主： - 页面结构和数据注入：`Jinja` - 局部刷新：`htmx` - 页面行为组织：`Stimulus` 这意味着默认策略不是直接做前后端分离，而是在现有插件模板结构上做渐进增强。推荐分工： - 模板负责页面骨架和服务端数据 - `htmx` 负责列表、搜索结果、分页这类局部 HTML 替换 - `Stimulus` 负责事件绑定、前端状态、本地存储和页面交互当前 admin 通用页已经按这个方向整理： - `modelList`：服务端 partial + `htmx` + `Stimulus` - `modelForm`：`Stimulus` 主导，relation search 已切到 `htmx` ## Installed Plugins 默认插件集合定义在 [core/plugin_settings.py](core/plugin_settings.py) 的 `INSTALLED_PLUGINS` 中，当前包含： - `auth` - `web` - `admin` - `front` - `attachment` - `blog` - `system` - `model_api` - `email` - `sms` - `area` - `vpn` - `message` - `celery` - `dingtalk` ## Plugin Template 如果你要在这个仓库里新增一个插件，最小模板建议直接从下面开始： ```text plugins// __init__.py manifest.py bootstrap.py services/ __init__.py models/ __init__.py views/ __init__.py ``` 最小骨架示例： `plugins//__init__.py` ```python from core import BasePlugin class Plugin(BasePlugin): def __init__(self): super().__init__("") def setup(self): from .views import router self.router.include_router(router) def build_plugin(): return Plugin() ``` `plugins//manifest.py` ```python PLUGIN = { "name": "", "package": "plugins.", "meta": {"name": "", "description": ""}, "depends": [], "models": ["plugins..models"], "init": "plugins..bootstrap:init_plugin", } ``` `plugins//bootstrap.py` ```python def init_plugin(app) -> None: del app ``` `plugins//views/__init__.py` ```python from fastapi import APIRouter router = APIRouter() ``` 补充约定： - 前后端分离 API 放 `api/` - SSR 页面路由和 `TemplateView` 放 `views/` - 模板放 `templates//` - 业务逻辑放 `services/` - 模型和 schema 注册放 `models/` - 需要默认数据时增加 `data/` - 根目录除 `__init__.py`、`manifest.py`、`bootstrap.py` 外不再新增运行时代码文件 - 历史单文件模块应整理成同名目录加同名文件，例如 `tasks/tasks.py` - `api/__init__.py`、`models/__init__.py`、`views/__init__.py` 只做轻量导出或聚合，不承载实际业务 - 不要把主要逻辑直接平铺在插件根目录更完整的插件约定见 [plugins/README.md](plugins/README.md)。 ## Run 先安装依赖： ```bash python uv_sync.py ``` 环境变量示例可以直接参考： - [.env.example](.env.example) 如果要根据当前静态插件配置和 extras 自动拼装命令，也可以用： ```bash python uv_sync.py python uv_sync.py --extra attachment-oss python uv_sync.py --all-extras ``` 说明： - 脚本会默认读取 [core/plugin_settings.py](core/plugin_settings.py) 中静态声明的 `INSTALLED_PLUGINS` - 如果不想启用某个插件，直接在 `core/plugin_settings.py` 里删除或注释掉对应项 - `auth`、`email`、`celery` 这类插件依赖现在已经拆到 `pyproject.toml` 的 plugin extras 中 - `attachment-oss`、`attachment-cos`、`attachment-s3` 这类 attachment provider 依赖，需要显式通过 `--extra` 指定 - PostgreSQL、Redis、Mongo 这类公共运行时依赖现在放在基础依赖中，不再单独拆 extra - 测试依赖在 `dev` dependency group 中；如果你直接用 `uv sync`，uv 默认也会同步开发依赖数据库迁移由 Alembic 管理。启动应用前先执行： ```bash uv run alembic upgrade head ``` 再启动开发服务： ```bash DEBUG=true uv run uvicorn main:app --reload --port 9307 ``` 如果在部署环境需要多进程，可以通过环境变量控制： ```bash export WORKERS=4 export CELERY_WORKER_CONCURRENCY=4 ``` HTTP 响应默认会启用 gzip 压缩，也可以通过环境变量调整： ```bash export GZIP_ENABLED=true export GZIP_MINIMUM_SIZE=500 ``` 应用和 Celery 共用同一个时区配置： ```bash export TZ=Asia/Shanghai ``` 如果要启用异步任务和定时任务，还需要单独启动 Celery worker/beat： ```bash uv run celery -A plugins.celery.services.app:celery_app worker -l info uv run celery -A plugins.celery.services.app:celery_app beat -l info -S plugins.celery.services.scheduler:DatabaseScheduler ``` 当前 Celery 会递归发现各插件 `tasks/` 目录下的所有 Python 模块，因此任务可以按领域拆分到多个文件，而不必都堆在单个 `tasks.py` 中。 Celery 默认会优先读取： - `CELERY_BROKER_URL` - `CELERY_RESULT_BACKEND` 如果这两个没配，则会自动用 `CACHE_REDIS_HOST` / `CACHE_REDIS_PORT` / `CACHE_REDIS_USER` / `CACHE_REDIS_PASSWORD` 组装： - cache: `CACHE_REDIS_DB`，默认 `0` - broker: `CELERY_BROKER_REDIS_DB`，默认 `1` - result backend/store: `CELERY_RESULT_REDIS_DB`，默认 `2` 所以本地常见配置可以只写： ```bash export CACHE_REDIS_HOST='127.0.0.1' export CACHE_REDIS_PORT='6379' export CACHE_REDIS_PASSWORD='your-redis-password' export CACHE_REDIS_DB='0' export CELERY_BROKER_REDIS_DB='1' export CELERY_RESULT_REDIS_DB='2' ``` 如果你想手动指定 Celery 地址，也可以直接写完整 URL： ```bash export CELERY_BROKER_URL='redis://:password@127.0.0.1:6379/1' export CELERY_RESULT_BACKEND='redis://:password@127.0.0.1:6379/2' ``` 说明： - `DEBUG` 现在只接受 bool 语义值，不再兼容 `release/prod` 这类字符串 - 应用启动时不会自动建表；如果数据库没迁移好，应该先跑 Alembic - 可以从 [.env.example](.env.example) 拷一份环境变量模板再改 ### PostgreSQL 当前仓库同时支持： - SQLite: `sqlite+aiosqlite:///./data/myapp.db` - PostgreSQL: `postgresql+asyncpg://user:password@host:5432/dbname` 数据库配置现在支持两种方式： 1. 直接提供 `DATABASE_URL` 2. 提供分项配置，应用启动时自动拼接 `DATABASE_URL` 更推荐第 2 种，尤其是密码里包含 `@`、`:`、`/` 这类特殊字符时，不需要手工 URL encode。本地切到 PostgreSQL 时，可以这样配： ```bash export DATABASE_SCHEME='postgresql+asyncpg' export DATABASE_HOST='127.0.0.1' export DATABASE_PORT='5432' export DATABASE_USER='fast_tailor' export DATABASE_PASSWORD='p@ss:word/123' export DATABASE_NAME='fast_tailor' uv run alembic upgrade head uv run uvicorn main:app --reload --port 9307 ``` 说明： - SQLAlchemy async driver 现在统一按 `asyncpg` 走 PostgreSQL - Alembic 也直接复用最终生成出来的 `DATABASE_URL` - SQLite 仍然保留为默认开发数据库 - 如果同时提供了 `DATABASE_URL` 和分项配置，优先使用 `DATABASE_URL` ## Docker 仓库现在提供了基础容器文件： - [Dockerfile](Dockerfile) - [Dockerfile-base](Dockerfile-base) - [docker-compose.yml](docker-compose.yml) - [.dockerignore](.dockerignore) 直接启动： ```bash cp .env.example .env docker compose up --build ``` 现在 Docker 镜像分成两层： - `Dockerfile-base` - 负责编译依赖和运行时底座 - 一般只在依赖变化时重建 - `Dockerfile` - 基于 `fast-tailor:base` 只拷贝项目代码 - 代码更新时重建更快如果要手动构建镜像，推荐这样： ```bash docker build -f Dockerfile-base -t fast-tailor:base . docker build -t fast-tailor:latest . ``` 如果要构最小版基础镜像： ```bash docker build -f Dockerfile-base -t fast-tailor:base-min \ --build-arg INSTALL_POSTGRESQL_CLIENT=false . ``` 说明： - `docker-compose.yml` 默认只包含应用本身的 3 个服务： - `fastapi` - `celery-worker` - `celery-beat` - `docker-compose.yml` 构建应用镜像时默认使用 [Dockerfile](Dockerfile)，因此本地应先准备好 `fast-tailor:base` - 容器入口统一走 [entrypoint.sh](entrypoint.sh)，会先执行 `alembic upgrade head`，再根据 `APP_ROLE` 启动对应进程 - `WORKERS` 同时控制 `uvicorn` worker 数和雪花 ID 的 worker 分配范围 - `CELERY_WORKER_CONCURRENCY` 控制 Celery worker 并发数 - 默认监听 `9307` - 默认 SQLite 数据目录会挂载到容器内 `/opt/fast/data` - Compose 通过 `.env` 注入绝大部分环境变量，避免在 `docker-compose.yml` 中重复维护大段 `environment` - 可以先用 [.env.example](.env.example) 生成一份 `.env`，再按实际环境修改数据库、Redis、SMTP 等配置 - 如果需要 Redis、PostgreSQL 等基础设施，建议接入外部现有服务，或在你自己的部署编排里单独提供 - 如果需要自定义配置，可以在运行前提供 `.env`，但 `DEBUG` 仍然必须是 `true/false` - 基础镜像会先复制 [core/plugin_settings.py](core/plugin_settings.py) 和 [uv_sync.py](uv_sync.py)，再通过 `uv_sync.py --print-extras` 解析当前静态插件需要的 Python extras - `asyncpg`、`redis`、`motor` 这类公共运行时依赖现在直接放在基础依赖中 - `INSTALL_POSTGRESQL_CLIENT=true` 时，基础镜像会额外安装 `psql` / `pg_dump` - `INSTALL_POSTGRESQL_CLIENT=false` 时，不会在基础镜像里安装 PostgreSQL 客户端工具 - 应用和 Celery 都通过环境变量 `TZ` 控制时区，默认是 `UTC` 如果要在 Docker Compose 里启 PostgreSQL： ```bash export DATABASE_SCHEME='postgresql+asyncpg' export DATABASE_HOST='postgres' export DATABASE_PORT='5432' export DATABASE_USER='fast_tailor' export DATABASE_PASSWORD='fast_tailor' export DATABASE_NAME='fast_tailor' docker compose --profile postgres up --build ``` 说明： - `postgres` 服务使用 Compose profile，默认不会启动 - `fastapi` 服务同时支持 `DATABASE_URL` 和分项数据库配置 - 首次切库后仍然要先跑 Alembic；compose 启动命令里已经包含这一步 ## Data Init 默认数据初始化走统一 registry，不再使用插件私有的 `initial_data()` 通道。当前链路是： 1. `core/app.py` 加载插件 2. 插件在 `bootstrap.py -> init_plugin(app)` 中注册默认数据任务 3. `lifespan` 阶段执行 `data_init_registry.run(...)` 通用注册 helper 在： - [core/db/lifecycle/data_init.py](core/db/lifecycle/data_init.py) 常见用法： - `register_data_tasks(plugin, callback, data=data_module)` ## Database 数据库主入口： - [core/db/session.py](core/db/session.py) - [core/db/model](core/db/model) - [core/db/schema](core/db/schema) 当前约定： - 运行时模型都应注册 schema - admin / model API / data init / CRUD 共用 schema 契约 - 不再保留“schema + fallback 反射”双轨逻辑 ## Auth 认证相关入口： - [plugins/auth/api/login.py](plugins/auth/api/login.py) - [plugins/auth/services/token.py](plugins/auth/services/token.py) - [plugins/auth/services/auth.py](plugins/auth/services/auth.py) 当前实现： - access token 使用 JWT - refresh token 默认启用服务端 cache 存储 - 同一用户再次登录会覆盖旧 refresh token - logout 会删除当前用户 refresh token cache 后端配置在 [core/config.py](core/config.py)，支持： - `CACHE_BACKEND=sqlite` - `CACHE_BACKEND=redis` ## Attachment Providers 默认安装只包含本地 provider。可选 extras： ```bash uv sync --extra attachment-oss uv sync --extra attachment-cos uv sync --extra attachment-s3 uv sync --extra attachment-all ``` 默认会创建一个本地 provider： - `code=default` - `provider_type=local` - `base_dir=data/files` ## Common Routes - `GET /healthz` - `POST /api/v1/auth/login` - `POST /api/v1/auth/refresh` - `POST /api/v1/auth/logout` - `GET /admin` - `POST /api/model/{model}/list` - `GET /api/attachment/providers` - `POST /api/attachment/upload` - `GET /area/search` - `GET /vpn` - `GET /message/list` - `GET /scheduler/task/list` ## Admin Relation Draft Payload admin 表单里的 `ONETOMANY` / `MANYTOMANY` 关联，当前支持把“页面临时记录”随主表单一起提交。推荐 payload 语义： ```json [ {"id": 12}, {"_state": "create", "name": "New Tag"}, {"_state": "update", "id": 18, "name": "Updated Tag"}, {"_state": "delete", "id": 21} ] ``` 约定： - `id` 存在且 `_state` 为空：保留现有记录，不做额外动作 - `_state=create`：创建新关联记录 - `_state=update`：更新已有关联记录 - `_state=delete`：从当前提交结果中移除该记录 - 没有 `id` 且 `_state` 为空：忽略，避免误创建当前 admin form 已支持： - `ONETOMANY` / `MANYTOMANY` 弹窗新增草稿记录 - 已有关联记录弹窗编辑，并在提交时转成 `_state=update` ## Testing 测试使用独立数据库，并在测试启动前自动执行 Alembic migration。常用命令： ```bash DEBUG=true uv run pytest DEBUG=true uv run pytest plugins/auth/tests/test_auth.py -q DEBUG=true uv run pytest plugins/admin/tests/test_admin.py -q ``` ## Notes - `DEBUG=release` 这类旧环境变量写法已经不再支持 - 新增运行时代码优先放到 `core/*`、`plugins/*`、`tests/*` 中 - 插件测试放在 `plugins//tests` 中，pytest 会根据 `core/plugin_settings.py` 的 `INSTALLED_PLUGINS` 收集启用插件的测试 - 插件目录和约束见 [plugins/README.md](plugins/README.md)