Agent/SERVER_MIGRATION_GUIDE.md

服务器迁移指南

⚠️ 重要：不要直接拉取代码！

由于我们进行了以下数据库变更，必须先执行迁移，否则会导致数据丢失或功能异常：

1. resources表：contents → resources（表重命名）
2. resources表：添加新字段（secure_body, content_type, metadata, updated_at）
3. knowledge表：添加resource_ids字段（用于关联资源）

迁移步骤

1. 连接到服务器

ssh agent_server
cd ~/main_agent

2. 备份数据库（重要！）

# 备份数据库文件
cp knowhub.db knowhub.db.backup.$(date +%Y%m%d_%H%M%S)

# 验证备份
ls -lh knowhub.db*

3. 拉取迁移脚本（不拉取全部代码）

# 只拉取迁移脚本
git fetch origin
git checkout origin/main -- migrate_to_resource.py

# 或者手动创建脚本（如果git checkout不工作）
# 将migrate_to_resource.py的内容复制到服务器

4. 执行迁移

# 确保在包含knowhub.db的目录中
python migrate_to_resource.py

预期输出：

============================================================
KnowHub 数据库迁移
变更内容：
  1. contents表 → resources表
  2. resources表添加新字段
  3. knowledge表添加resource_ids字段
============================================================
数据库路径: /home/user/main_agent/knowhub.db

当前表: {'contents', 'knowledge', 'experiences'}

============================================================
步骤1: 迁移 resources 表
============================================================
contents表中有 X 条记录
现有字段: {...}

添加 N 个新字段...
  ALTER TABLE contents ADD COLUMN secure_body TEXT DEFAULT ''
  ALTER TABLE contents ADD COLUMN content_type TEXT DEFAULT 'text'
  ALTER TABLE contents ADD COLUMN metadata TEXT DEFAULT '{}'
  ALTER TABLE contents ADD COLUMN updated_at TEXT DEFAULT ''
✅ 字段添加完成

重命名表: contents → resources
✅ 表重命名完成
resources表中有 X 条记录
✅ 数据完整，X 条记录全部保留

============================================================
步骤2: 更新 knowledge 表
============================================================
现有字段: {...}

添加 resource_ids 字段...
✅ resource_ids字段添加完成

============================================================
迁移总结
============================================================
迁移后的表: {'resources', 'knowledge', 'experiences'}
✅ resources表: X 条记录
✅ knowledge表: Y 条记录, resource_ids字段: 存在

✅ 迁移完成！现在可以拉取新代码并重启服务

5. 验证迁移

# 检查表是否存在
sqlite3 knowhub.db "SELECT name FROM sqlite_master WHERE type='table';"

# 检查resources表数据
sqlite3 knowhub.db "SELECT COUNT(*) FROM resources;"

# 检查knowledge表是否有resource_ids字段
sqlite3 knowhub.db "PRAGMA table_info(knowledge);" | grep resource_ids

6. 拉取新代码

git pull origin main

7. 重启服务

# 根据你的服务管理方式
# 如果使用systemd
sudo systemctl restart knowhub

# 如果使用screen/tmux
# 先停止旧进程，然后启动新进程
pkill -f "uvicorn knowhub.server"
uvicorn knowhub.server:app --host 0.0.0.0 --port 8000 &

# 或者使用你的启动脚本
./start_knowhub.sh

8. 验证服务

# 测试API
curl http://localhost:8000/api/resource

# 检查日志
tail -f logs/knowhub.log  # 根据实际日志路径

如果迁移失败

恢复备份

# 停止服务
pkill -f "uvicorn knowhub.server"

# 恢复备份
cp knowhub.db.backup.YYYYMMDD_HHMMSS knowhub.db

# 回退代码
git reset --hard HEAD~1

# 重启服务
uvicorn knowhub.server:app --host 0.0.0.0 --port 8000 &

检查问题

# 查看迁移脚本输出
# 查看数据库状态
sqlite3 knowhub.db ".tables"
sqlite3 knowhub.db ".schema contents"
sqlite3 knowhub.db ".schema resources"

数据库变更详情

1. resources表（原contents表）

变更：

• 表名：contents → resources
• 新增字段：
  • secure_body TEXT DEFAULT '' - 敏感内容（加密存储）
  • content_type TEXT DEFAULT 'text' - 内容类型（text|code|credential|cookie）
  • metadata TEXT DEFAULT '{}' - JSON元数据
  • updated_at TEXT DEFAULT '' - 更新时间

影响：

• 旧的/api/content端点不再可用
• 需要使用新的/api/resource端点

2. knowledge表

变更：

• 新增字段：resource_ids TEXT DEFAULT '[]' - 关联的资源ID列表（JSON数组）

用途：

• 知识条目可以引用多个资源
• 示例：["code/selenium/login", "credentials/website_a"]
• 通过GET /api/resource/{id}获取关联的资源详情

注意事项

1. 必须先备份：迁移前务必备份数据库
2. 按顺序执行：不要跳过步骤
3. 验证完整性：迁移后检查数据条数是否一致
4. 测试API：重启后测试新的/api/resource端点

API端点变更

迁移后，API端点已更改：

旧端点	新端点	状态
POST /api/content	POST /api/resource	✅ 已更新
GET /api/content/{id}	GET /api/resource/{id}	✅ 已更新
PATCH /api/content/{id}	PATCH /api/resource/{id}	✅ 已更新
GET /api/content	GET /api/resource	✅ 已更新

如果有外部系统调用旧API，需要同步更新。