- 搭起来容易,用起来要一直修,这是两回事
- 修掉的问题有五个,修不掉的有一个,还有一类不该由我修
- 替代品不是另一个成品软件,是自己写的那套工具
- 最后卸载时,真正花时间的不是删,是分清什么丢了回不来
半年前我在这台笔记本上搭了一套论文研究用的工作流。三个服务串起来:LiteLLM 把一堆免费模型聚合成统一网关,Dify 用 Docker Compose 跑起来做编排,再接一个自己写的监控面板。双击一个 start-all.bat,三个窗口起来,就算开工了。
现在这套东西已经卸载了。
在说怎么卸的之前,得先说为什么卸。原因不是"它坏了"——它没坏,是每次开机都要重新面对一圈可能出问题的环节。我把前后遇到的所有故障记了下来,一共十几个,修完之后回头一看,这些故障其实是分层的。
这篇就按这三层来讲。
第一层:能彻底修掉的问题
这一层有五个。修完就永久免疫,不会再犯。但它们是当时耗时间最多的部分,而且每一个都长得不像它真正的样子。
1. 端口"没人占用"但绑不上
监控面板起不来,报 EADDRINUSE: address already in use。
第一反应是上个进程没退干净。但 netstat -ano | findstr :5000 查了一遍,端口不在列表里。进程也没了,端口也没占,那到底是谁占着。
根因是 TCP 的 TIME_WAIT 状态。连接关闭后,端口不会立刻释放,会被内核保留两到四分钟,确保最后一个确认包能送达。这个状态下端口被内核攥着,但常规的 netstat 输出里看不到它。
所以「杀进程再启动」这条常规路子必然失败:杀进程解决不了内核状态。
修的时候动了两个地方,一个治标一个治本:
// 监控面板:允许直接绑定处于 TIME_WAIT 的端口
srv.listen({
port: DASH_PORT,
host: "0.0.0.0",
reuseAddr: true
}, () => { /* ... */ });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 这样翻倍。重试五次的逻辑,实际跑了十几次。
看了一眼重试函数就明白了:
// 错误写法:每次重试都往同一个 server 上加一个新监听器
function startServer(retries) {
srv.on("error", e => {
if (e.code === "EADDRINUSE") {
setTimeout(() => startServer(retries + 1), 4000);
}
});
}on() 是追加,不是替换。每次递归调用都往同一个对象上叠一个新监听器,它们会同时触发,每个都再调一次 startServer,每个又叠一个。
修法是换成只触发一次的 once(),并且先清掉旧的:
// 正确写法:先清空再挂,且只挂一次
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
→ 网关启动瞬间崩溃
→ 窗口闪退
→ 看门狗发现网关挂了,重启
→ 又崩 → 死循环这是最典型的"表象和根因隔了好几层"——看到的是看门狗在疯狂重启,实际是编码问题。
一行环境变量解决:
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。
另外两个
剩下两个没上面这么绕,一句话说完:
- 路径硬编码:项目换过盘,脚本里还写着旧目录。纯粹是搬家没更新,改完就好。
- 批处理延迟变量:
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 之后要等三十到六十秒让服务初始化完,前后约两分钟。
这里的问题不是"能不能修"
两分钟能修好,一行命令的事。问题在于它复发的时机完全不可控——你没法预测哪次开机它会犯。于是每次开工前你都得先赌一次,赌输了就先花两分钟,而且得先意识到"是这个老毛病又犯了",而不是又去查一遍别的。
我一开始还试过别的路子。既然每次开机都可能要重建网络,那干脆把整套东西做成开机自动重建。做了一半停下来了——为了让一个偶发问题不影响使用,我搭了一套更复杂的自动化,而自动化本身又多了几个可能坏的地方。这是典型的负收益。
第三层:不该由我修的问题
到这里我停了一下,问自己一个问题:这些问题是从哪来的?
前两层是"环境和你作对",但还有一类,是这类工具本来的形态决定的:
- 每个环境都要单独配一遍。 换个地方部署,这一套配置、密钥、目录挂载都要重来。
- 服务连不上就只能干等。 面板没起来,整个流程就卡在那里,没有降级路径。
- 能力上限锁在别人给的表单里。 这是最要紧的一条——我想加一个新环节(比如从摘要里自动抽出代码仓库地址),得先在脑子里翻译成它那套节点和连线的形式,再拖拽连好。我花在"把想法翻译成它的界面"上的时间,比花在想清楚这个想法上还多。
这一层不是 bug,所以修不掉。只能换掉。
替代品:不是另一个成品软件
想清楚第三层之后,选型其实没有纠结很久。我先试过几个方向:
| 方向 | 为什么没走 |
|---|---|
| 换一个同类可视化编排平台 | 第三层的问题一模一样,只是换个界面重新配一遍 |
| 留在原地,继续修 | 第一层已经修完了,第二层修不掉,第三层不该修 |
| 自己写一套工具 | 选它 |
选第三条的理由就一个:我要的那些环节,用代码写出来比拖拽更快。
最后成型的是一套自己写的工具,端到端可跑:丢一个 PDF 进去,它自己拆模块、去检索、打分、给出缝合方案。跑代码的部分交给另一台有显卡的机器,用轮询去取任务。
对比一下就清楚了:
| 可视化编排平台 | 自己写的工具 | |
|---|---|---|
| 加一个新环节 | 想清楚 + 翻译成节点连线 + 拖拽配置 | 想清楚 + 写代码 |
| 换环境部署 | 配置、密钥、挂载都要重来 | 一套代码,带走就行 |
| 中途失败 | 卡在界面上等 | 有日志,能断点重试 |
| 排查问题 | 看容器日志、看界面报错 | 看自己的日志 |
| 启动开销 | 十几个容器 | 按需启动 |
这个对比里最容易被忽略的一行
是「排查问题」那行。可视化编排的代价不止是搭起来慢,而是出问题的时候,你排查的是别人的系统。第一层那五个问题里,有一半是在读我没写过的代码。
卸载:真正花时间的不是删
决定卸载之后,我以为这是个十分钟的活。最后花掉的时间,九成在删之前。
原因是第一反应「docker compose down 然后删目录」行不通——我并不知道它到底在哪些地方留了东西。于是先做了一件事:把所有相关的东西列出来,只列不删。
列完之后是这样:
| 位置 | 内容 | 体积 |
|---|---|---|
| 源码目录 | 克隆下来的完整仓库,含 .git | 1.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。
需要的时候,用同一个大版本的镜像挂回去就能读:
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 篇 |
五个判断里,只有第一个我一开始就想对了。其余四个都是"我以为我知道"。
三件事
判断一个自建服务要不要留,不看它出了多少问题,看它有几层问题修不掉。 能彻底修掉的属于学费,交一次就完了;修了还会复发的,是把成本摊到未来每一次使用上。
排查问题时,先分清你排查的是自己的代码还是别人的系统。 第一层那五个问题里有一半是在读我没写过的代码。这个成本在选型时根本看不见,只在出问题的时候才浮现。
"能不能重建"比"重不重要"好判断。 卸载的难点从来不是删,是分清哪些东西删了就回不来。顺序应该是:先列全 → 按能不能重建分两类 → 把不能重建的归档并验证 → 最后才动手。
如果只想记三件事
- 端口"没被占用却绑不上"→ 查 TIME_WAIT,治本是
reuseAddr。 - 中文 Windows 上遇到莫名其妙的闪退乱码 → 先试
PYTHONUTF8=1。 - 文件名是 UUID 的目录,删之前一定先建索引。