koel 9.15.0 配置参数详解
Koel 9.15.0 配置参数详解：.env 全量变量按应用基础/数据库/存储/扫描/流式转码/搜索/集成/功能开关/SSO/Laravel 十类逐项解说，含 config:show 实测回显与生产配置模板。
koelkoelLaravel音乐2026/10/29
koel 9.15.0 配置参数详解
目标：把 Koel 9.15.0 的全部配置参数（.env 变量）按用途分类讲清含义、默认值与实测表现，并给出可直接套用的生产配置模板。全部取值与回显在 Ubuntu 24.04.5 LTS 实测实例（部署见《koel 9.15.0 Docker Compose 部署指南》）上验证，镜像内 .env.example（358 行）与运行时 config:show 输出均已逐项核对。
一、环境信息
| 项目 | 值 | 备注 |
|---|---|---|
| 操作系统 | Ubuntu 24.04.5 LTS（x86_64） | 实测服务器 |
| Koel 版本 | 9.15.0 | 配置结构以该版本的 .env.example 与 config/koel.php 为准 |
| 运行时 | PHP 8.4.27 / Laravel 13.24.0 | php artisan about 实测 |
| 数据库 | MariaDB 10.11.19（DB_CONNECTION=mysql） | 实测连接正常 |
| 应用目录 | /var/www/koel | 下文所有 artisan 命令均在该目录执行 |
| 配置文件 | /var/www/koel/.env | Koel 全部自定义参数所在（Laravel 约定） |
| 演示管理账号 | admin@koel.dev / q1w2e3r4 | 实测登录通过 |
二、前置条件
- 已完成 Koel 9.15.0 安装并能正常访问（首次安装见《koel 9.15.0 Docker Compose 部署指南》或官方手动安装文档）；
- 能登录服务器编辑
/var/www/koel/.env，并能以应用运行用户（www-data）执行 artisan 命令； - 演示账号 admin@koel.dev / q1w2e3r4 已可登录 Web 界面（用于对照界面表现）。
三、参数查看与修改方式
Koel 的自定义参数集中在应用根目录的 .env 文件（KEY=VALUE 格式），全部参数都有"运行时真实值"可查——改配置前后务必用下面三种手段核对，而不是只看文件。
方式 1：直接查看 .env 文件（实测实例的完整内容，33 行）：
cat /var/www/koel/.env
实测回显：
APP_NAME=Koel
APP_ENV=production
APP_DEBUG=false
APP_URL=http://127.0.0.1
DB_CONNECTION=mysql
DB_HOST=database
DB_PORT=3306
DB_DATABASE=koel
DB_USERNAME=koel
DB_PASSWORD=koeldb2026
STORAGE_DRIVER=local
MEDIA_PATH=/music
ARTIFACTS_PATH=
IGNORE_DOT_FILES=true
APP_MAX_SCAN_TIME=600
MEMORY_LIMIT=1024
STREAMING_METHOD=php
SCOUT_DRIVER=tntsearch
USE_MUSICBRAINZ=true
TRANSCODE_FLAC=false
ALLOW_DOWNLOAD=true
BACKUP_ON_DELETE=true
PODCASTS_ENABLED=true
RADIO_ENABLED=true
CLEAN_URLS_ENABLED=false
EMBED_ENABLED=true
MAIL_MAILER=log
BROADCAST_CONNECTION=log
CACHE_DRIVER=file
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120
方式 2：config:show 查看运行时真实值——比看文件更可信，因为它显示的是"应用此刻实际生效"的值（完整配置树，支持 config:show koel.streaming 这类点号路径下钻）：
cd /var/www/koel && php artisan config:show koel.scan
实测回显：
koel.scan ..................................................................
timeout ................................................................ 600
memory_limit .......................................................... 1024
jobs ..................................................................... 4
php artisan config:show koel.streaming | head -7
实测回显：
koel.streaming .............................................................
bitrate ................................................................ 128
aac_fast .............................................................. true
method .......................................................... x-sendfile
ffmpeg_path ................................................ /usr/bin/ffmpeg
transcode_flac ....................................................... false
transcode_timeout ...................................................... 300
php artisan config:show scout | head -6 && php artisan config:show database.default
实测回显：
scout ......................................................................
driver ........................................................... tntsearch
prefix .....................................................................
queue ................................................................ false
after_commit ......................................................... false
chunk ⇁ searchable ..................................................... 500
database.default ..................................................... mysql
方式 3：koel:doctor 一屏总览关键配置的健康状态（目录权限、数据库、搜索索引、FFmpeg、集成状态、流式方式等十余项，详见《koel 9.15.0 常用 CLI 命令与工具详解》）。
修改生效规则（重要）：
- 编辑
.env后需清配置缓存并重启应用进程：php artisan config:clear后重启 php-fpm/Apache（或容器）； - 进程环境变量优先于 .env 文件：若运行环境注入了同名变量（systemd 的
Environment=、shell 导出、编排平台的 environment 等），.env中的同名项会被静默覆盖——本文实测实例就发生了.env写STREAMING_METHOD=php而运行时实际为x-sendfile的现象，核辨方法见第七章 FAQ Q1。
四、参数总览
Koel 9.15.0 的 .env.example 共 358 行，约 70 个变量。按用途归为十类，总览如下（★=本文实测实例已启用并验证的项）：
| 分类 | 代表变量 | 一句话作用 |
|---|---|---|
| 应用基础 | ★APP_NAME、★APP_ENV、★APP_DEBUG、★APP_URL、TRUSTED_HOSTS、TRUSTED_PROXIES、APP_KEY、FORCE_HTTPS | 应用标识、环境、安全边界 |
| 数据库 | ★DB_CONNECTION、★DB_HOST、★DB_PORT、★DB_DATABASE、★DB_USERNAME、★DB_PASSWORD、DATABASE_URL、MYSQL_ATTR_SSL_CA | 关系库连接 |
| 媒体存储 | ★STORAGE_DRIVER、★MEDIA_PATH、★ARTIFACTS_PATH、AWS_、SFTP_、WEBDAV_、DROPBOX_、IMAGE_STORAGE_* | 音频与图片的存放位置 |
| 扫描与媒体库 | ★IGNORE_DOT_FILES、★APP_MAX_SCAN_TIME、★MEMORY_LIMIT、SCAN_JOBS、SYNC_LOG_LEVEL | 扫描行为与资源上限 |
| 流式与转码 | ★STREAMING_METHOD、★TRANSCODE_FLAC、FFMPEG_PATH、TRANSCODE_BIT_RATE、TRANSCODE_AAC_FAST、TRANSCODE_TIMEOUT、CDN_URL | 音频出流方式与实时转码 |
| 搜索 | ★SCOUT_DRIVER、ALGOLIA_APP_ID、ALGOLIA_SECRET、MEILISEARCH_HOST、MEILISEARCH_KEY | 全文搜索引擎选择 |
| 元数据与集成 | ★USE_MUSICBRAINZ、MUSICBRAINZ_USER_AGENT、LASTFM_API_KEY/SECRET、LISTENBRAINZ_API_ENDPOINT、SPOTIFY_CLIENT_ID/SECRET、YOUTUBE_API_KEY、TICKETMASTER_*、IPINFO_TOKEN | 封面/MBID/scrobble 等外部服务 |
| 功能开关 | ★ALLOW_DOWNLOAD、★BACKUP_ON_DELETE、MEDIA_BROWSER_ENABLED、★CLEAN_URLS_ENABLED、★EMBED_ENABLED、★PODCASTS_ENABLED、★RADIO_ENABLED | 模块与能力开关 |
| SSO 与代理认证 | SSO_GOOGLE_、SSO_OIDC_、SSO_DEFAULT_ROLE、PROXY_AUTH_* | 免密登录与企业身份对接 |
| Laravel 基础 | ★MAIL_MAILER、★BROADCAST_CONNECTION、★CACHE_DRIVER、★QUEUE_CONNECTION、★SESSION_DRIVER、★SESSION_LIFETIME、PUSHER_*、SENTRY_LARAVEL_DSN、FILESYSTEM_DISK | 框架层驱动选型 |
💡 技术拓展：Koel 的全文搜索走 Laravel Scout 抽象层，可选驱动不止一种——
驱动 原理 适用场景 tntsearch 纯 PHP 全文索引，数据在本地文件，零外部依赖 默认；中小库（数万首内）个人部署 database 直接用数据库 LIKE/FULLTEXT 查询 不想维护索引文件的极简场景 meilisearch 独立 MeiliSearch 服务，毫秒级搜索 大库（十万首级）、要求即时搜索体验 algolia SaaS 托管搜索 不介意第三方托管与费用 实测实例采用默认 tntsearch（
config:show scout实测 driver=tntsearch），个人库规模下无需额外维护搜索引擎服务。
五、核心参数分类详解
5.1 应用基础
APP_NAME=Koel
APP_ENV=production
APP_DEBUG=false
APP_URL=http://127.0.0.1
TRUSTED_HOSTS=
TRUSTED_PROXIES=PRIVATE_SUBNETS
APP_KEY=base64:... # 首次初始化自动生成
FORCE_HTTPS=
| 参数 | 默认值 | 说明 |
|---|---|---|
| APP_NAME | Koel | 应用名；同时是 Sanctum 令牌签发名（实测令牌所属应用名即 Koel） |
| APP_ENV | production | 运行环境；实测 about 输出 Environment=production、Debug Mode=OFF |
| APP_DEBUG | false | 调试开关；生产必须 false，否则异常页暴露堆栈 |
| APP_URL | http://localhost:8000 | 对外访问地址，影响生成的绝对链接（封面 URL、密码重置链接等）；实测实例为 http://127.0.0.1 |
| TRUSTED_HOSTS | 空 | 逗号分隔的合法主机名白名单，空=不限制；支持 *.example.com 通配 |
| TRUSTED_PROXIES | PRIVATE_SUBNETS | 信任 X-Forwarded-* 的反代 IP 列表；默认仅信任私网网段 |
| APP_KEY | 空（自动生成） | 32 字节加密密钥；更换后所有已签发令牌失效、加密数据不可解，实测登录返回的 token/audio-token 均依赖它 |
| FORCE_HTTPS | 空 | 反代后 HTTPS 探测失败时置 true 强制生成 https 链接 |
验证：改 APP_DEBUG 前后用 php artisan about 对照 Debug Mode 行（实测 OFF）。
5.2 数据库
DB_CONNECTION=mysql
DB_HOST=database
DB_PORT=3306
DB_DATABASE=koel
DB_USERNAME=koel
DB_PASSWORD=koeldb2026
DATABASE_URL=
MYSQL_ATTR_SSL_CA=
| 参数 | 默认值 | 说明 |
|---|---|---|
| DB_CONNECTION | mysql | 驱动值域（实测 .env.example 注释）：mysql（MySQL/MariaDB 默认）、mariadb、pgsql（PostgreSQL）、sqlsrv（SQL Server）、sqlite-persistent（本地 SQLite 文件） |
| DB_HOST | 127.0.0.1 | 数据库主机；实测实例为容器编排服务名 database |
| DB_PORT | 3306 | 端口，随驱动变化（pgsql 为 5432） |
| DB_DATABASE / DB_USERNAME / DB_PASSWORD | koel / koel / 空 | 库名与凭据 |
| DATABASE_URL | 空 | 整串连接 URL（Heroku 类平台），设置后替代上面散装五项 |
| MYSQL_ATTR_SSL_CA | 空 | MySQL over SSL 的根 CA 绝对路径 |
实测连接验证：php artisan koel:doctor（实测输出 "Checking database connection .... OK"）或 php artisan db:show。数据库侧实测共 40 张业务表（songs、albums、artists、playlists、podcasts、radio_stations、personal_access_tokens 等）。
5.3 媒体存储
STORAGE_DRIVER=local
MEDIA_PATH=/music
ARTIFACTS_PATH=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=
AWS_ENDPOINT=
AWS_BUCKET=
SFTP_HOST=
SFTP_PORT=
SFTP_ROOT=
SFTP_USERNAME=
SFTP_PASSWORD=
SFTP_PRIVATE_KEY=
SFTP_PASSPHRASE=
WEBDAV_BASE_URL=
WEBDAV_USERNAME=
WEBDAV_PASSWORD=
WEBDAV_PATH_PREFIX=
DROPBOX_APP_KEY=
DROPBOX_APP_SECRET=
DROPBOX_REFRESH_TOKEN=
IMAGE_STORAGE_DRIVER=local
IMAGE_STORAGE_DIR=storage/images
IMAGE_STORAGE_BUCKET=
IMAGE_STORAGE_URL=
| 参数 | 默认值 | 说明 |
|---|---|---|
| STORAGE_DRIVER | local | 值域（实测 .env.example 注释）：local 本地磁盘；sftp SFTP 服务器；s3 / dropbox / webdav 为 Koel Plus 专属（实测免费实例 koel:license:status 返回 "No license found"，配了也用不了） |
| MEDIA_PATH | 空 | local 驱动的媒体库根目录（绝对路径）；实测实例为 /music，扫描与上传均落在此目录（实测扫描 "Scanning /music with 4 parallel workers"） |
| ARTIFACTS_PATH | 空 | 转码产物、播客下载等中间文件目录；空=系统临时目录/koel（实测 doctor 显示 "Artifacts directory /tmp/koel/ is readable/writable .... OK"） |
| AWS_* / SFTP_* / WEBDAV_* / DROPBOX_* | 空 | 对应驱动的连接凭据，启用相应驱动时才需要 |
| IMAGE_STORAGE_DRIVER / DIR | local / storage/images | 封面与头像的存储；可独立设为 s3 并配独立桶 |
💡 技术拓展：媒体存储后端（STORAGE_DRIVER）是典型的多选架构点——local 性能最好且零依赖但受单机磁盘约束；sftp 适合媒体在 NAS/远程盘；s3/dropbox/webdav 属 Plus，把库托管到对象存储适合多实例或超大库。实测实例数据量小且本地盘充裕，采用 local。
5.4 扫描与媒体库
IGNORE_DOT_FILES=true
APP_MAX_SCAN_TIME=600
MEMORY_LIMIT=1024
SCAN_JOBS=
SYNC_LOG_LEVEL=error
| 参数 | 默认值 | 说明 |
|---|---|---|
| IGNORE_DOT_FILES | true | 扫描时跳过点文件/点目录（.git、.cache 等），大目录显著提速；媒体确在点目录下才改 false |
| APP_MAX_SCAN_TIME | 600 | 网页端触发扫描的超时秒数（CLI 的 koel:scan 不受此限，实测 .env.example 注释明确说明） |
| MEMORY_LIMIT | 空 | 扫描进程内存上限 MB；实测设 1024，运行时确认 config:show koel.scan 输出 memory_limit=1024 |
| SCAN_JOBS | 4 | 并行扫描 worker 数；实测 config:show koel.scan 输出 jobs=4，koel:scan 回显 "Scanning /music with 4 parallel workers" |
| SYNC_LOG_LEVEL | error | 扫描日志粒度：all（全量）/ error（默认，仅报错）；日志在 storage/logs/ |
5.5 流式与转码
STREAMING_METHOD=php
TRANSCODE_FLAC=false
FFMPEG_PATH=
TRANSCODE_BIT_RATE=128
TRANSCODE_AAC_FAST=true
TRANSCODE_TIMEOUT=300
CDN_URL=
| 参数 | 默认值 | 说明 |
|---|---|---|
| STREAMING_METHOD | php | 值域（实测 .env.example 注释）：php / x-sendfile / x-accel-redirect；移动 App 场景官方强烈建议后两者；实测实例运行时为 x-sendfile（来源与核辨见第七章 FAQ Q1） |
| TRANSCODE_FLAC | false | FLAC 实时转 AAC 开关；实测关闭（FLAC 原样直出） |
| FFMPEG_PATH | 空（自动探测） | ffmpeg 绝对路径；实测自动探测为 /usr/bin/ffmpeg（koel:doctor 输出 "FFmpeg binary /usr/bin/ffmpeg is executable .... OK"） |
| TRANSCODE_BIT_RATE | 128 | 转码码率 kbps；运行时实测 koel.streaming.bitrate=128（兼容旧变量名 OUTPUT_BIT_RATE） |
| TRANSCODE_AAC_FAST | true | 用 FFmpeg 快速 AAC 编码器（快且高码率下质量好）；false 用慢速 twoloop |
| TRANSCODE_TIMEOUT | 300 | 单文件转码超时秒；0=不限（不建议） |
| CDN_URL | 空 | 媒体文件 CDN 前缀，映射到站点根；无 CDN 不配 |
流式方式核验命令与实测回显：
php artisan config:show koel.streaming | grep method
实测回显：
method .......................................................... x-sendfile
5.6 搜索
SCOUT_DRIVER=tntsearch
ALGOLIA_APP_ID=
ALGOLIA_SECRET=
MEILISEARCH_HOST=
MEILISEARCH_KEY=
| 参数 | 默认值 | 说明 |
|---|---|---|
| SCOUT_DRIVER | tntsearch | 值域（实测 .env.example 注释）：tntsearch（默认）/ database / algolia / meilisearch；运行时实测 driver=tntsearch |
| ALGOLIA_APP_ID / ALGOLIA_SECRET | 空 | Algolia 凭据 |
| MEILISEARCH_HOST / MEILISEARCH_KEY | 空 | MeiliSearch 服务地址与密钥 |
切换驱动后需重建索引：php artisan koel:search:import（实测回显为 Song/Album/Artist/Playlist/Podcast 五类模型逐个 Imported）。
5.7 元数据与外部集成
USE_MUSICBRAINZ=true
MUSICBRAINZ_USER_AGENT=
LASTFM_API_KEY=
LASTFM_API_SECRET=
LISTENBRAINZ_API_ENDPOINT=
SPOTIFY_CLIENT_ID=
SPOTIFY_CLIENT_SECRET=
YOUTUBE_API_KEY=
TICKETMASTER_API_KEY=
TICKETMASTER_DEFAULT_COUNTRY_CODE=US
IPINFO_TOKEN=
| 参数 | 默认值 | 说明 |
|---|---|---|
| USE_MUSICBRAINZ | true | 用 MusicBrainz 社区音乐库补全艺人/专辑/曲目元数据；实测开启 |
| MUSICBRAINZ_USER_AGENT | 空（自动生成） | 访问 MusicBrainz 的 UA；空则按站点 URL+版本生成 |
| LASTFM_API_KEY / SECRET | 空 | Last.fm 集成（艺术家信息 + scrobble）；需在 last.fm/api 创建 API 账号 |
| LISTENBRAINZ_API_ENDPOINT | 空 | ListenBrainz 上报端点；不填用官方服务，用户在个人资料页自助连接 |
| SPOTIFY_CLIENT_ID / SECRET | 空 | Spotify 封面补全 |
| YOUTUBE_API_KEY | 空 | YouTube 集成 |
| TICKETMASTER_* / IPINFO_TOKEN | 空 / 空 | 演出推荐集成（按用户 IP 定位国家） |
集成是否就绪用 koel:doctor 一屏可见，实测回显（未申请 Key 时的形态）：
Last.fm integration .......................................... Not available
YouTube integration .......................................... Not available
Spotify integration .......................................... Not available
5.8 功能开关
ALLOW_DOWNLOAD=true
BACKUP_ON_DELETE=true
MEDIA_BROWSER_ENABLED=false
CLEAN_URLS_ENABLED=false
EMBED_ENABLED=true
PODCASTS_ENABLED=true
RADIO_ENABLED=true
| 参数 | 默认值 | 说明 |
|---|---|---|
| ALLOW_DOWNLOAD | true | 允许歌曲下载 |
| BACKUP_ON_DELETE | true | 从文件系统删除歌曲前先备份一份（误删保险） |
| MEDIA_BROWSER_ENABLED | false | 资源管理器式媒体浏览器（Plus 功能） |
| CLEAN_URLS_ENABLED | false | 伪静态 URL（/albums 代替 /#/albums）；实测关闭 |
| EMBED_ENABLED | true | 允许歌曲/专辑/歌单外链嵌入第三方站点 |
| PODCASTS_ENABLED | true | 播客模块；实测开启（koel:podcasts:sync 可运行，空库返回 "No podcasts to sync."） |
| RADIO_ENABLED | true | 电台模块；实测开启（radio_stations 表存在） |
5.9 SSO 与反向代理认证
SSO_GOOGLE_CLIENT_ID=
SSO_GOOGLE_CLIENT_SECRET=
SSO_GOOGLE_HOSTED_DOMAIN=yourdomain.com
SSO_OIDC_ISSUER=
SSO_OIDC_CLIENT_ID=
SSO_OIDC_CLIENT_SECRET=
SSO_OIDC_BUTTON_LABEL=
SSO_DEFAULT_ROLE=user
PROXY_AUTH_ENABLED=false
PROXY_AUTH_USER_HEADER=remote-user
PROXY_AUTH_PREFERRED_NAME_HEADER=remote-preferred-name
PROXY_AUTH_ALLOW_LIST=
| 参数 | 默认值 | 说明 |
|---|---|---|
| SSO_GOOGLE_* | 空 | Google OAuth 单点登录；三项配齐即自动启用 SSO |
| SSO_OIDC_* | 空 | 通用 OIDC 提供商（实测 .env.example 注释点名 Authentik、Authelia、Keycloak、Zitadel）；ISSUER 填暴露 /.well-known/openid-configuration 的 URL |
| SSO_DEFAULT_ROLE | user | SSO 首登用户被授予的角色：user（默认）或 guest |
| PROXY_AUTH_ENABLED | false | 反向代理头认证（Authelia 类网关后部署） |
| PROXY_AUTH_USER_HEADER | remote-user | 携带用户唯一标识的请求头名 |
| PROXY_AUTH_ALLOW_LIST | 空 | 允许注入认证头的代理 IP/CIDR 白名单；空=全部拒绝（等效禁用） |
5.10 Laravel 基础驱动
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"
MAIL_MAILER=smtp
MAIL_HOST=mailhog
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
BROADCAST_CONNECTION=log
CACHE_DRIVER=file
FILESYSTEM_DISK=local
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120
PUSHER_APP_ID=
PUSHER_APP_KEY=
PUSHER_APP_SECRET=
PUSHER_APP_CLUSTER=
SENTRY_LARAVEL_DSN=
SQS_PUBLIC_KEY=
SQS_SECRET_KEY=
SQS_QUEUE_PREFIX=
SQS_QUEUE_NAME=
SQS_QUEUE_REGION=
| 参数 | 默认值 | 说明 |
|---|---|---|
| MAIL_MAILER | smtp | 邮件驱动；实测 log（写日志不真发）——个人部署无邀请邮件需求时最省事；需邀请成员/找回密码才配 smtp |
| BROADCAST_CONNECTION | log | 事件广播驱动；实测 log。配 pusher 可获得"远程遥控播放、后台上传完成实时刷新"等增强（需同时填 PUSHER_*） |
| CACHE_DRIVER | file | 缓存驱动；实测 file。多实例或高频访问可换 redis |
| QUEUE_CONNECTION | sync | 队列驱动；实测 sync（同步执行）。上传后处理较多时建议 database/redis + 常驻队列进程 |
| SESSION_DRIVER / SESSION_LIFETIME | file / 120 | 会话存储与有效期（分钟） |
| FILESYSTEM_DISK | local | Laravel 文件系统默认盘 |
| PUSHER_* | 空 | Pusher 凭据（配合 BROADCAST_CONNECTION=pusher） |
| SENTRY_LARAVEL_DSN | 空 | Sentry 异常上报；实测 about 显示 Enabled=MISSING DSN（未配置即关闭） |
| SQS_* | 空 | AWS SQS 队列配置 |
六、生产配置模板
以下模板按三档典型场景给出，均已在实测实例的参数值域内验证过取值合法性；直接替换 .env 相应段落即可。
模板 A：个人自用（1–2 人，库 ≤1 万首，8GB 内存 / 机械盘或 SATA SSD）——实测实例即此档：
APP_ENV=production
APP_DEBUG=false
DB_CONNECTION=mysql
DB_HOST=database
STORAGE_DRIVER=local
MEDIA_PATH=/music
IGNORE_DOT_FILES=true
APP_MAX_SCAN_TIME=600
MEMORY_LIMIT=1024
SCAN_JOBS=4
STREAMING_METHOD=x-sendfile
TRANSCODE_FLAC=false
SCOUT_DRIVER=tntsearch
USE_MUSICBRAINZ=true
ALLOW_DOWNLOAD=true
BACKUP_ON_DELETE=true
PODCASTS_ENABLED=true
RADIO_ENABLED=true
MAIL_MAILER=log
BROADCAST_CONNECTION=log
CACHE_DRIVER=file
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120
要点：搜索/队列/缓存全用零依赖默认值，FLAC 不转码（文件少、盘慢时转码反而增加卡顿），流式用 x-sendfile 为移动 App 做准备。
模板 B：家庭多用户（3–8 人，库 1–5 万首，16GB 内存 / NVMe SSD）：
APP_ENV=production
APP_DEBUG=false
DB_CONNECTION=mysql
STORAGE_DRIVER=local
MEDIA_PATH=/music
ARTIFACTS_PATH=/var/koel-artifacts
IGNORE_DOT_FILES=true
APP_MAX_SCAN_TIME=1800
MEMORY_LIMIT=2048
SCAN_JOBS=8
STREAMING_METHOD=x-sendfile
TRANSCODE_FLAC=true
TRANSCODE_BIT_RATE=192
TRANSCODE_TIMEOUT=600
SCOUT_DRIVER=tntsearch
USE_MUSICBRAINZ=true
ALLOW_DOWNLOAD=true
BACKUP_ON_DELETE=true
PODCASTS_ENABLED=true
RADIO_ENABLED=true
EMBED_ENABLED=false
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
BROADCAST_CONNECTION=pusher
CACHE_DRIVER=file
QUEUE_CONNECTION=database
SESSION_DRIVER=file
SESSION_LIFETIME=1440
要点：多 FLAC 收藏开转码（弱终端播 192k AAC 更顺）；扫描资源翻倍；邮箱配 smtp 以支持成员邀请与密码找回；队列用 database 让上传后处理异步化；对外分享少时关 EMBED。
模板 C：大库/团队（≥5 万首或团队 10+ 人，32GB 内存 / NVMe，另备 MeiliSearch 与 S3 兼容存储）：
APP_ENV=production
APP_DEBUG=false
DB_CONNECTION=mariadb
STORAGE_DRIVER=s3
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
AWS_REGION=auto
AWS_ENDPOINT=https://<s3-兼容服务>
AWS_BUCKET=koel-media
MEDIA_PATH=
ARTIFACTS_PATH=/var/koel-artifacts
SCAN_JOBS=8
MEMORY_LIMIT=4096
APP_MAX_SCAN_TIME=3600
STREAMING_METHOD=x-accel-redirect
TRANSCODE_FLAC=true
SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://<meilisearch>:7700
MEILISEARCH_KEY=${MEILISEARCH_KEY}
CACHE_DRIVER=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
BROADCAST_CONNECTION=pusher
SENTRY_LARAVEL_DSN=${SENTRY_LARAVEL_DSN}
要点：第三方凭据一律经环境变量注入（${VAR}），不落 .env 明文；s3 存储为 Plus 功能需先激活许可；搜索换 MeiliSearch、缓存/队列/会话换 redis，为本机 tntsearch 索引与文件缓存减负；x-accel-redirect 配合 Nginx 出流。
七、常见问题（FAQ）
Q1：.env 里写 STREAMING_METHOD=php，为什么运行时是 x-sendfile？
实测排查实录：先看文件——
grep STREAMING_METHOD /var/www/koel/.env
实测回显：
STREAMING_METHOD=php
再看运行时——
php artisan config:show koel.streaming | grep method
实测回显：
method .......................................................... x-sendfile
两者不一致说明该值不是来自 .env 文件：Laravel 读取配置时进程环境变量优先于 .env 文件，实测实例的运行环境（Koel 官方应用镜像的内置环境变量）注入了 STREAMING_METHOD=x-sendfile。核辨方法：
printenv STREAMING_METHOD
实测回显：
x-sendfile
结论与解决：环境变量 > .env。想让 .env 的值生效，必须让运行环境不再注入同名变量（编排层面覆盖），改完用 config:show 复核。这条优先级规则对所有 KEY 都成立，排查"改了不生效"时先 printenv 再怀疑缓存。
Q2：改了 .env 但界面行为没变？
三步核查：① printenv <KEY> 确认没有同名环境变量覆盖（见 Q1）；② php artisan config:clear 清配置缓存（若开启过 config:cache，缓存未清前 .env 改动不可见）；③ 重启应用进程（php-fpm/Apache 或容器）后用 config:show 核对生效值。
Q3：koel:doctor 里 Last.fm/YouTube/Spotify 显示 Not available 是故障吗？
不是。这些集成都需要先到对应平台申请 API Key 并写入 .env（见 5.7 节），未配置时 doctor 如实显示 Not available（实测回显见 5.7 节）。配置后重跑 doctor 应显示 OK。
Q4：上传大文件失败，跟 MEMORY_LIMIT 有关吗？
无关。MEMORY_LIMIT（实测 1024）只限定扫描进程的内存上限（config:show koel.scan 的 memory_limit 项）。上传大小受 PHP 的 upload_max_filesize/post_max_size 与 Web 服务器 client_max_body_size（Nginx）限制——实测实例 koel:doctor 显示 "Max upload size ....... 800M"，即应用镜像预设的 PHP 上传上限；自建环境按需调大 php.ini 相应项。
Q5：忘记管理员密码怎么办？
用 CLI 重置（实测可用的完整过程见《koel 9.15.0 常用 CLI 命令与工具详解》4.5 节）：
cd /var/www/koel && php artisan koel:admin:change-password admin@koel.dev
按提示两次输入新密码，实测回显（输入不回显）：
Changing the user's password (ID: 1, email: admin@koel.dev)
Alrighty, the new password has been saved. Enjoy! 👌
Q6：换了 APP_KEY 后所有人都要重新登录？
是。APP_KEY 参与令牌与加密数据签名，实测登录返回的 token/audio-token 与之绑定。除非密钥泄露，不要更换；确需更换后让用户重新登录即可，媒体库数据不受影响（存在数据库中，与 APP_KEY 无关）。
八、参考链接
- 官方配置文档：https://docs.koel.dev/installation（.env 变量说明）与 https://docs.koel.dev/usage/streaming（流式方式专述）
- 官方 .env.example（与 9.15.0 版本一致，本文取值来源之一）：https://github.com/koel/koel/blob/master/.env.example
- 云存储（Plus）支持说明：https://docs.koel.dev/plus/cloud-storage-support
- 服务集成（Last.fm/YouTube/Spotify/Ticketmaster）：https://docs.koel.dev/service-integrations
- 站内关联：《koel 9.15.0 介绍与选型指南》（项目定位与选型）、《koel 9.15.0 Docker Compose 部署指南》（部署与容器侧排障）、《koel 9.15.0 常用 CLI 命令与工具详解》（doctor/scan 等命令实测）
章节目录