# Docker Run Env

> Runs commands in Docker when the host lacks the required runtime (Python, Node, Go, Java, etc.). Pulls appropriate images, configures China domestic mirrors for pip/npm/apt/yum before installing dependencies, and mounts the workspace. Use when a command fails due to missing tools, version mismatch, or when installing a full local runtime is unnecessary.

- Skill: `ech09527/docker-run-env` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ech09527/docker-run-env`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ech09527/docker-run-env/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ech09527 (https://skillmd.com/u/ech09527)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ech09527/docker-run-env

---


# Docker 运行环境回退

当任务需要执行命令，而当前主机缺少对应运行环境时，**优先用 Docker 拉取镜像完成任务**，不要在主机上安装完整运行时（除非用户明确要求）。

## 决策流程

1. **先探测主机**：尝试运行或检查所需命令/版本（`command -v`、`--version`）。
2. **缺环境则走 Docker**：不要反复在主机上 `apt install python3` / `brew install node` 等。
3. **选对镜像**：按项目/任务选择官方或 slim 镜像，版本与项目要求一致。
4. **挂载工作区**：始终 `-v "$(pwd):/workspace" -w /workspace`，保证读写项目文件。
5. **容器内装依赖前**：必须先配置国内镜像（见下文），**禁止**直接用容器默认源。
6. **一次性容器**：优先 `docker run --rm`；需要复用则用命名容器或 docker compose。

## 常用镜像映射

| 需求 | 镜像示例 |
|------|----------|
| Python | `python:3.12-slim`、`python:3.11-slim` |
| Node.js | `node:20-slim`、`node:18-slim` |
| Go | `golang:1.22` |
| Java | `eclipse-temurin:17-jdk` |
| Rust | `rust:1.77-slim` |
| 通用 Shell | `ubuntu:22.04`、`debian:bookworm-slim` |

拉取：`docker pull <image>`。若拉取慢，可说明正在使用默认 registry；必要时配置 Docker 镜像加速（daemon 级，非本 skill 范围）。

## 基本运行模板

```bash
docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  <image> \
  <command>
```

交互式或需环境变量时加 `-it`，需要网络加 `--network host`（仅当任务需要）。

## 国内镜像配置（装依赖前必做）

**规则**：凡在容器内执行 `pip install`、`npm install`、`apt-get install`、`yum install`、`apk add`、`cargo install` 等，必须先切换国内源。不要依赖容器自带默认 registry / apt / yum 源。

### pip

```bash
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
```

或单次安装：`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <pkg>`

### npm / pnpm / yarn

```bash
npm config set registry https://registry.npmmirror.com
# pnpm: pnpm config set registry https://registry.npmmirror.com
# yarn: yarn config set registry https://registry.npmmirror.com
```

### apt（Debian / Ubuntu）

在 `apt-get update` 之前替换 sources（按发行版选择路径）：

```bash
sed -i 's|deb.debian.org|mirrors.aliyun.com|g; s|security.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list
# Ubuntu 22.04 还可：
# sed -i 's|archive.ubuntu.com|mirrors.aliyun.com|g; s|security.ubuntu.com|mirrors.aliyun.com|g' /etc/apt/sources.list
apt-get update -y
```

### yum / dnf（CentOS / RHEL / Fedora）

```bash
# CentOS 7 示例
sed -i 's|^mirrorlist=|#mirrorlist=|g; s|^#baseurl=|baseurl=|g' /etc/yum.repos.d/CentOS-*.repo
sed -i 's|mirror.centos.org|mirrors.aliyun.com|g' /etc/yum.repos.d/CentOS-*.repo
yum makecache -y
```

### apk（Alpine）

```bash
sed -i 's|dl-cdn.alpinelinux.org|mirrors.aliyun.com|g' /etc/apk/repositories
apk update
```

### cargo（Rust）

```bash
export RUSTUP_DIST_SERVER=https://rsproxy.cn
export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
# 或写入 $HOME/.cargo/config.toml:
# [source.crates-io]
# replace-with = "rsproxy"
# [source.rsproxy]
# registry = "https://rsproxy.cn/crates.io-index"
```

更多镜像地址与发行版差异见 [mirrors-reference.md](mirrors-reference.md)。

## 典型工作流示例

### Python 项目跑脚本/测试

```bash
docker pull python:3.12-slim
docker run --rm -v "$(pwd):/workspace" -w /workspace python:3.12-slim bash -c '
  pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple &&
  pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn &&
  pip install -r requirements.txt &&
  python script.py
'
```

### Node 项目

```bash
docker pull node:20-slim
docker run --rm -v "$(pwd):/workspace" -w /workspace node:20-slim bash -c '
  npm config set registry https://registry.npmmirror.com &&
  npm ci &&
  npm test
'
```

### 仅需一次性命令、先装系统包

```bash
docker run --rm -v "$(pwd):/workspace" -w /workspace ubuntu:22.04 bash -c '
  sed -i "s|archive.ubuntu.com|mirrors.aliyun.com|g; s|security.ubuntu.com|mirrors.aliyun.com|g" /etc/apt/sources.list &&
  apt-get update -y &&
  apt-get install -y curl &&
  curl --version
'
```

## 注意事项

- **权限**：容器内生成文件可能属 root；若影响后续主机操作，可用 `-u "$(id -u):$(id -g)"`。
- **长期任务**：构建镜像比每次 `run` 装依赖更高效时，可写临时 Dockerfile，仍在 Dockerfile 里配置国内源。
- **GPU / 特殊硬件**：需 `--gpus all` 或专用镜像（如 `nvidia/cuda`），本 skill 不替代硬件文档。
- **报告用户**：说明因主机缺环境已改用 Docker，并注明镜像名与关键命令。

## 附加资源

- 各工具国内镜像备选列表：[mirrors-reference.md](mirrors-reference.md)