diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..1b7c9f8 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,10 @@ +# executor 派生镜像的构建上下文 = 仓库根(compose 里 context: .), +# 但只需要 executor/ 与 skills/ 两份源码;其余(含 node_modules、任务数据、密钥)全部排除。 +* +!executor +!skills +# 技能目录里运行期生成 / 体积大的部分不进构建上下文 +skills/deps +skills/*/.deps_installed +skills/*/fonts +skills/*/__pycache__ diff --git a/docker-compose.yml b/docker-compose.yml index bc1f6a3..f7295a5 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -26,10 +26,45 @@ services: - my-app-network - 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: - 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 restart: unless-stopped + depends_on: + agent-executor-init: + condition: service_completed_successfully expose: - "9000" volumes: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d7fe4c5..d5bef80 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -111,6 +111,8 @@ graph LR - 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`。 - 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` 头注释。 --- @@ -272,6 +274,7 @@ stateDiagram-v2 - `runSkill` 流程:`skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`) → `ensureDeps` → 选 `python3 run.py ''` 或 `bash run.sh ''` → `runEntry`。 - **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`),env 只传 `PYTHONPATH=`。 - **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/` 看到的就是本会话数据,`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 客户端 @@ -328,7 +331,7 @@ stateDiagram-v2 ## 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}]}`,免鉴权。 - `POST /exec` body `{command, cwd(必填), timeout_ms?, max_output_chars?, env?}` → SSE 流: diff --git a/executor/Dockerfile b/executor/Dockerfile index 24a0f56..d9a6963 100644 --- a/executor/Dockerfile +++ b/executor/Dockerfile @@ -1,4 +1,9 @@ -FROM node:20-slim +# ============================================================================= +# 基础阶段 M —— 长期不变:node + 系统工具 + 预烘 Python 依赖。 +# 只承载“系统层”,不含任何技能专属依赖。构建上下文为仓库根(compose: context: .), +# 故 COPY 路径带 executor/ 前缀。 +# ============================================================================= +FROM node:20-slim AS base # MPLBACKEND=Agg:让 matplotlib 使用非交互式后端,避免缺少显示设备报错。 # PYTHONUNBUFFERED=1:实时输出日志。 @@ -36,7 +41,9 @@ RUN pip3 install --no-cache-dir --break-system-packages \ # ---- executor 服务(零依赖单文件,仅 Node 内置 http)---- WORKDIR /app -COPY server.js ./ +COPY executor/server.js ./ +# 技能依赖准备脚本:由 agent-executor-init 服务在启动前执行(pip/资产,无特权) +COPY executor/init-skills.js ./ # 隔离用的空挂载点:必须存在且为空。 # /workspace/tasks —— wrapper 用 tmpfs 遮盖它,再 bind 回当前 session(虚拟任务根) @@ -49,7 +56,7 @@ RUN mkdir -p /workspace/tasks /workspace/scratch \ EXPOSE 9000 # 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 一致。 ENV PORT=9000 \ EXECUTOR_ROOTS=/workspace \ @@ -60,3 +67,24 @@ ENV PORT=9000 \ EXECUTOR_LOG_LEVEL=info 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 diff --git a/executor/init-skills.js b/executor/init-skills.js new file mode 100644 index 0000000..7049f60 --- /dev/null +++ b/executor/init-skills.js @@ -0,0 +1,92 @@ +#!/usr/bin/env node +// agent-executor-init:executor 启动前的一次性技能准备。 +// +// 只处理“运行期可变”的依赖: +// - requirements.txt → python3 -m pip install --target /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); + } +})(); diff --git a/skills/README.md b/skills/README.md index 541ee6a..7bc7c91 100644 --- a/skills/README.md +++ b/skills/README.md @@ -128,7 +128,7 @@ def main(): ### 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`: @@ -139,10 +139,14 @@ beautifulsoup4==4.11.1 - 依赖安装使用 `pip install --target`,不会污染系统全局。 - 所有技能**共享**同一个 `deps` 目录,请注意版本冲突(后装的覆盖先装的)。建议锁定精确版本。 +- 运行期 skills 目录只读;若上线后经 UI 改了 `requirements.txt`,需重启(`docker compose up -d`)触发重新 init,否则该技能会因依赖未就绪而失败。 ### 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`: @@ -154,8 +158,8 @@ apt-get install -y -qq some-package ``` - `install.sh` 必须可执行(`chmod +x install.sh`)。 -- 脚本中的操作应尽量幂等,以避免重复执行时出错。 -- 如果安装耗时较长,请耐心等待;Skill Manager 会设置超时(默认 10 分钟)。 +- 请保持幂等:两处都以内容 hash 为缓存,仅在变化时执行。 +- 改动 `install.sh` 后:系统包需 `docker compose build agent-executor`,资产需 `docker compose up -d`(或两者一起 `build && up`)。 ### 5.3 缓存机制