LangBot/docs/multi-tenant/DATABASE_MIGRATION_GUIDE.md

LangBot 多租户数据库迁移指南

概述

LangBot 从单租户 OSS 架构迁移到多租户 SaaS 架构，需要执行 7 个数据库迁移（0009-0015）。

迁移序列

0009_workspace_tenancy_kernel → 创建 Workspace、成员、邀请表
0010_scope_tenant_resources → 所有业务表添加 workspace_uuid
0011_postgres_tenant_rls → PostgreSQL 行级安全策略
0012_plugin_installation_identity → 插件实例租户绑定
0013_tenant_pgvector → RAG 向量存储隔离
0014_cloud_directory_projection → Cloud 控制平面同步
0015_cloud_core_collaboration → 协作和权限功能

执行步骤

1. 备份（必须）

# SQLite
cp ~/.langbot/data/langbot.db ~/.langbot/data/langbot.db.backup-$(date +%Y%m%d)

# PostgreSQL  
pg_dump -U langbot_user -d langbot_db -F c -f langbot_backup_$(date +%Y%m%d).dump

2. 执行迁移

# 停止服务
sudo -S -p '' systemctl stop langbot

# 执行迁移
python -m langbot.pkg.persistence.migration upgrade head

# 验证
python -m langbot.pkg.persistence.migration current
# 预期: 0015_cloud_core_collaboration

# 启动服务
sudo -S -p '' systemctl start langbot

3. OSS 单租户自动迁移

迁移会自动：

• 创建默认 Workspace（名称："Default Workspace"）
• 第一个用户成为 Owner
• 所有现有资源绑定到该 Workspace

4. 验证检查

# 检查 Workspace
python << EOF
from langbot.pkg.persistence import manager
import sqlalchemy as sa

with manager.engine.connect() as conn:
    ws = conn.execute(sa.text("SELECT uuid, name FROM workspaces LIMIT 1")).first()
    print(f"Workspace: {ws[1]} ({ws[0]})")
    
    # 检查资源绑定
    bot_count = conn.execute(sa.text(
        f"SELECT COUNT(*) FROM bots WHERE workspace_uuid='{ws[0]}'"
    )).scalar()
    print(f"Bots: {bot_count}")
EOF

回滚方案

完全回滚（丢失多租户数据）

# 1. 停止服务
sudo -S -p '' systemctl stop langbot

# 2. 恢复备份
cp ~/.langbot/data/langbot.db.backup-YYYYMMDD ~/.langbot/data/langbot.db

# 3. 回退代码
git checkout v4.10.x
pip install -e .

# 4. 启动
sudo -S -p '' systemctl start langbot

降级迁移（保留数据但移除多租户）

# 警告：会移除 Workspace 表但保留资源
python -m langbot.pkg.persistence.migration downgrade 0008_mcp_resource_prefs

常见问题

Q: 迁移后无法登录

# 检查用户 UUID
python << EOF
from langbot.pkg.persistence import manager
import sqlalchemy as sa

with manager.engine.connect() as conn:
    users = conn.execute(sa.text("SELECT id, user, uuid, status FROM users")).all()
    for u in users:
        print(f"{u[1]}: UUID={u[2]}, Status={u[3]}")
EOF

Q: 资源看不见了

检查 Workspace 上下文：

# 前端请求需要带 X-Workspace-ID header
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Workspace-ID: $WORKSPACE_UUID" \
     http://localhost:5200/api/v1/platform/bots

Q: 迁移速度慢

# SQLite 优化
sqlite3 ~/.langbot/data/langbot.db << EOF
PRAGMA journal_mode=WAL;
PRAGMA synchronous=NORMAL;
VACUUM;
EOF

性能调优

PostgreSQL 索引

-- 迁移后创建
CREATE INDEX CONCURRENTLY idx_model_providers_workspace 
    ON model_providers(workspace_uuid);

CREATE INDEX CONCURRENTLY idx_bots_workspace 
    ON bots(workspace_uuid);

CREATE INDEX CONCURRENTLY idx_pipelines_workspace 
    ON pipelines(workspace_uuid);

预估时间

• SQLite < 100MB: 2-5 分钟
• SQLite 100MB-1GB: 5-15 分钟
• PostgreSQL: < 5 分钟（取决于数据量）

支持

问题反馈：https://github.com/langbot-app/LangBot/issues

版本: 1.0
最后更新: 2026-07-30