BuildingAI 帮助文档
BuildingAI 官网
  1. 插件与框架开发
  • 欢迎使用 BuildingAI
  • 演示环境
  • 用户社群
  • 企业版咨询
  • 产品线路图
  • 更新日志
  • API 赞助商
  • 积分获取方式
  • 应用安装教程「必看」
  • 使用教程
    • 快速使用
      • 对话
      • 智能体
      • 知识库
      • 工作流
      • MCP 服务
      • 登录配置
      • 密钥配置
      • 模型计费
      • 积分充值
      • 会员订阅
      • 卡密兑换
      • DIY装修
    • 常见配置教程
      • 微信支付配置
      • 支付宝支付配置
      • 微信公众号配置
      • OSS存储配置
      • 短信配置
      • 谷歌登录配置
      • Ollama配置
    • 应用配置教程
      • 香蕉绘画-使用教程
      • Sora2短剧视频-使用教程
      • 即梦AI绘画-使用教程
      • wan2.6漫剧-使用教程
    • 大模型申请教程
      • 即梦AI密钥-申请教程
      • 豆包大模型-申请教程
      • 通义千问-申请教程
    • 老版本教程
      • 功能使用教程
      • 智能体
      • MCP工具
      • DIY中心
  • 部署教程
    • 宝塔面板部署
    • Windows 环境下 Docker 部署
    • Docker方式安装
  • 开发文档
    • 网络接口
      • 登录注册
        • 账号密码登录
        • 账号密码注册
      • 前台
        • 文件上传/下载
          • 单个上传
          • 多个上传
          • 列表
          • 详情
          • 下载
          • 删除
        • 用户
          • 算力明细
          • 登录配置
        • AI聊天
          • 对话(非流式)
          • 流式对话
          • 对话记录
          • 对话详情
          • 修改记录
          • 删除记录
          • 获取记录对话
        • MCP
          • 列表
          • 所有记录
          • 详情:id
          • 创建
          • 修改
          • 可见状态
          • 添加
          • 关联详情
          • 系统MCP
          • json导入
          • 移除
          • 删除
          • 获取快捷菜单
          • 系统MCP详情:id
          • 连通性
          • 批量连通性
        • 充值中心
          • 充值中心
          • 充值提交订单
          • 充值记录
          • 预支付
          • 获取支付结果
        • 模型厂商
          • 列表
          • 详情:id
          • 详情:code
        • AI模型
          • 列表
          • 详情:id
          • 默认模型
        • 数据分析
          • 数据记录
        • 会员中心
          • 会员中心信息
          • 获取套餐列表
          • 预支付
          • 订阅提交订单
      • 后台
        • 工作空间
          • MCP
            • 列表
            • 详情
            • 创建
            • 修改
            • 删除
            • 批量删除
            • 启用状态
            • json导入
            • 连通性
            • 批量连通性
            • 获取快捷菜单
            • 设置快捷菜单
          • AI模型
            • 厂商管理
              • 列表
              • 新增
              • 详情:id
              • 详情:provider
              • 修改
              • 删除
              • 状态
            • 模型管理
              • 列表
              • 新增
              • 详情:id
              • 修改
              • 删除:id
              • 批量删除
              • 设为默认
              • 模型类型
              • 模型支持能力
              • 父级模型类型
          • AI知识库
            • 知识库列表
            • 知识库详情
            • 转移知识库
            • 知识库删除
            • 知识库文档列表
            • 知识库文档详情
            • 知识库文档删除
            • 知识库分段列表
            • 知识库分段详情
            • 知识库分段删除
            • 数据列表接口
          • AI智能体
            • 智能体创建
            • 智能体列表
            • 智能体详情
            • 智能体对话记录列表
            • 智能体对话记录详情
            • 智能体对话
            • 智能体发布API接口对话
            • 智能体发布API获取对话列表
            • 智能体发布API获取对话消息
            • 智能体发布API更新对话
            • 智能体发布API删除对话
          • 密钥管理
            • 密钥模板
              • 列表
              • 全部列表
              • 详情
              • 创建
              • 修改
              • 删除
              • 批量删除
              • 修改状态
              • json导入
            • 密钥配置
              • 列表
              • 列表:templateId
              • 创建
              • 统计
              • 详情
              • 完整详情
              • 修改
              • 修改状态
              • 删除
              • 批量删除
        • 用户管理
          • 列表
          • 创建
          • 详情:id
          • 删除
          • 批量删除
          • 重置密码
          • 更新状态
          • 重置随机密码
          • 登录设置
          • 登录设置
        • 角色管理
          • 创建
          • 详情:id
          • 修改
          • 删除
          • 列表
        • 菜单管理
          • 创建
          • 详情:id
          • 修改
          • 删除
          • 列表
        • 插件管理
          • 我的插件
            • 列表
            • 修改
            • 详情:id
            • 创建
            • 启用列表
            • 批量删除
            • 删除:id
            • 批量状态
            • 禁用:id
            • 启用:id
            • 是否存在:identifier
            • 详情:identifier
            • 入库插件详情:identifier
            • 本地列表
            • 类型列表
            • 版本列表:identifier
            • 安装
            • 卸载
          • 插件操作
            • 下载
            • 安装
          • 平台密钥
            • 获取开发者密钥
            • 设置开发者密钥
        • 权限管理
          • 列表
          • 扫描权限
          • 同步到库
          • 扫描接口
          • 清理废弃权限
          • 详情:code
        • 字典配置
          • 列表
        • 系统操作
          • 支付配置
            • 列表
            • 详情:id
            • 状态
            • 更新
          • 系统信息
            • 安装状态
            • 安装状态
          • pm2
            • 进程列表
            • 日志
            • 重启
            • 重载
            • 停止进程
            • 进程详情
            • 进程状态
            • 清空日志
            • 保存进程
            • 健康检查
            • 删除进程
        • 套餐充值
          • 获取套餐充值配置
          • 获取套餐充值配置 Copy
        • 财务
          • 财务中心
          • 用户余额明细
        • 订单管理
          • 充值订单列表
          • 充值订单详情
          • 充值订单退款
          • 会员订单列表
        • 渠道管理
          • 公众号配置
            • 详情
            • 修改
        • 数据分析
          • 数据看板
        • VIP 会员
          • 会员等级
            • 新增会员等级
            • 会员等级列表
            • 修改会员等级
            • 会员等级详情
            • 删除会员等级
          • 订阅计划
            • 新增订阅计划
            • 订阅计划设置
            • 设置会员功能状态
            • 更改订阅计划状态
            • 订阅计划详情
            • 修改订阅计划
            • 删除订阅计划
            • 更新订阅计划排序
      • 插件
        • 文章插件
          • 前台
            • 列表
          • 后台
            • 文章
              • 列表
              • 创建
            • 分类
              • 列表
              • 创建
        • 智能体-企业微信插件
          • 对话接口
        • 配图大师
          • 后台
            • 配图记录
            • 获取配图插件
            • 插件设置
    • 插件与框架开发
      • 技术规范
      • 前置准备
      • 本地部署与开发
      • 目录结构
      • 项目配置
      • 主程序启动链路
      • 请求处理链路
      • 后端开发约定
      • BaseController 与 BaseService
      • DTO、工具与通用服务
      • 前端开发
      • 主程序计费接入
      • 数据库与实体建议
      • AI SDK 开发文档
      • BuildingAI 升级开发文档
      • 应用开发
        • 介绍
        • 创建应用
        • 模板结构
        • 应用开发
        • 打包发布
        • 插件更新
        • 插件清单文件
        • 插件后端开发
        • 插件前端开发
        • Extension SDK 怎么用
        • 插件计费接入
        • 插件 AI 能力接入建议
        • Seeds、Upgrade 与存储
        • 插件升级开发文档
        • 构建与发布
      • PC 客户端
        • 开发文档
        • 构建文档
  • 设计资源
    • 官方素材库
  • 政策
    • 开源许可
    • 服务条款
    • 隐私政策
  1. 插件与框架开发

BuildingAI 升级开发文档

本文是教作为开发者如果进行升级脚本书写:
什么时候需要写 migration
什么时候需要写 Upgrade
Upgrade 应该怎么写
有没有命令可以生成升级文件
写完以后系统是怎么识别并执行的
本文适用于主程序范围内的二开:
packages/api
packages/client
packages/core
packages/@buildingai/*

1. 先记住一句话#

主程序升级的执行顺序是:
migration -> Upgrade -> data/versions/<version>
也就是说:
1.
先做数据库结构升级
2.
再做业务数据升级
3.
最后写版本完成标记
对应入口在:
packages/api/src/core/database/services/database-init.service.ts
packages/api/src/core/database/services/version-manager.service.ts

2. migration 和 Upgrade 到底怎么分#

这是二开时最容易写错的地方。

2.1 什么时候写 migration#

只要你改的是“数据库结构”,就应该优先写 migration。
典型场景:
新增表
新增字段
修改字段类型
新增索引
新增约束
重命名表或字段
一句话判断:
如果这次改动可以描述成“数据库 schema 变了”,就写 migration。

2.2 什么时候写 Upgrade#

只要你改的是“已有数据怎么迁移、修复、初始化”,就应该写 Upgrade。
典型场景:
给旧数据补默认值
把旧配置结构改成新配置结构
新版本上线后要批量清洗历史数据
新增功能需要初始化系统数据、菜单数据、配置数据
需要跨表读取旧数据再写入新表
一句话判断:
如果这次改动依赖“读取已有数据后再处理”,就写 Upgrade。

2.3 什么情况两者都要写#

很常见。
比如你给某张表新增了一个字段 status:
1.
migration:先把字段加出来
2.
Upgrade:再把历史数据的 status 补成合理值
这就是最标准的写法。

2.4 什么情况两者都不用写#

下面这些通常不需要升级脚本:
纯前端页面调整
纯接口逻辑调整,但不涉及历史数据
文案、样式、交互变化
只改了运行时计算逻辑,没有改数据库结构和存量数据

3. 主程序 migration 写在哪里#

源码目录:
packages/@buildingai/db/src/migrations/
运行时实际读取的是构建产物:
packages/@buildingai/db/dist/migrations/
升级器对文件名的识别规则是:
{timestamp}-{version}-{description}.js
源码里对应的 ts 文件命名也应该遵循同样结构,例如:
1776000000000-26.1.0-add-report-table.ts
仓库里的现有例子:
packages/@buildingai/db/src/migrations/1765088629599-25.1.0-add-member.ts
packages/@buildingai/db/src/migrations/1774943726484-26.0.0-upgrade.ts

4. 主程序 migration 有哪些生成命令#

@buildingai/db 里已经提供了生成命令。
进入目录:

4.1 手工创建 migration 模板#

例如:
这个命令会:
1.
在 src/migrations/ 下创建文件
2.
帮你生成基础模板
3.
需要你自己补 SQL 或 TypeORM 逻辑

4.2 根据实体变化自动生成 migration#

例如:
这个命令会:
1.
对比实体定义和当前数据库 schema
2.
自动生成 migration
3.
自动改名成项目要求的版本命名格式
使用前提:
数据库必须是实体文件改动前的数据库
数据库必须可连接
.env 已配置数据库连接
实体变更已经写好

5. 主程序 Upgrade 写在哪里#

主程序 Upgrade 归 @buildingai/upgrade 包管理。
推荐目录:
packages/@buildingai/upgrade/src/scripts/<version>/index.ts
例如:
packages/@buildingai/upgrade/src/scripts/26.1.0/index.ts
兼容旧写法:
packages/@buildingai/upgrade/src/scripts/26.1.0.ts
但从加载逻辑看,优先推荐目录形式:
scripts/<version>/index.js

6. 主程序 Upgrade 有没有生成命令#

目前仓库里没有“自动生成 Upgrade 文件”的现成命令。
也就是说:
migration:可以用脚本创建或自动生成
Upgrade:需要你按约定目录手工新建文件
这是二开文档里最重要的一个现实约束。

7. 主程序 Upgrade 的最小写法#

最推荐直接继承 BaseUpgradeScript。
示例:
import { BaseUpgradeScript, UpgradeContext } from "../../index";

export class Upgrade extends BaseUpgradeScript {
    readonly version = "26.1.0";

    async execute(context: UpgradeContext): Promise<void> {
        this.log("Start upgrading data for 26.1.0");

        const { dataSource } = context;

        await dataSource.query(`
            UPDATE report
            SET summary = ''
            WHERE summary IS NULL
        `);

        this.success("Upgrade finished");
    }
}

export default Upgrade;
关键点:
1.
类名建议叫 Upgrade
2.
要实现 execute(context)
3.
version 要和目录版本一致
4.
推荐同时 export default Upgrade
相关基础类型定义在:
packages/@buildingai/upgrade/src/index.ts

8. 主程序 Upgrade 里最常用的方法怎么用#

execute(context) 里最核心的是 context.dataSource。

8.1 执行原生 SQL#

适合:
批量更新
一次性修复旧数据
复杂 SQL
示例:
await context.dataSource.query(
    `
    UPDATE "config"
    SET value = $1
    WHERE key = $2
    `,
    [JSON.stringify({ enabled: true }), "site_settings"],
);

8.2 用 Repository 读写实体#

适合:
你已经有明确实体
想利用实体映射和条件查询
示例:
const repo = context.dataSource.getRepository("User");

const users = await repo.find({
    where: { status: "active" },
});

for (const user of users) {
    user.nickname = user.nickname || user.username;
}

await repo.save(users);

8.3 用 dataSource.manager#

适合:
想统一通过 manager 操作多个实体
示例:
const manager = context.dataSource.manager;

const items = await manager.find("Config", {
    where: { group: "system" },
});

8.4 用事务#

只要你的升级逻辑里包含“多个步骤必须一起成功”,就建议显式开事务。
示例:
const queryRunner = context.dataSource.createQueryRunner();
await queryRunner.connect();
await queryRunner.startTransaction();

try {
    await queryRunner.query(`
        UPDATE "report"
        SET "status" = 'ready'
        WHERE "status" IS NULL
    `);

    await queryRunner.query(`
        INSERT INTO "audit_log" ("action")
        VALUES ('upgrade-26.1.0')
    `);

    await queryRunner.commitTransaction();
} catch (error) {
    await queryRunner.rollbackTransaction();
    throw error;
} finally {
    await queryRunner.release();
}

9. 如何决定“写 migration 还是写 Upgrade”#

可以直接按下面这张表判断:
场景应该写什么
新增表、字段、索引migration
把旧字段数据迁移到新字段migration + Upgrade
给旧数据补默认值Upgrade
清理脏数据Upgrade
初始化新版本系统配置Upgrade
纯前端改动都不用

10. 写 Upgrade 时的几个硬规则#

10.1 尽量幂等#

也就是重复执行不要把数据写坏。
例如:
先判断字段值是不是已经迁移过
UPDATE ... WHERE target IS NULL
INSERT 前先查是否已存在

10.2 不要把建表、加字段写进 Upgrade#

结构变更必须优先放 migration。
因为系统执行顺序本来就是:
migration -> Upgrade
如果你把 DDL 塞进 Upgrade,后面维护会很乱。

10.3 一个版本只处理这个版本该做的事#

不要把很多历史修复混进同一个脚本。
建议按版本拆开,这样升级失败时更容易定位。

10.4 日志要能看懂#

建议至少打这些日志:
开始执行
当前处理批次/数据量
完成

11. 写完之后怎么让系统识别#

主程序升级器识别版本的依据是:
1.
根目录 package.json.version
2.
@buildingai/db 构建产物里的 migration
3.
@buildingai/upgrade 构建产物里的脚本
所以你写完升级代码后,通常需要:
然后重启应用。
系统启动时会自动:
1.
判断 data/versions/<current-version> 是否存在
2.
如果不存在,就按版本顺序跑 migration
3.
再跑 Upgrade
4.
最后写版本文件

12. 开发者最常见的几个错误#

12.1 只改了 Upgrade,没改版本号#

如果当前版本文件已经存在,升级器不会再跑。
所以:
新增升级逻辑通常意味着新版本
主程序版本要和你的升级内容对应

12.2 把数据修复写进 migration#

少量简单数据修复可以接受,但涉及复杂业务逻辑时应该拆到 Upgrade。

12.3 Upgrade 写得不可重复执行#

一旦第一次跑到一半失败,第二次重启可能继续撞错。

12.4 写了源码但没构建#

升级器读的是构建产物,不是源码目录。

13. 推荐开发流程#

当你给主程序新增一个版本升级逻辑时,推荐顺序:
1.
先确认这次改动是 schema 变化、数据变化,还是两者都有
2.
schema 变化先创建 migration
3.
数据变化再手工补 Upgrade
4.
把版本号提升到目标版本
5.
pnpm build
6.
在测试库启动验证
7.
确认 data/versions/<version> 已写入

14. 你可以直接照抄的判断标准#

如果你只记一段,记下面这段就够了:
改表结构:写 migration
改历史数据:写 Upgrade
两者都有:两个都写,先 migration 后 Upgrade
纯前端或纯运行时逻辑:通常都不用写
migration 有生成命令,Upgrade 没有,需要手工创建
修改于 2026-04-17 03:31:37
上一页
AI SDK 开发文档
下一页
介绍
Built with