Libredesk v2.9.0 配置参数详解

目标：逐项讲解 Libredesk v2.9.0 的 config.toml 配置参数——查看与修改方式、全部参数段总览、核心参数分类详解（默认值 + 改动影响）、生产环境推荐模板与常见问题。全文基于官方 config.sample.toml（v2.9.0）逐段解读，并在 Ubuntu 22.04 + Docker Compose 实测环境验证参数修改与生效方式（log_level 调整实测通过）。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Libredesk：v2.9.0（实测 docker exec libredesk_app ./libredesk --version 回显 v2.9.0 (5668a2a2 2026-10-22T11:43:42Z, linux/amd64)）
依赖：PostgreSQL 17（postgres:17-alpine）、Redis 7（redis:7-alpine）
部署形态：Docker Compose 三服务（app/db/redis），配置文件挂载于 /libredesk/config.toml（宿主机 config.toml）
参数基线：官方 config.sample.toml（仓库 main 分支，2026-10-24 获取）
实测验证：[app].log_level 由 debug 改为 info 后重启，日志中 level=debug 行数由有到 0（详见 3.3 节）

二、前置条件

阅读与操作本文前需要：

已按《Libredesk Docker Compose 部署指南》部署完成一套可运行的 Libredesk（二进制部署同样适用，配置文件路径不同而已）；
知道配置文件位置：Compose 部署为宿主机 ./config.toml（挂载到容器 /libredesk/config.toml）；二进制部署默认工作目录下 config.toml（可用 --config 指定路径）；
理解 TOML 基本语法：[section] 表头 + key = value，字符串用双引号，时长值如 "5m"、"60s"。

三、参数查看与修改方式

3.1 查看当前配置

Libredesk 没有导出配置的 CLI 子命令，查看方式有三种：

直接读配置文件（最可靠）：Compose 部署时读宿主机 config.toml；启动日志第一段 reading config file: /libredesk/config.toml 可确认应用实际加载的路径（实测回显见 3.3）；
管理界面：登录后 Admin → Settings 可查看/修改部分运行时设置（这类设置存数据库，与 config.toml 分离）；
源码核对：v2.9.0 源码 config.sample.toml 是全部参数的权威清单，每项带注释。

3.2 修改方式：配置文件 vs 环境变量

两种方式任选或混用：

方式 A：改 config.toml（推荐，改动可见可审计），改完重启应用生效：

# Compose 部署：改宿主机 config.toml 后重启应用服务
docker compose restart app

方式 B：环境变量覆盖（官方安装文档约定，2026-10-24 查询）：全部环境变量用 LIBREDESK_ 前缀，嵌套键用双下划线 __ 连接；要完全脱离配置文件时传 --config=""：

TOML 配置键	等价环境变量
`app.encryption_key = "..."`	`LIBREDESK_APP__ENCRYPTION_KEY=...`
`upload.fs.upload_path = "uploads"`	`LIBREDESK_UPLOAD__FS__UPLOAD_PATH=uploads`
`db.host = "localhost"`	`LIBREDESK_DB__HOST=localhost`

💡 说明：环境变量优先级高于配置文件（url 类参数除外，见 5.4 节 Redis 段），适合把密码类敏感值留在编排层注入，配置文件入库版本管理。

3.3 修改生效实测（log_level 由 debug 改 info）

第一步：编辑 config.toml，把 [app] 段的 log_level = "debug" 改为 log_level = "info"；

第二步：重启应用：

docker compose restart app

第三步：验证生效——重启后日志中不再出现 level=debug 行（改前 debug 级别会输出 invalidating agent cache 之类调试行）：

# 统计重启后日志中 debug 行数
docker logs libredesk_app --since 3m 2>&1 | grep -c 'level=debug'

# 确认应用读到配置并正常启动（日志节选）
docker logs libredesk_app --since 3m 2>&1 | tail -4

2026/10/23 20:25:14 reading config file: /libredesk/config.toml
2026/10/23 20:25:14 loading i18n language file: en-US
timestamp=2026-10-23T20:25:14.341Z level=info message="loaded embeddings into memory" caller=/home/runner/work/libredesk/libredesk/internal/ai/embedding.go:283 sc=ai count=0 dimensions=0 vector_bytes=0 text_bytes=0 approx_mb=0
2026/10/23 20:25:14 Server started at 0.0.0.0:9000

同时服务回到可用状态：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8153/

四、参数总览

v2.9.0 config.sample.toml 全部参数段及职责一览（参数名后为官方默认值）：

参数段	职责	关键参数（默认值）
`[app]`	应用全局	`log_level`（debug）、`env`（dev）、`check_updates`（true）、`encryption_key`（必填）、`static_dir`（注释态）
`[app.server]`	HTTP 服务	`address`（0.0.0.0:9000）、`socket`（空）、`disable_secure_cookies`（false）、`session_lifetime`（9h）、`read_timeout`/`write_timeout`（60s）、`max_body_size`（104857600）、`read_buffer_size`（65536）、`keepalive_timeout`（10s）
`[auth]`	认证	`local_login_enabled`（true）
`[upload]`	附件存储	`provider`（fs）
`[upload.fs]`	本地存储	`upload_path`（uploads）、`expiry`（1h）
`[upload.s3]`	S3 存储	`url`（空）、`access_key`/`secret_key`（空）、`region`、`bucket`、`bucket_path`（空）、`expiry`（30m）
`[db]`	PostgreSQL	`host`（db）、`port`（5432）、`user`/`password`/`database`（libredesk）、`ssl_mode`（disable）、`max_open`（30）、`max_idle`（30）、`max_lifetime`（300s）
`[redis]`	Redis	`address`（redis:6379）、`user`/`password`（空）、`db`（0）、`url`（注释态，优先级最高）
`[message]`	消息队列	`outgoing_queue_workers`（10）、`incoming_queue_workers`（10）、`message_outgoing_scan_interval`（50ms）、`incoming_queue_size`/`outgoing_queue_size`（5000）
`[notification]`	通知	`concurrency`（2）、`queue_size`（2000）
`[automation]`	自动化规则	`worker_count`（10）、`time_trigger_lookback_days`（90）
`[ai_agent]`	AI 助手	`worker_count`（10）、`queue_size`（1000）、`max_steps`（6）、`max_history_messages`（30）
`[autoassigner]`	自动分派	`autoassign_interval`（5m）
`[webhook]`	Webhook 派发	`workers`（5）、`queue_size`（10000）、`timeout`（15s）
`[ssrf]`	出站 SSRF 防护	`enabled`（false）、`allowed_cidrs`（[]）
`[conversation]`	会话行为	`unsnooze_interval`（5m）、`draft_retention_duration`（360h）、`continuity_scan_interval`（5m）
`[sla]`	SLA 评估	`evaluation_interval`（5m）
`[rate_limit.widget]`	聊天组件限流	`enabled`（true）、`requests_per_minute`（100）
`[rate_limit.auth]`	认证端点限流	`enabled`（true）、`requests_per_minute`（30）
`[rate_limit.public]`	公开页限流	`enabled`（true）、`requests_per_minute`（100）
`[rate_limit.media]`	媒体下载限流	`enabled`（true）、`requests_per_minute`（300）

💡 技术拓展：Libredesk 的任务队列基于 Redis Streams 实现 at-least-once 派发（源码 internal/streamqueue 注释明确 "durable, at-least-once work queue backed by Redis Streams. Handlers MUST be idempotent"）。同类队列选型对比——

队列形态代表特点适用
内存队列 Go channel 零依赖，重启丢任务可丢的短任务
Redis Streams Libredesk、各类 Go 服务轻量、可持久、at-least-once 中小规模可靠队列
独立消息中间件 Kafka/RabbitMQ 强吞吐/路由能力大规模异构系统

Libredesk 选 Redis Streams，与其"Redis 必装"的架构一致，不额外引入中间件。

队列形态	代表	特点	适用
内存队列	Go channel	零依赖，重启丢任务	可丢的短任务
Redis Streams	Libredesk、各类 Go 服务	轻量、可持久、at-least-once	中小规模可靠队列
独立消息中间件	Kafka/RabbitMQ	强吞吐/路由能力	大规模异构系统

五、核心参数分类详解

5.1 `[app]` 应用全局段

[app]
log_level = "info"        # 日志级别：info, debug, warn, error, fatal
env = "prod"              # 环境：dev/prod，dev 会在终端输出彩色日志
check_updates = true      # 启动时检查更新，有新版在管理后台横幅提示
encryption_key = "37c754db5e59cd92c374e108e1763f94"  # 32 字符加密密钥

log_level：生产建议 info；排障时临时开 debug（官方 sample 默认 debug，实测 debug 级别会输出代理缓存失效等高频调试行，量大）；
env：官方示例为 dev，生产改 prod（差异是终端彩色日志，功能无影响）；
check_updates：内网环境可关 false，减少出站请求；
encryption_key：必须恰好 32 字符，用 openssl rand -hex 16 生成；首次启动前设置后永不更换——它加密落库的收件箱密码等敏感信息，更换后旧密文全部无法解密（官方文档原文强调）；
static_dir（默认注释）：自定义前端静态文件目录，目录结构需镜像内置 static/，只替换提供的文件。

5.2 `[app.server]` HTTP 服务段

[app.server]
address = "0.0.0.0:9000"          # 监听地址
socket = ""                        # Unix socket 路径，非空则替代 TCP
disable_secure_cookies = false     # 关闭安全 Cookie（生产勿动）
session_lifetime = "9h"            # 会话有效期
read_timeout = "60s"               # 读超时
write_timeout = "60s"              # 写超时
max_body_size = 104857600          # 请求体上限 100MB
read_buffer_size = 65536           # 读缓冲（同时是请求头上限）
keepalive_timeout = "10s"          # Keep-Alive 时长

address：容器内部监听 9000 不必改，对外暴露靠端口映射或反代；
max_body_size：默认 100MB，官方注释提醒——有反向代理时（如 Nginx）需同步调大代理的 client_max_body_size，否则大附件先被代理拒绝；
session_lifetime：登录态时长，按安全策略调整；
disable_secure_cookies：仅 HTTP 明文调试环境才考虑 true，生产走 HTTPS 保持 false。

5.3 `[auth]` 认证段

[auth]
local_login_enabled = true   # 允许邮箱+密码登录

配置 OIDC 单点登录（Google/Microsoft 等）并启用后可关掉本地密码登录；官方注释同时说明一个保护机制：没有任何已启用 OIDC Provider 时，Libredesk 会自动保持本地登录可用，防止锁死——若启用的 Provider 故障导致无法登录，把该项改回 true 即可恢复。

5.4 `[db]` 与 `[redis]` 连接段

[db]
host = "db"            # Compose 内服务名；同机二进制部署写 localhost
port = 5432
user = "libredesk"
password = "libredesk"
database = "libredesk"
ssl_mode = "disable"   # 库与应用同内网时可 disable；跨网启用 TLS
max_open = 30          # 最大打开连接数
max_idle = 30          # 最大空闲连接数
max_lifetime = "300s"  # 连接最长复用时间

[redis]
# url = "redis://user:password@host:port/db"   # 配置后覆盖下面全部项
address = "redis:6379"
user = ""
password = ""
db = 0

[db] 各项必须与部署 PostgreSQL 时的 POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB 三变量一致（见部署篇 4.3 节），不一致时应用起不来；
max_open/max_idle：默认 30/30，中小团队够用；坐席多、报表重时可上调（需同时核对 PostgreSQL 的 max_connections）；
[redis].url：官方注释明确 url 参数配置后覆盖其余 redis 配置项，带密码的 Redis 用它最省事（redis://:密码@redis:6379/0）。

5.5 `[upload]` 附件存储段

[upload]
provider = "fs"        # fs=本地文件系统，s3=S3 兼容对象存储

[upload.fs]
upload_path = 'uploads'   # 相对应用工作目录
expiry = "1h"             # 附件签名 URL 有效期

[upload.s3]
url = ""               # 非 AWS 的 S3 兼容端点（如 MinIO）才填
access_key = ""        # 留空则用 IAM 角色
secret_key = ""
region = "ap-south-1"
bucket = "bucket-name"
bucket_path = ""       # 桶内前缀路径
expiry = "30m"         # S3 签名 URL 有效期

fs 与 s3 两选一：单机部署用 fs（配合部署篇的 ./uploads 挂载即可）；多副本/云上部署切 s3（MinIO 等 S3 兼容存储填 url，AWS 原生留空走默认端点）。切换 provider 后新附件写新存储，旧附件仍在原存储，需自行迁移。

5.6 `[message]` 消息队列段

[message]
outgoing_queue_workers = 10        # 出站消息 worker 数
incoming_queue_workers = 10        # 入站消息 worker 数
message_outgoing_scan_interval = "50ms"   # 出站扫描间隔
incoming_queue_size = 5000         # 入站队列上限
outgoing_queue_size = 5000         # 出站队列上限

邮件/聊天消息的进出站吞吐参数。官方注释：message_outgoing_scan_interval 保持小值可让消息尽快发出；并发消息量大（批量群发、大流量聊天）时上调 worker 数与队列上限。

5.7 `[automation]` / `[autoassigner]` / `[sla]` / `[conversation]` 业务节拍段

[automation]
worker_count = 10                   # 自动化规则 worker 数
time_trigger_lookback_days = 90     # 时间触发规则回看天数（≤0 用 90 天）

[autoassigner]
autoassign_interval = "5m"          # 自动分派扫描间隔

[conversation]
unsnooze_interval = "5m"            # Snooze 到期检查间隔
draft_retention_duration = "360h"   # 草稿保留时长（15 天）
continuity_scan_interval = "5m"     # 离线会话连续性邮件扫描间隔

[sla]
evaluation_interval = "5m"          # SLA 合规评估间隔

这一组是"后台节拍"：调小间隔响应更快但增加数据库扫描频率，默认 5 分钟对客服场景已足够灵敏；draft_retention_duration 控制草稿在库内保留多久后清理（官方示例 360 小时，可改 "48h" 等更短值省空间）。

5.8 `[ai_agent]` AI 助手段

[ai_agent]
worker_count = 10              # 自主应答 worker 数
queue_size = 1000              # 应答任务队列上限
max_steps = 6                  # 单次回复最大工具调用步数（1-20）
max_history_messages = 30      # 送入模型的会话历史条数（5-100）

控制 AI 助手自动应答的并发与上下文窗口：max_steps 限制 AI 单次回复可执行的工具调用次数（防失控循环），max_history_messages 限制携带的聊天历史条数（直接关联 token 消耗与成本）。

5.9 `[webhook]` 与 `[ssrf]` 段

[webhook]
workers = 5          # Webhook 派发 worker 数
queue_size = 10000   # 派发队列上限
timeout = "15s"      # 单次 HTTP 请求超时

[ssrf]
enabled = false      # 屏蔽出站请求到私网/回环/云元数据 IP
allowed_cidrs = []   # 启用后放行的内网 CIDR 白名单

[webhook]：Webhook 订阅多、接收方慢时上调 workers；timeout 需大于最慢接收方的响应时间；
[ssrf]：官方注释给出明确口径——自托管单租户部署保持 false（内网 Webhook、内网 OIDC、内网模型端点是正当需求）；多租户/托管形态设 true，防止租户借 Webhook 探测内网，必要时用 allowed_cidrs 放行已知内网目标（如 ["10.0.0.0/8"]）。

5.10 `[rate_limit.*]` 四组限流段

[rate_limit.widget]
enabled = true
requests_per_minute = 100   # 聊天组件 API

[rate_limit.auth]
enabled = true
requests_per_minute = 30    # 登录/改密等认证端点

[rate_limit.public]
enabled = true
requests_per_minute = 100   # 帮助中心、CSAT、robots.txt/sitemap

[rate_limit.media]
enabled = true
requests_per_minute = 300   # 附件/头像等公开媒体下载

按客户端 IP 限流（依赖反代正确传 X-Client-IP 头，见部署篇 FAQ Q2）。enabled = false 整组关闭；被限流场景（大促聊天高峰、帮助中心被爬）按组上调 requests_per_minute 即可，无需重启数据库层。

六、生产配置模板

适用场景：8GB 内存 / 4 vCPU 云主机，50 坐席以内的客服团队（含 PostgreSQL/Redis 同机 Compose 部署）。相对官方 sample 的改动点已注释标出：

[app]
log_level = "info"              # 生产收日志量，排障时临时开 debug
env = "prod"                    # 生产环境
check_updates = true
encryption_key = "<openssl rand -hex 16 生成的 32 字符>"   # 首启前设置，永不再改

[app.server]
address = "0.0.0.0:9000"
socket = ""
disable_secure_cookies = false  # 生产走 HTTPS，保持 false
session_lifetime = "9h"
read_timeout = "60s"
write_timeout = "60s"
max_body_size = 104857600       # 反代同步 client_max_body_size
read_buffer_size = 65536
keepalive_timeout = "10s"

[auth]
local_login_enabled = true      # 配好 OIDC 前保持 true

[upload]
provider = "fs"                 # 单机部署用本地盘 + 每日备份 uploads 目录

[upload.fs]
upload_path = 'uploads'
expiry = "1h"

[db]
host = "db"
port = 5432
user = "libredesk"
password = "<与 .env 的 POSTGRES_PASSWORD 一致>"
database = "libredesk"
ssl_mode = "disable"
max_open = 30
max_idle = 30
max_lifetime = "300s"

[redis]
address = "redis:6379"
user = ""
password = ""
db = 0

[message]
outgoing_queue_workers = 10
incoming_queue_workers = 10
message_outgoing_scan_interval = "50ms"
incoming_queue_size = 5000
outgoing_queue_size = 5000

[notification]
concurrency = 2
queue_size = 2000

[automation]
worker_count = 10
time_trigger_lookback_days = 90

[ai_agent]
worker_count = 10
queue_size = 1000
max_steps = 6
max_history_messages = 30

[autoassigner]
autoassign_interval = "5m"

[webhook]
workers = 5
queue_size = 10000
timeout = "15s"

[ssrf]
enabled = false                 # 单租户自托管保持 false
allowed_cidrs = []

[conversation]
unsnooze_interval = "5m"
draft_retention_duration = "360h"
continuity_scan_interval = "5m"

[sla]
evaluation_interval = "5m"

[rate_limit.widget]
enabled = true
requests_per_minute = 100

[rate_limit.auth]
enabled = true
requests_per_minute = 30

[rate_limit.public]
enabled = true
requests_per_minute = 100

[rate_limit.media]
enabled = true
requests_per_minute = 300

要点：该模板与官方 config.sample.toml 唯二必改项是 encryption_key（换随机值）与 env（dev→prod），其余保持默认即可稳定运行；扩容方向按第五节各段说明逐项上调。

七、常见问题

Q1：改了 config.toml 不生效？ 三个检查点：① 改的是挂载进容器的那个文件（Compose 部署看 volumes: ./config.toml:/libredesk/config.toml）；② 改完执行了 docker compose restart app（配置只在进程启动时读取一次，日志 reading config file 行之后不再重读）；③ 环境变量是否覆盖了同名键（LIBREDESK_* 前缀优先级更高）。

Q2：encryption_key 忘了改就直接启动了，还能补救吗？ 首次启动即用默认值建库的话，库内密文用该密钥加密。此时库内尚无重要凭据，最干净的做法是清库重来：停应用 → 删除数据卷重建 → 设置好 key 再 up（命令见部署篇卸载一节）。已积累生产数据后绝不能改 key，否则收件箱密码等密文无法解密。

Q3：[db] 连接失败 pq: password authentication failed？ config.toml 与部署数据库时 .env 的三要素（user/password/database）不一致。两边改成同一套值；若 PostgreSQL 数据卷已用旧凭据初始化，改 config.toml 侧去匹配库，而不是改 .env（环境变量只在空数据卷首次初始化时生效）。

Q4：日志级别调到 info 后还想看某类调试信息？ log_level 是全局开关，无按模块分级；排障期间临时切 debug 并重启，看完切回 info。debug 会输出代理缓存失效、WebSocket 连接等高频行，注意日志盘空间。

Q5：Nginx 反代后限流失效/审计 IP 全是反代 IP？ 反代必须设置 proxy_set_header X-Client-IP $remote_addr;——Libredesk 从该头取真实客户端 IP 用于限流与审计（官方文档警告项），缺了它所有请求都视为来自代理。

Q6：想用 MinIO 存附件怎么配？ [upload] 段 provider = "s3"，[upload.s3] 填 url（MinIO 端点，如 http://minio:9000）、access_key/secret_key、region（任意合法值）、bucket。改完 docker compose restart app，之后新上传附件直接进对象存储。

八、参考链接

官方配置样例（参数权威来源）：https://github.com/abhinavxd/libredesk/blob/main/config.sample.toml
官方安装文档（环境变量与命令行参数章节）：https://docs.libredesk.io/getting-started/installation
本专栏相关篇目：认知与选型见《Libredesk 介绍与选型指南》；部署步骤见《Libredesk Docker Compose 部署指南》；API 集成见《Libredesk v2.9.0 API 使用详解》

Libredesk v2.9.0 配置参数详解

Libredesk v2.9.0 配置参数详解

一、环境信息

二、前置条件

三、参数查看与修改方式

3.1 查看当前配置

3.2 修改方式：配置文件 vs 环境变量

3.3 修改生效实测（log_level 由 debug 改 info）

四、参数总览

五、核心参数分类详解

5.1 [app] 应用全局段

5.2 [app.server] HTTP 服务段

5.3 [auth] 认证段

5.4 [db] 与 [redis] 连接段

5.5 [upload] 附件存储段

5.6 [message] 消息队列段

5.7 [automation] / [autoassigner] / [sla] / [conversation] 业务节拍段

5.8 [ai_agent] AI 助手段

5.9 [webhook] 与 [ssrf] 段

5.10 [rate_limit.*] 四组限流段

六、生产配置模板

七、常见问题

八、参考链接

5.1 `[app]` 应用全局段

5.2 `[app.server]` HTTP 服务段

5.3 `[auth]` 认证段

5.4 `[db]` 与 `[redis]` 连接段

5.5 `[upload]` 附件存储段

5.6 `[message]` 消息队列段

5.7 `[automation]` / `[autoassigner]` / `[sla]` / `[conversation]` 业务节拍段

5.8 `[ai_agent]` AI 助手段

5.9 `[webhook]` 与 `[ssrf]` 段

5.10 `[rate_limit.*]` 四组限流段