dbtool-cli-v1/QA_RUNTIME_ENVIRONMENT.md

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
• 容器内可直接运行：
  • docker
  • cargo
  • rustc
• 宿主机 Docker daemon 已配置好 registry mirror（如有）
• 宿主机 Cargo / Rustup mirror 配置已就绪（如有）

使用步骤

1. 启动升级后的 local-db-codex 部署
2. 进入 agent 所在容器运行环境，确认 docker、cargo、rustc 可用
3. 在工作区准备 CLI：
   • 开发验证：cargo build
   • 或使用已生成的 target/debug/dbtool / target/release/dbtool
4. 导出密码环境变量：

export DBTOOL_PASSWORD=dbtool
export DBTOOL_POSTGRES_ADMIN_PASSWORD=dbtoolroot

5. 拉起 PostgreSQL / MySQL：

docker compose -f docker-compose.demo.yml up -d postgres mysql

6. 导入 demo 数据：

./examples/scripts/bootstrap-postgres.sh
./examples/scripts/bootstrap-mysql.sh

如果本机 PostgreSQL demo 容器早于本轮权限修正创建，先清旧卷再重建：

docker compose -f docker-compose.demo.yml down -v
docker compose -f docker-compose.demo.yml up -d postgres mysql
./examples/scripts/bootstrap-postgres.sh
./examples/scripts/bootstrap-mysql.sh

PostgreSQL demo 当前权限边界：

• postgres / dbtoolroot：只用于 seed、restricted probe 建立与清理
• dbtool / dbtool：QA 与 TUI/CLI live 路径使用的非超级用户

可先验证 dbtool 不再是超级用户：

PGPASSWORD="$DBTOOL_POSTGRES_ADMIN_PASSWORD" \
psql -h 127.0.0.1 -p 55432 -U postgres -d dbtool_demo \
  -c "select rolname, rolsuper, rolcreaterole, rolcreatedb from pg_roles where rolname='dbtool';"

PostgreSQL restricted-schema 最小复验步骤：

PGPASSWORD="$DBTOOL_POSTGRES_ADMIN_PASSWORD" \
psql -h 127.0.0.1 -p 55432 -U postgres -d dbtool_demo <<'SQL'
drop schema if exists restricted_probe cascade;
create schema restricted_probe;
create table restricted_probe.audit_log (
  id bigint primary key,
  note text not null
);
insert into restricted_probe.audit_log values (1, 'hidden from dbtool');
revoke all on schema restricted_probe from public;
revoke all on all tables in schema restricted_probe from public;
revoke all on schema restricted_probe from dbtool;
revoke all on all tables in schema restricted_probe from dbtool;
SQL

export DBTOOL_PASSWORD=dbtool
cargo run -p dbtool-cli -- inspect --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD
cargo run -p dbtool-cli -- inspect --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --schema restricted_probe

预期：

• root inspect 出现 restricted_probe [restricted]
• 显式 --schema restricted_probe 返回 restricted inspect error，而不是 empty tables

清理：

PGPASSWORD="$DBTOOL_POSTGRES_ADMIN_PASSWORD" \
psql -h 127.0.0.1 -p 55432 -U postgres -d dbtool_demo \
  -c "drop schema if exists restricted_probe cascade;"

7. 按 SMOKE_RUNBOOK.md 执行 PostgreSQL / MySQL 的 happy-path；按 HOST_FAILURE_PATH_CHECKLIST.md 执行 failure-path
8. 将结果回填到 ACCEPTANCE_CHECKLIST.md、TEST_STRATEGY.md、PRE_RELEASE_CHECKLIST.md
9. 清理环境：

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 为准
• 在发起宿主机或 sidecar live 执行前，先跑离线夹具收敛 helper / wrapper 契约：

scripts/qa/test-failure-path-fixtures.sh

• 若只想检查单一路径，可改跑：

scripts/qa/test-failure-path-fixtures.sh format
scripts/qa/test-failure-path-fixtures.sh sidecar

2026-03-28 当前容器化 runner 观察

• QA runner 已可访问 Docker daemon，但当前仍缺 docker compose 子命令。
• QA runner 不能直接访问 127.0.0.1:55432/53306，也不能直接访问 demo 数据库容器 IP。
• 当前有效补充路径是：
  1. 复用已运行的 dbtool-cli-v1-postgres-1 / dbtool-cli-v1-mysql-1
  2. 用 docker exec 直接导入 PostgreSQL / MySQL demo 数据
  3. 创建 sidecar container 并加入 dbtool-cli-v1_default 网络

4. 在 sidecar container 内执行 dbtool，默认主机名跟随 QA_POSTGRES_CONTAINER / QA_MYSQL_CONTAINER（当前默认是 dbtool-cli-v1-postgres-1 / dbtool-cli-v1-mysql-1）

这条 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 执行
• 证据文件回传到本地输出目录
• 当前 PostgreSQL sidecar 重导入默认使用 postgres / dbtoolroot；若宿主机 demo 管理员身份被改写，可改传 QA_POSTGRES_ADMIN_USER / QA_POSTGRES_ADMIN_PASSWORD

团队职责

• 后端：维护 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 容器。