diff --git a/README.md b/README.md index 7251978..561bea6 100644 --- a/README.md +++ b/README.md @@ -801,7 +801,9 @@ networks: ### 13.2 对外暴露(IP:端口) -无域名/反代时,compose 直接把容器 8080 映射到宿主机 8090,浏览器访问 `http://<服务器IP>:8090`(端口可用 `.env` 的 `AGENT_PORT` 改)。外部网络 `my-app-network` 与 `mcp` 仓库的服务共用、由本仓库创建(无需手动 `docker network create`,但因此要**先起 agent 再起 mcp**):agent 按容器名访问 MCP,如 `http://mcp_web_search:3000/`。认证用应用内置的多用户登录(`config.yml` 的 `auth.users`,登录页 `/login`),多用户共享同一任务库,不做任务隔离。 +无域名/反代时,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 节。 HTTP 直连时浏览器不认为这是“安全上下文”:PWA/Service Worker 不注册、`navigator.clipboard` 降级(前端已有回退),登录 cookie 无 `Secure` 标志可正常工作。日后若加 HTTPS 反代,**SSE 需关代理缓冲**(`proxy_buffering off`),详见 `docs/DEPLOY.md`。 diff --git a/app/server/routes/mcp-uploads.js b/app/server/routes/mcp-uploads.js new file mode 100644 index 0000000..cdf6297 --- /dev/null +++ b/app/server/routes/mcp-uploads.js @@ -0,0 +1,85 @@ +// 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/server.js b/app/server/server.js index 9a875a1..1225a8d 100644 --- a/app/server/server.js +++ b/app/server/server.js @@ -31,6 +31,14 @@ 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'))); diff --git a/docker-compose.yml b/docker-compose.yml index 0a00d8c..5fbb36e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -21,9 +21,11 @@ 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 - - agent-internal # 技能准备(一次性,跑完退出):把各技能的“运行期可变”依赖落到宿主 ./skills—— # requirements.txt → pip --target 共享 deps 目录;install.sh → 技能资产(如字体提取)。 @@ -49,7 +51,7 @@ services: - PYTHONDONTWRITEBYTECODE=1 - TZ=Asia/Shanghai networks: - - agent-internal + - my-app-network agent-executor: # M' = M + 技能系统层依赖(executor/Dockerfile 的 skills 阶段)。 @@ -118,14 +120,13 @@ services: - /run networks: - - agent-internal + - my-app-network networks: - # 与 mcp 仓库共用:agent-core 按容器名访问 MCP 服务(如 http://mcp_web_search:3000/)。 - # 网络由本仓库创建(固定名字,避免被加上 compose 项目名前缀);mcp 侧声明为 external 直接加入, - # 所以全新机器上要【先起 agent,再起 mcp】。 + # 全部服务共用一个网络;由本仓库创建(固定名字,避免被加上 compose 项目名前缀),mcp 侧声明为 + # external 直接加入 —— 所以全新机器上要【先起 agent,再起 mcp】。 + # - core / executor 靠它按容器名访问 MCP 服务(如 http://mcp_web_search:3000/) + # - executor 靠它把本地图片上传给 video_gen(http://mcp_video_gen:3000/upload,不经公网) my-app-network: name: my-app-network driver: bridge - agent-internal: - driver: bridge diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0c0d346..9b867f5 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -48,6 +48,7 @@ agent/ │ │ │ ├── config.js /api/config 读写(含 api_key/password 脱敏) │ │ │ ├── platforms.js /api/platforms/balance 余额查询 │ │ │ ├── skills.js /api/skills 技能文件管理 +│ │ │ ├── mcp-uploads.js /mcp-uploads/uploads/* 公网只读中转(智能服务器拉图用) │ │ │ └── system.js /api/system/status + /restart 优雅重启 │ │ ├── templates/ │ │ │ └── system-prompt.txt system prompt 静态模板(每次请求复用,利于上游前缀缓存) @@ -87,6 +88,7 @@ graph LR Core[agent-core
宿主机 8090] Exec[agent-executor
:9000 内网] MCP[MCP 服务
my-app-network] + Zhipu[智谱服务器] LLM[LLM 池
OpenAI 兼容] Tasks[./tasks
任务目录 bind mount] Skills[./skills
技能目录 bind mount] @@ -96,6 +98,9 @@ graph LR Core -->|SSE /exec| Exec Core -->|POST /chat/completions| LLM Core -->|tools/call| MCP + MCP -->|提交任务| Zhipu + Zhipu -->|匿名 GET 拉参考图| Core + Core -->|只读转发 GET /uploads/*| MCP Core <-->|读写| Tasks Exec <-->|读写| Tasks Core <-->|技能 + deps| Skills @@ -103,11 +108,15 @@ graph LR Core --> DB ``` -两个容器通过 `agent-internal` 内网 bridge 通信;外网只暴露 Core(宿主机端口映射)。 +所有容器都在同一个 `my-app-network` 上(core 与 executor 同时靠它访问 MCP);外网只暴露 Core +(宿主机端口映射)。注意其中一条**反向**的入站链路:智谱服务器来拉参考图时,走的是 Core 的 +`/mcp-uploads/uploads/*` 只读中转(详见下面约束)。 **关键约束**(改 compose 时务必保持): +- 全部容器同一个网络 `my-app-network`(由本仓库 compose 创建,mcp 侧 external 加入)——core 靠它访问 MCP 服务,executor 靠它把本地图片上传给 video_gen。 - `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` 则不挂该路由。 - 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 6a22abe..719e145 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -80,7 +80,28 @@ docker compose logs -f agent-core # 看到 "Agent server listening on 8080" 浏览器打开 **`http://<服务器IP>:8090`**(端口可用 `.env` 里的 `AGENT_PORT` 改)。 登录用第 2 步 `auth.users` 里配的账号。 -对外只需放行这一个端口:`agent-executor`(9000)只在 `agent-internal` 内网,没有映射到宿主机。 +**对外只需要放行这一个端口**:`agent-executor`(9000)和 mcp 的三个服务都只在 `my-app-network` +内网,没有映射到宿主机(需要从宿主机 curl 调试时,去 mcp 仓库的 `docker-compose.yml` 里临时 +把对应服务的 `ports` 两行取消注释)。 + +### 4.1 图片中转(只有图生视频会用到) + +智谱服务器生成视频前要回来拉参考图,它不带 cookie、不带 `Authorization`,必须公网匿名可达。 +而 video_gen 不该为此占一个公网端口(那样它的 `POST /upload` 也会一起暴露),所以由 core 代拉: + +``` +智谱 ──匿名 GET──► http://<服务器IP>:8090/mcp-uploads/uploads/<随机文件名> + │ core 只转发 GET/HEAD + ▼ + mcp_video_gen:3001 ← video_gen 的只读监听(那边压根没有 /upload) +``` + +- 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 后自动删除、只读不能写。 ## 5. 没有 HTTPS 的影响(可忽略,仅记录)