diff --git a/gitea/README.md b/gitea/README.md
index 47603f7..52e7d4a 100644
--- a/gitea/README.md
+++ b/gitea/README.md
@@ -63,7 +63,7 @@ scp -r gitea/ root@服务器IP:/opt/gitea
 ```bash
 ssh root@服务器IP
 cd /opt/gitea
-chmod +x deploy.sh backup.sh
+chmod +x deploy.sh backup.sh upgrade.sh migrate.sh
 
 # 首次运行 → 自动安装系统依赖 + Docker + Nginx
 # 然后生成 .env 配置文件（密码已随机生成）并退出
@@ -226,24 +226,215 @@ docker compose down           # 停止并移除容器
 docker compose up -d          # 启动
 ```
 
-### 升级 Gitea
+### 升级组件（一键脚本）
+
+```bash
+cd /opt/gitea
+chmod +x upgrade.sh
+
+# 交互式选择要升级的组件
+bash upgrade.sh
+
+# 或直接指定组件
+bash upgrade.sh gitea      # 仅升级 Gitea
+bash upgrade.sh mysql      # 仅升级 MySQL
+bash upgrade.sh nginx      # 仅升级 Nginx
+bash upgrade.sh certbot    # 仅升级 Certbot
+bash upgrade.sh docker     # 仅升级 Docker
+bash upgrade.sh all        # 升级全部
+```
+
+> 脚本会自动显示当前版本、执行备份、拉取新镜像、重启服务并验证。
+
+---
+
+### 手动升级详细步骤
+
+#### 升级 Gitea
+
+Gitea 以 Docker 容器运行，升级 = 拉取新镜像 + 重启容器。数据库结构变更会在启动时自动迁移。
 
 ```bash
 cd /opt/gitea
 
-# 1. 先备份
+# 1. 备份（必须！）
 bash backup.sh
 
-# 2. 拉取新镜像
-docker compose pull
+# 2. 查看当前版本
+curl -s http://127.0.0.1:3000/api/v1/version
 
-# 3. 重启
+# 3. 修改目标版本（编辑 .env 中的 GITEA_IMAGE）
+#    ● 查看最新版本号: https://github.com/go-gitea/gitea/releases
+#    ● 或访问: https://hub.docker.com/r/gitea/gitea/tags
+vi .env
+# 修改: GITEA_IMAGE=gitea/gitea:1.25.5  ← 替换为目标版本号
+
+# 4. 拉取新镜像
+docker compose pull server
+
+# 5. 重启（自动执行数据库迁移）
+docker compose up -d server
+
+# 6. 检查日志确认启动成功
+docker compose logs -f server
+# 看到 "Starting new Web server: tcp:0.0.0.0:3000" 表示成功
+# Ctrl+C 退出日志
+
+# 7. 验证新版本
+curl -s http://127.0.0.1:3000/api/v1/version
+```
+
+**注意事项：**
+- 务必查阅 [Gitea 发版说明](https://github.com/go-gitea/gitea/releases) 了解 Breaking Changes
+- 不支持版本降级，升级前务必备份
+- 跨多个大版本建议逐版本升级（如 1.21 → 1.22 → 1.23）
+
+#### 升级 MySQL
+
+**小版本升级（8.0.x → 8.0.y）**— 安全，直接拉取新镜像：
+
+```bash
+cd /opt/gitea
+
+# 1. 备份
+bash backup.sh
+
+# 2. 拉取最新 8.0 补丁
+docker compose pull db
+
+# 3. 重启 MySQL
+docker compose up -d db
+
+# 4. 等待就绪，确认版本
+docker compose exec db mysql --version
+
+# 5. 重启 Gitea 刷新连接
+docker compose restart server
+```
+
+**大版本升级（8.0 → 8.4 / 9.0）**— 需要导出/导入数据：
+
+```bash
+cd /opt/gitea
+
+# 1. 完整备份
+bash backup.sh
+
+# 2. 导出数据库
+docker compose exec -T db mysqldump \
+    -u root -p"${DB_ROOT_PASSWORD}" \
+    --single-transaction --routines --triggers \
+    --databases gitea > /tmp/gitea_mysql_export.sql
+
+# 3. 停止所有服务
+docker compose down
+
+# 4. 备份 MySQL 数据目录
+cp -a /var/lib/mysql/gitea /var/lib/mysql/gitea.bak
+
+# 5. 清空数据目录（新版本将重新初始化）
+rm -rf /var/lib/mysql/gitea/*
+
+# 6. 修改 docker-compose.yml 中的镜像版本
+#    将 image: mysql:8.0 改为 image: mysql:8.4
+vi docker-compose.yml
+#    MySQL 8.4+ 如不需要旧认证插件，可删除 --mysql-native-password=ON
+
+# 7. 启动新版本 MySQL（等待初始化完成）
+docker compose up -d db
+docker compose logs -f db
+# 看到 "ready for connections" 后 Ctrl+C
+
+# 8. 导入数据
+docker compose exec -T db mysql \
+    -u root -p"${DB_ROOT_PASSWORD}" < /tmp/gitea_mysql_export.sql
+
+# 9. 启动 Gitea
 docker compose up -d
 
-# 4. 检查日志
-docker compose logs -f server
+# 10. 确认版本
+docker compose exec db mysql --version
 ```
 
+**注意事项：**
+- MySQL 仅支持相邻大版本升级（8.0 → 8.4 → 9.0），不可跨版本
+- 确认 Gitea 对目标 MySQL 版本的兼容性
+- 回滚方法：`docker compose down` → 恢复数据目录和 docker-compose.yml → 重启
+
+#### 升级 Nginx
+
+Nginx 通过系统包管理器安装，使用系统更新升级：
+
+```bash
+# 1. 查看当前版本
+nginx -v
+
+# 2. 更新 Nginx
+apt-get update && apt-get install -y --only-upgrade nginx
+# CentOS/RHEL: yum update -y nginx
+
+# 3. 验证配置文件无语法错误
+nginx -t
+
+# 4. 平滑重载（不中断服务）
+systemctl reload nginx
+
+# 5. 确认新版本
+nginx -v
+```
+
+> Nginx 的 `reload` 是平滑重载，不会中断现有连接。只有配置文件变化才需要重载。
+
+#### 升级 Certbot + 续期 SSL 证书
+
+```bash
+# 1. 查看当前版本
+certbot --version
+
+# 2. 更新 Certbot
+apt-get update && apt-get install -y --only-upgrade certbot python3-certbot-nginx
+# CentOS/RHEL: yum update -y certbot python3-certbot-nginx
+
+# 3. 确认新版本
+certbot --version
+
+# 4. 查看证书状态
+certbot certificates
+
+# 5. 测试续期流程（不实际续期）
+certbot renew --dry-run
+
+# 6. 查看证书到期时间
+openssl x509 -enddate -noout -in /etc/letsencrypt/live/你的域名/fullchain.pem
+
+# 如证书即将到期或需要强制续期:
+certbot renew --force-renewal --post-hook 'systemctl reload nginx'
+```
+
+> 证书自动续期已由 deploy.sh 配置 cron（每天 03:00 检查），通常无需手动操作。
+
+#### 升级 Docker
+
+```bash
+# 1. 查看当前版本
+docker --version
+docker compose version
+
+# 2. 更新 Docker Engine + Compose
+apt-get update && apt-get install -y --only-upgrade \
+    docker-ce docker-ce-cli containerd.io docker-compose-plugin
+# CentOS/RHEL: yum update -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+
+# 3. 确认版本
+docker --version
+docker compose version
+
+# 4. 确认容器正常运行
+docker compose ps
+```
+
+> Docker 更新后服务会自动重启，容器在 `restart: always` 策略下会自动恢复。
+
 ### 定时自动备份
 
 ```bash
@@ -284,6 +475,116 @@ gunzip < /var/backups/gitea/db_20260406_030000.sql.gz | \
 docker compose up -d
 ```
 
+### 迁移到新服务器（一键脚本）
+
+将已部署的 Gitea 完整迁移到另一台服务器，包含数据库、仓库、LFS、配置等全部数据。
+
+> 参考 [Gitea 官方备份与恢复文档](https://docs.gitea.com/zh-cn/administration/backup-and-restore)
+
+```bash
+# ===== 旧服务器 =====
+cd /opt/gitea
+chmod +x migrate.sh
+
+# 导出迁移包（会自动停服 → mysqldump → 打包数据 → 打包配置）
+bash migrate.sh export
+# 生成: /var/backups/gitea/gitea_migrate_日期.tar.gz
+
+# 传输到新服务器
+scp /var/backups/gitea/gitea_migrate_*.tar.gz root@新服务器IP:/opt/gitea/
+```
+
+```bash
+# ===== 新服务器 =====
+# 前提：已安装 Docker（可先运行 deploy.sh 的 Docker 安装步骤，或手动安装）
+mkdir -p /opt/gitea
+cd /opt/gitea
+
+# 导入迁移包（会自动恢复配置 → 恢复数据 → 导入数据库 → 启动 → regenerate hooks → doctor check）
+bash migrate.sh import gitea_migrate_日期.tar.gz
+
+# 验证迁移完整性
+bash migrate.sh verify
+```
+
+**脚本自动完成的操作：**
+
+| 阶段 | 操作 |
+|------|------|
+| 导出 | 停止 Gitea → mysqldump 导出数据库 → 打包 Gitea 数据目录 → 打包部署配置 → 生成迁移包 |
+| 导入 | 解压 → 恢复配置 → 恢复数据目录 → 启动 MySQL → 导入数据库 → 启动 Gitea → regenerate hooks → doctor check |
+| 验证 | 检查容器状态 → API 可达性 → 数据库连接 → 仓库/用户数量 → 数据目录完整性 → Nginx 状态 |
+
+**迁移后注意事项：**
+- 如域名或 IP 变更，导入前需修改 `.env` 中的 `GITEA_DOMAIN`
+- 域名变更后需更新 DNS 解析并重新申请 SSL 证书：`certbot certonly --webroot -w /var/www/certbot -d 新域名`
+- 如新服务器未安装 Nginx/Certbot，可运行 `bash deploy.sh` 补装（脚本会跳过已有组件）
+- 确保新服务器 Gitea 版本 ≥ 旧服务器版本（不支持降级）
+- 官方建议使用 `mysqldump` 而非 `gitea dump` 的 XORM 导出（脚本已采用此方案）
+
+<details>
+<summary>手动迁移步骤（不使用脚本）</summary>
+
+```bash
+# ===== 旧服务器 =====
+cd /opt/gitea
+
+# 1. 停止 Gitea
+docker compose stop server
+
+# 2. 导出数据库
+docker compose exec -T db mysqldump \
+    -u root -p"${DB_ROOT_PASSWORD}" \
+    --single-transaction --routines --triggers \
+    --databases gitea > gitea-db.sql
+
+# 3. 停止全部
+docker compose down
+
+# 4. 打包数据
+tar czf gitea-data.tar.gz -C /var/lib/gitea .
+
+# 5. 打包配置
+tar czf gitea-config.tar.gz .env docker-compose.yml nginx/ *.sh
+
+# 6. 传输
+scp gitea-db.sql gitea-data.tar.gz gitea-config.tar.gz root@新服务器:/opt/gitea/
+```
+
+```bash
+# ===== 新服务器 =====
+cd /opt/gitea
+
+# 7. 恢复配置
+tar xzf gitea-config.tar.gz
+vi .env  # 如需修改域名
+
+# 8. 恢复数据
+mkdir -p /var/lib/gitea
+tar xzf gitea-data.tar.gz -C /var/lib/gitea
+chown -R 1000:1000 /var/lib/gitea
+
+# 9. 启动 MySQL 并导入
+docker compose up -d db
+# 等待就绪...
+docker compose exec -T db mysql \
+    -u root -p"${DB_ROOT_PASSWORD}" \
+    --default-character-set=utf8mb4 < gitea-db.sql
+
+# 10. 启动 Gitea
+docker compose up -d
+
+# 11. 重新生成 Git Hooks（必须！否则 push 会失败）
+docker compose exec -u git server \
+    /usr/local/bin/gitea -c /data/gitea/conf/app.ini admin regenerate hooks
+
+# 12. 运行 doctor 修复潜在问题
+docker compose exec -u git server \
+    /usr/local/bin/gitea -c /data/gitea/conf/app.ini doctor check --all --fix
+```
+
+</details>
+
 ---
 
 ## 五、安全加固清单
@@ -322,11 +623,14 @@ docker compose exec server gitea admin user change-password -u 管理员用户
 - 确认 Git 提交邮箱与 GPG 密钥邮箱一致
 
 **Q: 如何迁移到新服务器？**
-1. 旧服务器执行 `bash backup.sh`
-2. 复制部署目录 `/opt/gitea/`、数据 `/var/lib/gitea/`、备份 `/var/backups/gitea/` 到新服务器
-3. 新服务器执行 `bash deploy.sh`
-4. 修改域名 DNS 指向新服务器 IP
-5. 重新申请 SSL 证书：`certbot certonly --webroot -w /var/www/certbot -d 域名`
+使用迁移脚本一键完成，详见上方「迁移到新服务器」章节：
+```bash
+# 旧服务器导出
+bash migrate.sh export
+# 新服务器导入
+bash migrate.sh import gitea_migrate_xxx.tar.gz
+bash migrate.sh verify
+```
 
 ---
 
@@ -338,6 +642,8 @@ docker compose exec server gitea admin user change-password -u 管理员用户
 ├── .env.example                    # 环境变量模板
 ├── .env                            # 运行时配置（自动生成）
 ├── deploy.sh                       # 全新服务器一键部署脚本
+├── upgrade.sh                      # 组件升级脚本（Gitea/MySQL/Nginx/Certbot/Docker）
+├── migrate.sh                      # 服务器迁移脚本（导出/导入/验证）
 ├── backup.sh                       # MySQL + 数据备份脚本
 ├── .gitignore
 ├── README.md
@@ -366,3 +672,8 @@ docker compose exec server gitea admin user change-password -u 管理员用户
 /etc/nginx/sites-available/gitea    # Nginx HTTPS 配置（由 deploy.sh 生成）
 /etc/letsencrypt/live/域名/         # SSL 证书（由 Certbot 管理）
 ```
+
+## 官方文档
+
+- Gitea 官方文档（英文）：<https://docs.gitea.com/>
+- Gitea 官方文档（中文）：<https://docs.gitea.com/zh-cn/>
diff --git a/gitea/migrate.sh b/gitea/migrate.sh
new file mode 100644
index 0000000..222e1a4
--- /dev/null
+++ b/gitea/migrate.sh
@@ -0,0 +1,513 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================
+# Gitea 迁移脚本（旧服务器 → 新服务器）
+# 用法：
+#   bash migrate.sh export              # 旧服务器：导出迁移包
+#   bash migrate.sh import <迁移包路径>  # 新服务器：导入迁移包
+#   bash migrate.sh verify              # 迁移后：验证完整性
+#
+# 迁移流程：
+#   旧服务器 → export → scp 传输 → 新服务器 → import → verify
+# ============================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+log()     { echo -e "${GREEN}[INFO]${NC} $*"; }
+warn()    { echo -e "${YELLOW}[WARN]${NC} $*"; }
+error()   { echo -e "${RED}[ERROR]${NC} $*" >&2; }
+step()    { echo -e "\n${CYAN}========== $* ==========${NC}"; }
+confirm() {
+    echo -en "${YELLOW}[确认]${NC} $* [y/N]: "
+    read -r reply
+    [[ "$reply" =~ ^[Yy]$ ]]
+}
+
+# ===== 前置检查 =====
+preflight() {
+    if [ "$(id -u)" -ne 0 ]; then
+        error "请使用 root 用户运行: sudo bash migrate.sh"
+        exit 1
+    fi
+}
+
+load_env() {
+    if [ ! -f .env ]; then
+        error ".env 文件不存在"
+        exit 1
+    fi
+    set -a
+    source .env
+    set +a
+}
+
+# =============================================================
+#  导出模式 — 在旧服务器执行
+# =============================================================
+do_export() {
+    step "迁移导出 — 旧服务器"
+
+    load_env
+
+    GITEA_DATA_DIR="${GITEA_DATA_DIR:-/var/lib/gitea}"
+    MYSQL_DATA_DIR="${MYSQL_DATA_DIR:-/var/lib/mysql/gitea}"
+    BACKUP_DIR="${BACKUP_DIR:-/var/backups/gitea}"
+    DATE=$(date +%Y%m%d_%H%M%S)
+    EXPORT_DIR="${BACKUP_DIR}/migrate_${DATE}"
+    EXPORT_ARCHIVE="${BACKUP_DIR}/gitea_migrate_${DATE}.tar.gz"
+
+    mkdir -p "$EXPORT_DIR"
+
+    # --- 1. 显示当前状态 ---
+    step "1/6 当前环境信息"
+    log "域名: ${GITEA_DOMAIN:-未设置}"
+    log "数据目录: ${GITEA_DATA_DIR}"
+    log "MySQL 数据: ${MYSQL_DATA_DIR}"
+
+    if docker compose ps --status running 2>/dev/null | grep -q gitea; then
+        GITEA_VER=$(curl -sf http://127.0.0.1:3000/api/v1/version 2>/dev/null | grep -oP '"version"\s*:\s*"\K[^"]+' || echo "未知")
+        log "Gitea 版本: ${GITEA_VER}"
+    fi
+
+    MYSQL_VER=$(docker compose exec -T db mysql --version 2>/dev/null | grep -oP 'Distrib \K[0-9.]+' || echo "未知")
+    log "MySQL 版本: ${MYSQL_VER}"
+
+    echo ""
+    warn "导出过程中 Gitea 将停止服务，以保证数据一致性。"
+    if ! confirm "是否继续？"; then
+        log "已取消"
+        rm -rf "$EXPORT_DIR"
+        exit 0
+    fi
+
+    # --- 2. 停止 Gitea，保留 MySQL 用于导出 ---
+    step "2/6 停止 Gitea 容器"
+    docker compose stop server 2>/dev/null || true
+    log "Gitea 已停止"
+
+    # --- 3. 导出 MySQL 数据库 ---
+    step "3/6 导出 MySQL 数据库"
+    log "使用 mysqldump 导出（比 gitea dump 的 XORM 更可靠）..."
+    docker compose exec -T db mysqldump \
+        -u root -p"${DB_ROOT_PASSWORD}" \
+        --single-transaction \
+        --routines \
+        --triggers \
+        --databases gitea \
+        > "${EXPORT_DIR}/gitea-db.sql"
+
+    DB_SIZE=$(du -h "${EXPORT_DIR}/gitea-db.sql" | cut -f1)
+    log "数据库导出完成: gitea-db.sql (${DB_SIZE})"
+
+    # --- 4. 停止所有容器 ---
+    step "4/6 停止全部容器"
+    docker compose down
+    log "全部容器已停止"
+
+    # --- 5. 打包 Gitea 数据 ---
+    step "5/6 打包 Gitea 数据目录"
+    if [ -d "$GITEA_DATA_DIR" ]; then
+        log "正在打包 ${GITEA_DATA_DIR} ..."
+        tar czf "${EXPORT_DIR}/gitea-data.tar.gz" \
+            -C "$(dirname "$GITEA_DATA_DIR")" \
+            "$(basename "$GITEA_DATA_DIR")"
+        DATA_SIZE=$(du -h "${EXPORT_DIR}/gitea-data.tar.gz" | cut -f1)
+        log "数据打包完成: gitea-data.tar.gz (${DATA_SIZE})"
+    else
+        warn "数据目录 ${GITEA_DATA_DIR} 不存在，跳过"
+    fi
+
+    # --- 5b. 打包部署配置 ---
+    log "正在打包部署配置..."
+    tar czf "${EXPORT_DIR}/gitea-config.tar.gz" \
+        -C "$SCRIPT_DIR" \
+        --exclude='.git' \
+        --exclude='data' \
+        --exclude='backups' \
+        .env docker-compose.yml .env.example \
+        $([ -d nginx ] && echo "nginx/") \
+        $([ -f backup.sh ] && echo "backup.sh") \
+        $([ -f deploy.sh ] && echo "deploy.sh") \
+        $([ -f upgrade.sh ] && echo "upgrade.sh") \
+        $([ -f migrate.sh ] && echo "migrate.sh") \
+        $([ -f .gitignore ] && echo ".gitignore") \
+        $([ -f README.md ] && echo "README.md") \
+        2>/dev/null || true
+    log "配置打包完成: gitea-config.tar.gz"
+
+    # --- 5c. 记录元信息 ---
+    cat > "${EXPORT_DIR}/migrate-meta.txt" <<EOF
+# Gitea 迁移元信息
+export_date=${DATE}
+gitea_version=${GITEA_VER:-unknown}
+mysql_version=${MYSQL_VER:-unknown}
+gitea_domain=${GITEA_DOMAIN:-}
+gitea_data_dir=${GITEA_DATA_DIR}
+mysql_data_dir=${MYSQL_DATA_DIR}
+source_hostname=$(hostname)
+EOF
+
+    # --- 6. 生成最终迁移包 ---
+    step "6/6 生成迁移包"
+    tar czf "$EXPORT_ARCHIVE" -C "$BACKUP_DIR" "migrate_${DATE}"
+    TOTAL_SIZE=$(du -h "$EXPORT_ARCHIVE" | cut -f1)
+
+    # 清理临时目录
+    rm -rf "$EXPORT_DIR"
+
+    # 重启服务（旧服务器可继续运行）
+    echo ""
+    if confirm "导出完成。是否重启旧服务器的 Gitea？"; then
+        docker compose up -d
+        log "服务已重启"
+    fi
+
+    echo ""
+    log "===== 导出完成 ====="
+    log "迁移包: ${EXPORT_ARCHIVE} (${TOTAL_SIZE})"
+    echo ""
+    log "下一步：将迁移包传输到新服务器并执行导入"
+    echo -e "${CYAN}  scp ${EXPORT_ARCHIVE} root@新服务器IP:/opt/gitea/${NC}"
+    echo -e "${CYAN}  # 在新服务器上:${NC}"
+    echo -e "${CYAN}  cd /opt/gitea${NC}"
+    echo -e "${CYAN}  bash migrate.sh import $(basename "$EXPORT_ARCHIVE")${NC}"
+}
+
+# =============================================================
+#  导入模式 — 在新服务器执行
+# =============================================================
+do_import() {
+    local archive="$1"
+
+    if [ ! -f "$archive" ]; then
+        error "迁移包不存在: $archive"
+        echo "用法: bash migrate.sh import <迁移包路径>"
+        exit 1
+    fi
+
+    step "迁移导入 — 新服务器"
+
+    # --- 1. 解压迁移包 ---
+    step "1/9 解压迁移包"
+    WORK_DIR=$(mktemp -d)
+    tar xzf "$archive" -C "$WORK_DIR"
+    MIGRATE_DIR=$(find "$WORK_DIR" -maxdepth 1 -type d -name 'migrate_*' | head -1)
+
+    if [ -z "$MIGRATE_DIR" ]; then
+        error "无效的迁移包格式"
+        rm -rf "$WORK_DIR"
+        exit 1
+    fi
+
+    # 显示元信息
+    if [ -f "${MIGRATE_DIR}/migrate-meta.txt" ]; then
+        log "迁移包信息:"
+        grep -v '^#' "${MIGRATE_DIR}/migrate-meta.txt" | while IFS='=' read -r key val; do
+            printf "  %-20s %s\n" "$key:" "$val"
+        done
+    fi
+
+    # --- 2. 检查必要文件 ---
+    step "2/9 检查迁移包内容"
+    local has_db=false has_data=false has_config=false
+
+    [ -f "${MIGRATE_DIR}/gitea-db.sql" ] && has_db=true
+    [ -f "${MIGRATE_DIR}/gitea-data.tar.gz" ] && has_data=true
+    [ -f "${MIGRATE_DIR}/gitea-config.tar.gz" ] && has_config=true
+
+    log "数据库导出: $(${has_db} && echo '✓' || echo '✗')"
+    log "数据目录:   $(${has_data} && echo '✓' || echo '✗')"
+    log "部署配置:   $(${has_config} && echo '✓' || echo '✗')"
+
+    if ! $has_db || ! $has_data; then
+        error "迁移包缺少必要文件（需要 gitea-db.sql 和 gitea-data.tar.gz）"
+        rm -rf "$WORK_DIR"
+        exit 1
+    fi
+
+    echo ""
+    warn "导入将覆盖当前服务器上的 Gitea 数据。"
+    if ! confirm "是否继续？"; then
+        log "已取消"
+        rm -rf "$WORK_DIR"
+        exit 0
+    fi
+
+    # --- 3. 恢复配置文件 ---
+    step "3/9 恢复部署配置"
+    if $has_config; then
+        tar xzf "${MIGRATE_DIR}/gitea-config.tar.gz" -C "$SCRIPT_DIR"
+        log "配置文件已恢复到 ${SCRIPT_DIR}/"
+    fi
+
+    # 加载 .env
+    load_env
+    GITEA_DATA_DIR="${GITEA_DATA_DIR:-/var/lib/gitea}"
+    MYSQL_DATA_DIR="${MYSQL_DATA_DIR:-/var/lib/mysql/gitea}"
+
+    # --- 4. 提示修改配置 ---
+    step "4/9 检查配置"
+    echo ""
+    warn "如果新服务器的域名或 IP 与旧服务器不同，请先修改 .env："
+    echo -e "  ${CYAN}vi ${SCRIPT_DIR}/.env${NC}"
+    echo ""
+    echo "  当前配置："
+    echo "    GITEA_DOMAIN=${GITEA_DOMAIN:-未设置}"
+    echo "    GITEA_DATA_DIR=${GITEA_DATA_DIR}"
+    echo "    MYSQL_DATA_DIR=${MYSQL_DATA_DIR}"
+    echo ""
+
+    if ! confirm "配置正确，继续导入？（如需修改请选 N，改完后重新运行 import）"; then
+        log "已暂停。修改 .env 后重新运行:"
+        echo -e "  ${CYAN}bash migrate.sh import ${archive}${NC}"
+        rm -rf "$WORK_DIR"
+        exit 0
+    fi
+
+    # --- 5. 停止现有服务 ---
+    step "5/9 停止现有服务"
+    docker compose down 2>/dev/null || true
+
+    # --- 6. 安装基础设施（如新服务器未部署过） ---
+    step "6/9 检查基础设施"
+    if ! command -v docker &>/dev/null; then
+        warn "Docker 未安装。请先运行 deploy.sh 安装基础设施，或手动安装 Docker。"
+        echo -e "  ${CYAN}bash deploy.sh${NC}"
+        rm -rf "$WORK_DIR"
+        exit 1
+    fi
+
+    if ! docker compose version &>/dev/null; then
+        error "Docker Compose V2 未安装"
+        rm -rf "$WORK_DIR"
+        exit 1
+    fi
+    log "Docker 和 Compose 已就绪"
+
+    # --- 7. 恢复 Gitea 数据目录 ---
+    step "7/9 恢复 Gitea 数据"
+    mkdir -p "$(dirname "$GITEA_DATA_DIR")"
+    if [ -d "$GITEA_DATA_DIR" ] && [ "$(ls -A "$GITEA_DATA_DIR" 2>/dev/null)" ]; then
+        warn "数据目录 ${GITEA_DATA_DIR} 非空"
+        if confirm "是否清空后恢复？（选 N 则覆盖合并）"; then
+            rm -rf "${GITEA_DATA_DIR:?}/"*
+        fi
+    fi
+    tar xzf "${MIGRATE_DIR}/gitea-data.tar.gz" -C "$(dirname "$GITEA_DATA_DIR")"
+    chown -R 1000:1000 "$GITEA_DATA_DIR"
+    log "Gitea 数据已恢复到 ${GITEA_DATA_DIR}"
+
+    # --- 8. 恢复数据库 ---
+    step "8/9 恢复 MySQL 数据库"
+
+    # 确保 MySQL 数据目录存在
+    mkdir -p "$MYSQL_DATA_DIR"
+
+    # 启动 MySQL（清空后让其自动初始化）
+    log "启动 MySQL 容器..."
+    docker compose up -d db
+
+    # 等待 MySQL 就绪
+    log "等待 MySQL 就绪..."
+    local retries=0
+    while ! docker compose exec -T db mysqladmin ping -h localhost -u root -p"${DB_ROOT_PASSWORD}" --silent 2>/dev/null; do
+        retries=$((retries + 1))
+        if [ "$retries" -ge 60 ]; then
+            error "MySQL 启动超时（60 次重试）"
+            rm -rf "$WORK_DIR"
+            exit 1
+        fi
+        sleep 2
+    done
+    log "MySQL 已就绪"
+
+    # 导入数据库
+    log "正在导入数据库（这可能需要几分钟）..."
+    docker compose exec -T db mysql \
+        -u root -p"${DB_ROOT_PASSWORD}" \
+        --default-character-set=utf8mb4 \
+        < "${MIGRATE_DIR}/gitea-db.sql"
+    log "数据库导入完成"
+
+    # --- 9. 启动 Gitea 并执行迁移后操作 ---
+    step "9/9 启动 Gitea 并验证"
+    docker compose up -d
+    log "容器已启动，等待 Gitea 就绪..."
+
+    local retries=0
+    while ! curl -sf http://127.0.0.1:3000/api/v1/version &>/dev/null; do
+        retries=$((retries + 1))
+        if [ "$retries" -ge 60 ]; then
+            warn "Gitea 启动超时，请手动检查: docker compose logs server"
+            break
+        fi
+        sleep 2
+    done
+
+    if curl -sf http://127.0.0.1:3000/api/v1/version &>/dev/null; then
+        GITEA_VER=$(curl -sf http://127.0.0.1:3000/api/v1/version | grep -oP '"version"\s*:\s*"\K[^"]+')
+        log "Gitea ${GITEA_VER} 启动成功"
+    fi
+
+    # 重新生成 Git Hooks（迁移后必须执行）
+    log "重新生成 Git Hooks..."
+    docker compose exec -u git server \
+        /usr/local/bin/gitea -c /data/gitea/conf/app.ini admin regenerate hooks || \
+        warn "regenerate hooks 失败，请手动执行"
+
+    # 运行 doctor 检查
+    log "运行 doctor 诊断..."
+    docker compose exec -u git server \
+        /usr/local/bin/gitea -c /data/gitea/conf/app.ini doctor check --all --fix 2>&1 | \
+        tail -5 || warn "doctor check 返回异常，请检查日志"
+
+    # 清理
+    rm -rf "$WORK_DIR"
+
+    echo ""
+    log "===== 导入完成 ====="
+    log "Gitea 已在新服务器运行"
+    echo ""
+    warn "迁移后请检查以下事项:"
+    echo "  1. 访问 https://${GITEA_DOMAIN:-你的域名} 确认页面正常"
+    echo "  2. 如域名/IP 变更，需更新 DNS 解析"
+    echo "  3. 如需 HTTPS，需重新申请 SSL 证书:"
+    echo -e "     ${CYAN}certbot certonly --webroot -w /var/www/certbot -d ${GITEA_DOMAIN:-你的域名}${NC}"
+    echo "  4. 测试 Git clone / push 操作"
+    echo "  5. 测试 SSH 克隆: git clone ssh://git@${GITEA_DOMAIN:-你的域名}:${SSH_PORT:-2222}/用户/仓库.git"
+    echo ""
+    log "运行验证命令检查完整性: bash migrate.sh verify"
+}
+
+# =============================================================
+#  验证模式 — 迁移后验证完整性
+# =============================================================
+do_verify() {
+    step "迁移后验证"
+
+    load_env
+    GITEA_DATA_DIR="${GITEA_DATA_DIR:-/var/lib/gitea}"
+    local pass=0 fail=0
+
+    check() {
+        if eval "$2" &>/dev/null; then
+            echo -e "  ${GREEN}✓${NC} $1"
+            pass=$((pass + 1))
+        else
+            echo -e "  ${RED}✗${NC} $1"
+            fail=$((fail + 1))
+        fi
+    }
+
+    echo ""
+    log "检查服务状态:"
+    check "Gitea 容器运行中" "docker compose ps --status running | grep -q gitea"
+    check "MySQL 容器运行中" "docker compose ps --status running | grep -q gitea-db"
+
+    log "检查 API:"
+    check "Gitea API 可达" "curl -sf http://127.0.0.1:3000/api/v1/version"
+
+    if curl -sf http://127.0.0.1:3000/api/v1/version &>/dev/null; then
+        GITEA_VER=$(curl -sf http://127.0.0.1:3000/api/v1/version | grep -oP '"version"\s*:\s*"\K[^"]+')
+        log "  Gitea 版本: ${GITEA_VER}"
+    fi
+
+    log "检查数据库:"
+    check "MySQL 连接正常" "docker compose exec -T db mysqladmin ping -h localhost -u root -p'${DB_ROOT_PASSWORD}' --silent"
+
+    # 检查仓库数量
+    REPO_COUNT=$(docker compose exec -T db mysql -u root -p"${DB_ROOT_PASSWORD}" -N -e \
+        "SELECT COUNT(*) FROM gitea.repository;" 2>/dev/null || echo "0")
+    log "  仓库数量: ${REPO_COUNT}"
+
+    USER_COUNT=$(docker compose exec -T db mysql -u root -p"${DB_ROOT_PASSWORD}" -N -e \
+        "SELECT COUNT(*) FROM gitea.user;" 2>/dev/null || echo "0")
+    log "  用户数量: ${USER_COUNT}"
+
+    log "检查数据目录:"
+    check "Gitea 数据目录存在" "[ -d '${GITEA_DATA_DIR}/gitea' ]"
+    check "仓库目录存在" "[ -d '${GITEA_DATA_DIR}/gitea/repositories' ] || [ -d '${GITEA_DATA_DIR}/git/repositories' ]"
+    check "app.ini 存在" "[ -f '${GITEA_DATA_DIR}/gitea/conf/app.ini' ]"
+
+    # 统计仓库目录下的裸仓库数量
+    if [ -d "${GITEA_DATA_DIR}/gitea/repositories" ]; then
+        DISK_REPOS=$(find "${GITEA_DATA_DIR}/gitea/repositories" -name "*.git" -type d -maxdepth 3 2>/dev/null | wc -l)
+        log "  磁盘上的仓库目录: ${DISK_REPOS}"
+    fi
+
+    log "检查网络:"
+    check "SSH 端口可监听" "docker compose port server 2222"
+
+    if command -v nginx &>/dev/null; then
+        check "Nginx 运行中" "systemctl is-active nginx"
+        check "Nginx 配置正确" "nginx -t"
+    else
+        warn "  Nginx 未安装（如需 HTTPS 请运行 deploy.sh 或手动安装）"
+    fi
+
+    echo ""
+    log "===== 验证结果: ${pass} 通过, ${fail} 失败 ====="
+    if [ "$fail" -gt 0 ]; then
+        warn "存在失败项，请检查上方输出并排查问题"
+        echo "  查看日志: docker compose logs"
+        return 1
+    else
+        log "所有检查通过！迁移成功。"
+    fi
+}
+
+# =============================================================
+#  主入口
+# =============================================================
+usage() {
+    echo "Gitea 迁移脚本"
+    echo ""
+    echo "用法:"
+    echo "  bash migrate.sh export                # 旧服务器：导出迁移包"
+    echo "  bash migrate.sh import <迁移包路径>    # 新服务器：导入迁移包"
+    echo "  bash migrate.sh verify                # 迁移后：验证完整性"
+    echo ""
+    echo "迁移流程:"
+    echo "  1. 旧服务器: bash migrate.sh export"
+    echo "  2. 传输: scp gitea_migrate_xxx.tar.gz root@新服务器:/opt/gitea/"
+    echo "  3. 新服务器: bash migrate.sh import gitea_migrate_xxx.tar.gz"
+    echo "  4. 新服务器: bash migrate.sh verify"
+}
+
+main() {
+    preflight
+
+    case "${1:-}" in
+        export)
+            do_export
+            ;;
+        import)
+            if [ -z "${2:-}" ]; then
+                error "请指定迁移包路径"
+                echo "用法: bash migrate.sh import <迁移包路径>"
+                exit 1
+            fi
+            do_import "$2"
+            ;;
+        verify)
+            do_verify
+            ;;
+        -h|--help|help)
+            usage
+            ;;
+        *)
+            usage
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"
diff --git a/gitea/upgrade.sh b/gitea/upgrade.sh
new file mode 100644
index 0000000..c435945
--- /dev/null
+++ b/gitea/upgrade.sh
@@ -0,0 +1,617 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================
+# Gitea 服务组件升级脚本
+# 支持升级：Gitea / MySQL / Nginx / Certbot / Docker
+# 用法：bash upgrade.sh [组件名]
+#   bash upgrade.sh              # 交互式选择
+#   bash upgrade.sh gitea        # 仅升级 Gitea
+#   bash upgrade.sh mysql        # 仅升级 MySQL
+#   bash upgrade.sh nginx        # 仅升级 Nginx
+#   bash upgrade.sh certbot      # 仅升级 Certbot
+#   bash upgrade.sh docker       # 仅升级 Docker
+#   bash upgrade.sh all          # 升级全部组件
+# ============================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+log()     { echo -e "${GREEN}[INFO]${NC} $*"; }
+warn()    { echo -e "${YELLOW}[WARN]${NC} $*"; }
+error()   { echo -e "${RED}[ERROR]${NC} $*" >&2; }
+step()    { echo -e "\n${CYAN}========== $* ==========${NC}"; }
+confirm() {
+    echo -en "${YELLOW}[确认]${NC} $* [y/N]: "
+    read -r reply
+    [[ "$reply" =~ ^[Yy]$ ]]
+}
+
+# ===== 前置检查 =====
+preflight() {
+    if [ "$(id -u)" -ne 0 ]; then
+        error "请使用 root 用户运行: sudo bash upgrade.sh"
+        exit 1
+    fi
+
+    if [ ! -f .env ]; then
+        error ".env 文件不存在，请先完成部署: bash deploy.sh"
+        exit 1
+    fi
+
+    set -a
+    source .env
+    set +a
+
+    # 检测包管理器
+    if command -v apt-get &> /dev/null; then
+        PKG_MGR="apt"
+    elif command -v dnf &> /dev/null; then
+        PKG_MGR="dnf"
+    elif command -v yum &> /dev/null; then
+        PKG_MGR="yum"
+    else
+        error "不支持的系统"
+        exit 1
+    fi
+}
+
+# ===== 获取当前版本信息 =====
+show_versions() {
+    step "当前组件版本"
+
+    # Gitea
+    local gitea_ver="未运行"
+    if docker compose ps --format json 2>/dev/null | grep -q '"server"' || \
+       docker compose ps 2>/dev/null | grep -q "gitea.*Up"; then
+        gitea_ver=$(curl -sf http://127.0.0.1:3000/api/v1/version 2>/dev/null | grep -o '"version":"[^"]*"' | cut -d'"' -f4 || echo "未知")
+    fi
+    local gitea_image
+    gitea_image=$(docker compose images server 2>/dev/null | tail -1 | awk '{print $2":"$3}' || echo "未知")
+    echo -e "  Gitea:   ${CYAN}${gitea_ver}${NC}  (镜像: ${gitea_image})"
+
+    # MySQL
+    local mysql_ver="未运行"
+    if docker compose ps --format json 2>/dev/null | grep -q '"db"' || \
+       docker compose ps 2>/dev/null | grep -q "gitea-db.*Up"; then
+        mysql_ver=$(docker compose exec -T db mysql --version 2>/dev/null | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1 || echo "未知")
+    fi
+    echo -e "  MySQL:   ${CYAN}${mysql_ver}${NC}"
+
+    # Nginx
+    local nginx_ver
+    nginx_ver=$(nginx -v 2>&1 | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "未安装")
+    echo -e "  Nginx:   ${CYAN}${nginx_ver}${NC}"
+
+    # Certbot
+    local certbot_ver
+    certbot_ver=$(certbot --version 2>&1 | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "未安装")
+    echo -e "  Certbot: ${CYAN}${certbot_ver}${NC}"
+
+    # Docker
+    local docker_ver
+    docker_ver=$(docker --version 2>/dev/null | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "未安装")
+    local compose_ver
+    compose_ver=$(docker compose version --short 2>/dev/null || echo "未安装")
+    echo -e "  Docker:  ${CYAN}${docker_ver}${NC}  (Compose: ${compose_ver})"
+
+    # SSL 证书
+    local domain="${GITEA_DOMAIN:-}"
+    if [ -n "$domain" ] && [ -d "/etc/letsencrypt/live/${domain}" ]; then
+        local cert_expiry
+        cert_expiry=$(openssl x509 -enddate -noout -in "/etc/letsencrypt/live/${domain}/fullchain.pem" 2>/dev/null | cut -d= -f2 || echo "未知")
+        echo -e "  SSL证书: 到期 ${CYAN}${cert_expiry}${NC}"
+    fi
+    echo ""
+}
+
+# ===== 备份 =====
+do_backup() {
+    step "升级前备份"
+
+    if [ -f "$SCRIPT_DIR/backup.sh" ]; then
+        log "正在执行完整备份..."
+        bash "$SCRIPT_DIR/backup.sh"
+        log "备份完成"
+    else
+        warn "backup.sh 不存在，跳过自动备份"
+        if ! confirm "继续升级（未备份）？"; then
+            error "已取消"
+            exit 1
+        fi
+    fi
+}
+
+# ============================================================
+#  升级 Gitea（Docker 容器）
+# ============================================================
+upgrade_gitea() {
+    step "升级 Gitea"
+
+    local current_image
+    current_image=$(grep -E '^\s*image:' docker-compose.yml | head -1 | awk '{print $2}' | envsubst || echo "unknown")
+    log "当前镜像配置: $(grep -E 'GITEA_IMAGE' .env 2>/dev/null | head -1 || echo '使用默认')"
+
+    # 获取远程最新 tag
+    log "检查最新版本..."
+    local latest_tag=""
+    # 尝试从 Docker Hub API 获取最新稳定版
+    latest_tag=$(curl -sf "https://registry.hub.docker.com/v2/repositories/gitea/gitea/tags?page_size=50&ordering=last_updated" 2>/dev/null \
+        | grep -o '"name":"[0-9]\+\.[0-9]\+\.[0-9]\+"' \
+        | head -1 \
+        | cut -d'"' -f4 || echo "")
+
+    if [ -n "$latest_tag" ]; then
+        log "Docker Hub 最新稳定版: $latest_tag"
+    else
+        warn "无法查询最新版本，请手动确认目标版本"
+    fi
+
+    echo ""
+    echo -e "  ${YELLOW}升级方式说明：${NC}"
+    echo "  ┌──────────────────────────────────────────────────────┐"
+    echo "  │ 方式 A（推荐）：修改 .env 中的 GITEA_IMAGE 后拉取    │"
+    echo "  │ 方式 B：直接拉取当前配置的镜像（获取 tag 内最新构建） │"
+    echo "  └──────────────────────────────────────────────────────┘"
+    echo ""
+
+    local do_change_version="n"
+    if [ -n "$latest_tag" ]; then
+        echo -en "  是否更新 GITEA_IMAGE 到 ${CYAN}gitea/gitea:${latest_tag}${NC}？[y/N]: "
+        read -r do_change_version
+    fi
+
+    if [[ "$do_change_version" =~ ^[Yy]$ ]] && [ -n "$latest_tag" ]; then
+        # 更新 .env 中的 GITEA_IMAGE
+        if grep -q "^GITEA_IMAGE=" .env; then
+            sed -i "s|^GITEA_IMAGE=.*|GITEA_IMAGE=gitea/gitea:${latest_tag}|" .env
+        else
+            echo "GITEA_IMAGE=gitea/gitea:${latest_tag}" >> .env
+        fi
+        log "已更新 .env: GITEA_IMAGE=gitea/gitea:${latest_tag}"
+        # 重新加载
+        set -a; source .env; set +a
+    fi
+
+    log "正在拉取 Gitea 镜像..."
+    docker compose pull server
+
+    log "正在重启 Gitea 容器（数据库迁移会自动执行）..."
+    docker compose up -d server
+
+    # 等待 Gitea 就绪
+    log "等待 Gitea 启动..."
+    local ready=0
+    for i in $(seq 1 60); do
+        if curl -sf http://127.0.0.1:3000/api/v1/version &> /dev/null; then
+            ready=1
+            break
+        fi
+        sleep 2
+    done
+
+    if [ "$ready" -eq 1 ]; then
+        local new_ver
+        new_ver=$(curl -sf http://127.0.0.1:3000/api/v1/version | grep -o '"version":"[^"]*"' | cut -d'"' -f4)
+        log "Gitea 升级成功！当前版本: $new_ver"
+    else
+        warn "Gitea 可能仍在启动，请检查日志: docker compose logs -f server"
+    fi
+
+    echo ""
+    warn "请浏览器访问 https://${GITEA_DOMAIN:-你的域名} 确认功能正常"
+}
+
+# ============================================================
+#  升级 MySQL（Docker 容器 — 小版本升级）
+# ============================================================
+upgrade_mysql() {
+    step "升级 MySQL"
+
+    local current_ver
+    current_ver=$(docker compose exec -T db mysql --version 2>/dev/null | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1 || echo "未知")
+    log "当前 MySQL 版本: $current_ver"
+
+    local current_image
+    current_image=$(grep -E 'image:\s*mysql' docker-compose.yml | awk '{print $2}' | tr -d '"' || echo "mysql:8.0")
+    log "当前镜像: $current_image"
+
+    echo ""
+    echo -e "  ${YELLOW}MySQL 升级须知：${NC}"
+    echo "  ┌──────────────────────────────────────────────────────────┐"
+    echo "  │ ● 小版本升级（8.0.x → 8.0.y）：拉取新镜像重启即可       │"
+    echo "  │ ● 大版本升级（8.0 → 8.4/9.0）：需要额外迁移步骤         │"
+    echo "  │   大版本升级建议：mysqldump 导出 → 新版本容器 → 导入      │"
+    echo "  │ ● MySQL 仅支持相邻大版本升级，不可跨版本                 │"
+    echo "  └──────────────────────────────────────────────────────────┘"
+    echo ""
+
+    # 选择升级类型
+    echo "  选择升级类型："
+    echo "    1) 小版本升级 — 拉取 mysql:8.0 最新补丁（推荐）"
+    echo "    2) 大版本升级 — 升级到 MySQL 8.4 LTS"
+    echo "    3) 大版本升级 — 升级到 MySQL 9.x（创新版本）"
+    echo "    0) 跳过 MySQL 升级"
+    echo ""
+    echo -en "  请选择 [0-3]: "
+    read -r mysql_choice
+
+    case "$mysql_choice" in
+        1)
+            _mysql_minor_upgrade
+            ;;
+        2)
+            _mysql_major_upgrade "mysql:8.4" "8.4"
+            ;;
+        3)
+            _mysql_major_upgrade "mysql:9.0" "9.0"
+            ;;
+        *)
+            log "跳过 MySQL 升级"
+            return
+            ;;
+    esac
+}
+
+_mysql_minor_upgrade() {
+    log "正在拉取 MySQL 8.0 最新镜像..."
+    docker compose pull db
+
+    log "正在重启 MySQL 容器..."
+    docker compose up -d db
+
+    # 等待就绪
+    log "等待 MySQL 就绪..."
+    for i in $(seq 1 60); do
+        if docker compose exec -T db mysqladmin ping -h localhost -u root -p"${DB_ROOT_PASSWORD}" --silent &> /dev/null; then
+            break
+        fi
+        sleep 2
+    done
+
+    local new_ver
+    new_ver=$(docker compose exec -T db mysql --version 2>/dev/null | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1 || echo "未知")
+    log "MySQL 小版本升级完成！当前版本: $new_ver"
+
+    # 重启 Gitea 确保数据库连接正常
+    log "重启 Gitea 以重新连接数据库..."
+    docker compose restart server
+}
+
+_mysql_major_upgrade() {
+    local target_image="$1"
+    local target_ver="$2"
+
+    warn "⚠️  MySQL 大版本升级有风险，确保已完成备份！"
+    echo ""
+    if ! confirm "确认要将 MySQL 升级到 ${target_ver}？"; then
+        log "已取消"
+        return
+    fi
+
+    log "第 1 步：导出当前数据库..."
+    local dump_file="/tmp/gitea_mysql_upgrade_$(date +%Y%m%d_%H%M%S).sql"
+    docker compose exec -T db mysqldump \
+        -u root -p"${DB_ROOT_PASSWORD}" \
+        --single-transaction \
+        --routines \
+        --triggers \
+        --databases gitea \
+        > "$dump_file"
+    local dump_size
+    dump_size=$(du -h "$dump_file" | cut -f1)
+    log "数据库导出完成: $dump_file ($dump_size)"
+
+    log "第 2 步：停止服务..."
+    docker compose down
+
+    log "第 3 步：备份 MySQL 数据目录..."
+    local mysql_data="${MYSQL_DATA_DIR:-/var/lib/mysql/gitea}"
+    local backup_mysql="${mysql_data}.bak.$(date +%Y%m%d_%H%M%S)"
+    cp -a "$mysql_data" "$backup_mysql"
+    log "数据目录已备份至: $backup_mysql"
+
+    log "第 4 步：清空 MySQL 数据目录（新版本将重新初始化）..."
+    rm -rf "${mysql_data:?}"/*
+
+    log "第 5 步：更新 docker-compose.yml 中的 MySQL 镜像..."
+    sed -i "s|image: mysql:8\.0|image: ${target_image}|" docker-compose.yml
+
+    # MySQL 8.4+ 不再需要 --mysql-native-password
+    if [[ "$target_ver" != "8.0" ]]; then
+        warn "MySQL ${target_ver} 默认使用 caching_sha2_password"
+        warn "移除 --mysql-native-password=ON 参数（如有兼容问题可恢复）"
+        sed -i '/--mysql-native-password=ON/d' docker-compose.yml
+    fi
+
+    log "第 6 步：启动新版本 MySQL..."
+    docker compose up -d db
+
+    log "等待 MySQL ${target_ver} 初始化..."
+    for i in $(seq 1 90); do
+        if docker compose exec -T db mysqladmin ping -h localhost -u root -p"${DB_ROOT_PASSWORD}" --silent &> /dev/null; then
+            break
+        fi
+        if [ "$i" -eq 90 ]; then
+            error "MySQL 启动超时！请检查日志: docker compose logs db"
+            error "如需回滚：cp -a $backup_mysql/* $mysql_data/ 并恢复 docker-compose.yml"
+            exit 1
+        fi
+        sleep 2
+    done
+
+    log "第 7 步：导入数据库..."
+    docker compose exec -T db mysql -u root -p"${DB_ROOT_PASSWORD}" < "$dump_file"
+    log "数据库导入完成"
+
+    log "第 8 步：启动 Gitea..."
+    docker compose up -d
+
+    local new_ver
+    new_ver=$(docker compose exec -T db mysql --version 2>/dev/null | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1 || echo "未知")
+    log "MySQL 大版本升级完成！当前版本: $new_ver"
+
+    echo ""
+    warn "导出文件保留在: $dump_file"
+    warn "旧数据目录保留在: $backup_mysql"
+    warn "确认运行正常后可手动删除以上文件"
+}
+
+# ============================================================
+#  升级 Nginx（系统包）
+# ============================================================
+upgrade_nginx() {
+    step "升级 Nginx"
+
+    local current_ver
+    current_ver=$(nginx -v 2>&1 | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "未知")
+    log "当前 Nginx 版本: $current_ver"
+
+    log "正在更新 Nginx..."
+    case "$PKG_MGR" in
+        apt)
+            apt-get update -qq
+            apt-get install -y --only-upgrade nginx
+            ;;
+        dnf)
+            dnf upgrade -y nginx
+            ;;
+        yum)
+            yum update -y nginx
+            ;;
+    esac
+
+    local new_ver
+    new_ver=$(nginx -v 2>&1 | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "未知")
+
+    if [ "$current_ver" = "$new_ver" ]; then
+        log "Nginx 已是最新版: $new_ver"
+    else
+        log "Nginx 已更新: $current_ver → $new_ver"
+    fi
+
+    # 验证配置
+    log "验证 Nginx 配置..."
+    if nginx -t 2>&1; then
+        systemctl reload nginx
+        log "Nginx 配置验证通过并已重载"
+    else
+        error "Nginx 配置验证失败！请手动检查"
+        error "  nginx -t"
+        error "  vi /etc/nginx/sites-available/gitea"
+    fi
+}
+
+# ============================================================
+#  升级 Certbot（系统包）
+# ============================================================
+upgrade_certbot() {
+    step "升级 Certbot"
+
+    local current_ver
+    current_ver=$(certbot --version 2>&1 | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "未安装")
+    log "当前 Certbot 版本: $current_ver"
+
+    log "正在更新 Certbot..."
+    case "$PKG_MGR" in
+        apt)
+            apt-get update -qq
+            apt-get install -y --only-upgrade certbot python3-certbot-nginx
+            ;;
+        dnf)
+            dnf upgrade -y certbot python3-certbot-nginx
+            ;;
+        yum)
+            yum update -y certbot python3-certbot-nginx
+            ;;
+    esac
+
+    local new_ver
+    new_ver=$(certbot --version 2>&1 | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "未知")
+
+    if [ "$current_ver" = "$new_ver" ]; then
+        log "Certbot 已是最新版: $new_ver"
+    else
+        log "Certbot 已更新: $current_ver → $new_ver"
+    fi
+
+    # 测试证书续期
+    log "测试证书续期（dry-run）..."
+    if certbot renew --dry-run 2>&1 | tail -3; then
+        log "证书续期测试通过"
+    else
+        warn "证书续期测试失败，请检查 certbot 配置"
+    fi
+
+    # 检查证书有效期
+    local domain="${GITEA_DOMAIN:-}"
+    if [ -n "$domain" ] && [ -f "/etc/letsencrypt/live/${domain}/fullchain.pem" ]; then
+        local expiry
+        expiry=$(openssl x509 -enddate -noout -in "/etc/letsencrypt/live/${domain}/fullchain.pem" | cut -d= -f2)
+        log "当前证书到期时间: $expiry"
+
+        # 检查是否30天内到期
+        local expiry_epoch
+        expiry_epoch=$(date -d "$expiry" +%s 2>/dev/null || echo 0)
+        local now_epoch
+        now_epoch=$(date +%s)
+        local days_left=$(( (expiry_epoch - now_epoch) / 86400 ))
+
+        if [ "$days_left" -lt 30 ] && [ "$days_left" -gt 0 ]; then
+            warn "证书将在 ${days_left} 天后到期"
+            if confirm "是否立即续期？"; then
+                certbot renew --force-renewal --post-hook 'systemctl reload nginx'
+                log "证书已续期"
+            fi
+        elif [ "$days_left" -le 0 ]; then
+            error "证书已过期！正在强制续期..."
+            certbot renew --force-renewal --post-hook 'systemctl reload nginx'
+        else
+            log "证书有效期剩余: ${days_left} 天"
+        fi
+    fi
+}
+
+# ============================================================
+#  升级 Docker（系统包）
+# ============================================================
+upgrade_docker() {
+    step "升级 Docker"
+
+    local current_ver
+    current_ver=$(docker --version | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "未知")
+    log "当前 Docker 版本: $current_ver"
+
+    log "正在更新 Docker..."
+    case "$PKG_MGR" in
+        apt)
+            apt-get update -qq
+            apt-get install -y --only-upgrade docker-ce docker-ce-cli containerd.io docker-compose-plugin
+            ;;
+        dnf)
+            dnf upgrade -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+            ;;
+        yum)
+            yum update -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+            ;;
+    esac
+
+    local new_ver
+    new_ver=$(docker --version | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "未知")
+
+    if [ "$current_ver" = "$new_ver" ]; then
+        log "Docker 已是最新版: $new_ver"
+    else
+        log "Docker 已更新: $current_ver → $new_ver"
+        warn "Docker 已更新，容器将自动重启"
+    fi
+
+    local compose_ver
+    compose_ver=$(docker compose version --short 2>/dev/null || echo "未知")
+    log "Docker Compose 版本: $compose_ver"
+
+    # 确保服务正常运行
+    log "确认容器运行状态..."
+    docker compose ps
+}
+
+# ============================================================
+#  升级全部
+# ============================================================
+upgrade_all() {
+    step "升级全部组件"
+    echo ""
+    warn "将依次升级: Docker → Nginx → Certbot → MySQL → Gitea"
+    warn "升级前会自动执行完整备份"
+    echo ""
+
+    if ! confirm "确认升级全部组件？"; then
+        log "已取消"
+        exit 0
+    fi
+
+    do_backup
+    upgrade_docker
+    upgrade_nginx
+    upgrade_certbot
+    upgrade_mysql
+    upgrade_gitea
+
+    step "全部组件升级完成"
+    show_versions
+}
+
+# ============================================================
+#  交互菜单
+# ============================================================
+interactive_menu() {
+    echo ""
+    echo -e "  ${CYAN}可升级组件：${NC}"
+    echo "    1) Gitea    — Docker 容器镜像升级"
+    echo "    2) MySQL    — Docker 容器镜像升级（支持大/小版本）"
+    echo "    3) Nginx    — 系统包升级"
+    echo "    4) Certbot  — 系统包升级 + 证书检查"
+    echo "    5) Docker   — Docker Engine + Compose 升级"
+    echo "    6) 全部升级  — 依次升级所有组件"
+    echo "    0) 退出"
+    echo ""
+    echo -en "  请选择 [0-6]: "
+    read -r choice
+
+    case "$choice" in
+        1) do_backup; upgrade_gitea ;;
+        2) do_backup; upgrade_mysql ;;
+        3) upgrade_nginx ;;
+        4) upgrade_certbot ;;
+        5) do_backup; upgrade_docker ;;
+        6) upgrade_all ;;
+        0) log "退出"; exit 0 ;;
+        *) error "无效选择"; exit 1 ;;
+    esac
+}
+
+# ============================================================
+#  主入口
+# ============================================================
+main() {
+    echo -e "${CYAN}"
+    echo "  ____  _ _"
+    echo " / ___|(_) |_ ___  __ _"
+    echo "| |  _ | | __/ _ \\/ _\` |"
+    echo "| |_| || | ||  __/ (_| |"
+    echo " \\____|_|\\__\\___|\\__,_|  Upgrade Script"
+    echo -e "${NC}"
+
+    preflight
+    show_versions
+
+    local target="${1:-}"
+
+    case "$target" in
+        gitea)   do_backup; upgrade_gitea ;;
+        mysql)   do_backup; upgrade_mysql ;;
+        nginx)   upgrade_nginx ;;
+        certbot) upgrade_certbot ;;
+        docker)  do_backup; upgrade_docker ;;
+        all)     upgrade_all ;;
+        "")      interactive_menu ;;
+        *)
+            error "未知组件: $target"
+            echo "  用法: bash upgrade.sh [gitea|mysql|nginx|certbot|docker|all]"
+            exit 1
+            ;;
+    esac
+
+    echo ""
+    step "升级后版本信息"
+    show_versions
+    log "升级完成！请检查服务是否正常: docker compose ps"
+}
+
+main "$@"