功能:executor 镜像分层(基础 M + 技能系统层派生镜像)+ 启动前 skills 初始化

- executor/Dockerfile 改多阶段:base 为基础镜像 M(长期不变,系统工具 + 预烘 Python 包);skills 阶段 = M + 技能系统层依赖(构建期跑各 install.sh,apt 等系统包持久且对命令只读)。build context 改为仓库根,用 .dockerignore 只放行 executor/ 与 skills/。

- 新增 agent-executor-init 一次性服务(executor/init-skills.js,与 core ensureDeps 同 hash/marker 格式):启动前把 requirements.txt(pip --target 共享 deps)与 install.sh 资产落到宿主 ./skills;只挂 ./skills、无特权、read_only,跑完退出;executor depends_on service_completed_successfully。

- 运行期 skills 仍 :ro;M 不变、skills 可变、命令写不了共享系统层,会话隔离保持。

- 实测:构建 stage 两个 install.sh 正常;init 幂等跳过/按需重跑(install.sh 与 pip 分支各验一次);executor 重建后 ReadonlyRootfs=true、/run tmpfs、core 到 executor 健康、run_skill 端到端正常。docs/ARCHITECTURE.md 与 skills/README.md 同步。
This commit is contained in:
2026-09-11 23:35:17 +08:00
parent 2f96414c49
commit dbc1783b3e
6 changed files with 181 additions and 9 deletions
+10
View File
@@ -0,0 +1,10 @@
# executor 派生镜像的构建上下文 = 仓库根(compose 里 context: .),
# 但只需要 executor/ 与 skills/ 两份源码;其余(含 node_modules、任务数据、密钥)全部排除。
*
!executor
!skills
# 技能目录里运行期生成 / 体积大的部分不进构建上下文
skills/deps
skills/*/.deps_installed
skills/*/fonts
skills/*/__pycache__
+36 -1
View File
@@ -26,10 +26,45 @@ services:
- my-app-network - my-app-network
- agent-internal - agent-internal
# 技能准备(一次性,跑完退出):把各技能的“运行期可变”依赖落到宿主 ./skills——
# requirements.txt → pip --target 共享 deps 目录;install.sh → 技能资产(如字体提取)。
# 系统层依赖(apt 等)不在这里做,由镜像的 skills 构建阶段烘进(才持久且对命令只读)。
# 只挂 ./skills(不挂 ./tasks),因此看不到任何会话数据;read_only 根 + tmpfs /tmp。
agent-executor-init:
build:
context: .
dockerfile: executor/Dockerfile
target: skills
image: agent-agent-executor-skills
container_name: agent-executor-init
restart: "no"
command: ["node", "init-skills.js"]
read_only: true
tmpfs:
- /tmp
volumes:
- ./skills:/workspace/skills
environment:
- HOME=/tmp
- TMPDIR=/tmp
- PYTHONDONTWRITEBYTECODE=1
- TZ=Asia/Shanghai
networks:
- agent-internal
agent-executor: agent-executor:
build: ./executor # M' = M + 技能系统层依赖(executor/Dockerfile 的 skills 阶段)。
# 管理员增删/改动 skills 后:docker compose build agent-executor 重建这层,M 不动。
build:
context: .
dockerfile: executor/Dockerfile
target: skills
image: agent-agent-executor-skills
container_name: agent-executor container_name: agent-executor
restart: unless-stopped restart: unless-stopped
depends_on:
agent-executor-init:
condition: service_completed_successfully
expose: expose:
- "9000" - "9000"
volumes: volumes:
+4 -1
View File
@@ -111,6 +111,8 @@ graph LR
- nginx-proxy 前置时**必须 `proxy_buffering off`**,否则 SSE 流被缓冲。详见 `docs/DEPLOY.md`。 - nginx-proxy 前置时**必须 `proxy_buffering off`**,否则 SSE 流被缓冲。详见 `docs/DEPLOY.md`。
- Core 通过环境变量 `EXECUTOR_URL` / `EXECUTOR_TOKEN` 注入 executor 端点(也可用 `config.yml` 的 `executor` 段覆盖)。**token 从 `.env` 读取**(compose 变量替换 `${EXECUTOR_TOKEN:?...}`,未设置直接报错,杜绝静默无鉴权);`.env` 已 gitignore,模板见 `.env.example`,生成:`openssl rand -hex 32`。 - Core 通过环境变量 `EXECUTOR_URL` / `EXECUTOR_TOKEN` 注入 executor 端点(也可用 `config.yml` 的 `executor` 段覆盖)。**token 从 `.env` 读取**(compose 变量替换 `${EXECUTOR_TOKEN:?...}`,未设置直接报错,杜绝静默无鉴权);`.env` 已 gitignore,模板见 `.env.example`,生成:`openssl rand -hex 32`。
- Executor **拒绝来自容器自身(回环/本机网卡)的 `/exec`**:隔离只 unshare mount+pid,命令与 executor 同 net ns,能打到 `127.0.0.1:9000`;据此即使 token 泄漏也无法在会话内调用 `/exec` 越权读他人会话(core 在另一容器,不受影响)。本机集成测试用 `EXECUTOR_ALLOW_LOCAL_ORIGIN=1` 放行,生产不得设置。 - Executor **拒绝来自容器自身(回环/本机网卡)的 `/exec`**:隔离只 unshare mount+pid,命令与 executor 同 net ns,能打到 `127.0.0.1:9000`;据此即使 token 泄漏也无法在会话内调用 `/exec` 越权读他人会话(core 在另一容器,不受影响)。本机集成测试用 `EXECUTOR_ALLOW_LOCAL_ORIGIN=1` 放行,生产不得设置。
- Executor 镜像分两阶段(`executor/Dockerfile`):`base` = M(长期不变,仅系统工具 + 预烘 Python 包),`skills` = M' = M + 技能“系统层”依赖。compose 用 `build.target: skills`、上下文为仓库根(`.dockerignore` 只放行 `executor/`、`skills/`)。管理员增删/改动 skills 后 `docker compose build agent-executor` 重建 M',M 不动。
- `agent-executor-init` 在 executor 启动前一次性执行(`executor/init-skills.js`):把各技能 `requirements.txt`(`pip --target` 共享 deps)与 `install.sh` 生成的资产落到宿主 `./skills`,跑完即退出;只挂 `./skills`(不挂 `./tasks`,看不到会话数据)、无特权、`read_only`。executor `depends_on` 其 `service_completed_successfully`。
- Executor 在 compose 里加了 cgroup/ulimit 护栏(`cpus 2.0` / `mem_limit 2g` / `pids_limit 512` / `ulimits.fsize 2G`)——详见 `executor/server.js` 头注释。 - Executor 在 compose 里加了 cgroup/ulimit 护栏(`cpus 2.0` / `mem_limit 2g` / `pids_limit 512` / `ulimits.fsize 2G`)——详见 `executor/server.js` 头注释。
--- ---
@@ -272,6 +274,7 @@ stateDiagram-v2
- `runSkill` 流程:`skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`) → `ensureDeps` → 选 `python3 run.py '<json>'` 或 `bash run.sh '<json>'` → `runEntry`。 - `runSkill` 流程:`skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`) → `ensureDeps` → 选 `python3 run.py '<json>'` 或 `bash run.sh '<json>'` → `runEntry`。
- **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`),env 只传 `PYTHONPATH=<deps_root>`。 - **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`),env 只传 `PYTHONPATH=<deps_root>`。
- **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/<sid>` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。`ensureDeps` 的安装命令仍传技能目录(依赖是技能私有资源,且 skills 为 `:ro`,运行期不应安装)。 - **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/<sid>` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。`ensureDeps` 的安装命令仍传技能目录(依赖是技能私有资源,且 skills 为 `:ro`,运行期不应安装)。
- **依赖就绪时机**:系统层依赖(apt 等,`install.sh` 的副作用)在镜像 `skills` 阶段烘入 M';pip 依赖与技能资产(如字体提取)在服务启动前由 `agent-executor-init` 落到宿主 `./skills`(hash/marker 与 `ensureDeps` 同格式)。运行期 skills `:ro`,`runSkill` 的 `ensureDeps` 命中 marker 即跳过;若运行期经 UI 改了依赖,需 `docker compose up -d` 重新 init(否则该技能会报依赖安装失败)。
### 5.6 `remote-exec.js` —— 远端 executor 客户端 ### 5.6 `remote-exec.js` —— 远端 executor 客户端
@@ -328,7 +331,7 @@ stateDiagram-v2
## 6. agent-executor 容器 ## 6. agent-executor 容器
单文件 Node HTTP 服务(`executor/server.js`),零依赖。端点: 单文件 Node HTTP 服务(`executor/server.js`),零依赖。镜像 `executor/Dockerfile` 分两阶段:`base`(M,长期不变)与 `skills`(M' = M + 技能系统层依赖,管理员改 skills 后重建)。端点:
- `GET /health` → `{ok, running:[{id, pid, cwd, started_at}]}`,免鉴权。 - `GET /health` → `{ok, running:[{id, pid, cwd, started_at}]}`,免鉴权。
- `POST /exec` body `{command, cwd(必填), timeout_ms?, max_output_chars?, env?}` → SSE 流: - `POST /exec` body `{command, cwd(必填), timeout_ms?, max_output_chars?, env?}` → SSE 流:
+31 -3
View File
@@ -1,4 +1,9 @@
FROM node:20-slim # =============================================================================
# 基础阶段 M —— 长期不变:node + 系统工具 + 预烘 Python 依赖。
# 只承载“系统层”,不含任何技能专属依赖。构建上下文为仓库根(compose: context: .),
# 故 COPY 路径带 executor/ 前缀。
# =============================================================================
FROM node:20-slim AS base
# MPLBACKEND=Agg:让 matplotlib 使用非交互式后端,避免缺少显示设备报错。 # MPLBACKEND=Agg:让 matplotlib 使用非交互式后端,避免缺少显示设备报错。
# PYTHONUNBUFFERED=1:实时输出日志。 # PYTHONUNBUFFERED=1:实时输出日志。
@@ -36,7 +41,9 @@ RUN pip3 install --no-cache-dir --break-system-packages \
# ---- executor 服务(零依赖单文件,仅 Node 内置 http)---- # ---- executor 服务(零依赖单文件,仅 Node 内置 http)----
WORKDIR /app WORKDIR /app
COPY server.js ./ COPY executor/server.js ./
# 技能依赖准备脚本:由 agent-executor-init 服务在启动前执行(pip/资产,无特权)
COPY executor/init-skills.js ./
# 隔离用的空挂载点:必须存在且为空。 # 隔离用的空挂载点:必须存在且为空。
# /workspace/tasks —— wrapper 用 tmpfs 遮盖它,再 bind 回当前 session(虚拟任务根) # /workspace/tasks —— wrapper 用 tmpfs 遮盖它,再 bind 回当前 session(虚拟任务根)
@@ -49,7 +56,7 @@ RUN mkdir -p /workspace/tasks /workspace/scratch \
EXPOSE 9000 EXPOSE 9000
# EXECUTOR_LOG_LEVEL:日志等级 debug|info|warn|error|none(默认 info)。 # EXECUTOR_LOG_LEVEL:日志等级 debug|info|warn|error|none(默认 info)。
# debug 会把与 core 的完整交互逐条打印(请求行、/exec 请求体、每条 SSE 帧、JSON 响应)。 # debug 会把与 core 的完整交互逐条打印(请求、/exec 请求体、每条 SSE 帧、JSON 响应)。
# EXECUTOR_ISOLATION_BASE:宿主机 tasks 在本容器内的真实挂载点,必须与 compose 的 volumes 一致。 # EXECUTOR_ISOLATION_BASE:宿主机 tasks 在本容器内的真实挂载点,必须与 compose 的 volumes 一致。
ENV PORT=9000 \ ENV PORT=9000 \
EXECUTOR_ROOTS=/workspace \ EXECUTOR_ROOTS=/workspace \
@@ -60,3 +67,24 @@ ENV PORT=9000 \
EXECUTOR_LOG_LEVEL=info EXECUTOR_LOG_LEVEL=info
CMD ["node", "server.js"] CMD ["node", "server.js"]
# =============================================================================
# 派生阶段 M' = M + 技能的“系统层”依赖(管理员增删/改动 skills 后重建这一层,M 不动)。
#
# 只取 install.sh 对系统层(/usr、/var)的作用——这部分必须烘进镜像才持久、
# 且对命令只读(会话之间互不影响)。pip 依赖与技能资产(如字体提取)写出的文件
# 随构建层丢弃,它们由 agent-executor-init 落到宿主 ./skills(重启不丢)。
#
# install.sh 属“管理员审核过的资产”;构建期以 root 执行,故仍需保持其最小化。
# compose 通过 build.target: skills 选用本阶段。
# =============================================================================
FROM base AS skills
ENV DEBIAN_FRONTEND=noninteractive
COPY skills /tmp/skills
RUN for d in /tmp/skills/*/; do \
if [ -f "$d/install.sh" ]; then \
echo "[skills] install.sh: $d"; \
( cd "$d" && bash install.sh ) || echo "[skills][WARN] install.sh 失败(系统依赖可能缺失):$d"; \
fi; \
done; \
rm -rf /tmp/skills
+92
View File
@@ -0,0 +1,92 @@
#!/usr/bin/env node
// agent-executor-init:executor 启动前的一次性技能准备。
//
// 只处理“运行期可变”的依赖:
// - requirements.txt → python3 -m pip install --target <skills>/deps -r ...
// - install.sh → 在技能目录执行(生成技能自带资产,如从系统字体提取 cjk.ttf)
// 系统层依赖(apt 等)不在这里做——那部分由派生镜像 M'(executor/Dockerfile 的 skills 阶段)
// 承载,才持久且对命令只读。
//
// 无特权:不做任何 mount;只挂 ./skills(不挂 ./tasks),因此看不到任何会话数据。
// 幂等:按 requirements.txt/install.sh 的内容 hash(与 core 的 ensureDeps 同格式)比对
// .deps_installed,命中即跳过。
// 退出码恒为 0:单个技能失败只告警,不阻断 executor 启动(该技能暂不可用,其余照常)。
'use strict';
const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const { spawnSync } = require('child_process');
const ROOT = process.env.SKILLS_ROOT || '/workspace/skills';
const DEPS = path.join(ROOT, 'deps');
function log() {
const args = Array.prototype.slice.call(arguments);
console.log('[' + new Date().toISOString() + '] [skills-init]', ...args);
}
// 与 core(app/server/tools/skills.js 的 hashFile/ensureDeps)保持完全一致的 hash 与 marker 格式。
function hashFile(p) {
try { return crypto.createHash('sha1').update(fs.readFileSync(p)).digest('hex'); } catch (_) { return ''; }
}
function run(cmd, args, cwd) {
log('run:', cmd, args.join(' '), '(cwd=' + cwd + ')');
const r = spawnSync(cmd, args, { cwd, stdio: 'inherit', env: process.env });
if (r.error) { log('spawn 失败:' + r.error.message); return false; }
return r.status === 0;
}
function initSkill(name) {
const dir = path.join(ROOT, name);
const reqPath = path.join(dir, 'requirements.txt');
const installPath = path.join(dir, 'install.sh');
const hasReq = fs.existsSync(reqPath);
const hasInstall = fs.existsSync(installPath);
if (!hasReq && !hasInstall) return;
const need = 'req:' + hashFile(reqPath) + '|install:' + hashFile(installPath);
const markerPath = path.join(dir, '.deps_installed');
try {
if (fs.existsSync(markerPath) && fs.readFileSync(markerPath, 'utf8') === need) {
log('跳过(已就绪):' + name);
return;
}
} catch (_) { /* marker 读失败按未就绪处理 */ }
log('初始化:' + name);
let ok = true;
try {
if (hasReq) {
fs.mkdirSync(DEPS, { recursive: true });
ok = run('python3', ['-m', 'pip', 'install', '--no-cache-dir', '--target', DEPS, '-r', reqPath], dir) && ok;
}
if (hasInstall) {
ok = run('bash', ['install.sh'], dir) && ok;
}
} catch (e) {
log('异常:' + name + ':' + e.message);
ok = false;
}
if (ok) {
fs.writeFileSync(markerPath, need, 'utf8');
log('就绪:' + name);
} else {
log('失败(不写 marker,下次启动重试):' + name);
}
}
(function main() {
try {
if (!fs.existsSync(ROOT)) { log('技能根目录不存在,跳过:' + ROOT); return; }
const names = fs.readdirSync(ROOT, { withFileTypes: true })
.filter(e => e.isDirectory() && e.name !== 'deps')
.map(e => e.name)
.sort();
log('技能根=' + ROOT + ',共 ' + names.length + ' 个技能');
for (const n of names) initSkill(n);
log('初始化结束');
} catch (e) {
log('顶层异常(忽略,不阻断 executor):' + e.message);
}
})();
+8 -4
View File
@@ -128,7 +128,7 @@ def main():
### 5.1 Python 依赖 ### 5.1 Python 依赖
在技能目录下放置 `requirements.txt` 文件,列出所有需要的第三方包。Skill Manager 会**自动安装**这些依赖到共享的 `deps` 目录(位于技能根目录下的 `deps/`),并通过 `PYTHONPATH` 注入运行环境。 在技能目录下放置 `requirements.txt` 文件,列出所有需要的第三方包。服务启动前,`agent-executor-init`(`executor/init-skills.js`)会**自动安装**这些依赖到共享的 `deps` 目录(技能根目录下的 `deps/`),运行期通过 `PYTHONPATH` 注入;结果按 `requirements.txt` 的 hash 缓存(`.deps_installed`),未变化则跳过。
示例 `requirements.txt`: 示例 `requirements.txt`:
@@ -139,10 +139,14 @@ beautifulsoup4==4.11.1
- 依赖安装使用 `pip install --target`,不会污染系统全局。 - 依赖安装使用 `pip install --target`,不会污染系统全局。
- 所有技能**共享**同一个 `deps` 目录,请注意版本冲突(后装的覆盖先装的)。建议锁定精确版本。 - 所有技能**共享**同一个 `deps` 目录,请注意版本冲突(后装的覆盖先装的)。建议锁定精确版本。
- 运行期 skills 目录只读;若上线后经 UI 改了 `requirements.txt`,需重启(`docker compose up -d`)触发重新 init,否则该技能会因依赖未就绪而失败。
### 5.2 系统级依赖 ### 5.2 系统级依赖
如果技能需要系统库或字体等,可以提供一个 `install.sh` 脚本。Skill Manager 会在首次运行或脚本内容变化时执行它,并缓存结果。 如果需要系统库或字体等,提供一个 `install.sh` 脚本。它在两处执行:
- **镜像构建**(`executor/Dockerfile` 的 `skills` 阶段,`build.target: skills`):此处安装的系统包(`apt-get` 等)会烘进派生镜像 M',持久且对命令只读——**系统包必须走这里**。
- **服务启动前的 init**(`executor/init-skills.js`):用于生成技能自带资产(如从系统字体提取 `fonts/cjk.ttf`)。init 容器根文件系统只读,`apt-get install` 在这里不生效,不要依赖它。
示例 `install.sh`: 示例 `install.sh`:
@@ -154,8 +158,8 @@ apt-get install -y -qq some-package
``` ```
- `install.sh` 必须可执行(`chmod +x install.sh`)。 - `install.sh` 必须可执行(`chmod +x install.sh`)。
- 脚本中的操作应尽量幂等,以避免重复执行时出错。 - 请保持幂等:两处都以内容 hash 为缓存,仅在变化时执行。
- 如果安装耗时较长,请耐心等待;Skill Manager 会设置超时(默认 10 分钟)。 - 改动 `install.sh` 后:系统包需 `docker compose build agent-executor`,资产需 `docker compose up -d`(或两者一起 `build && up`)。
### 5.3 缓存机制 ### 5.3 缓存机制