BISHENG 后端运维脚本实战指南数据导出、权限迁移回填与租户数据修复全解析【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng导读本文以 BISHENG 开源仓库中 scripts 目录说明文档 为骨架系统梳理后端所有手工维护与迁移脚本的用途、命令、参数与底层实现原理。这些脚本覆盖四大类场景日常模式对话导出、RBAC→ReBAC 权限体系迁移与对账、LinsightF035升级数据迁移、以及多租户/知识空间/部门树的历史数据修复与压测数据灌入。读完本文你将掌握在src/backend目录下安全运行这些一次性脚本的正确姿势——包括默认 dry-run 的安全约定、--apply的写入开关、幂等设计与脚本间的顺序依赖并能从源码层面理解main.py启动期自动回填与手工脚本的分工边界。一、脚本目录定位与通用运行约定src/backend/scripts/存放的是手工维护与迁移脚本manual maintenance and migration scripts与随服务启动自动执行的初始化逻辑互补。运行这些脚本前请先掌握三条通用约定运行位置绝大多数 Python 脚本要求从src/backend/目录下执行并通过PYTHONPATH./让解释器能导入bisheng包解释器使用项目虚拟环境.venv/bin/pythonscripts/seed_load_test_org.py的示例中也有直接用python的写法取决于你的环境配置加载多数脚本通过config环境变量指定配置文件缺省时回落为config.yaml例如configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/xxx.py。目录内还提供了一批.sh包装脚本如 migrate_workstation_models_to_workbench.sh、backfill_knowledge_space_user_pin.sh 等它们会自动探测解释器 /PYTHONPATH/ config把--apply位置参数透传给 Python 脚本便于手工运维直接调用。说明README 中记载的export_daily_chat_messages.py与reconcile_permission_migration_db.py/.sh未出现在当前仓库快照的 scripts 目录列表中命令与参数契约以 README 为准实际使用时请以部署版本目录内容为准。二、导出类脚本日常模式对话导出export_daily_chat_messages.py该脚本导出**日常模式flow_type 15**的对话内容默认导出最近 30 天的消息并按会话聚合为 JSON。核心用法PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py --days 7 PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py --format csv PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py --tenant-id 3 PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py --full-session参数说明参数默认值作用--config环境变量config否则config.yaml指定配置文件--days30导出最近多少天的消息--formatjson输出格式json或csv--tenant-id无仅导出指定租户--user-id无仅导出指定用户--chat-id无仅导出指定会话--include-deleted关包含已删除会话--full-session关只要会话在时间窗口内活跃就导出该会话的全部消息而非仅窗口内消息日常模式在 BISHENG 中对应工作站对话flow_type 15导出产物适合作为合规留存、数据迁移或分析的输入。三、权限模型迁移与回填脚本权限类脚本解决两类问题模型配置迁移把旧位置的配置搬到新位置与权限数据回填为历史存量数据补齐缺失的授权信息。这类脚本的共同特点是默认 dry-run、--apply才写库、幂等可重跑。1.migrate_workstation_models_to_workbench.py工作台模型配置迁移一次性迁移脚本把旧的全局每日工作台模型列表从config.key workstation行迁移到默认租户的tenant_system_model_config.key linsight_llm行。行为要点读取workstation.models来自config表只写默认租户tenant_id 1若 Root 已有linsight_llm行仅合并更新models字段若 Root 没有linsight_llm行则新建一行保留旧的workstation.models不动后续 UI 保存流程可自行清理/覆盖。PYTHONPATH./ .venv/bin/python scripts/migrate_workstation_models_to_workbench.py PYTHONPATH./ .venv/bin/python scripts/migrate_workstation_models_to_workbench.py --apply bash scripts/migrate_workstation_models_to_workbench.sh bash scripts/migrate_workstation_models_to_workbench.sh apply2.migrate_channel_permissions_for_relation_models.py自定义资源权限模板回填把 channel 模块的默认权限回填进 channel 模块出现之前创建的旧自定义关系模型资源权限模板。注意它的适用对象是is_system false的自定义模型读取全局config.key permission_relation_models_v1JSON 列表对每个没有任何 channel 权限 id 的自定义模型按其继承档位owner/manager/editor/viewer追加 channel 默认权限来源为channel_permission_template.default_permission_ids_for_relation跳过系统模型它们在运行时从模板动态计算 channel 默认值跳过已含任一 channel 权限 id 的自定义模型绝不覆盖管理员显式做过的 channel 定制保留所有非 channel 权限。PYTHONPATH./ .venv/bin/python scripts/migrate_channel_permissions_for_relation_models.py PYTHONPATH./ .venv/bin/python scripts/migrate_channel_permissions_for_relation_models.py --apply bash scripts/migrate_channel_permissions_for_relation_models.sh bash scripts/migrate_channel_permissions_for_relation_models.sh apply3.backfill_relation_model_move_permissions.py冻结系统档位的 F034 移动权限回填这是大部分情况下无需手动执行的脚本相同的幂等回填已在每次后端启动时自动运行接线在 main.py 的 lifespan 中第 61-64 行调用了backfill_relation_model_move_permissions正常升级 重启即可自愈。独立脚本的存在价值仅在于不重启修复环境或先预览改动。要理解它需要先理解permission_relation_models_v1配置行中每个系统档位的permissions_explicit开关见 backfill_relation_model_move_permissions.py 的 docstringpermissions_explicitFalse默认 seed 值勾选状态读取时按代码模板动态计算调用default_permission_ids_for_relation(relation)现算新增权限如本次的move_file/move_folder会自动出现无需回填permissions_explicitTrue勾选状态是保存那一刻冻结的快照update_relation_model保存 permissions 时会把开关翻成 True。模板后来新增的权限不会自动补进快照——这正是所有者/可管理档位缺移动权限的根因。脚本行为对每个系统is_system true且已冻结permissions_explicit true的档位计算目标权限集{move_file, move_folder} ∩ default_permission_ids_for_relation(relation)所有者 / 可管理 / 可编辑can_edit 及以上→ 两个都补可查看viewer→ 交集为空不补只把缺失的这两个 id并入permissions[]不动其它任何已勾选项跳过动态档位permissions_explicit false和自定义is_system false档位幂等补齐后重跑无变化。在 relation_model_backfill.py 中可以看到核心逻辑apply_move_permission_backfill的实现NEW_PERMISSION_IDS default_permission_ids_for_relation(relation or )计算交集且仅当m.get(is_system) and m.get(permissions_explicit) is True时才处理。脚本主流程L76-L110直连 DB 读取Config行、JSON 解析、dry-run 打印、--apply时写回整行配置并提交。安全保证源码 docstring 明确声明只新增move_file/move_folder绝不删除或重置已有勾选只动 system explicitTrue 的档位单次写整行配置失败回滚该 config key 不走 Redis 缓存aget_config_by_key直连 DB运行中的进程下次读取即生效无需重启。# 从 src/backend/ 运行 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_relation_model_move_permissions.py configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_relation_model_move_permissions.py --apply4.backfill_channel_member_rebac_grants.py修复缺失的频道成员 ReBAC 授权修复在 commitc530bf375之前就已激活、因此从未写入 ReBAC grant的频道订阅者。由于成员管理/授权列表是从 OpenFGA tuple 渲染的这类成员在space_channel_member中处于激活态却在授权列表中不可见。行为扫描频道全部或--channel-id指定单个筛选status ACTIVE、非CREATOR、直接grant_subject_type为NULL/self成员对每个在 FGA 上没有既有 grant 的成员通过ChannelService.sync_direct_channel_user_permissions写入 viewer/manager grant 与关系模型绑定幂等跳过创建者owner 由OwnerService管理、PENDING/REJECTED成员、组织授权成员、以及 FGA 中已存在的成员。PYTHONPATH./ .venv/bin/python scripts/backfill_channel_member_rebac_grants.py PYTHONPATH./ .venv/bin/python scripts/backfill_channel_member_rebac_grants.py --apply PYTHONPATH./ .venv/bin/python scripts/backfill_channel_member_rebac_grants.py --channel-id id --apply bash scripts/backfill_channel_member_rebac_grants.sh bash scripts/backfill_channel_member_rebac_grants.sh apply bash scripts/backfill_channel_member_rebac_grants.sh --channel-id id apply5.clean_department_space_user_group_grants.py清理部门空间的用户组授权F033 的一次性清理。部门知识空间不再允许用户组授权维度API 拒绝新增 user_group grant客户端也隐藏了对应 Tab本脚本移除部门空间上历史遗留的 user_group grant——撤销 OpenFGA tuple 并删除关系模型绑定运行时代码不再为这些 grant 保留兼容路径。行为扫描每个部门知识空间DepartmentKnowledgeSpaceDao.aget_all将每个user_groupgrant 报告为(space_id, group_id, relation, affected_users)--apply时通过PermissionService.authorize撤销 grant 并移除绑定只处理部门空间的user_groupgrant——绝不触碰普通空间、也绝不处理 user/department grant。⚠️--apply不可逆会撤销组成员访问权限务必先 review dry-run 输出。export configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/clean_department_space_user_group_grants.py # dry-run PYTHONPATH./ .venv/bin/python scripts/clean_department_space_user_group_grants.py --apply # execute四、F006 RBAC → ReBAC 权限迁移与对账1.permission_migration.sh历史权限迁移手工执行器F006 历史权限迁移RBAC → ReBAC的手工运行入口。用法与模式详见 permission_migration.sh 源码实现bash bisheng/script/permission_migration.sh bash bisheng/script/permission_migration.sh dry_run bash bisheng/script/permission_migration.sh verify bash bisheng/script/permission_migration.sh replay bash bisheng/script/permission_migration.sh replay 3模式映射脚本会把模式翻译成permission_rbac_to_rebac_migration.py的不同参数模式行为底层参数execute默认正常执行迁移--step Ndry_run仅预览迁移统计--dry-run --step Nonly_step只执行指定步骤--only-step Ndry_run_only_step只预览指定步骤--dry-run --only-step Nverify对比旧 RBAC 与新 ReBAC 权限结果--verify --step Nreplay从指定步骤强制重放忽略已完成状态并清空 checkpoint--force --step Nforce与replay行为一致为兼容保留--force --step N步骤映射8 步脚本第 2 个参数传入步骤号1Super Admin2User Group Membership3Role Access Expansion4Space/Channel Members5Resource Owners6Folder Hierarchy7Department Membership8Group Resources2.reconcile_permission_migration_db.py业务级数据库对账该脚本不重放迁移实现而是直接从业务表重建期望的 tuple 并与 OpenFGA datastore 的tuple表对比。涉及的业务表包括userrole、roleaccess、space_channel_member、knowledgefile、user_department、groupresource等。PYTHONPATH./ .venv/bin/python scripts/reconcile_permission_migration_db.py \ --tuple-db-url mysqlpymysql://user:passhost:3306/openfga \ --step 1 PYTHONPATH./ .venv/bin/python scripts/reconcile_permission_migration_db.py \ --tuple-db-url mysqlpymysql://user:passhost:3306/openfga \ --step 3 --apply参数--tuple-db-urlOpenFGA datastore 的 SQLAlchemy URL必填--store-id可选的 OpenFGA store id省略时自动解析--step只检查第 N 步18--applydiff 后通过 OpenFGA API 应用写入/删除--sample-limit打印多少条样例 tuple diff。3.reconcile_permission_migration_db.sh按步骤对账的 shell 包装bash scripts/reconcile_permission_migration_db.sh check 1 mysqlpymysql://user:passhost:3306/openfga bash scripts/reconcile_permission_migration_db.sh apply 3 mysqlpymysql://user:passhost:3306/openfga参数arg1 为check或applyarg2 为步骤号18arg3 为 OpenFGA tuple DB URL。第 3 个参数可省略若以下环境变量之一已设置OPENFGA_TUPLE_DB_URLOPENFGA_DATASTORE_URLOPENFGA_DATASTORE_URI五、LinsightF035升级脚本F035 是灵思任务模式deepagents功能上线的大版本其升级清单共 4 步步骤 2/3 在服务启动时自动回填步骤 4SOP→Skill 数据迁移由于要写对象存储、较重必须手工执行。完整升级清单见 docs/architecture/08-deployment.md 的升级 checklist。1.migrate_sop_to_skill.py/.shSOP → 技能迁移F035 第 4 步手工必跑升级必做v2.6 之前 → v2.6F035 4 步中的第 4 步——手工执行。必须在alembic upgrade head之后运行。与 F035 菜单/模型回填第 2/3 步启动自动执行不同本次 SOP→Skill 数据迁移不会自动运行——它要写对象存储、较重保持为手工运维脚本。一次性迁移把遗留的linsight_sop行转换为租户自定义技能linsight_skill元数据行 SKILLS_ROOT/data/skills/{tenant_id}/name/SKILL.md技能包。细节见 migrate_sop_to_skill.py 的 docstring 与实现display_name保留原始中文SOP 名截断到 255 字符同租户重名追加2/3后缀name技能 ID是 SOP 名的 pypinyin slug如标书撰写流程→biao-shu-zhuan-xie-liu-cheng空/纯符号名回退为sop-{id}同租户重名追加-2/-3后缀保证 64 字符上限见_dedupe_name实现description使用 SOP 自带描述截断到 1024 字符SOP 无描述时用 SOP 名兜底不调用 LLM——技能描述是必填的linsight_skill.description非空且SkillService拒绝空描述绝不能留空内容行连名称都没有时使用_FALLBACK_DESCRIPTION 历史 SOP#{sop_id}迁移生成的技能。frontmatter 携带metadata.display-name与metadata.sop-id——sop-id使重跑幂等已迁移的 SOP 重跑会覆盖自己的技能包而不是再分配一个带后缀的新名字输出stdout JSON 文件的迁移摘要运维产物产品内没有迁移报告失败/跳过项需人工处理在管理页修复重建或拆分超限 SOP 后重新上传遗留linsight_sop表保持不动归档设计 §8.6。# 从 src/backend/ 运行默认 dry-run bash scripts/migrate_sop_to_skill.sh # dry-run, all tenants bash scripts/migrate_sop_to_skill.sh apply # persist bash scripts/migrate_sop_to_skill.sh --tenant-id 2 apply # single tenant参数--apply持久化、--tenant-id id、--report-file path默认./migrate_sop_to_skill_report.json。2.backfill_linsight_task_mode_web_menu.py任务模式菜单权限回填F035 第 3 步启动自动F035 第 3 步——启动自动。服务启动时自动运行main.lifespan幂等失败不阻塞启动共享逻辑在bisheng/permission/domain/linsight_task_mode_menu_backfill.py。CLI 仅用于手工重跑或 dry-run 预览。功能给所有已拥有home菜单权限的角色授予WEB_MENU的linsight_task_mode权限。F035 把任务模式/linsight从共享的home菜单权限中拆出为独立子开关不做这次回填升级后的部署会让既有角色丢失任务模式访问权限路由守卫现在检查linsight_task_mode。幂等可重跑默认 dry-run。# 从 src/backend/ 运行 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_linsight_task_mode_web_menu.py # dry-run configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_linsight_task_mode_web_menu.py --apply # write3.migrate_linsight_task_model_to_default.py任务模型配置改写F035 第 2 步启动自动F035 第 2 步——启动自动。同上启动时自动运行main.lifespan幂等失败不阻塞启动共享逻辑在bisheng/llm/domain/services/linsight_default_model_backfill.py。F035 Track Edeepagents改写每个租户在tenant_system_model_config中的linsight_llm配置行——删除遗留的task_model/linsight_executor_mode键设置新的单一linsight_default_model_id若旧task_model.id仍在该行的models列表中就保留它否则回退到第一个 model idmodels为空则置空。JSON 用 Python 解析不用JSON_EXTRACT以保证 DM8/MySQL 兼容。幂等无task_model的行跳过可重跑默认 dry-run。# 从 src/backend/ 运行 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/migrate_linsight_task_model_to_default.py # dry-run configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/migrate_linsight_task_model_to_default.py --apply # write4.seed_overflow_skill.py溢出压测技能Dev/QA 专用非升级项Dev/QA fixture——不属于任何升级清单。种入一个溢出 QA技能其字段被推到极限用于人工目检技能详情抽屉SkillDetailSheet.tsx2026-06-16 溢出加固Track I。幂等重跑替换同一技能--remove删除。插入技能默认目标租户 1display_name255 字符、name64 字符、description1024 字符无空格、SKILL.md 正文携带 400 字符无断点 token、以及一个长名 bundle 资产——覆盖全部四个溢出点标题 / ID chip / 描述 / 预览加文件树。人工验收清单见 features/v2.6.0/035-linsight-task-mode/tasks.md 的 TI-1。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/seed_overflow_skill.py # dry-run configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/seed_overflow_skill.py --apply # create configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/seed_overflow_skill.py --remove # clean up六、租户 / 数据修复脚本1.backfill_message_citation_relations.py引用关系回填把历史message_citation.message_id回填到新的message_citation_relation关联表使同一个全局citation_id可被多条工作流输出消息复用。默认 dry-run、分批执行且幂等必须在升级后的服务已创建message_citation_relation表之后运行。可选--recover-markers会额外扫描消息正文中的引用标记恢复旧版本中消息已提交、随后引用唯一键冲突留下的关联。恢复时校验chat_id/flow_id找不到引用实体或作用域不匹配的标记只统计、不写入。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_message_citation_relations.py configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_message_citation_relations.py --recover-markers --apply # 或用 shell 包装自动探测解释器 / PYTHONPATH / config bash scripts/backfill_message_citation_relations.sh bash scripts/backfill_message_citation_relations.sh --recover-markers apply2.dedupe_gpts_tools.py预置工具去重清理同一租户下(tool_key, tenant_id)重复的预置工具/工具类型行。根因历史上复制内置工具到子租户未显式带tenant_id在 root 上下文下被server_default1盖成 root加上t_gpts_tools.tool_key当时没有唯一约束导致 root 下同一tool_key堆了多份如web_search×3。危害有二get_tool_by_tool_key().first()可能解析到非预期的那条工作流读到旧配置且会阻止后续添加UNIQUE(tool_key, tenant_id)约束。行为每组保留最小 id 为 canonical重定向assistantlink.tool_id、t_gpts_tools.type到 canonical硬删 stray 行。非预置自定义 API/MCP重复只报告不删除。工作台配置 JSON / OpenFGA 中对 stray id 的引用也只报告需人工跟进。⚠️--apply前先备份数据库。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/dedupe_gpts_tools.py # dry-run默认不写库 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/dedupe_gpts_tools.py --apply # 执行清理硬删 重定向引用apply 干净后再手动加约束ALTER TABLE t_gpts_tools ADD CONSTRAINT uk_gpts_tools_key_tenant UNIQUE (tool_key, tenant_id);3.backfill_knowledge_space_user_pin.py知识空间置顶解耦回填F037知识空间置顶从space_channel_member.is_pinned解耦到独立的knowledge_space_user_pin表置顶是纯个人偏好不再寄生在成员关系上。本脚本把历史置顶迁移到新表让升级后用户保留已置顶的空间。来源行space_channel_member中business_typespace且is_pinned为真且statusACTIVE每条转成knowledge_space_user_pin(user_id, space_idbusiness_id)。幂等已存在的(user_id, space_id)跳过可重复运行。前置先alembic upgrade head建好knowledge_space_user_pin表迁移f044_knowledge_space_user_pin。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_knowledge_space_user_pin.py # dry-run默认不写库 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_knowledge_space_user_pin.py --apply # 写入 # 或用 shell 包装 bash scripts/backfill_knowledge_space_user_pin.sh # dry-run bash scripts/backfill_knowledge_space_user_pin.sh apply # 写入4.backfill_departments_under_single_root.py部门单根收编把所有误挂为根的部门收编到默认组织根部门BSroot下保证全平台只有一个根部门。背景历史上 SSO 网关同步的顶层部门parent_external_id为空被挂为parent_idNone变成与默认组织平级的兄弟根导致出现多个根、且其path不以默认组织根 path 为前缀按path LIKE {root_path}%圈定租户成员时被漏算。同步逻辑已修复顶层部门改挂默认组织根下但增量推送未重推的存量部门需本脚本一次性收编。做什么默认租户下、除默认组织根外的所有 active 根部门parent_id IS NULL设parent_id默认组织根.id并级联重写整棵子树path。不区分 source不触碰挂载状态。幂等收编后parent_id不再为空重复运行被自然跳过。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_departments_under_single_root.py # dry-run默认不写库 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_departments_under_single_root.py --apply # 写入 # 或用 shell 包装 bash scripts/backfill_departments_under_single_root.sh # dry-run bash scripts/backfill_departments_under_single_root.sh apply # 写入5.backfill_user_tenant_associations.py用户默认租户归属回填把缺失/未激活的默认租户归属回填到user_tenant表。这段逻辑原先挂在服务启动流程init_default_data()的_init_default_tenant里每次进程启动都会全表扫描users/user_tenant一次反连接 一次把全部is_active1行读进内存在大用户量部署下属于把数据维护塞进了热路径。已从启动流剥离——启动只保证默认租户id1存在。运行期不依赖这张回填表UserPayload租户解析在用户无user_tenant行时回退到DEFAULT_TENANT_ID多租户登录还会惰性补挂故缺行不会阻塞登录/查询本回填是纯数据一致性维护按需运行一次即可。做什么两步与原启动逻辑等价、幂等① 对没有任何user_tenant行的用户插入默认租户行(tenant_id1, is_default1, is_active1, statusactive)② 对tenant_id1 / is_default1 / statusactive / is_active IS NULL且该用户当前无任何is_active1行的孤儿默认行置is_active1每用户只激活一条。只新增/激活不删除、不 demote。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_user_tenant_associations.py # dry-run默认不写库 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_user_tenant_associations.py --apply # 写入 # 或用 shell 包装 bash scripts/backfill_user_tenant_associations.sh # dry-run bash scripts/backfill_user_tenant_associations.sh apply # 写入6.backfill_department_parent_tuples.py部门父边 FGA 回填把 DB 部门树的父子关系回填成 OpenFGA 的department#parent继承边additive只加不删幂等。背景写department:{parent}#parentdepartment:{child}边的只有 F002 手动建/移部门SSO 同步及早期 f006 迁移进来的部门在 FGA 里没有这条边导致部门 admin 的 FGA 继承对其失效。SSO 同步链路已修复为实时维护 parent 边本脚本按 DB 当前树形一次性补齐存量部门的边。遍历所有statusactive且parent_id非空的部门全租户、全来源每个发一条write department:{parent_id}#parent department:{id}。batch_write_tuples对重复写幂等可反复跑。运行顺序在backfill_departments_under_single_root.py定型 parent_id之后运行会一并补上被收编部门的 root→顶层 边。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_department_parent_tuples.py # dry-run默认 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_department_parent_tuples.py --apply # 写入 # 或用 shell 包装 bash scripts/backfill_department_parent_tuples.sh # dry-run bash scripts/backfill_department_parent_tuples.sh apply # 写入七、压测数据脚本seed_load_test_org.py压测数据脚本批量生成部门树 用户灌入数据库用于大用户量下的体验/性能测试尤其 ReBAC 读路径。在平台默认根部门Tenant.root_dept_id下按--fanout广度优先生成--departments个部门自动维护物化path与department#parentFGA 边再生成--users个本地用户轮询分配主部门is_primary1可选--secondary-ratio挂附属部门每人写 user 默认角色 user_department user_tenant 及department#memberFGA 边。所有数据打source--source默认loadtest标签 external_idloadtest_dept_*/loadtest_user_*因此幂等且可用--purge一键清理。统一密码Test1234ab。干跑是默认行为--apply才写库/写 FGA/删数据。默认写 OpenFGA--no-fga只灌库。--with-role-fga才逐用户同步默认角色到 FGA慢。configconfig.yaml PYTHONPATH./ python scripts/seed_load_test_org.py --departments 200 --users 50000 --fanout 8 # dry-run默认 configconfig.yaml PYTHONPATH./ python scripts/seed_load_test_org.py --departments 200 --users 50000 --fanout 8 --apply # 写入 DB FGA configconfig.yaml PYTHONPATH./ python scripts/seed_load_test_org.py --departments 200 --users 50000 --apply --no-fga # 只灌库 configconfig.yaml PYTHONPATH./ python scripts/seed_load_test_org.py --purge --apply # 清理压测数据 # 或用 shell 包装自动探测解释器 / PYTHONPATH / config bash scripts/seed_load_test_org.sh --departments 200 --users 50000 --apply八、运维执行安全最佳实践综合以上全部脚本提炼出 BISHENG 运维脚本的统一纪律默认 dry-run--apply才写所有会改动数据的脚本都以 dry-run 为默认行为如backfill_relation_model_move_permissions.py、dedupe_gpts_tools.py、backfill_knowledge_space_user_pin.py、backfill_departments_under_single_root.py、backfill_user_tenant_associations.py、backfill_department_parent_tuples.py、seed_load_test_org.py先看输出再确认写前备份涉及硬删/重定向引用的脚本如dedupe_gpts_tools.py要求--apply前先备份数据库幂等设计脚本普遍通过业务键如sop-id、(user_id, space_id)、(tool_key, tenant_id)、parent_id是否为空天然跳过已处理数据可反复重跑顺序依赖先定型数据再补派生数据典型链路为backfill_departments_under_single_root.py先定型 parent_id→backfill_department_parent_tuples.py再补 FGA 边区分自动与手工部分回填F035 第 2/3 步、F034 move 权限已在 main.py 的 lifespan 中自动执行CLI 仅用于手工重跑或预览而 SOP→Skill 迁移写对象存储与 F006 权限迁移必须按 docs/architecture/08-deployment.md 升级 checklist 手工执行数据一致性 vs 热路径如backfill_user_tenant_associations.py所示BISHENG 已把重扫描逻辑从启动热路径剥离为按需脚本运行期通过回退与惰性补挂保证功能不依赖回填完成。掌握这些约定后你可以在升级窗口内安全、有序地完成 BISHENG 的权限迁移、数据修复与压测准备并随时用 dry-run 输出作为审计依据。【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 BISHENG 后端运维脚本实战指南：数据导出、权限迁移回填与租户数据修复全解析
BISHENG 后端运维脚本实战指南数据导出、权限迁移回填与租户数据修复全解析【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng导读本文以 BISHENG 开源仓库中 scripts 目录说明文档 为骨架系统梳理后端所有手工维护与迁移脚本的用途、命令、参数与底层实现原理。这些脚本覆盖四大类场景日常模式对话导出、RBAC→ReBAC 权限体系迁移与对账、LinsightF035升级数据迁移、以及多租户/知识空间/部门树的历史数据修复与压测数据灌入。读完本文你将掌握在src/backend目录下安全运行这些一次性脚本的正确姿势——包括默认 dry-run 的安全约定、--apply的写入开关、幂等设计与脚本间的顺序依赖并能从源码层面理解main.py启动期自动回填与手工脚本的分工边界。一、脚本目录定位与通用运行约定src/backend/scripts/存放的是手工维护与迁移脚本manual maintenance and migration scripts与随服务启动自动执行的初始化逻辑互补。运行这些脚本前请先掌握三条通用约定运行位置绝大多数 Python 脚本要求从src/backend/目录下执行并通过PYTHONPATH./让解释器能导入bisheng包解释器使用项目虚拟环境.venv/bin/pythonscripts/seed_load_test_org.py的示例中也有直接用python的写法取决于你的环境配置加载多数脚本通过config环境变量指定配置文件缺省时回落为config.yaml例如configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/xxx.py。目录内还提供了一批.sh包装脚本如 migrate_workstation_models_to_workbench.sh、backfill_knowledge_space_user_pin.sh 等它们会自动探测解释器 /PYTHONPATH/ config把--apply位置参数透传给 Python 脚本便于手工运维直接调用。说明README 中记载的export_daily_chat_messages.py与reconcile_permission_migration_db.py/.sh未出现在当前仓库快照的 scripts 目录列表中命令与参数契约以 README 为准实际使用时请以部署版本目录内容为准。二、导出类脚本日常模式对话导出export_daily_chat_messages.py该脚本导出**日常模式flow_type 15**的对话内容默认导出最近 30 天的消息并按会话聚合为 JSON。核心用法PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py --days 7 PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py --format csv PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py --tenant-id 3 PYTHONPATH./ .venv/bin/python scripts/export_daily_chat_messages.py --full-session参数说明参数默认值作用--config环境变量config否则config.yaml指定配置文件--days30导出最近多少天的消息--formatjson输出格式json或csv--tenant-id无仅导出指定租户--user-id无仅导出指定用户--chat-id无仅导出指定会话--include-deleted关包含已删除会话--full-session关只要会话在时间窗口内活跃就导出该会话的全部消息而非仅窗口内消息日常模式在 BISHENG 中对应工作站对话flow_type 15导出产物适合作为合规留存、数据迁移或分析的输入。三、权限模型迁移与回填脚本权限类脚本解决两类问题模型配置迁移把旧位置的配置搬到新位置与权限数据回填为历史存量数据补齐缺失的授权信息。这类脚本的共同特点是默认 dry-run、--apply才写库、幂等可重跑。1.migrate_workstation_models_to_workbench.py工作台模型配置迁移一次性迁移脚本把旧的全局每日工作台模型列表从config.key workstation行迁移到默认租户的tenant_system_model_config.key linsight_llm行。行为要点读取workstation.models来自config表只写默认租户tenant_id 1若 Root 已有linsight_llm行仅合并更新models字段若 Root 没有linsight_llm行则新建一行保留旧的workstation.models不动后续 UI 保存流程可自行清理/覆盖。PYTHONPATH./ .venv/bin/python scripts/migrate_workstation_models_to_workbench.py PYTHONPATH./ .venv/bin/python scripts/migrate_workstation_models_to_workbench.py --apply bash scripts/migrate_workstation_models_to_workbench.sh bash scripts/migrate_workstation_models_to_workbench.sh apply2.migrate_channel_permissions_for_relation_models.py自定义资源权限模板回填把 channel 模块的默认权限回填进 channel 模块出现之前创建的旧自定义关系模型资源权限模板。注意它的适用对象是is_system false的自定义模型读取全局config.key permission_relation_models_v1JSON 列表对每个没有任何 channel 权限 id 的自定义模型按其继承档位owner/manager/editor/viewer追加 channel 默认权限来源为channel_permission_template.default_permission_ids_for_relation跳过系统模型它们在运行时从模板动态计算 channel 默认值跳过已含任一 channel 权限 id 的自定义模型绝不覆盖管理员显式做过的 channel 定制保留所有非 channel 权限。PYTHONPATH./ .venv/bin/python scripts/migrate_channel_permissions_for_relation_models.py PYTHONPATH./ .venv/bin/python scripts/migrate_channel_permissions_for_relation_models.py --apply bash scripts/migrate_channel_permissions_for_relation_models.sh bash scripts/migrate_channel_permissions_for_relation_models.sh apply3.backfill_relation_model_move_permissions.py冻结系统档位的 F034 移动权限回填这是大部分情况下无需手动执行的脚本相同的幂等回填已在每次后端启动时自动运行接线在 main.py 的 lifespan 中第 61-64 行调用了backfill_relation_model_move_permissions正常升级 重启即可自愈。独立脚本的存在价值仅在于不重启修复环境或先预览改动。要理解它需要先理解permission_relation_models_v1配置行中每个系统档位的permissions_explicit开关见 backfill_relation_model_move_permissions.py 的 docstringpermissions_explicitFalse默认 seed 值勾选状态读取时按代码模板动态计算调用default_permission_ids_for_relation(relation)现算新增权限如本次的move_file/move_folder会自动出现无需回填permissions_explicitTrue勾选状态是保存那一刻冻结的快照update_relation_model保存 permissions 时会把开关翻成 True。模板后来新增的权限不会自动补进快照——这正是所有者/可管理档位缺移动权限的根因。脚本行为对每个系统is_system true且已冻结permissions_explicit true的档位计算目标权限集{move_file, move_folder} ∩ default_permission_ids_for_relation(relation)所有者 / 可管理 / 可编辑can_edit 及以上→ 两个都补可查看viewer→ 交集为空不补只把缺失的这两个 id并入permissions[]不动其它任何已勾选项跳过动态档位permissions_explicit false和自定义is_system false档位幂等补齐后重跑无变化。在 relation_model_backfill.py 中可以看到核心逻辑apply_move_permission_backfill的实现NEW_PERMISSION_IDS default_permission_ids_for_relation(relation or )计算交集且仅当m.get(is_system) and m.get(permissions_explicit) is True时才处理。脚本主流程L76-L110直连 DB 读取Config行、JSON 解析、dry-run 打印、--apply时写回整行配置并提交。安全保证源码 docstring 明确声明只新增move_file/move_folder绝不删除或重置已有勾选只动 system explicitTrue 的档位单次写整行配置失败回滚该 config key 不走 Redis 缓存aget_config_by_key直连 DB运行中的进程下次读取即生效无需重启。# 从 src/backend/ 运行 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_relation_model_move_permissions.py configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_relation_model_move_permissions.py --apply4.backfill_channel_member_rebac_grants.py修复缺失的频道成员 ReBAC 授权修复在 commitc530bf375之前就已激活、因此从未写入 ReBAC grant的频道订阅者。由于成员管理/授权列表是从 OpenFGA tuple 渲染的这类成员在space_channel_member中处于激活态却在授权列表中不可见。行为扫描频道全部或--channel-id指定单个筛选status ACTIVE、非CREATOR、直接grant_subject_type为NULL/self成员对每个在 FGA 上没有既有 grant 的成员通过ChannelService.sync_direct_channel_user_permissions写入 viewer/manager grant 与关系模型绑定幂等跳过创建者owner 由OwnerService管理、PENDING/REJECTED成员、组织授权成员、以及 FGA 中已存在的成员。PYTHONPATH./ .venv/bin/python scripts/backfill_channel_member_rebac_grants.py PYTHONPATH./ .venv/bin/python scripts/backfill_channel_member_rebac_grants.py --apply PYTHONPATH./ .venv/bin/python scripts/backfill_channel_member_rebac_grants.py --channel-id id --apply bash scripts/backfill_channel_member_rebac_grants.sh bash scripts/backfill_channel_member_rebac_grants.sh apply bash scripts/backfill_channel_member_rebac_grants.sh --channel-id id apply5.clean_department_space_user_group_grants.py清理部门空间的用户组授权F033 的一次性清理。部门知识空间不再允许用户组授权维度API 拒绝新增 user_group grant客户端也隐藏了对应 Tab本脚本移除部门空间上历史遗留的 user_group grant——撤销 OpenFGA tuple 并删除关系模型绑定运行时代码不再为这些 grant 保留兼容路径。行为扫描每个部门知识空间DepartmentKnowledgeSpaceDao.aget_all将每个user_groupgrant 报告为(space_id, group_id, relation, affected_users)--apply时通过PermissionService.authorize撤销 grant 并移除绑定只处理部门空间的user_groupgrant——绝不触碰普通空间、也绝不处理 user/department grant。⚠️--apply不可逆会撤销组成员访问权限务必先 review dry-run 输出。export configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/clean_department_space_user_group_grants.py # dry-run PYTHONPATH./ .venv/bin/python scripts/clean_department_space_user_group_grants.py --apply # execute四、F006 RBAC → ReBAC 权限迁移与对账1.permission_migration.sh历史权限迁移手工执行器F006 历史权限迁移RBAC → ReBAC的手工运行入口。用法与模式详见 permission_migration.sh 源码实现bash bisheng/script/permission_migration.sh bash bisheng/script/permission_migration.sh dry_run bash bisheng/script/permission_migration.sh verify bash bisheng/script/permission_migration.sh replay bash bisheng/script/permission_migration.sh replay 3模式映射脚本会把模式翻译成permission_rbac_to_rebac_migration.py的不同参数模式行为底层参数execute默认正常执行迁移--step Ndry_run仅预览迁移统计--dry-run --step Nonly_step只执行指定步骤--only-step Ndry_run_only_step只预览指定步骤--dry-run --only-step Nverify对比旧 RBAC 与新 ReBAC 权限结果--verify --step Nreplay从指定步骤强制重放忽略已完成状态并清空 checkpoint--force --step Nforce与replay行为一致为兼容保留--force --step N步骤映射8 步脚本第 2 个参数传入步骤号1Super Admin2User Group Membership3Role Access Expansion4Space/Channel Members5Resource Owners6Folder Hierarchy7Department Membership8Group Resources2.reconcile_permission_migration_db.py业务级数据库对账该脚本不重放迁移实现而是直接从业务表重建期望的 tuple 并与 OpenFGA datastore 的tuple表对比。涉及的业务表包括userrole、roleaccess、space_channel_member、knowledgefile、user_department、groupresource等。PYTHONPATH./ .venv/bin/python scripts/reconcile_permission_migration_db.py \ --tuple-db-url mysqlpymysql://user:passhost:3306/openfga \ --step 1 PYTHONPATH./ .venv/bin/python scripts/reconcile_permission_migration_db.py \ --tuple-db-url mysqlpymysql://user:passhost:3306/openfga \ --step 3 --apply参数--tuple-db-urlOpenFGA datastore 的 SQLAlchemy URL必填--store-id可选的 OpenFGA store id省略时自动解析--step只检查第 N 步18--applydiff 后通过 OpenFGA API 应用写入/删除--sample-limit打印多少条样例 tuple diff。3.reconcile_permission_migration_db.sh按步骤对账的 shell 包装bash scripts/reconcile_permission_migration_db.sh check 1 mysqlpymysql://user:passhost:3306/openfga bash scripts/reconcile_permission_migration_db.sh apply 3 mysqlpymysql://user:passhost:3306/openfga参数arg1 为check或applyarg2 为步骤号18arg3 为 OpenFGA tuple DB URL。第 3 个参数可省略若以下环境变量之一已设置OPENFGA_TUPLE_DB_URLOPENFGA_DATASTORE_URLOPENFGA_DATASTORE_URI五、LinsightF035升级脚本F035 是灵思任务模式deepagents功能上线的大版本其升级清单共 4 步步骤 2/3 在服务启动时自动回填步骤 4SOP→Skill 数据迁移由于要写对象存储、较重必须手工执行。完整升级清单见 docs/architecture/08-deployment.md 的升级 checklist。1.migrate_sop_to_skill.py/.shSOP → 技能迁移F035 第 4 步手工必跑升级必做v2.6 之前 → v2.6F035 4 步中的第 4 步——手工执行。必须在alembic upgrade head之后运行。与 F035 菜单/模型回填第 2/3 步启动自动执行不同本次 SOP→Skill 数据迁移不会自动运行——它要写对象存储、较重保持为手工运维脚本。一次性迁移把遗留的linsight_sop行转换为租户自定义技能linsight_skill元数据行 SKILLS_ROOT/data/skills/{tenant_id}/name/SKILL.md技能包。细节见 migrate_sop_to_skill.py 的 docstring 与实现display_name保留原始中文SOP 名截断到 255 字符同租户重名追加2/3后缀name技能 ID是 SOP 名的 pypinyin slug如标书撰写流程→biao-shu-zhuan-xie-liu-cheng空/纯符号名回退为sop-{id}同租户重名追加-2/-3后缀保证 64 字符上限见_dedupe_name实现description使用 SOP 自带描述截断到 1024 字符SOP 无描述时用 SOP 名兜底不调用 LLM——技能描述是必填的linsight_skill.description非空且SkillService拒绝空描述绝不能留空内容行连名称都没有时使用_FALLBACK_DESCRIPTION 历史 SOP#{sop_id}迁移生成的技能。frontmatter 携带metadata.display-name与metadata.sop-id——sop-id使重跑幂等已迁移的 SOP 重跑会覆盖自己的技能包而不是再分配一个带后缀的新名字输出stdout JSON 文件的迁移摘要运维产物产品内没有迁移报告失败/跳过项需人工处理在管理页修复重建或拆分超限 SOP 后重新上传遗留linsight_sop表保持不动归档设计 §8.6。# 从 src/backend/ 运行默认 dry-run bash scripts/migrate_sop_to_skill.sh # dry-run, all tenants bash scripts/migrate_sop_to_skill.sh apply # persist bash scripts/migrate_sop_to_skill.sh --tenant-id 2 apply # single tenant参数--apply持久化、--tenant-id id、--report-file path默认./migrate_sop_to_skill_report.json。2.backfill_linsight_task_mode_web_menu.py任务模式菜单权限回填F035 第 3 步启动自动F035 第 3 步——启动自动。服务启动时自动运行main.lifespan幂等失败不阻塞启动共享逻辑在bisheng/permission/domain/linsight_task_mode_menu_backfill.py。CLI 仅用于手工重跑或 dry-run 预览。功能给所有已拥有home菜单权限的角色授予WEB_MENU的linsight_task_mode权限。F035 把任务模式/linsight从共享的home菜单权限中拆出为独立子开关不做这次回填升级后的部署会让既有角色丢失任务模式访问权限路由守卫现在检查linsight_task_mode。幂等可重跑默认 dry-run。# 从 src/backend/ 运行 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_linsight_task_mode_web_menu.py # dry-run configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_linsight_task_mode_web_menu.py --apply # write3.migrate_linsight_task_model_to_default.py任务模型配置改写F035 第 2 步启动自动F035 第 2 步——启动自动。同上启动时自动运行main.lifespan幂等失败不阻塞启动共享逻辑在bisheng/llm/domain/services/linsight_default_model_backfill.py。F035 Track Edeepagents改写每个租户在tenant_system_model_config中的linsight_llm配置行——删除遗留的task_model/linsight_executor_mode键设置新的单一linsight_default_model_id若旧task_model.id仍在该行的models列表中就保留它否则回退到第一个 model idmodels为空则置空。JSON 用 Python 解析不用JSON_EXTRACT以保证 DM8/MySQL 兼容。幂等无task_model的行跳过可重跑默认 dry-run。# 从 src/backend/ 运行 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/migrate_linsight_task_model_to_default.py # dry-run configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/migrate_linsight_task_model_to_default.py --apply # write4.seed_overflow_skill.py溢出压测技能Dev/QA 专用非升级项Dev/QA fixture——不属于任何升级清单。种入一个溢出 QA技能其字段被推到极限用于人工目检技能详情抽屉SkillDetailSheet.tsx2026-06-16 溢出加固Track I。幂等重跑替换同一技能--remove删除。插入技能默认目标租户 1display_name255 字符、name64 字符、description1024 字符无空格、SKILL.md 正文携带 400 字符无断点 token、以及一个长名 bundle 资产——覆盖全部四个溢出点标题 / ID chip / 描述 / 预览加文件树。人工验收清单见 features/v2.6.0/035-linsight-task-mode/tasks.md 的 TI-1。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/seed_overflow_skill.py # dry-run configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/seed_overflow_skill.py --apply # create configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/seed_overflow_skill.py --remove # clean up六、租户 / 数据修复脚本1.backfill_message_citation_relations.py引用关系回填把历史message_citation.message_id回填到新的message_citation_relation关联表使同一个全局citation_id可被多条工作流输出消息复用。默认 dry-run、分批执行且幂等必须在升级后的服务已创建message_citation_relation表之后运行。可选--recover-markers会额外扫描消息正文中的引用标记恢复旧版本中消息已提交、随后引用唯一键冲突留下的关联。恢复时校验chat_id/flow_id找不到引用实体或作用域不匹配的标记只统计、不写入。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_message_citation_relations.py configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_message_citation_relations.py --recover-markers --apply # 或用 shell 包装自动探测解释器 / PYTHONPATH / config bash scripts/backfill_message_citation_relations.sh bash scripts/backfill_message_citation_relations.sh --recover-markers apply2.dedupe_gpts_tools.py预置工具去重清理同一租户下(tool_key, tenant_id)重复的预置工具/工具类型行。根因历史上复制内置工具到子租户未显式带tenant_id在 root 上下文下被server_default1盖成 root加上t_gpts_tools.tool_key当时没有唯一约束导致 root 下同一tool_key堆了多份如web_search×3。危害有二get_tool_by_tool_key().first()可能解析到非预期的那条工作流读到旧配置且会阻止后续添加UNIQUE(tool_key, tenant_id)约束。行为每组保留最小 id 为 canonical重定向assistantlink.tool_id、t_gpts_tools.type到 canonical硬删 stray 行。非预置自定义 API/MCP重复只报告不删除。工作台配置 JSON / OpenFGA 中对 stray id 的引用也只报告需人工跟进。⚠️--apply前先备份数据库。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/dedupe_gpts_tools.py # dry-run默认不写库 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/dedupe_gpts_tools.py --apply # 执行清理硬删 重定向引用apply 干净后再手动加约束ALTER TABLE t_gpts_tools ADD CONSTRAINT uk_gpts_tools_key_tenant UNIQUE (tool_key, tenant_id);3.backfill_knowledge_space_user_pin.py知识空间置顶解耦回填F037知识空间置顶从space_channel_member.is_pinned解耦到独立的knowledge_space_user_pin表置顶是纯个人偏好不再寄生在成员关系上。本脚本把历史置顶迁移到新表让升级后用户保留已置顶的空间。来源行space_channel_member中business_typespace且is_pinned为真且statusACTIVE每条转成knowledge_space_user_pin(user_id, space_idbusiness_id)。幂等已存在的(user_id, space_id)跳过可重复运行。前置先alembic upgrade head建好knowledge_space_user_pin表迁移f044_knowledge_space_user_pin。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_knowledge_space_user_pin.py # dry-run默认不写库 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_knowledge_space_user_pin.py --apply # 写入 # 或用 shell 包装 bash scripts/backfill_knowledge_space_user_pin.sh # dry-run bash scripts/backfill_knowledge_space_user_pin.sh apply # 写入4.backfill_departments_under_single_root.py部门单根收编把所有误挂为根的部门收编到默认组织根部门BSroot下保证全平台只有一个根部门。背景历史上 SSO 网关同步的顶层部门parent_external_id为空被挂为parent_idNone变成与默认组织平级的兄弟根导致出现多个根、且其path不以默认组织根 path 为前缀按path LIKE {root_path}%圈定租户成员时被漏算。同步逻辑已修复顶层部门改挂默认组织根下但增量推送未重推的存量部门需本脚本一次性收编。做什么默认租户下、除默认组织根外的所有 active 根部门parent_id IS NULL设parent_id默认组织根.id并级联重写整棵子树path。不区分 source不触碰挂载状态。幂等收编后parent_id不再为空重复运行被自然跳过。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_departments_under_single_root.py # dry-run默认不写库 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_departments_under_single_root.py --apply # 写入 # 或用 shell 包装 bash scripts/backfill_departments_under_single_root.sh # dry-run bash scripts/backfill_departments_under_single_root.sh apply # 写入5.backfill_user_tenant_associations.py用户默认租户归属回填把缺失/未激活的默认租户归属回填到user_tenant表。这段逻辑原先挂在服务启动流程init_default_data()的_init_default_tenant里每次进程启动都会全表扫描users/user_tenant一次反连接 一次把全部is_active1行读进内存在大用户量部署下属于把数据维护塞进了热路径。已从启动流剥离——启动只保证默认租户id1存在。运行期不依赖这张回填表UserPayload租户解析在用户无user_tenant行时回退到DEFAULT_TENANT_ID多租户登录还会惰性补挂故缺行不会阻塞登录/查询本回填是纯数据一致性维护按需运行一次即可。做什么两步与原启动逻辑等价、幂等① 对没有任何user_tenant行的用户插入默认租户行(tenant_id1, is_default1, is_active1, statusactive)② 对tenant_id1 / is_default1 / statusactive / is_active IS NULL且该用户当前无任何is_active1行的孤儿默认行置is_active1每用户只激活一条。只新增/激活不删除、不 demote。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_user_tenant_associations.py # dry-run默认不写库 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_user_tenant_associations.py --apply # 写入 # 或用 shell 包装 bash scripts/backfill_user_tenant_associations.sh # dry-run bash scripts/backfill_user_tenant_associations.sh apply # 写入6.backfill_department_parent_tuples.py部门父边 FGA 回填把 DB 部门树的父子关系回填成 OpenFGA 的department#parent继承边additive只加不删幂等。背景写department:{parent}#parentdepartment:{child}边的只有 F002 手动建/移部门SSO 同步及早期 f006 迁移进来的部门在 FGA 里没有这条边导致部门 admin 的 FGA 继承对其失效。SSO 同步链路已修复为实时维护 parent 边本脚本按 DB 当前树形一次性补齐存量部门的边。遍历所有statusactive且parent_id非空的部门全租户、全来源每个发一条write department:{parent_id}#parent department:{id}。batch_write_tuples对重复写幂等可反复跑。运行顺序在backfill_departments_under_single_root.py定型 parent_id之后运行会一并补上被收编部门的 root→顶层 边。configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_department_parent_tuples.py # dry-run默认 configconfig.yaml PYTHONPATH./ .venv/bin/python scripts/backfill_department_parent_tuples.py --apply # 写入 # 或用 shell 包装 bash scripts/backfill_department_parent_tuples.sh # dry-run bash scripts/backfill_department_parent_tuples.sh apply # 写入七、压测数据脚本seed_load_test_org.py压测数据脚本批量生成部门树 用户灌入数据库用于大用户量下的体验/性能测试尤其 ReBAC 读路径。在平台默认根部门Tenant.root_dept_id下按--fanout广度优先生成--departments个部门自动维护物化path与department#parentFGA 边再生成--users个本地用户轮询分配主部门is_primary1可选--secondary-ratio挂附属部门每人写 user 默认角色 user_department user_tenant 及department#memberFGA 边。所有数据打source--source默认loadtest标签 external_idloadtest_dept_*/loadtest_user_*因此幂等且可用--purge一键清理。统一密码Test1234ab。干跑是默认行为--apply才写库/写 FGA/删数据。默认写 OpenFGA--no-fga只灌库。--with-role-fga才逐用户同步默认角色到 FGA慢。configconfig.yaml PYTHONPATH./ python scripts/seed_load_test_org.py --departments 200 --users 50000 --fanout 8 # dry-run默认 configconfig.yaml PYTHONPATH./ python scripts/seed_load_test_org.py --departments 200 --users 50000 --fanout 8 --apply # 写入 DB FGA configconfig.yaml PYTHONPATH./ python scripts/seed_load_test_org.py --departments 200 --users 50000 --apply --no-fga # 只灌库 configconfig.yaml PYTHONPATH./ python scripts/seed_load_test_org.py --purge --apply # 清理压测数据 # 或用 shell 包装自动探测解释器 / PYTHONPATH / config bash scripts/seed_load_test_org.sh --departments 200 --users 50000 --apply八、运维执行安全最佳实践综合以上全部脚本提炼出 BISHENG 运维脚本的统一纪律默认 dry-run--apply才写所有会改动数据的脚本都以 dry-run 为默认行为如backfill_relation_model_move_permissions.py、dedupe_gpts_tools.py、backfill_knowledge_space_user_pin.py、backfill_departments_under_single_root.py、backfill_user_tenant_associations.py、backfill_department_parent_tuples.py、seed_load_test_org.py先看输出再确认写前备份涉及硬删/重定向引用的脚本如dedupe_gpts_tools.py要求--apply前先备份数据库幂等设计脚本普遍通过业务键如sop-id、(user_id, space_id)、(tool_key, tenant_id)、parent_id是否为空天然跳过已处理数据可反复重跑顺序依赖先定型数据再补派生数据典型链路为backfill_departments_under_single_root.py先定型 parent_id→backfill_department_parent_tuples.py再补 FGA 边区分自动与手工部分回填F035 第 2/3 步、F034 move 权限已在 main.py 的 lifespan 中自动执行CLI 仅用于手工重跑或预览而 SOP→Skill 迁移写对象存储与 F006 权限迁移必须按 docs/architecture/08-deployment.md 升级 checklist 手工执行数据一致性 vs 热路径如backfill_user_tenant_associations.py所示BISHENG 已把重扫描逻辑从启动热路径剥离为按需脚本运行期通过回退与惰性补挂保证功能不依赖回填完成。掌握这些约定后你可以在升级窗口内安全、有序地完成 BISHENG 的权限迁移、数据修复与压测准备并随时用 dry-run 输出作为审计依据。【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考