Bar Assistant 6.10.1 配置参数详解

Bar Assistant v6.10.1（Laravel 12/PHP 8.4）配置面逐项拆解：.env 全量清单、APP_KEY、SQLite 默认库与 MySQL/PG 切换、Redis 缓存会话分区、Meilisearch 索引结构、吧台业务开关、抓取代理、AI provider、价格货币与计费、日志与改配置标准动作，附 config:show 三处报错实录。

Bar AssistantBar AssistantLaravel自托管Redis2026/11/01

Bar Assistant 6.10.1 配置参数详解

适用版本：Bar Assistant API v6.10.1（Laravel 12.70.2 / PHP 8.4.27，php artisan about 实测）。本文以官方 .env.example 与运行时 php artisan config:show 实测输出为纲，逐项拆解配置面。部署过程见 《Bar Assistant Docker Compose 部署指南》。

一、配置体系总览

Bar Assistant 是 Laravel 应用，配置分三层：

  1. 环境变量 .env（官方模板 .env.example）——所有可调项的入口，容器部署时直接以环境变量注入；
  2. config/*.php——Laravel 配置定义层，读取 env；
  3. 配置缓存——生产镜像默认已缓存（php artisan about 实测 Config .... CACHED），改 env 后需 php artisan config:clear 或重启服务进程才生效。

查看生效值的正确姿势（实测）：

php artisan config:show bar-assistant

三个真实报错（照抄，避坑用）：

  Not enough arguments (missing: "config").

（config:show 必须带配置名）

  Too many arguments to "config:show" command, expected arguments "config".

（一条命令只能查一个配置文件，config:show database redis 不行）

   ERROR  Configuration file or key redis does not exist.

（v6 的 Redis 连接定义在 database 配置里，应查 config:show database）

二、官方 .env.example 全量清单（2026-11-01 实查仓库）

APP_NAME="Bar Assistant"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=

# Database
DB_CONNECTION=sqlite
DB_FOREIGN_KEYS=true

# Drivers
LOG_CHANNEL=stderr
LOG_LEVEL=warning
CACHE_DRIVER=redis
FILESYSTEM_DISK=local
QUEUE_CONNECTION=sync
SESSION_DRIVER=redis
SESSION_LIFETIME=120

# Redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Search
SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=
MEILISEARCH_KEY=

# Mail
# MAIL_MAILER= / MAIL_HOST= / MAIL_PORT= / MAIL_USERNAME= / MAIL_PASSWORD=
# MAIL_ENCRYPTION= / MAIL_RESET_URL= / MAIL_CONFIRM_URL=
MAIL_FROM_ADDRESS="no-reply@barassistant.app"
MAIL_FROM_NAME="Bar Assistant"
MAIL_REQUIRE_CONFIRMATION=false

# Billing
# ENABLE_BILLING= / BILLING_PRODUCT_PRICES= / MAX_USER_BARS= / CASHIER_CURRENCY=
# PADDLE_SANDBOX= / PADDLE_VENDOR_ID= / PADDLE_VENDOR_AUTH_CODE= / PADDLE_AUTH_CODE=

README 另列高频项：ALLOW_REGISTRATION、ENABLE_PASSWORD_LOGIN、METRICS_ENABLED、METRICS_ALLOWED_IPS、SCRAPING_HTTP_PROXY、SCRAPING_CLIENT_CERT、GEN_AI_PROVIDER、GEN_AI_MODEL、GEN_AI_IMAGE_PROVIDER、GEN_AI_IMAGE_MODEL。

三、应用核心（APP_*）

变量默认说明
APP_NAMEBar Assistant邮件与页面标题用名
APP_ENVproduction生产固定 production
APP_KEY空等价其他栈的 SECRET_KEY：加密会话/令牌的根密钥，首次部署必须生成（php artisan key:generate），官方镜像安装脚本自动完成；丢失后已签发令牌全部失效
APP_DEBUGfalse生产保持 false
APP_URL空API 对外可达地址；compose 里注入的是浏览器可达地址（本例 http://localhost:8135），php artisan about 实测回显 URL .... localhost:8135

四、数据库（DB_*）——默认 SQLite，非 MongoDB

常见误区把 Bar Assistant 写成 MongoDB 栈；实测 config:show database 默认连接是 SQLite，单文件库：

  database ...................................................................
  default ............................................................. sqlite
  connections ⇁ sqlite ⇁ driver ....................................... sqlite
  connections ⇁ sqlite ⇁ database .. storage/bar-assistant/database.ba3.sqlite
  connections ⇁ sqlite ⇁ journal_mode .................................... wal
  connections ⇁ sqlite ⇁ foreign_key_constraints ........................ true
  connections ⇁ sqlite ⇁ busy_timeout ................................... 5000
  connections ⇁ sqlite ⇁ synchronous .................................. NORMAL

要点：

  • 库文件 storage/bar-assistant/database.ba3.sqlite 位于持久卷内（compose 篇的 bar_data 卷），备份卷即备份库；
  • journal_mode=wal + busy_timeout=5000：并发写友好；DB_FOREIGN_KEYS=true 对应 foreign_key_constraints；
  • 官方同时预置 mysql/mariadb/pgsql 连接段（实测 config:show database 可见，默认 host 127.0.0.1、utf8mb4、pgsql 默认 sslmode=prefer）。多用户高并发或 NAS 上想统一 DB 服务时设 DB_CONNECTION=pgsql + DB_HOST/DB_PORT/DB_DATABASE/DB_USERNAME/DB_PASSWORD 即可切换，无需改代码。

五、Redis（缓存/会话/队列/指标共用）

config:show database 的 redis 段实测（注意：Redis 定义挂在 database 配置下）：

  redis ⇁ client .................................................... phpredis
  redis ⇁ options ⇁ prefix ........................... bar_assistant_database_
  redis ⇁ default ⇁ host ............................................... redis
  redis ⇁ default ⇁ port ................................................ 6379
  redis ⇁ default ⇁ database ............................................... 0
  redis ⇁ cache ⇁ database ................................................. 1
  redis ⇁ horizon ⇁ options ⇁ prefix .................. bar_assistant_horizon:
变量默认说明
REDIS_HOSTredis主机名/地址；compose 内用服务名 redis
REDIS_PORT6379
REDIS_PASSWORDnull空密码时留 null
CACHE_DRIVERredis可 file；about 实测生效值 redis
SESSION_DRIVERredis可 file；会话库 db 0，缓存库 db 1，key 前缀 bar_assistant_database_
SESSION_LIFETIME120分钟
QUEUE_CONNECTIONsync默认同步队列；sync-datapack、图片抓取等重任务如需后台化可换 redis 队列并起 php artisan horizon（about 实测 Broadcasting=null、Queue=sync）

六、搜索（SCOUT_* / MEILISEARCH_*）——非 Elasticsearch

全文检索用 Meilisearch（Laravel Scout 抽象层）。config:show scout 实测：

  scout ......................................................................
  driver .......................................................... meilisearch
  queue ................................................................. true
  chunk ⇁ searchable ..................................................... 500
  meilisearch ⇁ host ................................. http://meilisearch:7700
  meilisearch ⇁ key ...................... masterKey-make-it-long-for-security
变量说明
SCOUT_DRIVER默认 meilisearch；官方同时支持 typesense（config:show 可见完整 typesense 节点段，默认端口 8108）与 algolia
MEILISEARCH_HOST服务内部地址（如 http://meilisearch:7700），与前端用的浏览器可达地址区分
MEILISEARCH_KEYAPI key；直填 master key 可用但不安全，官方提供 php artisan bar:setup-meilisearch 生成受限 scoped key 并自动回写 ENV（CLI 篇详述）

索引结构实测（scout 配置内建，sync-datapack 后自动创建 cocktails/ingredients 两索引）：Cocktail 可过滤 tags/bar_id、可排序 name/date、可搜 name/tags/description/date/short_ingredients；Ingredient 可过滤 category/origin/bar_id。scout.queue=true 表示索引更新走队列异步。

七、吧台业务开关（bar-assistant 配置域）

php artisan config:show bar-assistant 实测全量（本例部署值）：

  bar-assistant ..............................................................
  version ............................................................ v6.10.1
  allow_registration .................................................... true
  max_default_bars ......................................................... 1
  max_premium_bars ........................................................ 10
  mail_require_confirmation ............................................ false
  mail_reset_url ........................................................ null
  mail_confirm_url ...................................................... null
  enable_billing ....................................................... false
  prices ⇁ 0 .................................................................
  metrics ⇁ enabled ..................................................... true
  metrics ⇁ allowed_ips ⇁ 0 ....................................... 10.89.60.1
  enable_feeds ......................................................... false
  enable_password_login ................................................. true
  scraping_client ⇁ proxy ............................................... null
  scraping_client ⇁ cert ................................................ null
  ai ⇁ provider ......................................................... null
  ai ⇁ model ............................................................ null
  ai ⇁ provider_image ................................................... null
  ai ⇁ model_image ...................................................... null
  ai ⇁ timeout ........................................................... 120
  ai ⇁ image_supports_reference ......................................... true

逐项：

ENV 变量config 键默认说明
ALLOW_REGISTRATIONallow_registrationtrue关掉可禁自助注册（配合先建管理员）；公网裸奔实例建议 false
—max_default_bars / max_premium_bars1 / 10免费/付费用户可建吧台数（自托管通常用不到）
MAIL_REQUIRE_CONFIRMATIONmail_require_confirmationfalsetrue 时新注册须邮箱验证后才能登录
MAIL_RESET_URL / MAIL_CONFIRM_URL同名null邮件里链接的前端地址，部署了 Salt Rim 应指向前端 URL
ENABLE_PASSWORD_LOGINenable_password_logintrue上 SSO 后可关密码登录
—enable_feedsfalseRSS 输出开关
METRICS_ENABLEDmetrics.enabledfalse开 /api/metrics Prometheus 端点
METRICS_ALLOWED_IPSmetrics.allowed_ips空逗号分隔 IP 白名单；只按请求源 IP 精确匹配，本机经 IPv6 回环访问会被拒（日志 Denied IP address ::1 metrics endpoint access 实录见部署篇）

八、配方抓取与图片（SCRAPING_*）

按 URL 导入第三方配方站与抓取配图的 HTTP 客户端配置：

变量说明
SCRAPING_HTTP_PROXY抓取走代理（如 http://192.168.1.62:7897），服务器出网受限时关键
SCRAPING_CLIENT_CERTmTLS 客户端证书路径

实测 config:show bar-assistant 中对应 scraping_client ⇁ proxy/cert，默认 null。抓来的图片落 storage/bar-assistant 卷的 uploads 目录（about 实测 public/uploads LINKED）。AI 生成图片另见下节。

九、AI 扩展（GEN_AI_*）

四个变量驱动 Laravel AI SDK（实测 config:show ai 可见 openai/anthropic/ollama/gemini/groq/openai-compatible 等 17 家 provider 全预置，各 key 默认 null）：

变量说明
GEN_AI_PROVIDER文本 provider 标识（openai、anthropic、ollama…），留空即禁用（实测 server/version 返回 is_ai_enabled:false）
GEN_AI_MODEL指定模型；openai-compatible 类 provider 必填
GEN_AI_IMAGE_PROVIDER / GEN_AI_IMAGE_MODEL配图生成（返回 is_ai_image_enabled）
—ai.timeout 默认 120 秒；ai.image_supports_reference 默认 true（参考图生图）

内网闭环玩法：GEN_AI_PROVIDER=ollama + 宿主 Ollama 服务，key 留空（实测 ollama 默认 url http://localhost:11434）。

十、价格、货币与计费（CASHIER_* / BILLING_*）

原料价格与鸡尾酒成本核算是产品功能（价格登记走 API，货币随用户设置）；.env 的计费段是给官方 SaaS 化收款用的：

变量说明
ENABLE_BILLING收款开关，自托管保持 false（实测 enable_billing=false）
CASHIER_CURRENCY货币代码（Laravel Cashier 标准项，如 eur/usd/cny）
BILLING_PRODUCT_PRICES / MAX_USER_BARS定价与吧台配额
PADDLE_*Paddle 收款通道参数，自托管无需

十一、邮件（MAIL_*）

SMTP 六件套（MAIL_MAILER/MAIL_HOST/MAIL_PORT/MAIL_USERNAME/MAIL_PASSWORD/MAIL_ENCRYPTION）+ MAIL_FROM_ADDRESS/MAIL_FROM_NAME。不配 MAILER 时 about 实测驱动仍显示 smtp 但发送会失败；配好后用 php artisan bar:test-email you@example.com 验证（CLI 篇）。

十二、日志（LOG_*）

变量默认说明
LOG_CHANNELstderr官方容器镜像推荐值：日志走标准错误，由日志驱动收集；实测 API 报错（如导出 500 的 TypeError ... ExportController.php:102）完整出现在 stderr 流
LOG_LEVELwarning排障期可临时 debug

十三、改配置的标准动作

# 1. 改 .env 或 compose environment 段
# 2. 清配置缓存（生产镜像默认 Config=CACHED）
php artisan config:clear
# 3. 重启应用（容器化即 restart 服务）
# 4. 复核生效值
php artisan config:show bar-assistant
php artisan about

十四、生产推荐基线

项建议
APP_KEY首次部署生成并离线备份
ALLOW_REGISTRATION公网实例 false；家庭多人用 true+MAIL_REQUIRE_CONFIRMATION=true
MEILI_MASTER_KEY≥32 位随机；正式环境跑 bar:setup-meilisearch 换 scoped key
METRICS_ALLOWED_IPS只写 Prometheus 抓取源真实 IP
DB单机 SQLite 足够；多实例/重并发切 pgsql
QUEUE_CONNECTION上 redis + horizon（图片抓取/AI 变重时）
SCOUT_DRIVER保留 meilisearch；无搜索需求可设 null 省一个服务（代价：前端搜索不可用）

十五、系列导航

  • 选型：《Bar Assistant 介绍与选型指南》
  • 部署：《Bar Assistant Docker Compose 部署指南》
  • 命令实操：《Bar Assistant 6.10.1 常用 CLI/API 命令详解》
Bar Assistant 6.10.1 配置参数详解 - Quzuo