# Neta Windows 托盘模式设计

> 日期：2026-04-25
> 状态：待实施
> 修订：v2 — 按架构复核收紧运行时边界、控制接口与实施顺序

## 目标

在现有 Windows 离线安装链路基础上，为 Neta 增加首版托盘模式。
首版要求保留当前安装器总体体验，但新增完整的 Windows 托盘入口，使用户可以通过托盘完成打开系统、启停服务、打开目录和退出程序。

本期目标不是重做桌面端架构，而是在不改动数据库安全方案的前提下，补齐 Windows 本地使用体验中最明显的缺口。

## 当前项目现实

当前 Neta 的 Windows 运行链路已经具备以下真实状态：

- `backend.exe` 是现有唯一运行入口，启动入口为 `packages/backend/bootstrap.js`
- 启动前已会读取外部 `config.yaml` 并注入运行配置
- `backend.exe` 已负责真实端口选择、`data.dir` 路径收口、日志目录、运行锁和自动打开浏览器
- Inno Setup 当前默认安装、快捷方式、首次启动和卸载都直接围绕 `backend.exe`
- 仓库当前没有现成的桌面端托盘基础设施，也没有 `.NET` / Rust / Go 托盘项目

因此，这次托盘设计必须是对现有单进程 Windows 架构的增量改造，而不是重画一套新的桌面运行时。

## 已确认约束

- 保持当前启动方式总体体验不变，只是额外增加托盘图标和托盘菜单
- 首版托盘菜单必须包含：
  - 打开系统
  - 重启服务
  - 停止服务
  - 打开日志目录
  - 打开配置目录
  - 退出程序
- 安装器允许新增独立 `tray.exe`
- 桌面快捷方式和开机自启都统一启动 `tray.exe`
- `tray.exe` 负责拉起和监控 `backend.exe`
- 数据库安全相关问题本期不改，继续沿用当前 `config.yaml` 方案
- 不引入 Windows Service
- 不实现“关闭浏览器窗口后最小化到托盘”
- 不实现自动更新、首次启动配置向导
- 不调整 `config.yaml` 的当前存放位置

## 1. 方案对比

### 方案 A：独立 `tray.exe` + 现有 `backend.exe`（推荐）

- `backend.exe` 继续承载 Midway.js 后端与前端静态资源
- 新增一个轻量原生 Windows 托盘程序 `tray.exe`
- `tray.exe` 负责托盘图标、菜单、开机自启、单实例、启动/停止/重启 `backend.exe`
- 安装器入口、桌面快捷方式、开始菜单和开机自启统一指向 `tray.exe`

优点：
- Windows 职责边界清晰，托盘控制和 Web 服务解耦
- 便于处理托盘生命周期、单实例和目录打开等原生能力
- 后续若继续扩展状态提示、升级控制器、最小化托盘等能力，演进路径更自然

代价：
- 安装产物从一个主 exe 变成两个 exe
- 打包链路需要增加一个托盘程序构建步骤
- 打包环境要新增桌面端工具链依赖

### 方案 B：把托盘能力并入 `backend.exe`

- 继续只保留 `backend.exe`
- 同一个进程同时承担后端服务与托盘功能

优点：
- 产物更少
- 打包表面上更简单

代价：
- Node/pkg 进程承载 Windows 原生托盘能力更复杂
- 进程窗口形态、生命周期和服务控制容易互相耦合
- 后续加菜单状态和异常恢复时复杂度明显更高

### 方案 C：`tray.exe` 仅做启动器，核心控制仍回到 `backend.exe`

优点：
- 比单进程更容易落地

代价：
- 职责边界仍不干净
- 后续扩菜单、状态同步和异常恢复时容易重新耦合

### 结论

采用方案 A：新增独立 `tray.exe` 作为 Windows 壳层，`backend.exe` 保持当前服务职责。

## 2. 总体架构

安装产物分成两层：

- `backend.exe`：现有 pkg 产物，继续负责 Midway.js 服务、静态前端、配置加载、数据目录解析、真实端口选择、单实例、优雅退出
- `tray.exe`：新增 Windows 托盘控制器，负责本地托盘交互、菜单操作和后端进程编排

启动路径改为：

```text
桌面快捷方式 / 开机自启 / 开始菜单
  -> tray.exe
      -> 检查 backend.exe 是否已运行
      -> 未运行则拉起 backend.exe
      -> 已运行则仅挂托盘
```

核心原则：

- `backend.exe` 是唯一运行时真源
- Web 服务职责、真实端口、路径、锁、ready 状态全部保留在 `backend.exe`
- `tray.exe` 不是第二个运行时中心，只是本地壳层和控制面消费者
- 两者之间只通过最小化的本机控制协议通信，不共享业务逻辑

## 3. 托盘菜单定义

首版托盘菜单固定包含以下项目：

1. 打开系统
   - 打开当前本地前端首页
   - URL 必须来自 `backend.exe` 状态接口返回值，不由 `tray.exe` 自行猜测

2. 重启服务
   - 由 `tray.exe` 先请求 `backend.exe` 优雅停止
   - 停止完成后，再由 `tray.exe` 重新拉起 `backend.exe`
   - “重启”是托盘侧的编排动作，不是后端自重启接口

3. 停止服务
   - 由 `tray.exe` 调用本机 stop 控制接口
   - 等待后端退出，并将托盘状态更新为“服务未运行”

4. 打开日志目录
   - 打开 `{dataDir}/logs`

5. 打开配置目录
   - 打开安装目录中 `config.yaml` 所在目录

6. 退出程序
   - 默认同时退出托盘和后端服务
   - 顺序为：先请求后端优雅退出，再退出 `tray.exe`
   - 如后端超时未退出，可执行兜底强制结束

## 4. 本机控制协议

`tray.exe` 不承载业务逻辑，只作为本机控制层。
`backend.exe` 在现有 Web 服务之外，新增一个仅本机可用的最小控制入口供托盘调用。

### 4.1 通信方式

首版采用 loopback HTTP：

- 仅监听 `127.0.0.1`
- 不对外网暴露
- 使用本地 secret 进行鉴权，避免同机其他进程随意控制

### 4.2 首次发现机制

为了解决动态端口和托盘首次附着问题，`backend.exe` 启动后必须在 `{dataDir}/runtime-info.json` 写入本机运行时引导信息。

该文件至少包含：

- `pid`
- `ready`
- `startedAt`
- `port`
- `url`
- `controlBaseUrl`
- `controlSecret`
- `dataDir`
- `logDir`
- `configDir`

用途：

- `tray.exe` 首次启动时，先通过安装目录下的 `config.yaml` 定位 `data.dir`
- 再从 `{dataDir}/runtime-info.json` 读取当前 `backend.exe` 的真实控制地址和本机 secret
- 从而避免硬编码 8003，也避免在“backend 已经在运行”时无法获知 secret

`runtime-info.json` 是本地桌面版运行时的引导文件，不是对外 API，也不是新的业务配置入口。

### 4.3 最小控制面

首版只提供两个接口：

- `GET /base/runtime/status`
- `POST /base/runtime/stop`

说明：

- 路由层级必须遵循当前 `modules/base/controller/app/*.ts` 的现有挂载风格
- 这里的 `/base/runtime/*` 是基于当前 `app/comm` 控制器实际访问模式确定的逻辑落点

明确不提供：

- `POST /base/runtime/restart`
- `POST /base/runtime/open`

原因：

- `restart` 应由 `tray.exe` 负责 stop + spawn 编排，不应由 `backend.exe` 自己承担自重启职责
- `open` 不需要独立控制接口，`tray.exe` 从状态接口取得真实 URL 后自行打开浏览器即可

### 4.4 状态接口返回内容

状态接口至少返回：

- 当前运行状态
- ready 状态
- 实际监听端口
- 首页 URL
- 数据目录路径
- 日志目录路径
- 配置目录路径
- 后端 PID

这样 `tray.exe` 可以始终依赖真实运行状态驱动菜单，而不是自行拼接路径或端口。

### 4.5 启动握手

`tray.exe` 启动后执行：

1. 读取安装目录下的 `config.yaml`，得到 `data.dir`
2. 读取 `{dataDir}/runtime-info.json`
3. 若引导文件存在，则先根据其中的 `pid` 与 `controlBaseUrl` 尝试附着已有 `backend.exe`
4. 若状态接口返回 ready，则仅挂载托盘
5. 若引导文件缺失、陈旧或接口不可达，则由 `tray.exe` 拉起新的 `backend.exe`
6. 新进程启动后，先轮询 `runtime-info.json`，再轮询 `status` 接口直到 ready
7. ready 后刷新菜单状态

运行时存活性判断优先级保持为：

1. `status` 接口
2. `backend.exe` 进程是否仍存活
3. `neta.lock` 仅作诊断辅助

### 4.6 鉴权

首版控制接口必须具备本机鉴权机制：

- `backend.exe` 每次启动都生成新的 `controlSecret`
- `controlSecret` 仅写入 `{dataDir}/runtime-info.json`，供本机 `tray.exe` 复用
- `tray.exe` 后续请求必须携带该 secret
- 正常退出时必须清理 `runtime-info.json`

这样既保留了“每次启动轮换 secret”的边界，也解决了托盘在附着已运行 backend 时的发现问题。
## 5. 运行时行为与边界条件

### 5.1 单实例

- `backend.exe` 继续保留现有单实例锁与运行检测逻辑
- `tray.exe` 也需要独立单实例保护，避免出现多个托盘图标
- 如果重复启动 `tray.exe`，不创建第二个实例，而是唤起已有实例并执行“打开系统”

### 5.2 状态判断优先级

`tray.exe` 判断 `backend.exe` 状态时，优先级固定为：

1. 先探测本机 `status` 接口
2. 接口不可达时，再检查 `backend.exe` 进程是否存在
3. `neta.lock` 仅作为诊断辅助，不作为一等控制协议

原因：

- 当前真实端口由 `backend.exe` 决定
- `backend.exe` 已有自己的锁和退出清理机制
- 直接依赖锁文件容易与真实 ready 状态漂移

### 5.3 端口处理

- `backend.exe` 继续沿用现有可用端口探测逻辑，不强制固定 8003
- `tray.exe` 不自行猜测端口
- “打开系统”始终使用状态接口返回的真实 URL

### 5.4 启动失败

- `tray.exe` 拉起后端后，在限定时间内轮询状态接口
- 若超时仍未 ready，托盘图标进入“异常”状态
- 菜单保留“打开日志目录”和“重试启动”的恢复路径
- 首版不增加复杂配置向导，只提示“服务启动失败，请查看日志”

### 5.5 后端异常退出

- `tray.exe` 持续感知 `backend.exe` 状态
- 若后端异常崩溃，托盘菜单切换为“服务未运行”
- 用户可以直接从托盘执行重启服务

### 5.6 优雅退出

退出顺序固定为：

```text
tray.exe 发起 stop 请求
  -> backend.exe 执行优雅收尾
  -> 超时则由 tray.exe 兜底结束
  -> tray.exe 自身退出
```

同一顺序也用于安装器卸载阶段。

### 5.7 手动运行 backend.exe

如果用户绕过标准入口，直接双击 `backend.exe`：

- 服务仍可启动
- 但不保证拥有完整托盘体验
- 标准使用入口仍是 `tray.exe`

## 6. 技术选型

建议新增一个独立包：`packages/windows-tray/`。

### 6.1 推荐实现

使用 `.NET 8` 实现原生 Windows 托盘程序，并发布为自包含单文件 `tray.exe`。

推荐原因：

- 做系统托盘、单实例、打开目录、进程管理这些 Windows 原生动作更稳妥
- 与 Node/pkg 运行时彻底解耦
- 可以直接产出适合 Inno Setup 分发的单文件 exe
- 不要求最终用户额外安装 .NET Runtime

### 6.2 当前仓库前提

当前 Neta 仓库中没有现成的 `.NET` 托盘工程，因此这不是接入现有桌面端项目，而是新增一条桌面端工具链。

这意味着打包环境必须新增前置条件：

- 打包机安装 `.NET 8 SDK`
- 安装器构建脚本支持 `dotnet publish`
- Windows 打包说明同步补充 `.NET 8 SDK` 依赖

### 6.3 为什么不放进现有前后端栈里做

- 前端 Vue 不是桌面托盘技术栈
- 后端 Node/pkg 进程更适合承担服务，不适合顺带承载稳定的 Windows 壳层能力
- 用独立托盘程序更符合当前项目边界：业务继续在后端，UI 继续在浏览器，Windows 壳层作为单独辅助包存在

## 7. 仓库改动清单

### 7.1 新增后端控制层

建议新增：

- `packages/backend/src/modules/base/controller/app/runtime.ts`
- `packages/backend/src/modules/base/service/runtime.ts`
- `packages/backend/src/comm/runtime-secret.ts`
- `packages/backend/src/comm/runtime-state.ts`
- `packages/backend/src/comm/runtime-info.ts`
- `packages/backend/src/comm/graceful-shutdown.ts`

建议修改：

- `packages/backend/bootstrap.js`
  - 新增最小 CLI 参数支持，例如：
    - `--tray-secret`
    - `--no-browser`
- `packages/backend/src/configuration.ts`
  - 注册统一 shutdown coordinator
  - 暴露真实端口、目录和运行状态
  - 维护并清理 `{dataDir}/runtime-info.json`

### 7.2 新增托盘包

建议新增：

- `packages/windows-tray/Neta.Tray.csproj`
- `packages/windows-tray/Program.cs`
- `packages/windows-tray/TrayApplicationContext.cs`
- `packages/windows-tray/BackendProcessManager.cs`
- `packages/windows-tray/RuntimeInfoStore.cs`
- `packages/windows-tray/StatusClient.cs`
- `packages/windows-tray/SingleInstance.cs`
- `packages/windows-tray/Assets/neta.ico`

职责包括：

- 托盘图标与菜单
- 单实例
- 读取 `config.yaml` 与 `runtime-info.json`
- 启动 `backend.exe`
- 请求停止 `backend.exe`
- 编排重启 `backend.exe`
- 打开浏览器
- 打开日志目录
- 打开配置目录
- 按“status > process > lock”顺序判断状态
- 支持安装器卸载阶段的无界面 `--shutdown` 模式

### 7.3 修改打包和安装器链路

建议修改：

- `packages/backend/scripts/build-windows-installer.js`
  - 先生成 `backend.exe`
  - 再执行 `dotnet publish` 生成 `tray.exe`
  - 最后一起交给 Inno Setup 打包
- `packages/backend/installer/setup.iss`
  - 安装 `backend.exe` 与 `tray.exe`
  - 桌面快捷方式改为指向 `tray.exe`
  - 开机自启注册表改为指向 `tray.exe`
  - 卸载时优先调用 `tray.exe --shutdown`
  - 若优雅停机失败，再兜底 `taskkill`

## 8. 实施顺序

这次改造必须严格分阶段推进，不能并行混改：

1. 先在 `backend.exe` 中补齐最小本机控制面
2. 再实现 `tray.exe` 并接入状态轮询、启停编排与单实例
3. 最后修改安装器、快捷方式、开机自启和卸载流程

原因：

- `tray.exe` 必须依赖 `backend.exe` 的真实状态面才能稳定工作
- 当前安装器和卸载逻辑是围绕 `backend.exe` 写死的
- 若未先立住控制面，托盘实现会被迫用端口猜测、进程猜测和锁文件硬拼状态

## 9. 安装器行为

### 9.1 安装后入口

安装完成后：

- 桌面快捷方式指向 `tray.exe`
- 开始菜单入口指向 `tray.exe`
- 若勾选开机自启，注册表项写入 `tray.exe`

### 9.2 卸载顺序

卸载时执行：

1. 调用 `tray.exe --shutdown`，由托盘侧先请求 `backend.exe` 优雅退出
2. 等待短超时，让 `tray.exe` 自身退出
3. 若仍有残留进程，再兜底强制结束 `tray.exe` / `backend.exe`
4. 删除程序目录
5. 根据现有安装器策略决定是否保留数据目录

### 9.3 重装

- 重装继续保留当前“程序目录覆盖、数据目录尽量不动”的原则
- `tray.exe` 只是新增程序层产物，不改变现有数据目录策略

## 10. 验证策略

### 10.1 自动验证

后端测试：

- 本机状态接口返回真实端口和目录
- 本机 secret 校验有效
- stop 行为符合预期
- 优雅退出逻辑符合预期

打包脚本 smoke：

- 能生成 `packages/backend/build/pkg-output/backend.exe`
- 能生成托盘发布产物 `tray.exe`
- Inno Setup 能将两者一并打包进安装器

### 10.2 Windows 手工验收

必须验证：

- 安装后系统托盘出现图标
- “打开系统”能打开正确 URL
- “停止服务 / 重启服务”状态切换正确
- “打开日志目录 / 打开配置目录”路径正确
- “退出程序”能同时退出托盘与后端
- 卸载后程序目录清理正常
- 重装后数据目录不会被误删

## 11. 本期明确不做

本期范围明确排除以下内容：

- 数据库安全改造
- 首次启动配置向导
- 自动更新机制
- 浏览器关闭后最小化到托盘
- 将 `backend.exe` 改造成 Windows Service
- 调整 `config.yaml` 到 ProgramData 或其他新位置

## 12. 结论

本期采用“独立 `tray.exe` + 现有 `backend.exe`”的双进程方案。

其中：

- `backend.exe` 是唯一运行时真源
- `tray.exe` 是 Windows 本地托盘控制层，也是安装器标准入口
- 两者通过仅本机可用、带 secret 鉴权的最小控制接口通信
- `tray.exe` 只消费状态并编排 stop + spawn，不承担后端自重启职责

这样可以在不重做现有安装器和服务架构的前提下，为 Windows 用户补齐托盘入口、服务启停、目录打开和整体退出能力，并为后续继续扩展桌面体验保留清晰边界。