エイカク
dc995af34b
* fix(desktop): rotate electron and backend logs * refactor(desktop): centralize log rotation defaults and debug fs errors * fix(desktop): harden rotation fs ops and buffer backend log writes * refactor(desktop): extract buffered logger and reduce sync stat calls * refactor(desktop): simplify rotation flow and harden logger config * fix(desktop): make app logging async and flush-safe * fix: harden app log path switching and debug-gated rotation errors * fix: cap buffered log chunk size during path switch
132 lines
4.1 KiB
Markdown
132 lines
4.1 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`
|
|
- Both files rotate by size by default: `20MB` per file, keep `3` backups.
|
|
- Electron log rotation envs:
|
|
- `ASTRBOT_ELECTRON_LOG_MAX_MB`
|
|
- `ASTRBOT_ELECTRON_LOG_BACKUP_COUNT`
|
|
- Backend log rotation envs:
|
|
- `ASTRBOT_BACKEND_LOG_MAX_MB`
|
|
- `ASTRBOT_BACKEND_LOG_BACKUP_COUNT`
|
|
- Rotation debug logging:
|
|
- `ASTRBOT_LOG_ROTATION_DEBUG=1` (or `NODE_ENV=development`) to print filesystem errors from rotation operations.
|
|
- 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
|
|
```
|