Swirl AI Search 管理员指南：从配置到部署全解析

Swirl AI Search 管理员指南：从配置到部署全解析

swirl-search Swirl is open-source software that uses AI to simultaneously search multiple content and data sources, finds the best results using a reader LLM, then prompts Generative AI, enabling you to get answers from your own data. 项目地址: https://gitcode.com/gh_mirrors/sw/swirl-search

概述

Swirl AI Search 是一个基于 Django 框架构建的智能搜索平台，本文将全面介绍如何配置、管理和部署 Swirl AI Search 系统。作为管理员，您将学习到环境配置、用户管理、权限控制、生产部署等关键知识。

环境配置详解

核心配置文件

Swirl 使用 .env 文件存储关键配置，采用 django-environ 进行管理：

1. 默认配置模板：.env.dist 文件包含所有默认设置
2. 初始化过程：安装脚本会自动复制 .env.dist 为 .env
3. 配置示例：

SECRET_KEY=your-unique-key-here
ALLOWED_HOSTS=yourdomain.com
SWIRL_EXPLAIN=True  # 启用结果解释功能

关键配置项说明

| 配置项 | 作用 | 推荐值 | |-------|------|-------| | SWIRL_TIMEOUT | 连接器超时时间(秒) | 10 | | SWIRL_DEDUPE_FIELD | 去重主键字段 | 'url' | | SWIRL_RELEVANCY_CONFIG | 相关性评分权重 | 标题1.5/正文1.0 |

配置修改流程

1. 编辑 .env 文件
2. 重启服务使配置生效
3. 注意：.env 不应纳入版本控制

用户管理体系

管理员账户操作

创建超级用户：

python manage.py createsuperuser --username admin --email admin@example.com

密码修改方式：

1. 命令行方式：

python manage.py changepassword username

2. Web界面方式：
   • 访问 /admin 界面
   • 在用户管理页面操作

权限模型设计

Swirl 采用基于对象的细粒度权限控制：

| 对象类型 | 权限类型 | 说明 | |---------|---------|------| | 搜索提供者 | CRUD | 数据源管理 | | 搜索任务 | CRUD | 搜索执行 | | 结果集 | 只读/编辑 | 结果查看 |

典型权限方案：

• 普通用户：搜索任务创建+结果查看
• 数据分析师：增加结果分析权限
• 系统管理员：全权限

生产环境部署指南

反向代理配置

为什么需要反向代理：

1. 性能优化：

   • SSL/TLS 卸载
   • 静态内容缓存
   • 负载均衡

2. 高可用保障：

   • 健康检查
   • 故障自动转移

推荐方案：

• Nginx：高性能、易配置
• HAProxy：专业级负载均衡
• 云服务商方案：AWS ALB/Azure Gateway

服务守护化

使用 swirl.py 管理服务生命周期：

# 启动服务
python swirl.py start

# 查看状态
python swirl.py status

# 重启服务
python swirl.py restart celery-worker

系统维护与升级

升级流程

1. 更新代码库
2. 运行安装脚本：

./install.sh

3. 初始化设置：

python swirl.py setup

4. 重启服务

数据库维护

迁移操作：

python swirl.py migrate

紧急恢复：

1. 删除 db.sqlite3
2. 清空迁移文件
3. 重新初始化

品牌定制化

UI 定制要素

1. Logo替换：

   • 尺寸：818×214px
   • 格式：PNG
   • 边距：≥30px

2. 文本定制：

   • 搜索按钮文字
   • 提示文本
   • AI响应标签

配置步骤

1. 访问管理界面 /admin
2. 上传品牌配置
3. 刷新前端界面

高级配置技巧

定时服务调整

搜索过期服务：

• 默认每小时执行
• 修改 CELERY_BEAT_SCHEDULE 配置

订阅更新服务：

• 默认每4小时执行
• 企业版支持5分钟间隔

相关性优化

通过 SWIRL_RELEVANCY_CONFIG 调整：

{
    'title': {'weight': 1.5},  # 标题权重
    'body': {'weight': 1.0}    # 正文权重
}

故障排查

常见问题解决

1. 服务无法启动：

   • 检查端口冲突
   • 验证数据库权限

2. 迁移失败：

   • 清理旧迁移文件
   • 重建数据库

3. 权限问题：

   • 检查用户组设置
   • 验证对象所有权

最佳实践建议

1. 安全建议：

   • 定期轮换 SECRET_KEY
   • 禁用调试模式
   • 使用HTTPS

2. 性能优化：

   • 合理设置超时参数
   • 优化数据库索引
   • 调整Celery并发数

3. 维护计划：

   • 定期备份数据库
   • 监控服务日志
   • 及时应用安全更新

通过本指南，您应该已经掌握了 Swirl AI Search 系统的全面管理知识。实际部署时，请根据具体业务需求调整配置参数，并建立完善的监控和维护机制。

swirl-search Swirl is open-source software that uses AI to simultaneously search multiple content and data sources, finds the best results using a reader LLM, then prompts Generative AI, enabling you to get answers from your own data. 项目地址: https://gitcode.com/gh_mirrors/sw/swirl-search