Tiledesk 配置参数详解

一、配置体系总览

Tiledesk 的配置全部通过 环境变量 注入，不使用传统配置文件（YAML/JSON）。每个微服务独立读取自己的环境变量集合。

1.1 配置层级

┌──────────────────────────────────────────────────┐
│ 全局共享变量（所有服务通用）                       │
│ - MONGODB_URI / JWT_SECRET_KEY / LOG_LEVEL 等    │
├──────────────────────────────────────────────────┤
│ 服务专有变量（每个服务独立读取）                   │
│ - tiledesk-server / chatbot / chat21-server ... │
├──────────────────────────────────────────────────┤
│ 前端编译时变量（Angular environment.prod.ts）      │
│ - serverUrl / wsUrl / chatUrl                    │
└──────────────────────────────────────────────────┘

1.2 变量格式约定

• 布尔值：true / false（小写字符串）
• 端口号：纯数字字符串，如 "3000"
• URI：完整连接串，如 mongodb://user:pass@host:27017/dbname
• 密钥：任意字符串，生产环境必须替换默认值

1.3 默认值清单（官方 Compose 部署）

下表列出 Tiledesk Community Edition 部署时的默认凭据和密钥，生产部署必须全部替换：

二、全局共享变量

2.1 日志

2.2 MongoDB

所有涉及数据库的服务（server、chatbot、chat21-server、chat21-http、backend-llm）都需要 MongoDB 连接串。

⚠️ 两个数据库分离：tiledesk 存项目/坐席/会话/机器人配置，chat21 存实时消息/会话。源码安装时可共用一个 MongoDB 实例，通过数据库名区分。

2.3 Redis 缓存

2.4 RabbitMQ 消息队列

所有服务通过 AMQP/RabbitMQ 交换消息。关键连接串是 JWT 格式的 AMQP URL，包含预生成的凭据。

💡 AMQP URL 说明：Tiledesk 的 AMQP 连接串使用了 RabbitMQ JWT 认证插件，URL 格式为 amqp://ignored:<JWT_TOKEN>@host:5672。ignored 是占位用户名，真正的凭据在 JWT payload 里。源码安装时可以用标准 amqp://user:password@host:5672 格式（关闭 RabbitMQ JWT 插件），但必须确保所有服务的用户名密码一致。

RabbitMQ 基础凭据（broker 自身）：

2.5 JWT 与鉴权

⚠️ 密钥一致性规则：JWT_SECRET_KEY、CHAT21_JWT_SECRET、JWT_KEY 三个变量在生产环境中必须全部设置为同一个值，否则 server 和 chat21 系列的 JWT 无法互相验证。

2.6 外部访问地址

统一配置 Widget、Dashboard、WebSocket 端点对外暴露的地址。

影响范围：dashboard、webwidget、ionic、cds 等前端组件启动时会读取这些值，硬编码嵌入到编译产物中。

三、tiledesk-server 主后端配置

server 是 Tiledesk 的核心 API 服务，端口 3000。除了上文的全局变量外，专有配置如下：

3.1 Chat21 集成

3.2 AI / LLM 配置

3.3 RAG / 向量存储

3.4 Email 通知

3.5 多渠道集成

3.6 其他

四、chat21 实时消息组件

chat21 系列是 Tiledesk 的 MQTT 实时消息引擎，含三个独立服务。

4.1 chat21-server（MQTT Broker）

4.2 chat21-http-server（Chat HTTP API）

4.3 chat21-web-widget / chat21-ionic（前端）

前端组件在编译时读取以下环境变量，运行时通过浏览器加载。

五、AI / LLM 后端配置

5.1 tiledesk-chatbot（Bot 引擎）

5.2 backend-llm-train / backend-llm-qa（Python FastAPI）

两个实例共用同一份代码，通过 TILELLM_ROLE 区分职责。

六、Nginx 反代配置

统一入口 Nginx 承担路径路由和 WebSocket 升级。源码安装时需要手动配置（见 《Tiledesk Ubuntu 22.04 源码安装指南》 第六章）。关键 location 段：

⚠️ WebSocket 升级：Nginx 反代 WebSocket 时必须加 proxy_http_version 1.1 + proxy_set_header Upgrade $http_upgrade + proxy_set_header Connection "upgrade"，否则 MQTT over WS 无法握手。

七、FEATURES_TOKEN 功能开关

FEATURES_TOKEN 是一串以冒号分隔的开关码，前缀字母表示功能组类型：

当前 Community Edition 的 FEATURES_TOKEN 值为：

PAY:F-ANA:T-ACT:T-TRI:T-GRO:T-DEP:T-OPH:T-MTL:T-CAR:T-PSA:F-MTT:T-SUP:T-LBS:T-APP:T-DEV:F-NOT:T-IPS:F-ETK:F-RAS:F-PPB:F-PET:F-MTS:F-TIL:T-DGF:T-NAT:T-HPB:F-TOW:F-KNB:T-GPT:T-BAN:F-AST:F-MON:T-CNT:F-AUT:F-WUN:F-INT:T-DPA:T

💡 Community 版已通过 FEATURES_TOKEN 开启了几乎所有 T- 核心功能位（约 30 个），但 F- 付费功能（F-ANA 高级分析、F-MTT 模板等）仍需企业版 License 才能生效。License Key 通过 LICENSE_KEY 环境变量注入 server。

八、Qdrant 向量存储

Qdrant 是独立部署的开源向量数据库，不需要额外配置变量——默认即可工作。可选配置：

Qdrant 的 collection 会由 tiledesk-server 在首次创建知识库时自动建立，不需要手工创建。

九、配置调优建议

9.1 内存调优

Node.js 服务默认堆内存约 200-300MB，可通过 NODE_OPTIONS 调整：

# systemd 服务中增加环境变量
Environment=NODE_OPTIONS="--max-old-space-size=512"

9.2 RabbitMQ 调优

# /etc/rabbitmq/rabbitmq.conf
default_vhost = /
default_user = rabbitmq
default_pass = <强密码>
loopback_users = none

# MQTT 插件配置
mqtt.tcp_listener.port = 1883

9.3 MongoDB 调优

生产环境建议在 MongoDB 开启 WiredTiger 压缩和合理的连接池：

// mongosh 中设置
db.adminCommand({setParameter: 1, maxInternalLoginCacheSize: 100})

9.4 Redis 调优

# /etc/redis/redis.conf
maxmemory 1gb
maxmemory-policy allkeys-lru
save 900 1
save 300 10

十、配置完整性检查清单

部署完成后执行以下检查，确保所有关键变量已正确配置：

# 1. 所有 JWT 密钥必须相同
echo "JWT一致性检查:"
grep JWT /opt/tiledesk/backend/*/.env 2>/dev/null

# 2. RabbitMQ 连接串必须所有服务一致
echo "AMQP一致性检查:"
grep -r AMQP_MANAGER_URL\|RABBITMQ_URI /opt/tiledesk/backend/*/.env 2>/dev/null

# 3. 外部地址
echo "外部地址配置:"
grep EXTERNAL_BASE_URL /opt/tiledesk/backend/server/.env 2>/dev/null

# 4. GPTKEY 是否已替换
echo "GPTKEY检查:"
grep -r GPTKEY /opt/tiledesk/backend/*/.env | grep CHANGEIT && \
  echo "⚠️ 警告: GPTKEY 仍为 CHANGEIT，AI 功能不可用" || \
  echo "✅ GPTKEY 已配置"

# 5. 默认管理员密码（需 Dashboard 内修改）
echo "默认管理员: admin@tiledesk.com / superadmin"
echo "⚠️ 请首次登录后立即修改！"