Tiledesk Docker Compose 部署指南

一、前置条件

1.1 环境要求

组件	最低版本	推荐版本
Docker	20.10+	24.0+
Docker Compose	v2.0+	v2.24+
操作系统	Linux（Ubuntu 20.04/22.04/24.04、Debian 11/12、CentOS 7+）	Ubuntu 22.04 LTS
CPU	4 核	8 核
内存	8 GB	16 GB
磁盘	50 GB SSD	200 GB SSD

1.2 端口占用

Tiledesk 默认部署会占用以下端口，开始前请确认这些端口未被其他服务使用：

# 在目标服务器上检查端口占用
sudo ss -ltnp | grep -E ':(3000|4200|4500|4502|8004|8081|8082|1883|3007|3008|5672|6333|6379|15672|15675|27017)\b'

若上述命令无输出，说明所有端口空闲，可以继续。如有冲突，需调整或停掉冲突服务。

1.3 创建部署目录

# 专用部署目录
sudo mkdir -p /opt/tiledesk
sudo chown $USER:$USER /opt/tiledesk
cd /opt/tiledesk

二、下载 Compose 文件

从 Tiledesk 官方 deployment 仓库拉取 Community Edition 的 compose 文件：

# 下载 docker-compose.yml（来自 master 分支 Community 版）
curl -fsSL https://raw.githubusercontent.com/Tiledesk/tiledesk-deployment/master/docker-compose/docker-compose.yml -o docker-compose.yml

# 验证文件完整性
wc -l docker-compose.yml

预期输出约 400 行。也可以直接 clone 整个仓库：

git clone --depth 1 https://github.com/Tiledesk/tiledesk-deployment.git tiledesk-deployment
cp tiledesk-deployment/docker-compose/docker-compose.yml ./

⚠️ 网络说明：若 GitHub 下载慢或超时，可通过代理访问：
curl -x http://192.168.1.62:7897 -fsSL https://raw.githubusercontent.com/Tiledesk/tiledesk-deployment/master/docker-compose/docker-compose.yml -o docker-compose.yml

三、配置 .env 文件

docker-compose.yml 使用了 ${VAR:-default} 变量替换语法，部分变量必须在 .env 文件中设置（否则 compose 会报未定义变量错误）。

3.1 创建 .env

在 compose 文件同级目录创建 .env：

cat > .env << 'EOF'
# ===== 外部访问地址 =====
# 本地测试保持默认即可
EXTERNAL_BASE_URL=http://localhost:8081
EXTERNAL_MQTT_BASE_URL=ws://localhost:8081

# ===== RabbitMQ 基础凭据（必须设，否则 compose 启动时会因变量为空报 warning） =====
RABBITMQ_ERLANG_COOKIE=tiledesk_rabbitmq_cookie_change_me_001
RABBITMQ_DEFAULT_USER=rabbitmq
RABBITMQ_DEFAULT_PASS=rabbitmq_pass_change_me_001
EOF

3.2 .env 关键变量说明

变量	必填	默认值	说明
`EXTERNAL_BASE_URL`	生产必填	`http://localhost:8081`	外部访问根地址，Widget 和 Dashboard 会嵌入此地址
`EXTERNAL_MQTT_BASE_URL`	生产必填	`ws://localhost:8081`	MQTT over WebSocket 地址，聊天实时推送
`RABBITMQ_ERLANG_COOKIE`	必填	无	RabbitMQ 集群 cookie，单节点部署填任意长随机串
`RABBITMQ_DEFAULT_USER`	必填	无	RabbitMQ 初始管理员用户名
`RABBITMQ_DEFAULT_PASS`	必填	无	RabbitMQ 初始管理员密码

3.3 生产环境进阶变量

在 .env 中可覆盖以下 compose 内硬编码的默认值（compose 环境变量语法 ${VAR} 会优先读取 .env 或 shell 环境变量）：

变量	默认值（compose 内）	覆盖说明
`GPTKEY`（多容器）	`CHANGEIT`	OpenAI API Key；不启用 AI Bot 可保持 CHANGEIT，启用后必须填入有效 key
`LICENSE_KEY`（server）	空	企业版 License；Community 版不需要
`EMAIL_*`（server）	空	SMTP 邮件通知配置（SMTP 服务器、端口、用户名、密码、发件地址）
`JWT_SECRET_KEY`（server）	`tokenKey`	JWT 签名密钥，生产必须改
`APPS_ACCESS_TOKEN_SECRET`（server）	`nodeauthsecret`	Apps 访问令牌密钥，生产必须改

四、启动部署

4.1 拉取镜像

第一次启动前先拉取全部镜像（14 个服务，总计约 5-6 GB）：

docker compose pull

⚠️ 网络说明：若 docker pull 慢或超时，需配置 Docker daemon 代理 /etc/docker/daemon.json 添加 "proxies": { "default": { "httpProxy": "http://192.168.1.62:7897", "httpsProxy": "http://192.168.1.62:7897" } }，然后 sudo systemctl restart docker。

4.2 启动全部服务

# 后台启动（推荐，否则前台会滚日志淹没终端）
docker compose up -d

# 指定 compose 项目名（避免与其他组件的 compose 冲突）
docker compose -p tiledesk-community up -d

预期输出：

[+] Running 14/14
 ✔ Network tiledesk_default        Created
 ✔ Volume "tiledesk-datadb"         Created
 ✔ Container mongo                 Started
 ✔ Container redis                 Started
 ✔ Container rabbitmq              Started
 ✔ Container chat21server          Started
 ✔ Container chat21httpserver      Started
 ✔ Container backend-llm-train     Started
 ✔ Container backend-llm-qa        Started
 ✔ Container chatbot               Started
 ✔ Container qdrant                Started
 ✔ Container server                Started
 ✔ Container dashboard             Started
 ✔ Container chat21-ionic          Started
 ✔ Container chat21-web-widget     Started
 ✔ Container cds                   Started
 ✔ Container tiledesk-docker-proxy Started

4.3 等待健康检查通过

server 容器配置了 healthcheck（curl -f http://localhost:3000/），初始等待期 40 秒。等待所有服务进入 healthy 或 running 状态：

# 持续观察状态变化
watch -n 5 'docker compose ps'

全部服务 STATE 显示 Up 或 healthy 即为启动完成。首次启动约 30-60 秒，MongoDB 初始化需要一些时间。

4.4 查看日志

# 全部服务日志（最后 100 行）
docker compose logs --tail=100

# 实时跟踪主后端日志
docker compose logs -f server

# 跟踪 AI Bot 日志
docker compose logs -f chatbot

4.5 Compose 项目名说明

默认 compose 项目名为部署目录名（如 /opt/tiledesk → 项目名 tiledesk）。若同时部署多个组件，务必显式指定 -p 参数：

# 推荐写法：项目名含组件名和版本
docker compose -p tiledesk-community-202610 up -d

项目名决定容器名前缀、网络名、数据卷名，不一致会导致 docker compose down 误删其他组件的网络/卷。

五、初始化登录

5.1 首次访问

浏览器打开统一入口地址：

URL	用途
`http://<服务器IP>:8081/`	管理后台 Dashboard
`http://<服务器IP>:8081/widget/`	嵌入 Web Widget 示例页
`http://<服务器IP>:8081/chat/`	完整聊天界面（Chat21 Ionic）
`http://<服务器IP>:8081/cds/`	Bot Flow 设计器（Design Studio）
`http://<服务器IP>:8081/api/`	REST API 根路径
`http://<服务器IP>:8081/mqws/`	RabbitMQ WebSocket

5.2 默认管理员凭据

💡 技术拓展：Community Edition 首次启动时 server 容器会自动初始化一个默认管理员账号。这个账号在所有自部署版本中都是硬编码的，登录后请立即修改密码。

字段	值
邮箱	`admin@tiledesk.com`
密码	`superadmin`

登录路径：Dashboard → 右上角头像 → Profile → 修改密码。

5.3 创建首个项目

登录后 Dashboard 会引导创建 Project（项目/租户）：

点击 New Project
填写项目名（如 "MySupport"）
选择时区
保存

每个 Project 是独立的租户，会话、Bot、知识库、坐席都在 Project 下隔离管理。

六、停止与重启

6.1 正常停止

# 停止全部容器（保留数据卷）
docker compose down

# 停止并删除数据卷（⚠️ 会清空 MongoDB 所有数据！）
docker compose down -v

6.2 重启

# 重启全部
docker compose restart

# 只重启某个服务（如改了 server 的环境变量）
docker compose restart server

6.3 只启动/停止单个服务

# 临时停掉 AI Bot（不想消耗 API 额度时）
docker compose stop chatbot backend-llm-train backend-llm-qa

# 单独拉起 Qdrant（重启后向量库服务需要先于其他服务）
docker compose up -d qdrant

七、更新与升级

7.1 拉取最新镜像

Tiledesk Community 的 compose 镜像 tag 固定为 stable 版本（如 tiledesk-server:2.13.23-op1），不会自动跟随 latest。升级步骤：

cd /opt/tiledesk

# 1. 备份数据（可选但推荐）
docker run --rm -v tiledesk-datadb:/data -v $(pwd):/backup alpine tar czf /backup/mongo-backup-$(date +%Y%m%d).tar.gz -C /data .

# 2. 拉取新 compose 文件
curl -fsSL https://raw.githubusercontent.com/Tiledesk/tiledesk-deployment/master/docker-compose/docker-compose.yml -o docker-compose.yml.new
# diff 对比
diff docker-compose.yml docker-compose.yml.new
# 确认无问题后覆盖
mv docker-compose.yml.new docker-compose.yml

# 3. 拉取新镜像
docker compose pull

# 4. 滚动重启
docker compose up -d

7.2 备份恢复

# 恢复备份（先停止所有服务）
docker compose down
docker run --rm -v tiledesk-datadb:/data -v $(pwd):/backup alpine sh -c 'cd /data && tar xzf /backup/mongo-backup-20261027.tar.gz'
docker compose up -d

八、常见问题排查

8.1 server 容器启动失败

docker compose logs server

常见原因：

MongoDB 未就绪：server depends_on.mongo.condition 为 service_healthy，检查 mongo 容器日志是否有 waiting for connections
RabbitMQ 未就绪：同理，rabbitmq 需要先 RABBITMQ_* 环境变量已设置
JWT_SECRET_KEY 与 chat21server/chat21httpserver 不一致：三个服务的 JWT_KEY 必须相同，compose 默认都是 tokenKey

8.2 Dashboard 页面空白

# 检查 dashboard 容器是否在跑
docker compose ps dashboard

# 检查端口映射
curl -I http://localhost:4500

# 预期 HTTP/1.1 200 OK；若 404 则是 FEATURES_TOKEN 问题

# 检查 MQTT over WebSocket 端点
curl http://localhost:8081/mqws/ws

# 预期返回 426 Upgrade Required（说明 WebSocket 升级正常）
# 若 Connection refused → 检查 chat21server 和 rabbitmq 容器
docker compose logs chat21server | grep -i mqtt

8.4 Qdrant 连接被拒

Compose 中 Qdrant 数据卷映射为 ./qdrant_storage:/qdrant/storage：

# 检查目录权限
ls -la qdrant_storage/
chmod 777 qdrant_storage/  # 临时测试，生产建议用 named volume

九、安全加固清单

项目	操作	优先级
默认管理员密码	Dashboard → Profile → 修改	🔴 高
JWT_SECRET_KEY	server 环境变量 `tokenKey` → 随机 32 字节串	🔴 高
APPS_ACCESS_TOKEN_SECRET	server 环境变量 `nodeauthsecret` → 随机 32 字节串	🔴 高
MongoDB 端口 27017	compose 中改为 expose（只内部访问），去掉端口映射	🔴 高
Redis 端口 6379	同上，不要对外暴露	🔴 高
RabbitMQ AMQP/MQTT	同上，只 15672 管理端口按需暴露	🟡 中
GPTKEY	改为有效的 API Key 后方可使用 AI 功能	🟡 中
外部地址	设置 EXTERNAL_BASE_URL 为正式域名，加 HTTPS	🟡 中
HTTPS 反代	Nginx/Caddy 证书 + EXTERNAL_MQTT_BASE_URL 用 wss://	🟢 低（可用 Cloudflare 先挡）

十、生产环境建议

10.1 数据持久化

compose 里 MongoDB 用 named volume tiledesk-datadb，但 Qdrant 用 bind mount ./qdrant_storage。生产建议统一用 named volume：

# docker-compose.yml 修改
volumes:
  tiledesk-datadb:
  qdrant-data:

# qdrant service
qdrant:
  volumes:
    - qdrant-data:/qdrant/storage

10.2 反向代理

在 Tiledesk 前置 Nginx/Caddy 做 TLS 终止和域名解析。核心配置要点：

WebSocket 升级必须正确处理（MQTT 和 Dashboard 都用到 WS）
/mqws/ 路径反代到 proxy 容器的 /mqws/
反代参考 compose README 中的 Nginx 配置

10.3 GPTKEY 生产安全

compose 中所有用到 AI 的服务都要配置 GPTKEY：

server
chatbot
backend-llm-train
backend-llm-qa

建议改用 Docker secrets 或 .env 文件（不要硬编码在 compose.yml 里）。

Tiledesk Docker Compose 部署指南

Tiledesk Docker Compose 部署指南

一、前置条件

1.1 环境要求

1.2 端口占用

1.3 创建部署目录

二、下载 Compose 文件

三、配置 .env 文件

3.1 创建 .env

3.2 .env 关键变量说明

3.3 生产环境进阶变量

四、启动部署

4.1 拉取镜像

4.2 启动全部服务

4.3 等待健康检查通过

4.4 查看日志

4.5 Compose 项目名说明

五、初始化登录

5.1 首次访问

5.2 默认管理员凭据

5.3 创建首个项目

六、停止与重启

6.1 正常停止

6.2 重启

6.3 只启动/停止单个服务

七、更新与升级

7.1 拉取最新镜像

7.2 备份恢复

八、常见问题排查

8.1 server 容器启动失败

8.2 Dashboard 页面空白

8.3 聊天 Widget 连接超时

8.4 Qdrant 连接被拒

九、安全加固清单

十、生产环境建议

10.1 数据持久化

10.2 反向代理

10.3 GPTKEY 生产安全