用途：在本地用 Docker 运行 ClickHouse，搭建快速迭代的开发闭环，适合本地开发环境搭建、schema 变更与查询调试、集成测试。
主要能力：提供基于 Docker Compose 的开发流程，包括自动迁移的初始化脚本、种子数据生成器、可复用的客户端单例，以及测试间清空表的集成测试框架。
使用方式：需已安装并运行 Docker 或 Docker Compose（docker info 成功），Node.js 18+ 及 @clickhouse/client 包，本地可写项目目录，无需云账号或网络。按七步构建：编写 docker-compose.yml 暴露 8123（HTTP）和 9000（原生 TCP），挂载 ./init-db 自动迁移与命名卷持久化；执行 docker compose up -d 并用 curl http://localhost:8123/ping 验证返回 Ok；编写 init-db/001-schema.sql 定义 CREATE DATABASE / CREATE TABLE ... ENGINE = MergeTree()；编写 scripts/seed.ts 通过 client.insert({ format: 'JSONEachRow' }) 批量插入；组织 init-db/、scripts/、src/、tests/ 及 .env.local / .env.example；编写 src/db.ts 暴露记忆化 getClient()；编写 vitest tests/setup.ts 在 beforeEach 中 TRUNCATE 表、afterAll 关闭客户端；在 package.json 添加 db:up、db:down、db:reset、db:seed、db:shell、test 脚本。
限制：仅本地开发，无外部 ClickHouse Cloud 服务；容器凭据在 docker-compose.yml 内联声明（CLICKHOUSE_USER: default，CLICKHOUSE_PASSWORD: dev_password），真实覆盖放 git 忽略的 .env.local，仅提交 .env.example，切勿在本地开发外复用 dev_password。常见错误：连接被拒需 docker compose up -d；READONLY 需设 CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1；Too many parts 需批量插入或调大 parts_to_throw_insert；内存超限需加 --memory 4g。其他细节暂未提供。