assist/部署更新指南.md

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): 错误修复，向后兼容

版本管理命令

# 查看当前版本
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文件 优点: 无需重启服务，用户体验好 缺点: 有限制，不能更新核心逻辑

# 热更新
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)

适用场景: 核心逻辑变更、数据库结构变更、依赖更新 优点: 完整更新，确保一致性 缺点: 需要重启服务

# 完整更新
python scripts/update_manager.py full-update --source ./new_version --environment production

3. 自动更新 (Auto Update)

智能选择: 优先尝试热更新，失败则进行完整更新

# 自动更新
python scripts/update_manager.py auto-update --source ./new_version --environment production

🌍 环境管理

部署到不同环境

# 开发环境
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

环境检查

# 检查更新可用性
python scripts/update_manager.py check --source ./new_version --environment production

💾 备份与回滚

自动备份

• 每次更新前自动创建备份
• 备份包含应用文件和数据库
• 备份信息记录在 backup_info.json

手动备份

# 创建备份
python scripts/update_manager.py create-backup --environment production

回滚操作

# 列出所有备份
python scripts/update_manager.py list-backups

# 回滚到指定备份
python scripts/update_manager.py rollback --backup tsp_assistant_backup_20250916_163000 --environment production

备份信息

每个备份包含：

• 应用文件完整副本
• 数据库文件
• 版本信息
• Git提交哈希
• 备份时间戳

📊 监控与通知

健康检查

• 更新后自动执行健康检查
• 检查服务是否正常启动
• 验证API接口可用性

通知机制

• 更新成功/失败通知
• 回滚操作通知
• 系统状态监控

🎯 最佳实践

1. 更新流程

# 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. 飞书集成部署前准备

# 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. 安全更新

# 生产环境更新前先备份
python scripts/update_manager.py create-backup --environment production

# 使用自动更新（包含回滚机制）
python scripts/update_manager.py auto-update --source ./new_version --environment production

3. 紧急回滚

# 快速回滚到最新备份
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 集成

# 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 示例
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. 数据库字段迁移失败

   • 检查数据库连接状态
   • 验证字段映射配置
   • 确认数据库权限
   • 查看数据库初始化日志

紧急处理

# 停止服务
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)

• ✅ 初始版本发布

---

注意: 生产环境更新前请务必在测试环境验证，并确保有可用的备份。