Agent/RESOURCE_STORAGE_IMPLEMENTATION.md

Resource存储系统实现总结

实现内容

1. 数据库扩展

• 扩展contents表，添加以下字段：
  • secure_body: 敏感内容（加密存储）
  • content_type: 内容类型（text|code|credential|cookie）
  • metadata: JSON元数据
  • updated_at: 更新时间

2. 加密机制

• 使用AES-256-GCM加密算法
• 密钥从环境变量ORG_KEYS读取
• 格式：encrypted:AES256-GCM:{base64_data}
• 实现函数：
  • encrypt_resource(): 加密
  • decrypt_resource(): 解密
  • get_org_key(): 获取组织密钥

3. API端点

• POST /api/resource: 提交资源（自动加密secure_body）
• GET /api/resource/{id}: 获取资源（支持X-Org-Key头解密）
• PATCH /api/resource/{id}: 更新资源
• GET /api/resource: 列出资源（支持content_type过滤）

4. 数据模型

• ResourceIn: 提交请求模型
• ResourcePatchIn: 更新请求模型
• ResourceOut: 响应模型

5. 文档

• knowhub/docs/resource-storage.md: 设计文档
• knowhub/docs/resource-storage-examples.md: 使用示例
• knowhub/docs/decisions.md: 决策记录（新增第0条）
• knowhub/docs/knowledge-management.md: 更新架构说明

6. 工具

• migrate_resources.py: 数据库迁移脚本
• test_resource_storage.py: 测试脚本

使用方法

1. 配置密钥

# 生成密钥
python -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"

# 添加到.env
echo "ORG_KEYS=test:你的密钥base64" >> .env

2. 迁移数据库

python migrate_resources.py

3. 启动服务

uvicorn knowhub.server:app --reload

4. 测试功能

python test_resource_storage.py

设计特点

1. 分离公开/敏感内容：body明文可搜索，secure_body加密保护
2. 灵活的密钥管理：支持多组织密钥，通过resource_id前缀区分
3. 访问控制：需要提供正确的X-Org-Key才能解密
4. 元数据支持：记录获取时间、过期时间、语言等信息
5. 层级结构：通过ID路径实现树形组织（如tools/selenium/login）

安全考虑

• ✅ 敏感内容加密存储
• ✅ 密钥不入库，存储在环境变量
• ✅ 访问需要验证密钥
• ✅ 记录提交者和时间戳
• ⚠️ 密钥在HTTP头中传输（建议使用HTTPS）
• ⚠️ 数据库文件泄露仍有风险（建议文件系统加密）

后续改进

1. 支持密钥轮换
2. 添加访问日志
3. 支持密钥过期时间
4. 前端管理界面
5. 批量导入/导出功能