ctms/docs/UPDATE_DEMO.txt

#!/bin/bash
# CTMS 在线更新功能演示
# 此脚本演示如何使用新的更新功能

cat <<'EOF'
╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║              CTMS 在线更新功能 - 快速演示                    ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

本演示将展示如何使用优化后的更新脚本从远程仓库拉取代码并自动部署。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【场景 1】基础更新 - 交互式操作

命令：
  bash scripts/update.sh dev

特点：
  • 自动检测当前远程仓库地址
  • 提示输入 Git 凭证
  • 创建自动备份 tag
  • 验证项目身份
  • 自动部署

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【场景 2】指定仓库地址

命令：
  bash scripts/update.sh main \
    --repo-url https://github.com/user/ctms.git

特点：
  • 明确指定远程仓库
  • 适合多仓库环境
  • 仍然交互式输入凭证

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【场景 3】全自动模式 - CI/CD 部署

命令：
  export GIT_USERNAME="deploy-bot"
  export GIT_PASSWORD="ghp_xxxxxxxxxxxxx"

  bash scripts/update.sh release \
    --repo-url https://github.com/company/ctms.git \
    --branch v1.2.0 \
    --yes

特点：
  ✓ 无交互确认
  ✓ 从环境变量读取凭证
  ✓ 指定特定分支/标签
  ✓ 适合自动化部署

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【场景 4】强制覆盖本地更改

命令：
  bash scripts/update.sh dev --force

特点：
  ⚠ 执行 git reset --hard
  ⚠ 本地更改将丢失
  • 适合纯部署环境

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【场景 5】SSH 密钥认证

命令：
  bash scripts/update.sh dev \
    --repo-url git@github.com:user/ctms.git

特点：
  ✓ 无需输入密码
  ✓ 前提：已配置 SSH 公钥
  ✓ 最安全的方式

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【安全特性】

1. 项目身份验证
   • 检查 4 个特征文件
   • 防止拉取错误仓库
   • 拉取前后各验证一次

2. 自动备份
   • 创建带时间戳的 Git tag
   • 格式：pre-update-20260623-143022
   • 支持一键回滚

3. 工作目录保护
   • 检测未提交更改
   • 提供 stash/reset/取消 三种选择
   • 防止意外丢失代码

4. 凭证安全
   • 临时凭证助手
   • 自动清理（trap EXIT）
   • 不暴露在进程列表

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【实战演练】

让我们演示一个完整的更新流程：

步骤 1：查看当前状态
  $ git status
  $ git log --oneline -5

步骤 2：执行更新（使用当前仓库）
  $ bash scripts/update.sh dev

步骤 3：脚本会依次执行：
  ✓ 检查工作目录状态
  ✓ 解析仓库地址（自动检测到当前 remote）
  ✓ 解析分支（使用当前分支：dev）
  ✓ 显示参数预览并确认
  ✓ 验证项目身份
  ✓ 创建备份 tag：pre-update-20260623-151022
  ✓ 配置 Git 认证（提示输入用户名/密码）
  ✓ 拉取代码
  ✓ 再次验证项目身份
  ✓ 调用 install.sh 部署
  ✓ 显示成功信息

步骤 4：验证更新结果
  $ git log --oneline -3
  $ docker ps
  $ curl http://127.0.0.1:8888/health

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【回滚演示】

如果更新后发现问题，可以快速回滚：

步骤 1：查看备份 tag
  $ git tag | grep pre-update

  输出示例：
  pre-update-20260623-143022
  pre-update-20260623-151022

步骤 2：回滚到备份点
  $ git reset --hard pre-update-20260623-143022

步骤 3：重新部署
  $ bash scripts/install.sh dev --skip-migrate

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【GitHub Actions 集成示例】

在 .github/workflows/deploy.yml 中配置：

name: Auto Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: self-hosted
    steps:
      - name: Update CTMS
        env:
          GIT_USERNAME: ${{ secrets.DEPLOY_USERNAME }}
          GIT_PASSWORD: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          cd /opt/ctms
          bash scripts/update.sh main \
            --repo-url https://github.com/${{ github.repository }}.git \
            --branch main \
            --yes \
            --skip-backup

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【故障排查】

问题 1：认证失败
  症状：✖ 出错 拉取失败，请检查网络连接和仓库权限

  解决方案：
  • 检查仓库地址是否正确
  • 确认 Token 未过期
  • 确保有仓库访问权限

问题 2：项目身份验证失败
  症状：✖ 出错 项目身份验证失败

  解决方案：
  • 检查 --repo-url 是否指向正确的 CTMS 仓库
  • 确认 --branch 参数正确

问题 3：合并冲突
  症状：✖ 出错 合并失败，可能存在冲突

  解决方案：
  • 方法 1：手动解决冲突后重新运行
  • 方法 2：使用 --force 强制覆盖

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【最佳实践】

生产环境更新检查清单：
  □ 已在测试环境验证更新
  □ 已备份数据库
  □ 已通知相关人员维护窗口
  □ 准备回滚脚本
  □ 确认 --base-url 参数正确
  □ 使用 --branch 指定稳定版本

Token 安全管理：
  ✓ 使用 Personal Access Token 而非密码
  ✓ 设置 Token 过期时间
  ✓ 最小权限原则（只给 repo 权限）
  ✓ 定期轮换 Token
  ✓ 不在代码中硬编码

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【性能优化】

跳过不必要的步骤：

• 跳过镜像构建（仅重启容器）：
  bash scripts/update.sh dev --skip-build

• 跳过数据库迁移（无 schema 变更）：
  bash scripts/update.sh dev --skip-migrate

• 跳过备份（信任更新）：
  bash scripts/update.sh dev --skip-backup

• 组合使用：
  bash scripts/update.sh dev --skip-build --skip-migrate

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【更多帮助】

查看完整文档：
  • 使用指南：docs/GIT_SYNC_GUIDE.md
  • 优化总结：docs/UPDATE_OPTIMIZATION_SUMMARY.md
  • 命令帮助：bash scripts/update.sh --help

运行功能测试：
  bash scripts/test_update.sh

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

演示完成！你现在可以开始使用新的更新功能了 🚀

EOF