Files
Enterprise-Knowledge-Base/migrations/README.md
T

200 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 数据库迁移说明
## 📋 迁移文件列表
### MySQL
```
mysql/
├── 00-init-db.sql # ❗️初始化脚本(包含后期添加的字段)
├── 02-add-agent-config-if-missing.sql # ✅ 兼容性迁移(检查并添加缺失字段)
└── 03-cleanup-unreferenced-models.sql # 🧹 清理未引用模型(维护脚本)
```
### ParadeDB/PostgreSQL
```
paradedb/
├── 01-migrate-to-paradedb.sql # ❗️ParadeDB 初始化
├── 02-add-agent-config-if-missing.sql # ✅ 兼容性迁移(检查并添加缺失字段)
└── 03-cleanup-unreferenced-models.sql # 🧹 清理未引用模型(维护脚本)
```
## ⚠️ 重要说明
### 关于 `agent_config` 等字段
你可能会注意到 `agent_config`、`context_config`、`agent_steps` 这些字段**同时出现在**:
- ✅ 初始化脚本中(`00-init-db.sql`)
- ✅ 迁移脚本中(`02-add-agent-config-if-missing.sql`)
**这不是错误!** 这是为了兼容两种场景:
#### 场景1: 全新安装 🆕
运行 `00-init-db.sql` 时,会直接创建包含所有字段的表(包括 `agent_config`)。
当运行 `02-add-agent-config-if-missing.sql` 时,会检测到字段已存在,跳过添加。
#### 场景2: 旧版本升级 ⬆️
如果你的数据库是从旧版本(不包含 `agent_config` 的版本)升级:
- `00-init-db.sql` 早已运行过(但那时还没有 `agent_config` 字段)
- 运行 `02-add-agent-config-if-missing.sql` 时,会检测到字段不存在,然后添加
### 为什么会这样?
根据 `AGENT_CONFIG_TENANT_REFACTORING.md` 文档,`agent_config` 是后来添加的功能。理论上:
**❌ 不应该做的(但已经做了):**
```sql
-- 00-init-db.sql 被修改了,添加了后来才加的字段
CREATE TABLE tenants (
agent_config JSON DEFAULT NULL, -- 这个字段是后来加的!
...
);
```
**✅ 应该做的:**
```sql
-- 00-init-db.sql(保持不变)
CREATE TABLE tenants (
-- 没有 agent_config
...
);
-- 02-add-agent-config.sql(新文件)
ALTER TABLE tenants ADD COLUMN agent_config JSON DEFAULT NULL;
```
但由于初始化脚本已经被修改,我们创建了一个**智能的兼容性迁移脚本** `02-add-agent-config-if-missing.sql`,它:
- ✅ 检查字段是否存在
- ✅ 只在字段不存在时才添加
- ✅ 对新旧数据库都安全
## 🚀 使用方法
### 方法1: 全新部署
```bash
# 直接运行所有迁移
./scripts/migrate.sh up
# 结果:
# - 00-init-db.sql: 创建表(包含 agent_config)
# - 02-add-agent-config-if-missing.sql: 检测到字段已存在,跳过
```
### 方法2: 从旧版本升级
```bash
# 运行新的迁移
docker exec -i paradedb_container psql -U postgres -d WeKnora \
< migrations/paradedb/02-add-agent-config-if-missing.sql
# 结果:
# - 检测到 agent_config 不存在
# - 添加 agent_config、context_config、agent_steps 字段
# - 创建 GIN 索引提高查询性能
```
### 方法3: 验证字段是否存在
#### MySQL
```sql
SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_DEFAULT
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = 'WeKnora'
AND TABLE_NAME = 'tenants'
AND COLUMN_NAME = 'agent_config';
```
#### PostgreSQL
```sql
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'tenants'
AND column_name = 'agent_config';
```
## 📝 涉及的字段
以下字段是通过 `02-add-agent-config-if-missing.sql` 处理的:
### `tenants` 表
- `agent_config` (JSON/JSONB): 租户级别的 Agent 配置
### `sessions` 表
- `agent_config` (JSON/JSONB): 会话级别的 Agent 配置
- `context_config` (JSON/JSONB): LLM 上下文管理配置
### `messages` 表
- `agent_steps` (JSON/JSONB): Agent 执行步骤(推理过程和工具调用)
## 🎯 最佳实践建议
### 对于新字段的添加
如果你需要添加新字段,**不要修改 `00-init-db.sql`**!应该:
1. 创建新的迁移文件:`03-your-feature.sql`
2. 使用 `ALTER TABLE` 添加字段
3. 使用 `IF NOT EXISTS` 确保幂等性
示例:
```sql
-- 03-add-new-feature.sql
ALTER TABLE tenants
ADD COLUMN IF NOT EXISTS new_field VARCHAR(255) DEFAULT NULL;
```
### 对于现有字段的修改
```sql
-- 04-modify-field.sql
ALTER TABLE tenants
MODIFY COLUMN existing_field TEXT NULL;
```
## 📚 更多信息
详细的迁移指南请参考:[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)
## 🧹 维护脚本
### 03-cleanup-unreferenced-models.sql
**用途**: 清理数据库中未被任何知识库引用的模型
**清理条件**(必须同时满足):
- ❌ 未被 `knowledge_bases` 引用(embedding/summary/rerank/vlm 模型)
- ❌ 未被 `knowledges` 引用(embedding 模型)
- ❌ 非默认模型(`is_default = FALSE`)
- ❌ 非系统模型(`tenant_id != 0`)
- ❌ 未软删除(`deleted_at IS NULL`)
**使用步骤**:
1. 📊 运行 DRY RUN 查询查看将被删除的模型
2. 💾 备份数据库
3. 🔄 选择软删除(推荐)或硬删除
4. ✅ 验证结果
**详细说明**: 请查看 [CLEANUP_GUIDE.md](./CLEANUP_GUIDE.md)
**⚠️ 重要**:
- 软删除可以回滚,硬删除不可逆
- 建议先在测试环境验证
- 可设置定时任务自动清理
## 🔗 相关文档
- `AGENT_CONFIG_TENANT_REFACTORING.md` - Agent 配置重构说明
- `CONTEXT_MANAGER_IMPLEMENTATION.md` - 上下文管理器实现
- `MIGRATION_GUIDE.md` - 完整的迁移指南
- `CLEANUP_GUIDE.md` - 模型清理指南 🆕
---
**创建时间**: 2025-11-03
**问题发现**: Agent Config 字段既在初始化脚本中,又应该在增量迁移中
**解决方案**: 创建智能兼容性迁移脚本,同时支持新旧数据库
**更新时间**: 2025-11-03
**新增功能**: 添加未引用模型清理脚本,支持软删除和硬删除