GPU_GUARD_MONOREPO/packages/backend

Neta Backend / Windows 安装器打包说明

本文档记录当前 Windows 离线安装器的打包方式、依赖要求、产物路径，以及当前版本仍然存在的缺口。

当前状态

当前已经可以产出以下三个文件：

• build/pkg-output/backend.exe
• build/tray-output/Neta.Tray.exe
• build/installer-output/neta-setup.exe

其中：

• backend.exe 是前端静态资源 + 后端 Midway.js + Node.js 运行时的单文件产物
• Neta.Tray.exe 是 Windows 托盘控制层产物
• neta-setup.exe 是基于 Inno Setup 的离线安装器
• packages/backend/skills 会随安装器一起打包，并在首次启动时同步到数据目录的 skills/ 下

打包环境要求

建议在 Windows 10/11 x64 上打包。

需要提前安装：

1. Node.js

建议使用当前项目已验证版本范围内的 Node.js（建议 20+，当前环境也已在 Node 22 下完成打包验证）。

2. pnpm

前端构建使用 pnpm build。

安装示例：

npm install -g pnpm

3. .NET 8 SDK

生成 tray.exe 需要安装 .NET 8 SDK。

winget install Microsoft.DotNet.SDK.8

4. Inno Setup 6

生成 neta-setup.exe 需要安装 Inno Setup 6。

可使用：

winget install --id JRSoftware.InnoSetup --accept-package-agreements --accept-source-agreements

当前脚本会自动尝试从以下位置查找 ISCC.exe：

• %LOCALAPPDATA%\Programs\Inno Setup 6\ISCC.exe
• C:\Program Files (x86)\Inno Setup 6\ISCC.exe
• C:\Program Files\Inno Setup 6\ISCC.exe
• 或系统 PATH 中的 iscc

一键打包步骤

方式一：先打 exe，再打安装器

在 packages/backend 目录执行：

npm run pkg
node scripts/build-windows-installer.js

方式二：直接打安装器

npm run build:windows-installer

说明：

• build-windows-installer.js 会先检查 build/pkg-output/backend.exe
• 如果不存在，会自动先执行 scripts/pkg-build.js
• 然后执行 dotnet publish 生成 build/tray-output/Neta.Tray.exe
• 最后由 Inno Setup 生成安装器，并把 packages/backend/skills 一并带入安装目录

当前打包脚本做了什么

scripts/pkg-build.js

执行顺序如下：

1. 构建前端
2. 构建后端
3. 生成 build/pkg-stage/ staging 目录
4. 把前端产物覆盖到后端 public/ 中
5. 生成 staging 用的 package.json
6. 用 npm 在 staging 目录做扁平化生产依赖安装
7. patch generator-function 的 exports，规避 pkg 对 .mjs 的兼容问题
8. 执行 @yao-pkg/pkg 生成 backend.exe

installer 构建时的前端特殊处理

Windows 安装器构建不是普通线上前端构建，当前脚本会额外注入：

• VITE_API_BASE_URL=''
• VITE_COOL_EPS_ENABLE=true

这样做的原因：

1. 安装器场景下前后端同源运行，前端 API 需要走本地同源地址
2. installer 场景前端仍依赖构建期生成的 EPS service 代理；若关闭，会导致 service.base.open 不存在，从而在登录页初始化时报错

产物位置

打包完成后产物位于：

packages/backend/build/pkg-output/backend.exe
packages/backend/build/tray-output/Neta.Tray.exe
packages/backend/build/installer-output/neta-setup.exe

当前安装器默认行为

安装目录

默认安装到：

C:\Program Files\Neta

当前默认配置文件

安装器会把：

installer/config.default.yaml

复制为安装目录下的：

config.yaml

当前数据目录

当前默认写死为：

C:\NetaData

运行数据（日志、lock、runtime-info、skills）都写到这里。

内置 Skill 目录

安装器会把：

packages/backend/skills

打进安装目录下的：

{app}\skills

并在首次启动时把缺失的内置 skill 同步到：

C:\NetaData\skills

本地开发（npm run dev）仍直接读取仓库内的：

packages/backend/skills

桌面快捷方式

安装器会创建桌面快捷方式和开始菜单快捷方式，启动 tray.exe，由托盘控制层负责附着或拉起 backend.exe。

当前已知缺口 / 发布前建议补齐项

以下问题目前都已经记录，其中部分属于发布阻塞项。

1. 数据库账号密码仍然是明文配置（发布阻塞）

当前 installer/config.default.yaml 里包含数据库连接信息，安装后会以明文形式写到安装目录下的 config.yaml。

当前风险：

• 用户机器上可直接看到数据库账号密码
• 安装目录中的配置文件容易被误拷贝、误传播
• 不适合正式对外发布

建议后续方案：

• 安装器安装时让用户输入数据库连接信息
• 或首次启动时通过配置向导填写
• 或改为读取更安全的部署侧配置（如企业内部分发配置）
• 至少不要把正式生产数据库凭证直接内置到默认配置模板中

2. 当前没有自动更新机制

当前安装器只支持重新打包、重新安装，不支持：

• 在线检查更新
• 增量更新
• 回滚
• 版本迁移提示

建议后续补齐：

• 版本检查
• 升级包下载
• 升级失败回滚
• 配置/数据迁移策略

3. Windows 托盘模式

当前安装器已切换为 tray.exe 作为用户入口：

• 桌面快捷方式与开始菜单快捷方式指向 tray.exe
• 托盘菜单提供“打开系统 / 重启服务 / 停止服务 / 打开日志目录 / 打开配置目录 / 退出程序”
• 托盘优先通过 runtime-info.json + 本机 status/stop 控制面附着已运行后端
• “打开系统”始终使用 runtime 状态接口返回的真实 URL，因此当 8003 被占用、后端回退到 8004/8005 等端口时，托盘会打开实际运行端口
• 停止服务 / 退出程序 / 卸载都会先尝试优雅停机，再按安装目录路径兜底清理残留 backend.exe

4. 当前关闭路径

当前停机 / 卸载路径为：

停止服务 / 退出程序
  └─ 优先调用 /app/base/runtime/stop
     └─ 等待 backend 退出
        └─ 若仍存活，则按安装目录路径强杀所有 backend.exe

卸载
  └─ tray.exe --shutdown
     └─ taskkill /IM tray.exe /F
     └─ taskkill /IM backend.exe /F

也就是说：

• 优先走托盘触发的本机优雅停机
• 如果 runtime-info.json 丢失、stop 接口失败、或 pkg stub / wrapper 残留，仍会按安装目录路径兜底清理 backend 进程
• “退出程序”不只是退出托盘，也会先结束后台服务

5. 安装器还没有“数据目录选择页”

设计文档中原本计划支持用户选择数据目录，但当前实现仍然使用默认值：

C:\NetaData

也就是说：

• 目前用户可以选程序安装目录
• 但不能在安装器 UI 中选择数据目录
• config.yaml 中的数据目录还没有在安装时动态写入

这也是当前版本与设计目标之间的重要差距之一。

6. 缺少首次启动配置向导 / 数据库连通性检测

当前安装后直接启动，如果配置不对，只能从日志或错误提示中排查。

建议后续补齐：

• 首次启动向导
• 数据库连接测试
• 数据目录可写性测试
• 端口占用检查提示

7. 升级迁移策略还不完整

当前虽然已经做到“程序目录 / 数据目录分离”，但还缺少：

• config.yaml schema 版本迁移
• 数据目录结构升级迁移
• 不同版本安装器对旧配置的兼容检查

8. 当前更偏向“内测版安装器”，还不适合作为正式商用发布版

当前版本已经可用于：

• 内部验证
• 本地演示
• 离线安装链路测试

但如果要进入正式对外发布，还建议至少补齐：

• 配置安全
• 托盘/服务控制
• 数据目录选择
• 升级更新
• 更友好的故障提示和日志查看入口

推荐的下一阶段改造优先级

建议按下面顺序推进：

1. 去掉明文数据库凭证
2. 实现安装器数据目录选择 + 写回 config.yaml
3. 增加 Windows 托盘控制入口 ✅ 已完成
4. 实现优雅停止服务 ✅ 已完成
5. 补自动更新机制

验证命令

重新打包后，可用以下命令验证：

cd packages/backend
npm run build:windows-installer

验证产物：

ls -lh build/pkg-output/backend.exe
ls -lh build/tray-output/Neta.Tray.exe
ls -lh build/installer-output/neta-setup.exe

Windows 托盘模式验证

验证点：

• tray.exe 能读取 config.yaml 与 runtime-info.json
• 托盘能附着或拉起 backend.exe
• “打开系统”使用 runtime 状态接口返回的真实 URL（包括 8003 被占用时的回退端口）
• 内置 skill 会从安装目录 skills/ 同步到数据目录 skills/
• Skill 管理页能读到内置 skill，Tool 管理页能读到工具 catalog
• “停止服务”能让 backend 退出；再次“打开系统”后托盘状态会恢复为“运行中”
• “退出程序”会先结束 backend，再退出 tray
• 卸载时优先调用 tray.exe --shutdown
• 若优雅停机失败，仍会兜底清理安装目录对应的 backend.exe

如果只验证 exe：

cp installer/config.default.yaml build/pkg-output/config.yaml
build/pkg-output/backend.exe

备注

当前 README 记录的是 截至本次 Windows 安装器实现后的真实状态，不是目标态说明。后续若补齐托盘、自动更新、安装器数据目录选择等能力，需要同步更新本文件。