Libredesk Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上用 Docker Compose 从零部署 Libredesk v2.9.0 客户支持/共享收件箱系统（libredesk 应用 + PostgreSQL 17 + Redis 7 三服务编排），完成配置、初始化、管理员密码设置、登录验证与数据持久化、备份、升级等全套运维动作。全文命令与回显均在 Ubuntu 22.04 实测环境逐条验证通过（部署目录 /opt/libredesk/，应用端口实测用宿主机 8153 映射，读者无冲突时可用官方默认 9000）。

一、环境信息

本文所有命令在以下环境实测通过：

操作系统：Ubuntu 22.04（x86_64）
Docker：24+，Docker Compose v2 插件（实测版本 Docker Compose version v5.5.1）
Libredesk：libredesk/libredesk:latest（实测运行版本 v2.9.0 (5668a2a2 2026-10-22T11:43:42Z, linux/amd64)）
数据库：postgres:17-alpine
缓存/队列：redis:7-alpine
部署目录：/opt/libredesk/（本文示例路径）
端口规划（实测值）：应用 8153→9000（官方默认 9000→9000）、PostgreSQL 127.0.0.1:25432→5432、Redis 127.0.0.1:26379→6379
镜像体积（docker images 实测）：libredesk/libredesk:latest 73.9MB、postgres:17-alpine 424MB、redis:7-alpine 57.8MB

二、镜像选型说明

Libredesk 官方只发布一个应用镜像，数据库与缓存使用社区标准镜像，选型依据如下：

服务	镜像	选型理由
应用	`libredesk/libredesk:latest`	Docker Hub 官方仓库唯一维护镜像，当前指向 v2.9.0；镜像仅 73.9MB（Go 静态编译单二进制 + 内嵌前端）
数据库	`postgres:17-alpine`	官方 compose 文件指定版本；Libredesk 要求 PostgreSQL ≥13，选 17 系获得最新支持
缓存/队列	`redis:7-alpine`	官方 compose 文件指定版本；用于会话、限流与 Redis Streams 任务队列，7 系为当前稳定大版本

💡 说明：生产建议把 latest 固定为具体版本标签（本文实测时 latest 即 v2.9.0），避免 docker compose pull 意外引入破坏性更新；升级方法见第十章。

三、前置条件

部署前确认以下三件事：

软件依赖：已安装 Docker Engine 与 Compose v2 插件，验证命令与实测回显：

# 查看 Compose 版本
docker compose version

Docker Compose version v5.5.1

端口规划：应用端口默认 9000；若宿主机 9000 已被占用（本文实测环境即如此），改映射到空闲端口（如 8153）。PostgreSQL/Redis 的宿主端口默认只绑定 127.0.0.1，仅供本机调试访问，无需对外开放；用 ss 确认目标端口空闲：

# 确认 8153 端口未被占用（无输出即空闲）
ss -ltn | grep 8153

加密密钥：Libredesk 用 32 字符的 encryption_key 加密落库的敏感信息（如收件箱密码），首次启动前必须设置，之后不可更换（更换后已存密文无法解密）。用 openssl 生成：

# 生成 32 字符随机密钥
openssl rand -hex 16

37c754db5e59cd92c374e108e1763f94

四、部署步骤

4.1 创建部署目录并下载官方文件

# 创建部署目录
mkdir -p /opt/libredesk && cd /opt/libredesk

# 下载官方 compose 文件与示例配置
curl -LO https://github.com/abhinavxd/libredesk/raw/main/docker-compose.yml
curl -LO https://github.com/abhinavxd/libredesk/raw/main/config.sample.toml

# 复制为正式配置文件
cp config.sample.toml config.toml

4.2 编辑 config.toml（必改项）

至少修改 app.encryption_key；本节给出实测使用的完整配置关键段（逐项说明见配置篇）：

[app]
log_level = "info"
env = "prod"
check_updates = true
encryption_key = "37c754db5e59cd92c374e108e1763f94"   # 替换为你 openssl rand -hex 16 的结果

[app.server]
address = "0.0.0.0:9000"

[db]
host = "db"          # compose 网络内数据库服务名
port = 5432
user = "libredesk"
password = "libredesk"
database = "libredesk"
ssl_mode = "disable"

[redis]
address = "redis:6379"   # compose 网络内缓存服务名

⚠️ 注意：encryption_key 必须恰好 32 字符，且首次启动前设置、之后不再更换——更换会导致已保存的收件箱密码等密文全部无法解密。

4.3 编写 docker-compose.yml 与 .env

官方 compose 已含 app/db/redis 三服务。本文实测版本（端口因宿主机冲突调整为 8153/25432/26379，其余与官方一致）：

services:
  # Libredesk 应用
  app:
    image: libredesk/libredesk:latest
    container_name: libredesk_app
    restart: unless-stopped
    ports:
      - "8153:9000"        # 宿主机无冲突时可写 "9000:9000"
    environment:
      # 首次启动安装时自动为 System 用户设置该密码
      LIBREDESK_SYSTEM_USER_PASSWORD: ${LIBREDESK_SYSTEM_USER_PASSWORD:-}
    depends_on:
      - db
      - redis
    volumes:
      - ./uploads:/libredesk/uploads:rw
      - ./config.toml:/libredesk/config.toml
    command: [sh, -c, "./libredesk --install --idempotent-install --yes --config /libredesk/config.toml && ./libredesk --upgrade --yes --config /libredesk/config.toml && ./libredesk --config /libredesk/config.toml"]

  # PostgreSQL 数据库
  db:
    image: postgres:17-alpine
    container_name: libredesk_db
    restart: unless-stopped
    ports:
      # 只绑定本机回环地址；需要外部连接数据库时改为 0.0.0.0
      - "127.0.0.1:25432:5432"
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-libredesk}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-libredesk}
      POSTGRES_DB: ${POSTGRES_DB:-libredesk}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-libredesk} -d ${POSTGRES_DB:-libredesk}"]
      interval: 10s
      timeout: 5s
      retries: 6
    volumes:
      - postgres-data:/var/lib/postgresql/data

  # Redis
  redis:
    image: redis:7-alpine
    container_name: libredesk_redis
    restart: unless-stopped
    ports:
      # 只绑定本机回环地址
      - "127.0.0.1:26379:6379"
    volumes:
      - redis-data:/data

networks:
  libredesk:

volumes:
  postgres-data:
  redis-data:

配套 .env 文件（与 compose 同目录，存放首次安装用的管理员密码与数据库凭据）：

# /opt/libredesk/.env
LIBREDESK_SYSTEM_USER_PASSWORD=Q1w2e3r4!@
POSTGRES_USER=libredesk
POSTGRES_PASSWORD=libredesk
POSTGRES_DB=libredesk

⚠️ 注意：System 是 Libredesk 内置管理员账号（用户名固定为 System），其密码必须满足强度策略：10–72 位，至少含大写字母、小写字母、数字、特殊字符各一——q1w2e3r4 这类弱口令会在安装时直接报错 system user password is not strong。密码只在首次建库时从该环境变量读取，之后修改需用 4.5 节的命令。

4.4 启动服务

# 后台启动三服务（首次启动会自动建库、跑迁移、建 System 用户）
docker compose up -d

实测启动日志（docker logs libredesk_app 节选，完整经历「建库 → 建用户 → 迁移 → 起服务」四段）：

2026/10/23 19:47:09 Build: v2.9.0 (5668a2a2 2026-10-22T11:43:42Z, linux/amd64)
2026/10/23 19:47:09 reading config file: /libredesk/config.toml
2026/10/23 19:47:10 database schema installed successfully
2026/10/23 19:47:10 using provided password for system user
2026/10/23 19:47:10 system user created successfully. Use command 'libredesk --set-system-user-password' to set the password and login with email 'System'.
2026/10/23 19:47:10 Build: v2.9.0 (5668a2a2 2026-10-22T11:43:42Z, linux/amd64)
2026/10/23 19:47:10 reading config file: /libredesk/config.toml
2026/10/23 19:47:10 running migration v0.3.0
2026/10/23 19:47:10 running migration v0.4.0
2026/10/23 19:47:10 running migration v0.5.0
2026/10/23 19:47:10 running migration v0.6.0
2026/10/23 19:47:10 running migration v0.7.0
2026/10/23 19:47:10 running migration v0.7.4
2026/10/23 19:47:10 running migration v0.8.5
2026/10/23 19:47:10 running migration v0.9.1
2026/10/23 19:47:10 running migration v1.0.1
2026/10/23 19:47:10 running migration v2.0.0
2026/10/23 19:47:10 running migration v2.2.0
2026/10/23 19:47:10 running migration v2.3.0
2026/10/23 19:47:10 running migration v2.4.0
2026/10/23 19:47:10 running migration v2.5.0
2026/10/23 19:47:10 running migration v2.6.0
2026/10/23 19:47:10 running migration v2.8.0
2026/10/23 19:47:10 running migration v2.9.0-rc.8
2026/10/23 19:47:10 running migration v2.9.0-rc.9
2026/10/23 19:47:10 running migration v2.9.0-rc.10
2026/10/23 19:47:10 upgrade complete
2026/10/23 19:47:10 loading i18n language file: en-US
2026/10/23 19:47:10 Server started at 0.0.0.0:9000

确认三服务状态（实测回显）：

# 查看服务状态
docker compose ps

NAME              IMAGE                        COMMAND                   SERVICE   CREATED          STATUS                    PORTS
libredesk_app     libredesk/libredesk:latest   "sh -c './libredesk …"   app       32 minutes ago   Up 32 minutes             0.0.0.0:8153->9000/tcp, [::]:8153->9000/tcp
libredesk_db      postgres:17-alpine           "docker-entrypoint.s…"   db        33 minutes ago   Up 33 minutes (healthy)   127.0.0.1:25432->5432/tcp
libredesk_redis   redis:7-alpine               "docker-entrypoint.s…"   redis     33 minutes ago   Up 33 minutes             127.0.0.1:26379->6379/tcp

💡 说明：应用启动命令把「安装 → 升级 → 运行」串成一条链，--idempotent-install 在库已存在时打印 skipping installation as schema is already installed 后正常退出（退出码 0），链条继续走 --upgrade（无待迁移项时秒退）再进入服务进程，因此每次重启容器都是安全的。

4.5 管理员密码的两种设置方式

方式 A（推荐）：如 4.3 节在 .env 里配置 LIBREDESK_SYSTEM_USER_PASSWORD，首次 up 时自动生效（上面日志中的 using provided password for system user 即此机制）。

方式 B：事后用交互命令重设（会同时注销该账号所有已登录会话）：

# 交互式重设 System 用户密码
docker exec -it libredesk_app ./libredesk --set-system-user-password

按提示输入两次新密码后回显 password updated successfully. Login with email 'System' and the new password.

4.6 登录验证

浏览器访问 http://<服务器IP>:8153（官方默认端口部署则为 :9000），以 Email System + 设置的密码登录。用 curl 等价验证（实测回显）：

# 登录接口验证（密码换成你设置的值）
curl -s -c cookies.txt -H 'Content-Type: application/json' \
  -d '{"email":"System","password":"Q1w2e3r4!@"}' \
  http://127.0.0.1:8153/api/v1/auth/login

{"status":"success","data":{"id":1,"created_at":"2026-10-23T19:47:10.248407Z","updated_at":"2026-10-23T19:50:46.787083Z","first_name":"System","last_name":"","email":"System","type":"agent","availability_status":"offline", ...

# 首页连通性验证
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8153/

返回 success 与 200 即部署完成。登录后第一件事：到 Admin → Inboxes 添加邮件/在线聊天/WhatsApp 收件箱，到 Admin → Teammates → Agents 邀请坐席。

五、数据持久化说明

Libredesk 的持久化分三块，缺一不可：

数据	存储位置	持久化方式	说明
业务数据（会话/消息/联系人/知识库等）	PostgreSQL	命名卷 `postgres-data` → `/var/lib/postgresql/data`	核心数据，备份以它为准
缓存与队列	Redis	命名卷 `redis-data` → `/data`	可丢失（会话失效重新登录即可），但保留可免重启后任务重放
上传附件	应用内 `uploads/` 目录	bind mount `./uploads` → `/libredesk/uploads`	头像、聊天附件等文件

验证数据卷已创建（实测回显）：

# 查看 compose 管理的数据卷
docker volume ls | grep libredesk

libredesk_postgres-data
libredesk_redis-data

⚠️ 注意：./uploads 目录由 compose 自动创建；若手动迁移部署，确保该目录存在且应用进程可写，否则附件上传失败。

六、环境变量表

compose 编排层使用的环境变量（定义于 .env 或导出后传入 docker compose up）：

变量	默认值	说明
`LIBREDESK_SYSTEM_USER_PASSWORD`	空	首次建库时为 System 用户设置的密码；需满足 10–72 位强度策略；库已存在时该值被忽略
`POSTGRES_USER`	`libredesk`	数据库用户名，需与 config.toml `[db].user` 一致
`POSTGRES_PASSWORD`	`libredesk`	数据库密码，需与 config.toml `[db].password` 一致
`POSTGRES_DB`	`libredesk`	数据库名，需与 config.toml `[db].database` 一致

应用层配置不靠环境变量而靠 config.toml（也支持 LIBREDESK_ 前缀 + 双下划线嵌套的环境变量覆盖，如 LIBREDESK_DB__HOST=db，完整规则与参数逐项解释见《Libredesk v2.9.0 配置参数详解》）。

七、配置参数说明

compose 部署形态下，配置分两层：

编排层（docker-compose.yml + .env）：管服务拓扑、端口映射、数据卷、服务间依赖与健康检查，改动后需 docker compose up -d 重建生效；
应用层（config.toml）：管应用行为——HTTP 服务参数（监听地址、会话时长、请求体上限）、数据库/Redis 连接池、消息队列 worker 数、自动化/SLA/自动分派扫描间隔、限流阈值、上传 Provider（fs/S3）、AI 接入、Webhook 派发线程等，改动后需 docker compose restart app 生效。

config.toml 全部参数的逐项说明、默认值与生产推荐模板见《Libredesk v2.9.0 配置参数详解》。

八、配置文件挂载

compose 中两个挂载点的行为（实测确认）：

./config.toml:/libredesk/config.toml：单文件 bind mount，宿主机改完执行 docker compose restart app 即生效；启动日志的 reading config file: /libredesk/config.toml 行可确认应用读到的是挂载文件；
./uploads:/libredesk/uploads:rw：目录 bind mount，应用内上传路径默认相对工作目录 uploads（[upload.fs].upload_path），挂载后文件直接落宿主机 /opt/libredesk/uploads/。

💡 说明：自定义前端样式可用 --static-dir（或 config.toml 的 static_dir）指向自定义静态文件目录，目录结构需镜像内建 static/，只替换你提供的文件，其余用内置默认。

九、等价 docker run

不用 Compose 时，以下三条命令等价复现本文三服务拓扑（生产仍建议用 Compose 统一管理）：

# 1. 创建内部网络
docker network create libredesk

# 2. 启动 PostgreSQL
docker run -d --name libredesk_db --network libredesk \
  -p 127.0.0.1:25432:5432 \
  -e POSTGRES_USER=libredesk -e POSTGRES_PASSWORD=libredesk -e POSTGRES_DB=libredesk \
  -v libredesk_postgres-data:/var/lib/postgresql/data \
  --restart unless-stopped postgres:17-alpine

# 3. 启动 Redis
docker run -d --name libredesk_redis --network libredesk \
  -p 127.0.0.1:26379:6379 \
  -v libredesk_redis-data:/data \
  --restart unless-stopped redis:7-alpine

# 4. 启动 Libredesk 应用
docker run -d --name libredesk_app --network libredesk \
  -p 8153:9000 \
  -e LIBREDESK_SYSTEM_USER_PASSWORD='Q1w2e3r4!@' \
  -v /opt/libredesk/config.toml:/libredesk/config.toml \
  -v /opt/libredesk/uploads:/libredesk/uploads:rw \
  --restart unless-stopped libredesk/libredesk:latest \
  sh -c "./libredesk --install --idempotent-install --yes --config /libredesk/config.toml && ./libredesk --upgrade --yes --config /libredesk/config.toml && ./libredesk --config /libredesk/config.toml"

十、常用运维命令

10.1 日常启停与日志

# 查看实时日志（应用）
docker compose logs -f app

（持续输出运行日志，Ctrl+C 退出跟踪；关键行示例：）
timestamp=2026-10-23T20:17:10.655Z level=info message="fetching pending applied SLAs" caller=/home/runner/work/libredesk/libredesk/internal/sla/sla.go:898 sc=sla

# 重启应用（改 config.toml 后）
docker compose restart app

# 停止 / 启动全部服务
docker compose stop
docker compose start

10.2 版本确认与升级

# 确认当前运行版本
docker exec libredesk_app ./libredesk --version

v2.9.0 (5668a2a2 2026-10-22T11:43:42Z, linux/amd64)

# 拉取新镜像
docker compose pull

[+] Running 1/1
 ✔ app Pulled                                                         3.2s

# 重建应用（数据库迁移由启动链中的 --upgrade 自动完成）
docker compose up -d app
docker exec libredesk_app ./libredesk --version   # 复核新版本号

⚠️ 注意：升级前先按 10.3 备份数据库；大版本升级先读官方 Releases 的变更说明。

10.3 数据库备份与恢复

# 备份（导出到宿主机当前目录）
docker exec libredesk_db pg_dump -U libredesk -d libredesk > libredesk_$(date +%F).sql

# 核对备份文件行数（实测约 6147 行/全新库）
wc -l libredesk_2026-10-24.sql

6147 libredesk_2026-10-24.sql

# 恢复（空库时）
cat libredesk_2026-10-24.sql | docker exec -i libredesk_db psql -U libredesk -d libredesk

同时把 ./uploads/ 目录一并拷贝归档，附件才能完整恢复。

10.4 卸载

# 停止并移除三服务与网络（-v 连同数据卷一起删除，数据将丢失，慎用）
docker compose down -v

保留数据卷时去掉 -v。

十一、常见问题

Q1：重启后应用起不来，日志出现 skipping installation as schema is already installed 后没有下文？ 这是正常现象的第一段输出：--idempotent-install 检测到库已存在即跳过，链条随后执行 --upgrade 与启动进程。若确实没起来，看 docker compose logs app 是否报数据库连接错误——常见原因是 .env 与 config.toml 的数据库凭据不一致（部署时 POSTGRES_PASSWORD 与 [db].password 必须相同）。

Q2：浏览器登录报 CSRF token mismatch？ 应用日志中对应错误形如 level=error message="csrf token mismatch" method=POST。原因是反向代理（如 Nginx）没有转发必要的头。按官方文档，代理必须设置 proxy_set_header X-Client-IP $remote_addr;（Libredesk 用它识别客户端做限流与审计），并保持 Upgrade/Connection 头透传以支持 WebSocket。

Q3：--set-system-user-password 提示密码不合规？ System 用户密码要求 10–72 位且至少含大写字母、小写字母、数字、特殊字符各一（源码常量 minPassword=10, maxPassword=72）。q1w2e3r4（8 位、无大写与特殊字符）不满足，请使用 Q1w2e3r4!@ 这类符合策略的口令。

Q4：首次 up 时报 system user password is not strong？ .env 里 LIBREDESK_SYSTEM_USER_PASSWORD 不满足强度策略，按 Q3 修改后重新 docker compose up -d（注意：库已建成的场景下该变量不再生效，改用 4.5 节方式 B 重设）。

Q5：附件上传失败？ 确认 ./uploads 宿主目录存在且可写（官方文档明确：应用不会自动创建该目录，目录缺失或不可写时上传直接失败）；若改用 S3 存储，检查 config.toml [upload] provider 与 [upload.s3] 各项。

Q6：宿主机端口冲突？ 本文实测将 9000 映射为 8153、5432/6379 映射为 25432/26379。部署时用 ss -ltn 先检查目标端口，compose 的 ports 左侧宿主端口可自由调整，右侧容器端口不变。

十二、参考链接

官方安装文档：https://docs.libredesk.io/getting-started/installation
官方 compose 文件：https://github.com/abhinavxd/libredesk/blob/main/docker-compose.yml
示例配置：https://github.com/abhinavxd/libredesk/blob/main/config.sample.toml
Docker Hub：https://hub.docker.com/r/libredesk/libredesk
本专栏相关篇目：认知与选型见《Libredesk 介绍与选型指南》；配置参数见《Libredesk v2.9.0 配置参数详解》；API 集成见《Libredesk v2.9.0 API 使用详解》