---
title: Windows Runtime 与安装器
created: 2026-04-26
updated: 2026-04-26
type: concept
tags: [deploy, backend, config]
sources: [packages/backend/src/comm/, packages/backend/src/modules/base/controller/app/runtime.ts, packages/backend/scripts/pkg-build.js, packages/backend/scripts/build-windows-installer.js, packages/backend/installer/setup.iss, packages/windows-tray/]
---

# Windows Runtime 与安装器

Windows runtime 是 2026-04-25 后新增的本地部署子系统，目标是把后端打包成 `backend.exe`，再配合 .NET 托盘程序和 Inno Setup 安装器运行。它和 [[project-overview]] 的开发态不同，重点处理配置文件、数据目录、运行时状态、进程生命周期和本机控制接口。

## 组件

| 组件 | 路径 | 职责 |
|------|------|------|
| 后端可执行文件 | `packages/backend/scripts/pkg-build.js` | 使用 pkg/yao-pkg 打包后端 |
| 安装器构建 | `packages/backend/scripts/build-windows-installer.js` | 构建 backend.exe、发布托盘 exe、调用 Inno Setup |
| 安装器脚本 | `packages/backend/installer/setup.iss` | 生成 Windows 安装包 |
| 托盘程序 | `packages/windows-tray/Neta.Tray/` | 启动/附着/停止后端，打开系统、日志、配置目录 |
| 运行时控制 API | `modules/base/controller/app/runtime.ts` | `/app/base/runtime/status` 与 `/stop` |
| 配置加载 | `comm/config-loader.ts` | pkg 模式读取 `config.yaml` |
| 数据目录 | `comm/data-dir.ts` | 统一可写路径 |
| runtime info | `comm/runtime-info.ts` | 写入 pid、端口、URL、控制密钥、目录信息 |

## 配置与数据目录

pkg 模式下，后端要求 `config.yaml` 与 `backend.exe` 同目录。配置必须包含：

- `server.port`
- `data.dir`
- `database.host/username/database`
- `autoOpenBrowser`

数据目录解析顺序：

1. 外部配置的 `data.dir`
2. 环境变量 `NETA_DATA_DIR`
3. pkg 模式下的 `<exe-dir>/data`
4. 开发态下的 `<cwd>/dist`

这条规则影响 SQLite 记忆、Session Tree file provider、skill 目录、日志、runtime info 等所有可写路径，避免安装目录和源码目录混用。

## 托盘控制

托盘程序会读取安装目录中的 runtime 信息，如果后端已就绪就附着；否则启动 `backend.exe` 并等待 runtime info 可用。菜单能力包括：

- 打开系统：使用后端返回的本机 URL。
- 重启服务：先走 `/stop`，再重新启动后端。
- 停止服务：先尝试控制 API，超时后按 pid 和安装目录内 backend 进程强制结束。
- 打开日志目录 / 配置目录。
- 退出程序：停止后端并退出托盘。

控制 API 只允许 loopback 地址，并通过 `x-neta-tray-secret` 校验 `NETA_TRAY_SECRET`，避免远程请求停止本机服务。

## 构建与部署边界

- `config.prod.ts` 从外部配置读取数据库和端口，并保持 EPS 在后端生产配置里关闭。
- 前端生产配置使用 same-origin API base URL，安装器场景下避免协议相对 URL 和双斜杠。
- SPA history fallback 在后端静态文件服务中兜底，支持刷新前端路由。
- bundled skills 会进入安装包，运行时按需初始化 skill 目录和 tool catalog。

## 相关页面

- [[project-overview]] — Monorepo 和部署入口
- [[skill-system]] — bundled skills 与运行时 skill 目录
- [[memory-system]] — SQLite 记忆路径受 dataDir 影响
- [[session-tree-runtime]] — file provider 的 rootDir 受 dataDir 影响
- [[base-module]] — runtime 控制接口挂在 base 模块下
