主题

Dockerized dev

Dockerized dev 标记 Dockerfile、Compose 或 container build 是本地开发、集成验证或部署交付的一等路径。它不表示“仓库里偶然有 Dockerfile”,而是 Docker 影响运行环境、数据卷、端口、build args、嵌入式前端产物或 release artifact。

  • 服务
  • 运维

目录

Definition

Dockerized dev 标记 Dockerfile、Compose 或 container build 是本地开发、集成验证或部署交付的一等路径。它不表示“仓库里偶然有 Dockerfile”,而是 Docker 影响运行环境、数据卷、端口、build args、嵌入式前端产物或 release artifact。

这个 Topic 的判断重点是容器是否承载了可维护的运行真相:基础镜像、multi-stage build、前端 asset 注入、SQLite volume、env var、healthcheck、Compose service 名和 release artifact 都会影响后续 Agent 如何验证项目。若 Dockerfile 没有被 README、scripts、workflow 或部署文档消费,只能算待复核证据(projects/codex-vibe-monitor.md、projects/proxy-broker.md)。

When to use

当 Docker/Compose 是 README、scripts、CI、deploy 或 release workflow 的显式部分时使用。若 Dockerfile 只是旧实验文件、没有脚本/CI/deploy 证据,应先复核。

当项目需要稳定复现 runtime、隔离系统依赖、发布单镜像服务、在 Compose 中固定 DB/volume,或把 Web bundle 嵌进后端 binary/runtime 时,应命中本 Topic。单纯为了本地临时调试而留下的 Dockerfile 不够;必须能说明它在交付或验证链路中承担什么职责(projects/blog-26.md、projects/tavily-hikari.md)。

Habits / defaults

  • Rust + React 服务常见两阶段构建:Bun/Vite 先构建 web/dist,Rust stage 再 embed 或复制静态资产;projects/codex-vibe-monitor.md、projects/proxy-broker.md、projects/xp.md 都是这种形态。
  • Compose 中的端口、env 和 volume 是项目记忆;projects/tavily-hikari.md 保留 PROXY_PORT、PROXY_DB_PATH 和 data volume,projects/blog-26.md 保留 /app/data/sqlite.db。
  • 不要把容器默认端口当作 Codex 预览端口;交付 localhost 前仍要走全局端口租约。
  • Docker build gate 要同时验证前端资产和后端 binary,尤其是 embedded admin UI 服务。
  • 项目摘要应记录容器数据路径和 env var,而不是只写“支持 Docker”。SQLite、uploads、cache 或 API key 路径一旦漏记,迁移部署时最容易丢状态(projects/blog-26.md、projects/tavily-hikari.md)。
  • 对 Rust/React 服务,Dockerfile 的 base image、Bun/Rust 版本和 build args 是兼容性证据;遇到 glibc、OpenSSL 或静态资产问题时优先回读 Dockerfile,而不是只看 Cargo/npm manifest(projects/codex-vibe-monitor.md)。
  • 当 Compose 同时承载 Prometheus/Grafana/Tempo 等观测组件时,把 monitoring network、target service alias、named volume、只读 provisioning 和 host exposure 一起当作部署合同审查;不因为“只是监控”就跳过网络隔离和凭据边界(projects/codex-vibe-monitor.md、skills/style-playbook/references/topics/monitoring-dashboard/TOPIC.md)。
  • 观测 Compose 的验证应覆盖服务能否 provision、target 是否 fresh、dashboard/alert query 是否有正确样本,以及观测组件停止时业务服务是否仍可用;docker compose up 成功不等于整条观测链路有效(projects/codex-vibe-monitor.md)。
  • Compose 只表达编排和隔离,不替目标项目决定 metrics retention、trace window、sampling、容量或性能预算;这些参数必须由项目自己的证据和验收合同拥有。

Reference implementations

  • projects/blog-26.md:多 runtime 博客平台,Docker 数据路径和 build split 是交付 contract。
  • projects/dockrev.md:Docker/Compose update manager 本身以 Docker delivery 为核心。
  • projects/tavily-hikari.md:Compose 直接表达 MCP proxy 运行环境和 SQLite volume。
  • projects/codex-vibe-monitor.md:Dockerfile 固定 Bun/Rust/Debian 版本并注入 APP_EFFECTIVE_VERSION;ops/observability/compose.yml 另外展示观测服务的网络、volume、provisioning 和隔离边界,适合检查主服务交付与观测 sidecar 是否一致。
  • projects/xp.md:分布式服务的容器化边界与端口/状态管理更复杂,适合作为“不要只看 Dockerfile 是否存在”的反例式参考。

Failure modes

  • 只看到 Dockerfile 就打标签,可能把弃用文件提升成 Topic;要看 README/scripts/CI/deploy 是否引用。
  • 容器 build 成功但 web asset 版本未注入,会导致 UI 显示错误版本。
  • Compose volume/env 漏记会让 Agent 在迁移部署时丢数据。
  • 直接复用 Compose 暴露端口给用户预览,会绕过全局端口租约并可能撞到其他 worktree;owner-facing localhost 必须由当前工作区服务会话持有(projects/style-playbook-skills.md)。
  • 在容器里重新生成前端资产但没有把 build/version/env 注入记录到项目快照,会让站点显示与 release tag 不一致;需要把 Docker build args、web script 和 release workflow 一起审查(projects/codex-vibe-monitor.md)。
  • 把 Prometheus、Grafana 或 Tempo 的 host port、secret mount、volume 和 network 成员资格复制到另一个项目,可能造成暴露面或状态边界错误;迁移时只复用结构,重新审查 bind、身份、容量和通知策略(projects/codex-vibe-monitor.md、skills/style-playbook/references/topics/monitoring-dashboard/TOPIC.md)。
  • 只验证 Compose 服务启动,不验证 exporter scrape、freshness、dashboard provisioning 或业务降级语义,会把“容器健康”误报成“观测可用”;应使用项目自己的工具和 synthetic/acceptance 验证补齐证据(projects/codex-vibe-monitor.md)。

Evidence index

  • projects/blog-26.md
  • projects/dockrev.md
  • projects/tavily-hikari.md
  • projects/xp.md
  • projects/codex-vibe-monitor.md
  • ops/observability/compose.yml
  • ops/observability/prometheus.yml
  • ops/observability/grafana/provisioning/
  • skills/style-playbook/references/data/topic-candidates.json