7.0 KiB
7.0 KiB
PostgreSQL / MySQL Runtime Smoke 环境建议
结论
当前阶段的目标推荐方案是：让 QA agent 直接在升级后的 local-db-codex 容器内执行 smoke，并通过挂载宿主机 Docker daemon、Docker 配置、Cargo 与 Rustup 目录来复用宿主能力。
- 继续复用现有
docker-compose.demo.yml、bootstrap 脚本和 SQL fixtures - 不依赖长期运行的宿主机 PostgreSQL / MySQL
- 不再要求 QA 手动切回宿主机执行
- 将 Docker、Rust、Cargo mirror、Docker registry mirror 的能力统一沉淀到容器运行时
在该部署升级完成前，宿主机执行仍然是可用 fallback；但后续默认路径应转向容器内 agent 自行完成 smoke。
2026-03-26 的 CMP-17 已证明该路径可以成立：宿主机 PostgreSQL / MySQL smoke 已执行完成，因此“当前 QA runner 无 Docker”只代表本 agent 本地限制，不再代表方案无效。
三种方案对比
方案 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
结论：作为 fallback 可用，但不再是长期目标路径。
方案 D：升级 local-db-codex，让 agent 在容器内复用宿主机 Docker 和 Rust
优点：
- agent 可直接在容器内执行 PostgreSQL / MySQL Docker-backed smoke
- 后续每个功能实现后的测试路径一致，不需要在人和 agent 之间切换执行环境
- 继续复用宿主机 Docker daemon 的镜像缓存、registry mirror 和权限体系
- 继续复用宿主机 Rust toolchain、Cargo 配置和 crates mirror 配置
缺点：
- 需要维护容器与宿主机之间的挂载关系
- Docker socket 暴露会提升容器能力边界，需明确接受该风险
- 宿主机 Docker / Rust 环境本身出问题时，容器内 agent 会继承同样问题
结论：这是后续迭代的目标方案。
推荐执行方式
容器化 QA runner 要求
deploy/local-db-codex已升级，挂载：- 宿主机 Docker socket
- 宿主机 Docker config
- 宿主机 Cargo home
- 宿主机 Rustup home
- 容器内可直接运行：
dockercargorustc
- 宿主机 Docker daemon 已配置好 registry mirror（如有）
- 宿主机 Cargo / Rustup mirror 配置已就绪（如有）
使用步骤
- 启动升级后的
local-db-codex部署 - 进入 agent 所在容器运行环境，确认
docker、cargo、rustc可用 - 在工作区准备 CLI：
- 开发验证：
cargo build - 或使用已生成的
target/debug/dbtool/target/release/dbtool
- 开发验证：
- 导出密码环境变量：
export DBTOOL_PASSWORD=dbtool
- 拉起 PostgreSQL / MySQL：
docker compose -f docker-compose.demo.yml up -d postgres mysql
- 导入 demo 数据：
./examples/scripts/bootstrap-postgres.sh
./examples/scripts/bootstrap-mysql.sh
- 按
SMOKE_RUNBOOK.md执行 PostgreSQL / MySQL 的 happy-path；按HOST_FAILURE_PATH_CHECKLIST.md执行 failure-path - 将结果回填到
ACCEPTANCE_CHECKLIST.md、TEST_STRATEGY.md、PRE_RELEASE_CHECKLIST.md - 清理环境：
docker compose -f docker-compose.demo.yml down -v
Failure-path 执行入口
- PostgreSQL / MySQL happy-path 继续使用
SMOKE_RUNBOOK.md - PostgreSQL / MySQL failure-path 统一使用
HOST_FAILURE_PATH_CHECKLIST.md - 证据记录格式继续以
FAILURE_PATH_EVIDENCE_TEMPLATE.md为准
2026-03-28 当前容器化 runner 观察
- QA runner 已可访问 Docker daemon，但当前仍缺
docker compose子命令。 - QA runner 不能直接访问
127.0.0.1:55432/53306，也不能直接访问 demo 数据库容器 IP。 - 当前有效补充路径是：
- 复用已运行的
dbtool-cli-v1-postgres-1/dbtool-cli-v1-mysql-1 - 用
docker exec直接导入 PostgreSQL / MySQL demo 数据 - 创建 sidecar container 并加入
dbtool-cli-v1_default网络
- 复用已运行的
- 在 sidecar container 内执行
dbtool，主机名使用postgres/mysql
这条 sidecar network execution 路径在 2026-03-28 当前 heartbeat 已被直接验证，可用于继续补 PostgreSQL / MySQL failure-path 证据。
为减少重复手工步骤，当前仓库已提供：
scripts/qa/run-failure-path-evidence-sidecar.sh ./target/release/dbtool ./tmp/failure-path-evidence
这条脚本化路径会自动完成：
- PostgreSQL / MySQL demo 数据重导入
- sidecar container 创建与清理
- sidecar 内 failure-path helper 执行
- 证据文件回传到本地输出目录
团队职责
- 后端：维护
docker-compose.demo.yml、bootstrap 脚本、fixtures、命令契约和容器内 smoke 兼容性 - QA：优先在容器内 agent 运行环境执行 smoke，沉淀证据和失败复现记录
- 前端：当前继续 gated，不参与此轮 runtime smoke
- CTO：维持方案边界，并确保
local-db-codex能长期承载容器内 smoke
风险与维护成本
- Docker socket 暴露：容器获得了较强的宿主机控制能力，必须明确接受这一安全边界。
- 宿主机 Docker / Rust 环境漂移：容器会继承宿主机配置，出现问题时必须同时排查宿主机。
- 二进制与文档漂移：QA 执行时必须绑定具体 commit 或 release artifact。
- 端口冲突：必要时继续参数化 compose 端口。
- 当前已知结论：宿主机 patched-run 已确认 MySQL 中文与 emoji 输出正常，问题根因收敛到 bootstrap/import 字符集路径；后续需要把这类验证稳定迁入容器内 smoke 路径。
总体维护成本可控，因为主路径继续复用仓库现有 smoke 资产，只是把执行宿主从人工宿主机切换成可复用宿主能力的 Paperclip 容器。