Sonic Docker Compose 部署指南

‍‍​​‌​> 目标：用 Docker Compose 在 Ubuntu 22.04 服务器上一键部署 Sonic 搜索后端（sonic-server v1.10.2），完成配置文件挂载、token 认证、数据持久化，并给出升级、日志、备份等日常运维命令；全流程已在 Ubuntu 22.04（x86_64）+ Docker Compose v5.5.1 实测通过。

一、环境信息

本文所有命令与回显实测自以下环境：

• 操作系统：Ubuntu 22.04（x86_64）
• Docker：Docker Compose v5.5.1（docker compose version 实测回显）
• Sonic：sonic-server v1.10.2（官方镜像 valeriansaliou/sonic:latest，连接问候语 CONNECTED <sonic-server v1.10.2> 实测）
• 镜像体积：71.4MB；进程空载内存约 6.3 MiB（docker stats 实测）
• 监听端口：TCP 1491（宿主机与容器内一致）
• 挂载路径：配置 /opt/data/sonic/config.cfg → /etc/sonic/config.cfg；数据 /opt/data/sonic/store/ → /opt/data/sonic/store/（容器内外同路径，与配置文件中的存储路径保持一致）
• 认证口令：q1w2e3r4（测试口令，生产环境请更换）

二、镜像选型说明

Sonic 官方在 Docker Hub 发布镜像 valeriansaliou/sonic，与源码同仓库构建（多阶段构建：Rust 编译后复制进 distroless 运行底座），这是唯一官方镜像源。选型要点：

实测拉取记录（版本固定到 1.10.2，摘要 sha256:f8f9f249f2dd8d6674784a82ea0427922f6c2240700b01558a7b667f277e690a）：

$ docker pull valeriansaliou/sonic:latest
25197dda31ba: Pull complete
89616afad584: Pull complete
Digest: sha256:f8f9f249f2dd8d6674784a82ea0427922f6c2240700b01558a7b667f277e690a
Status: Downloaded newer image for valeriansaliou/sonic:latest
docker.io/valeriansaliou/sonic:latest

⚠️ 注意：该镜像基于 distroless 运行底座，内部没有 shell，docker exec 进容器执行 cat/sh 会直接失败（实测报 executable file not found in $PATH）。查看配置请直接看宿主机挂载文件，导出镜像内文件用 docker create + docker cp/docker export。

关键差异与选择：生产环境固定版本 tag 并记录 digest，升级时先在测试环境验证新版本索引兼容性（官方对分词/规范化行为的变更要求重建索引）。

三、前置条件

1. 已安装 Docker Engine 与 Docker Compose 插件，验证命令与实测回显：

docker compose version

Docker Compose version v5.5.1

2. 宿主机 1491 端口未被占用，验证：

ss -ltn | grep 1491

（无输出即空闲。）

3. 准备宿主机目录与配置文件：

mkdir -p /opt/data/sonic/store/

配置文件内容见第七节（配置参数说明），先创建空文件占位也可以，首次 up 前务必写入完整配置。

四、部署步骤

4.1 编写 compose.yml

在部署目录（本文用 /opt/data/sonic/）创建 compose.yml：

services:
  sonic:
    image: valeriansaliou/sonic:latest
    container_name: sonic-1.10.2-search
    restart: unless-stopped
    ports:
      - "1491:1491"
    volumes:
      - /opt/data/sonic/config.cfg:/etc/sonic/config.cfg
      - /opt/data/sonic/store/:/var/lib/sonic/store/
    command: ["sonic", "-c", "/etc/sonic/config.cfg"]

逐项说明：

• container_name：固定容器名，便于日志与监控命令引用（sonic-1.10.2-search）；
• restart: unless-stopped：宿主机重启或进程崩溃后自动拉起（手动 stop 的除外）；
• ports: "1491:1491"：宿主机与容器端口一致，Sonic Channel 客户端连 宿主机IP:1491；
• volumes 第一行：配置文件 bind mount，容器内 Sonic 读 /etc/sonic/config.cfg；
• volumes 第二行：数据目录 bind mount（容器内外同路径），KV 与 FST 双存储全部落在这里，重建容器数据不丢；同路径挂载也让配置中的 store.kv.path、store.fst.path 在宿主机与容器内写法完全一致，排障时无需换算；
• command：必填。镜像默认 CMD 只有 sonic（等价 sonic 无参数启动），必须显式传 -c /etc/sonic/config.cfg 指向挂载的配置文件。

⚠️ 注意一个实测踩过的坑：command 必须写全 ["sonic", "-c", "/etc/sonic/config.cfg"]。如果只写 command: ["-c", "/etc/sonic/config.cfg"]，Compose 会把参数当作可执行文件，启动即报错：

docker: Error response from daemon: failed to create task for container: failed to create
shim task: OCI runtime create failed: runc create failed: unable to start container process:
error during container init: exec: "-c": executable file not found in $PATH

4.2 写入完整配置文件

将第七节内容写入 /opt/data/sonic/config.cfg。其中与部署直接相关的两处关键设置：

• inet = "0.0.0.0:1491"：监听容器内所有网卡。官方默认值 [::1]:1491 只绑回环地址，端口映射后外部连不通（这是 Sonic 容器化部署最常见的「起得来但连不上」根因）；
• auth_password = "q1w2e3r4"：通道认证口令，生产环境务必改为强随机值（也可以用第六节的环境变量注入，避免明文落盘）。

4.3 启动服务

docker compose up -d

实测回显（首次启动会创建网络与容器）：

 Network work-sonic_default Creating
 Network work-sonic_default Created
 Container sonic-1.10.2-search Creating
 Container sonic-1.10.2-search Created
 Container sonic-1.10.2-search Starting
 Container sonic-1.10.2-search Started

4.4 验证部署

第一步：容器状态：

docker compose ps

NAME                  IMAGE                         COMMAND                   SERVICE   CREATED        STATUS                  PORTS
sonic-1.10.2-search   valeriansaliou/sonic:latest   "sonic -c /etc/sonic…"   sonic     1 second ago   Up Less than a second   0.0.0.0:1491->1491/tcp, [::]:1491->1491/tcp

第二步：服务日志：

docker compose logs sonic

实测节选（启动头部）：

sonic-1.10.2-search  | 2026-10-17T08:04:56.857688Z DEBUG reading config file: "/etc/sonic/config.cfg"
sonic-1.10.2-search  | 2026-10-17T08:04:56.858944Z  INFO starting up
sonic-1.10.2-search  | 2026-10-17T08:04:56.859053Z  INFO started
sonic-1.10.2-search  | 2026-10-17T08:04:56.859227Z  INFO tasker is now active
sonic-1.10.2-search  | 2026-10-17T08:04:56.859277Z  INFO listening on tcp://0.0.0.0:1491

listening on tcp://0.0.0.0:1491 即监听地址生效确认。

第三步：协议连通性（宿主机任装了 nc 即可）：

printf 'PING\nQUIT\n' | nc -w 2 127.0.0.1 1491

实测回显：

CONNECTED <sonic-server v1.10.2>
ENDED not_recognized

第一行问候语确认版本 v1.10.2；ENDED not_recognized 是未认证直接发 PING 的预期行为（未 START 前任何命令都会结束连接，属协议设计，不是故障）。

第四步：认证后读写闭环（完整交互见《Sonic 常用 CLI 命令与工具详解》）：

<<< CONNECTED <sonic-server v1.10.2>
>>> START ingest q1w2e3r4
<<< STARTED ingest protocol(1) buffer(20000)
>>> PUSH messages default conversation:1 "Hello world, this is Sonic search backend"
<<< OK

换 search 模式查询能命中 conversation:1，部署即完成。

五、数据持久化说明

Sonic 的全部索引数据在 /opt/data/sonic/store/ 下（容器内外同路径），本方案将其 bind mount 到宿主机同路径。实测目录结构（KV 与 FST 双引擎按集合散列分目录）：

store/
├── fst/
│   ├── 4f744a98
│   └── 6dbe5b68
└── kv/
    ├── 4244275
    ├── 4f744a98
    ├── 6dbe5b68
    └── d0b342

持久化实测：写入数据后执行 docker compose restart sonic，重启完成立即查询：

>>> QUERY messages default "sonic"
<<< EVENT QUERY WCI74LVQ conversation:6 conversation:4 conversation:2

结果集与重启前一致，持久化生效。即使 docker compose down 删除容器，只要 /opt/data/sonic/store/ 在，重新 up -d 后数据完整恢复。

⚠️ 注意：RocksDB 开启了 WAL（默认 write_ahead_log = true），未到 900 秒落盘周期的写入也能在崩溃后恢复；但备份仍建议在停机或 TRIGGER backup 后进行，直接拷贝正在写入的 kv 目录可能拿到不一致快照。

六、环境变量表

Sonic 支持 SONIC_ 前缀环境变量覆盖配置文件，规则：SONIC_ + 配置路径（下划线段用 __ 连接），环境变量优先级高于文件。常用项：

在 compose.yml 中注入示例：

    environment:
      SONIC_CHANNEL__AUTH_PASSWORD: "q1w2e3r4"

实测有效（用错误口令连接被拒，验证口令确已生效）：

>>> START search wrong-pass
<<< ENDED authentication_failed

另外，server.log_level、channel.inet、channel.auth_password、store.kv.path、store.fst.path 五个键支持配置内插值 "${env.变量名}"，如 auth_password = "${env.SONIC_PASSWORD}"，可从宿主机环境读入口令。

七、配置参数说明

部署用完整配置文件 /opt/data/sonic/config.cfg（与容器内 /etc/sonic/config.cfg 一致，逐参数详解见《Sonic 配置参数详解》）：

[server]
log_level = "info"

[channel]
inet = "0.0.0.0:1491"
tcp_timeout = 300
auth_password = "q1w2e3r4"

[normalization]
unicode_normalization = "none"
diacritic_folding_enabled = false
stemming_enabled = false

[tokenization]
detect_special_patterns = true
compat_split_special_patterns = true

[search]
query_limit_default = 10
query_limit_maximum = 100
query_alternates_try = 4
query_minimum_term_idf_default = 0.1
query_minimum_term_idf_minimum_object_count = 100
suggest_limit_default = 5
suggest_limit_maximum = 20
list_limit_default = 100
list_limit_maximum = 500

[store.kv]
path = "/var/lib/sonic/store/kv/"
retain_word_objects = 1000
pool.inactive_after = 1800
database.flush_after = 900
database.compression_type = "zstd"
database.parallelism = 2
database.max_files = 100
database.write_buffer_size = 16384
database.write_ahead_log = true

[store.fst]
path = "/var/lib/sonic/store/fst/"
pool.inactive_after = 300
graph.consolidate_after = 180
graph.max_size = 2048
graph.max_words = 250000

部署视角最需要关注的三组：

• 可用性组：inet（必须 0.0.0.0 才能端口映射）、auth_password（必须设置，默认无口令裸奔）、tcp_timeout（空闲连接 300 秒超时）；
• 数据安全组：database.write_ahead_log = true（崩溃不丢数据）+ database.flush_after = 900（落盘周期，越小越安全、IO 越多）；
• 资源组：retain_word_objects（单词最多关联对象数，控制索引膨胀）、graph.max_size/max_words（FST 图上限）。

八、配置文件挂载

挂载生效验证（宿主机与容器内看到同一份数据）：

ls /opt/data/sonic/store/kv/

4244275
4f744a98
6dbe5b68
d0b342

修改配置后的生效方式：docker compose restart sonic（Sonic 启动时读一次配置，无热加载）。重启后用 docker compose logs sonic | head 确认新配置被读取（reading config file: "/etc/sonic/config.cfg"）。

九、等价 docker run

不使用 Compose 时，以下单条 docker run 与上述 compose.yml 完全等价（实测可用）：

docker run -d \
  --name sonic-1.10.2-search \
  --restart unless-stopped \
  -p 1491:1491 \
  -v /opt/data/sonic/config.cfg:/etc/sonic/config.cfg \
  -v /opt/data/sonic/store/:/opt/data/sonic/store/ \
  valeriansaliou/sonic:latest \
  sonic -c /etc/sonic/config.cfg

与 Compose 方案二选一即可，两者容器名相同不可同时存在。

十、常用运维命令

升级操作完整实测流程：

docker compose pull

（回显 Status: Downloaded newer image ... 或已是最新提示。）

docker compose up -d

（回显 Recreate ... Started，容器用新镜像重建，挂载的索引数据自动继承。）

⚠️ 注意：跨大版本升级前先在测试环境验证；官方文档明确：分词/规范化行为变更后需要重建索引（重新 PUSH 全部数据）才能保证结果一致。

十一、常见问题

Q1：容器 Up 但客户端连不上 1491？ 根因九成是配置里 inet 保持官方默认 [::1]:1491（仅回环监听），端口映射转发不到回环。改为 inet = "0.0.0.0:1491" 后 docker compose restart sonic，日志出现 listening on tcp://0.0.0.0:1491 即修复（本环境实测复现并解决）。

Q2：启动即退出，日志报配置错误？ Sonic 启动校验配置约束：store.kv.database.flush_after 必须严格小于 store.kv.pool.inactive_after；store.fst.graph.consolidate_after 必须严格小于 store.fst.pool.inactive_after。违反约束进程直接 panic 退出，按默认值（900<1800、180<300）调整即可。

Q3：docker exec sonic-1.10.2-search sh 报错进不去？ 官方镜像是 distroless 底座，无 shell。排查配置直接看宿主机 /opt/data/sonic/config.cfg；需要导出镜像内文件时用 docker create + docker export。

Q4：PUSH 超长文本后连接直接断开？ 协议单命令上限为 STARTED 返回的 buffer(20000) 字节。实测发送 25000 字节的 PUSH，服务端直接关闭连接。客户端必须按 buffer 值拆分文本分多次 PUSH（对象词条取并集），或缩短单条文本。

Q5：刚 PUSH 的数据 SUGGEST/LIST 查不到？ QUERY 走 KV 即时可见；SUGGEST/LIST 走 FST 词图，需要等合并（默认 180 秒）或手动 TRIGGER consolidate（control 模式）后立即出现（本环境实测复现并验证）。

Q6：忘记 auth_password 怎么办？ 配置文件在宿主机 /opt/data/sonic/config.cfg，直接查看或修改后 docker compose restart sonic；若用环境变量注入，查看 compose.yml 或 docker inspect sonic-1.10.2-search 的 Env 段。

十二、参考链接

• Sonic 官方仓库：https://github.com/valeriansaliou/sonic
• 官方 Docker Hub（镜像说明）：https://hub.docker.com/r/valeriansaliou/sonic
• 官方配置参考：https://github.com/valeriansaliou/sonic/blob/master/CONFIGURATION.md
• 官方协议规范：https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md
• 本专栏配套篇：《Sonic 介绍与选型指南》《Sonic 配置参数详解》《Sonic 常用 CLI 命令与工具详解》
• 相关文档：《MeiliSearch 1.55.0 Docker Compose 部署指南》《MeiliSearch 1.55.0 Ubuntu 22.04 安装指南》