probably-rendering-one-more-pixel-tonight/docs/docker-build-cache.md

Docker 构建上下文与缓存

入口与忽略规则

所有 CI 构建命令都在仓库根目录使用 . 作为 context，包括以 -f 选择的子项目 Dockerfile。统一使用根 .dockerignore，递归排除依赖目录、Git 元数据、本机环境文件、编译输出、测试证据及缓存；保留 .env.example 供 Compose 校验使用。

普通的子目录 .dockerignore 不会自动叠加到根 context。当前 runner 使用 legacy builder，不依赖 Dockerfile 专属忽略文件或 BuildKit cache mount。若以后改用子目录 context，必须同时调整共享包与跨应用文件的输入路径，不能只在子目录添加忽略文件。

依赖层与源码层

• Wiki 的根 Dockerfile 是实际 CI 入口，apps/waterfall-wiki/Dockerfile 是对应副本，两者的功能内容保持同步；根文件额外保留镜像生命周期标签。
• 统一 Web 应用先根据锁文件与 workspace 配置执行 pnpm fetch，再复制清单并 pnpm install --offline --frozen-lockfile。修改 scripts 或品牌源码不会使下载层失效；基础镜像、pnpm 版本、平台或配置变化，以及 Docker 缓存清除仍可能要求重新下载。
• Python 从 pyproject.toml 读取固定运行依赖与构建后端要求，在独立依赖阶段安装。源码阶段安装当前包并运行单测，最终镜像仅继承系统运行环境并复制已验证的虚拟环境，不携带应用源码目录和测试目录。虚拟环境仍包含 pip 和构建后端，未声称完全剥离构建工具。
• 品牌包只作为 workspace 依赖随 Web 应用构建，不提供独立 Dockerfile、镜像构建工作流或常驻服务。专用品牌检查已停止自动运行，保留测试脚本供明确需要时在远程执行。
• 不因共享包缓存命中而漏掉消费者：品牌变更需触发 统一应用 PR 检查和 main 发布。根忽略规则变化也触发相关检查。

验证与限制

构建、打包与产物验证只在已确认的 ces-control runner 执行。Web 与 Python 的工作分支 push/PR 仅运行轻量静态检查；类型检查、单元测试、编译、镜像构建和部署都只在 main push 执行。不再单独构建品牌检查镜像。

本次没有升级 Docker builder，也没有承诺消除 legacy builder 的镜像层提交耗时；缓存层调整后的实际收益需比较后续 CI 日志。源码变化仍需构建，当前采用持久测试基础设施；本次应用合并仍保留完整集成验证，按影响范围选择测试留作后续优化。

本机不新增 Dev Containers/Tilt 启动方式；这类方案需要单独确认本地运行和编译授权。