公网链接改为内网现签:新增 /public-link 签发入口,删掉 /mcp-uploads 中转

- download-token.js(新): 从 files.js 抽出临时链接签名(密钥/报文形状/验签),浏览器下载与公网链接共用一份
- routes/public-link.js(新): GET /public-link?path=<绝对路径> 现签一条签名下载链接,
  返回纯文本 URL(AI 直接 curl 取用,免解析 JSON)
  边界:只收绝对路径 + workspace_root 前缀 + 会话表存在性 + realpath 复核(挡 ln -s 外泄)
- server.js: 该路由只挂在【不映射宿主机】的内网端口(PUBLIC_LINK_PORT,默认 8081),
  因此不需要任何凭据 —— 鉴权靠网络边界而不是密钥,密钥也不会漏进会话记录
- server.js/routes: 删掉 mcp-uploads.js 及其挂载(上传中转整套作废)
- config.js/config.example.yml: 新增 public_link.{base_url,ttl_ms}(默认 30 分钟,夹 1min~24h)
- docker-compose.yml: 去掉 MCP_UPLOADS_URL
- 文档: DEPLOY.md 4.1 改写为「公网临时链接」;ARCHITECTURE.md 同步文件树/时序图/约束
This commit is contained in:
2026-09-15 19:57:37 +08:00
parent f84afe4246
commit 70779e843e
11 changed files with 221 additions and 143 deletions
+1 -1
View File
@@ -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`。
+10
View File
@@ -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>:<AGENT_PORT>),只用于拼绝对地址;
# 留空 = 该功能整体关闭(对应 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
+20
View File
@@ -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') : '';
+46
View File
@@ -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 };
+12 -25
View File
@@ -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 链路)
-85
View File
@@ -1,85 +0,0 @@
// MCP 上传文件的公网只读中转(agent-core 侧)。
//
// 为什么需要这一层:
// 无域名部署时对外只开 agent-core 一个端口(AGENT_PORT,默认 8090)。但 video_gen 的
// /uploads/<file> 那一跳是【智谱的服务器】去拉的 —— 它不带 cookie、不带 Authorization,
// 必须是公网匿名可达。而 video_gen 自己不该占一个公网端口(那样它的 POST /upload 也会一起
// 暴露,写入口就跑到公网上了)。所以由 core 代拉:智谱拿到的地址是
// http://<服务器IP>:<AGENT_PORT>/mcp-uploads/uploads/<file>
// 这一跳只读、只走 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 };
+76
View File
@@ -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;
+19 -8
View File
@@ -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,
// 宿主机对应 <repo>/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(', '));
+3 -5
View File
@@ -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
+10 -7
View File
@@ -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` 放行,生产不得设置。
+24 -12
View File
@@ -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>:<AGENT_PORT>/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 的影响(可忽略,仅记录)