da4736c323
主要更新内容: - 🚀 飞书多维表格集成，支持工单数据同步 - 🤖 AI建议与人工描述语义相似度计算 - 🎨 前端UI全面优化，现代化设计 - 📊 智能知识库入库策略（AI准确率<90%使用人工描述） - 🔧 代码重构，模块化架构优化 - 📚 完整文档整合和更新 - 🐛 修复配置导入和数据库字段问题 技术特性: - 使用sentence-transformers进行语义相似度计算 - 快速模式结合TF-IDF和语义方法 - 响应式设计，支持移动端 - 加载状态和动画效果 - 配置化AI准确率阈值
356 lines
8.8 KiB
Markdown
356 lines
8.8 KiB
Markdown
# TSP智能助手部署与更新指南
|
||
|
||
## 📋 目录
|
||
- [部署策略](#部署策略)
|
||
- [版本控制](#版本控制)
|
||
- [更新方式](#更新方式)
|
||
- [环境管理](#环境管理)
|
||
- [备份与回滚](#备份与回滚)
|
||
- [监控与通知](#监控与通知)
|
||
- [最佳实践](#最佳实践)
|
||
|
||
## 🚀 部署策略
|
||
|
||
### 1. 多环境部署架构
|
||
|
||
```
|
||
开发环境 (Development)
|
||
↓ 测试通过
|
||
测试环境 (Staging)
|
||
↓ 验证通过
|
||
生产环境 (Production)
|
||
```
|
||
|
||
### 2. 环境配置
|
||
|
||
| 环境 | 路径 | 服务名 | 自动重启 | 用途 |
|
||
|------|------|--------|----------|------|
|
||
| development | `./dev_deploy` | 无 | 否 | 本地开发 |
|
||
| staging | `/opt/tsp_assistant_staging` | `tsp_assistant_staging` | 是 | 功能测试 |
|
||
| production | `/opt/tsp_assistant` | `tsp_assistant` | 是 | 生产服务 |
|
||
|
||
## 🔄 版本控制
|
||
|
||
### 版本号规则
|
||
- **主版本号 (Major)**: 重大功能变更，可能不兼容
|
||
- **次版本号 (Minor)**: 新功能添加，向后兼容
|
||
- **修订号 (Patch)**: 错误修复，向后兼容
|
||
|
||
### 版本管理命令
|
||
|
||
```bash
|
||
# 查看当前版本
|
||
python version.py version
|
||
|
||
# 增加版本号
|
||
python version.py increment --type patch # 1.2.0 -> 1.2.1
|
||
python version.py increment --type minor # 1.2.0 -> 1.3.0
|
||
python version.py increment --type major # 1.2.0 -> 2.0.0
|
||
|
||
# 添加变更日志
|
||
python version.py changelog --message "修复系统性能趋势图表显示问题"
|
||
|
||
# 创建Git标签
|
||
python version.py tag --message "Release v1.2.0"
|
||
```
|
||
|
||
## 🔧 更新方式
|
||
|
||
### 1. 热更新 (Hot Update)
|
||
**适用场景**: 前端文件、配置文件、非核心Python文件
|
||
**优点**: 无需重启服务，用户体验好
|
||
**缺点**: 有限制，不能更新核心逻辑
|
||
|
||
```bash
|
||
# 热更新
|
||
python scripts/update_manager.py hot-update --source ./new_version --environment production
|
||
```
|
||
|
||
**支持热更新的文件**:
|
||
- `src/web/static/js/dashboard.js`
|
||
- `src/web/static/css/style.css`
|
||
- `src/web/templates/dashboard.html`
|
||
- `src/web/app.py` (部分)
|
||
- 配置文件
|
||
|
||
### 2. 完整更新 (Full Update)
|
||
**适用场景**: 核心逻辑变更、数据库结构变更、依赖更新
|
||
**优点**: 完整更新，确保一致性
|
||
**缺点**: 需要重启服务
|
||
|
||
```bash
|
||
# 完整更新
|
||
python scripts/update_manager.py full-update --source ./new_version --environment production
|
||
```
|
||
|
||
### 3. 自动更新 (Auto Update)
|
||
**智能选择**: 优先尝试热更新，失败则进行完整更新
|
||
|
||
```bash
|
||
# 自动更新
|
||
python scripts/update_manager.py auto-update --source ./new_version --environment production
|
||
```
|
||
|
||
## 🌍 环境管理
|
||
|
||
### 部署到不同环境
|
||
|
||
```bash
|
||
# 开发环境
|
||
python scripts/update_manager.py auto-update --source ./new_version --environment development
|
||
|
||
# 测试环境
|
||
python scripts/update_manager.py auto-update --source ./new_version --environment staging
|
||
|
||
# 生产环境
|
||
python scripts/update_manager.py auto-update --source ./new_version --environment production
|
||
```
|
||
|
||
### 环境检查
|
||
|
||
```bash
|
||
# 检查更新可用性
|
||
python scripts/update_manager.py check --source ./new_version --environment production
|
||
```
|
||
|
||
## 💾 备份与回滚
|
||
|
||
### 自动备份
|
||
- 每次更新前自动创建备份
|
||
- 备份包含应用文件和数据库
|
||
- 备份信息记录在 `backup_info.json`
|
||
|
||
### 手动备份
|
||
|
||
```bash
|
||
# 创建备份
|
||
python scripts/update_manager.py create-backup --environment production
|
||
```
|
||
|
||
### 回滚操作
|
||
|
||
```bash
|
||
# 列出所有备份
|
||
python scripts/update_manager.py list-backups
|
||
|
||
# 回滚到指定备份
|
||
python scripts/update_manager.py rollback --backup tsp_assistant_backup_20250916_163000 --environment production
|
||
```
|
||
|
||
### 备份信息
|
||
每个备份包含：
|
||
- 应用文件完整副本
|
||
- 数据库文件
|
||
- 版本信息
|
||
- Git提交哈希
|
||
- 备份时间戳
|
||
|
||
## 📊 监控与通知
|
||
|
||
### 健康检查
|
||
- 更新后自动执行健康检查
|
||
- 检查服务是否正常启动
|
||
- 验证API接口可用性
|
||
|
||
### 通知机制
|
||
- 更新成功/失败通知
|
||
- 回滚操作通知
|
||
- 系统状态监控
|
||
|
||
## 🎯 最佳实践
|
||
|
||
### 1. 更新流程
|
||
|
||
```bash
|
||
# 1. 开发完成，提交代码
|
||
git add .
|
||
git commit -m "feat: 添加新功能"
|
||
git push
|
||
|
||
# 2. 更新版本号
|
||
python version.py increment --type minor
|
||
python version.py changelog --message "添加新功能"
|
||
|
||
# 3. 创建发布标签
|
||
python version.py tag --message "Release v1.4.0"
|
||
|
||
# 4. 部署到测试环境
|
||
python scripts/update_manager.py auto-update --source . --environment staging
|
||
|
||
# 5. 测试验证通过后，部署到生产环境
|
||
python scripts/update_manager.py auto-update --source . --environment production
|
||
```
|
||
|
||
### 1.1. 飞书集成部署前准备
|
||
|
||
```bash
|
||
# 1. 配置飞书应用
|
||
# - 在飞书开放平台创建企业自建应用
|
||
# - 获取app_id和app_secret
|
||
# - 配置应用权限（读取多维表格）
|
||
|
||
# 2. 更新配置文件
|
||
# 编辑 config/integrations_config.json
|
||
{
|
||
"feishu": {
|
||
"app_id": "your-app-id",
|
||
"app_secret": "your-app-secret",
|
||
"app_token": "your-app-token",
|
||
"table_id": "your-table-id",
|
||
"status": "active"
|
||
}
|
||
}
|
||
|
||
# 3. 初始化数据库（包含新字段）
|
||
python init_database.py
|
||
|
||
# 4. 测试飞书连接
|
||
# 访问主仪表板的"飞书同步"标签页
|
||
# 点击"测试连接"验证配置
|
||
```
|
||
|
||
### 2. 安全更新
|
||
|
||
```bash
|
||
# 生产环境更新前先备份
|
||
python scripts/update_manager.py create-backup --environment production
|
||
|
||
# 使用自动更新（包含回滚机制）
|
||
python scripts/update_manager.py auto-update --source ./new_version --environment production
|
||
```
|
||
|
||
### 3. 紧急回滚
|
||
|
||
```bash
|
||
# 快速回滚到最新备份
|
||
python scripts/update_manager.py rollback --backup $(python scripts/update_manager.py list-backups | head -1 | cut -d' ' -f2) --environment production
|
||
```
|
||
|
||
### 4. 版本管理最佳实践
|
||
|
||
- **开发阶段**: 使用patch版本号
|
||
- **功能完成**: 使用minor版本号
|
||
- **重大变更**: 使用major版本号
|
||
- **每次发布**: 创建Git标签
|
||
- **重要更新**: 记录详细变更日志
|
||
|
||
## 🛠️ 工具集成
|
||
|
||
### CI/CD 集成
|
||
|
||
```yaml
|
||
# GitHub Actions 示例
|
||
name: Deploy TSP Assistant
|
||
on:
|
||
push:
|
||
tags: ['v*']
|
||
jobs:
|
||
deploy:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v2
|
||
- name: Deploy to Staging
|
||
run: |
|
||
python scripts/update_manager.py auto-update --source . --environment staging
|
||
- name: Run Tests
|
||
run: |
|
||
# 运行自动化测试
|
||
- name: Deploy to Production
|
||
if: success()
|
||
run: |
|
||
python scripts/update_manager.py auto-update --source . --environment production
|
||
```
|
||
|
||
### Docker 集成
|
||
|
||
```dockerfile
|
||
# Dockerfile 示例
|
||
FROM python:3.9-slim
|
||
WORKDIR /app
|
||
COPY requirements.txt .
|
||
RUN pip install -r requirements.txt
|
||
COPY . .
|
||
EXPOSE 5000
|
||
CMD ["python", "start_dashboard.py"]
|
||
```
|
||
|
||
## 🚨 故障处理
|
||
|
||
### 常见问题
|
||
|
||
1. **更新失败**
|
||
- 检查依赖是否正确安装
|
||
- 验证数据库迁移是否成功
|
||
- 查看服务日志
|
||
|
||
2. **回滚失败**
|
||
- 确认备份文件完整性
|
||
- 检查文件权限
|
||
- 验证服务配置
|
||
|
||
3. **健康检查失败**
|
||
- 检查服务是否正常启动
|
||
- 验证端口是否被占用
|
||
- 查看应用日志
|
||
|
||
4. **飞书集成问题**
|
||
- 检查飞书应用权限配置
|
||
- 验证app_token和table_id是否正确
|
||
- 确认网络连接和API访问权限
|
||
- 查看飞书同步日志
|
||
|
||
5. **数据库字段迁移失败**
|
||
- 检查数据库连接状态
|
||
- 验证字段映射配置
|
||
- 确认数据库权限
|
||
- 查看数据库初始化日志
|
||
|
||
### 紧急处理
|
||
|
||
```bash
|
||
# 停止服务
|
||
sudo systemctl stop tsp_assistant
|
||
|
||
# 手动回滚
|
||
sudo rm -rf /opt/tsp_assistant
|
||
sudo cp -r ./backups/tsp_assistant_backup_20250916_163000/app /opt/tsp_assistant
|
||
sudo chown -R www-data:www-data /opt/tsp_assistant
|
||
sudo systemctl start tsp_assistant
|
||
```
|
||
|
||
## 📝 更新记录
|
||
|
||
### v1.4.0 (2025-09-19)
|
||
- ✅ 飞书集成功能：支持飞书多维表格数据同步
|
||
- ✅ 页面功能合并：飞书同步页面合并到主仪表板
|
||
- ✅ 数据库架构优化：扩展工单表字段，支持飞书数据
|
||
- ✅ 代码重构优化：大文件拆分，降低运行风险
|
||
- ✅ 字段映射完善：智能映射飞书字段到本地数据库
|
||
- ✅ 数据库初始化改进：集成字段迁移到初始化流程
|
||
|
||
### v1.3.0 (2025-09-17)
|
||
- ✅ 数据库架构优化：MySQL主数据库+SQLite备份系统
|
||
- ✅ 工单详情API修复：解决数据库会话管理问题
|
||
- ✅ 备份管理系统：自动备份MySQL数据到SQLite
|
||
- ✅ 数据库状态监控：实时监控MySQL和SQLite状态
|
||
- ✅ 备份管理API：支持数据备份和恢复操作
|
||
|
||
### v1.2.0 (2025-09-16)
|
||
- ✅ 系统设置扩展：API管理、模型参数配置、端口管理
|
||
- ✅ 真实数据分析：修复性能趋势图表显示
|
||
- ✅ 工单AI建议功能
|
||
- ✅ 知识库搜索优化
|
||
- ✅ Agent管理改进
|
||
|
||
### v1.1.0 (2025-09-16)
|
||
- ✅ 工单AI建议功能
|
||
- ✅ 知识库搜索优化
|
||
- ✅ Agent管理改进
|
||
|
||
### v1.0.0 (2024-01-01)
|
||
- ✅ 初始版本发布
|
||
|
||
---
|
||
|
||
**注意**: 生产环境更新前请务必在测试环境验证，并确保有可用的备份。
|