本目录包含测试用 Dockerfile，供 testcontainers 自动化测试和手动验证使用。
镜像不包含 peeka 代码，只提供基础运行环境。代码通过 volume mount 挂载，镜像内设置 PYTHONPATH=/app，
无需 pip install 即可直接使用。只要镜像存在就能反映最新代码，无需重新构建。
| 类型 | Dockerfile 命名 | 镜像标签命名 |
|---|---|---|
| 基础镜像 | base.Dockerfile-<version> |
peeka-base:<version> |
| 测试镜像 | test.Dockerfile-<version> |
peeka-test:<version> |
构建顺序: 对于 Python < 3.14 需要分两阶段构建：
- 先构建基础镜像（包含 Python + GDB + python3-dbg）
- 再构建测试镜像（基于基础镜像，安装 textual 依赖）
Python 3.14 使用官方基础镜像直接构建测试镜像，无需单独基础镜像。
| 镜像标签 | Dockerfile | Python | 附加机制 | 用途 |
|---|---|---|---|---|
peeka-base:3.8 |
base.Dockerfile-3.8 |
3.8 | GDB + ptrace | 基础镜像（Python 3.8 + gdb + python3-dbg） |
peeka-test:3.8 |
test.Dockerfile-3.8 |
3.8 | GDB + ptrace | 完整 E2E 测试（Python 3.8） |
peeka-base:3.12 |
base.Dockerfile-3.12 |
3.12 | GDB + ptrace | 基础镜像（Python 3.12 + gdb + python3-dbg） |
peeka-test:3.12 |
test.Dockerfile-3.12 |
3.12 | GDB + ptrace | 完整 E2E 测试（Python 3.12） |
peeka-test:3.14 |
test.Dockerfile-3.14 |
3.14 | PEP 768 sys.remote_exec |
原生 PEP 768 测试 |
所有镜像均使用 USTC 镜像源（中科大）加速 apt 和 pip 下载。
从项目根目录执行：
# 1. 构建基础镜像
docker build --network=host -f docker/base.Dockerfile-3.8 -t peeka-base:3.8 .
docker build --network=host -f docker/base.Dockerfile-3.12 -t peeka-base:3.12 .
# 2. 构建测试镜像
docker build --network=host -f docker/test.Dockerfile-3.8 -t peeka-test:3.8 .
docker build --network=host -f docker/test.Dockerfile-3.12 -t peeka-test:3.12 .
docker build --network=host -f docker/test.Dockerfile-3.14 -t peeka-test:3.14 .# Python 3.8 (需要先构建基础)
docker build --network=host -f docker/base.Dockerfile-3.8 -t peeka-base:3.8 .
docker build --network=host -f docker/test.Dockerfile-3.8 -t peeka-test:3.8 .
# Python 3.12 (需要先构建基础)
docker build --network=host -f docker/base.Dockerfile-3.12 -t peeka-base:3.12 .
docker build --network=host -f docker/test.Dockerfile-3.12 -t peeka-test:3.12 .
# Python 3.14 (直接构建，无需单独基础)
docker build --network=host -f docker/test.Dockerfile-3.14 -t peeka-test:3.14 .docker build --network=host --no-cache -f docker/base.Dockerfile-<version> -t peeka-base:<version> .
docker build --network=host --no-cache -f docker/test.Dockerfile-<version> -t peeka-test:<version> .# Python 3.8 GDB 容器（挂载宿主机代码目录到 /app）
docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
-v $(pwd):/app peeka-test:3.8
# Python 3.12 GDB 容器
docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
-v $(pwd):/app peeka-test:3.12
# PEP 768 Python 3.14 容器
docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
-v $(pwd):/app peeka-test:3.14容器测试位于 tests/container/，由 pytest + testcontainers 自动管理容器生命周期。
conftest.py 会自动挂载宿主机项目目录到 /app，通过 PYTHONPATH=/app 直接使用挂载的代码。
# 运行全部容器测试
uv run pytest tests/container/test_attach.py -v -m container --timeout=180
# 仅运行指定 Python 版本测试
uv run pytest tests/container/test_attach.py -v -k "py38"
uv run pytest tests/container/test_attach.py -v -k "gdb"
uv run pytest tests/container/test_attach.py -v -k "py314"# 启动测试目标进程
python examples/demo.py --mode loop &
# 附加到进程
python -m peeka.cli attach $(pgrep -f demo.py)
# 观测函数调用
python -m peeka.cli watch 'demo.Calculator.add' -n 5
# 追踪调用栈
python -m peeka.cli stack 'demo.Calculator.add' -n 2
# 搜索类
python -m peeka.cli sc 'Calculator'构建时必须使用 --network=host。原因：本机运行 Clash 代理（127.0.0.1:7897），
DNS 会将域名解析为 198.18.x.x 段的 fake-IP，Docker 隔离网络无法路由到 Clash。
使用 --network=host 共享宿主机网络栈即可正常访问 USTC 镜像源。
注意：Dockerfile 内部不使用任何代理环境变量（http_proxy/https_proxy），
仅通过 USTC 镜像源直接下载。
所有测试镜像已在 Dockerfile 中内置 TERM=xterm-256color 和 COLORTERM=truecolor，
docker exec 进入容器后 TUI 可直接使用，无需额外设置。
docker/
├── base.Dockerfile-3.8 # 基础镜像（Python 3.8 + gdb + python3-dbg）
├── base.Dockerfile-3.12 # 基础镜像（Python 3.12 + gdb + python3-dbg）
├── test.Dockerfile-3.8 # 测试镜像（基于 peeka-base:3.8）
├── test.Dockerfile-3.12 # 测试镜像（基于 peeka-base:3.12）
├── test.Dockerfile-3.14 # 测试镜像（Python 3.14 原生 PEP 768）
├── restart-demo.sh # 容器启动脚本：自动运行 demo 进程
└── README.md