企业官网建设流程全解析

LumenX 是一款基于 Tauri 的 AI 短漫剧一站式生产平台，桌面应用能将小说文本转化为动态视频，打通剧本分析、角色定制、分镜绘制到视频合成的完整创作链路。本文面向新手用户，讲清楚 LumenX 桌面应用的日常使用方式，以及两个最常被问到的维护问题：怎么查看日志、怎么安全地清理缓存，并附上常见问题排查清单，读完即可完成大部分自助排障。

桌面应用的结构：前端界面 + Python 后端（Sidecar）

理解排查方法之前，先花 30 秒了解 LumenX 桌面应用的架构，后面所有内容都会好懂很多：

• 前端界面：由 Tauri 外壳承载，负责全部可视化操作（项目、分镜、Playground 等），配置见 tauri.conf.json。
• Python 后端：应用启动时会自动拉起一个内嵌的 FastAPI 后端进程（Sidecar 模式），监听本机127.0.0.1:17177端口，负责所有模型调用、文件存储与健康检查。启动与守护逻辑在 sidecar.rs 中：每 200ms 轮询一次/health接口，最长等待 30 秒确认后端就绪。
• 数据与日志：默认统一存放在用户主目录下的~/.lumen-x/中（代码逻辑见 src/utils/init.py）。

💡 也就是说：界面卡住 ≠ 后端死了。排查时先确认17177端口上的后端是否存活，再决定是刷新页面还是重启应用。

快速上手：启动与日常使用

1. 安装并打开 LumenX Studio（macOS 需要 12.0 及以上版本，打包目标为 dmg/app，见 tauri.conf.json 中的minimumSystemVersion配置）。
2. 首次启动后稍等几秒，后端 Sidecar 会自动完成自检，无需手动执行任何命令。
3. 在「设置 → API 密钥」中填入模型服务的 API Key，密钥仅保存在本地，不会上传。
4. macOS 下可使用原生菜单栏快捷操作：⌘ + ,打开设置、⌘ + N新建项目，菜单实现见 menu.rs。

日志查看：三条路径，从易到难

方式一：任务卡住时，用内置 Diagnose 弹窗（推荐）

这是最不需要动手的方案。当分镜生成等任务等待超过 60 秒，界面上会出现Cancel和Diagnose按钮。点击 Diagnose 会打开诊断弹窗，自动完成三件事（组件实现见 PendingTaskAffordance.tsx）：

• 检测后端是否可达，并显示当前项目数量；
• 展示日志文件的完整路径，一键复制；
• 自动拉取日志最后 200 行，并把ERROR、Exception、Traceback等错误行单独置顶到「Errors only」区域——根因通常就在这一小块红色区域里。

方式二：直接打开日志文件

日志默认写入以下位置（各系统路径写法略有差异）：

打开方式任选其一：

• 在应用内「设置 → 关于」或「存储」页签，可以看到只读展示的LOG_DIR与DATA_DIR路径（文案定义见 zh.json），复制路径后在文件管理器中打开即可；
• 终端执行：tail -n 100 ~/.lumen-x/logs/app.log。

两个环境变量可以覆盖默认目录：LUMENX_DATA_DIR修改数据根目录，LUMENX_LOG_DIR修改日志目录，方便需要集中管理日志的场景。

日志不会无限膨胀：采用滚动写入策略，单文件上限 5MB，保留 3 个备份（app.log.1~app.log.3），总占用约 20MB 封顶（配置见 src/utils/init.py 中的_LOG_MAX_BYTES与_LOG_BACKUP_COUNT）。

方式三：通过后端接口读取

后端提供两个只读接口，可用于脚本化检查：

• GET http://127.0.0.1:17177/health：返回后端是否存活及日志路径，实现见 api.py；
• GET http://127.0.0.1:17177/diagnose/log_tail?lines=200：返回日志末尾 N 行（上限 1000 行）及自动提取的错误摘要。

缓存与数据文件都在哪，哪些可以清理

LumenX 的落盘文件分两类，别混在一起删：

1. 用户数据目录~/.lumen-x/（谨慎操作）

包含运行配置config.json与logs/日志。删掉config.json需要重新配置密钥与模型，排查问题前不要删除整个目录。

2. 生成输出目录output/（可安全清理）

后端在后端工作目录下按用途组织了若干子目录（挂载逻辑见 api.py）：

• output/cache/：模型返回媒体的本地缓存（按 URL 哈希命名）、语音预览缓存等，删除后应用会自动重新下载/生成，可放心清理；
• output/playground/images/、output/playground/videos/：Playground 独立生成的结果，想释放空间可整目录删除；
• output/uploads/、output/video/、output/assets/：项目资产与成片，属于你的创作内容，删除前请确认已备份。

清理缓存的建议步骤：

1. 完全退出 LumenX Studio（确保 Sidecar 后端进程结束）；
2. 进入后端工作目录下的output/cache/，删除其中的子目录内容；
3. 如有需要，同样处理output/playground/下不再保留的生成结果；
4. 重新启动应用，一切功能自动恢复。

⚠️ 日志文件（app.log*）在提报问题时是重要证据，提交 Issue 前请勿清理。

常见问题排查清单（FAQ）

Q1：界面提示「当前离线」或后端不可达？先用 Diagnose 弹窗或GET /health确认后端是否存活。若不可达，说明 Sidecar 已退出：重启应用即可，后端会自动重新拉起。注意：后端重启会清空内存中的任务，卡住的任务会被自动标记为失败，重新提交一般就能恢复。

Q2：视频合成/配音报 ffmpeg 相关错误？后端内置系统自检逻辑（system_check.py），会优先使用打包携带的 ffmpeg，否则回退到系统 PATH。macOS/Linux 可执行ffmpeg -version确认是否安装；Windows 需把 ffmpeg 的bin目录加入 PATH 后重启应用才会生效。

Q3：任务一直转圈不动？按顺序执行：按 F5 刷新页面排除前端轮询中断 → 点 Diagnose 看「Errors only」红色区域（常见根因：密钥过期、网络不通、模型参数错误）→ 仍未解决则重启应用。

Q4：如何确认版本是否为最新？「设置 → 关于」页内置了更新检查器，会显示当前版本（如 v1.2.1，版本定义见 tauri.conf.json），并支持检查可用更新。

Q5：占用空间越来越大，如何评估？先看output/目录大小（生成结果是大头），日志目录本身被滚动策略限制在约 20MB 内，通常无需处理。

小结

LumenX 桌面应用的日常维护其实只有三件事：用 Diagnose 弹窗看日志、在「设置」页确认 DATA_DIR / LOG_DIR 路径、定期清理output/cache/与output/playground/。配合127.0.0.1:17177/health健康检查接口，绝大多数「卡住 / 离线 / 报错」问题都能在不联系开发者的情况下自助解决。更多后端行为细节可参考 src/apps/comic_gen/api.py 与 src/utils/ 目录下的工具模块。