processor/scripts/systemd/host-units/README.md

生产机 systemd 用户单元(实际运行配置)

本目录是生产机 192.168.110.58 上实际在跑的那套 systemd 用户单元,入库是为了 换机/重装时可直接复用。与上级目录的 *.service.in(deploy.py 的模板,另一套命名 egodata-backend / egodata-workers)并存,互不影响 —— 当前运行的是本目录这套。

包含什么

文件	作用
egodata-storage.service	sshfs 挂载 NAS 数据(~/.cache/egodata-data)。含僵尸挂载自愈:启动前先 fusermount3 -u -z 清理残留,再重挂
egodata-api.service	uvicorn 后端 + 前端网页(同一进程,0.0.0.0:8000)。Requires+After 挂载,挂载没就绪不会启动
egodata-worker.service	异步处理 worker(领工作流任务)
egodata-watchdog.sh + .service + .timer	每分钟巡检:挂载掉了重挂、API 不健康重启。启动中(activating)跳过、连续 2 次不健康才动手,避开 API 冷启约 20s 的误判
install.sh	一键安装到 ~/.config/systemd/user/ + ~/.local/bin/

为什么这样配(踩过的坑)

1. 换网络/休眠后服务全挂:sshfs 断线 → 挂载单元失败 → API 启动时扫描数据目录撞上 死挂载崩溃 → systemd 因"正常退出码"不重启。已用 Restart=always + Requires= 修正。
2. 僵尸挂载(Transport endpoint is not connected):断线后挂载点残留,mkdir/sshfs 全失败,重启重试 73 次也挂不上。已用 ExecStartPre=fusermount3 -u -z 自愈。
3. API 冷启约 20s:看门狗若在这期间判为宕机就会反复重启,故加 activating 跳过 + 连续 2 次阈值。

安装

bash install.sh

依赖:

• sshfs(processor/.tools/sshfs/usr/bin/sshfs,单元里写死此路径)
• NAS 的 SSH 私钥 ~/.ssh/id_rsa
• ~/.config/egodata-worker-env(含 EGODATA_WORKER_API_KEY,不入库,install.sh 会 生成占位,取值见 processor/.env)

常用操作

systemctl --user status egodata-api          # 状态
journalctl --user -u egodata-api -f          # 实时日志
systemctl --user restart egodata-api         # 重启后端(前端同一个进程)
systemctl --user list-timers egodata-watchdog.timer   # 看门狗巡检计划

注意:前端与后端是同一个服务(uvicorn 同时提供 API 和网页模板),没有独立的前端进程。