Skip to content
速览
  • 搭起来容易,用起来要一直修,这是两回事
  • 修掉的问题有五个,修不掉的有一个,还有一类不该由我修
  • 替代品不是另一个成品软件,是自己写的那套工具
  • 最后卸载时,真正花时间的不是删,是分清什么丢了回不来

半年前我在这台笔记本上搭了一套论文研究用的工作流。三个服务串起来:LiteLLM 把一堆免费模型聚合成统一网关,Dify 用 Docker Compose 跑起来做编排,再接一个自己写的监控面板。双击一个 start-all.bat,三个窗口起来,就算开工了。

现在这套东西已经卸载了。

在说怎么卸的之前,得先说为什么卸。原因不是"它坏了"——它没坏,是每次开机都要重新面对一圈可能出问题的环节。我把前后遇到的所有故障记了下来,一共十几个,修完之后回头一看,这些故障其实是分层的。

修到最后,才发现问题是分层的第三层:设计代价 —— 不是 bug,是这类工具本来的样子每个环境都要单独配一遍 · 服务连不上就只能干等 · 能力上限锁在别人给的表单里→ 换掉这套东西才会消失第二层:偶发复发 —— 知道怎么修,但如果不用它就不会犯容器 DNS 解析偶发失效 · 重启后容器 IP 变了但缓存没刷新→ 修一次好一阵,代价是每次复发都要手动重建网络(约 2 分钟)第一层:已彻底修复 —— 修一次,永久免疫路径硬编码 · 批处理延迟变量 · 端口 TIME_WAIT · 事件监听器堆积 · 中文编码冲突→ 这些问题不会再出现,但它们是当时耗掉最多时间的部分剩下的两件事没修:偶发的那层修不掉,设计那层不该由我修判断一个自建服务要不要留,不看它出了多少问题,看它有几层问题修不掉

这篇就按这三层来讲。

第一层:能彻底修掉的问题 ​

这一层有五个。修完就永久免疫,不会再犯。但它们是当时耗时间最多的部分,而且每一个都长得不像它真正的样子。

1. 端口"没人占用"但绑不上 ​

监控面板起不来,报 EADDRINUSE: address already in use。

第一反应是上个进程没退干净。但 netstat -ano | findstr :5000 查了一遍,端口不在列表里。进程也没了,端口也没占,那到底是谁占着。

根因是 TCP 的 TIME_WAIT 状态。连接关闭后,端口不会立刻释放,会被内核保留两到四分钟,确保最后一个确认包能送达。这个状态下端口被内核攥着,但常规的 netstat 输出里看不到它。

所以「杀进程再启动」这条常规路子必然失败:杀进程解决不了内核状态。

修的时候动了两个地方,一个治标一个治本:

js
// 监控面板:允许直接绑定处于 TIME_WAIT 的端口
srv.listen({
  port: DASH_PORT,
  host: "0.0.0.0",
  reuseAddr: true
}, () => { /* ... */ });
bat
rem 启动脚本:杀完旧进程先等几秒,别立刻起   [!code ++]
for /f "tokens=5" %%a in ('netstat -ano ^| findstr ":5000 "') do (
    taskkill /F /PID %%a >nul 2>&1
)
timeout /t 3 /nobreak >nul

记住这个组合

「端口没被占用,但绑定失败」基本就是 TIME_WAIT。诊断命令是 netstat -ano | findstr TIME_WAIT,治本是给 socket 加 reuseAddr。这类现象在频繁重启的短连接服务上最常见——恰好就是自己搭东西时的常态。

2. 重试逻辑把自己炸了 ​

修完端口问题,新问题冒出来:日志里重试次数不是 1、2、3、4、5,而是 1、2、4、8、16 这样翻倍。重试五次的逻辑,实际跑了十几次。

看了一眼重试函数就明白了:

js
// 错误写法:每次重试都往同一个 server 上加一个新监听器
function startServer(retries) {
  srv.on("error", e => {
    if (e.code === "EADDRINUSE") {
      setTimeout(() => startServer(retries + 1), 4000);
    }
  });
}

on() 是追加,不是替换。每次递归调用都往同一个对象上叠一个新监听器,它们会同时触发,每个都再调一次 startServer,每个又叠一个。

修法是换成只触发一次的 once(),并且先清掉旧的:

js
// 正确写法:先清空再挂,且只挂一次
function startServer(attempt) {
  serverInstance.removeAllListeners("error");
  serverInstance.listen(port, host);
  serverInstance.once("error", e => {
    if (e.code === "EADDRINUSE" && attempt < 5) {
      setTimeout(() => startServer(attempt + 1), 4000);
    }
  });
}

从别的语言过来会踩这个

在 Java 或 C# 里,= 是替换、+= 才是追加,习惯了两者并存。Js 里 on() 只有追加语义,没有"替换全部监听器"的语法,必须显式调用 removeAllListeners()。加上重试这种本身就带递归的逻辑,就是指数爆炸。

3. 中文注释把网关搞崩了 ​

有一阵子,双击启动脚本后网关窗口一闪而过,监控面板的看门狗就反复打印"正在重启网关"。启动脚本的输出里还有一堆乱码,类似 '湰' 不是内部或外部命令。

事情是这样一步步断下去的:

配置文件里有中文注释(UTF-8)
  → 系统 Python 默认按 GBK 读文件
  → UnicodeDecodeError
  → 网关启动瞬间崩溃
  → 窗口闪退
  → 看门狗发现网关挂了,重启
  → 又崩 → 死循环

这是最典型的"表象和根因隔了好几层"——看到的是看门狗在疯狂重启,实际是编码问题。

一行环境变量解决:

bat
rem 让 Python 的所有文件读写都按 UTF-8,不跟随系统区域设置   [!code ++]
set PYTHONUTF8=1
litellm --config config.yaml --port 4000

中文 Windows 上这条几乎万能

碰到莫名其妙的闪退、乱码、解码错误,先怀疑文件编码。Python 的 open() 默认用系统区域编码(中文 Windows 是 GBK),PYTHONUTF8=1 一行绕过,不用改任何代码。批处理文件里的中文注释也是同类问题——中文 Windows 的 cmd 按 GBK 解析,而编辑器常存成 UTF-8。

另外两个 ​

剩下两个没上面这么绕,一句话说完:

  1. 路径硬编码:项目换过盘,脚本里还写着旧目录。纯粹是搬家没更新,改完就好。
  2. 批处理延迟变量:set /a counter=counter+1 配 if !counter! lss 10,但脚本没开延迟扩展,!counter! 被当字面字符串,判断永远为假,循环永远不退出。换成 for /l 就好了,不需要延迟扩展。

第二层:修不掉,只能等它犯 ​

这一层只有一个问题,但它是让我真正开始动摇的那个。

容器日志里出现这个:

redis.exceptions.ConnectionError: Error -3 connecting to redis:6379.
Temporary failure in name resolution.

同一个网络里的两个容器,突然解析不了对方的容器名了。这是 Docker Desktop 在 Windows 上的偶发问题:重启之后容器 IP 变了,但 DNS 缓存没跟着刷新。

修法是完整的重建,不是重启:

操作效果
restart只重启进程,保留网络和 IP
stop + start同上,网络不动
down + up -d重建网络,DNS 刷新

down + up 之后要等三十到六十秒让服务初始化完,前后约两分钟。

这里的问题不是"能不能修"

两分钟能修好,一行命令的事。问题在于它复发的时机完全不可控——你没法预测哪次开机它会犯。于是每次开工前你都得先赌一次,赌输了就先花两分钟,而且得先意识到"是这个老毛病又犯了",而不是又去查一遍别的。

我一开始还试过别的路子。既然每次开机都可能要重建网络,那干脆把整套东西做成开机自动重建。做了一半停下来了——为了让一个偶发问题不影响使用,我搭了一套更复杂的自动化,而自动化本身又多了几个可能坏的地方。这是典型的负收益。

第三层:不该由我修的问题 ​

到这里我停了一下,问自己一个问题:这些问题是从哪来的?

前两层是"环境和你作对",但还有一类,是这类工具本来的形态决定的:

  1. 每个环境都要单独配一遍。 换个地方部署,这一套配置、密钥、目录挂载都要重来。
  2. 服务连不上就只能干等。 面板没起来,整个流程就卡在那里,没有降级路径。
  3. 能力上限锁在别人给的表单里。 这是最要紧的一条——我想加一个新环节(比如从摘要里自动抽出代码仓库地址),得先在脑子里翻译成它那套节点和连线的形式,再拖拽连好。我花在"把想法翻译成它的界面"上的时间,比花在想清楚这个想法上还多。

这一层不是 bug,所以修不掉。只能换掉。

替代品:不是另一个成品软件 ​

想清楚第三层之后,选型其实没有纠结很久。我先试过几个方向:

方向为什么没走
换一个同类可视化编排平台第三层的问题一模一样,只是换个界面重新配一遍
留在原地,继续修第一层已经修完了,第二层修不掉,第三层不该修
自己写一套工具选它

选第三条的理由就一个:我要的那些环节,用代码写出来比拖拽更快。

最后成型的是一套自己写的工具,端到端可跑:丢一个 PDF 进去,它自己拆模块、去检索、打分、给出缝合方案。跑代码的部分交给另一台有显卡的机器,用轮询去取任务。

对比一下就清楚了:

可视化编排平台自己写的工具
加一个新环节想清楚 + 翻译成节点连线 + 拖拽配置想清楚 + 写代码
换环境部署配置、密钥、挂载都要重来一套代码,带走就行
中途失败卡在界面上等有日志,能断点重试
排查问题看容器日志、看界面报错看自己的日志
启动开销十几个容器按需启动

这个对比里最容易被忽略的一行

是「排查问题」那行。可视化编排的代价不止是搭起来慢,而是出问题的时候,你排查的是别人的系统。第一层那五个问题里,有一半是在读我没写过的代码。

卸载:真正花时间的不是删 ​

决定卸载之后,我以为这是个十分钟的活。最后花掉的时间,九成在删之前。

原因是第一反应「docker compose down 然后删目录」行不通——我并不知道它到底在哪些地方留了东西。于是先做了一件事:把所有相关的东西列出来,只列不删。

列完之后是这样:

位置内容体积
源码目录克隆下来的完整仓库,含 .git1.03 GB(.git 占 413 MB)
数据卷数据库、向量库、插件、上传文件约 600 MB
Docker 侧容器、5 个专属镜像 + 5 个通用镜像数 GB
工作目录根下一堆启动、修复、同步脚本几十 KB

同时冒出来一个我完全忘了的东西:一个同名的嵌套目录,466 MB,里面是第二份完整的源码仓库。早期手工搬目录时把工作目录复制进了它自己的子目录,当时没察觉。

嵌套副本是整理目录时最容易留下的东西

这种副本不会自己消失,只会在你删东西的时候忽然出现,让你不确定删的是哪一份。

分清:哪些能重建 ​

列完清单,按一个问题分类——这东西删了之后,我能不能再造出来?

能重建的,重点是不心疼:源码(开源项目随时重克隆)、向量库索引(265 MB,有原始文档就能重建)、插件二进制(126 MB,重装即可)、镜像缓存(重新拉)。

不能重建的,一共两样:

保不住的为什么
上传的原始文件传进去的东西,删了就真没了
数据库(236 MB)应用定义、知识库元数据、对话历史。工作流还能从导出的配置重建,对话历史没有任何地方备份过

判断标准只有一条

不是"这个文件重不重要",而是"这个东西删了之后我还能不能造出来"。前一问会犹豫,后一问立刻就有答案。

数据库:唯一不能重建的,Docker 又起不来 ​

清单里最该保的就是数据库。正常做法是把它启起来,导出一份 SQL。

问题是 Docker 起不来。启动之后进程列表里没有它,命名管道也不存在,等了三分钟还是这样。

两条路:要么继续排查 Docker 为什么起不来,要么换一个不需要 Docker 的办法。

我选了第二条。数据库的数据目录是直接挂载到宿主机的(不是 Docker 命名卷),意味着文件就老老实实躺在一个普通目录里。那就直接冷备份——把整个数据目录复制一份,236 MB。

需要的时候,用同一个大版本的镜像挂回去就能读:

bash
docker run -d --name db-restore \
  -e POSTGRES_PASSWORD=<当初那个密码> \
  -v "<归档目录>/postgres-raw:/var/lib/postgresql/data" \
  -p 15432:5432 postgres:15-alpine

大版本必须对上

PostgreSQL 的数据目录跨大版本不兼容。备份时是什么版本,恢复就得用什么版本,否则容器直接拒绝启动。所以备份时顺手把镜像 TAG 记下来。

这条路其实比导出 SQL 更省事:不用等 Docker、不用进容器、不用管权限。代价只有一个——找不到现成镜像的时候,得自己搭环境才能读它。

一个没想到的发现 ​

知识库里 54 个上传文件,文件名全是系统生成的 UUID:

0796d284-5039-4f0a-83f8-0a7a0e397c69.pdf
0a683d3d-8102-4062-8533-6d1f79e3a1d5.pdf
12c9382c-9c01-4c53-8b4c-5aea2235811e.pdf

这些名字等于没有名字。所以归档时顺手做了一件事:读每个文件的元数据,生成 UUID → 标题的对照表。

做完发现两件事。一是去重后只有 16 篇(其中一篇被重复上传了 10 次);二是这 16 篇基本全是自己研究方向上的综述。

文件名是 UUID 的目录,等于没有名字

这类目录删之前一定先建索引,否则你面对的就是一堆随机字符串,根本判断不了哪个能删。顺便,重复上传这件事本身也说明问题——同一个文件我传了 10 次,说明当时我就没搞清里面有什么。

归档之后长什么样 ​

最后留下的目录约 340 MB:

归档目录/
├── README-归档说明.md   ← 留下了什么、为什么、怎么恢复
├── workflows/           ← 工作流的导出文件(最有价值的部分)
├── docs/                ← 踩坑记录、复盘笔记
├── papers/              ← 16 篇去重后的文档 + UUID 对照索引
├── db/postgres-raw/     ← 数据库冷备份
├── code/                ← 自己写的脚本和工具
└── env/                 ← 配置文件(含密钥,另外标注了)

有一点值得单独说:归档说明本身是这套东西里最值钱的一页。

工作流的导出文件三个月后我还能看懂,但"当初为什么从这一版改到那一版""为什么最后弃用了"这种信息,不写下来就永久丢了。所以我给归档目录写的不是文件清单,是决策记录。

事先的判断 vs 实际是什么 ​

环节我一开始的判断实际是什么
我遇到的问题一个服务挂了三层问题叠在一起,底层崩溃会引发上层连环故障,表象和根因隔好几层
修完就好了吗修完就稳定了修掉五个,还剩一个偶发复发的
卸载要多久十分钟,删目录删镜像九成时间花在删之前的审计和归档上
相关文件在哪就一个源码目录源码、数据卷、镜像、散落的脚本,还有一个 466 MB 的嵌套副本
上传文件有多少就是那 54 个 PDF去重后只有 16 篇

五个判断里,只有第一个我一开始就想对了。其余四个都是"我以为我知道"。

三件事 ​

  1. 判断一个自建服务要不要留,不看它出了多少问题,看它有几层问题修不掉。 能彻底修掉的属于学费,交一次就完了;修了还会复发的,是把成本摊到未来每一次使用上。

  2. 排查问题时,先分清你排查的是自己的代码还是别人的系统。 第一层那五个问题里有一半是在读我没写过的代码。这个成本在选型时根本看不见,只在出问题的时候才浮现。

  3. "能不能重建"比"重不重要"好判断。 卸载的难点从来不是删,是分清哪些东西删了就回不来。顺序应该是:先列全 → 按能不能重建分两类 → 把不能重建的归档并验证 → 最后才动手。

如果只想记三件事
  1. 端口"没被占用却绑不上"→ 查 TIME_WAIT,治本是 reuseAddr。
  2. 中文 Windows 上遇到莫名其妙的闪退乱码 → 先试 PYTHONUTF8=1。
  3. 文件名是 UUID 的目录,删之前一定先建索引。

用 VitePress 搭的,托管在 GitHub Pages