119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
# PostgreSQL / MySQL Runtime Smoke 环境建议
|
||
|
||
## 结论
|
||
|
||
当前阶段的推荐方案是：**让 QA 在宿主机执行 smoke，但数据库仍使用仓库内的 Docker Compose 临时拉起**。
|
||
|
||
- 继续复用现有 `docker-compose.demo.yml`、bootstrap 脚本和 SQL fixtures
|
||
- 不依赖长期运行的宿主机 PostgreSQL / MySQL
|
||
- 不在当前阶段扩展 `local-db-codex` 运行时去支持 Docker
|
||
|
||
这条路径最符合当前项目状态：仓库里的 smoke 输入已经存在，真正缺的是一个有 Docker 的执行宿主，而不是新的产品代码或平台改造。
|
||
|
||
## 三种方案对比
|
||
|
||
### 方案 A：宿主机长期运行 PostgreSQL / MySQL
|
||
|
||
优点：
|
||
|
||
- 首次接入快
|
||
- QA 不需要每次拉起容器
|
||
|
||
缺点：
|
||
|
||
- 状态容易漂移，重复执行时很难保证数据库干净
|
||
- 需要长期维护端口、用户、权限和版本
|
||
- 一旦多人共用宿主机，测试数据会互相污染
|
||
- 更适合共享开发环境，不适合作为 release smoke 证据来源
|
||
|
||
结论：**可作为临时兜底，不作为推荐主路径。**
|
||
|
||
### 方案 B：为 `local-db-codex` 部署增加 Docker runtime 能力
|
||
|
||
优点：
|
||
|
||
- 从 agent 视角最方便，理论上可以把 smoke 也放回当前容器体系
|
||
- 后续若多个项目都依赖容器型集成测试，长期上限更高
|
||
|
||
缺点：
|
||
|
||
- 这是平台/安全/运维改造，不是当前仓库内的小改动
|
||
- 会引入容器嵌套、权限边界、镜像缓存、资源隔离等额外复杂度
|
||
- 当前项目的真实瓶颈是缺可执行宿主，不是缺应用层代码
|
||
|
||
结论：**不适合作为本阶段 unblock 手段，只在未来多个项目都提出同类需求时再立项。**
|
||
|
||
### 方案 C：QA runner 在宿主机执行，数据库通过 Docker Compose 临时拉起
|
||
|
||
优点：
|
||
|
||
- 直接复用现有仓库资产，落地最快
|
||
- 每次 `up` / `down -v` 都是干净环境，可重复性最好
|
||
- 不要求改 `local-db-codex` 平台
|
||
- 后续可平滑迁移到自托管 runner 或专用 QA 主机
|
||
|
||
缺点：
|
||
|
||
- 需要一台具备 Docker / `docker compose` 的宿主机
|
||
- 宿主机上仍需准备 Rust toolchain 或 release binary
|
||
|
||
结论：**这是当前推荐方案。**
|
||
|
||
## 推荐执行方式
|
||
|
||
### 宿主机要求
|
||
|
||
- Linux 或 macOS 宿主机
|
||
- 已安装 Docker 和 `docker compose`
|
||
- 可运行 Rust `cargo`，或已取得本仓库 release / debug 二进制
|
||
- 2026-03-26 当前 QA agent runner 不满足该要求：它有 `node v24.14.0` 和预编译 `target/release/dbtool`，但缺少 `docker` 与 `cargo`
|
||
|
||
### 使用步骤
|
||
|
||
1. 在宿主机拉取当前仓库代码并进入项目根目录
|
||
2. 准备 CLI：
|
||
- 开发验证：`cargo build`
|
||
- 或使用已生成的 `target/debug/dbtool` / `target/release/dbtool`
|
||
3. 导出密码环境变量：
|
||
|
||
```bash
|
||
export DBTOOL_PASSWORD=dbtool
|
||
```
|
||
|
||
4. 拉起 PostgreSQL / MySQL：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.demo.yml up -d postgres mysql
|
||
```
|
||
|
||
5. 导入 demo 数据：
|
||
|
||
```bash
|
||
./examples/scripts/bootstrap-postgres.sh
|
||
./examples/scripts/bootstrap-mysql.sh
|
||
```
|
||
|
||
6. 按 `SMOKE_RUNBOOK.md` 执行 PostgreSQL / MySQL 的 `connect` / `inspect` / `query` / `export`
|
||
7. 将结果回填到 `ACCEPTANCE_CHECKLIST.md`、`TEST_STRATEGY.md`、`PRE_RELEASE_CHECKLIST.md`
|
||
8. 清理环境：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.demo.yml down -v
|
||
```
|
||
|
||
## 团队职责
|
||
|
||
- 后端：维护 `docker-compose.demo.yml`、bootstrap 脚本、fixtures 和命令契约
|
||
- QA：在宿主机执行 smoke，沉淀证据和失败复现记录
|
||
- 前端：当前继续 gated，不参与此轮 runtime smoke
|
||
- CTO：维持方案边界；若没有 Docker-capable host，再升级为平台支持请求
|
||
|
||
## 风险与维护成本
|
||
|
||
- 宿主机不可用：需要指定一台固定 QA 主机或自托管 runner
|
||
- 二进制与文档漂移：QA 执行时必须绑定具体 commit 或 release artifact
|
||
- 端口冲突：优先使用专用 QA 主机；必要时再参数化 compose 端口
|
||
- 当前 runner 与目标宿主能力不一致：本地可继续复核 SQLite 与预编译二进制，但 PostgreSQL / MySQL Docker smoke 必须迁移到符合要求的宿主机
|
||
|
||
总体维护成本低，因为主路径复用仓库现有资产，不引入新的长期数据库运维负担，也不引入新的平台能力改造。
|