docker-local-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Local Development

Docker 本地开发

Run this skill in the main conversation. Do not spawn subagents, agent teams, or delegated parallel workers unless the user explicitly approves the proposed count and scope after being told that doing so can increase usage. Ask again before expanding an approved scope.

在主对话中运行此技能。除非用户在被告知该操作会增加使用量后，明确批准提议的数量和范围，否则不要生成子Agent、Agent团队或委托并行工作进程。在扩展已批准的范围前需再次询问用户。

Guardrails

防护规则

Design for local development. Keep production images, secrets, deployment, certificates, and runtime topology separate.
Inspect before asking questions or proposing services. Treat detection as evidence, not authority.
Ask only about unresolved choices that materially change the result. Group related questions and recommend a default; do not force a fixed questionnaire.
Preserve existing Docker files and unrelated working-tree changes. Show a semantic diff before replacing or materially restructuring a working stack. Never commit, reset, delete volumes, run migrations or seeds, or overwrite files unless the user authorized that action.
Generate only services the project uses or the user explicitly requests. A database is not mandatory when the project uses SQLite, a host service, or an external database.
Prefer direct foreground commands and one concern per service. Add Supervisor or PM2 only when the project already requires it or production-parity testing justifies it.
Prefer a stable top-level Compose
```
name:
```
and role-based service names. Do not set
```
container_name
```
by default because it prevents service scaling and creates cross-project collisions.
Select images by project constraints, team or production compatibility, trusted publisher, supported version, and architecture. Treat an already-downloaded image only as a tie-breaker. Avoid floating
```
latest
```
tags in generated files.
Publish only ports needed by the host. Bind local-only ports to
```
127.0.0.1
```
by default; keep databases, caches, SMTP, PHP-FPM, and internal APIs unexposed when possible.
Keep secrets out of committed files, generated documentation, command output, and frontend or proxy containers. Generate an ignored local env file plus a safe example when configuration is needed.

专为本地开发设计。将生产镜像、密钥、部署配置、证书以及运行时拓扑结构分开处理。
在提问或提议服务前先检查项目。将检测结果作为参考，而非绝对依据。
仅针对会实质性改变结果的未解决选项提问。将相关问题分组并推荐默认选项；不要强制使用固定问卷。
保留现有Docker文件和无关的工作树变更。在替换或实质性重构现有堆栈前，展示语义差异。除非用户授权，否则绝不要提交、重置、删除卷、运行迁移或数据填充，也不要覆盖文件。
仅生成项目实际使用或用户明确要求的服务。当项目使用SQLite、主机服务或外部数据库时，数据库并非必需组件。
优先使用直接前台命令，每个服务对应单一职责。仅当项目已需要或生产一致性测试有必要时，才添加Supervisor或PM2。
优先使用稳定的顶级Compose
```
name:
```
和基于角色的服务名称。默认不要设置
```
container_name
```
，因为这会阻止服务扩容并导致跨项目冲突。
根据项目约束、团队或生产兼容性、可信发布方、支持版本和架构选择镜像。仅将已下载的镜像作为平局决胜因素。在生成的文件中避免使用浮动的
```
latest
```
标签。
仅发布主机所需的端口。默认将仅本地访问的端口绑定到
```
127.0.0.1
```
；尽可能不暴露数据库、缓存、SMTP、PHP-FPM和内部API。
不要将密钥放入已提交的文件、生成的文档、命令输出以及前端或代理容器中。当需要配置时，生成一个被忽略的本地环境文件以及安全示例。

Workflow

工作流程

1. Inspect the project

1. 检查项目

Check Docker and Compose capabilities before selecting syntax:

bash

docker version
docker compose version

Inspect, when present:

compose.yaml

compose.yml

docker-compose*.yml

, and override files

```
Dockerfile*
```
,
```
.dockerignore
```
,
```
.devcontainer/
```
, Makefiles, and package scripts
application manifests, lockfiles, runtime-version files, env examples, and monorepo/workspace files
existing local proxy conventions, Compose project names, networks, volumes, and host port mappings
Git status and repository instructions before editing tracked files

Run stack detection from this skill directory, passing the project root:

bash

./scripts/detect-stack.sh "<project-root>"

The script emits JSON on stdout and diagnostics on stderr. Confirm uncertain findings from source files without printing secret values.

When Docker is available, optionally inspect local images and networks:

bash

./scripts/detect-images.sh
./scripts/detect-network.sh

Do not let cached images or a detected network override project compatibility or isolation requirements.

在选择语法前，先检查Docker和Compose的功能：

bash

docker version
docker compose version

若存在以下文件/目录，需进行检查：

compose.yaml

、

compose.yml

、

docker-compose*.yml

以及覆盖文件

```
Dockerfile*
```
、
```
.dockerignore
```
、
```
.devcontainer/
```
、Makefile和包脚本
应用清单、锁文件、运行时版本文件、环境示例以及单仓/工作区文件
现有本地代理约定、Compose项目名称、网络、卷和主机端口映射
在编辑已跟踪文件前，查看Git状态和仓库说明

从本技能目录运行堆栈检测脚本，传入项目根目录：

bash

./scripts/detect-stack.sh "<project-root>"

该脚本在标准输出中输出JSON，在标准错误中输出诊断信息。从源文件中确认不确定的发现，但不要打印敏感值。

当Docker可用时，可选择性检查本地镜像和网络：

bash

./scripts/detect-images.sh
./scripts/detect-network.sh

不要让缓存镜像或检测到的网络覆盖项目兼容性或隔离要求。

2. Resolve the design

2. 确定设计方案

Infer and summarize:

apps in scope, dev commands, internal ports, shared packages, and live-reload needs
runtime and package-manager versions from constraints and lockfiles
database, cache, queue, scheduler, mail, and debugging services actually used
existing reverse proxy, explicit
```
.localhost
```
hostnames, same-origin
```
/api
```
routing, and required host exposure
bind mounts versus Compose Watch; use Watch only when supported by the installed Compose version
merge versus focused repair versus replacement of existing Docker files

Ask for confirmation only where evidence is absent or conflicting. Typical high-impact questions are the apps to run, database parity, reverse-proxy integration, externally reachable ports, and whether an existing stack may be restructured.

推断并总结以下内容：

范围内的应用、开发命令、内部端口、共享包和热重载需求
从约束和锁文件中获取的运行时和包管理器版本
实际使用的数据库、缓存、队列、调度器、邮件和调试服务
现有反向代理、明确的
```
.localhost
```
主机名、同源
```
/api
```
路由以及所需的主机暴露配置
绑定挂载与Compose Watch；仅当已安装的Compose版本支持时才使用Watch
对现有Docker文件进行合并、针对性修复还是替换

仅在证据缺失或冲突时请求确认。典型的高影响问题包括要运行的应用、数据库一致性、反向代理集成、可外部访问的端口以及是否可以重构现有堆栈。

3. Load only relevant references

3. 仅加载相关参考资料

Need	Read
Detection rules and monorepo discovery	`references/tech-stack-detection.md`
Images, processes, dependencies, mounts, environment, Dockerfiles	`references/service-configuration-guide.md`
WordPress, Drupal, or Joomla	`references/cms-configuration-guide.md`
Ports, proxies, domains, networks, host access	`references/networking-ports-guide.md`
Existing Compose or Dockerfile changes	`references/merge-backup-strategy.md`
Readiness checks and smoke tests	`references/health-check-patterns.md`

Use assets as starting points, not immutable output. Remove unselected services and adapt placeholders, healthchecks, commands, paths, users, and versions to the detected project.

需求	参考文档
检测规则与单仓发现	`references/tech-stack-detection.md`
镜像、进程、依赖、挂载、环境、Dockerfile	`references/service-configuration-guide.md`
WordPress、Drupal或Joomla	`references/cms-configuration-guide.md`
端口、代理、域名、网络、主机访问	`references/networking-ports-guide.md`
现有Compose或Dockerfile变更	`references/merge-backup-strategy.md`
就绪检查与冒烟测试	`references/health-check-patterns.md`

将资源作为起点，而非不可变更的输出。移除未选择的服务，并根据检测到的项目调整占位符、健康检查、命令、路径、用户和版本。

4. Preview and generate

4. 预览与生成

Before writing, present:

files to create or modify
inferred services and versions
host ports and domains
source/dependency mount strategy
important changes to an existing stack

After approval where required, generate the smallest coherent setup:

local env example and ignored local env file when needed
dev Dockerfile or dev build target
```
.dockerignore
```
```
compose.yaml
```
without the obsolete top-level
```
version
```
selected proxy, process, and helper configuration
concise usage notes only when useful or requested

Prefer:

bind-mounted source with named dependency volumes for straightforward active development
Compose Watch with
```
sync
```
,
```
sync+restart
```
, or
```
rebuild
```
rules for large trees, native dependencies, or projects that benefit from granular sync
one-shot dependency installers only when they solve a real bind-mount or monorepo problem; mark them as expected to exit successfully
separate worker and scheduler services using the same image as the app
Compose profiles for optional debugging and administration tools
health-gated dependencies only when the dependency defines a valid healthcheck

Do not automatically run migrations, seeds, CMS installers, destructive cleanup, or database write tests.

在编写前，需展示：

要创建或修改的文件
推断出的服务和版本
主机端口和域名
源码/依赖挂载策略
对现有堆栈的重要变更

在需要时获得批准后，生成最小且连贯的配置：

必要时生成本地环境示例和被忽略的本地环境文件
开发环境Dockerfile或开发构建目标
```
.dockerignore
```
不含过时顶级
```
version
```
字段的
```
compose.yaml
```
选定的代理、进程和辅助配置
仅在有用或被请求时提供简洁的使用说明

优先选择：

绑定挂载源码，配合命名依赖卷以实现简单的主动开发
对大型目录、原生依赖或能从细粒度同步中受益的项目，使用带有
```
sync
```
、
```
sync+restart
```
或
```
rebuild
```
规则的Compose Watch
仅当能解决实际的绑定挂载或单仓问题时，才使用一次性依赖安装器；标记它们预期会成功退出
使用与应用相同镜像的独立工作进程和调度器服务
为可选的调试和管理工具使用Compose配置文件
仅当依赖定义了有效的健康检查时，才使用健康检查 gated 的依赖

不要自动运行迁移、数据填充、CMS安装程序、破坏性清理或数据库写入测试。

5. Verify

5. 验证

Run static checks first:

bash

docker compose config --quiet
docker build --check .

Use

docker build --check

only when the installed Docker version supports it. Then build and start after the user has approved container execution:

bash

docker compose build
docker compose up -d --wait
docker compose ps -a

--wait

is unavailable, start detached and poll declared healthchecks with a bounded timeout. Inspect logs for failed or restarting services.

Run the bundled checks when applicable:

bash

./scripts/health-check.sh
./scripts/db-test.sh          # connection/read-only query
./scripts/db-test.sh --crud   # explicit temporary-table CRUD check

Also run a stack-specific smoke check such as

php artisan about

wp core version

drush status

python manage.py check

, or the application's health endpoint. Verify hot reload by changing a harmless source file only when the user authorized runtime testing.

先运行静态检查：

bash

docker compose config --quiet
docker build --check .

仅当已安装的Docker版本支持时，才使用

docker build --check

。在用户批准容器执行后，再构建并启动：

bash

docker compose build
docker compose up -d --wait
docker compose ps -a

若

--wait

不可用，则以分离模式启动，并在有限超时内轮询已声明的健康检查。检查日志中是否有失败或重启的服务。

适用时运行捆绑的检查脚本：

bash

./scripts/health-check.sh
./scripts/db-test.sh          # 连接/只读查询
./scripts/db-test.sh --crud   # 显式临时表CRUD检查

同时运行堆栈特定的冒烟测试，例如

php artisan about

、

wp core version

、

drush status

、

python manage.py check

或应用的健康端点。仅当用户授权运行时测试时，才通过修改无害的源码文件来验证热重载功能。

6. Report

6. 报告

Report:

generated or modified files
selected services, versions, local URLs, and explicit host exposure
exact verification commands and results
expected stopped one-shot services
assumptions, skipped checks, and platform-specific limitations

Never include secret values in the report.

报告内容包括：

生成或修改的文件
选定的服务、版本、本地URL和明确的主机暴露配置
确切的验证命令和结果
预期会停止的一次性服务
假设条件、跳过的检查以及特定平台的限制

绝不要在报告中包含敏感值。

Host Port Registry

主机端口注册表

Persistent host-port tracking is optional. First check:

bash

PORT_REGISTRY_FILE="${DOCKER_LOCAL_DEV_PORT_REGISTRY:-${XDG_STATE_HOME:-$HOME/.local/state}/docker-local-dev/HOST_PORT_REGISTRY.md}"
test -f "$PORT_REGISTRY_FILE" && sed -n '1,220p' "$PORT_REGISTRY_FILE"

Before creating or refreshing the registry, explain the exact output path and scan root and obtain confirmation because the report may contain local project names and paths. Then run:

bash

node ./scripts/scan-host-ports.mjs --root "<approved-root>" --out "$PORT_REGISTRY_FILE" --yes

Treat registered ports as reserved even when no process is currently listening. For a single project without a registry, a live port check is sufficient.

持久化主机端口跟踪为可选功能。首先检查：

bash

PORT_REGISTRY_FILE="${DOCKER_LOCAL_DEV_PORT_REGISTRY:-${XDG_STATE_HOME:-$HOME/.local/state}/docker-local-dev/HOST_PORT_REGISTRY.md}"
test -f "$PORT_REGISTRY_FILE" && sed -n '1,220p' "$PORT_REGISTRY_FILE"

在创建或刷新注册表前，需说明确切的输出路径和扫描根目录并获得用户确认，因为报告可能包含本地项目名称和路径。然后运行：

bash

node ./scripts/scan-host-ports.mjs --root "<approved-root>" --out "$PORT_REGISTRY_FILE" --yes

即使当前没有进程在监听，已注册的端口也视为保留。对于没有注册表的单个项目，实时端口检查已足够。

Acceptance Criteria

验收标准

Generated Compose configuration parses without unresolved placeholders.
Selected images and commands match project constraints and contain no unreviewed floating tags.
App containers reach dependencies by Compose service name, not
```
localhost
```
.
Optional services are absent or profile-gated.
Host ports are minimal, conflict-free, and loopback-bound unless broader access was requested.
Healthchecks invoke commands available in their images and test readiness rather than process presence alone.
Source changes reload as intended; lockfile changes follow the documented install or rebuild path.
No secrets, production data, private domains, or unauthorized mutations appear in generated files or reports.

生成的Compose配置解析后无未解析的占位符。
选定的镜像和命令符合项目约束，且不含未审核的浮动标签。
应用容器通过Compose服务名称访问依赖，而非
```
localhost
```
。
可选服务不存在或通过配置文件 gated。
主机端口数量最少、无冲突，且默认绑定到回环地址，除非请求更广泛的访问权限。
健康检查调用镜像中可用的命令，测试就绪状态而非仅进程存在。
源码变更按预期重载；锁文件变更遵循文档化的安装或重建路径。
生成的文件或报告中不包含密钥、生产数据、私有域名或未授权的变更。