Koel自建音乐流服务和个人音乐电台-Koel Docker安装与使用教程
Koel是国外一个可以自建的个人音乐流服务器的软件,界面干净清爽,没有什么花里胡哨的东西,也没有什么开屏广告。如果你厌倦了某云、某Q、某狗等各种开机烦人的广告,也厌烦了各类音乐APP无关的功能,只要想要安安静静地听听歌,那么使用Koel自建音乐服务器就是一个非常不错的选择。
Koel安装起来并不简单,Koel官方给的安装教程需要配置不少的环境,所以我们使用Koel Docker的安装方法,直接可以一键安装与部署。Koel Docker安装对于服务器要求并不高,只需要一台VPS主机即可,只不过你需要找一个大容量的VPS主机,方便你存储大量的音乐文件。

更多的存储和同步服务还有:
- 利用Pydio搭建免费私有云存储-多终端自动同步可在线播放音乐视频
- Syncthing开源免费跨平台的文件同步工具-利用Syncthing搭建免费同步网盘
- FileGator文件管理器安装与使用教程-免费开源在线文件管理和下载程序
PS:2026年11月15日更新,替换Koel旧镜像与MySQL 5.7新装示例,更新Compose初始化、持久化和音乐扫描命令,修正Filemanager访问端口。
一、Koel安装前准备
网站:
- https://github.com/koel/koel
- https://github.com/koel/docker
- https://hub.docker.com/r/phanan/koel
1.1 准备VPS主机
Docker需要VPS运行,现在的VPS主机基本上也是白菜价了,有关于VPS主机评测查看:VPS主机排行榜单。
1.2 Docker环境
有了VPS主机,现在你就可以需要在VPS主机上配置好Docker环境,这里有一个一键安装Docker环境的命令,配置起来非常地简单:Docker 和 Docker Compose 一键安装脚本 可手动选择安装版本和下载源。
二、Koel Docker安装
首是新建文件夹。
mkdir -p /root/wzfou/koel cd /root/wzfou/koel
然后是新建 docker-compose.yml
vim docker-compose.yml
下面改用koel/docker提供的phanan/koel镜像及MariaDB示例,供全新安装参考。已有0xcaff/koel或MySQL 5.7数据卷不能直接套这份配置:先备份数据库、音乐、封面及APP_KEY,再按目标版本迁移,不能将旧MySQL卷直接交给MariaDB。原图保留旧版界面。
services:
koel:
image: phanan/koel
depends_on:
- database
ports:
- "3006:80"
environment:
DB_CONNECTION: mysql
DB_HOST: database
DB_USERNAME: koel
DB_PASSWORD: "替换为数据库用户密码"
DB_DATABASE: koel
APP_KEY: ${KOEL_APP_KEY:?请先在.env中设置KOEL_APP_KEY}
volumes:
- /opt/music:/music
- koel_images:/var/www/html/storage/app/public/images
- koel_search:/var/www/html/storage/search-indexes
database:
image: mariadb:10.11
volumes:
- db:/var/lib/mysql
environment:
MYSQL_ROOT_PASSWORD: "替换为独立的数据库管理员密码"
MYSQL_DATABASE: koel
MYSQL_USER: koel
MYSQL_PASSWORD: "替换为与上方一致的数据库用户密码"
volumes:
db:
koel_images:
koel_search:
然后执行命令安装:
# 全新安装:先生成密钥,将输出保存到当前目录.env docker run --rm phanan/koel php artisan key:generate --show # 编辑.env:KOEL_APP_KEY=上一步完整输出;已有站点保留原APP_KEY nano .env docker compose config --quiet docker compose up -d docker compose ps docker compose logs --tail=100 koel
三、Koel Docker设置
当前镜像通常在首次启动时自动运行koel:init,除非设置SKIP_INIT。先看启动日志,不要每次启动都强制重建账号。需要手动初始化时,用Compose服务名进入,避免依赖旧版koel_koel_1容器名:
docker compose exec --user www-data koel php artisan koel:init --no-assets

打开IP:3006。当前镜像首次初始化会创建默认管理员,按相应版本README登录并立即修改邮箱和密码;不要假设总会出现注册向导。反代HTTPS时另核对FORCE_HTTPS设置。

登录成功后,先设置一下你的音乐文件存储路径。我们在Docker安装时设置了/opt/music,这里我们就填写/music。

你也可在你的服务器中看到此目录,你现在可以将音乐文件上传到这个目录中了。

四、Koel音乐服务器使用
当前镜像通过调度任务定期扫描/music,不是复制文件后必定立即可见。需要立即入库可运行docker compose exec –user www-data koel php artisan koel:sync,再检查日志和文件读取权限。

这个就是Koel音乐播放界面。(点击放大)

五、Koel优化文件管理
下面Filemanager命令和截图是历史整合方案,与当前Koel并无必需依赖。8006来自-p 8006:80,不是8003;沿用第三方管理器前要核对镜像维护情况和认证,不要将音乐管理目录无认证开放。
整合Filemanager。我们在以前的文章有介绍过CCAA脚本整合了Filemanager文件管理器,Filemanager是一个非常不错的在线文件管理器。Koel可以使用以下方法将Filemanager整合进来。
docker run -d --restart=always \
-v /opt/music:/srv \
-p 8006:80 \
--name filebrowser \
langren1353/filebrowser-ckplayer
访问IP:8006就可以Filemanager界面了,由于我们在安装Filemanager时已经将它默认的下载路径设置与Koel的音乐路径保持一致,直接用Filemanager就可以下载和查看文件了。


六、总结
Koel使用Docker安装简单方便,但是Koel的移动APP是收费的,介意的朋友可以直接使用Koel的Web版,在手机浏览器中添加快捷方式,这样变相地在手机上使用Koel播放音乐了。
文章出自:挖站否 https://wzfou.com/koel/,版权所有。本站文章除注明出处外,皆为作者原创文章,可自由引用,但请注明来源。 https://hub.docker.com/r/phanan/koel













这个教程基于什么系统也不说。