企业官网建设流程全解析

• 后端
• 即时通讯

nonebot-plugin-orm是 NoneBot 的官方数据库支持插件，基于 SQLAlchemy 与 Alembic 构建，为机器人项目提供多数据库后端支持、会话管理、关系模型管理与数据库迁移能力。本指南面向插件使用者（而非插件开发者），从安装、日常迁移操作到数据库连接配置逐层展开，读完即可独立完成"安装带数据库的插件、升级/回滚数据库、按插件隔离连接"的全部日常操作。

阅读前提：区分项目名与模块名

在开始之前，请务必分清两个概念，nonebot-plugin-orm的所有 CLI 操作都依赖这一点：

• 项目名（Project Name）：用于代码仓库与 PyPI 发布名称，以nonebot-plugin-开头、词间用横杠分隔，例如nonebot-plugin-wordcloud；
• 模块名（Module Name）：用于程序导入，以nonebot_plugin_开头、词间用下划线分隔，例如nonebot_plugin_wordcloud。

在nb orm系列命令中，统一使用插件模块名（下划线形式）。有关命名规范更完整的约定，可参见 插件命名规范。

快速上手：创建一个带数据库插件的机器人

假设我们要新建一个机器人，并安装一个使用数据库存储数据的插件（以nonebot-plugin-wordcloud为例），完整步骤如下：

nb init # 初始化项目文件夹 pip install nonebot-plugin-orm[sqlite] # 安装 nonebot-plugin-orm，并附带 SQLite 支持 nb plugin install nonebot-plugin-wordcloud # 安装插件 # nb orm heads # 查看有什么插件使用到了数据库（可选） nb orm upgrade # 升级数据库 # nb orm check # 检查一下数据库模式是否与模型定义一致（可选） nb run # 启动机器人

其中各步骤的含义：

1. nb init借助 nb-cli 脚手架生成标准 NoneBot 项目骨架；
2. pip install nonebot-plugin-orm[sqlite]安装 ORM 插件本体，[sqlite]额外附加 SQLite 异步驱动（aiosqlite）。nonebot-plugin-orm只提供 ORM 与迁移能力，本身不含数据库驱动与后端，需按所选数据库另行安装对应 extra；
3. nb plugin install安装目标插件；
4. nb orm upgrade将数据库模式同步到当前所有插件模型的最新状态——安装新插件或升级插件版本后必须执行；
5. 可选地执行nb orm heads观察各插件对应的迁移分支，执行nb orm check验证模式一致性；
6. nb run启动机器人。

关于数据库驱动的更多说明（SQLite / PostgreSQL / MySQL 各自的安装方式与连接串格式），见 数据库驱动和后端。

卸载插件并删除其数据

如果不再需要某个插件，且希望连同它的数据一并清除，按如下顺序操作：

nb plugin uninstall nonebot-plugin-wordcloud # 卸载插件 # nb orm heads # 查看有什么插件使用到了数据库。（可选） nb orm downgrade nonebot_plugin_wordcloud@base # 降级数据库，删除数据 # nb orm check # 检查一下数据库模式是否与模型定义一致（可选）

这里的关键是nb orm downgrade <插件模块名>@base：将指定插件分支回滚到初始状态（base），从而删除该插件创建的所有表和数据。注意此处的模块名使用下划线形式nonebot_plugin_wordcloud，而非项目名nonebot-plugin-wordcloud。

CLI 命令详解

nb orm是nonebot-plugin-orm暴露给 nb-cli 的迁移命令组，下面逐条解析上文示例中出现的命令。

heads：查看迁移分支头

nb orm heads

显示所有的迁移分支头（branch heads），一般一个分支对应一个使用数据库的插件。输出格式为<迁移 ID> (<插件模块名>) (<头部类型>)：

46327b837dd8 (nonebot_plugin_chatrecorder) (head) 9492159f98f7 (nonebot_plugin_user) (head) 71a72119935f (nonebot_plugin_session_orm) (effective head) ade8cdca5470 (nonebot_plugin_wordcloud) (head)

• head：该分支的最新迁移；
• effective head：当前生效的整体头部（多分支汇合后的全局最新状态）。

执行此命令可以快速了解：当前安装了哪些使用数据库的插件、各自处于什么迁移版本。

upgrade：升级数据库

nb orm upgrade <插件模块名>@<迁移 ID>

<插件模块名>@<迁移 ID>为可选参数。不带参数时，将所有分支升级到各自的最新版本，这也是最常见的用法：

nb orm upgrade

每次安装新插件或更新插件版本后，都需要执行一次（不带参数的）升级命令，将数据库模式同步到与机器人当前代码一致的状态。

downgrade：降级数据库

nb orm downgrade <插件模块名>@<迁移 ID>

当需要回滚插件版本或删除插件时使用。<迁移 ID>也可以是base，即回滚到初始状态（相当于该插件从未创建过数据），常用于卸载插件后删除其数据：

nb orm downgrade <插件模块名>@base

check：检查模式一致性

nb orm check

检查数据库模式是否与模型定义一致。若不一致会给出具体的差异（例如缺失的表、列等）。值得注意的是：机器人启动前会自动运行此命令（当ALEMBIC_STARTUP_CHECK=true时），并在检查失败时阻止启动——这正是"定义了模型但没迁移就启动会报错"的机制来源。

迁移脚本从何而来

upgrade/downgrade所驱动的迁移脚本由 Alembic 自动生成，开发插件时通过以下命令创建：

nb orm revision -m "first revision" --branch-label weather

其中-m是迁移描述，--branch-label指定分支（一般为插件模块名）。生成的脚本位于插件包内的migrations目录，记录数据库模式的增量变化；脚本主体是upgrade()/downgrade()一对互逆操作，分别对应建表与删表等 DDL 语句。因此数据库迁移可以像 git 管理代码一样可复现、可逆地同步模式。官方强烈建议：永远检查自动生成的迁移脚本，并在开发环境中测试后再执行，迁移脚本中的任何错误都可能导致数据丢失。

开发阶段若频繁修改模型，可临时关闭启动检查（.env.dev）：

ALEMBIC_STARTUP_CHECK=false

此时每次启动机器人都会自动将数据库模式与模型定义同步，省去手动迁移的繁琐。

配置项详解

nonebot-plugin-orm通过 NoneBot 的全局配置（.env/.env.prod等）读取以下配置项，用于控制默认数据库连接与引擎行为。

sqlalchemy_database_url：默认数据库连接 URL

默认数据库连接 URL，所有未单独指定绑定的插件（含机器人核心）都使用此连接：

SQLALCHEMY_DATABASE_URL=dialect+driver://username:password@host:port/database

连接串采用 SQLAlchemy 标准的dialect+driver格式，例如：

• SQLite：sqlite+aiosqlite:///file_path（不指定路径时，默认数据库文件为<data path>/nonebot-plugin-orm/db.sqlite3，其中数据目录由nonebot-plugin-localstore提供，参见 本地存储）；
• PostgreSQL：postgresql+psycopg://user:password@host:port/dbname；
• MySQL / MariaDB：mysql+aiomysql://user:password@host:port/dbname。

连接串的完整语法约定，参考 SQLAlchemy 官方"引擎配置 / Database URLs"一节。

sqlalchemy_bind：按插件绑定不同数据库

将bind keys（一般为插件模块名）映射到数据库连接 URL、create_async_engine()参数字典或AsyncEngine实例的字典，实现"不同插件使用不同数据库"的隔离。

例如，让nonebot-plugin-wordcloud使用一个 SQLite 数据库并开启 Echo 选项便于调试，而其他所有插件使用默认的 PostgreSQL 数据库：

SQLALCHEMY_BINDS='{ "": "postgresql+psycopg://scott:tiger@localhost/mydatabase", "nonebot_plugin_wordcloud": { "url": "sqlite+aiosqlite://", "echo": true } }'

• 键为""（空字符串）时对应默认连接（即sqlalchemy_database_url的取值）；
• 键为插件模块名（如nonebot_plugin_wordcloud）时，为该插件单独指定连接；
• 值为字符串表示直接给出 URL；值为字典表示传给create_async_engine()的参数（url与echo等）。

sqlalchemy_engine_options：引擎默认参数

作为create_async_engine()的默认参数字典，对未在 bind 中单独指定的引擎生效：

SQLALCHEMY_ENGINE_OPTIONS='{ "pool_size": 5, "max_overflow": 10, "pool_timeout": 30, "pool_recycle": 3600, "echo": true }'

• pool_size：连接池保留的连接数（默认 5）；
• max_overflow：连接池满后可额外创建的连接数（默认 10）；
• pool_timeout：等待连接超时秒数（默认 30）；
• pool_recycle：连接回收间隔秒数，防止数据库端主动断开闲置连接（默认 3600）；
• echo：打印引擎执行的所有 SQL 语句，便于调试。

sqlalchemy_echo：全局调试开关

一键开启 SQL 与连接池日志，等价于同时打开引擎的 Echo 与 Echo Pool 选项：

SQLALCHEMY_ECHO=true

调试完成后建议关闭，避免日志刷屏影响性能。

配置覆盖优先级

以上配置之间存在覆盖关系，遵循"特殊优先于一般"的原则，具体优先级为：

sqlalchemy_database_url > sqlalchemy_bind > sqlalchemy_echo > sqlalchemy_engine_options

即：sqlalchemy_database_url决定默认连接；sqlalchemy_bind可以针对特定插件覆盖默认连接；sqlalchemy_echo覆盖全局 echo 行为；sqlalchemy_engine_options作为兜底默认参数。由于覆盖顺序并非显而易见，官方建议只配置必要的选项，避免多个配置项叠加产生难以排查的意外行为。

数据库驱动与后端选型

nonebot-plugin-orm仅提供 ORM 与迁移能力，本身不包含数据库后端与驱动，需要按目标数据库另行安装：

• SQLite：轻量嵌入式数据库，数据以单文件存储、无需独立后端，适合开发环境与小型应用，但不建议用于大型生产环境；
• PostgreSQL：开源关系数据库中对各类高级功能支持最为完善，是中小型应用的首选；
• MySQL / MariaDB：经典开源关系数据库，同样适合中小型应用。

安装并配置完成后，执行nb orm upgrade完成首次迁移，再执行nb orm check验证，若输出"没有检测到新的升级操作"，即可启动机器人。

进阶阅读：会话、依赖注入与自动化测试

用户指南之外，nonebot-plugin-orm面向插件开发者的能力同样围绕上述 CLI 与配置展开，可作为深入使用的延伸：

• 会话管理：插件通过async_scoped_session（作用域为当前事件与事件响应器）或get_session()（新会话，需手动管理）依赖注入获取 ORM 会话，配合session.get()、session.add()、session.commit()完成增删改查；模型与 ORM 会话不应存入 NoneBot 会话状态，参见 开发者指南示例；
• 依赖注入：Model类可作为依赖直接注入查询结果，SQLDepends可将任意 SQL 语句（通常为select）包装为依赖，类型标注决定返回"迭代器/标量、单个/多个、连续/分块"等数据结构，详见 依赖注入；
• 多后端测试：官方推荐用 GitHub Actions 构建测试矩阵，通过SQLALCHEMY_DATABASE_URL环境变量在 SQLite / PostgreSQL / MySQL 三种后端上分别执行nb orm upgrade后运行pytest，从而保证插件在不同数据库上的兼容性，详见 测试指南。

小结

对普通用户而言，nonebot-plugin-orm的日常使用可以浓缩为四条命令、四个配置项：

• 命令：nb orm heads（查看分支）→nb orm upgrade（升级）→nb orm downgrade <模块名>@base（回滚/删数据）→nb orm check（校验）；
• 配置：SQLALCHEMY_DATABASE_URL（默认连接）、SQLALCHEMY_BINDS（按插件绑定）、SQLALCHEMY_ENGINE_OPTIONS（引擎默认参数）、SQLALCHEMY_ECHO（调试开关），优先级依次递减。

牢记"项目名用横杠、模块名用下划线"，在安装新插件后执行一次nb orm upgrade，即可让机器人数据库始终与代码保持一致。

• 后端
• 即时通讯