devcontainer.json 的 "service" 字段必须严格匹配 docker-compose.yml 中 services 下的键名（大小写敏感、冒号后无空格），否则报“Service 'xxx' not found”；同时需共用自定义 bridge 网络并配置 healthcheck，确保容器间 DNS 解析与服务就绪。

devcontainer.json 的 service 字段必须严格匹配 docker-compose.yml 中的 service 名

VSCode 启动 Dev Container 时，会把 devcontainer.json 里的 service 值（比如 "app"）当作容器名，去 docker-compose.yml 的 services 下找对应键。填成 "application" 或 "my-app"，就会报 Service 'xxx' not found。

常见错误现象：

• VSCode 提示 “Failed to launch dev container: Service 'app' not found”
• 容器启动后，app 容器里 ping db 或 curl http://redis:6379 失败，提示 Unknown host

确保：

• devcontainer.json 中 "service": "app"
• docker-compose.yml 顶层有 services:，且下级第一级 key 确实是 app:（注意冒号和缩进）
• 路径正确：如果 docker-compose.yml 在项目根目录，devcontainer.json 中写 "dockerComposeFile": "docker-compose.yml"；如果它在 .devcontainer/ 下，则写 "dockerComposeFile": "docker-compose.yml"（此时路径相对于 .devcontainer/）

所有服务必须共用同一个自定义 bridge 网络，否则容器名无法解析

Docker 默认的 bridge 网络不支持通过 service 名互相访问——它只支持 IP 地址通信。depends_on 仅控制启动顺序，不解决 DNS 解析问题。

必须显式定义网络并挂载所有服务：

• 在 docker-compose.yml 顶层加 networks: 块，例如：

  networks:<br>  app-net:<br>    driver: bridge<br>    ipam:<br>      config:<br>        - subnet: 172.20.0.0/16

• 每个 service（app、db、redis）都必须声明 networks: [app-net]
• 不要用 host 或省略 networks 字段——那样容器间只能靠 IP，db 这个 hostname 就永远解析不了

验证方式：进 app 容器执行 nslookup db 或 getent hosts db，应返回类似 172.20.0.2 db 的结果。

app 容器启动时连接 db 报 Connection refused？不是 DNS 问题，是服务没 ready

DNS 解析成功 ≠ 服务已监听。VSCode 只等容器状态变成 running，不会等 PostgreSQL 初始化完数据库、Redis 加载完配置。

OpenClaw Docker Setup

在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...

下载

必须给依赖服务加 healthcheck，并在 app 的 depends_on 中引用它：

• 在 db service 下加：

  healthcheck:<br>  test: ["CMD-SHELL", "pg_isready -U postgres -d myapp_dev"]<br>  interval: 30s<br>  timeout: 10s<br>  retries: 5

• 在 app service 的 depends_on 中写：

  depends_on:<br>  db:<br>    condition: service_healthy

• 同时确保 db 的 environment 里设置了 POSTGRES_DB 和 POSTGRES_PASSWORD，否则 pg_isready 会失败

不加 healthcheck 的后果：Node 应用一启动就尝试 require('pg').connect('postgres://postgres:password@db:5432/myapp_dev')，大概率触发 connect ECONNREFUSED 172.20.0.2:5432。

workspaceFolder 和 volume 挂载路径不一致会导致 Node require 找不到模块

VSCode 用 workspaceFolder 决定工作区根路径，而 Node 运行时依赖 require 的相对路径。两者不一致时，require('./config/db') 可能报 Cannot find module。

典型错配：

• devcontainer.json 中 "workspaceFolder": "/workspace"
• docker-compose.yml 中 volumes: ["../src:/app/src"] —— 但代码实际在 /app/src，而 VSCode 认为根是 /workspace

解决方案：

• 统一路径：推荐全部用 /workspace，即 volumes: ["..:/workspace"]，然后 workspaceFolder 也设为 /workspace
• 或改用 build + context，避免硬编码路径；Dockerfile 中 WORKDIR /workspace，再 COPY . .
• 检查 Node 启动命令是否带 --cwd /workspace，否则 process.cwd() 可能是 / 或 /home/node

最隐蔽的问题是：本地 npm install 装的包在宿主机 node_modules，但容器里没挂载、也没重新装，require('express') 就直接崩了——务必在容器内运行 npm ci 或挂载 node_modules（不推荐）。