QQ 机器人后端排障实录:dsh + 中转网关 + 桥接层的四层定位法

〇、这套东西是干什么的

一句话:让一个 DeepSeek 模型驱动的人格,活在 QQ 里跟我聊天,同时把模型请求收拢到自己搭的中转网关上。

它不是一个程序,是四层东西拼起来的:QQ 协议适配 → 桥接层 → 模型宿主 → 中转网关。任何一层出问题,表现出来的症状都可能长得很像,所以这篇主要写「怎么定位到到底是哪一层坏了」。

下面全部内容来自真实线上环境,涉及公网地址、密钥、账号的部分已做脱敏。

一、总体架构

QQ 群 / 私聊
  │  OneBot / 协议适配(snowluma,以 MCP 工具形式提供)
  ▼
qq-bridge  (Node, systemd: qq-bridge)
  ├─ roles/*.md    人格卡(每轮拼进 user 消息)
  ├─ state/        会话映射、当前角色
  └─ plugins/     agent preset、工具限制器
  │  HTTP RPC
  ▼
dsh-qq  (:3080, systemd: dsh-qq, profile=qq)
  │  OpenAI 兼容请求
  ▼
new-api 网关  (:3000, Docker)
  ├─ 渠道 2   本地代理 → 上游 A(只认带日期后缀的模型名)
  ├─ 渠道 49  上游 B
  └─ 渠道 51  上游 C(带输入内容审核)

旁路:
qq-admin  (:13101) ──nginx──► qqadmin.7998888.xyz:8443
dsh web  (:4000, 用户级 systemd) ──nginx──► dsh.7998888.xyz:8443

两个旁路都是私用管理入口,只做反代 + 证书,不对外宣传。

二、服务器上的目录与文件

路径 用途
~/qq-bridge 桥接层主体。源码 src/bridge.js(单文件,一万多行)、人格卡 roles/、日志 logs/、插件 plugins/
~/qq-admin 管理后台,server.js + auth.json(口令)+ sessions.json(登录态)
~/.dsh/profiles/qq dsh 的 profile:cordis.patch.yml 决定装哪些插件
~/.dsh/sessions/ 按工作目录分组的会话存档,这是排障的金矿(见第五节)
~/.dsh/vendor/dsh-purge 宿主补丁插件 v1.1.78,通过 link: 依赖挂进 profile
~/.dsh/prompt-inject.md 默认注入的提示词文件,约 21 KB,被塞进 system 消息
~/backups new-api 渠道表的 mysqldump 快照

三、服务与端口

unit 监听 作用
dsh-qq 127.0.0.1:3080 模型宿主,dsh --profile qq
qq-bridge 内部 QQ ↔ 模型 双向转换
qq-admin 127.0.0.1:13101 管理后台
dsh-web(用户级) 127.0.0.1:4000 浏览器版 dsh,独立实例
Docker: new-api 0.0.0.0:3000 中转网关 + MySQL 容器

三个系统级 unit 的共通点:Restart=always、RestartSec=3~5,都以 ubuntu 用户跑。

四、部署方式

4.1 模型宿主

全局安装后用独立 profile 隔离,不污染默认配置:

bash
npm i -g @deepseek-ai/dsh
dsh --profile qq --no-open --host 127.0.0.1 --port 3080

systemd 里必须显式给出 HOME、PATH、DSH_INSTALL_MODULES,否则它找不到自己的依赖;密钥走 EnvironmentFile= 而不是写进 unit。

4.2 桥接层

纯 Node,无构建步骤,npm i 后 node src/bridge.js 即可。配置在 config.json,人格卡按文件名映射到 roles/<名字>.md。

4.3 中转网关

Docker 起 new-api,渠道、令牌、倍率全在容器内的 MySQL 里。渠道信息可以直接改库,但必须同时改两张表:

mysql
-- channels 是「渠道元数据」,运行时真正读的是 abilities
update channels  set priority=100, weight=1 where id=<cid>;
update abilities set priority=100, weight=1 where channel_id=<cid>;
-- 改完必须重启容器刷新内存缓存
docker restart new-api
踩过的坑:只改 channels,前台看配置已经变了,但请求仍然按旧权重分发 —— 因为调度读的是 abilities。

4.4 反代

管理后台挂 8443 + 泛域名证书,登录接口单独限速,静态与快照一律不走缓存:

nginx
server {
    listen 8443 ssl http2;
    server_name qqadmin.<域名>;
    ssl_certificate     /etc/letsencrypt/live/wild-<域名>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wild-<域名>/privkey.pem;
    server_tokens off;

    location = /api/login {
        limit_req zone=qqadmin burst=6 nodelay;
        include /etc/nginx/snippets/qqadmin-proxy.conf;
    }
    location / {
        limit_req zone=qqadmin burst=40 nodelay;
        include /etc/nginx/snippets/qqadmin-proxy.conf;
    }
}

五、部署过程:照工程文档走完八个阶段

这套东西不是一次性装好的。它照着一份十二节的工程文档(协作文档里那份接入提示词)推进,压实成八个阶段:审查仓库 → 环境检查 → 部署桥接 → 装宿主端 → 配置双向 → 定人格 → 安全审查 → 端到端测试。文档的价值不在「写得多全」,而在它把每一步都要求「实际验证」——命令敲过不等于功能可用。下面把文档要求与线上真实结果并排摆开。

5.1 八个阶段与实际落地

阶段 文档要求 实际执行 结果
0 审查仓库 读 README / RULES / docs,核对版本与宿主兼容性,不靠仓库介绍推断功能 逐份读完,再打印 package.json 的版本、engines、scripts、依赖 版本 0.2.1-r1,node >=22.13.0,ESM,7 个运行依赖
1 环境检查 OS / Node / npm / git、宿主是否安装且 Web 在跑、协议端双端点是否通 逐项核,含端口占用 Node v24.18.1、CLI 0.2.1-rc.2、OneBot 的 WS 与 HTTP 端点都在
2 部署桥接 获取代码 → 装依赖 → 由模板生成配置(不覆盖已有真实配置)→ 审查安装脚本行为 照做,先看 postinstall 动什么 postinstall 会打协议端 SDK 补丁,属预期行为,需放行
3 装宿主端 先评估是否要跑 setup-dsh.mjs,确认不破坏现有 profile node scripts/setup-dsh.mjs qq(参数是 profile 名) 装 2 套 preset + 3 个 MCP + 2 个 bundle
4 配置双向 宿主地址/认证/模型标识、协议端双地址与鉴权、白名单默认拒绝 手工填,模板默认值不可直接用 provider 与模型标识两处必须改,见 5.9
5 定人格 先用仓库自带的安全 preset,不要一上来就换复杂角色 qq-chat-v2,核对工具面 全局工具仅 7 个,白名单只留必要项
6 安全审查 凭据不外泄、运行数据不进 git、工具权限最小化、不得为修连接关认证 逐条核到具体文件 密钥走 EnvironmentFile;state/ 与 config.json 忽略
7 端到端测试 A 基础服务 / B AI 链路 / C 私聊 / D 群聊 / E 异常恢复,五组分开跑 见 5.7 五组全过,异常恢复单独验证
8 交付 版本兼容结论、改动文件与原因、命令与真实结果、启停与排障方式 —— 就是本文

5.2 阶段零:先审仓库,别凭介绍推断

文档把这条放在第一位是有原因的:这类桥接项目普遍「README 写的是上一版」。真正决定能不能装起来的只有三个字段——版本、Node 下限、有没有 postinstall 副作用。

bash
# 版本、运行时下限、安装钩子,一眼看全
git clone <官方仓库> ~/qq-bridge && cd ~/qq-bridge
node -e "const p=require('./package.json');
  console.log(p.version, p.engines, p.type,
    Object.keys(p.dependencies||{}).length,
    p.scripts.postinstall || 'none')"

5.3 阶段一:环境检查

这张表不全绿就不要往下走,否则后面每个报错都会指向错误的方向。

检查项 期望 怎么查
Node ≥ 22.13(仓库 engines 声明) node -v
宿主 CLI 已安装,版本与仓库适配表对得上 dsh --version
宿主 Web 本机回环端口可访问 curl -s -o /dev/null -w "%{http_code}" 127.0.0.1:3080
协议端 WS OneBot v11 反向/正向 WS 已开 ss -lntp | grep 3001
协议端 HTTP HTTP API 已开,且与 WS 不同端口 curl -s 127.0.0.1:13000/get_status
运行数据 存在时不要覆盖,先备份 ls config.json state/
文档特别强调的一点:协议端是独立第三方软件,安装、初始化、扫码登录必须由本人完成,不得打包进项目,也不得自动下载或代其登录。实际部署里它是独立容器,端口全部只绑回环地址,访问一律通过 SSH 隧道——这一条既是许可要求,也是暴露面控制。

5.4 阶段二~三:装桥接,再装宿主端

两条腿分开装。桥接是纯 Node,没有构建步骤;宿主端靠一个 setup 脚本把 preset 和 MCP 挂进 profile。

bash
npm i                        # postinstall 会给协议端 SDK 打补丁,属预期
cp -n config.example.json config.json   # -n:已存在就不覆盖

# 参数是 profile 名,默认值是 web,QQ 侧必须显式传 qq
node scripts/setup-dsh.mjs qq

setup-dsh.mjs 干三件事:装 qq-chat / qq-chat-v2 两套 agent preset(作为 bundle 的 patch 层插入,不再写老的 preset 目录)、在 cordis.patch.yml 里挂三个 MCP(协议端、协议端宿主、安全搜索)、在 profile 的 package.json 里注册两个 bundle。脚本是幂等的,重复跑不会叠加,但跑之前仍要先备份 profile 的那两个文件——它会改写它们。

5.5 阶段四:把两条腿接上

配置里两个对端各占一段。任何一段错,表象都是同一句「不回话」,所以两段都要先单独验通。

json
{
  "dsh": {
    "baseUrl": "http://127.0.0.1:3080",
    "provider": "new-api",
    "model": "deepseek-v4.1-flash",
    "reasoningEffort": "off",
    "allowRemote": false
  },
  "snowluma": {
    "wsUrl": "ws://127.0.0.1:3001",
    "httpUrl": "http://127.0.0.1:13000",
    "accessToken": "<协议端令牌>"
  },
  "allow": { "private": [<QQ>], "groups": [] },
  "allowAllWhenEmpty": false
}

三个必须对齐的点:① 模型标识要用宿主认的名字,不一定等于官网 API 的名字;② HTTP 与 WS 是不同端口、不同鉴权,不能假设同源同令牌;③ 白名单为空时按 allowAllWhenEmpty 走拒绝,不要为了方便测试长期放开。

5.6 阶段五~六:先定人格,再做安全审查

文档在这两步上很克制:先用仓库自带的安全 preset 跑通,不要一上来就换成复杂角色。理由是角色设定会改变工具调用倾向,一旦出问题,你分不清是链路坏了,还是人格让它乱调工具。实际用的是 qq-chat-v2,只注册 7 个全局工具,白名单也只列必要项——工具面小,出错的面就小。

安全审查不是勾选清单,每一条都要落到一个具体文件或参数上:

审查项 落地做法
API 密钥 只放 systemd 的 EnvironmentFile=(权限 600),不进 unit、不进 config.json、不进日志
运行数据不进 git .gitignore 覆盖 config.json / state/ / logs/
工具权限 preset 只注册少量全局工具;执行期由工具守卫兜底。约束器报「未知工具」多半是白名单与实际工具面不匹配,属噪音
管理入口 后台只绑 127.0.0.1,外网走 nginx + 证书 + 独立限速;不为修连接问题关认证、绕过鉴权
SSRF 外部请求走 safe 搜索 MCP,禁内网地址;不要为「能搜到」而放开任意 URL

5.7 阶段七:端到端测试 A~E

用例 手段 结果
A 基础服务 unit 状态 + 协议端 get_status / get_login_info 通过
B AI 链路 独立会话跑一轮,核对模型标识与回包事件 通过
C 私聊 白名单内账号多轮对话 + /reset 重置 通过
D 群聊 触发规则命中、两个群上下文互不串线 通过
E 异常恢复 停宿主看报错是否可辨;重启桥接看会话映射是否还在 通过
一个必须知道的测试限制:机器人会忽略自己发出的消息(user_id === self_id),所以私聊无法自测。可行做法是本地起一个假的 OneBot 上游,把 wsUrl 临时指过去,灌一条私聊事件,看它是否回 send_private_msg;验完立刻把地址改回、把测试号从白名单删掉。真实 QQ 端的「已通过」不能拿这个结果冒充。

5.8 阶段八:启停与日志

bash
systemctl status  qq-bridge dsh-qq qq-admin
systemctl restart qq-bridge
journalctl -u qq-bridge -f          # 系统侧日志
tail -f ~/qq-bridge/logs/bridge.log # 业务侧日志,只在事件时写

bridge.log 是事件驱动的,安静期停更是正常现象,不要据此判断服务挂了——先看 unit 状态,再问协议端要 get_status。

5.9 文档没写、实际必须补的四件事

文档假设 实际情况 补的动作
配置模板的 provider 可直接用 模板默认值指向的 provider 在本机没有凭据,回合直接以错误结束 抄一份已跑通实例的 provider 段,密钥走 EnvironmentFile
推理强度按默认给最大值 上游不一定吃这套参数,且这类对话要的是快 模型侧把 off 映射成上游的合法值,配置里明确写 off
协议端由本人安装登录即完事 容器化后端口全绑回环,公网根本连不上 本地端口 → SSH 隧道;隧道断开不等于服务挂,先查协议端状态
装完按文档跑测试就算通过 第一次启动几乎必然卡在 provider 或模型标识上 把「单轮最小请求能回包」当成第一道验收,再谈人格和安全

六、dsh-purge:宿主补丁层的部署与运维

前面四层都是「装上去就能用」的组件,这一章要讲的插件不是。它不改模型、不走网络,而是直接改写宿主自己 node_modules 里的代码——把提示词拼装、审批策略、沙箱默认值这些位置上的原文替换掉,宿主下次加载就是被改过的版本。

这类「改别人包里的代码」的方案,故障形态和普通插件完全两回事:插件加载成功,不等于功能生效。它的生效与否取决于「补丁有没有真的落进目标文件」,而这两件事在日志里看不出区别——第 7.1 节就是踩这个坑的完整过程。

6.1 它由哪几个部件组成

先看清结构再动手。这个包运行依赖是 0,全部逻辑在自己目录里,这也是它能被 vendor 进项目、用 link: 挂进 profile 的前提。

部件 路径 作用
包元信息 package.json 版本 1.1.78,ESM(type: module),main=lib/index.js,注册 CLI bin=dsh-purge,node>=18,运行依赖 0
补丁引擎 lib/core.js 锚点表 + 替换 + 备份,是整包的主体;旧版审计记录里 dsh-purge 标记出现 329 处
插件入口 lib/index.js 向宿主注册 purge_apply / purge_revert / purge_status 三个工具,并声明 inject: [systemPrompt, tools]
重打入口 lib/reapply.js、bin/dsh-purge.js 启动自愈逻辑与 CLI 子命令,两者共用同一套锚点表
包级补丁 cordis.patch.yml 不经手写即可生效的那部分:关掉旧的红队包、清空 system-prompt 的 harness 身份与人格前后缀
附带模块 presets/redteam、lib/redteam 演练台。与补丁逻辑互不依赖,关掉它不影响清洗

6.2 部署四步

顺序不能乱:先落地 → 再挂依赖 → 再注册 → 最后应用。跳过第二或第三步,插件会「看起来装好了但根本没被加载」;跳过第四步,就是第 7.1 节那个空转。

第一步,放进 vendor 目录并核对版本。不要直接丢进 node_modules——宿主升级会把那里整个覆盖掉。

bash
mkdir -p ~/.dsh/vendor
# 把发行包解压或克隆到 ~/.dsh/vendor/dsh-purge
grep -m1 '"version"' ~/.dsh/vendor/dsh-purge/package.json

第二步,用 link: 挂进 profile 的依赖与 bundles。这两处都要写。只写依赖不写 bundles,宿主不会把它当组件加载。

json
{
  "name": "dsh-profile-qq",
  "private": true,
  "dependencies": {
    "dsh-purge": "link:/home/ubuntu/.dsh/vendor/dsh-purge"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-purge"
      ]
    }
  }
}

第三步,在 profile 的 cordis.patch.yml 里 insert 一条本体。inject 声明它要挂到哪两个服务上,config 是它自己的开关。

yaml
- insert:
    - id: dsh-purge
      name: dsh-purge
      inject: [ systemPrompt, tools ]
      config:
        enabled: true
        autoApplyOnStart: true      # 关键:见 6.5
        autoUpdateOnStart: false
        autoRevertOnMissing: false
        injectOnce: false
        stripMnemon: true
        verbose: false
        postPromptOrder: 5100

第四步,应用一次并重启宿主。没跑这一步,前面三步只是「登记」,一行代码都没改。

bash
node ~/.dsh/vendor/dsh-purge/bin/dsh-purge.js --apply
systemctl restart dsh-qq
# 复核:必须看到「0 待清洗」
node ~/.dsh/vendor/dsh-purge/bin/dsh-purge.js --status | grep -E "备份|补丁|注入状态"
一句话判据:只看一个数字就知道有没有生效:「待清洗」必须为 0。待清洗是 0 以外的任何值,都说明有补丁点没落进文件,功能一定不全。

6.3 补丁机制:锚点、标记、备份

它不是「整文件替换」,而是按锚点定位到具体那一行再改。每个补丁点有编号、名字、类别和状态,跑一次 --status 就能看到全表:

text
dsh-purge 状态 / Status
  宿主 / surface web
  插件根 / root  .../@deepseek-ai        ← 54 个目标条目
  备份 / backup  有 / yes
  注入文件       ~/.dsh/prompt-inject.md
  注入状态       default

  补丁 66/82 已清洗, 0 待清洗
    ✓ [#1 ] WORKSPACE_CONTEXT_INTRO        提示词/Prompt — applied
    ✓ [#7 ] SANDBOX_MODE_DEFAULT           代码/Code     — applied
    · [#76] PRESET_UNRESTRICTED_IDENTITY_STRIP 提示词 — na
    · [#71] LIANGSHEN_IDENTITY_LINE        提示词/Prompt — missing_file
    · [#80] MINIMAL_OFFICIAL_TOOLSET       工具/Tools    — skipped

线上这一份的实际分布,82 个补丁点覆盖 54 个目标条目,按类别分是 46 处代码、25 处提示词、11 处工具:

状态 数量 含义 要不要管
applied 66 补丁已写进目标文件,文件里带标记注释 正常
na 11 当前宿主上没有对应端点。桌面端专属的项在 Linux 服务端永远是这个状态 不用管
missing_file 1 锚点声明的目标文件在宿主里不存在(版本差异) 不用管
skipped 4 锚点文本对上了但前置条件不满足,主动跳过 不用管
最常见的误判:把 16 个非 applied 当成「插件坏了」。实际 66/82 才是这台机器的正常值——剩下的要么是桌面端专属,要么是宿主压根没那个文件。判断标准只有一个:「待清洗」是否为 0。

改过的文件旁边会留一份 *.dshpurge.bak,这就是 --revert 的依据。所以这个插件的回滚是「文件级精确回滚」,不需要重装宿主,也不会连带丢掉别的插件改动。

6.4 CLI 与运行时工具

同一套能力有两个入口:命令行给运维用(服务挂了也能跑),工具给对话里的模型用(会话里能自己查状态)。

入口 命令 / 工具名 用途
CLI --status 打印目标清单、备份状态、82 个补丁点的逐个状态。排查第一步永远是这个
CLI --apply 按锚点表写补丁,同时生成 *.dshpurge.bak 备份
CLI --revert 从备份逐文件还原,把宿主退回原始版本
CLI --edit 打开注入文件编辑
CLI --uninstall 撤掉补丁并清注册
工具 purge_status 会话内查状态,等价于 --status
工具 purge_apply 会话内触发应用
工具 purge_revert 会话内触发回滚

只有前三个(status / apply / revert)会被注册成对话工具,其余三个是纯 CLI。这个区别很实用:宿主起不来的时候,CLI 是唯一还能用的入口。

6.5 配置项:只有三个会咬人

可配的键有二十多个,但绝大多数是内容侧参数。真正影响「能不能生效」的只有三个:

键 默认 影响 建议
autoApplyOnStart false 启动时自动重打补丁。false 意味着宿主重启也不会把丢掉的补丁补回来 设 true
autoRevertOnMissing false 锚点找不到时是否自动回滚。true 有风险:宿主小版本升级后锚点失配,可能把已生效的补丁一并撤掉 保持 false
autoUpdateOnStart false 启动时自动更新插件本身。更新会重写锚点表,有引入新 skipped 的风险 保持 false,手动升级

其余常见键:enabled 总开关、injectOnce 是否只在首轮注入、stripMnemon 是否剥离记忆块、verbose 打印详细日志、postPrompt 与 postPromptOrder 追加一段高优先级消息、autoRetry / retryMax 失败重试、autoContinue / continueMax 截断续写、hooksDenyBypass 与 capabilityProtocol 两个工具权限相关的开关。

6.6 状态文件:判断「到底打上了没有」的唯一依据

插件在 ~/.dsh/dsh-purge/ 下维护几个小文件,排查时比日志可靠得多——日志会滚,这些不会:

文件 内容 用途
applied.json 本次应用的时间与结果摘要 判断「最后一次 apply 是什么时候、成功没有」
installed-rev 已安装的插件版本号 和 package.json 对比,确认跑的是哪个版本
override-state.json 被覆盖条目的状态快照 排查「为什么某个补丁点被跳过了」
同目录下的 *.bak-purge-<时间戳> 应用前的配置文件备份 区分「插件配置被改过」和「补丁没打上」

6.7 三个复发点

复发点 症状 对策
升级宿主覆盖 node_modules。npm i -g @deepseek-ai/dsh 会把 @deepseek-ai/* 整目录重写,补丁全部丢失 升级后第一次启动一切正常,但补丁效果全无;--status 显示大量待清洗 升级后立刻跑一次 --apply;或开 autoApplyOnStart
锚点随版本漂移。宿主改了一行原文,锚点就匹配不上 个别补丁点变成 skipped,功能「少一块」而不是全丢 每次升级后看 --status,确认待清洗为 0;有 skipped 再看 override-state.json
只在配置里重新登记、没有重新应用。改过 cordis.patch.yml 之后以为已经恢复,其实补丁是空的 插件加载正常、三个工具都在,但输出里一丝补丁痕迹都没有 任何一次还原或改动后,都跑一遍 --apply + --status
最隐蔽的那个:第一条有时间差陷阱:升级当下不会报任何错,插件照常加载,只有功能悄悄消失。所以「升级宿主」这个动作必须和「验证待清洗 = 0」绑成一个流程,中间不能省。

6.8 运维清单

bash
# 1. 任何改动后第一步:看真实覆盖率
node ~/.dsh/vendor/dsh-purge/bin/dsh-purge.js --status \
  | grep -E "备份|补丁|注入状态"

# 2. 待清洗不为 0 → 应用
node ~/.dsh/vendor/dsh-purge/bin/dsh-purge.js --apply

# 3. 重启对应实例(qq 走 systemd,web 是用户级)
systemctl restart dsh-qq
systemctl --user restart dsh-web    # 注意是用户级

# 4. 出问题要退回原版
node ~/.dsh/vendor/dsh-purge/bin/dsh-purge.js --revert

# 5. 确认宿主文件里确实有标记(数量≈39)
grep -rl "dsh-purge" ~/.npm-global/lib/node_modules/@deepseek-ai/dsh/node_modules/\
  --include="*.js" | wc -l

最后一条是外部交叉验证。不要只信插件自己报的状态——插件的状态是它自己写的,直接去目标文件里 grep 标记,才能证明代码真的改了。这两个结论一致,才算生效。

七、排障记录:六个「看起来是 A,其实是 B」

7.1 插件明明加载了,功能却没生效

现象:宿主的补丁插件状态显示已注册,三个子命令工具都在,但输出里一丝补丁痕迹都没有。

定位:用插件自带的 --status 看真实覆盖率:

status
备份 / backup  无 / no
补丁 5/82 已清洗, 60 待清洗

根因:前一天做过一次还原(目录里留着 *.bak-purge-<时间戳>),之后只在配置里把插件重新登记回去,没有重新「应用」。而 profile 里 autoApplyOnStart: false,所以重启也不会自动补,一直空转。

修复:手动应用一次,并把 autoApplyOnStart 改成 true 防复发。结果 66/82 已清洗、0 待清洗,39 个宿主文件带上标记。剩下 16 条是 na(桌面端专属)或 missing_file(宿主没这个文件),正常。

教训:npm i -g 升级宿主会覆盖 node_modules,补丁全部丢失。这类「改别人包里的代码」的方案,天生带升级即失效的属性,必须配自愈。

7.2 以为要手动重启的进程,其实是用户级 systemd

现象:另一个实例跑在 4000 端口,进程 ps 看是 MainThread,直觉是 nohup 起的野进程,一直不敢动。

定位:别猜,直接问 systemd:

bash
systemctl status <PID>
XDG_RUNTIME_DIR=/run/user/<uid> systemctl --user list-units 'dsh*' --all

根因:它是用户级 unit(~/.config/systemd/user/dsh-web.service),sudo systemctl 完全看不到它,所以「重启了没效果」。

修复:加 XDG_RUNTIME_DIR 用 --user restart。顺带一个副作用:这个实例每次重启都会换访问 token,旧链接直接失效。

7.3 一条日志 112 KB,把真信息彻底埋了

现象:日志里每轮都刷 restrict 失败 78/82,看着像严重故障。

定位:量一下单行长度就明白了 —— 每次报错都把整张已知工具清单拼进消息,78 条拼成一行 112 KB。

根因:不是故障。那个人格 preset 只注册了 7 个全局工具,白名单里抄的是标准工具集(bash / read / write / glob…),在当前组合下本来就不存在。报错恰恰证明硬边界是好的。

修复:改成只打印计数 + 3 个样例,完整清单落到诊断文件。单次启动日志 112 KB → 750 B,限制逻辑一行没动。

教训:日志噪音不是「不好看」的问题,它会让人把正常状态误判成故障,反过来也可能让真故障沉底。

7.4 报错文案来自上游,不是本地代码

现象:用户侧收到

error
Failed to create stream: failed to generate stream from <上游>:
failed to invoke model 'invalid' with streaming:
request failed with status 404: {"message":"Model 'invalid' not found"}

本地代码里 grep invalid 一个字都搜不到,一度以为是本地模型名配错了。

定位:绕过网关,拿渠道的 base_url + key 直连复现,同一段文案原样返回 → 确认是上游的错,本地只是透传包装。

根因:那个渠道的 model_mapping 把一个模型名指到了上游不存在的目标。同期还有一条 403「Input text may contain sensitive information」,也在另一个上游。

方法论:见到陌生报错先分层——直连上游复现一次,能复现就是上游,不能才是自己。这一步能省掉大半瞎猜。

7.5 网关重试的「降层陷阱」

这是本篇最有价值的一条,因为它反直觉。

现象:主渠道偶发 403,重试之后不但没救回来,反而总是撞到另一个早已失效的渠道上,把错误升级成 404。

定位:翻 new-api 的 model/ability.go 源码:

getPriority()(rc.23)
// retry 不是「重试次数」,而是「优先级层下标」
// 第 N 次重试取第 N 层,层内才按 weight 随机
if retry >= len(priorities) {
    retry = retry % len(priorities)   // 层用完了才兜回
}

根因:当时的分层是 [100: 健康A, 健康B] / [0: 三个死渠道]。健康 B 虽在同一层,但重试只会往下一层走,不会在同层再抽一次 —— 所以必然掉进 0 层的死渠道。

修复:把失效渠道从该模型的候选里彻底移除,让优先级栈只剩一层 [100],重试被取模兜回本层,才有 50% 概率换到健康的那台。

候选布局 403 后的走向 结果
两层 [健康×2] / [死×3] 降到 0 层死渠道 错误升级成 404
一层 [健康×3] 取模兜回本层重抽 约 2/3 概率直接成功

另外确认了两个参数:重试码范围包含 401-407 / 409-499,403 是会重试的;RetryTimes=3,而自动禁用渠道是关着的(开着反而容易误伤主力)。

7.6 改了配置没效果,真凶在会话历史里

现象:调整了人格设定,重启也做了,实测每条回复仍然是老样子。

定位:不猜,去看会话存档 ~/.dsh/sessions/<工作目录>/session-*/session.v4.jsonl.zstd。它是 zstd 压缩的 JSONL,每个事件一行:

bash
# 事件类型分布
zstdcat session.v4.jsonl.zstd | python3 -c "
import json,sys,collections
c=collections.Counter()
for l in sys.stdin:
    try: d=json.loads(l)
    except: continue
    c[d.get('type')]+=1
for k,v in c.most_common(): print(v,k)"

# 直接数某种措辞在历史里沉淀了几次
zstdcat session.v4.jsonl.zstd | grep -o "某个措辞" | sort | uniq -c

根因:历史里已经堆了十几次同一种收尾说法,模型每轮都在读自己上一版怎么回答,于是稳定复现同一种风格。配置(人格卡 / 系统注入 / 预设)三层全部正常,问题在第四层:上下文。

修复:桥接层有 /reset(等同 /new,仅管理员可用)。它做的事是把会话 ID、最近消息缓存、排队中的消息全部作废,下一句自动建新会话;长期记忆不受影响。重置完,同样的配置立刻正常。

四层定位法:判断「改配置为什么没效果」时按顺序排——配置层(人格/注入/预设有没有进请求)、路由层(请求落到哪个渠道、重试怎么走)、缓存层(进程内缓存是否失效)、上下文层(历史里的自我模仿)。前三层都能从日志看出来,第四层只能翻会话存档。

7.6.1 顺带一个缓存细节

人格卡的读取缓存键设计得比较讲究:文件名 + 文件大小 + mtime。只带 mtime 的话,在秒级粒度的文件系统上同一秒内重写会命中旧缓存,每条提示词都注入旧人格;带上文件名则切换角色永不误命中,带上 size 则原地重写也能击穿。

实践意义:改完人格卡不用重启桥接层,只要内容长度变了就会自动重读。

八、命令速查

要做的事 命令
补丁覆盖率 node ~/.dsh/vendor/dsh-purge/bin/dsh-purge.js --status
重新应用 / 回滚 ... --apply / --revert
重启模型宿主 systemctl restart dsh-qq
重启 web 实例 XDG_RUNTIME_DIR=/run/user/<uid> systemctl --user restart dsh-web
渠道分流统计 docker logs new-api | grep "record consume log" | grep -o "channel_id\":[0-9]*" | sort | uniq -c
查看会话事件 zstdcat session.v4.jsonl.zstd | head
渠道表备份 docker exec <db> mysqldump ... channels abilities > backups/$(date +%F-%H%M%S).sql

九、复发风险与运维要点

风险 触发条件 处置
补丁全丢 升级宿主包 靠 autoApplyOnStart 自愈;版本大跳时会有 skipped,需看 --status
优先级层被重置 在后台「保存」渠道 保存动作会按 channel.priority 重建 abilities,回跑接入脚本
上下文自我锚定 长期会话里形成稳定风格 改完配置先 /reset 再验证,否则会被旧风格稀释
上游账号态变化 余额、key、实名、风控 直连探测确认 200 再动配置,先测后改

最后一条经验:改任何共享入口(网关、渠道权重)之前先备份、先隔离测试。这次的兜底渠道验证就是在临时把其他渠道 enabled=0 后跑「只剩它一个」的场景,确认 4/4 成功,再靠脚本的 finally 自动还原。否则你永远不知道那条兜底链路到底通不通。

十、写在最后

这套东西真正难的不是把它搭起来,是出问题时知道该看哪一层。日志会骗人(5.4)、配置会骗人(5.1)、进程列表会骗人(5.2)、甚至「改了没效果」这件事本身也会骗人(5.6)。

所以现在我的习惯是:任何一个症状,先问「这是哪一层的表现」,再用能直接证伪的手段去验 —— 直连上游、数日志字节、翻会话存档、问 systemd。少猜一层,就少改一次配置。

© 版权声明
THE END
喜欢就支持一下吧
点赞5 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容