diff --git a/README.md b/README.md index 561bea6..9399790 100644 --- a/README.md +++ b/README.md @@ -803,7 +803,7 @@ networks: 无域名/反代时,compose 直接把容器 8080 映射到宿主机 8090,浏览器访问 `http://<服务器IP>:8090`(端口可用 `.env` 的 `AGENT_PORT` 改)。网络 `my-app-network` 与 `mcp` 仓库的服务共用、由本仓库创建(无需手动 `docker network create`,但因此要**先起 agent 再起 mcp**):core 与 executor 都靠它按容器名访问 MCP。认证用应用内置的多用户登录(`config.yml` 的 `auth.users`,登录页 `/login`),多用户共享同一任务库,不做任务隔离。 -**对外只开这一个端口**(executor 与 mcp 服务都不映射宿主机)。其中一条是反向入站:智谱服务器生成视频前要拉参考图,走的是 core 的只读中转 `GET /mcp-uploads/uploads/*`(只转发 GET/HEAD,写路径不经公网),见 `docs/DEPLOY.md` 第 4.1 节。 +**对外只开这一个端口**(executor 与 mcp 服务都不映射宿主机)。其中一条是反向入站:外部服务(如智谱)生成视频前要拉参考图,走的是 core 的**签名下载链接**——由 AI 在内网 `curl http://agent-core:8081/public-link?path=…` 现签(该签发端口不映射宿主机,所以不需要凭据),见 `docs/DEPLOY.md` 第 4.1 节。 HTTP 直连时浏览器不认为这是“安全上下文”:PWA/Service Worker 不注册、`navigator.clipboard` 降级(前端已有回退),登录 cookie 无 `Secure` 标志可正常工作。日后若加 HTTPS 反代,**SSE 需关代理缓冲**(`proxy_buffering off`),详见 `docs/DEPLOY.md`。 diff --git a/app/config.example.yml b/app/config.example.yml index 24a1f69..2f2e4e1 100644 --- a/app/config.example.yml +++ b/app/config.example.yml @@ -56,6 +56,16 @@ data_root: "./data" # url: "http://agent-executor:9000" # token: "change-me" # 选填;executor 侧配同值才校验 +# 公网临时链接(给"自己来拉文件"的外部服务用:例如智谱视频生成前要下载参考图)。 +# 配了 base_url 后,core 会额外在**内网**监听一个不映射宿主机的端口(env PUBLIC_LINK_PORT,默认 8081), +# 上面只挂一条 GET /public-link?path=<文件的绝对路径>;沙箱里的 AI 命令 curl 它,即可换回一条 +# 短命的公网下载链接(复用登录下载那套签名:不可猜 / 会过期 / 绑会话 / 重启即全部失效)。 +# base_url 填本服务的对外地址(就是浏览器访问的 http://<服务器IP>:),只用于拼绝对地址; +# 留空 = 该功能整体关闭(对应 MCP 服务里需要公网 URL 的那部分就用不了)。 +public_link: + base_url: "" # 例:"http://1.2.3.4:8090" + ttl_ms: 1800000 # 选填:链接有效期,默认 30 分钟(代码里夹在 1 分钟 ~ 24 小时) + # 日志等级(改后重启生效):debug < info < warn < error < none,只输出 ≥ 该等级的日志;none=全部静默。 # info(默认)=关键动作概述;debug 另加用户/AI 消息全文、工具调用参数/结果等排查细节。 log_level: info diff --git a/app/server/config.js b/app/server/config.js index 245f259..de225fb 100644 --- a/app/server/config.js +++ b/app/server/config.js @@ -43,6 +43,10 @@ const DEFAULTS = { // MCP 服务列表:每项 {name?, url, headers?, enable?(默认 true,false 时启动不加载)};启动时发现其工具并追加到内置工具之后。 // 注意与内置工具(definitions.json)严格分离:这里只配外部 MCP 服务。 mcp_servers: [], + // 公网临时链接:base_url 非空时,core 额外在内网监听一个**不映射宿主机**的端口(PUBLIC_LINK_PORT, + // 默认 8081),上面只挂 GET /public-link:沙箱里的 AI 命令 curl 它,换一条短命的公网下载链接 + // (给智谱那类"自己来拉文件"的外部服务用)。base_url = 本服务的对外地址(如 http://1.2.3.4:8090)。 + public_link: { base_url: '', ttl_ms: 1800000 }, }; function deepMerge(base, extra) { @@ -236,10 +240,26 @@ function parseAndValidate(rawText, configPath) { s.headers = headers; } + normalizePublicLink(cfg); + cfg.config_path = configPath || ''; return cfg; } +// 公网临时链接(public_link)规范化:base_url 去尾斜杠;ttl_ms 夹在 [1min, 24h]—— +// 公网链接宁可短不可长(“永久公开”正是这套机制要避免的东西)。 +function normalizePublicLink(cfg) { + const pl = cfg.public_link || {}; + cfg.public_link = { + base_url: String(pl.base_url || '').trim().replace(/\/+$/, ''), + ttl_ms: Math.min(Math.max(Number(pl.ttl_ms) || 1800000, 60 * 1000), 24 * 3600 * 1000), + }; + if (cfg.public_link.base_url && !/^https?:\/\//i.test(cfg.public_link.base_url)) { + log.warn('config', 'public_link.base_url 看起来不是 http(s) 地址:' + cfg.public_link.base_url); + } + return cfg; +} + function loadConfig(configPath) { const p = configPath || process.env.AGENT_CONFIG || path.join(__dirname, '..', 'config.yml'); const text = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : ''; diff --git a/app/server/download-token.js b/app/server/download-token.js new file mode 100644 index 0000000..7736b3d --- /dev/null +++ b/app/server/download-token.js @@ -0,0 +1,46 @@ +// 临时链接签名(files.js 的浏览器下载链接、routes/public-link.js 的公网链接共用同一套)。 +// +// 设计要点: +// - 密钥进程内随机:重启后所有旧链接自动失效。公网链接本来就该短命,这是免费拿到的性质。 +// - 签名覆盖「会话 + 路径 + 过期时间」三项,任何一项被改都会验签失败; +// 验签用 timingSafeEqual,不做按字节比较的旁路。 +// - 这里只提供"怎么签";"给谁签、能签什么"由调用方决定(见 routes/public-link.js 的边界校验)。 +'use strict'; + +const crypto = require('crypto'); + +const SECRET = crypto.randomBytes(32).toString('hex'); + +// 浏览器原生下载用:前端拿到后立刻 window.location.href 导航,5 分钟足够 +const BROWSER_TTL_MS = 5 * 60 * 1000; + +function signPayload(payload) { + return crypto.createHmac('sha256', SECRET).update(payload).digest('hex'); +} + +function sameHex(a, b) { + try { + return crypto.timingSafeEqual(Buffer.from(String(a), 'utf8'), Buffer.from(String(b), 'utf8')); + } catch (_) { return false; } +} + +function validPayload(payload, expires, t) { + const exp = Number(expires); + if (!t || !Number.isFinite(exp) || exp < Date.now()) return false; + return sameHex(signPayload(payload), t); +} + +// 下载链接的报文形状(唯一一份;files.js 验签、public-link.js 签发都走它,避免两边写歪) +function downloadPayload(sessionId, rel, expires) { + return sessionId + '\n' + rel + '\n' + expires; +} + +function signDownload(sessionId, rel, expires) { + return signPayload(downloadPayload(sessionId, rel, expires)); +} + +function validDownload(sessionId, rel, expires, t) { + return validPayload(downloadPayload(sessionId, rel, expires), expires, t); +} + +module.exports = { BROWSER_TTL_MS, signPayload, sameHex, validPayload, signDownload, validDownload }; diff --git a/app/server/routes/files.js b/app/server/routes/files.js index 0f125b4..30f0508 100644 --- a/app/server/routes/files.js +++ b/app/server/routes/files.js @@ -3,10 +3,10 @@ const express = require('express'); const fs = require('fs'); const path = require('path'); const multer = require('multer'); -const crypto = require('crypto'); const engine = require('../engine'); const { listTaskFiles } = require('./sessions'); const { resolveInTask } = require('../tools/executor'); +const downloadToken = require('../download-token'); const log = require('../log'); const router = express.Router(); @@ -90,22 +90,11 @@ router.get('/:id/files', function (req, res) { // 移动端浏览器 fetch+blob 下载会丢失文件名(uuid.bin);改为短时效签名链接, // 前端拿到后 window.location.href 导航下载,走原生下载流程。 // 密钥随进程启动随机生成,重启后旧 token 自动失效。 -const DOWNLOAD_TOKEN_TTL_MS = 5 * 60 * 1000; -const downloadTokenSecret = crypto.randomBytes(32).toString('hex'); - -function signDownloadToken(sessionId, rel, expires) { - return crypto.createHmac('sha256', downloadTokenSecret) - .update(sessionId + '\n' + rel + '\n' + expires).digest('hex'); -} - -function validDownloadToken(sessionId, rel, expires, t) { - const exp = Number(expires); - if (!t || !Number.isFinite(exp) || exp < Date.now()) return false; - const expected = signDownloadToken(sessionId, rel, exp); - try { - return crypto.timingSafeEqual(Buffer.from(String(t), 'utf8'), Buffer.from(expected, 'utf8')); - } catch (_) { return false; } -} +// 签名实现(密钥、报文形状、验签)统一在 ../download-token.js: +// routes/public-link.js 给外部服务签的是同一种链接,两边共用一份形状,避免“签得出、验不过”。 +const DOWNLOAD_TOKEN_TTL_MS = downloadToken.BROWSER_TTL_MS; +const signDownloadToken = downloadToken.signDownload; +const validDownloadToken = downloadToken.validDownload; // 签发临时下载链接(需正常认证;拿到的链接 5 分钟内有效) router.get('/:id/files/download-token', function (req, res) { @@ -353,17 +342,15 @@ function zipNameFor(paths) { '-' + pad(d.getHours()) + pad(d.getMinutes()) + pad(d.getSeconds()) + '.zip'; } +// 打包下载的报文形状与单文件下载不同(整串 paths 一起签),其余共用 ../download-token.js +function zipPayload(sessionId, pathsRaw, expires) { + return sessionId + '\nzip\n' + pathsRaw + '\n' + expires; +} function signZipToken(sessionId, pathsRaw, expires) { - return crypto.createHmac('sha256', downloadTokenSecret) - .update(sessionId + '\nzip\n' + pathsRaw + '\n' + expires).digest('hex'); + return downloadToken.signPayload(zipPayload(sessionId, pathsRaw, expires)); } function validZipToken(sessionId, pathsRaw, expires, t) { - const exp = Number(expires); - if (!t || !Number.isFinite(exp) || exp < Date.now()) return false; - const expected = signZipToken(sessionId, pathsRaw, exp); - try { - return crypto.timingSafeEqual(Buffer.from(String(t), 'utf8'), Buffer.from(expected, 'utf8')); - } catch (_) { return false; } + return downloadToken.validPayload(zipPayload(sessionId, pathsRaw, expires), expires, t); } // 签发打包下载链接(需正常认证;与单文件下载同一条 token 链路) diff --git a/app/server/routes/mcp-uploads.js b/app/server/routes/mcp-uploads.js deleted file mode 100644 index cdf6297..0000000 --- a/app/server/routes/mcp-uploads.js +++ /dev/null @@ -1,85 +0,0 @@ -// MCP 上传文件的公网只读中转(agent-core 侧)。 -// -// 为什么需要这一层: -// 无域名部署时对外只开 agent-core 一个端口(AGENT_PORT,默认 8090)。但 video_gen 的 -// /uploads/ 那一跳是【智谱的服务器】去拉的 —— 它不带 cookie、不带 Authorization, -// 必须是公网匿名可达。而 video_gen 自己不该占一个公网端口(那样它的 POST /upload 也会一起 -// 暴露,写入口就跑到公网上了)。所以由 core 代拉:智谱拿到的地址是 -// http://<服务器IP>:/mcp-uploads/uploads/ -// 这一跳只读、只走 video_gen 的【只读监听】(容器内 3001),写路径永远不经公网。 -// -// 安全边界(改这里务必保持): -// 1. 只转发 GET/HEAD,其余方法一律 405:POST /upload 不可能从这个路由穿过去。 -// 2. 上游固定为 video_gen 的只读监听(PUBLIC_PORT),那边压根没有 /upload 路由(纵深防御)。 -// 3. 文件名只放行 video_gen 生成的形态(randomUUID + 可选后缀),挡住目录穿越与探测。 -// 4. 本路由挂在 auth.middleware 之前(智谱不带凭据),因此是【匿名可读】的。 -// 它等同于"随机文件名 + 有 TTL"的能力链接:不要在这里挂任何敏感或可枚举的东西。 -'use strict'; - -const http = require('http'); -const https = require('https'); -const express = require('express'); -const log = require('../log'); - -// video_gen 的文件名:randomUUID() + 可选扩展名(见 mcp/video_gen/src/mcp-server.js 的 multer storage) -const FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/; -// 只透传与"取文件"有关的响应头,避免把上游的协商/凭据类头部带出去 -const PASS_HEADERS = ['content-type', 'content-length', 'last-modified', 'etag', 'accept-ranges', 'content-range']; - -// target 形如 http://mcp_video_gen:3001(环境变量 MCP_UPLOADS_URL) -function createRouter(target, options) { - const timeoutMs = (options && options.timeout_ms) || 30000; - const router = express.Router(); - const base = new URL(target); - const client = base.protocol === 'https:' ? https : http; - const basePath = base.pathname.replace(/\/+$/, ''); - - function relay(req, res) { - const file = req.params.file; - if (!FILE_RE.test(file) || file.includes('..')) { - return res.status(400).json({ error: 'bad file name' }); - } - const headers = {}; - if (req.headers.range) headers.Range = req.headers.range; // 大图/视频拖动时支持分片 - - const up = client.request({ - protocol: base.protocol, - hostname: base.hostname, - port: base.port, - method: req.method, - path: basePath + '/uploads/' + encodeURIComponent(file), - headers, - }, (upRes) => { - for (const h of PASS_HEADERS) { - if (upRes.headers[h] !== undefined) res.setHeader(h, upRes.headers[h]); - } - res.status(upRes.statusCode || 502); - upRes.pipe(res); - }); - - up.setTimeout(timeoutMs, () => up.destroy(new Error('upstream timeout'))); - up.on('error', (err) => { - if (res.headersSent) return res.destroy(); - // 只说地址不通,不把上游内部细节吐给公网 - log.warn('mcp-uploads', '中转失败 ' + file + ': ' + err.message); - res.status(502).json({ error: 'upstream unavailable' }); - }); - req.pipe(up); - } - - router.get('/uploads/:file', relay); - router.head('/uploads/:file', relay); - - // 其余方法/路径一律就地回掉,别落到后面的登录中间件上(那样智谱会拿到 401 页面而不是 404) - router.use((req, res) => { - if (/^\/uploads\/[^/]+$/.test(req.path)) { - res.set('Allow', 'GET, HEAD'); - return res.status(405).json({ error: 'method not allowed' }); - } - res.status(404).json({ error: 'not found' }); - }); - - return router; -} - -module.exports = { createRouter }; diff --git a/app/server/routes/public-link.js b/app/server/routes/public-link.js new file mode 100644 index 0000000..f31b675 --- /dev/null +++ b/app/server/routes/public-link.js @@ -0,0 +1,76 @@ +// 公网临时链接签发(只在【内网监听】的端口上,见 server.js 里 PUBLIC_LINK_PORT 那段)。 +// +// 用途:把任务目录里的文件变成一条短命的公网 URL,交给外部服务去取。第一个消费者是 +// MCP video_gen:智谱服务器生成视频前要自己来拉参考图,它不带 cookie、不带 Authorization, +// 所以必须给它一条「不可猜 + 会过期」的链接 —— 这正是 files.js 一直在用的签名下载链接 +// (auth.js 的 isSignedDownload 已放行带 ?t= 的 /files/download* 请求)。 +// 这里解决的唯一问题:**沙箱里的 AI 怎么拿到一条签名**(签发接口要登录,executor 里没有凭据)。 +// +// 为什么单独一个端口、且不映射到宿主机: +// 这条接口没法用凭据保护(AI 的命令带不了凭据),那就干脆让外部**连都连不上**。 +// 鉴权靠网络边界(不 publish),不靠密钥 —— 比任何 token 都可靠,也不会把密钥漏到会话记录里。 +// +// 边界(改这里务必保持): +// 1. 只接受绝对路径,且必须落在 workspace_root 内;再反查会话表确认会话真实存在。 +// 2. 取 realpath 复核仍在任务根内:挡住"先 ln -s 一个外泄目标,再签它的链接"。 +// 3. 只签"已存在且是文件"的路径;签出来的链接由 files.js 的 serveDownload 再验一遍。 +// 4. 返回 text/plain 而不是 JSON:AI 用 `curl -s` 拿到的 stdout 就是现成 URL,免解析。 +'use strict'; + +const path = require('path'); +const fs = require('fs'); +const express = require('express'); +const engine = require('../engine'); +const { signDownload } = require('../download-token'); +const log = require('../log'); + +const router = express.Router(); + +function bad(res, status, msg) { + return res.status(status).type('text/plain').send('ERROR: ' + msg + '\n'); +} + +router.get('/public-link', function (req, res) { + const cfg = engine.getConfig(); + const pl = cfg.public_link || {}; + if (!pl.base_url) return bad(res, 503, 'public_link.base_url 未配置,无法签发公网链接'); + + const raw = String(req.query.path || '').trim(); + if (!raw) return bad(res, 400, '缺少 path 参数(要文件的绝对路径,如 /workspace/tasks/<会话>/foo.png)'); + if (!path.isAbsolute(raw)) return bad(res, 400, 'path 必须是绝对路径(与你在命令里看到的路径一致)'); + + const root = path.resolve(cfg.workspace_root); + const abs = path.normalize(raw); + if (abs !== root && abs.indexOf(root + path.sep) !== 0) { + return bad(res, 400, 'path 必须位于任务根目录内:' + root); + } + + const rel = path.relative(root, abs); + const sid = rel.split(path.sep)[0]; + const fileRel = rel.slice(sid.length + 1); + if (!sid || !fileRel) return bad(res, 400, 'path 要指向会话目录下的某个文件,不能是目录本身'); + if (!engine.getSession(sid)) return bad(res, 404, '会话不存在:' + sid); + + let real; + try { + if (!fs.statSync(abs).isFile()) return bad(res, 400, '不是文件:' + raw); + real = fs.realpathSync(abs); + } catch (_) { + return bad(res, 404, '文件不存在:' + raw); + } + if (real !== abs && real.indexOf(fs.realpathSync(root) + path.sep) !== 0) { + return bad(res, 400, 'path 经符号链接指向了任务根之外,拒绝签发'); + } + + const expires = Date.now() + pl.ttl_ms; + const t = signDownload(sid, fileRel, expires); + const url = pl.base_url + '/api/sessions/' + encodeURIComponent(sid) + + '/files/download-name/' + encodeURIComponent(path.basename(fileRel)) + + '?path=' + encodeURIComponent(fileRel) + + '&expires=' + expires + '&t=' + t; + + log.info('public-link', sid + ' 签发公网链接(' + Math.round(pl.ttl_ms / 60000) + ' 分钟):' + fileRel); + res.type('text/plain').send(url + '\n'); +}); + +module.exports = router; diff --git a/app/server/server.js b/app/server/server.js index 1225a8d..208b880 100644 --- a/app/server/server.js +++ b/app/server/server.js @@ -31,14 +31,6 @@ app.use(express.json({ limit: '2mb' })); // 相比 nginx htpasswd 的 basic auth,cookie 在手机浏览器原生下载时也会自动携带,下载不再失败。 const auth = createAuth(cfg); app.use(auth.router); // /login、/logout、/api/login 等免认证端点 - -// MCP 上传文件的公网只读中转(为何需要见 routes/mcp-uploads.js 头注释)。 -// 必须挂在 auth.middleware 之前:智谱服务器来拉图时不会带任何凭据。 -// 未配 MCP_UPLOADS_URL 则不挂(此时 /mcp-uploads/* 不存在)。 -if (process.env.MCP_UPLOADS_URL) { - app.use('/mcp-uploads', require('./routes/mcp-uploads').createRouter(process.env.MCP_UPLOADS_URL)); -} - app.use(auth.middleware); // 其余请求需登录态(cookie 或 Basic 头) app.use(express.static(path.join(__dirname, 'public'))); @@ -90,6 +82,24 @@ app.get('/api/health', (req, res) => res.json({ ok: true, time: Date.now() })); const PORT = process.env.PORT || cfg.port; +// 公网临时链接的【签发】端口:只在容器内监听、**不映射到宿主机**(compose 也不 publish), +// 所以外部连不上,于是这条接口不需要任何凭据 —— executor 里的 AI 命令可以 curl 它换一条 +// 短命的公网链接(见 routes/public-link.js 头注释)。未配 public_link.base_url 则不启动。 +const PUBLIC_LINK_PORT = Number(process.env.PUBLIC_LINK_PORT) || 8081; + +function startPublicLinkServer() { + const pl = cfg.public_link || {}; + if (!pl.base_url) { + log.info('startup', ' public_link=未配置(public_link.base_url 为空),不启动签发端口'); + return; + } + const plApp = express(); + plApp.use(require('./routes/public-link')); + plApp.listen(PUBLIC_LINK_PORT, () => { + log.info('startup', ' public_link=' + pl.base_url + ' (签发端口 :' + PUBLIC_LINK_PORT + ' 仅内网,未映射宿主机)'); + }); +} + // 启动成功后把模型实际收到的各部分 dump 到文件方便人工核对(data_root 默认 ./data, // 宿主机对应 /data/prompt.txt,已被 gitignore)。包含两部分: // 1) system 消息:模板 + 可用技能段落 + 语言指令(进程内恒定,仅技能增删时变); @@ -120,6 +130,7 @@ mcp.init(cfg).then(async () => { } server.listen(PORT, () => { log.info('startup', 'Agent server listening on ' + PORT); + startPublicLinkServer(); log.info('startup', ' workspace_root=' + cfg.workspace_root); log.info('startup', ' data_root=' + cfg.data_root); log.info('startup', ' models=' + cfg.models.map(m => m.id + '@' + m.url).join(', ')); diff --git a/docker-compose.yml b/docker-compose.yml index 5fbb36e..ab5bb5c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -21,9 +21,6 @@ services: # 调用鉴权 token:两侧同一值。从 .env 读取(已 gitignore),不再硬编码进仓库; # 未设置则 compose 直接报错,避免静默无鉴权。生成:openssl rand -hex 32 - EXECUTOR_TOKEN=${EXECUTOR_TOKEN:?EXECUTOR_TOKEN not set - see .env.example} - # MCP 上传文件的公网只读中转目标(video_gen 的【只读监听】,容器内 3001)。 - # 智谱拉图→core→此地址;只转 GET/HEAD,写路径(POST /upload)不经公网。 - - MCP_UPLOADS_URL=http://mcp_video_gen:3001 networks: - my-app-network @@ -125,8 +122,9 @@ services: networks: # 全部服务共用一个网络;由本仓库创建(固定名字,避免被加上 compose 项目名前缀),mcp 侧声明为 # external 直接加入 —— 所以全新机器上要【先起 agent,再起 mcp】。 - # - core / executor 靠它按容器名访问 MCP 服务(如 http://mcp_web_search:3000/) - # - executor 靠它把本地图片上传给 video_gen(http://mcp_video_gen:3000/upload,不经公网) + # - core 与 executor 靠它按容器名访问 MCP 服务(如 http://mcp_web_search:3000/) + # - executor 靠它 curl core 的内网签发入口(http://agent-core:8081/public-link), + # 把本地图片换成一个短命的公网链接给外部服务用(不经过公网、不搬字节) my-app-network: name: my-app-network driver: bridge diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9b867f5..0cc5225 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -41,6 +41,7 @@ agent/ │ │ │ ├── definitions.json 内置 15 个工具的 OpenAI function 格式定义 │ │ │ ├── executor.js 工具执行器(文件类 + terminal + skill 委托) │ │ │ └── skills.js Skill Manager(list/info/run + 依赖安装 + 路径预处理) +│ │ ├── download-token.js 临时链接签名(浏览器下载 / 公网链接共用一套) │ │ ├── routes/ │ │ │ ├── sessions.js /api/sessions CRUD + 列表分页 │ │ │ ├── messages.js /api/sessions/:id/messages + SSE 流 + stop/release @@ -48,7 +49,7 @@ agent/ │ │ │ ├── config.js /api/config 读写(含 api_key/password 脱敏) │ │ │ ├── platforms.js /api/platforms/balance 余额查询 │ │ │ ├── skills.js /api/skills 技能文件管理 -│ │ │ ├── mcp-uploads.js /mcp-uploads/uploads/* 公网只读中转(智能服务器拉图用) +│ │ │ ├── public-link.js GET /public-link 签发公网临时链接(只挂内网端口) │ │ │ └── system.js /api/system/status + /restart 优雅重启 │ │ ├── templates/ │ │ │ └── system-prompt.txt system prompt 静态模板(每次请求复用,利于上游前缀缓存) @@ -99,8 +100,8 @@ graph LR Core -->|POST /chat/completions| LLM Core -->|tools/call| MCP MCP -->|提交任务| Zhipu - Zhipu -->|匿名 GET 拉参考图| Core - Core -->|只读转发 GET /uploads/*| MCP + Exec -->|curl /public-link 现签链接| Core + Zhipu -->|匿名 GET 签名链接| Core Core <-->|读写| Tasks Exec <-->|读写| Tasks Core <-->|技能 + deps| Skills @@ -109,14 +110,16 @@ graph LR ``` 所有容器都在同一个 `my-app-network` 上(core 与 executor 同时靠它访问 MCP);外网只暴露 Core -(宿主机端口映射)。注意其中一条**反向**的入站链路:智谱服务器来拉参考图时,走的是 Core 的 -`/mcp-uploads/uploads/*` 只读中转(详见下面约束)。 +(宿主机端口映射)。注意其中一条**反向**的入站链路:外部服务(如智谱)来拉文件时,走的是 Core 的 +签名下载链接 `/api/sessions/:id/files/download-name/*?t=…`(链接由内网签发入口 `GET /public-link` 现签)。 **关键约束**(改 compose 时务必保持): -- 全部容器同一个网络 `my-app-network`(由本仓库 compose 创建,mcp 侧 external 加入)——core 靠它访问 MCP 服务,executor 靠它把本地图片上传给 video_gen。 +- 全部容器同一个网络 `my-app-network`(由本仓库 compose 创建,mcp 侧 external 加入)——core 与 executor 都靠它按容器名访问 MCP 服务(executor 还要靠它 curl core 的签发入口)。 - `agent-core` 与 `agent-executor` 须把**同一份宿主机 `./tasks`、`./skills`**挂到相同的容器路径(默认 `/workspace/tasks`、`/workspace/skills`)。这是文件工具在 Core 本地直接读、命令在远端写,二者能"看到"彼此产物的根本约定。 -- **`/mcp-uploads/*` 是 Core 上唯一匿名可读的路由**(`routes/mcp-uploads.js`),只为让智谱服务器拉到参考图而存在:必须挂在 `auth.middleware` **之前**,且只转发 GET/HEAD 到 video_gen 的**只读监听**(不转写路径)。该路由本身就是“随机文件名 + TTL”的能力链接,往里加任何敏感/可枚举的东西都是错。未配 `MCP_UPLOADS_URL` 则不挂该路由。 +- **临时链接签名只有一份**(`download-token.js`):浏览器下载链接与 `routes/public-link.js` 给外部服务签的公网链接**必须是同一套**(密钥、报文形状、验签都共用)。两边写歪的后果是“签得出来、验不过去”,所以任何一边都不得自己拼 HMAC。 +- **`routes/public-link.js` 只挂在【不映射宿主机】的内网端口上**(`PUBLIC_LINK_PORT`,默认 8081):它不需要凭据(沙箱里的 AI 带不了凭据),所以安全性完全依赖“外部连不上这个端口”。**绝不要**把它挂到对外的 8080 上,也不要 publish 该端口。 +- 该路由是 Core 上唯一“匿名可写入口”性质的东西(它能给任意**已知会话**的文件签发链接),所以路径必须经 `workspace_root` 前缀校验 + 会话表校验 + realpath 复核(挡 `ln -s` 外泄);未配 `public_link.base_url` 则不启动签发端口。 - 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` 放行,生产不得设置。 diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 719e145..e4f8afb 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -51,6 +51,8 @@ workspace_root: /workspace/tasks # 不能留示例里的 ./data/tasks data_root: /workspace/data # SQLite 与 prompt dump 落在这个挂载卷里 skills: skills_root: /workspace/skills +public_link: # 需要给外部服务公网 URL 时才配(图生视频用);见第 4.1 节 + base_url: "http://<服务器IP>:8090" auth: # 建议启用,否则谁都能访问 secret: "换一个随机串" users: @@ -84,24 +86,34 @@ docker compose logs -f agent-core # 看到 "Agent server listening on 8080" 内网,没有映射到宿主机(需要从宿主机 curl 调试时,去 mcp 仓库的 `docker-compose.yml` 里临时 把对应服务的 `ports` 两行取消注释)。 -### 4.1 图片中转(只有图生视频会用到) +### 4.1 公网临时链接(只有“把本地文件交给外部服务”时才用到) -智谱服务器生成视频前要回来拉参考图,它不带 cookie、不带 `Authorization`,必须公网匿名可达。 -而 video_gen 不该为此占一个公网端口(那样它的 `POST /upload` 也会一起暴露),所以由 core 代拉: +场景:图生视频时,智谱服务器生成视频前要**自己来拉参考图**,它不带 cookie、不带 `Authorization`, +所以必须有一条公网匿名可达的 URL。做法是复用登录下载那套签名链接(`app/server/download-token.js`): +不可猜(HMAC)、会过期、绑会话、进程重启即全部失效。 + +AI 拿链接的姿势:core 额外在**内网**监听一个**不映射到宿主机**的端口(`PUBLIC_LINK_PORT`,默认 8081), +上面只有一条签发接口。因为压根没 publish,外部连不上,所以它**不需要任何凭据**: + +```bash +# AI 在 executor 沙箱里执行(路径就是它平时看到的那个绝对路径) +curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/foo.png" +# → http://<服务器IP>:8090/api/sessions/<会话>/files/download-name/foo.png?path=foo.png&expires=…&t=… +# stdout 就是现成 URL,直接当 image_url 用 +``` ``` -智谱 ──匿名 GET──► http://<服务器IP>:8090/mcp-uploads/uploads/<随机文件名> - │ core 只转发 GET/HEAD +智谱 ──匿名 GET──► /api/sessions/<会话>/files/download-name/…&t=… (core :8090) + │ 验签(会话 + 路径 + 时效) ▼ - mcp_video_gen:3001 ← video_gen 的只读监听(那边压根没有 /upload) + ./tasks/<会话>/foo.png ← 文件仍在原地,零拷贝 ``` -- AI 上传图片走的是**内网** `http://mcp_video_gen:3000/upload`,写路径从不经过公网。 -- core 侧由 `MCP_UPLOADS_URL=http://mcp_video_gen:3001` 开启这条中转(compose 已配好); - 留空则 `/mcp-uploads/*` 这条路由不存在。 -- mcp 侧必须把 `PUBLIC_BASE_URL` 设成 `http://<服务器IP>:/mcp-uploads`, - 否则返回给智谱的地址不对,图生视频会失败(video_gen 启动日志会打印两个实际生效的地址,便于核对)。 -- 这条路径**匿名可读**:内容不可枚举(文件名是 randomUUID)、24h 后自动删除、只读不能写。 +- 必须在 `config.yml` 配 `public_link.base_url = "http://<服务器IP>:8090"`;不配则不启动签发端口, + video_gen 的工具描述里也不会出现那条命令(它会退化成“请运维配 PUBLIC_LINK_URL”)。 +- 链接有效期 `public_link.ttl_ms`,默认 30 分钟;签完尽快用掉。 +- 沙箱外的人要用上这条链接,得同时知道 IP、路径和签名;签名猜不出来,过期即废。 +- 这条路不搬字节:文件始终在它原本的位置,也不需要 video_gen 参与上传/落盘。 ## 5. 没有 HTTPS 的影响(可忽略,仅记录)