Koel 快速上手指南：五种安装方式、环境变量配置与升级/降级实践

音视频后端前端【免费下载链接】koelMusic streaming solution that works.项目地址https://gitcode.com/gh_mirrors/ko/koel点击查看免费下载本篇技术指南完整讲解 Koel 音乐流媒体服务的起步流程从服务器端与客户端的运行要求到独立二进制、预编译归档、源码构建、Docker、Railway 五种安装方式再到.env环境配置含邮件服务的判定逻辑、FrankenPHP 运行方式以及升级与降级的最佳实践。读完本篇你将掌握从零部署一套 Koel 实例、按需切换数据库与存储、并以 systemd 或反向代理方式投入生产的完整能力。Koel 的两段式架构与运行需求Koel 由两部分组成服务端server是一个扮演 API 角色的 Laravel 应用客户端client是一个负责用户界面的 Vue.js 应用。两部分对运行环境的需求各不相同。服务端需求PHP满足 Laravel 的部署要求 中则声明php: 8.3同时要求laravel/framework^13.0因此在较新环境上请以 8.3 及以上为准。此外 composer.json 还声明了ext-exif、ext-gd、ext-fileinfo、ext-json、ext-SimpleXML等 PHP 扩展依赖。数据库任选一种 Laravel 支持的数据库。Koel 已在 MySQL、MariaDB、PostgreSQL 和 SQLite 上完成测试如果你使用的是 SQLiteDB_CONNECTION需设为sqlite-persistent详见下文配置说明。源码构建工具链如果选择从源码构建需要准备 Composer、Git、Node.js 20 以及 pnpmpnpm install会顺带在本地产出构建前端所需的 Vite 工具链。客户端需求Koel 已在 Chrome 47、Firefox 42、Safari 8、Opera 34 和 Edge 上测试通过但始终推荐使用各浏览器的最新版本。安装 Koel 的五种方式Koel 官方提供以下五种安装/启动方式你可以根据自己的运维习惯选择。方式一使用独立二进制Standalone Binarykoel/franken 发布页提供的单归档发行版将 FrankenPHPCaddy PHP 运行时与编译好的 Koel 应用打包在一起。宿主机无需安装 Composer、Node 或系统 PHP默认使用 SQLite做到零配置开箱即用tar -xzf koel-franken-v9.3.2-linux-x86_64.tar.gz cd koel-franken-v9.3.2-linux-x86_64 ./koel php-server --listen :8000首次运行时Koel 会在$HOME/.koel/下完成初始化生成应用密钥app key并创建全新的 SQLite 数据库随后 FrankenPHP 开始在指定端口或域名上提供服务。之后可以执行./artisan koel:storage配置媒体存储并开始使用。关于该方式的完整约定MySQL/PostgreSQL 覆盖、systemd 服务单元等请参阅 独立二进制部署指南。几个关键事实值得一提该发行版在所有可写状态统一放在$HOME/.koel/下.env环境配置、db.sqlite数据库、storage/Laravel 存储日志、会话、缓存、上传图片、storage/app/artifacts/转码文件、下载的播客、临时下载、php.d/koel.iniPHP 配置覆盖如关闭 display_errors、屏蔽 error_reporting、512M 上传限制。发行版自带的./artisan是./koel php-cli artisan …的快捷方式使用同一套 PHP 运行时与环境。升级时只需下载新归档、覆盖解压、重启服务即可$HOME/.koel/中的配置、数据库、图片与搜索索引都会被保留。方式二使用预编译归档Pre-Compiled Archive如果不想手动编译前端资源可以直接使用预编译归档。到 GitHub 的 Releases 页面 下载 Assets 下的.tar.gz或.zip文件解压到目标 Web 根目录然后执行composer koel:init -- --no-assets # 跟随向导填写必要配置 php artisan serve--no-assets跳过前端资源编译因为归档内已内置编译产物。方式三从源码构建Building from Source在控制台依次执行cd KOEL_ROOT_DIR git clone https://github.com/koel/koel.git . git checkout latest # 检出 Releases 页面标记的最新版本 composer koel:init # 跟随向导填写必要配置 php artisan serve从源码安装时koel:init会完整执行composer install由 scripts/koel-init.php 脚本包装→php artisan koel:init→ 安装 npm 依赖并编译前端资源。若想在源码安装下跳过前端编译同样使用composer koel:init -- --no-assets。上述两种方式完成后浏览器访问 http://localhost:8000 即可开始使用 Koel。警告请使用正规 Web 服务器http://localhost:8000 只是 Koel准确说是 Laravel的开发服务器。生产环境请将 Apache、nginx、Caddy 等正规服务器指向 Koel 的public/目录——这与任何标准 PHP 应用的部署流程一致。Koel 在项目根目录附带了开箱即用的配置nginx.conf.examplenginx PHP-FPM和 Caddyfile.example配合 FrankenPHP。方式四使用 DockerKoel 提供官方 Docker 镜像 koel/docker具体指令与问题上报请参照该仓库。方式五使用 Railway社区方案若希望在 Railway 上用 PostgreSQL 部署 Koel可使用社区维护的模板点击文档中的 Deploy on Railway 按钮即可。注意这不是 Koel 官方方案模板问题请反馈给维护者osbytes/template-koel。首次部署后请立即修改默认管理员密码默认账号为adminkoel.dev默认密码KoelIsCool。安装向导koel:init到底做了什么无论预编译归档还是源码构建安装过程都由koel:init命令驱动。阅读 InitCommand.php 的实现可以看到向导按以下顺序执行清理缓存调用config:clear与cache:clear确保.env存在若根目录没有.env从 .env.example 复制一份对应ensureEnvFileExists()生成应用密钥若APP_KEY为空通过DotenvEditor写入随机生成的base64:密钥配置并连接数据库交互模式下让用户选择mysql默认/pgsql/sqlsrv/ SQLite并填写 host、port、database、user、password非交互模式下会重试最多 10 次NON_INTERACTION_MAX_DATABASE_ATTEMPT_COUNT失败则放弃并等待管理员修复迁移数据库执行migrate --force种子数据若用户表为空创建默认管理员账号即上文提到的adminkoel.dev/KoelIsCool并执行db:seed --force链接存储调用storage:link让public/storage指向存储目录否则专辑/艺人图片可能无法加载迁移旧版图片若检测到旧版public/img/storage/目录自动迁移到storage/app/public/images/设置媒体路径交互式询问媒体目录绝对路径可留空稍后在 Web 界面配置或使用 S3/Dropbox 等云端存储编译前端资源除非传了--no-assets否则执行pnpm install与pnpm run build安装调度器调用koel:scheduler:installWindows 或--no-scheduler时跳过。向导完成后若处于生产环境会提示当前实例可访问的 URL如果首次创建了管理员还会输出登录邮箱与初始密码。整套流程让你在交互式问答中完成配置而不必手写.env。配置.env环境变量Koel 的配置存放在项目根目录的.env文件中安装过程中由koel:init复制.env.example并填充合理值生成。你可以随时修改其中的值来适配环境完整的环境变量清单见 环境变量参考。.env.example中几个与起步强相关的关键项变量说明默认值APP_URL应用访问地址http://localhost:8000DB_CONNECTION数据库连接名对应驱动mysql默认、mariadb、pgsql、sqlsrv、sqlite-persistent。该值必须存在composer koel:init才能正常工作mysqlDB_HOST/DB_PORT/DB_DATABASE/DB_USERNAME/DB_PASSWORD数据库连接参数也支持用DATABASE_URL一次性提供连接串如 Heroku 场景127.0.0.1/3306/koel/koel/ 空STORAGE_DRIVER媒体存储驱动local、sftp以及 Koel Plus 的s3、dropbox、webdavlocalMEDIA_PATH媒体目录绝对路径STORAGE_DRIVERlocal时必填也可在 Web 界面修改空ARTIFACTS_PATH转码文件、播客节目、临时下载等产物的存放绝对路径留空则使用系统临时目录空TRUSTED_HOSTS允许访问 Koel 的主机名逗号分隔留空则允许任意主机名空FORCE_HTTPS自动 HTTPS 检测失败时强制使用 HTTPS URLfalseMAIL_MAILER邮件驱动详见下文smtp如果你使用 S3 或 S3 兼容服务如 Cloudflare R2、DigitalOcean Spaces还需设置AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGIONR2 用auto、AWS_ENDPOINT、AWS_BUCKET并记得为媒体域配置 CORS 策略。SFTP、Dropbox、WebDAV 各自有独立的变量组可参考 环境变量参考 中的完整表格。此外.env.example还包含媒体扫描APP_MAX_SCAN_TIME600、IGNORE_DOT_FILEStrue、SCAN_JOBS、流式播放与转码STREAMING_METHODphp、TRANSCODE_FLAC、TRANSCODE_BIT_RATE128、FFMPEG_PATH、下载ALLOW_DOWNLOADtrue、DOWNLOAD_LIMIT0、全文检索SCOUT_DRIVERtntsearch可选database、algolia、meilisearch以及各类服务集成MusicBrainz、Last.fm、Spotify、YouTube、Ticketmaster、ListenBrainz的配置入口。配置邮件服务MailerKoel 本身可以在没有邮件服务的情况下运行但忘记密码、用户邀请等功能依赖邮件。Koel 通过.env中的MAIL_MAILER值来判断是否需要邮件任何非空且不是log或array的值都被视为有效的邮件驱动。因此如果你不需要依赖邮件的功能只需把MAIL_MAILER设为log或array其余邮件相关配置留空即可——Koel 会自动识别并移除/禁用这些功能。.env.example中默认的邮件配置为MAIL_MAILERsmtp并附带了MAIL_HOST、MAIL_PORT、MAIL_FROM_ADDRESS、MAIL_FROM_NAME等标准项。使用 FrankenPHP 运行 KoelFrankenPHP 是一款把 Web 服务器Caddy和 PHP 运行时打包进单个二进制的现代 PHP 应用服务器自带自动化 HTTPS。Koel 在项目根目录提供了 Caddyfile.example 与其配合使用。完整的安装、Caddyfile、artisan 命令、systemd 服务与反向代理模式见 FrankenPHP 运行指南这里摘要其要点安装 FrankenPHP从官方文档获取预编译二进制Linux 下可用curl https://frankenphp.dev/install.sh | sh安装再sudo mv frankenphp /usr/local/bin/配置 Caddyfilecp Caddyfile.example Caddyfile把localhost替换成你要服务的域名使用真实公网域名会自动开启 Lets Encrypt 的 HTTPS运行frankenphp run之后 Koel 就运行在 443 端口80 端口自动 301 跳转到 HTTPS运行 artisan 命令FrankenPHP 自带 PHP任何php artisan …都要改写成frankenphp php-cli artisan command例如frankenphp php-cli artisan migrate执行迁移、frankenphp php-cli artisan koel:sync触发媒体扫描可设置别名alias artisanfrankenphp php-cli artisan方便使用DB_HOSTlocalhost的坑如果.env里 MySQL 的DB_HOSTlocalhostFrankenPHP 的 PHP 会因找不到 MySQL socket 而在koel:init时报Checking database connection … ERRORHTTP 服务却正常。修复方式单条命令用DB_HOST127.0.0.1 frankenphp php-cli artisan command覆盖或直接把.env改为DB_HOST127.0.0.1。Caddyfile.example 中还预置了反向代理场景所需的配置块auto_https off与servers { trusted_proxies … }默认被注释掉把站点块从localhost {改为:8001 {并在块内首行加bind 127.0.0.1再让现有 nginx 等反向代理指向127.0.0.1:8001即可TLS 由反向代理终结。对于生产部署无论独立二进制还是 FrankenPHP都可以用 systemd 守护创建/etc/systemd/system/koel.service设置Typesimple、WorkingDirectory、User、ExecStart并通过AmbientCapabilitiesCAP_NET_BIND_SERVICE让非 root 进程也能绑定 80/443 端口然后sudo systemctl daemon-reload、sudo systemctl enable --now koel、用sudo journalctl -u koel -f查看日志。完整服务单元示例见 独立二进制部署指南 与 FrankenPHP 运行指南。升级 Koel危险升级前务必备份数据库无论使用哪种安装方式升级前都要记得备份数据库。升级请先查阅 Releases 中与你当前版本、安装方式对应的升级指南。总体而言升级过程涉及更新源码与依赖、运行数据库迁移偶尔还要新增/修改一些配置值。升级源码安装从源码安装的升级非常简单cd KOEL_ROOT_DIR git pull git checkout latest composer koel:initkoel:init会负责依赖安装、数据库迁移以及任何必要的配置迁移例如旧版图片目录public/img/storage/到storage/app/public/images/的自动迁移。升级预编译归档安装下载最新归档解压并替换现有文件。务必先移除旧的app与config目录cd KOEL_ROOT_DIR rm -rf app config # 假设我们要升级到 v7.0.0 wget -qO- https://github.com/koel/koel/releases/download/v7.0.0/koel-v7.0.0.tar.gz | tar -xvzC . --strip-components1 composer koel:init -- --no-assets升级 Docker 安装Docker 用户只需拉取最新镜像并重启容器即可。提示始终阅读发行说明无论哪种安装方式升级前都应阅读 Releases 中的发行说明以获取针对性的升级指引及你可能会遗漏的其他重要变更。降级 KoelKoel不提供内置的降级机制。万一确实需要降级唯一安全的路径是从备份恢复数据库然后按照目标版本的安装指南重新安装对应版本。这再次印证了升级前必须备份数据库的重要性——降级本质上依赖完整的数据库备份。下一步完成安装与基础配置后你可以通过php artisan list | grep koel查看全部koel命名空间下的管理命令如koel:scan扫描音乐、koel:prune清理空艺人/专辑、koel:doctor检查安装健康度、koel:storage配置存储驱动等详见 CLI 命令参考也可以阅读 环境变量参考 深入了解存储、扫描、流媒体、服务集成与 SSO 等完整配置项把 Koel 调校到最适合你的运行环境。赞分享音视频后端前端【免费下载链接】koelMusic streaming solution that works.项目地址https://gitcode.com/gh_mirrors/ko/koel点击查看免费下载相关推荐Karakeep Docker 部署指南docker-compose 快速安装、环境变量配置与版本升级Karakeep Docker 部署指南docker compose 快速安装、环境变量配置与版本升级 本篇技术指南聚焦于 Karakeep原 Hoarde后端前端移动开发AI 应用知识管理全文检索MCP 服务Highcharts 图表库安装指南五种方式快速上手Highcharts 图表库安装指南五种方式快速上手 前言 Highcharts 是一款功能强大的数据可视化 JavaScript 库支持创建各种交互式图表数据可视化前端Pipenv 安装完全指南多平台安装方式、环境变量与验证升级实践Pipenv 安装完全指南多平台安装方式、环境变量与验证升级实践 本篇指南以 Pipenv 官方安装文档为核心骨架系统讲解在 Windows、Linux、m开发工具CLI包管理器上一篇Parler-TTS开源贡献者手册代码规范、PR流程与评审标准下一篇Llama-FS命令自动补全提升CLI操作效率创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考