Modly日志与会话归档系统揭秘：3D模型生成桌面应用如何快速定位线上问题

Modly日志与会话归档系统揭秘3D模型生成桌面应用如何快速定位线上问题【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modlyModly 是一款能在本地 GPU 上从图片、文字提示词直接生成 3D 模型的桌面应用。由于它同时运行 Electron 前端和 PythonFastAPI后端两套进程任何一环出错都可能出现界面闪一下就没了这类难以复现的问题。为此 Modly 内置了一套日志 会话归档系统每个会话的日志自动分文件落盘、按启动时间打包归档并在设置页提供一键查看与复制帮助开发者与用户快速定位线上问题。日志系统架构三个文件各司其职Modly 的日志统一存放在用户数据目录userData/logs下按职责拆成三个文件见 logger.ts日志文件写入内容用途modly.logElectron 主进程的全部 INFO / WARN / ERROR 记录追踪应用启动、扩展安装、更新等通用流程errors.log所有 ERROR 级别记录以及 Python 侧含 error、exception、traceback 等关键词的输出排错第一入口只关心报错时看它就够runtime.logPython FastAPI / uvicorn 前后端桥接的 stdout 与 stderr排查模型推理、3D 生成等后端运行时问题每一条日志都会带上 ISO 时间戳与级别标签格式形如[2026-03-20T10:23:45.123Z] [ERROR] ...方便按时间线对齐前后端行为。日志从哪来四条写入通道日志并非只有一个入口Modly 为不同进程各留了一条管道主进程日志logger.info / warn / error写入modly.log其中error会同时双写errors.loglogger.ts#L59-L68。未捕获异常兜底主进程顶层监听uncaughtException与unhandledRejection任何漏网异常都会被记入errors.log并推送到界面index.ts#L77-L87。Python 运行时输出Electron 通过 python-bridge.ts 启动 uvicorn并把其 stdout / stderr 逐行送入logger.python()正常输出进runtime.log检测到报错关键词时再追加进errors.log。前端渲染进程界面侧可通过 IPC 事件log:error上报错误统一打上[Renderer]前缀写入ipc-handlers.ts#L324。此外写入函数对console做了 EPIPE 防护——即使日志管道失效例如终端被关闭日志系统本身也绝不会把应用搞崩这本身就是线上问题定位的一道保险。会话归档每次启动自动打包只留最近10次Modly 用会话Session划分每一次应用启动归档逻辑集中在 archiveCurrentSession()应用每次启动时app.whenReady回调会第一时间执行归档index.ts#L89-L91把上一次会话的三个日志文件整体移入logs/sessions/时间戳/目录目录名采用2026-03-20T10-23-45这样的启动时间戳按名称排序即时间顺序归档后自动清理旧会话仅保留最近 10 次MAX_SESSIONS 10磁盘占用可控。归档后的目录结构大致如下userData/logs/ ├── modly.log ← 当前会话正在写入 ├── errors.log ├── runtime.log └── sessions/ ├── 2026-03-20T10-23-45/ └── 2026-03-21T09-01-12/这套机制的关键价值在于用户上次崩溃时的现场日志不会被本次启动覆盖问题发生后仍可在最近 10 个会话中逐段回溯。设置页查看日志切换会话、一键复制归档不是目的能查看才是。Modly 在设置 → Logs页面LogsSection.tsx提供了完整的日志面板会话下拉框默认显示Current session当前会话也可切换到任意历史归档会话列表来自 IPC 接口log:listSessionsipc-handlers.ts#L341-L352三个文件标签页ErrorsElectron 与 Python 全部报错、RuntimeFastAPI / Python 输出、AppElectron 通用日志Refresh / Copy all 按钮刷新或一键复制当前文件全部内容方便直接粘贴到问题反馈中——页面上也明确提示了这一点。前端通过 preload 层暴露的window.electron.log.readAll / listSessions读写日志electron-api.ts#L168-L169渲染进程不直接碰磁盘权限收口在主进程。快速定位线上问题的实操步骤 遇到生成失败、界面报错、扩展安装卡住等问题时建议按以下顺序排查先看errors.log只含错误记录噪音最小。优先确认错误发生在 Electron 侧还是 Python 侧看前缀是否为RUNTIME/[Renderer]。按时间戳切到出问题的会话在设置页会话下拉框中选择故障发生前后那次启动对应的归档避免被当前会话日志干扰。到runtime.log对齐后端行为3D 模型生成类问题如工作流节点报错通常伴随 FastAPI 端的 traceback可与errors.log中同一时刻的记录互相印证。点 Copy all 完整导出提交问题反馈时附上会话时间与三个文件的完整内容开发者即可按时间戳快速还原现场。相关源码索引 日志核心格式、写入、归档、保留策略electron/main/logger.ts异常兜底与启动时归档触发electron/main/index.ts日志 IPC 接口读取 / 列出会话electron/main/ipc-handlers.tsPython 输出捕获桥接electron/main/python-bridge.ts设置页日志面板 UIsrc/areas/settings/components/LogsSection.tsx小结Modly 的日志与会话归档系统用极简的设计解决了本地 AI 桌面应用最常见的排错难题分文件降低噪音、按启动时间归档保住现场、10 次上限控制磁盘、设置页一键查看复制。当你从图片生成 3D 模型遇到任何异常时打开设置页的 Logs 面板就是定位线上问题最快的入口。【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考