Skip to content
GitHub

Plugins

The backend’s plugin system comes from upstream fastapi-best-architecture (FBA). Each plugin is a directory under apps/api/backend/plugin/ with a plugin.toml saying what it is, where it mounts, which settings it needs, which plugins it depends on and which databases it supports; at start-up the backend scans these directories and wires in their routes, settings and hooks. Approvals, the AI assistant, the open platform, SMS and notifications are all plugins. Since 1.0 the plugin interface is part of the compatibility promise: plugin.toml fields, the fba add install flow and the extension points listed below will not change in breaking ways, so third-party plugins keep installing and running (see Upgrading).

Plugins
ScreenPathWhoWhat it does
System → Plugins/system/pluginSuperusersOne card per plugin: description, version, tags, kind, supported databases, the actual API prefix, settings; enable / disable, Download zip, Uninstall, install from a zip or a git URL
Command linefba add / fba removeWhoever has server accessInstall / uninstall plugins, including tables and seed data

Every Plugins endpoint is guarded by superuser, not a permission code.

PluginWhat it isKindDependencies
aiAI assistantOwn routes
configConfigExtends admin
dictData dictionaryExtends adminRequired, cannot be uninstalled
emailSending emailOwn routesplugin.toml declares only PostgreSQL and MySQL; it has no tables
noticeNoticesExtends adminnotification
notificationIn-app messages and channel routingExtends admin
oauth2GitHub / Google third-party sign-inOwn routes
openOpen API (AK/SK endpoints, webhooks)Own routes
smsSMS (Alibaba Cloud / Tencent Cloud)Own routes
workflowApproval workflowExtends adminnotification

Extending plugins merge their routes into an existing app (config’s endpoints land at /api/v1/sys/configs, for example); own-route plugins bring their own set. The Plugins page lists both the declared prefix and the actual mount point.

[plugin]
summary = "审批流" # 1–100 characters
version = "0.0.1" # x.y.z
description = "…" # 1–500 characters
author = "yile"
tags = ["other"] # ai / mcp / agent / auth / storage / notification / task / payment / other
database = ["mysql", "postgresql", "sqlserver"]
depends_on = ["notification"] # Plugins this one needs; no self-dependency, cycles or missing ones are errors
[app]
extend = "admin" # Extending: merged into backend.app.admin.api under the same path
# router = ["v1"] # Own routes: these routers are taken from the plugin's api/router.py
[api.workflow] # The key must match a file name under api/
prefix = "/workflow"
tags = "审批流"
[settings] # Upper-case keys; values are strings, numbers, booleans or lists of strings
WORKFLOW_AI_APPROVE_ENABLED = true
  • Dependency order decides the order of route injection and of SQL execution in fba init.
  • A plugin with model/ must declare database and ship complete init / destroy SQL for each declared database (SQL Server only needs the snowflake-key pair).
  • How [settings] reaches settings: precedence is process environment > .env > plugin.toml. But a key written only in plugin.toml and not declared in core/conf.py is an “extra” that container environment variables cannot override, which is why every built-in plugin setting is declared again in conf.py (type only, no default). Conversely, a key declared in conf.py with a default ignores the value in plugin.toml.
  • A plugin’s requirements.txt is installed with uv pip and checked again on every backend start; its .env.example is appended to .env on install.

How do I install, uninstall or disable a plugin?

Section titled “How do I install, uninstall or disable a plugin?”

Command-line install (development environments only):

终端窗口
fba add --path ./my_plugin.zip # or --repo-url <git URL>
fba add --path ./my_plugin.zip --no-sql # no tables, no seed SQL

It unzips or clones, appends .env.example, installs dependencies, creates the plugin’s tables and runs the init SQL for the current database. It does not use Alembic migrations. Zip requirements: the plugin directory at the root, containing at least plugin.toml and README.md; the plugin name comes from the zip’s file name. fba remove <plugin> runs the destroy SQL, uninstalls dependencies, packs the directory into a .backup.zip and deletes it; required plugins are refused. Restart the backend after either.

Install / uninstall on the Plugins page is also development-only, but creates no tables and runs no SQL (uninstall runs no destroy SQL either); on success it says to configure per the plugin’s README and restart. Use the command line when tables are needed.

Enable / disable is the switch on the Plugins page, stored in Redis.

  • Disabling takes effect immediately: every plugin’s routes are mounted at start-up and each request checks the plugin’s status first, so a disabled plugin’s endpoints return “Plugin X is not enabled, please contact the administrator” (HTTP 500).
  • A disabled plugin’s AI tools disappear from the tool list; disabling ai also closes the MCP gateway.
  • Plugin start-up hooks (setup / lifespan) only run for plugins enabled at start-up, so that part needs a restart; a newly installed plugin’s routes also appear only after a restart.
  • Disabling does not hide menus: those sidebar entries remain and their endpoints fail.

At start-up these file names are looked for in every plugin directory and loaded if present:

FileRegistersBuilt-in users
hooks.pyThe setup(app), lifespan and otel(app) hooksai
notification_kinds.pyNotification kinds (allowed channels, default policies), see Messages and notificationsnotice, open, workflow
data_change.pyData change history registrations, see Logs and auditconfig, oauth2
dataio.pyImport / export resources, see Import and exportdict, notice
webhook_events.pyOpen-platform webhook eventsworkflow
sms_templates.py · sms_providers.pySMS business templates · SMS providersworkflow (templates)
ai_tools.pyTools the AI assistant can call, see AI assistantworkflow

These scans do not check whether the plugin is enabled: a disabled plugin’s notification kinds and import / export resources stay registered, its endpoints just fail.

The frontend does not pick up a plugin’s pages automatically. For a plugin to have pages in the admin it needs:

  1. A page component under packages/platform/src/pages/<name>/
  2. A route file under apps/web/src/routes/_auth/
  3. A “route → component” entry in apps/web/src/lib/page-registry.tsx (multi-tab mounts pages through it)
  4. Menu rows in the plugin’s init SQL

A menu whose path has no frontend route is skipped in the sidebar, with a console warning in development. The full “add a page” walkthrough is Adding a business module from scratch.

  • Installing / uninstalling on the Plugins page creates no tables and runs no SQL; production cannot install plugins from the page.
  • Disabling a plugin does not hide its menus, and calls to a disabled plugin return 500 rather than a more fitting status.
  • The enable switch does not check required plugins, so dict can be disabled on the page.
  • When the Plugins page judges “supported databases”, the current database is hard-coded as SQL Server instead of reading the actual DATABASE_TYPE.
  • The built-in ai, sms and workflow plugins have no README.md, so downloading their zip from the page and installing it again fails the “must have a README” check.
  • The plugin conventions are backend-only; frontend pages are wired by hand as in the four steps above.
  • tests/test_plugin_order_is_deterministic.py: plugins sorted by dependency come out in the same order every time. tests/test_sql_scripts.py: every plugin’s SQL scripts are present.
  • Effects of disabling: disabling ai closes the MCP gateway (test_ai_mcp.py); disabling workflow removes its AI tools (test_ai_workflow_tools.py).
  • Not tested: plugin.toml validation, the installer, the Plugins endpoints; the Plugins page has no E2E.

On the live demo (admin / 123456), open System → Plugins to see each plugin’s declared and actual API prefix and its settings. The demo is not a development environment, so install and uninstall are refused; please don’t disable plugins, everyone shares this instance.