From 05d03f08362242832959e559f4751148152bea46 Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 17 Nov 2026 20:23:04 +0800 Subject: [PATCH] =?UTF-8?q?feat(relay):=20=E6=96=B0=E5=A2=9E=E4=B8=8A?= =?UTF-8?q?=E4=B8=8B=E6=96=87=E7=BC=93=E5=AD=98=E4=B8=AD=E7=BB=A7=EF=BC=8C?= =?UTF-8?q?=E6=94=AF=E6=8C=81=E5=A2=9E=E9=87=8F=E4=B8=8A=E4=BC=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 每轮只发新增的 user/tool 消息,relay 查表拼接后再转发上游,慢上行链路省掉 90%+ 上传。 - 协议:X-Context-Id + X-Context-Hash(空 = 全量替换),不命中回 409 由客户端重发全量 - 不带 header 或模型没开白名单 → 完全透明转发 - 单会话上限与总量 LRU 两个阈值,不设条数上限(会在最需要增量时打回全量) - 响应原样 pipe,不解析 SSE、不改帧、不缓冲 - 零依赖,纯 node:http --- .gitignore | 1 + relay/Dockerfile | 6 + relay/README.md | 105 ++++++++++++++ relay/config.example.json | 15 ++ relay/src/server.js | 280 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 407 insertions(+) create mode 100644 relay/Dockerfile create mode 100644 relay/README.md create mode 100644 relay/config.example.json create mode 100644 relay/src/server.js diff --git a/.gitignore b/.gitignore index 39ed21c..78de88b 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,4 @@ app/server/version.json *.apk # 部署配置真身(含密钥,模板见 scripts/deploy.conf.example); deploy.conf +relay/config.json diff --git a/relay/Dockerfile b/relay/Dockerfile new file mode 100644 index 0000000..bec6f64 --- /dev/null +++ b/relay/Dockerfile @@ -0,0 +1,6 @@ +FROM node:22-alpine +WORKDIR /app +COPY src/ ./src/ +# 镜像内只放模板;真身部署时用 volume 挂进来 +COPY config.example.json ./config.json +CMD ["node", "src/server.js"] diff --git a/relay/README.md b/relay/README.md new file mode 100644 index 0000000..8946e82 --- /dev/null +++ b/relay/README.md @@ -0,0 +1,105 @@ +# Context Relay + +把「每轮重传全量历史」换成「只传增量」。挡在 `workbuddy2api` 前面,对上游透明。 + +**为什么不改上游**:`workbuddy2api` 一天几十个提交,fork 维护不起。这层只在两者之间做 +「查表 + 拼数组 + pipe」,不改协议、不改 SSE。 + +--- + +## 协议 + +客户端多带两个头: + +| header | 说明 | +|---|---| +| `X-Context-Id` | `::`,会话级唯一标识 | +| `X-Context-Hash` | 客户端认为本服务已存的那段消息的 sha256;**空字符串 = 全量替换** | + +请求体的 `messages` **只放新增**(首轮/压缩后放全量),其余字段原样。 + +### 三种走向 + +| 条件 | 行为 | +|---|---| +| 没带 `X-Context-Id`,或模型没开 store | 完全透明转发,和直连一致 | +| `X-Context-Hash` 为空 | 整段替换缓存 | +| 缓存存在且 hash 命中 | 缓存 + 新增拼起来转发 | +| 其他 | **409** `{"code":"context_mismatch"}`,客户端改发全量 | + +409 是唯一的重试信号:会话被压缩、本服务重启、缓存过期,全都走这一条路,客户端不需要 +自己判断「该不该发全量」。 + +--- + +## 配置 + +`config.json`(部署时放,不入库;模板见 `config.example.json`): + +```jsonc +{ + "port": 7865, + "upstream": "http://workbuddy2api:7863", + "max_body_mb": 64, + "store": { + "ttl_ms": 604800000, // 7 天 + "max_bytes": 5242880, // 单个会话上限,超了该会话不缓存(不影响别人) + "max_total_bytes": 268435456,// 全部会话总量闸,超了 LRU 淘汰 + "models": { "cn:*": true, "global:*": false } + } +} +``` + +- **单会话上限**:超过就不缓存这个会话,下次请求 409 → 全量,行为仍然正确 +- **不设条数上限**:条数上限会在「会话最长、最需要增量」的时候把人打回全量,正好反着来 +- **模型白名单**:精确匹配优先,其次只认尾部 `*` 的前缀通配;不写 = 不开 + +--- + +## 部署 + +```yaml +# docker-compose.yml + ctx-relay: + build: ./relay + container_name: ctx-relay + restart: unless-stopped + volumes: + - ./relay/config.json:/app/config.json:ro + networks: [agent-mcp-net] +``` + +nginx 侧只新增一条路径,不影响现有的 `/`: + +```nginx +location /v1c/ { + proxy_pass http://ctx-relay:7865/; + proxy_http_version 1.1; + proxy_set_header Connection ""; + proxy_buffering off; + proxy_read_timeout 3600s; +} +``` + +客户端 base URL 改成 `https:///v1c`。 + +--- + +## 观测 + +每个带 context 的请求打一行: + +``` +19:38:27 [relay] kicer:task-xxx delta=2 total=51 上传 3.1KB 省 196.9KB 缓存 1.2MB/256.00MB +``` + +`/health` 返回当前会话数与占用字节。 + +--- + +## 边界 + +- **内存态**:进程重启缓存即丢 → 一次全量重建,之后恢复增量 +- **并发**:同一 `X-Context-Id` 串行(core 本来就串行,这把锁只防两个客户端同时打) +- **流式**:响应原样 `pipe`,不解析、不改帧、不缓冲 +- **压缩**:等价于一次全量替换,无需特殊处理 diff --git a/relay/config.example.json b/relay/config.example.json new file mode 100644 index 0000000..91f2882 --- /dev/null +++ b/relay/config.example.json @@ -0,0 +1,15 @@ +{ + "port": 7865, + "upstream": "http://workbuddy2api:7863", + "max_body_mb": 64, + "store": { + "ttl_ms": 604800000, + "max_bytes": 5242880, + "max_total_bytes": 268435456, + "models": { + "cn:deepseek-v4.1-flash": true, + "cn:*": true, + "global:*": false + } + } +} diff --git a/relay/src/server.js b/relay/src/server.js new file mode 100644 index 0000000..716ef4c --- /dev/null +++ b/relay/src/server.js @@ -0,0 +1,280 @@ +#!/usr/bin/env node +'use strict'; +// 上下文缓存中继:把「每轮重传全量历史」换成「只传增量」。 +// +// 客户端带两个头: +// X-Context-Id :: +// X-Context-Hash 客户端认为本服务已存的那段消息的 sha256(空 = 全量替换) +// 命中就把缓存拼在新增前面转发给上游;不命中回 409,客户端改发全量。 +// 不带这两个头 → 完全透明转发,行为与直连一致。 +// +// 本服务只做三件事:查表、拼数组、pipe 响应。不解析 SSE、不改帧、不缓冲。 + +const http = require('node:http'); +const https = require('node:https'); +const fs = require('node:fs'); +const path = require('node:path'); +const crypto = require('node:crypto'); + +// ---------- 配置 ---------- +const DEFAULTS = { + port: 7865, + upstream: 'http://127.0.0.1:7863', + max_body_mb: 64, + store: { + ttl_ms: 7 * 24 * 3600 * 1000, + max_bytes: 5 * 1024 * 1024, // 单个会话上限 + max_total_bytes: 256 * 1024 * 1024, // 全部会话总量闸(安全阀) + models: {}, + }, +}; + +function loadConfig() { + const file = process.argv[2] || path.join(__dirname, '..', 'config.json'); + let raw = {}; + if (fs.existsSync(file)) { + try { + raw = JSON.parse(fs.readFileSync(file, 'utf8')); + } catch (e) { + console.error('[relay] 配置不是合法 JSON:' + file + ' → ' + e.message); + process.exit(1); + } + } + const store = Object.assign({}, DEFAULTS.store, raw.store || {}); + store.models = store.models && typeof store.models === 'object' ? store.models : {}; + return Object.assign({}, DEFAULTS, raw, { store }); +} +const CFG = loadConfig(); + +function log(...a) { + console.log(new Date().toISOString().slice(11, 19), '[relay]', ...a); +} + +// ---------- 模型白名单 ---------- +// 精确匹配优先,其次只认尾部带 * 的前缀通配(cn:*)。不写 = 不开。 +function storeEnabled(model) { + const m = CFG.store.models; + const name = String(model || ''); + if (Object.prototype.hasOwnProperty.call(m, name)) return m[name] === true; + for (const k of Object.keys(m)) { + if (k.endsWith('*') && name.startsWith(k.slice(0, -1))) return m[k] === true; + } + return false; +} + +// ---------- 缓存 ---------- +// key -> { hash, messages, bytes, expireAt, lastUsed } +// 两个字节数阈值,语义不同: +// max_bytes —— 单个会话上限,超了就这个会话不缓存(下次全量),不影响别人 +// max_total_bytes —— 全部会话总量闸,超了按 LRU 淘汰最久没用的 +// 不设条数上限:那会在「会话最长、最需要增量」的时候把人打回全量,正好反着来。 +const cache = new Map(); +let cacheBytes = 0; + +function sha256(s) { + return crypto.createHash('sha256').update(s).digest('hex'); +} +// 两侧(core 与本服务)都只认 JSON.stringify 的结果:字段顺序取自原始报文, +// 客户端拼出来的字符串与服务端一致。 +function messagesHash(messages) { + return sha256(JSON.stringify(messages)); +} +function byteLen(s) { + return Buffer.byteLength(s, 'utf8'); +} + +function touch (key, entry) { + entry.lastUsed = Date.now(); + // Map 插入顺序即 LRU 顺序:删了再插,等价于移到队尾 + cache.delete(key); + cache.set(key, entry); +} + +function evictIfNeeded() { + const max = CFG.store.max_total_bytes; + const now = Date.now(); + for (const [k, e] of cache) { + if (e.expireAt <= now) { + cache.delete(k); + cacheBytes -= e.bytes; + } + } + while (cacheBytes > max && cache.size) { + const oldest = cache.keys().next().value; + const e = cache.get(oldest); + cache.delete(oldest); + cacheBytes -= e.bytes; + log('LRU 淘汰 ' + oldest + '(' + fmtBytes(e.bytes) + ')'); + } +} + +function put(key, messages) { + const prev = cache.get(key); + if (prev) { cacheBytes -= prev.bytes; cache.delete(key); } + const bytes = byteLen(JSON.stringify(messages)); + if (bytes > CFG.store.max_bytes) { + // 单会话超上限:直接不缓存。不能截断(截断会破坏上下文),只能退回全量模式。 + log(key + ' 单会话 ' + fmtBytes(bytes) + ' 超过上限 ' + fmtBytes(CFG.store.max_bytes) + ',不缓存'); + return null; + } + const entry = { + hash: messagesHash(messages), + messages, + bytes, + expireAt: Date.now() + CFG.store.ttl_ms, + lastUsed: Date.now(), + }; + cache.set(key, entry); + cacheBytes += bytes; + evictIfNeeded(); + return entry; +} + +function get(key) { + const e = cache.get(key); + if (!e) return null; + if (e.expireAt <= Date.now()) { + cache.delete(key); + cacheBytes -= e.bytes; + return null; + } + touch(key, e); + return e; +} + +function fmtBytes(n) { + if (n < 1024) return n + 'B'; + if (n < 1048576) return (n / 1024).toFixed(1) + 'KB'; + return (n / 1048576).toFixed(2) + 'MB'; +} + +// ---------- 同 key 串行 ---------- +// core 本来就是串行发的,这把锁只防「同一会话被两个客户端同时打」导致拼接乱序。 +const locks = new Map(); +async function withLock(key, fn) { + while (locks.has(key)) await locks.get(key); + let release; + const p = new Promise((r) => (release = r)); + locks.set(key, p); + try { + return await fn(); + } finally { + locks.delete(key); + release(); + } +} + +// ---------- 转发 ---------- +function splitUrl(u) { + const m = /^(https?):\/\/([^/]+)(\/.*)?$/.exec(u); + if (!m) throw new Error('上游地址非法: ' + u); + return { mod: m[1] === 'https' ? https : http, host: m[2], base: m[3] || '' }; +} +const UP = splitUrl(CFG.upstream); + +const HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', + 'te', 'trailer', 'transfer-encoding', 'upgrade', 'host', 'content-length']); + +function forward(bodyBuf, req, res) { + const headers = {}; + for (const [k, v] of Object.entries(req.headers)) { + if (!HOP.has(k.toLowerCase())) headers[k] = v; + } + headers['content-length'] = bodyBuf.length; + + const out = UP.mod.request( + { host: UP.host.split(':')[0], port: UP.host.split(':')[1] || (UP.mod === https ? 443 : 80), + path: UP.base + req.url.replace(/^\/v1c/, ''), method: req.method, headers }, + (upRes) => { + res.writeHead(upRes.statusCode, upRes.headers); + upRes.pipe(res); // 流式原样回传:SSE 不受影响 + } + ); + out.on('error', (e) => { + if (!res.headersSent) { + res.writeHead(502, { 'content-type': 'application/json' }); + res.end(JSON.stringify({ error: { code: 'upstream_unreachable', message: String(e && e.message || e) } })); + } else { + res.destroy(); + } + }); + out.end(bodyBuf); +} + +function sendJson(res, status, obj) { + const buf = Buffer.from(JSON.stringify(obj)); + res.writeHead(status, { 'content-type': 'application/json', 'content-length': buf.length }); + res.end(buf); +} + +// ---------- 主流程 ---------- +const server = http.createServer((req, res) => { + if (req.method === 'GET' && req.url === '/health') { + return sendJson(res, 200, { status: 'ok', service: 'ctx-relay', conversations: cache.size, bytes: cacheBytes }); + } + + const chunks = []; + let size = 0; + const limit = CFG.max_body_mb * 1024 * 1024; + req.on('data', (c) => { + size += c.length; + if (size > limit) { + sendJson(res, 413, { error: { code: 'body_too_large', message: 'body > ' + CFG.max_body_mb + 'MB' } }); + req.destroy(); + return; + } + chunks.push(c); + }); + req.on('end', () => { + const raw = Buffer.concat(chunks); + const ctxId = String(req.headers['x-context-id'] || '').trim(); + const ctxHash = String(req.headers['x-context-hash'] || '').trim(); + + let body; + try { + body = JSON.parse(raw.toString('utf8')); + } catch (_) { + return forward(raw, req, res); // 非 JSON 一律透明转发 + } + + // 没带 context id,或模型没开 store → 原样转发 + if (!ctxId || !storeEnabled(body.model)) { + return forward(raw, req, res); + } + + withLock(ctxId, () => { + const delta = Array.isArray(body.messages) ? body.messages : []; + const deltaBytes = byteLen(JSON.stringify(delta)); + const entry = get(ctxId); + let messages; + + if (ctxHash === '') { + messages = delta; // 全量替换(首轮 / 压缩后 / 回退重发) + } else if (entry && entry.hash === ctxHash) { + messages = entry.messages.concat(delta); + } else { + log(ctxId + ' hash 不匹配,回 409(delta=' + delta.length + ')'); + return sendJson(res, 409, { + error: { code: 'context_mismatch', message: 'context hash mismatch, resend full messages with empty X-Context-Hash' }, + }); + } + + const saved = byteLen(JSON.stringify(messages)) - deltaBytes; + put(ctxId, messages); + log(ctxId + ' delta=' + delta.length + ' total=' + messages.length + + ' 上传 ' + fmtBytes(deltaBytes) + ' 省 ' + fmtBytes(saved > 0 ? saved : 0) + + ' 缓存 ' + fmtBytes(cacheBytes) + '/' + fmtBytes(CFG.store.max_total_bytes)); + + const outBody = Buffer.from(JSON.stringify(Object.assign({}, body, { messages }))); + forward(outBody, req, res); + }).catch((e) => { + if (!res.headersSent) sendJson(res, 500, { error: { code: 'relay_error', message: String(e && e.message || e) } }); + }); + }); +}); + +server.listen(CFG.port, '0.0.0.0', () => { + log('监听 0.0.0.0:' + CFG.port + ' → ' + CFG.upstream); + log('store: ttl=' + (CFG.store.ttl_ms / 3600000) + 'h 单会话≤' + fmtBytes(CFG.store.max_bytes) + + ' 总量≤' + fmtBytes(CFG.store.max_total_bytes) + ' models=' + JSON.stringify(CFG.store.models)); +});