安装说明

详细的安装步骤和环境配置指南。

重要

软件升级后不支持降级，如果需要，请自行备份以下文件

1. 数据库文件 用户目录/.starbox/db/starbox.sqlite，
2. 数据存储文件夹

文件说明：

数据库文件：存储除音频外的所有数据

数据存储文件夹：存放生成的音频文件，可以在软件->设置->存储->数据存储路径查看， 也可以在 用户目录/.starbox/config.yaml 中 DATA_BASE_DIR 查看

📦 安装包说明

StarBox 提供两种版本：Electron 桌面客户端 和 Embedded 完整版。

Electron 桌面客户端

完整的桌面应用程序，包含前端界面和后端服务，提供最佳的用户体验。

操作系统	文件名	说明	推荐用户
Windows	starbox-client-{version}-setup.exe	Windows 安装程序	Windows 10/11 用户
macOS	starbox-client-{version}.dmg	macOS 磁盘镜像	macOS 10.15+ 用户
Linux	starbox-client-{version}.AppImage	AppImage 格式（免安装）	所有 Linux 发行版
Linux	starbox-client-{version}.deb	Debian/Ubuntu 安装包	Debian/Ubuntu 系用户
Linux	starbox-client-{version}.snap	Snap 通用包	支持 Snap 的发行版

Embedded 完整版

独立的可执行文件，内置 Web UI 和后端服务，无需安装，适合服务器部署或便携使用。

操作系统	文件名	说明	推荐用户
Windows	starbox-embedded-windows-{version}.exe	Windows 可执行文件（带控制台）	服务器部署、命令行用户
macOS	starbox-embedded-macos-{version}	macOS 可执行文件	服务器部署、终端用户
Linux	starbox-embedded-linux-{version}	Linux 可执行文件	服务器部署、Docker 容器

🎯 如何选择？

选择 Electron 桌面客户端，如果你：

• ✅ 需要完整的桌面应用体验
• ✅ 希望有系统托盘、窗口管理等桌面功能
• ✅ 在个人电脑上使用
• ✅ 需要自动更新功能

选择 Embedded 完整版，如果你：

• ✅ 需要在服务器上部署
• ✅ 希望通过浏览器访问
• ✅ 需要便携版本（U盘、移动硬盘）
• ✅ 想要更轻量的解决方案
• ✅ 需要在 Docker 容器中运行

📋 系统要求

Windows

• 操作系统: Windows 10 (1809+) / Windows 11
• 架构: x64 (64位)
• 内存: 最低 4GB RAM，推荐 8GB+
• 磁盘空间: 500MB 可用空间
• 依赖: FFmpeg（音频处理）

macOS

• 操作系统: macOS 10.15 (Catalina) 或更高版本
• 架构: Intel (x64) / Apple Silicon (arm64)
• 内存: 最低 4GB RAM，推荐 8GB+
• 磁盘空间: 500MB 可用空间
• 依赖: FFmpeg（音频处理）

Linux

• 发行版: Ubuntu 22.04+, Debian 11+, Fedora 35+, 或其他主流发行版
• 架构: x64 (64位)
• 依赖: glibc 2.31+, FFmpeg（音频处理）
• 内存: 最低 4GB RAM，推荐 8GB+
• 磁盘空间: 500MB 可用空间

提示

所有版本都需要先安装 FFmpeg，请参考 快速开始 中的 FFmpeg 安装说明。

🚀 安装步骤

Windows - Electron 客户端

1. 下载 starbox-client-{version}-setup.exe
2. 双击运行安装程序
3. 按照安装向导完成安装
4. 从开始菜单或桌面快捷方式启动 StarBox

Windows - Embedded 版本

1. 下载 starbox-embedded-windows-{version}.exe
2. 双击运行（会显示控制台窗口）
3. 浏览器访问 http://localhost:23450
4. 关闭控制台窗口即可停止服务

macOS - Electron 客户端

1. 下载 starbox-client-{version}.dmg
2. 双击打开 DMG 文件
3. 将 StarBox 拖动到 Applications 文件夹
4. 从 Applications 文件夹启动 StarBox
5. 首次运行时，右键点击选择"打开"以绕过安全检查

macOS - Embedded 版本

1. 下载 starbox-embedded-macos-{version}
2. 打开终端，赋予执行权限：

   chmod +x starbox-embedded-macos-{version}

3. 运行：

   ./starbox-embedded-macos-{version}

4. 浏览器访问 http://localhost:23450

Linux - Electron 客户端 (AppImage)

1. 下载 starbox-client-{version}.AppImage
2. 赋予执行权限：

   chmod +x starbox-client-{version}.AppImage

3. 双击运行或在终端执行：

   ./starbox-client-{version}.AppImage

Linux - Electron 客户端 (DEB)

1. 下载 starbox-client-{version}.deb
2. 安装：

   sudo dpkg -i starbox-client-{version}.deb
   sudo apt-get install -f  # 安装依赖

3. 从应用菜单启动或命令行运行：

   starbox

Linux - Electron 客户端 (Snap)

1. 下载 starbox-client-{version}.snap
2. 安装：

   sudo snap install starbox-client-{version}.snap --dangerous

   注意

   --dangerous 参数用于安装未经 Snap Store 验证的本地包

3. 从应用菜单启动或命令行运行：

   starbox

4. 卸载：

   sudo snap remove starbox

Linux - Embedded 版本

1. 下载 starbox-embedded-linux-{version}
2. 赋予执行权限：

   chmod +x starbox-embedded-linux-{version}

3. 运行：

   ./starbox-embedded-linux-{version}

4. 浏览器访问 http://localhost:23450

🔧 高级配置

Embedded 版本 - 自定义端口

# Windows
starbox-embedded-windows-{version}.exe --port 8080

# macOS/Linux
./starbox-embedded-macos-{version} --port 8080

Embedded 版本 - 后台运行 (Linux/macOS)

# 使用 nohup
nohup ./starbox-embedded-linux-{version} > starbox.log 2>&1 &

# 使用 screen
screen -dmS starbox ./starbox-embedded-linux-{version}

# 使用 systemd (推荐)
# 创建服务文件 /etc/systemd/system/starbox.service

日志文件位置

Electron 客户端：

• Windows: %APPDATA%\starbox\logs\
• macOS: ~/Library/Logs/starbox/
• Linux: ~/.config/starbox/logs/

Embedded 版本：

• 所有平台: 可执行文件同目录下的 logs/starbox-server.log

❓ 常见问题

遇到安装问题？查看 常见问题页面 获取详细的解决方案。

📚 下一步

• 查看 快速开始 了解如何使用