feat(usable): package gui-host validation snapshot
Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Paperclip CTO
@@ -2,13 +2,16 @@
|
||||
|
||||
## 结论
|
||||
|
||||
当前阶段的推荐方案是：**让 QA 在宿主机执行 smoke，但数据库仍使用仓库内的 Docker Compose 临时拉起**。
|
||||
当前阶段的目标推荐方案是：**让 QA agent 直接在升级后的 `local-db-codex` 容器内执行 smoke，并通过挂载宿主机 Docker daemon、Docker 配置、Cargo 与 Rustup 目录来复用宿主能力**。
|
||||
|
||||
- 继续复用现有 `docker-compose.demo.yml`、bootstrap 脚本和 SQL fixtures
|
||||
- 不依赖长期运行的宿主机 PostgreSQL / MySQL
|
||||
- 不在当前阶段扩展 `local-db-codex` 运行时去支持 Docker
|
||||
- 不再要求 QA 手动切回宿主机执行
|
||||
- 将 Docker、Rust、Cargo mirror、Docker registry mirror 的能力统一沉淀到容器运行时
|
||||
|
||||
这条路径最符合当前项目状态：仓库里的 smoke 输入已经存在，真正缺的是一个有 Docker 的执行宿主，而不是新的产品代码或平台改造。
|
||||
在该部署升级完成前，宿主机执行仍然是可用 fallback；但后续默认路径应转向容器内 agent 自行完成 smoke。
|
||||
|
||||
2026-03-26 的 [CMP-17](/CMP/issues/CMP-17#comment-0cd53e93-25a5-456b-8dba-31ea098c2aa8) 已证明该路径可以成立：宿主机 PostgreSQL / MySQL smoke 已执行完成，因此“当前 QA runner 无 Docker”只代表本 agent 本地限制，不再代表方案无效。
|
||||
|
||||
## 三种方案对比
|
||||
|
||||
@@ -57,62 +60,119 @@
|
||||
- 需要一台具备 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 要求
|
||||
|
||||
- Linux 或 macOS 宿主机
|
||||
- 已安装 Docker 和 `docker compose`
|
||||
- 可运行 Rust `cargo`，或已取得本仓库 release / debug 二进制
|
||||
- 2026-03-26 当前 QA agent runner 不满足该要求：它有 `node v24.14.0` 和预编译 `target/release/dbtool`，但缺少 `docker` 与 `cargo`
|
||||
- `deploy/local-db-codex` 已升级，挂载：
|
||||
- 宿主机 Docker socket
|
||||
- 宿主机 Docker config
|
||||
- 宿主机 Cargo home
|
||||
- 宿主机 Rustup home
|
||||
- 容器内可直接运行：
|
||||
- `docker`
|
||||
- `cargo`
|
||||
- `rustc`
|
||||
- 宿主机 Docker daemon 已配置好 registry mirror（如有）
|
||||
- 宿主机 Cargo / Rustup mirror 配置已就绪（如有）
|
||||
|
||||
### 使用步骤
|
||||
|
||||
1. 在宿主机拉取当前仓库代码并进入项目根目录
|
||||
2. 准备 CLI：
|
||||
1. 启动升级后的 `local-db-codex` 部署
|
||||
2. 进入 agent 所在容器运行环境，确认 `docker`、`cargo`、`rustc` 可用
|
||||
3. 在工作区准备 CLI：
|
||||
- 开发验证：`cargo build`
|
||||
- 或使用已生成的 `target/debug/dbtool` / `target/release/dbtool`
|
||||
3. 导出密码环境变量：
|
||||
4. 导出密码环境变量：
|
||||
|
||||
```bash
|
||||
export DBTOOL_PASSWORD=dbtool
|
||||
```
|
||||
|
||||
4. 拉起 PostgreSQL / MySQL：
|
||||
5. 拉起 PostgreSQL / MySQL：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.demo.yml up -d postgres mysql
|
||||
```
|
||||
|
||||
5. 导入 demo 数据：
|
||||
6. 导入 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. 清理环境：
|
||||
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. 清理环境：
|
||||
|
||||
```bash
|
||||
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。
|
||||
- 当前有效补充路径是：
|
||||
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`，主机名使用 `postgres` / `mysql`
|
||||
|
||||
这条 sidecar network execution 路径在 2026-03-28 当前 heartbeat 已被直接验证，可用于继续补 PostgreSQL / MySQL failure-path 证据。
|
||||
|
||||
为减少重复手工步骤，当前仓库已提供：
|
||||
|
||||
```bash
|
||||
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 和命令契约
|
||||
- QA：在宿主机执行 smoke，沉淀证据和失败复现记录
|
||||
- 后端：维护 `docker-compose.demo.yml`、bootstrap 脚本、fixtures、命令契约和容器内 smoke 兼容性
|
||||
- QA：优先在容器内 agent 运行环境执行 smoke，沉淀证据和失败复现记录
|
||||
- 前端：当前继续 gated，不参与此轮 runtime smoke
|
||||
- CTO：维持方案边界；若没有 Docker-capable host，再升级为平台支持请求
|
||||
- CTO：维持方案边界，并确保 `local-db-codex` 能长期承载容器内 smoke
|
||||
|
||||
## 风险与维护成本
|
||||
|
||||
- 宿主机不可用：需要指定一台固定 QA 主机或自托管 runner
|
||||
- 二进制与文档漂移：QA 执行时必须绑定具体 commit 或 release artifact
|
||||
- 端口冲突：优先使用专用 QA 主机；必要时再参数化 compose 端口
|
||||
- 当前 runner 与目标宿主能力不一致：本地可继续复核 SQLite 与预编译二进制，但 PostgreSQL / MySQL Docker smoke 必须迁移到符合要求的宿主机
|
||||
- Docker socket 暴露：容器获得了较强的宿主机控制能力，必须明确接受这一安全边界。
|
||||
- 宿主机 Docker / Rust 环境漂移：容器会继承宿主机配置，出现问题时必须同时排查宿主机。
|
||||
- 二进制与文档漂移：QA 执行时必须绑定具体 commit 或 release artifact。
|
||||
- 端口冲突：必要时继续参数化 compose 端口。
|
||||
- 当前已知结论：宿主机 patched-run 已确认 MySQL 中文与 emoji 输出正常，问题根因收敛到 bootstrap/import 字符集路径；后续需要把这类验证稳定迁入容器内 smoke 路径。
|
||||
|
||||
总体维护成本低，因为主路径复用仓库现有资产，不引入新的长期数据库运维负担，也不引入新的平台能力改造。
|
||||
总体维护成本可控，因为主路径继续复用仓库现有 smoke 资产，只是把执行宿主从人工宿主机切换成可复用宿主能力的 Paperclip 容器。
|
||||
|
||||
Reference in New Issue
Block a user