AionUi 开发环境搭建指南:AionCore 后端、bun 工作流与多实例调试实战
AionUi 开发环境搭建指南:AionCore 后端、bun 工作流与多实例调试实战
导读:本文是 AionUi(一个将 Gemini CLI、Claude Code、Codex 等命令行 AI Agent 包装为现代聊天界面的开源桌面应用)的开发入门手册,完整梳理了从零搭建本地开发环境、编译 Rust 后端、启动 Electron 桌面端,到多实例并行开发、prek 代码检查与 electron-vite 构建系统的全流程。读完本文,你将掌握 AionUi 的仓库布局与双仓库协作模式,能独立完成本地环境搭建、后端热更新迭代,并能熟练使用
bun run全家桶命令进行开发、构建、测试与调试。
本文以 docs/contributing/development.md 为骨架,并结合仓库源码(如 package.json、packages/desktop/electron.vite.config.ts、packages/web-host/src/backend-launcher.ts、.pre-commit-config.yaml)逐层深入,为你呈现一份"能直接照做"的开发指南。
环境要求(Prerequisites)
AionUi 的开发环境涉及 Node.js 运行时、bun 包管理器、Rust 工具链和 Python 四类基础组件:
| 组件 | 版本要求 | 用途 |
|---|---|---|
| Node.js | 22 或更高(根 package.json 的 engines 字段限定为 >=22 <25) |
运行 Vite、electron-vite、tsx 等构建工具 |
| bun | 最新稳定版 | 包管理器与脚本运行时(所有 bun run 命令的载体) |
| Rust stable + Cargo | 最新 stable | 编译本地 AionCore 后端二进制(aioncore) |
| Python | 3.11+ | 原生模块(native module)编译 |
| prek | 全局安装 @j178/prek |
PR 代码检查(pre-commit 的 Rust 实现) |
Windows 用户需要特别注意:请安装 Rust MSVC 工具链。如果 Rust 编译因缺少原生构建工具失败,需通过 Visual Studio Installer 安装 Microsoft C++ Build Tools,然后重新打开终端再试。这是 AionCore 编译过程中最常见的 Windows 环境问题。
仓库布局:双仓库协作模式
AionUi 的开发依赖两个仓库的协同工作:
- AionCore:构建本地后端二进制(macOS/Linux 上为
aioncore,Windows 上为aioncore.exe),负责 SQLite 数据库、Agent 进程托管、HTTP API 等后端能力; - AionUi:启动 Electron 桌面应用,并在启动时自动拉起后端二进制。
官方建议将两个仓库并排放置在同一个工作目录下:
workspace/
|-- AionCore/
`-- AionUi/
从源码看,桌面开发服务器通过 bun run start 继承的 PATH 来解析后端二进制(见 packages/web-host/src/backend-launcher.ts 的 resolveBackend 与 BackendBinaryResolver 类型,以及 scripts/webui.ts 中 resolveBackendBinary() 对 which/where 的调用)。因此必须先安装 AionCore,并在同一个终端里确认二进制可见,再启动 AionUi,否则会出现下文所述的 Cannot find "aioncore" binary 错误。
快速开始(Quick Start)
第 1 步:克隆两个仓库
git clone https://github.com/iOfficeAI/AionCore.git
git clone https://github.com/iOfficeAI/AionUi.git
两个仓库均使用 main 分支开发,除非维护者要求你测试其他分支。
第 2 步:构建并安装 AionCore
在 AionCore 仓库目录下执行:
macOS / Linux
cd AionCore
cargo clean
cargo install --path crates/aionui-app --locked
# 让 Cargo 安装的二进制对当前 shell 可见(如需)
export PATH="$HOME/.cargo/bin:$PATH"
# 验证 AionUi 能找到后端
which aioncore
aioncore --help
如果 which aioncore 无输出,将 export PATH="$HOME/.cargo/bin:$PATH" 写入你的 shell 配置文件(~/.zshrc、~/.bashrc 或对应 shell 的等价文件),打开新终端后再次验证。
Windows PowerShell
cd AionCore
cargo clean
cargo install --path crates/aionui-app --locked
# 让 Cargo 安装的二进制对当前 PowerShell 会话可见(如需)
$env:Path = "$env:USERPROFILE\.cargo\bin;$env:Path"
# 验证 AionUi 能找到后端
where.exe aioncore
aioncore --help
如果 where.exe aioncore 无输出,请确保 %USERPROFILE%\.cargo\bin 已加入用户 Path 环境变量,然后打开新的 PowerShell 窗口再次验证。
关于
--locked参数:cargo install --path ... --locked强制使用Cargo.lock中锁定的依赖版本,保证构建可复现。注意--locked只锁依赖,不会覆盖已安装的同版本二进制——这正是"更新后端"一节必须加--force的原因。
第 3 步:启动 AionUi
在 aioncore 可被发现的同一个终端里,进入 AionUi 仓库执行:
cd AionUi
# 安装依赖
bun install
# 以开发模式启动 Electron 桌面应用
bun run start
启动过程中,AionUi 会自动拉起 aioncore 并把后端端口传递给渲染进程——无需另开终端手动启动 AionCore。
从源码看,bun run start 实际执行的是 electron-vite dev --config packages/desktop/electron.vite.config.ts(见 package.json 的 scripts.start)。而后端拉起逻辑的核心在 packages/web-host/src/backend-launcher.ts 的 BackendLifecycleManager:
- 端口协商:
findAvailablePort()会避开浏览器 fetch 协议禁用的端口(代码中的FETCH_FORBIDDEN_PORTS集合,含 1、7、9、22、25、53 等),最多尝试 50 次,确保后端端口可被fetch正常访问; - 启动参数:
buildSpawnArgs()会拼装--port、--data-dir、--parent-pid、--log-level(开发模式默认debug)、--app-version、--local等参数传给aioncore; - 就绪检测:后端通过 stdout 输出
AIONCORE_LISTENING <json>(携带端口号)与AIONCORE_READY就绪标记,同时启动器还会以 200ms 间隔轮询http://127.0.0.1:<port>/health,两者谁先到达谁胜出; - 崩溃重启:运行期崩溃时,
handleCrash会在 60 秒窗口内最多重启 3 次(maxRestarts = 3、restartWindowMs = 60_000)。
这些实现细节解释了为什么"必须先装好 AionCore 再启动 AionUi"——启动器在 resolve_binary 阶段失败会直接抛出 BackendStartupError。
更新本地后端
当你 pull 或修改了 AionCore 后,需要重装后端二进制并重启 AionUi:
cd ../AionCore
cargo install --path crates/aionui-app --locked --force
cd ../AionUi
bun run start
使用 --force 是为了在 AionCore 包版本不变时强制覆盖已安装的二进制;否则 Cargo 可能保留旧二进制,导致你看到的仍是旧行为。
开发期所有权提醒:Electron 应用在开发期间"拥有"后端子进程。正在运行的 AionUi 不会自动加载新安装的二进制,必须退出后重启才生效(详见下文"后端变更不生效"一节)。
后端启动故障排查
报错 Cannot find "aioncore" binary
AionUi 无法从 bun run start 继承的 PATH 中找到后端。请在启动 AionUi 的同一个终端里执行:
# macOS / Linux
which aioncore
# Windows PowerShell
where.exe aioncore
命令失败则把 Cargo 的 bin 目录加入 PATH,并从新终端启动 AionUi。
从源码看,WebUI 路径(scripts/webui.ts 的 resolveBackendBinary())的查找顺序是:AIONUI_BACKEND_BIN 环境变量 → resources/bundled-aioncore/<platform-arch>/ 目录下的预捆绑二进制 → which/where 的 PATH 查找,全部失败才会抛出 Cannot find "aioncore" binary 错误。桌面端 packages/desktop/src/index.ts 与 packages/web-host/src/backend-launcher.ts 的解析逻辑同理,但可通过设置 AIONUI_BACKEND_BIN 显式指定二进制绝对路径。
终端里 aioncore 可用,但 AionUi 仍找不到
请确认 bun run start 是在能执行 aioncore --help 的同一个终端环境里启动的。IDE 内置终端和 GUI 启动的 shell 可能继承了不同的 PATH;更新 PATH 后请重启 IDE,或从终端启动 IDE。
后端变更不生效
退出 AionUi,用 cargo install --path crates/aionui-app --locked --force 重装 AionCore,再重新启动 AionUi。原因如前所述:开发期间 Electron 应用持有后端子进程,运行中的实例不会拾取新二进制。
Windows Rust 构建错误
使用 Rust MSVC 工具链并安装 Microsoft C++ Build Tools。安装或切换工具链后,打开新的 PowerShell 窗口并重新执行 AionCore 的安装命令——新窗口才能正确加载更新后的环境变量与工具链路径。
脚本参考(Scripts Reference)
AionUi 的所有开发、构建、测试命令都集中在根 package.json 的 scripts 字段。以下按类别整理(与官方文档一致,并补充了实际执行的底层命令)。
开发(Development)
| 命令 | 说明 | 底层实现(package.json) |
|---|---|---|
bun start |
开发模式启动 Electron 应用 | electron-vite dev --config packages/desktop/electron.vite.config.ts |
bun run start:multi |
在已有实例旁启动第二个 Electron 实例(见"多实例开发") | cross-env AIONUI_MULTI_INSTANCE=1 electron-vite dev ... |
bun run cli |
bun start 的别名 |
同上 |
bun run webui |
以 WebUI 模式启动(浏览器访问,无 Electron 窗口) | tsx scripts/webui.ts |
bun run webui:remote |
以 WebUI 模式启动并开启远程访问 | tsx scripts/webui.ts --remote |
bun run webui:prod |
以生产模式启动 WebUI | cross-env NODE_ENV=production tsx scripts/webui.ts |
bun run webui:prod:remote |
生产模式 + 远程访问 | 同上加 --remote |
bun run resetpass |
通过 CLI 重置用户密码 | tsx scripts/resetpass.ts |
bun run webui 系列在 scripts/webui.ts 中实现了完整的独立运行逻辑:默认端口开发 25809 / 生产 25808 / 多实例 25810(与 packages/desktop/src/common/config/constants.ts 的 WEBUI_DEFAULT_PORT 一致);数据目录默认 ~/.aionui-web[-dev][-2];首次启动时自动构建渲染层(可用 --no-build 跳过);若 SQLite 尚无管理员,会自动生成初始密码并打印在终端。支持的环境变量包括 AIONUI_PORT、AIONUI_HOST、AIONUI_ALLOW_REMOTE、AIONUI_DATA_DIR、AIONUI_STATIC_DIR、AIONUI_BACKEND_BIN 等。
构建与分发(Build & Distribution)
| 命令 | 说明 |
|---|---|
bun run package |
构建全部进程(main、preload、renderer)到 out/ |
bun run make |
bun run package 的别名 |
bun run dist |
为当前平台构建并打包可分发的安装包 |
bun run dist:mac / dist:win / dist:linux |
分别为 macOS / Windows / Linux 构建 |
bun run build-mac |
同时构建 macOS arm64 与 x64 安装包 |
bun run build-mac:arm64 / build-mac:x64 |
仅构建 Apple Silicon / Intel 版 |
bun run build-win |
构建 Windows 安装包 |
bun run build-win:arm64 / build-win:x64 |
构建 Windows ARM64 / x64 版 |
bun run build-deb |
构建 Linux(.deb)安装包 |
bun run build |
bun run build-mac 的别名 |
分发构建统一由 node scripts/build-with-builder.js 驱动(基于 electron-builder),并可通过 ELECTRON_BUILDER_COMPRESSION_LEVEL、--config.win.signAndEditExecutable 等环境变量/参数调整打包行为。
独立服务器(Standalone Server,非 Electron)
| 命令 | 说明 |
|---|---|
bun run build:renderer:web |
为独立 Web 部署构建渲染层 |
bun run build:server |
构建独立服务器 bundle 到 dist-server/ |
bun run server:start |
开发模式运行独立服务器 |
bun run server:start:remote |
运行独立服务器并开启远程访问 |
bun run server:start:prod |
生产模式运行独立服务器 |
bun run server:start:prod:remote |
生产模式 + 远程访问 |
bun run server:resetpass / server:resetpass:prod |
通过独立服务器 CLI 重置密码 |
代码质量(Code Quality)
| 命令 | 说明 |
|---|---|
bun run lint |
检查 lint 问题(oxlint,只读) |
bun run lint:fix |
自动修复 lint 问题 |
bun run format |
自动格式化代码(oxfmt) |
bun run format:check |
只检查格式、不修改文件 |
bun run i18n:types |
为 i18n key 生成 TypeScript 类型 |
测试(Testing)
| 命令 | 说明 |
|---|---|
bun run test |
运行全部单元测试(vitest) |
bun run test:watch |
监听模式运行测试 |
bun run test:coverage |
运行测试并生成覆盖率报告 |
bun run test:contract |
运行契约测试 |
bun run test:integration |
运行集成测试 |
bun run test:bun |
运行 Bun 专用数据库驱动测试 |
bun run test:e2e |
运行端到端测试(Playwright,配置见 playwright.config.ts) |
bun run test:packaged:i18n |
对打包构建运行 i18n 集成测试 |
bun run test:packaged:bun |
运行 Bun 打包集成测试 |
调试(Debug)
| 命令 | 说明 |
|---|---|
bun run debug:perf |
开启性能监控启动应用 |
bun run debug:perf:report |
生成性能报告 |
bun run debug:mcp |
调试 MCP 服务器连接 |
bun run debug:mcp:list |
列出已配置的 MCP 服务器 |
bun run debug:mcp:validate |
校验 MCP 服务器配置 |
bun run debug:custom-agent |
调试自定义 Agent 连接 |
多实例开发(Multi-Instance Development)
当你同时持有两个仓库克隆(例如 AionUi 和 AionUi-refactor)并需要并行运行时,第二个实例用以下命令启动:
bun run start:multi
该命令设置 AIONUI_MULTI_INSTANCE=1(实际执行 cross-env AIONUI_MULTI_INSTANCE=1 electron-vite dev ...),其效果如下:
- 跳过 Electron 单实例锁:见 packages/desktop/src/index.ts 第 87 行,
skipSingleInstanceLock = isE2ETestMode || process.env.AIONUI_MULTI_INSTANCE === '1',第二个实例不会因单实例锁直接退出; - 使用独立 userData 目录(
AionUi-Dev-2):避免数据库与配置冲突; - 隔离数据/配置符号链接路径(
~/.aionui-dev-2、~/.aionui-config-dev-2):见 packages/desktop/src/common/config/appEnv.ts 的getEnvAwareName(),它在开发模式下根据AIONUI_MULTI_INSTANCE追加-dev或-dev-2后缀,确保两个实例的目录名互不重叠; - Vite 渲染层、CDP、WebUI 代理端口自动递增避免冲突:其中 WebUI 端口由 packages/desktop/src/common/config/constants.ts 的
WEBUI_DEFAULT_PORT控制——多实例开发时从 25809 变为 25810(Vite dev server 端口则默认 5173,被占用时自动递增,见 packages/desktop/electron.vite.config.ts)。
注意:多实例 WebUI 默认端口为 25810(而非 25809)。在浏览器访问第二个实例的 WebUI 时,请使用无痕/隐私窗口——两个实例共享
localhost的 cookie 存储,而它们的 JWT 密钥不同,复用同一浏览器会话会导致鉴权失败。
代码检查(prek)
项目使用 prek(pre-commit 的 Rust 实现)进行代码检查,配置位于根目录 .pre-commit-config.yaml:
# 安装 prek
npm install -g @j178/prek
# 安装 git hooks(可选,提交前自动检查)
prek install
# 对暂存文件运行检查
prek run
# 对相对 main 的变更运行检查(与 CI 相同)
prek run --from-ref origin/main --to-ref HEAD
从 .pre-commit-config.yaml 看,本仓库的检查链包含:
| Hook | 检查内容 |
|---|---|
check-yaml / check-json / check-toml |
配置文件语法校验 |
check-merge-conflict / check-case-conflict |
冲突标记与大小写冲突检测 |
check-added-large-files |
大文件限制(--maxkb=1000) |
end-of-file-fixer / trailing-whitespace |
文件结尾与行尾空白修复 |
typecheck |
全项目 TypeScript 类型检查(bunx tsc --noEmit) |
oxlint |
lint 检查(替代 ESLint) |
oxfmt |
代码格式化(替代 Prettier) |
i18n-check |
i18n 翻译文件校验(node scripts/check-i18n.js) |
conventional-pre-commit |
提交信息必须符合 Conventional Commits(feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert,且强制 scope) |
这样保证本地检查与 CI 检查完全一致,prek run --from-ref origin/main --to-ref HEAD 即为 CI PR 检查的等价命令。
构建系统:electron-vite 与 out/ 目录
AionUi 使用 electron-vite 完成快速打包:
- 主进程(Main process):Vite 打包(ESM)
- 渲染进程(Renderer process):Vite 打包(React + TypeScript)
- 预加载脚本(Preload scripts):Vite 打包
构建产物输出到 out/ 目录:
out/
├── main/ # 主进程代码
├── renderer/ # 渲染进程代码
└── preload/ # 预加载脚本
从 packages/desktop/electron.vite.config.ts 可以读到大量构建细节:
- 入口:主进程入口为
packages/desktop/src/index.ts;preload 除主入口外还打包了宠物窗口(pet)相关的多个预加载脚本;渲染层是 MPA(多页面应用),入口包括index.html、pet/pet.html、pet-hit.html、pet-confirm.html; - 别名体系:
@(packages/desktop/src)、@common、@renderer、@process、@worker等,贯穿主进程与渲染层; - 资源复制:生产构建时通过
viteStaticCopy将 logo 资源复制到static/images; - 代码分割:通过
manualChunks将 React 及强耦合的 UI 生态(Arco、react-markdown、CodeMirror、Monaco、KaTeX、WaveDrom 等)聚合进单一vendorchunk,以规避 ESM chunk 循环导致的React.createContext未初始化白屏问题; - 版本注入:
__APP_VERSION__从根 package.json 读取真实版本注入渲染层,避免使用工作区内packages/desktop/package.json中占位的0.0.0; - Sentry Source Map:非开发环境且设置了
SENTRY_AUTH_TOKEN时自动上传 source map。
技术栈(Tech Stack)
| 技术 | 用途 |
|---|---|
| Electron | 跨平台桌面框架(v37+,见 package.json devDependencies) |
| React 19 | UI 框架 |
| TypeScript | 类型安全 |
| Vite | 快速打包器(经 electron-vite 集成) |
| UnoCSS | 原子化 CSS 引擎 |
| better-sqlite3 | 本地数据库 |
| vitest | 测试框架(另有 Playwright 用于 E2E) |
此外从 package.json 的依赖可以看出:项目集成了 Arco Design 组件库(@arco-design/web-react)、MCP SDK(@modelcontextprotocol/sdk)、多平台 Agent SDK(@anthropic-ai/sdk、openai、@google/genai 等)、Markdown/文档渲染(react-markdown、mermaid、katex、docx、mammoth、officeparser 等)以及多渠道接入(grammy、@larksuiteoapi/node-sdk、@wecom/aibot-node-sdk、dingtalk-stream),是一个典型的"桌面壳 + 本地后端 + 丰富前端生态"的架构。
延伸阅读
- 目录结构与命名规范:docs/contributing/file-structure.md
- 后端启动器源码:packages/web-host/src/backend-launcher.ts
- 独立 WebUI 启动脚本:scripts/webui.ts
- 构建配置:packages/desktop/electron.vite.config.ts
- 脚本全集与依赖清单:package.json
- E2E 测试配置:playwright.config.ts