mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-17 09:50:31 +08:00
a7e580407c
* feat: add desktop wrapper with frontend-only packaging * docs: add desktop build docs and track dashboard lockfile * fix: track desktop lockfile for npm ci * fix: allow custom install directory for windows installer * chore: migrate desktop workflow to pnpm * fix(desktop): build AppImage only on Linux * fix(desktop): harden packaged startup and backend bundling * fix(desktop): adapt packaged restart and plugin dependency flow * fix(desktop): prevent backend respawn race on quit * fix(desktop): prefer pyproject version for desktop packaging * fix(desktop): improve startup loading UX and reduce flicker * ci: add desktop multi-platform release workflow * ci: fix desktop release build and mac runner labels * ci: disable electron-builder auto publish in desktop build * ci: avoid electron-builder publish path in build matrix * ci: normalize desktop release artifact names * ci: exclude blockmap files from desktop release assets * ci: prefix desktop release assets with AstrBot and purge blockmaps * feat: add electron bridge types and expose backend control methods in preload script * Update startup screen assets and styles - Changed the icon from PNG to SVG format for better scalability. - Updated the border color from #d0d0d0 to #eeeeee for a softer appearance. - Adjusted the width of the startup screen from 460px to 360px for improved responsiveness. * Update .gitignore to include package.json * chore: remove desktop gitkeep ignore exceptions * docs: update desktop troubleshooting for current runtime behavior * refactor(desktop): modularize runtime and harden startup flow --------- Co-authored-by: Soulter <905617992@qq.com> Co-authored-by: Soulter <37870767+Soulter@users.noreply.github.com>
123 lines
3.7 KiB
Markdown
123 lines
3.7 KiB
Markdown
# AstrBot Desktop (Electron)
|
|
|
|
This document describes how to build the Electron desktop app from source.
|
|
|
|
## What This Package Contains
|
|
|
|
- Electron desktop shell (`desktop/main.js`)
|
|
- Bundled WebUI static files (`desktop/resources/webui`)
|
|
- App assets (`desktop/assets`)
|
|
|
|
Current behavior:
|
|
|
|
- Backend executable is bundled in the installer/package.
|
|
- App startup checks backend availability and auto-starts bundled backend when needed.
|
|
- Runtime data is stored under `~/.astrbot` by default, not as a full AstrBot source project.
|
|
|
|
## Prerequisites
|
|
|
|
- Python environment ready in repository root (`uv` available)
|
|
- Node.js available
|
|
- `pnpm` available
|
|
|
|
Desktop dependency management uses `pnpm` with a lockfile:
|
|
|
|
- `desktop/pnpm-lock.yaml`
|
|
- `pnpm --dir desktop install --frozen-lockfile`
|
|
|
|
## Build From Scratch
|
|
|
|
Run commands from repository root:
|
|
|
|
```bash
|
|
uv sync
|
|
pnpm --dir dashboard install
|
|
pnpm --dir dashboard build
|
|
pnpm --dir desktop install --frozen-lockfile
|
|
pnpm --dir desktop run dist:full
|
|
```
|
|
|
|
Output files are generated under:
|
|
|
|
- `desktop/dist/`
|
|
|
|
## Local Run (Development)
|
|
|
|
Start backend first:
|
|
|
|
```bash
|
|
uv run main.py
|
|
```
|
|
|
|
Start Electron shell:
|
|
|
|
```bash
|
|
pnpm --dir desktop run dev
|
|
```
|
|
|
|
## Notes
|
|
|
|
- `dist:full` runs WebUI build + backend build + Electron packaging.
|
|
- In packaged app mode, backend data root defaults to `~/.astrbot` (can be overridden by `ASTRBOT_ROOT`).
|
|
- Backend build uses `uv run --with pyinstaller ...`, so no manual `PyInstaller` install is required.
|
|
|
|
## Runtime Directory Layout
|
|
|
|
By default (`ASTRBOT_ROOT` not set), packaged desktop app uses this layout:
|
|
|
|
```text
|
|
~/.astrbot/
|
|
data/
|
|
config/ # Main configuration
|
|
plugins/ # Installed plugins
|
|
plugin_data/ # Plugin persistent data
|
|
site-packages/ # Plugin dependency installation target in packaged mode
|
|
temp/ # Runtime temp files
|
|
skills/ # Skill-related runtime data
|
|
knowledge_base/ # Knowledge base files
|
|
backups/ # Backup data
|
|
```
|
|
|
|
The app does not store a full AstrBot source tree in home directory.
|
|
|
|
## Troubleshooting
|
|
|
|
Startup behavior:
|
|
|
|
- Packaged app shows a local startup page first, then switches to dashboard after backend is reachable.
|
|
- If startup page never switches, check logs and timeout settings below.
|
|
|
|
Runtime logs:
|
|
|
|
- Electron shell log: `~/.astrbot/logs/electron.log`
|
|
- Backend stdout/stderr log: `~/.astrbot/logs/backend.log`
|
|
- On backend startup failure, the app dialog also shows the backend reason and backend log path.
|
|
|
|
Timeout and loading controls:
|
|
|
|
- `ASTRBOT_BACKEND_TIMEOUT_MS` controls how long Electron waits for backend reachability.
|
|
- In packaged mode, default is `0` (auto mode with a 5-minute safety cap).
|
|
- In development mode, default is `20000`.
|
|
- If backend startup times out, app shows startup failure dialog and exits.
|
|
- `ASTRBOT_DASHBOARD_TIMEOUT_MS` controls dashboard page load wait time after backend is ready (default `20000`).
|
|
- If you see `Unable to load the AstrBot dashboard.`, increase `ASTRBOT_DASHBOARD_TIMEOUT_MS`.
|
|
|
|
Startup page locale:
|
|
|
|
- Startup page language follows cached dashboard locale in `~/.astrbot/data/desktop_state.json`.
|
|
- Supported startup locales are `zh-CN` and `en-US`.
|
|
- Remove that file to reset locale fallback behavior.
|
|
|
|
Backend auto-start:
|
|
|
|
- `ASTRBOT_BACKEND_AUTO_START=0` disables Electron-managed backend startup.
|
|
- When disabled, backend must already be running at `ASTRBOT_BACKEND_URL` before launching app.
|
|
|
|
If Electron download times out on restricted networks, configure mirrors before install:
|
|
|
|
```bash
|
|
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
|
|
export ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
|
|
pnpm --dir desktop install --frozen-lockfile
|
|
```
|