init

docs/MIGRATION_STRATEGY.md

@@ -0,0 +1,106 @@
+# 数据库迁移策略
+
+## 问题背景
+
+在容器化部署中，如果应用在数据库迁移完成之前启动，新版本的代码可能会尝试访问不存在的数据库字段或表，导致运行时错误。
+
+## 解决方案
+
+### 启动脚本自动迁移
+
+我们使用 Docker 启动脚本 (`docker-entrypoint.sh`) 在应用启动前自动执行数据库迁移：
+
+```
+容器启动 → 执行迁移 → 迁移成功 → 启动应用
+                ↓
+            迁移失败 → 容器退出 → 部署脚本检测到并回滚
+```
+
+### 工作流程
+
+1. **容器启动时**：`docker-entrypoint.sh` 脚本首先执行
+2. **执行迁移**：运行 `artisan migrate` 命令
+3. **迁移成功**：继续启动应用
+4. **迁移失败**：容器退出（exit 1），部署脚本检测到并回滚
+
+### 优势
+
+- ✅ **避免字段不存在错误** - 迁移在应用启动前完成
+- ✅ **自动执行** - 无需手动操作
+- ✅ **失败自动回滚** - 迁移失败时容器退出，部署脚本自动回滚
+- ✅ **幂等操作** - Goravel 的 migrate 是安全的，可以重复执行
+
+### 配置选项
+
+#### 跳过迁移（不推荐）
+
+如果需要在某些情况下跳过迁移：
+
+```bash
+# 在 docker-compose.yml 中设置环境变量
+environment:
+  - SKIP_MIGRATE=true
+```
+
+**注意：** 跳过迁移可能导致应用启动后访问不存在的字段而报错。
+
+### 部署脚本中的处理
+
+部署脚本 (`docker-blue-green.sh`) 会：
+
+1. 启动新版本容器
+2. 等待容器启动（包括迁移完成）
+3. 验证应用是否已启动（如果迁移失败，应用不会启动）
+4. 如果容器退出，自动检测并回滚
+
+### 健康检查
+
+健康检查的 `start_period` 设置为 60 秒，给迁移足够的时间完成：
+
+```yaml
+healthcheck:
+  start_period: 60s  # 等待迁移和应用启动
+```
+
+### 单独执行迁移
+
+如果需要单独执行迁移（不重启容器）：
+
+```bash
+# 在运行中的容器中执行迁移
+./scripts/deploy/migrate.sh
+```
+
+### 故障排查
+
+如果迁移失败：
+
+1. **查看容器日志**：
+   ```bash
+   docker logs goravel-admin-blue
+   ```
+
+2. **检查迁移状态**：
+   ```bash
+   docker exec goravel-admin-blue /www/main artisan migrate:status
+   ```
+
+3. **手动执行迁移**：
+   ```bash
+   docker exec goravel-admin-blue /www/main artisan migrate
+   ```
+
+### 最佳实践
+
+1. **迁移应该是幂等的** - 确保迁移可以安全地重复执行
+2. **测试迁移** - 在测试环境先测试迁移
+3. **备份数据库** - 在生产环境执行迁移前备份数据库
+4. **监控迁移** - 关注容器日志，确保迁移成功
+
+### 相关文件
+
+- `docker-entrypoint.sh` - 容器启动脚本
+- `Dockerfile` - Docker 镜像构建文件
+- `scripts/deploy/docker-blue-green.sh` - 部署脚本
+- `scripts/deploy/migrate.sh` - 单独执行迁移脚本
+