数据库和依赖变更处理指南

# 数据库和依赖变更处理指南

## 目录

1. [变更检测](#变更检测)
2. [依赖变更处理](#依赖变更处理)
3. [数据库变更处理](#数据库变更处理)
4. [大表迁移方案](#大表迁移方案)
5. [完整更新流程](#完整更新流程)
6. [常见问题](#常见问题)

---

## 变更检测

### 自动检测脚本

```bash
#!/bin/bash
# check-changes.sh - 检测变更类型

cd /www/wwwroot/hrm-app

# 获取更新前后对比
git fetch origin
LOCAL=$(git rev-parse HEAD)
REMOTE=$(git rev-parse origin/main)

echo "========== 变更检测 =========="
echo ""

# 1. 检测依赖变更
echo "【1】依赖变更检测 (package.json / pnpm-lock.yaml)"
DEP_CHANGED=$(git diff --name-only $LOCAL $REMOTE | grep -E "package\.json|pnpm-lock\.yaml" || true)
if [ -n "$DEP_CHANGED" ]; then
    echo "⚠️  检测到依赖变更:"
    echo "$DEP_CHANGED"
    
    # 显示新增/删除的依赖
    echo ""
    echo "新增依赖:"
    git diff $LOCAL $REMOTE -- package.json | grep -E '^\+.*"dependencies"' -A 20 | grep '^\+' | grep -v '^\+\+' || echo "无"
    
    echo ""
    NEED_PNPM_INSTALL=1
else
    echo "✅ 无依赖变更"
    NEED_PNPM_INSTALL=0
fi

echo ""

# 2. 检测数据库变更
echo "【2】数据库变更检测 (schema.ts / drizzle/)"
DB_CHANGED=$(git diff --name-only $LOCAL $REMOTE | grep -E "schema\.ts|drizzle/" || true)
if [ -n "$DB_CHANGED" ]; then
    echo "⚠️  检测到数据库变更:"
    echo "$DB_CHANGED"
    
    # 显示具体变更
    echo ""
    echo "变更详情:"
    git diff --stat $LOCAL $REMOTE -- "**/schema.ts" | head -20
    
    NEED_DB_MIGRATE=1
else
    echo "✅ 无数据库变更"
    NEED_DB_MIGRATE=0
fi

echo ""

# 3. 检测环境变量变更
echo "【3】环境变量变更检测 (.env.example)"
ENV_CHANGED=$(git diff --name-only $LOCAL $REMOTE | grep ".env.example" || true)
if [ -n "$ENV_CHANGED" ]; then
    echo "⚠️  检测到环境变量模板变更:"
    echo "$ENV_CHANGED"
    echo ""
    echo "请检查是否需要更新 .env 文件:"
    git diff $LOCAL $REMOTE -- .env.example | head -30
else
    echo "✅ 无环境变量变更"
fi

echo ""
echo "========== 检测结果汇总 =========="
echo "需要安装依赖: $([ $NEED_PNPM_INSTALL -eq 1 ] && echo '是 ⚠️' || echo '否')"
echo "需要数据库迁移: $([ $NEED_DB_MIGRATE -eq 1 ] && echo '是 ⚠️' || echo '否')"
```

### 手动检测命令

```bash
# 检查具体文件变更
git diff --name-only HEAD origin/main

# 检查依赖变更详情
git diff HEAD origin/main -- package.json

# 检查 schema 变更详情
git diff HEAD origin/main -- "**/schema.ts"
```

---

## 依赖变更处理

### 依赖变更类型

| 类型 | 说明 | 风险 | 处理 |
|------|------|------|------|
| 小版本更新 | 1.0.0 → 1.0.1 | 低 | 直接 pnpm install |
| 大版本更新 | 1.0.0 → 2.0.0 | 高 | 检查 Breaking Changes |
| 新增依赖 | 添加新包 | 中 | pnpm install |
| 删除依赖 | 移除包 | 低 | pnpm install 会自动清理 |

### 处理流程

```bash
# Step 1: 查看变更内容
git diff HEAD origin/main -- package.json

# Step 2: 检查 Breaking Changes（重要！）
# 如果有大版本更新，查看 CHANGELOG
# 例如：React 18 → 19，需要检查不兼容的变更

# Step 3: 安装依赖
pnpm install

# Step 4: 检查是否有 peer dependency 警告
# 如果有警告，需要手动处理

# Step 5: 重新构建
pnpm build

# Step 6: 重启服务
pm2 restart hrm-app
```

### 常见依赖变更问题

```bash
# 问题1: peer dependency 冲突
# 解决: 按提示安装缺失的依赖或使用 --force
pnpm install --force

# 问题2: 依赖下载失败（网络问题）
# 解决: 使用国内镜像
pnpm config set registry https://registry.npmmirror.com
pnpm install

# 问题3: 依赖版本不兼容
# 解决: 锁定版本
pnpm install package@1.2.3
```

---

## 数据库变更处理

### 数据库变更类型

| 类型 | 示例 | 风险 | 处理时间 |
|------|------|------|----------|
| 新增表 | CREATE TABLE | 低 | 毫秒级 |
| 新增字段 | ADD COLUMN | 低 | 毫秒级 |
| 新增索引 | CREATE INDEX | 中 | 可能较慢 |
| 修改字段类型 | ALTER COLUMN TYPE | 高 | 可能锁表 |
| 删除字段 | DROP COLUMN | 高 | 需确认无引用 |
| 删除表 | DROP TABLE | 最高 | 需确认无引用 |

### 标准迁移流程

```bash
# Step 1: 备份数据库（必须！）
pg_dump -h localhost -U hrm_user hrm_db > /www/backup/db_$(date +%Y%m%d_%H%M%S).sql

# Step 2: 查看变更内容
git diff HEAD~1 HEAD -- "**/schema.ts"

# Step 3: 生成迁移文件
pnpm drizzle-kit generate

# 查看生成的迁移文件
ls -la drizzle/*.sql
cat drizzle/*.sql

# Step 4: 在测试环境先执行（强烈建议）
# 如果有测试环境，先在测试环境验证

# Step 5: 执行迁移
pnpm drizzle-kit push

# Step 6: 验证迁移结果
psql -h localhost -U hrm_user hrm_db -c "\dt"  # 列出所有表
psql -h localhost -U hrm_user hrm_db -c "\d table_name"  # 查看表结构
```

### 迁移文件示例

```sql
-- drizzle/0001_add_user_status.sql

-- 新增字段（安全操作）
ALTER TABLE "users" ADD COLUMN "status" varchar(20) DEFAULT 'active';

-- 新增索引（可能较慢，大表需注意）
CREATE INDEX "idx_users_status" ON "users" ("status");

-- 修改字段类型（危险操作，可能锁表）
-- 建议分步执行：
-- 1. 新增字段
-- 2. 迁移数据
-- 3. 删除旧字段

-- 删除字段（危险操作）
-- 先确认没有代码引用此字段！
-- ALTER TABLE "users" DROP COLUMN "old_field";
```

---

## 大表迁移方案

### 什么情况需要特殊处理？

- 表数据量 > 100万行
- 需要添加索引
- 需要修改字段类型
- 需要删除字段

### 方案一：在线 DDL（推荐）

```sql
-- PostgreSQL 支持大部分操作不锁表
-- 但需要检查是否会阻塞

-- 检查当前是否有长事务
SELECT * FROM pg_stat_activity WHERE state = 'active';

-- 添加字段（带默认值可能较慢）
-- 方式1: 分两步
ALTER TABLE large_table ADD COLUMN new_field varchar(100);
-- 然后分批更新默认值
UPDATE large_table SET new_field = 'default' WHERE id BETWEEN 1 AND 100000;
UPDATE large_table SET new_field = 'default' WHERE id BETWEEN 100001 AND 200000;
-- ...

-- 添加索引（使用 CONCURRENTLY 不锁表）
CREATE INDEX CONCURRENTLY idx_large_table_field ON large_table(field);
```

### 方案二：分批迁移

```bash
#!/bin/bash
# batch-migrate.sh - 分批迁移脚本

TABLE="large_table"
BATCH_SIZE=10000
TOTAL=$(psql -t -c "SELECT COUNT(*) FROM $TABLE")

echo "总记录数: $TOTAL"
echo "每批处理: $BATCH_SIZE"

for ((i=0; i<$TOTAL; i+=$BATCH_SIZE)); do
    echo "处理 $i - $((i+BATCH_SIZE)) ..."
    
    # 执行迁移
    psql -c "
        UPDATE $TABLE 
        SET new_field = 'value' 
        WHERE id BETWEEN $i AND $((i+BATCH_SIZE-1))
        AND new_field IS NULL
    "
    
    # 等待一下，避免压力过大
    sleep 1
done

echo "迁移完成"
```

### 方案三：停机迁移

```bash
# 如果是大版本更新，涉及大量数据库变更
# 建议选择低峰期停机迁移

# 1. 停止服务
pm2 stop hrm-app

# 2. 备份数据库
pg_dump -h localhost -U hrm_user hrm_db > backup.sql

# 3. 执行迁移
pnpm drizzle-kit push

# 4. 验证数据
psql -h localhost -U hrm_user hrm_db -c "SELECT COUNT(*) FROM users"

# 5. 启动服务
pm2 start hrm-app
```

---

## 完整更新流程

### 流程图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           完整更新流程                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐                                                            │
│  │ 1. 检测变更  │                                                            │
│  └──────┬──────┘                                                            │
│         │                                                                   │
│         ▼                                                                   │
│  ┌─────────────────────────────────────────────────────────────────┐        │
│  │                    有依赖变更？                                   │        │
│  ├─────────────────────────────────────────────────────────────────┤        │
│  │   是 → 备份数据库 → pnpm install → pnpm build → 继续            │        │
│  │   否 → 继续                                                      │        │
│  └─────────────────────────────────────────────────────────────────┘        │
│         │                                                                   │
│         ▼                                                                   │
│  ┌─────────────────────────────────────────────────────────────────┐        │
│  │                    有数据库变更？                                 │        │
│  ├─────────────────────────────────────────────────────────────────┤        │
│  │   是 → 备份数据库 → 检查变更类型 → 执行迁移 → 验证 → 继续        │        │
│  │   否 → 继续                                                      │        │
│  └─────────────────────────────────────────────────────────────────┘        │
│         │                                                                   │
│         ▼                                                                   │
│  ┌─────────────┐                                                            │
│  │ 4. 重启服务  │                                                            │
│  └──────┬──────┘                                                            │
│         │                                                                   │
│         ▼                                                                   │
│  ┌─────────────┐                                                            │
│  │ 5. 验证功能  │                                                            │
│  └─────────────┘                                                            │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 自动化脚本

```bash
#!/bin/bash
# full-update.sh - 完整更新脚本（处理依赖和数据库变更）

set -e

PROJECT_DIR="/www/wwwroot/hrm-app"
BACKUP_DIR="/www/backup/hrm-app"
DATE=$(date +%Y%m%d_%H%M%S)

cd $PROJECT_DIR

echo "========== 1. 检测变更 =========="

# 拉取最新代码信息
git fetch origin
LOCAL=$(git rev-parse HEAD)
REMOTE=$(git rev-parse origin/main)

if [ "$LOCAL" = "$REMOTE" ]; then
    echo "✅ 已是最新版本"
    exit 0
fi

# 检测变更
DEP_CHANGED=$(git diff --name-only $LOCAL $REMOTE | grep -E "package\.json|pnpm-lock\.yaml" || true)
DB_CHANGED=$(git diff --name-only $LOCAL $REMOTE | grep -E "schema\.ts|drizzle/" || true)

echo "依赖变更: $([ -n "$DEP_CHANGED" ] && echo '是' || echo '否')"
echo "数据库变更: $([ -n "$DB_CHANGED" ] && echo '是' || echo '否')"

echo ""
echo "========== 2. 备份数据库 =========="

# 无论是否有变更，都备份数据库
BACKUP_FILE="$BACKUP_DIR/db_$DATE.sql"
mkdir -p $BACKUP_DIR
pg_dump -h localhost -U hrm_user hrm_db > $BACKUP_FILE
gzip $BACKUP_FILE
echo "✅ 数据库已备份: $BACKUP_FILE.gz"

echo ""
echo "========== 3. 更新代码 =========="

BEFORE=$(git rev-parse --short HEAD)
git pull origin main
AFTER=$(git rev-parse --short HEAD)
echo "✅ 代码已更新: $BEFORE → $AFTER"

echo ""
echo "========== 4. 处理依赖变更 =========="

if [ -n "$DEP_CHANGED" ]; then
    echo "⚠️  检测到依赖变更，执行 pnpm install..."
    pnpm install
    echo "✅ 依赖已更新"
else
    echo "✅ 无依赖变更，跳过"
fi

echo ""
echo "========== 5. 构建项目 =========="

pnpm build
echo "✅ 构建完成"

echo ""
echo "========== 6. 处理数据库变更 =========="

if [ -n "$DB_CHANGED" ]; then
    echo "⚠️  检测到数据库变更"
    
    # 显示变更内容
    echo "变更文件:"
    echo "$DB_CHANGED"
    
    # 生成迁移
    echo "生成迁移文件..."
    pnpm drizzle-kit generate
    
    # 显示迁移 SQL
    echo ""
    echo "迁移 SQL:"
    cat drizzle/*.sql 2>/dev/null || echo "无新迁移文件"
    
    echo ""
    read -p "确认执行迁移？(y/n) " CONFIRM
    
    if [ "$CONFIRM" = "y" ]; then
        pnpm drizzle-kit push
        echo "✅ 数据库迁移完成"
    else
        echo "❌ 取消迁移，退出"
        exit 1
    fi
else
    echo "✅ 无数据库变更，跳过"
fi

echo ""
echo "========== 7. 重启服务 =========="

pm2 restart hrm-app
echo "✅ 服务已重启"

echo ""
echo "========== 8. 验证 =========="

sleep 5

# 检查 PM2 状态
PM2_STATUS=$(pm2 jlist | jq -r '.[] | select(.name=="hrm-app") | .pm2_env.status')
if [ "$PM2_STATUS" = "online" ]; then
    echo "✅ PM2 状态: online"
else
    echo "❌ PM2 状态: $PM2_STATUS"
    exit 1
fi

# 检查 HTTP
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5000)
if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "307" ]; then
    echo "✅ HTTP 响应: $HTTP_CODE"
else
    echo "❌ HTTP 响应: $HTTP_CODE"
    exit 1
fi

echo ""
echo "========== 更新完成 =========="
echo "版本: $BEFORE → $AFTER"
echo "备份: $BACKUP_FILE.gz"
```

---

## 常见问题

### Q1: 依赖安装失败怎么办？

```bash
# 清理缓存重试
rm -rf node_modules pnpm-lock.yaml
pnpm store prune
pnpm install

# 如果是网络问题，使用镜像
pnpm config set registry https://registry.npmmirror.com
pnpm install
```

### Q2: 数据库迁移失败怎么办？

```bash
# 1. 检查错误信息
pnpm drizzle-kit push

# 2. 如果是连接问题，检查数据库状态
systemctl status postgresql
psql -h localhost -U hrm_user hrm_db -c "SELECT 1"

# 3. 如果是 SQL 错误，手动修复
psql -h localhost -U hrm_user hrm_db -c "你的修复SQL"

# 4. 回滚到备份
psql -h localhost -U hrm_user hrm_db < /www/backup/db_xxx.sql
```

### Q3: 如何回滚数据库迁移？

```bash
# 方式1: 从备份恢复
psql -h localhost -U hrm_user hrm_db < /www/backup/db_20260517.sql

# 方式2: 手动回滚 SQL
# 编写反向 SQL，例如：
# CREATE TABLE → DROP TABLE
# ADD COLUMN → DROP COLUMN
# CREATE INDEX → DROP INDEX
psql -h localhost -U hrm_user hrm_db -c "DROP TABLE IF EXISTS new_table;"
```

### Q4: 大表添加字段很慢怎么办？

```sql
-- PostgreSQL 11+ 支持 ADD COLUMN 不锁表
-- 但带默认值可能会慢

-- 方式1: 不带默认值（快）
ALTER TABLE large_table ADD COLUMN new_field varchar(100);

-- 方式2: 分批设置默认值
UPDATE large_table SET new_field = 'default' WHERE id < 100000;
UPDATE large_table SET new_field = 'default' WHERE id >= 100000 AND id < 200000;
-- ...

-- 方式3: 使用后台更新（不阻塞）
-- 先设置为 NULL，然后用任务队列慢慢更新
```

### Q5: 如何确认迁移是否成功？

```bash
# 检查表结构
psql -h localhost -U hrm_user hrm_db -c "\d table_name"

# 检查数据数量
psql -h localhost -U hrm_user hrm_db -c "SELECT COUNT(*) FROM table_name"

# 检查迁移记录（如果 drizzle 有记录表）
psql -h localhost -U hrm_user hrm_db -c "SELECT * FROM __drizzle_migrations"
```

### Q6: 生产环境迁移最佳实践？

1. **低峰期操作** - 选择用户最少的时段
2. **先在测试环境验证** - 确保迁移 SQL 正确
3. **完整备份** - 必须先备份
4. **分步执行** - 不要一次性执行多个大变更
5. **监控进程** - 迁移时监控数据库状态
6. **准备回滚方案** - 确保有备份可以回滚

---

## 检查清单

更新前检查：

- [ ] 已查看变更内容（git diff）
- [ ] 已备份数据库
- [ ] 已检查依赖变更（package.json）
- [ ] 已检查数据库变更（schema.ts）
- [ ] 已通知相关人员（如有停机）
- [ ] 已准备回滚方案

更新后验证：

- [ ] PM2 状态正常（online）
- [ ] HTTP 响应正常（200/307）
- [ ] 关键功能可访问
- [ ] 数据库表结构正确
- [ ] 数据数量正确
- [ ] 日志无错误