企业官网建设流程全解析

agent-deck 是一款面向 AI 编码 Agent 的终端会话管理器，一个 TUI 统一管理 Claude Code、Gemini CLI、OpenCode、Codex 等多个 AI Agent 会话。它内置了Docker 沙箱能力：只需一个--sandbox参数或勾选一个复选框，就能把 AI Agent 会话跑进隔离容器中——Agent 可以读写你的项目代码，却碰不到系统其余部分。本文将带你完成容器化会话的安全部署，包括沙箱镜像、凭据共享、资源限制与常见问题排查。

为什么要把 AI Agent 放进 Docker 沙箱

AI 编码 Agent 天生拥有完整的 shell 执行权，而它"不受约束"的方式正是你的主机系统：误删文件、失控的rm -rf、恶意依赖安装、fork 炸弹……都可能直接作用于宿主机。

Docker 沙箱的价值在于划定爆炸半径：

• 🛡️ Agent 的每次操作都被限制在容器内，宿主机系统目录只读保护
• 📁 项目目录以读写方式挂载到容器的/workspace，Agent 正常工作不受影响
• 🔐 默认不挂载 Docker socket，容器内的 Agent 无法反向控制宿主机 Docker 守护进程
• 🧹 会话删除时容器自动清理，不留残余状态

对于"让 Agent 帮我改代码"这类场景，沙箱是成本最低的保险。

三步启用沙箱会话

第一步：确认 Docker 环境

agent-deck 会在会话启动时检测 Docker。它需要两样东西：dockerCLI 在 PATH 中，且 Docker 守护进程正在运行。若缺失会看到明确的报错：

• docker CLI is not installed or not in PATH
• docker daemon is not running; start Docker and try again

检测逻辑见 internal/docker/detect.go，macOS / Linux / WSL 均可使用。

第二步：一键创建沙箱会话

命令行方式最简单，在项目目录执行：

agent-deck add --sandbox .

在 TUI 中，新建会话对话框里勾选 "Run in Docker sandbox" 复选框即可（该选项始终可见，Docker 可用性在会话启动时才真正校验）。

第三步：在 config.toml 中设为默认

如果你希望所有新会话默认进沙箱，编辑$XDG_CONFIG_HOME/agent-deck/config.toml（通常为~/.config/agent-deck/config.toml）：

[docker] default_enabled = true # 新会话默认勾选沙箱 auto_cleanup = true # 会话结束时自动删除容器（默认即 true）

CLI 参数优先级高于配置文件：--sandbox/--sandbox-image始终覆盖[docker]段的默认值。完整配置项参考 skills/agent-deck/references/sandbox.md。

官方沙箱镜像里有什么

agent-deck 自带一个预置镜像agent-deck-sandbox:latest，由 sandbox/Dockerfile 构建，基于 Ubuntu 24.04，开箱即含：

如需自己重建：

docker build -t agent-deck-sandbox sandbox/

安全加固机制：六道防线

容器创建参数在 internal/docker/docker.go 中硬编码，每一条都在缩小 Agent 能造成的破坏：

1. --cap-drop=ALL—— 丢弃全部 Linux capabilities，没有chown、net_raw、sys_admin等特权
2. --security-opt=no-new-privileges—— 禁止通过 setuid 二进制提权
3. --read-only—— 根文件系统只读，仅/tmp、工具缓存目录等通过 tmpfs 显式开放
4. --pids-limit=4096—— 限制进程数，fork 炸弹打不垮宿主机
5. 不挂载 Docker socket—— 代码注释中明确写着这是有意为之，防止容器逃逸到宿主机
6. 挂载路径黑名单—— 用户自定义卷会先解析符号链接再校验，/etc、/proc、/sys、Docker socket、~/.aws等敏感路径一律拒绝（见 internal/docker/config.go 中的 blocked 列表）

另外，容器以宿主机用户身份运行（--user uid:gid）而非 root，不是 root），同步配置文件时还会拒绝指向目录外部的符号链接，防止凭据被"偷渡"出同步边界——细节实现见 internal/docker/sandbox.go。

凭据共享：容器里不用重新登录

沙箱不等于"断网裸奔"。agent-deck 解决了容器化最大的痛点——认证：

• 每次会话启动，宿主机的工具配置（~/.claude/、~/.codex/、~/.gemini/等）会被同步到各工具配置目录下的sandbox/子目录，再挂载进容器
• 容器内产生的运行时状态自由写入，不会污染宿主机配置
• 多个沙箱容器共享同一套凭据，一次登录，处处可用

⚠️ 唯一例外：macOS 上 Claude Code 的登录存在 Keychain 中，而 OAuth 刷新令牌是单用途、每次刷新都会轮换的。若复制到容器会"分叉"宿主机的刷新链，导致宿主机被登出。因此 agent-deck 默认不复制它，而是让沙箱自己拥有独立登录：第一次沙箱会话内执行/login，之后凭据保存在~/.claude/sandbox/.credentials.json并被所有容器复用。无值守场景可改用claude setup-token生成的令牌，通过environment配置以CLAUDE_CODE_OAUTH_TOKEN传入。

自定义镜像与资源限制

扩展沙箱镜像

项目有特殊依赖（如额外 Python 包、数据库客户端）时，直接基于官方镜像扩展：

FROM agent-deck-sandbox:latest RUN apt-get update && apt-get install -y python3-venv

构建后通过agent-deck add --sandbox-image my-sandbox:latest .单会话使用，或在配置中设为默认：

[docker] default_image = "my-sandbox:latest"

限制 CPU 与内存

[docker] cpu_limit = "2.0" # 最多 2 核 memory_limit = "4g" # 内存上限 4 GB environment = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"] # 透传主机环境变量

其他实用项：

• mount_ssh = true—— 只读挂载~/.ssh，容器内可正常 git 操作
• volume_ignores = ["node_modules"]—— 大目录不进项目挂载，加快启动

容器生命周期与日常管理

容器命名规则为agent-deck-{会话标题}-{ID前8位}，例如agent-deck-my-refactor-a1b2c3d4，在docker ps中一眼可辨。完整生命周期：

1. 创建：会话启动时同步配置、创建/启动容器（幂等，已存在则复用）
2. 运行：宿主机 tmux 会话通过docker exec进入容器执行 Agent CLI
3. 排查：按E键进入容器内 shell，随时查看容器状态
4. 清理：删除会话时容器自动移除；auto_cleanup = false可保留容器用于调试

常见问题排查

容器被 OOM 杀掉：macOS 上 Docker 运行在固定内存的 Linux 虚拟机中（默认仅 2 GB）。在 Docker Desktop 的 Settings > Resources > Advanced 中调高内存（建议 8 GB+），并可用docker stats --no-stream确认MEM LIMIT列。

提示 Docker 不可用：确认docker命令在 PATH 中且守护进程已启动（WSL 环境下需先启动 WSL 中的 Docker）。

想重置沙箱状态：直接删除对应工具的sandbox/目录即可，下次会话启动会自动重建。

Web 视图使用：终端相关的环境变量（TERM、COLORTERM等）会自动透传保证渲染正常，API 密钥类变量需显式加入environment列表。

延伸阅读

• 完整沙箱参考：skills/agent-deck/references/sandbox.md
• 全部配置项（含[docker]段详解）：skills/agent-deck/references/config-reference.md
• 容器生命周期源码：internal/docker/docker.go
• 沙箱镜像定义：sandbox/Dockerfile
• README 中 Docker Sandbox 章节：README.md

给 AI Agent 一个容器，它就有了舞台；agent-deck 的 Docker 沙箱让"放开手脚干活"和"宿主机安全"第一次不必二选一。