桌面故障排除

在更改之前确定运行时

桌面会话有单独的故障边界：Vite 在开发过程中提供前端资产； Tauri Rust 进程拥有原生集成； Bun sidecar 服务于应用程序请求和持久性； SolidJS Webview 连接到该 API。空白窗口、启动超时、401 响应和空项目列表可能有不同的原因。

记录启动命令以及端点是否来自 Tauri 还是 Vite 变量。不要仅仅因为不同的运行时显示不同的数据而删除数据库或重新安装依赖项。

了解启动时序

Rust shell 生成启动令牌，解析应用程序数据和迁移目录，并生成目标 sidecar。孩子绑定了 127.0.0.1 在临时端口上。它等到公开 /api/health 答案，然后使用该端口写入 JSON 就绪事件。网络视图调用 get_sidecar_endpoint 并创建其托管 API 运行时。

Retry 重新启动 webview 连接尝试；它不会补充已经耗尽的 Rust 监督预算。当 Supervisor 达到终端失败状态时，修复启动原因并重新启动应用程序。子进程重新启动之前的端口可能已过时。

分别检查端口和健康状况

Vite用途 localhost:1420 严格的端口选择，匹配Tauri配置的开发URL。它会失败，而不是默默地移动到另一个端口。 Sidecar 端口不相关，并且在发布之间会发生变化。配套 HTTPS 端口是第三个侦听器，默认为 8443，Studio 使用环回 4396。

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token

curl --max-time 5 --fail-with-body "$CADCAM_URL/api/health"
curl --max-time 5 --fail-with-body "$CADCAM_URL/health"   -H "Authorization: Bearer $CADCAM_TOKEN"
curl --max-time 5 --fail-with-body "$CADCAM_URL/version"   -H "Authorization: Bearer $CADCAM_TOKEN"

公共卫生路由返回状态和时间戳。经过身份验证的系统路由会公开准备情况和应用程序版本。健康的流程并不能证明所有提供程序、数据库查询或本机对话框都有效。比较 健康API 和 系统接口 选择探头时。

如果端口1420被占用，请主动识别并停止现有的开发服务器。如果记住的 API 端口拒绝连接，请读取当前就绪事件或重新解析 Tauri 端点，而不是猜测相邻端口。

使用隔离的 sidecar 进行复制

源进程对于将本机捆绑包问题与服务器行为分开非常有用。在交互式终端中从存储库根运行此命令；它创建一个新的数据目录并显式使用生成的迁移文件夹。

CADCAM_DIAGNOSTIC_DIR=$(mktemp -d /tmp/cadcamfun-desktop-guide.XXXXXX)
CADCAMFUN_TOKEN=local-development-token CADCAMFUN_DATA_DIR="$CADCAM_DIAGNOSTIC_DIR/data" CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" CADCAMFUN_AI_OFFLINE=true bun --no-env-file apps/sidecar/src/main.ts

将宣布的端口复制到第二个终端的探测变量中。离线AI模式避免依赖配置的远程模型进行基本启动诊断；它不运行替代的本地模型。服务器观察 stdin EOF、显式关闭事件和正常运行时中断。

源进程使用当前文件。本机进程使用已编译的可执行文件 src-tauri/binaries。如果只是编译运行失败，则通过重建 bun run build:sidecar 并检查捆绑/迁移资源。编辑 TypeScript 不会替换已经运行的可执行文件。

解析实际数据库路径

这些文件不是别名。在调查丢失的图纸之前匹配选定的工艺路径。浏览器设备永远不会打开这些 SQLite 文件。 sidecar 仅当其配置提供迁移文件夹时才应用迁移；省略它不会自动发现源树文件夹。

数据库层启用WAL和外键。在升级现有数据库之前，它会写入自动迁移前备份并保留五个匹配的备份。它不会在每次保存、未更改的启动、首次创建或内存测试时创建此类备份。通过数据库/恢复过程保留一致的备份；仅复制正在运行的 WAL 数据库的主文件可以忽略已提交的 WAL 内容。

读取协议输出和日志

在源 sidecar 终端中，stdout 保留用于就绪/错误协议事件，JSON 应用程序日志将转到 stderr。在本机应用程序中，Rust 日志记录插件捕获 shell 端事件，包括受监督的子输出。 shell 会编辑可能包含其启动凭据的行。

当地人 get_logs_dir 命令解析操作系统应用程序日志目录。它比假设跨系统的通用路径更可靠。 Webview 内的开发人员诊断可以通过现有的 Tauri 命令接口调用它；本机路径打开仅限于允许的文件夹并拒绝可执行文件类型。

可重用的启动屏幕组件支持可选的查看日志回调，但当前 App.tsx 不通过该回调。不要假设“查看日志”按钮在启动失败期间可见。保持开发启动终端可用或通过适当的诊断界面使用本机日志目录。

对于报告，请包括启动模式、非秘密数据/迁移路径、已用等待时间、当前 API 版本、确切的错误标记/消息以及上次相关启动事件。编辑启动/会话/设备令牌、配对链接、模型密钥和签名材料。

区分身份验证和空数据

浏览器真实客户端模式需要两者 VITE_SIDECAR_URL 和 VITE_SIDECAR_TOKEN。没有令牌的 URL 不会激活假后备；端点解析失败。 Vite 启动前必须提供变量。更新父 shell 不会重新配置已运行的服务器。

VITE_SIDECAR_URL=http://127.0.0.1:43111 VITE_SIDECAR_TOKEN=local-development-token bun run --filter @cadcamfun/desktop dev

除了应用程序令牌之外，受保护的调用还可以使用帐户会话上下文。伴随和独立桥代币的范围较窄，并且不能替代启动代币。 401 需要凭证诊断； 403需要操作/访问诊断；不存在或无法访问的项目可以报告为 404。

某些屏幕（包括项目子资源选项卡）当前将单个列表错误转换为空数组。空白选项卡不足以证明记录已被删除。阅读相应的 项目, 绘画， 或者 刀具路径 重新创建工作之前的端点。

有效的启动令牌是 64 个十六进制字符（32 个随机字节），并且在每次启动时都会发生变化。桌面 shell 不发出不同形状的令牌。

认识预览和本机限制

假 API 处理选定的项目、图纸、材料、工具、机器、工具路径、KV 和生成器路径。不受支持的集合会返回 HTTP 501 以及特定于预览的消息。灯具数据属于运行页面。成功的预览操作无法展示持久的组织、插件、计费或实时提供程序行为。

本机对话框、钥匙串操作、托盘、更新程序和 macOS 材料需要 Tauri 主机和正确的功能。在其功能配置下，已注册的命令仍然对 Web 视图不可用。对于文件打开，shell 会注册支持的关联并转发路径；仅凭这一点并不能证明特定编辑器导入了内容。

图形故障是另一个边界。非零容器大小、可见实体/图层、解锁选择和支持的 WebGL 是相关视口交互的先决条件。渲染的网格是渲染的证据，而不是成功的保存或 CAM 验证。使用 视口诊断 针对工作人员容量、超时和四视图行为。

恢复首选项和显示问题

共享的webview首选项记录是 cadcamfun.settings。默认值包括毫米、系统主题、三位小数、GRBL 首选项、启用捕捉、公差 0.01 毫米和启用玻璃。存储的字段独立验证；无效值会回退而不会使 shell 失败。完整/阻塞的本地存储可能会阻止持久性。

更改显示单位不会重新缩放存储的 CAD 几何图形。文档容差通过共享 CAD/生成器/验证设置帮助程序传播。一些特征/旋转值明确使用度数；绘制角度使用弧度。在将数值不匹配诊断为损坏的几何体之前，请验证现场契约。

Glass 行为取决于 Tauri/macOS 支持。该实现在支持的情况下使用 Liquid Glass，通过插件在旧版 macOS 上提供活力，并在不可用或禁用时使用不透明的回退。主题/材料更改不会改变几何形状、项目所有权或加工证据。

优先选择相关设置或功能控制而不是清除所有 webview 存储。该存储还可以包含会话/编辑器切换。视觉首选项重置不是数据库修复过程。

将 UI 恢复与加工证据分开

加载的项目、成功的 HTTP 保存、动画刀具路径和生成的 NC 是不同的观察结果。在依赖保存的加工结果之前，请检查该结果的精确 NC、源图纸/库存、工具组件、机器包络、选定的帖子和验证发布/问题。

仅当当前 NC 文本与其哈希匹配时，CAM 快照代码才会保留内核证据。可移植程序写入验证文档一致性，并可能重新评估捕获的内核请求。编辑 NC 或更改库存可能会使之前的证据失效。重新打开普通 NC 可以解析程序，而无需恢复相同的制造证明。

发生崩溃或保存中断后，首先检查已保存的行及其版本。 CAM 保存模式记录更新前的先前程序，而刀具路径详细信息手动保存则记录更新后的修订。项目历史再次分开。使用 历史比较 选择恢复路径。

不要将未解决的检查转换为已接受的操作，因为 UI 已恢复。针对实际资源和 NC 重新运行适当的验证；应用程序运行状况探测器对机器安全没有权限。

一次对一个故障进行分类

1. 记录启动模式、进程版本、端口和实际数据目录。
2. 探测健康状况，然后进行一项受保护的读取。将连接与授权分开。
3. 在重置或删除任何内容之前检查结构化启动/迁移错误。
4. 当怀疑编译/本机问题时，针对隔离源进程进行重现。
5. 修复已识别的原因，重新启动适当的进程，并更新过时的端点变量。
6. 重新打开保存的文档/程序并检查持久状态、版本、导出和当前验证。

实施锚点是 app/App.tsx, app/sidecar.ts, src-tauri/src/{sidecar,commands,lib}.rs, 边车 main.ts/config.ts/shutdown.ts，以及数据库生命周期。 当地发展 提供配置详细信息； 同伴配对 处理其单独的网络边界。

启动清单

1. 该平台是否存在 sidecar 二进制文件（src-tauri/binaries/sidecar-<target triple>)? desktop:dev 构建它； tauri:dev 可以使用存根。
2. 迁移是否发生在 src-tauri/resources/migrations? bun run build:sidecar 或 bun scripts/build.ts --only=resources 重新演绎它们。
3. 边车打印了吗 ready 60 秒内？寻找一个 error 日志目录中 stdout 上的行和 stderr 上的 JSON 日志（get_logs_dir).
4. 重启了吗？只允许自动重启一次；第二次失败会使状态保持在 failed.
5. 做 GET /api/health 在报告的端口上回答？如果确实如此，但受保护的路由返回 401，则该令牌属于不同的启动。
6. 数据目录是否可写，并且数据库文件是否未被具有不兼容迁移的另一个进程保持打开状态？

读取日志

Sidecar 日志是 stderr 上的 JSON 行，与 stdout 握手分开。可能包含凭据的行被替换为 [redacted: line may contain credentials] 在写入之前，因此日志中会出现经过编辑的行，而不是损坏。如果握手本身带有这样一行，则报告的启动错误是修订标记；阅读周围的 stderr 行以了解上下文。

日志目录是特定于平台的。从 get_logs_dir 命令而不是猜测路径，然后使用以下命令打开它 open_path，它接受应用程序日志目录。

错误消息及其含义

在 3D