Microduck守护进程军团：基于Unix socket与JSON-RPC的稳定训练架构

Microduck这个项目我折腾了不短时间，从最初直接把训练进程跑在终端前台，到后来被“终端一关全完蛋”“跑到一半断连”“显存爆掉连渣都不剩”这种事反复教育，才慢慢意识到：想把Microduck稳定地用起来，单靠一条命令是不够的，得给它配一支能长期驻留、各管一摊、互相协作的守护进程军团，进程之间用Unix socket走JSON-RPC通信。这篇就是我把这套架构从设计到落地、再到踩坑修复的完整记录。

如果你正打算在自己机器上跑Microduck做微调训练，或者已经能跑通但觉得“跑起来容易，跑稳很难”，这篇文章应该能帮你省掉不少弯路。我会把进程怎么拆、socket怎么规划、协议怎么定、训练任务怎么调度、出问题怎么排查这些事讲透，里面所有步骤和代码都是可以直接抄走用的。

1. 为什么Microduck要配一个“守护进程军团”

1.1 Microduck跑通之后，真正难的是什么

Microduck本身是一个面向本地训练和推理场景的轻量级LLM工具链，主打的是把模型微调、LoRA训练、推理这些都压在个人开发机或小型GPU服务器上完成。网上聊“microduck怎么训练”的帖子不少，大多止步于“能跑”，也就是命令行敲下去、日志刷起来、loss往下降，就算跑通了。但真到把训练当日常任务用的时候，问题立刻浮出水面。

最典型的一个场景：你拿一台没有显示器的服务器训练，SSH连上去启动训练，然后人走了，网络一抖动，终端断开，训练进程收到SIGHUP直接退出，跑了12小时的checkpoint全废。这就是常说的“前台进程扛不住断连”。再一个，训练和推理放在同一个进程里，训练吃掉全部显存，推理请求来了只能干等，跟死机一样。还有，如果你想把Microduck集成进自己的工具链，比如写个Web界面、写个定时任务、接个团队共用的API，总不能每次都去服务器上手动敲命令。

“跑通”只解决了“能不能训”的问题，真正难的是“能不能稳定地训、随时地推理、方便地被调用”。这时候就需要把Microduck拆成若干后台服务，也就是守护进程来承载。

1.2 从单进程到多守护进程：到底解决了什么问题

我最初也怀疑过，一个本地工具搞这么重的架构是不是过度设计。但把需求列清楚再想，就会发现拆分不是“为了架构而架构”，而是每一条都有真实的痛点支撑：

• 训练任务要跨会话存活，必须有一个脱离终端的守护进程来托管。
• 训练时占用GPU资源，推理服务不能跟着训练一起阻塞，需要独立进程隔离。
• 数据预处理、格式转换这些脏活累活，不该混进训练主流程。
• 训练进度、日志、状态查询需要对外提供统一入口，不能靠翻终端窗口。
• 崩溃要能自愈，至少主控进程要能把挂掉的子进程捞回来。

“守护进程军团”这个词看起来有点中二，但它描述的事实是：不是单个daemon，而是一组各司其职的daemon进程，由一个总控负责编排。它们共享同一套通信机制，但这个机制不是主从服从式的“命令下发”，而是服务之间互相调用，谁需要谁的数据就去请求谁。

这样拆完之后，训练中断、并发推理、异步查询、集成API这些问题都能在进程边界上解决，而不是在代码里到处堆特例。

1.3 通信选型：HTTP、gRPC、共享内存都不如Unix socket上的JSON-RPC

进程拆开了，进程之间怎么说话就成了关键问题。可供选择的方案不少，我逐一评估过：

我这里不是做性能对比测试，而是讲取舍逻辑。本地进程间通信，首先关注的是“不能被外部随便访问”，Unix socket通过文件系统权限就能锁住，天然比TCP端口安全。其次要关注开发效率和调试成本，JSON-RPC 2.0是一个足够简单也足够规范的协议，Python、C++、Node、Go都有现成实现，哪怕手写解析也不难。最后才是性能，训练任务每步迭代要几秒钟，推理任务一次也就几十到几百毫秒，JSON编解码这点开销完全可以忽略，真正的大数据（数据集文件、模型文件）根本不该走RPC，走文件系统就对了。

所以最终定下来：进程通信用Unix domain socket承载，协议用JSON-RPC 2.0风格，并在传输层做了一点扩展，专门处理训练任务这种“长时间运行”的方法调用。

2. 架构设计与进程职责：先画好军团编成表

2.1 五个守护进程各自的职责

整个守护进程军团由五个角色组成，名字带着Microduck的“duck”印记：

• duckctl：总控调度进程，负责启动、监控、拉起其他守护进程，也是外部请求的统一入口。
• ducktrain：训练服务进程，专门承担LoRA微调、全参微调这类训练任务，持有GPU资源。
• duckinfer：推理服务进程，负责模型加载和推理请求，跟训练进程隔离开，避免互相挤占显存。
• duckdata：数据处理服务进程，负责数据集加载、格式校验、tokenize、样本切分等前置工作。
• duckmon：监控与日志服务进程，收集其他进程的指标、日志和心跳，供查询和告警。

这五个角色不是平级的，duckctl是“军团长”，其他四个是“兵种”。duckctl不直接干活，它管调度、管心跳、管崩溃恢复。你外部想发起训练，请求打到duckctl，duckctl再转发给ducktrain；你想查训练进度，也是打到duckctl，由它去ducktrain那边取状态再返回。

为什么要加一层duckctl而不是直接调ducktrain？因为如果外部请求直接打给训练进程，你就没法在中间做鉴权、限流、任务编排和状态聚合。多这一层，外部使用方永远只面对一套API，内部谁挂了、谁来接班，对外是不可见的。

2.2 socket路径、目录结构与权限规划

Unix socket是通过文件系统路径来寻址的，所以路径规划就是个不能拍脑袋的事情。我采用的是每个进程一个独立socket文件，统一放在/run/microduck/目录下：

/run/microduck/ ├── duckctl.sock ├── ducktrain.sock ├── duckinfer.sock ├── duckdata.sock └── duckmon.sock

选/run而不是/tmp，是因为/run是系统开机后创建的运行时目录，更适合放守护进程的socket和pidfile；/tmp是任何人都能写的公共目录，容易出权限问题和命名冲突。如果你用户名权限不够创建/run/microduck，可以退一步用/tmp/microduck-$USER/，但目录权限必须设成700，保证只有你这个用户能访问。

socket文件权限我建议显式设置成0660，并用chown把属主设为服务账号。为什么不是0666？因为0666等于允许机器上任何用户都能往你的训练进程发请求，谁都能让你加载模型、删任务，这不是一个负责任的服务该有的态度。Unix socket最舒服的一点就是你不用像TCP那样去搞TLS，文件权限本身就是安全层。

pidfile也放在这个目录下，格式是<服务名>.pid，比如duckctl.pid。这个文件是给duckctl检测其他进程是否存活用的，也是手工排查时最快的判断依据。

2.3 JSON-RPC 协议设计：字段、错误码与长任务约定

协议底座是JSON-RPC 2.0，但为了适配训练这种长任务场景，我做了几处裁剪和扩展。先看一个标准的请求长什么样：

{ "jsonrpc": "2.0", "id": 202401071530, "method": "train.create", "params": { "model_path": "/models/llama-duck-7b", "lora_out": "/output/duck-lora", "dataset_path": "/data/duck_train.jsonl", "epochs": 3, "lr": 2e-5 } }

响应对应：

{ "jsonrpc": "2.0", "id": 202401071530, "result": { "task_id": "train-7f3a9c", "status": "accepted" } }

这是标准的请求-响应模式，适合创建任务、查询状态这类操作。但对于训练任务，真正发起训练之后，训练可能要跑几十分钟甚至几小时，客户端不可能一直拿着socket连接干等。所以我把训练类方法分成两个阶段：提交阶段和查询阶段。提交阶段只返回“任务是否被受理”以及task_id，查询阶段用新方法轮询任务状态。

这是JSON-RPC本身不支持“异步长任务”这个语义的务实补偿。协议解析不难，难的是什么样的调用模型能真正被训练流程用起来。很多人在这一步翻车，就是因为拿着同步RPC的思路去调训练任务，一个请求过去，客户端挂起几小时，中间断一下全废。

扩展约定还包括固定字段。每个请求必须带method前缀区分服务域，例如train.create走ducktrain、infer.generate走duckinfer、data.validate走duckdata。这样在设计方法注册表的时候，一眼就能看出方法的归属。

错误码也做了统一约定，我用负数表示协议层错误，正数表示业务层错误。标准JSON-RPC已经定义了-32700（解析错误）、-32600（无效请求）、-32601（方法不存在）、-32603（内部错误），这些保留。业务错误从1000开始递增，例如1001表示数据集不存在，1002表示GPU显存不足，1003表示任务已存在。

2.4 守护进程生命周期管理：daemonize、pidfile、日志与退出

守护进程和普通前台进程最大的区别在于生命周期。前台进程跟着终端走，终端关它就死；守护进程必须脱离终端、脱离会话，由系统init接管，这样才能做到“关终端不关进程”。

传统daemonize流程大致是：fork一次让父进程退出，子进程调用setsid脱离会话，再fork一次防止重新获取控制终端，然后切换工作目录、设置umask、重定向标准输入输出到日志文件。这套流程在C/C++里要自己写，Python里可以用python-daemon库，双fork、setsid、umask这些细节库都封装好了。

但我不建议所有人上来就自己实现daemonize。现代Linux系统上更省心的做法是直接用systemd管理这些守护进程，或者在开发阶段用nohup加&顶住。我自己的实操是：开发调试用前台模式加环境变量控制，正式跑的时候用systemd的Type=simple托管，每个服务一个unit文件，谁挂了systemd帮我拉起来。

守护进程还有一个关键动作：写pidfile。pidfile帮我们回答三个问题：进程是否在跑、进程号是多少、上次残留的进程是不是僵尸。每次启动时先读pidfile，如果发现进程还活着就直接拒绝重复启动；如果pidfile存在但进程不存在，说明上次没有正常退出，需要清掉残留文件再启动。

日志方面，我的原则是“每个进程一个日志文件，统一由duckmon收集摘要”。比如ducktrain.log里既有Microduck训练本身打的进度，也有RPC服务层的访问日志。这样排查的时候先把RPC访问日志翻一遍，确认请求到没到底层，再决定是不是要往训练日志里深挖。

3. 核心实现细节：socket层与JSON-RPC路由

3.1 Unix socket 服务端骨架（Python 示例）

Microduck本身是C++写的主力，但守护进程军团的服务端骨架我用了Python，主要原因是开发速度快、热更新方便，而且RPC这层对性能要求不高，瓶颈在训练和推理那一侧。这里分享一个最简的Unix socket服务端骨架：

import json import os import socket import logging SOCKET_PATH = "/run/microduck/ducktrain.sock" logging.basicConfig( filename="/var/log/microduck/ducktrain.log", level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s", ) def handle_line(line: str) -> dict: """单条JSON-RPC消息处理入口。""" try: req = json.loads(line) except json.JSONDecodeError: return {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "Parse error"}} req_id = req.get("id") method = req.get("method") params = req.get("params", {}) handler = ROUTER.get(method) if handler is None: return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32601, "message": f"Method not found: {method}"}} try: result = handler(params) return {"jsonrpc": "2.0", "id": req_id, "result": result} except Exception as exc: return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32603, "message": str(exc)}} def serve_forever(): os.makedirs(os.path.dirname(SOCKET_PATH), exist_ok=True) try: os.unlink(SOCKET_PATH) except FileNotFoundError: pass sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) sock.bind(SOCKET_PATH) os.chmod(SOCKET_PATH, 0o660) # backlog设置成5还是128，取决于并发量，本地服务10足够 sock.listen(10) logging.info("ducktrain socket listening on %s", SOCKET_PATH) while True: conn, _ = sock.accept() with conn: buffer = b"" while True: chunk = conn.recv(65536) if not chunk: break buffer += chunk # 按换行符切分，一条JSON-RPC消息一行 while b"\n" in buffer: line, buffer = buffer.split(b"\n", 1) if not line.strip(): continue resp = handle_line(line.decode("utf-8", errors="replace")) conn.sendall((json.dumps(resp) + "\n").encode("utf-8")) if __name__ == "__main__": serve_forever()

这段代码有几个细节值得说。一是按换行符切分消息，避免TCP粘包问题。Unix socket虽然是流式接口，但本地通信量不大，用换行分隔是JSON-RPC over stream场景里最简单粗暴且有效的方案。二是每次accept后先读完整行再回包，天然实现了“一问一答”的同步语义，逻辑清楚。三是启动时先尝试unlink旧的socket文件，否则上次进程残留的socket文件会导致bind失败报“Address already in use”。

3.2 RPC 方法注册与路由实现

ROUTER这个字典就是方法注册表，把方法名字符串映射到实际处理函数：

ROUTER = { "train.create": train_create, "train.status": train_status, "train.cancel": train_cancel, "infer.load": infer_load, "infer.generate": infer_generate, }

每个handler接收params字典，返回可JSON序列化的结果。我建议所有handler都套一层统一的异常捕获，就像上面代码里的try-except那样，把异常转成JSON-RPC标准错误返回给调用方，而不是让连接断开。连接一断，客户端那边只会看到笼统的“connection lost”，问题定位的成本立刻翻倍。

路由层还有一个容易被忽略的点：方法的幂等性。训练创建任务这种操作，客户端超时后重试，很可能造成同一个任务被提交两次。我的处理是在train.create里以(dataset_path, model_path, lora_out, epochs, lr)算一个签名，如果相同签名的任务已经在运行或排队，就直接返回现有task_id而不是新建任务。这个设计让我在排查“重复训练”问题时省了大力气。

3.3 训练长任务：轮询与通知的节奏

训练任务被创建之后，ducktrain进程内部会起一个线程去跑Microduck训练，RPC服务端线程不能阻塞。我的任务模型是：train.create把训练请求塞进一个队列，立即返回task_id；后台线程从队列里取任务，调用Microduck的训练接口，不断更新任务状态到内存字典和磁盘状态文件。

客户端查状态就用train.status方法：

{"jsonrpc": "2.0", "id": 2, "method": "train.status", "params": {"task_id": "train-7f3a9c"}}

返回：

{"jsonrpc": "2.0", "id": 2, "result": {"status": "running", "current_epoch": 2, "total_epochs": 3, "loss": 1.342, "progress": 0.67}}

轮询间隔我推荐3到5秒一次。太频繁会给ducktrain增加没意义的RPC压力，太稀疏则会让客户端界面看起来反应迟钝。如果你需要事件驱动的推送，也可以在JSON-RPC里定义一个notify方法，服务端主动向duckmon推送任务状态变化。但我自己实测下来，在本地服务场景下，轮询比推送简单可靠得多，推送还要处理客户端离线、重连、补发等等问题，增益很有限。所以我的结论是：先轮询，等确实出现秒级延迟感知需求再上推送。

3.4 容易被忽略的参数：backlog、超时、心跳与权限验证

这几个参数看着不起眼，但每一个都对应一次真实的线上故障。

backlog是listen接口的第二个参数，表示内核维护的连接队列长度。本地进程通信并发量通常不大，但也不是没有极端情况：比如你写了个监控脚本每秒钟来探活，加上正常的RPC请求，瞬间就有几十个连接排队。backlog设成10还是128，取决于你对自己服务的认知。我给所有服务都统一设了64，既不吃太多内核内存，也能扛住探活和正常请求的短时高峰。

超时分两层。第一层是socket自身的收发超时，服务器端每个连接都建议设置一个读超时，比如30秒内没收到完整请求就断开，防止客户端半开连接把服务端资源挂住。第二层是任务查询的“快速失败”语义，train.status这类查询方法必须在几百毫秒内返回，如果查询本身都超时，说明被调方已经卡死，客户端应该立刻报错而不是无限重试。

心跳是我在duckmon里加的一个机制。每个守护进程每隔10秒往duckmon上报一次心跳，包含进程号、内存占用、显存占用、当前任务数。如果连续3个心跳周期没收到某个进程的心跳，duckmon就通知duckctl，由duckctl决定是重启还是告警。这套机制让我在训练过程中能及时发现“进程还活着但卡死在IO”这种假死状态。

权限验证方面，Unix socket除了文件权限之外，还可以通过SO_PEERCRED拿到对端进程的PID和UID。这个能力很关键：即使socket文件权限设得再严，也存在进程间模拟访问的可能，SO_PEERCRED可以确认对端是不是被信任的进程。我在duckctl的访问层做了校验，只有UID为服务账号且PID存在于已注册进程列表的请求才会被受理，其余的直接拒绝。这样即使有人拿到了socket路径，也没法轻易发假请求。

4. 实操记录：把Microduck套进守护进程军团

4.1 环境准备与编译：先让Microduck能跑

在搭守护进程军团之前，Microduck本身得先在目标机器上跑通。我用的机器是一张RTX 4090 24G，系统是Ubuntu 22.04，依赖主要是CMake、CUDA Toolkit和gcc。Microduck的编译流程跟很多C++项目一样，大概是这样：

git clone https://github.com/microduck/microduck.git cd microduck mkdir build && cd build cmake .. -DGGML_CUDA=ON make -j$(nproc)

-DGGML_CUDA=ON是让ggml后端启用CUDA加速，如果机器是Apple Silicon，可以用-DGGML_METAL=ON；没有GPU纯CPU跑就什么都不加。编译完主要产物是microduck-train和microduck-infer两个可执行文件，前者负责训练，后者负责推理。

这里有一个我在第一次编译时踩过的坑：CMake缓存。如果你先以CPU模式编译过一次，再切到CUDA模式，必须把build目录整个删掉重新配置，否则就算加了-DGGML_CUDA=ON也可能继续用旧的CPU配置。这是一个很小但能卡住新人半小时的问题。

编译好之后，先手动拿一个mini数据集跑一次训练，确认底层训练链路是通的，再做后面的封装。这一步千万别跳，守护进程军团只是一个外壳，外壳再稳，底层训练器本身跑不通也是白搭。

4.2 启动军团的标准流程

我写了一个duckctl start命令，严格按依赖顺序启动各个守护进程。启动顺序有讲究：先duckdata，因为训练和推理都可能依赖数据服务；再duckmon，让监控从最开始就能收心跳；接着ducktrain和duckinfer；最后启动duckctl自己。中间任何一个进程起不来，启动流程直接中止，不向下走。

# 创建运行时目录 sudo mkdir -p /run/microduck sudo chown $USER:$USER /run/microduck chmod 700 /run/microduck # 按顺序启动 python3 services/duckdata.py --daemon python3 services/duckmon.py --daemon python3 services/ducktrain.py --daemon python3 services/duckinfer.py --daemon python3 services/duckctl.py --daemon

启动之后的第一件事，不是急着发训练请求，而是检查进程和socket文件是否都就位：

ls -l /run/microduck/ # 应该看到5个.sock文件和对应的.pid文件 ps aux | grep duck # 应该看到5个python3进程

如果socket文件存在但没有任何进程监听，多半是上次程序非正常退出留下的残骸。解决办法就是删掉对应的sock文件再重启，这一步我在服务启动脚本里已经做了自动清理，手工排查时也经常要手动删一次。

4.3 用 JSON-RPC 客户端打通训练与推理闭环

启动就绪后，我用一个Python客户端做完整链路测试。先创建训练任务：

import socket, json def rpc_call(sock_path, method, params, req_id): line = json.dumps({"jsonrpc": "2.0", "id": req_id, "method": method, "params": params}) + "\n" s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) s.connect(sock_path) s.sendall(line.encode()) resp = b"" while not resp.endswith(b"\n"): resp += s.recv(65536) s.close() return json.loads(resp) # 提交训练任务到 duckctl result = rpc_call( "/run/microduck/duckctl.sock", "train.create", { "model_path": "/models/llama-duck-7b", "lora_out": "/output/duck-lora", "dataset_path": "/data/duck_train.jsonl", "epochs": 3, "lr": 2e-5 }, req_id=1001 ) print(result) task_id = result["result"]["task_id"]

这一步如果返回accepted，说明任务已经进入ducktrain的任务队列。接着轮询状态：

import time for _ in range(120): status = rpc_call( "/run/microduck/duckctl.sock", "train.status", {"task_id": task_id}, req_id=1002 ) st = status["result"]["status"] print(f"status: {st}, loss: {status['result'].get('loss')}") if st in ("finished", "failed", "canceled"): break time.sleep(5)

训练完成后，把生成的LoRA权重加载到推理服务里，然后生成文本：

rpc_call( "/run/microduck/duckctl.sock", "infer.load", {"lora_path": "/output/duck-lora", "model_path": "/models/llama-duck-7b"}, req_id=1003 ) resp = rpc_call( "/run/microduck/duckctl.sock", "infer.generate", {"prompt": "写一段关于Unix socket的介绍", "max_tokens": 256}, req_id=1004 ) print(resp["result"]["text"])

这套测试跑通，基本就证明军团整个链条是通的。后续无论是接Web界面、接定时任务还是接团队API，都会轻松很多。

4.4 训练数据与模型输出的约定

训练环节能不能跑顺，很大程度取决于数据和输出路径的约定。Microduck常用的数据集格式是JSON Lines，每行一条样本，训练字段一般包含instruction、input和output，指令微调场景下尤其如此：

{"instruction": "解释一下什么是Unix domain socket", "input": "", "output": "Unix domain socket是一种用于同一台机器上进程间通信的socket机制，通过文件系统路径作为地址。"}

我把数据集统一放在/data/microduck/下面，命名规则是<任务名>_train.jsonl和<任务名>_val.jsonl。duckdata服务启动时会扫描这个目录，生成一个数据清单，训练请求里只需要告诉它“数据集名”，不需要传完整路径。这样做的目的是把路径管理收口到一处，避免训练请求里谁都能传一个任意路径，既难管理又有安全风险。

模型输出方面的约定是：LoRA权重统一输出到/output/microduck/<任务名>/目录，目录里至少包含adapter_model.bin、adapter_config.json和一份training_stats.json训练摘要。训练摘要里有最终loss、每轮loss、训练耗时、学习率、样本数等，这些信息会被ducktrain在任务结束回填到train.status的返回结果里，方便上层做报告和分析。

4.5 一次完整的 LoRA 微调任务参数

下面是我在16GB显存机器上跑一个7B模型LoRA微调的常用参数组合，直接通过JSON-RPC提交：

{ "jsonrpc": "2.0", "id": 1001, "method": "train.create", "params": { "base_model": "llama-duck-7b", "dataset": "alpaca_duck_train", "val_dataset": "alpaca_duck_val", "lora_out": "/output/microduck/alpaca_duck_run1", "lora_r": 16, "lora_alpha": 32, "lora_dropout": 0.05, "target_modules": ["q_proj", "v_proj", "k_proj", "o_proj"], "epochs": 3, "batch_size": 4, "gradient_accumulation_steps": 4, "learning_rate": 2e-4, "lr_scheduler": "cosine", "warmup_steps": 100, "max_seq_len": 2048, "save_steps": 500, "eval_steps": 100 } }

这里面的参数我挑几个重点解释一下。lora_r=16在7B模型上是一个比较折中的选择，r太小模型学不动，r太大LoRA省显存的意义就弱了。batch_size和gradient_accumulation_steps的配合是为了在显存有限的情况下得到更大的等效batch size，4 x 4等于等效32的batch size。learning_rate用2e-4而不用全参微调常用的1e-5，是因为LoRA本身的参数量小，需要相对高一点的学习率才能有效更新。

这些参数不是死的。同样一份数据，换一个基础模型就要重新调。我建议第一次跑先拿一个小数据集验证链路，确认loss趋势正常，再放全量数据长时间跑。

5. 常见问题与排查技巧实录

5.1 连接拒绝：socket文件找不到还是权限不够

“Connection refused”大概是我在这个架构里见过最多的报错。它有两种常见原因。

第一种，socket文件根本没有生成。检查方法很简单：

ls -l /run/microduck/

如果文件不存在，说明对应的守护进程还没起来，或者起来了但bind失败。看日志文件就行，日志里会写清楚bind失败的原因。

第二种，socket文件存在但你连不上。这种情况绝大多数是权限问题。Unix socket的连接权限由socket文件的属主和权限位控制，如果你用A用户启动服务，却用B用户去连接，sock文件权限是0660、属主是A，B用户就没有访问权。排查时先看属主：

ls -ln /run/microduck/duckctl.sock

再看当前用户：

whoami id

两边一对照就知道是不是权限不匹配。我自己后来统一用microduck系统账号跑所有服务，所有外部请求也通过这个账号执行，权限问题基本绝迹。

5.2 请求超时：长任务不该占用同步响应

有一次集成方反馈“训练请求发出去几十秒都没返回”，我第一反应是训练卡死了，结果去查日志，发现训练根本没开始。真正的原因是我的服务端实现有bug：train.create在把任务塞进队列之后，又顺手做了一次数据集校验，而那个校验要扫描整个数据集文件，7GB的文件扫描了几十秒，把整个RPC响应拖住了。

这个问题的解法就是我在协议设计里说的：训练类方法必须“快进快出”，提交就是提交，校验放后台做，状态通过查询接口暴露。我后来在duckdata里加了数据校验的缓存，第一次扫描后生成校验快照，后续请求直接读快照，几百毫秒就能完成。

另外一个常见的超时点出现在socket.recv上。客户端发完请求后如果服务器处理慢，客户端就会一直阻塞在recv上。我建议客户端侧用settimeout把读取超时设成30秒，避免无限挂起。

5.3 残留pidfile与僵尸守护进程

守护进程最阴间的故障是“pidfile还在，但进程已经死了”。我的duckmon有一次检测到duckinfer“假死”，心跳断了好几个周期，但pidfile还躺在目录里。查了半天发现是duckinfer显存不足触发了OOM kill，内核直接把进程杀了，pidfile自然没机会被清理。

所以我对pidfile的使用原则是：只把它当作“参考”而不是“真相”。在判断进程是否存活时，应该配合pidfile里的PID去查/proc/<pid>/目录是否存在，或者干脆发一个心跳查询RPC确认进程真实状态。后来我在duckctl的进程管理逻辑里加了这样一个检查步骤，发现问题就自动清掉残留pidfile并重新拉起服务，这才彻底解决了僵尸态问题。

5.4 多进程同时加载模型的资源竞争

一个我刚开始没预料到的问题：ducktrain训练完一个模型，duckinfer推理另一个模型，两个进程同时读取同一个基础模型文件时，磁盘IO和内存压力骤增，直接导致机器卡顿。

排查之后定位到根因是模型文件先被操作系统page cache缓存在内存里，多进程并发读同一份文件会加剧缓存竞争。解法有两个层面。第一，错峰加载：duckinfer在训练开始前先不加载模型，等到训练稳定运行后再加载；第二，把基础模型文件放到SSD上，并在加载时通过posix_fadvise禁用page cache预读，减少对page cache的抢占。

这些策略最终都落到架构约定里：ducktrain启动训练前，向duckctl报告“我要占用显存资源”，duckctl协调duckinfer暂时释放GPU内存。这样一来，训练和推理虽然在同一张卡上，但不会发生激烈的资源打架。

5.5 排查命令与错误码速查

最后把我的排查命令和错误码整理成一张速查表，方便你直接用：

排查时我常用的命令组合是：

# 查看进程存活状态 ps aux | grep duck # 查看所有socket文件 ls -l /run/microduck/ # 查看训练服务日志尾部 tail -f /var/log/microduck/ducktrain.log # 查看GPU显存情况 nvidia-smi

如果日志显示请求已经到了服务端但没返回，那就是handler执行逻辑的问题，往业务代码里查；如果日志里压根没有请求记录，那就是网络层或权限层的问题，往socket路径和权限上查。这套二分法基本能覆盖90%的故障场景。

这套守护进程军团架构我重构了三次才稳定下来。最初图省事把训练和推理塞进同一个进程，结果推理请求高峰期训练卡到loss不降；后来拆开了，又因为socket路径和权限没规划好，时不时冒出连接拒绝的问题。现在这版跑了一个多月，唯一一次服务中断还是因为机器断电，其余时间都稳如老狗。

如果你也要给Microduck做类似的守护进程封装，我的建议是先拆训练和推理这两个核心服务，数据服务和监控后续再加，不要一上来就想把所有模块全部微服务化。先把训练的稳定性守住，再谈军团扩张。最后一句话：Unix socket上的JSON-RPC这套组合，性能不是最高的，但它是本地多进程架构里“开发效率、调试体验、安全隔离”三者最均衡的方案，值得你认真用一次。