🐳 Docker 沙箱
本页配置的是 Agent 执行命令的沙箱容器。先为组件开启 enableShellTool()，并按会话存储选择 JSON、Redis 或 MySQL。
# Docker 模式
先确认 Java 应用所在环境能执行 docker 并访问 daemon：
docker version
docker info
准备包含业务所需工具的镜像。仓库提供了包含 Python、Node.js 和常用命令的镜像，从 LiteFlow 仓库根目录构建：
./liteflow-agent/docker/sandbox/build.sh
构建后得到 liteflow-agent-sandbox:node22。也可使用自己的镜像，并在镜像中安装所需依赖。
使用 JSON 存储时，保留会话存储中的存储配置，添加以下执行配置即可：
liteflow.agent.harness.filesystem-backend=DOCKER
liteflow.agent.harness.docker.image=liteflow-agent-sandbox:node22
liteflow.agent.harness.docker.snapshot-root=./data/agent-snapshots
容器中的默认工作目录是 /workspace。默认每次 Agent 调用后回收容器，下一次从快照恢复业务文件。请持久保留 JSON 状态目录和快照目录。
使用 Redis／MySQL 存储时，只需配置后端和镜像：
liteflow.agent.harness.filesystem-backend=DOCKER
liteflow.agent.harness.docker.image=liteflow-agent-sandbox:node22
Redis／MySQL 会自动保存 Docker 快照，此时必须移除 docker.snapshot-root。Docker 模式不需要配置 harness.local.workspace-root。
三种存储的搭配关系如下：
| 会话存储 | 本地执行 | Docker 执行 |
|---|---|---|
| JSON | JSON 保存状态和文件，本地目录运行命令 | JSON 保存状态，snapshot-root 保存容器业务文件 |
| Redis | Redis 保存状态和文件，本地目录运行命令 | Redis 保存状态与容器快照 |
| MySQL | MySQL 保存状态和文件，本地目录运行命令 | MySQL 保存状态与容器快照 |
# Docker 常用调整
默认容器断网，内存上限 512 MiB，CPU 配额为 1。需要访问外部服务或运行较重的任务时，按需调整：
liteflow.agent.harness.docker.network=BRIDGE
liteflow.agent.harness.docker.memory-size-bytes=1073741824
liteflow.agent.harness.docker.cpu-count=2
模型 API、Java 工具和 MCP 客户端由 Java 应用调用；Docker 的网络设置控制容器内命令的网络。
多轮调用频繁、希望复用容器时设置：
liteflow.agent.harness.docker.lifecycle=SESSION_IDLE
liteflow.agent.harness.docker.idle-timeout=10m
liteflow.agent.harness.docker.max-cached-sandboxes=8
| 生命周期 | 行为 |
|---|---|
PER_CALL，默认 | 每次调用后保存快照并回收容器，适合及时释放资源 |
SESSION_IDLE | 复用同一会话的容器，空闲后回收，适合频繁续聊 |
JSON 使用 SESSION_IDLE 时必须配置快照目录；快照主要在正常回收时保存，进程被强杀可能丢失最近的文件变更。Redis／MySQL 模式会在每次调用结束时保存快照。两种模式的快照都只保存工作区文件，不保存进程、内存或工作区外临时安装的依赖。
Java 应用本身也运行在容器中时，仍需为它提供 Docker CLI 和 daemon 访问方式。LiteFlow 不会自动挂载 Docker socket。各部署实例应能取得同一业务镜像。
# 快照和部署边界
快照保存工作区文件，不保存运行中的进程、内存状态或工作区外安装的软件。Python、Node.js 和业务依赖应预先安装到镜像中。
当前属性配置不提供任意 volumes、端口发布或环境变量映射。静态资料投影是复制，并非宿主机挂载。Java 工具、模型请求和 MCP 客户端仍在 Java 应用中运行，容器网络配置只控制容器内命令。