tsp-assistant/部署升级指南.md

# TSP智能助手部署升级指南

## 概述

本文档详细介绍了TSP智能助手项目的部署、升级和版本管理策略，包括多种部署方式和完整的回滚机制。

## 目录

1. [版本管理策略](#版本管理策略)
2. [部署方式](#部署方式)
3. [升级流程](#升级流程)
4. [回滚机制](#回滚机制)
5. [最佳实践](#最佳实践)
6. [故障排除](#故障排除)

## 版本管理策略

### 版本号规范

采用语义化版本控制（Semantic Versioning）：
- **主版本号（Major）**：不兼容的API修改
- **次版本号（Minor）**：向下兼容的功能性新增
- **修订号（Patch）**：向下兼容的问题修正

示例：`1.2.3` → `1.2.4`（补丁版本）

### 版本管理工具

项目提供了 `version.py` 脚本进行版本管理：

```bash
# 查看当前版本
python version.py version

# 增加版本号
python version.py increment --type patch    # 1.0.0 → 1.0.1
python version.py increment --type minor    # 1.0.1 → 1.1.0
python version.py increment --type major    # 1.1.0 → 2.0.0

# 设置部署状态
python version.py status --status production

# 添加变更日志
python version.py changelog --message "修复用户登录问题"

# 创建Git标签
python version.py tag --message "Release version 1.0.1"
```

### 版本信息存储

版本信息存储在 `version.json` 文件中：

```json
{
  "version": "1.0.0",
  "build_number": 1,
  "release_date": "2024-01-01T00:00:00",
  "git_commit": "a1b2c3d4",
  "deployment_status": "production",
  "changelog": [
    {
      "version": "1.0.0",
      "date": "2024-01-01T00:00:00",
      "description": "初始版本发布"
    }
  ],
  "dependencies": {
    "flask": "2.0.0",
    "sqlalchemy": "2.0.0"
  }
}
```

## 部署方式

### 1. 传统部署（推荐）

使用 `deploy.py` 脚本进行自动化部署：

```bash
# 部署到生产环境
python deploy.py deploy --source . --force

# 部署到测试环境
python deploy.py deploy --source . --environment staging

# 创建备份
python deploy.py backup

# 列出所有备份
python deploy.py list-backups

# 清理旧备份（保留5个）
python deploy.py cleanup --keep 5
```

### 2. Shell脚本部署

使用 `scripts/deploy.sh` 脚本：

```bash
# 部署到生产环境
./scripts/deploy.sh deploy production yourdomain.com 5000

# 部署到测试环境
./scripts/deploy.sh deploy staging staging.yourdomain.com 5001

# 部署到开发环境
./scripts/deploy.sh deploy development localhost 5000

# 回滚
./scripts/deploy.sh rollback backup_20240101_120000
```

### 3. Docker部署

#### 单容器部署

```bash
# 构建镜像
docker build -t tsp-assistant:latest .

# 运行容器
docker run -d \
  --name tsp-assistant \
  -p 5000:5000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  tsp-assistant:latest
```

#### Docker Compose部署

```bash
# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f tsp-assistant

# 停止服务
docker-compose down
```

### 4. 云平台部署

#### 阿里云ECS部署

```bash
# 1. 上传代码到服务器
scp -r . user@your-server:/opt/tsp_assistant

# 2. 在服务器上执行部署
ssh user@your-server
cd /opt/tsp_assistant
python deploy.py deploy --force
```

#### Kubernetes部署

```yaml
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tsp-assistant
spec:
  replicas: 3
  selector:
    matchLabels:
      app: tsp-assistant
  template:
    metadata:
      labels:
        app: tsp-assistant
    spec:
      containers:
      - name: tsp-assistant
        image: tsp-assistant:latest
        ports:
        - containerPort: 5000
        env:
        - name: DATABASE_URL
          value: "mysql+pymysql://user:pass@mysql-service/tsp_assistant"
```

## 升级流程

### 1. 准备升级

```bash
# 1. 确保代码已提交
git add .
git commit -m "准备升级到版本 1.0.1"

# 2. 创建发布分支
git checkout -b release-1.0.1

# 3. 更新版本号
python version.py increment --type patch

# 4. 添加变更日志
python version.py changelog --message "修复用户登录问题，优化性能"

# 5. 创建Git标签
python version.py tag --message "Release version 1.0.1"
```

### 2. 测试环境验证

```bash
# 1. 部署到测试环境
python deploy.py deploy --environment staging

# 2. 运行测试
python -m pytest tests/

# 3. 手动测试功能
curl http://staging.yourdomain.com/api/health
```

### 3. 生产环境升级

```bash
# 1. 创建备份
python deploy.py backup

# 2. 部署新版本
python deploy.py deploy --force

# 3. 验证部署
curl http://yourdomain.com/api/health

# 4. 监控系统状态
tail -f logs/tsp_assistant.log
```

### 4. 升级后验证

```bash
# 1. 健康检查
curl http://yourdomain.com/api/health

# 2. 功能测试
# - 用户登录
# - 工单创建
# - 知识库搜索
# - 数据分析

# 3. 性能监控
# - 响应时间
# - 内存使用
# - CPU使用率
```

## 回滚机制

### 1. 自动回滚

如果部署后健康检查失败，系统会自动回滚：

```bash
# 部署脚本会自动检测健康状态
python deploy.py deploy --force
# 如果健康检查失败，会自动回滚到上一个备份
```

### 2. 手动回滚

```bash
# 1. 列出可用备份
python deploy.py list-backups

# 2. 回滚到指定备份
python deploy.py rollback --backup backup_20240101_120000

# 3. 验证回滚结果
curl http://yourdomain.com/api/health
```

### 3. 数据库回滚

```bash
# 1. 停止服务
sudo systemctl stop tsp_assistant

# 2. 恢复数据库
cp backups/backup_20240101_120000/database/tsp_assistant.db ./

# 3. 重启服务
sudo systemctl start tsp_assistant
```

### 4. Docker回滚

```bash
# 1. 停止当前容器
docker stop tsp-assistant

# 2. 启动旧版本容器
docker run -d \
  --name tsp-assistant-old \
  -p 5000:5000 \
  tsp-assistant:v1.0.0

# 3. 验证回滚
curl http://localhost:5000/api/health
```

## 最佳实践

### 1. 部署前检查

- [ ] 代码已提交到版本控制
- [ ] 所有测试通过
- [ ] 数据库迁移脚本准备就绪
- [ ] 配置文件已更新
- [ ] 依赖包版本已锁定

### 2. 部署策略

- **蓝绿部署**：维护两套生产环境，切换流量
- **滚动更新**：逐步替换实例，保证服务可用性
- **金丝雀发布**：先发布给部分用户，验证无问题后全量发布

### 3. 监控和告警

```bash
# 设置监控脚本
cat > monitor.sh << 'EOF'
#!/bin/bash
while true; do
    if ! curl -f http://localhost:5000/api/health > /dev/null 2>&1; then
        echo "服务异常，发送告警"
        # 发送告警邮件或短信
    fi
    sleep 30
done
EOF

chmod +x monitor.sh
nohup ./monitor.sh &
```

### 4. 备份策略

- **自动备份**：每次部署前自动创建备份
- **定期备份**：每日创建完整备份
- **异地备份**：重要数据备份到不同地区
- **备份验证**：定期验证备份完整性

### 5. 安全考虑

- 使用HTTPS加密传输
- 定期更新依赖包
- 限制服务器访问权限
- 监控异常访问行为

## 故障排除

### 1. 常见问题

#### 部署失败

```bash
# 检查日志
tail -f logs/deploy.log

# 检查权限
ls -la /opt/tsp_assistant

# 检查服务状态
sudo systemctl status tsp_assistant
```

#### 服务无法启动

```bash
# 检查端口占用
netstat -tlnp | grep 5000

# 检查Python环境
which python3
python3 --version

# 检查依赖
pip list
```

#### 数据库连接失败

```bash
# 检查数据库服务
sudo systemctl status mysql

# 测试连接
mysql -u root -p -e "SHOW DATABASES;"

# 检查配置文件
cat src/config/config.py
```

### 2. 性能问题

#### 响应慢

```bash
# 检查系统资源
top
free -h
df -h

# 检查应用日志
tail -f logs/tsp_assistant.log

# 检查数据库性能
mysql -u root -p -e "SHOW PROCESSLIST;"
```

#### 内存泄漏

```bash
# 监控内存使用
ps aux | grep python

# 检查日志文件大小
ls -lh logs/

# 重启服务释放内存
sudo systemctl restart tsp_assistant
```

### 3. 紧急处理

#### 服务完全不可用

```bash
# 1. 立即回滚
python deploy.py rollback

# 2. 检查系统状态
sudo systemctl status tsp_assistant
sudo journalctl -u tsp_assistant -f

# 3. 联系技术支持
```

#### 数据丢失

```bash
# 1. 停止服务
sudo systemctl stop tsp_assistant

# 2. 恢复最新备份
python deploy.py rollback --backup latest

# 3. 验证数据完整性
python -c "from src.core.database import db; print('数据库连接正常')"
```

## 总结

TSP智能助手项目提供了完整的部署升级解决方案：

1. **版本管理**：语义化版本控制，自动版本号管理
2. **多种部署方式**：传统部署、Docker部署、云平台部署
3. **自动化流程**：一键部署、自动备份、健康检查
4. **完整回滚**：自动回滚、手动回滚、数据库回滚
5. **监控告警**：实时监控、异常告警、性能分析

通过遵循本指南，您可以安全、高效地管理TSP智能助手的部署和升级，确保系统的稳定性和可靠性。