Black Candy 配置参数详解

‍‍​​‌​> 目标：讲清 Black Candy v3.2.1 的完整配置面——环境变量体系、Web 管理设置页、个人偏好三层的参数语义、取值与实测表现，并给出家用单机与 PostgreSQL 双模板。事实依据为官方 README 环境变量表、源码与实测环境（Docker 部署见《Black Candy Docker Compose 部署实战》）。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64），Docker Engine 29.9.2 / Compose v5.6.1
• Black Candy：v3.2.1（官方映像 ghcr.io/blackcandy-org/blackcandy:latest，COMMIT_HASH 93cfdca9857a5e2ae847469c3238a6174515c76f）
• 实测服务端口：8136（容器内 80）；编排目录 /opt/black-candy/
• 配置事实来源：官方 README.md 环境变量表（溯源日期 2026-10-28）、映像内实测（设置页渲染、SQLite 存储清单、rails runner 运行时查询）
• 涉及的登录账号：管理员 admin@admin.com（密码已按流程改为 q1w2e3r4）

二、前置条件

1. 已按《Black Candy Docker Compose 部署实战》完成部署并可登录；
2. 理解 Black Candy 的三层配置面与生效方式：

💡 环境变量是「运行时配置」，存于进程环境、随编排文件版本化；设置页参数是「业务配置」，持久化在主库 production.sqlite3 的 settings 表中。两者的关系在「4.2 媒体路径」中详述。

三、参数总览

官方 README 环境变量表全量参数（Default 为官方标注值）：

💡 补充：映像还内置 WEB_CONCURRENCY=auto（Puma 集群进程数按 CPU 核数自动决定）与 LD_PRELOAD=/usr/lib/libjemalloc.so.2（jemalloc 内存分配器）两个运行时默认值，来自官方映像（docker inspect 取证），一般无需覆盖。

管理设置页参数（落库，保存即生效）：

个人设置页参数：Theme（单选 dark / light / auto，默认 auto，跟随系统）。

四、核心参数分类详解

4.1 数据库族：DB_ADAPTER + 四库分离

默认形态（SQLite）：Black Candy 基于 Rails 8 的三库架构再加主库，实际是四个独立 SQLite 文件，全部落在 /rails/storage。实测目录清单：

production.sqlite3        # 主库：用户/艺人/专辑/曲目/播放列表/会话
production_queue.sqlite3  # Solid Queue 后台任务库
production_cache.sqlite3  # 应用缓存库（含同步进行中标志位）
production_cable.sqlite3  # Action Cable 推送库

官方 README 的态度很明确：SQLite 简化安装，是自托管小服务的理想选择；只有当你认为 SQLite 对自己的量级不够用、或平台要求外部数据库（如 Heroku）时才切换 PostgreSQL。

切换 PostgreSQL：DB_ADAPTER=postgresql 并同时提供四个连接串（主库 + 任务 + 缓存 + 推送各一个）：

DB_ADAPTER=postgresql
DB_URL=postgresql://<user>:<pass>@<host>:5432/blackcandy
QUEUE_DB_URL=postgresql://<user>:<pass>@<host>:5432/blackcandy_queue
CACHE_DB_URL=postgresql://<user>:<pass>@<host>:5432/blackcandy_cache
CABLE_DB_URL=postgresql://<user>:<pass>@<host>:5432/blackcandy_cable

（连接串中的账号、密码、库名按读者环境替换；四个库须为相互独立的数据库名。）切换后存储目录中不再产生 .sqlite3 文件，数据持久化责任转移到 PostgreSQL 实例——备份策略也要随之改变（见「六、生产配置模板」）。

4.2 媒体路径：MEDIA_PATH 与设置页的双通道

媒体路径有两个声明入口，实测行为：

• 环境变量 MEDIA_PATH：启动时注入，与挂载点绑定（编排里 -v /opt/black-candy/media_data:/media_data + MEDIA_PATH=/media_data）。运行时查询验证：

docker exec black-candy-v3.2.1-app rails runner 'puts Setting.media_path'

实测输出：

/media_data

• 设置页 Media Path：渲染当前生效路径（实测输入框值 /media_data），修改保存后立即触发全量媒体同步（v3.2.0 起，设置页在媒体路径变更时主动触发 MediaSyncAllJob），旧路径下已入库而新路径不存在的曲目会被清理下架。

⚠️ 注意：无论哪个入口，路径都指容器内路径，必须与 volumes 挂载点一致；挂载点变了而 MEDIA_PATH 没改，同步会因目录不存在而得到空曲库。修改媒体路径属高风险操作，先备份再动（见《Black Candy 常用命令与运维实战》）。

4.3 会话安全：SECRET_KEY_BASE

• 作用面：登录会话（Cookie）的加解密根。值一旦变化，所有既有会话立即失效，所有用户需重新登录；
• 不设置的默认行为：每次启动都随机生成——这正是 README 特意提示「每次重启服务都会把用户登出」的原因；
• 生成方式（官方建议）：

openssl rand -hex 64

实测输出示例（读者应使用自己生成的新值，不要复用本文值）：

755d2fdebb694ac35618e4ebbe237c4254ef30b0298214099f826248c1a787cb422bde0fbba5935756204f0cdff82df8068b7e5c7fef16d688d6efe63f22e0ca

• 实测验证：部署时固定该值，服务在 stop → start 与映像升级（up -d 重建实例）之间来回切换，登录会话均保持有效。

4.4 传输与访问：FORCE_SSL / HTTP_PORT / DEMO_MODE

• FORCE_SSL（默认 false）：设为 true 后全站强制 HTTPS 跳转。前提是前置的反向代理已正确终结 TLS；直接裸 HTTP 访问的部署不要开启，否则站点不可达。实测部署未开启（本环境为 8136 端口直连 HTTP 验证形态）；
• HTTP_PORT（默认 80）：服务在容器内监听的端口。常规做法保持默认、在宿主侧换端口映射（"8136:80"）；仅当读者有「容器内也必须换端口」的特殊要求时才需要动它——注意端口映射右侧与该值需保持一致；
• DEMO_MODE（默认 false）：官方 README 定义——开启后所有用户（含管理员）不能使用任何管理特权、不能修改个人资料。适合把服务公开演示给他人时的只读收听形态；日常自用绝不要开启。实测环境未开启（保持管理员改密、建用户等全部特权可用）。

4.5 Web 管理设置页参数

管理员登录后访问 /setting（头像菜单 → Setting），实测页面参数：

• Transcode Bitrate（转码码率）：下拉框三档——128 / 192 / 320 kbps（实测选项值 128/192/320）。控制「浏览器不支持原格式时的转码输出码率」，码率越低流量越省、音质越差。家用局域网建议 320，公网/移动流量场景可降 128；
• Allow Transcode Lossless（允许无损转码）：复选框。开启后对无损格式（FLAC 等）也执行转码（转成有损输出）；关闭时无损文件优先原格式直出。实测环境默认关闭；
• Discogs Token：Discogs API 的个人令牌。填入后，媒体同步会对缺少封面的艺人/专辑向 Discogs 补抓官方图片（入库为外部封面附件）。不填则封面仅来自音频文件内嵌图。实测环境未填（测试音频无内嵌封面，页面显示占位图）；
• Sync 按钮：触发全量同步，异步执行——点击后按钮进入 Syncing 状态，任务经 Solid Queue 队列（队列名 critical）执行，完成时长与曲库规模成正比。实测 6 首测试曲从点击到全部入库约 10 秒内；日志取证见部署篇「常见问题」Q3。

4.6 个人偏好：主题

每用户独立的界面主题，实测设置页为三个单选项：dark（深色）/ light（浅色）/ auto（跟随系统，默认值）。保存即生效，纯前端观感参数，不影响服务端行为。

五、生产配置模板

模板一：家用单机（推荐起点）

适用：个人/家庭音乐库（万首以内）、单机 2C4G 起、SQLite 默认栈。即实测通过的编排 environment: 块：

    environment:
      SECRET_KEY_BASE: <openssl rand -hex 64 生成值>
      MEDIA_PATH: /media_data

配合的挂载与端口（完整编排见部署篇）：storage_data:/rails/storage（数据）、media_data:/media_data（音乐）、"8136:80"。只需两个环境变量即可上线——这是 Black Candy 配置面的最大特色。

资源规划（实测观察，534MB 映像、6 首测试曲栈运行平稳）：

• 内存：空闲态约数百 MB 级（Puma auto 集群 + Solid Queue 三进程 + jemalloc 已启用）；万首级曲库、少量并发收听场景建议预留 1-2 GB；
• 磁盘：主库体积与曲库文件数线性相关（实测 6 首约 150 KB，万首估算数百 MB 级），封面缓存与无损音乐本体才是大头；
• 转码并发：按需转码由 ffmpeg 执行，公网多用户并发收听时关注 CPU 余量。

模板二：PostgreSQL 外部库形态

适用：曲库规模大、已有 PostgreSQL 基础设施、或需要独立备份策略的读者：

    environment:
      SECRET_KEY_BASE: <openssl rand -hex 64 生成值>
      MEDIA_PATH: /media_data
      DB_ADAPTER: postgresql
      DB_URL: postgresql://blackcandy:<pass>@pg-host:5432/blackcandy
      QUEUE_DB_URL: postgresql://blackcandy:<pass>@pg-host:5432/blackcandy_queue
      CACHE_DB_URL: postgresql://blackcandy:<pass>@pg-host:5432/blackcandy_cache
      CABLE_DB_URL: postgresql://blackcandy:<pass>@pg-host:5432/blackcandy_cable
      FORCE_SSL: "true"

（<pass> 与主机名按实际替换；FORCE_SSL 仅在已有 TLS 反代时开启。）此形态下 /rails/storage 目录仍需挂出（封面等附件缓存仍在其中），但曲库主数据的备份责任转移到 PostgreSQL 侧。

六、常见问题（实测排障实录）

Q1：环境变量和设置页的媒体路径不一致时听谁的？

以环境变量为准。实测环境中 MEDIA_PATH=/media_data 始终与挂载点一致，设置页输入框显示的就是该值；若把设置页值改成别的路径，同步会指向新路径。原则：用编排声明的环境变量作为唯一事实源，设置页仅作核对与一次性变更入口。

Q2：改了 SECRET_KEY_BASE 之后发生什么？

所有用户被登出（会话解密失败），重新登录即可，数据无损。实测在改密验证流程中更换过会话根，效果符合预期。因此：生产固定该值后不要随意更换；轮换时选低峰期并通知用户。

Q3：DEMO_MODE 开了还能当管理员用吗？

不能。官方定义该模式下所有用户（含管理员）均无管理特权、不能改个人资料。实测环境未开启此模式；若误开启导致「设置页/用户管理入口消失」，把 DEMO_MODE 移除或改回 false 重启即恢复。

Q4：开启 FORCE_SSL 后 HTTP 访问不跳转或不可达？

FORCE_SSL 期望前面有终结 TLS 的反向代理。8136 直连 HTTP 的形态下开启它会导致访问异常（实测部署保持 FORCE_SSL=false）。正确顺序：先配好 HTTPS 反代并验证，再开启 FORCE_SSL。

Q5：转码码率改了没生效？

该参数只影响「需要转码」的播放（原格式不被浏览器支持或流式转码请求），不影响原格式直出的文件。用支持的浏览器播放 mp3 时通常直出（实测 /stream/new 直出 audio/mpeg，481202 字节与源文件一致），感知不到码率变化是正常现象；验证转码可用浏览器不支持的原格式（如 ape/flac 视开关状态）或观察转码流内容类型变化。

七、参考链接

• 官方 README 环境变量表（Configuration 章节）：https://github.com/blackcandy-org/blackcandy#configuration
• 官方仓库（Dockerfile 运行时默认值）：https://github.com/blackcandy-org/blackcandy
• 本专栏系列篇：《Black Candy 介绍与选型指南》、《Black Candy Docker Compose 部署实战》、《Black Candy 常用命令与运维实战》