# ECS 部署与回滚

## 目录（主机 `/data/spark-server`）

| 路径 | 说明 |
| --- | --- |
| `compose/docker-compose.yaml` | 服务定义 |
| `configs/config.yaml` | 运行配置（部署前会备份到 `configs/backup/`） |
| `images/spark-server-<release>.tar.gz` | 每次发布的镜像包（保留历史） |
| `images/spark-server.tar.gz` | 最近一次上传的包（兼容旧流程） |
| `releases/manifest.json` | 当前/上一版镜像 ID、release、时间 |
| `releases/previous_image_id` | 发布前 `latest` 的镜像 ID |
| Docker 标签 `spark-server:rollback` | 发布前从 `latest` 打的回滚点 |

## 发布

```bash
make deploy
# 或
bash deploy/docker/deploy.sh
```

流程概要：

1. 本地 `make image`，打标签 `spark-server:<git-sha>-<时间>` 与 `latest`
2. 上传镜像 tar、compose、config、nginx 片段
3. **在 load 新镜像前**，远端把当前 `spark-server:latest` 标为 `spark-server:rollback`，并备份 config
4. `docker load` → `compose up --force-recreate` → **migrate**
5. 轮询 `healthz` + `readyz`；失败则 **自动回滚** 到 `:rollback`（不跑 migrate）
6. 写 `releases/manifest.json`

环境变量：`SPARK_SSH_HOST`、`SPARK_SSH_KEY`、`SPARK_DATA_DIR`、`SPARK_RELEASE`（固定 release 名）、`SPARK_IMAGE_BASE`（默认 `spark-server`）、`SPARK_UPLOAD_CONFIG=1`（仅首次或刻意覆盖远端 `config.yaml`）。

生产密钥（SMTP、JWT 等）写在 ECS 上的 `/data/spark-server/configs/config.yaml`；部署默认不覆盖该文件。

## 回滚

**自动**：本次 `deploy.sh` 健康检查失败时会执行与手动回滚相同的步骤。

**手动**（上一版已成功跑过、且之后只做过一次 deploy）：

```bash
make deploy-rollback
# 或
bash deploy/docker/rollback.sh
```

将 `spark-server:rollback` 重新标为 `latest` 并重建容器。**不执行 migrate**。

### 限制（必读）

- **数据库迁移不可自动回滚**。回滚只恢复旧二进制；若新版本已执行 forward-only 迁移（如 `0018_square.sql`），旧进程通常仍能跑（新表闲置），但若迁移做了破坏性变更，需要 DBA 手工处理或从备份恢复库。
- 若连续多次 deploy，`:rollback` 只保留**上一次** deploy 前的镜像。更早版本用 `images/spark-server-<release>.tar.gz`：

  ```bash
  ssh ... 'docker load -i /data/spark-server/images/spark-server-<旧release>.tar.gz && \
    docker tag spark-server:latest spark-server:latest && \
    cd /data/spark-server/compose && docker compose up -d --force-recreate spark-server'
  ```

- 回滚 config：从 `configs/backup/config.yaml.<时间>` 拷回 `configs/config.yaml` 后再 `compose up`。

## 验证

```bash
curl -fsS http://127.0.0.1:18080/healthz   # 在 ECS 上
curl -fsS http://127.0.0.1:18080/readyz
```