Typesense Docker Compose 部署指南

目标：Typesense 30.2 官方镜像的 Docker Compose 部署全流程：compose 文件逐段说明、健康检查（无 curl 方案）、数据持久化实测、TYPESENSE_ 环境变量等价、配置文件挂载与常见问题排查，全部命令与回显实测照抄。

一、环境信息（实测环境）

本文全部命令与回显在以下环境实测照抄：

二、镜像选型说明

• 官方镜像：typesense/typesense:<版本>，Docker Hub 地址 https://hub.docker.com/r/typesense/typesense 。固定版本 tag（如 30.2），不建议 latest（升级不可控）；
• 镜像内含单二进制 typesense-server（位于 /opt/typesense-server），入口即执行该二进制，command 段的内容就是它的命令行参数；
• 架构：amd64 / arm64 均有官方构建；镜像内只有 bash，无 curl/wget，容器内健康检查需用 bash 内建能力（见「五、健康检查」）；
• 镜像以 root 运行，数据目录建议属主 root（bind 挂载时 Docker 会自动创建目录）。

三、前置条件

1. 宿主机安装 Docker 24+ 与 Compose v2：

docker version --format '{{.Server.Version}}'
docker compose version

2. 端口规划：宿主机端口 13909 映射容器 API 端口 8108（本系列约定）；集群场景另需节点互联端口 8107，本文单节点不涉及；
3. 创建部署与数据目录：

mkdir -p /opt/data/typesense/compose/data

四、部署步骤

4.1 完整 compose 文件

/opt/data/typesense/compose/docker-compose.yml（实测可用）：

services:
  typesense:
    image: typesense/typesense:30.2
    container_name: typesense-30.2-compose
    restart: on-failure
    ports:
      - "13909:8108"
    volumes:
      - ./data:/data
    command: '--data-dir /data --api-key=xyz --enable-cors'
    healthcheck:
      test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8108 && printf 'GET /health HTTP/1.0\r\n\r\n' >&3 && cat <&3 | grep -q '\"ok\":true'"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s

4.2 逐段说明

4.3 启动与验证

cd /opt/data/typesense/compose
docker compose up -d

实测输出：

[+] Running 1/1
 ✔ Container typesense-30.2-compose  Started

等待健康检查就绪（start_period: 15s 后开始判定）：

docker ps --filter name=typesense-30.2-compose --format '{{.Names}}\t{{.Status}}'

实测输出：

typesense-30.2-compose  Up 40 seconds (healthy)

宿主机验证 API（实测回显照抄）：

curl -s http://127.0.0.1:13909/health

{"ok":true}

curl -s -H 'X-TYPESENSE-API-KEY: xyz' http://127.0.0.1:13909/debug

{"version":"30.2"}

五、健康检查

三种层次（均已实测）：

5.1 Docker 健康检查（compose 内置）

见 4.1 的 healthcheck 段，docker ps 的 Status 列显示 healthy/unhealthy，可用于编排依赖判断。

5.2 容器内手工验证（无 curl 方案）

docker exec typesense-30.2-compose bash -c 'exec 3<>/dev/tcp/127.0.0.1/8108 && printf "GET /health HTTP/1.0\r\n\r\n" >&3 && cat <&3'

实测回显（末行）：

{"ok":true}

5.3 宿主机经映射端口验证

curl -s http://127.0.0.1:13909/health && echo

{"ok":true}

六、数据持久化说明

• ./data:/data 将容器内 RocksDB 数据目录落到宿主机 /opt/data/typesense/compose/data，含 db/、meta.json、state/（快照）等；
• 删除容器不会丢数据；docker compose down 亦不删除 bind 挂载目录；
• 实测持久化：写入数据后 docker compose down && docker compose up -d，数据完整保留：

curl -s -H 'X-TYPESENSE-API-KEY: xyz' http://127.0.0.1:13909/collections \
  | python3 -c "import json,sys; [print(d['name'], d['num_documents']) for d in json.load(sys.stdin)]"

实测回显（重启后）：

products 12
books 8

• 数据卷归属：compose 相对路径 ./data 是「文件所在目录」相对，实际落在 /opt/data/typesense/compose/data；若用 named volume（如 typesense-data:/data），需 docker volume inspect 找实际位置，备份策略建议基于宿主机目录 bind 挂载。

七、环境变量表

镜像约定：命令行参数 --foo-bar 对应环境变量 TYPESENSE_FOO_BAR，两者等价。常用如下：

环境变量等价性实测（TYPESENSE_API_PORT=8209 启动后日志照抄）：

I20261017 22:36:52.629xxx  typesense_server_utils.cpp:519] Typesense has started listening on port 8209

curl -s http://127.0.0.1:8209/health

{"ok":true}

完整参数清单与逐参数实测见《Typesense 30.2 配置参数详解》。

八、配置文件挂载

除 command 参数与环境变量外，支持挂载 INI 配置文件启动（容器内路径自定，经 --config 指向）。

宿主机 /opt/data/typesense/compose/typesense.ini（实测可用）：

[server]
api-port = 8108
data-dir = /data
api-key = xyz
enable-cors = true

compose 片段（替换 command 段）：

    volumes:
      - ./data:/data
      - ./typesense.ini:/etc/typesense/typesense.ini:ro
    command: '--config=/etc/typesense/typesense.ini'

实测：单独只挂配置、不挂数据目录时启动失败，日志原文照抄：

E20261017 22:21:06.962514     1 typesense_server_utils.cpp:502] Typesense failed to start. Data directory /data does not exist.

即 数据目录必须真实存在：compose 的 bind 挂载会自动创建宿主机目录，但「只挂配置不挂数据」时容器内裸目录不存在会直接退出。补挂数据卷后实测 /health 返回 {"ok":true}，且日志确认监听 8108。

九、等价 docker run 命令

与 4.1 compose 完全等价的一次性启动方式（实测通过，数据可从同一目录恢复）：

docker run -d \
  --name typesense-30.2-dockerrun \
  -p 13909:8108 \
  -v /opt/data/typesense/compose/data:/data \
  typesense/typesense:30.2 \
  --data-dir /data --api-key=xyz --enable-cors

实测：停掉 compose 后用该命令启动，/collections 返回的集合与文档数一致（数据同源）；删除该容器后 docker compose up -d 复活原服务，/health 返回 {"ok":true}。

十、常用运维命令

# 日志
docker logs -f typesense-30.2-compose
# 资源占用
docker stats typesense-30.2-compose --no-stream
# 重启（数据不丢）
docker compose restart
# 升级版本：改 image tag 后
docker compose up -d --force-recreate
# 手动快照（写入容器内 /data/state/snapshot/，随数据卷持久化）
curl -s -X POST -H 'X-TYPESENSE-API-KEY: xyz' \
  -H 'Content-Type: application/json' \
  http://127.0.0.1:13909/operations/snapshot -d '{"snapshot_path":"/tmp/snap"}'

{"success": true}

实测说明：v30.2 的快照实际落盘于数据目录内 state/snapshot/snapshot_<序号>，传入的 snapshot_path 仅作为服务器内部工作目录，快照文件随 ./data 持久化。

十一、常见问题

11.1 报 Invalid configuration: API key is not specified.

未提供 --api-key（或 TYPESENSE_API_KEY）。实测启动即退出，完整报错首行照抄：

Typesense 30.2
Invalid configuration: API key is not specified.
Command line usage: ./typesense-server --data-dir=string --api-key=string [options] ...

11.2 报 Data directory /data does not exist.

容器内数据目录不存在。compose/bind 挂载场景检查 volumes 路径是否正确；只挂配置文件时必须同时挂数据目录（见第八节实测）。

11.3 报 LOCK: Resource temporarily unavailable（日志含 RocksDB 字样）

同一数据目录被第二个实例占用：例如宿主机另跑了一个容器/进程指向同一个 data 目录。Typesense 基于 RocksDB，同一时刻仅允许一个实例独占目录。先 docker ps / ps aux | grep typesense-server 排查重复实例，确保数据目录与实例一一对应。

11.4 healthcheck 一直 unhealthy

日志出现 cannot create /dev/tcp/127.0.0.1/8108: Directory nonexistent：healthcheck 的 test 用了默认 /bin/sh（dash 不支持 /dev/tcp）。改用 test: ["CMD", "bash", "-c", "..."]（实测修复，见 4.1/4.2）。

11.5 端口冲突 bind: address already in use

宿主机 13909 已被占用。改映射（如 23909:8108）或释放端口；注意 13909 是本系列约定端口，变更后需同步更新文中所有示例。

11.6 浏览器跨域请求被拦

前端直连 Typesense 需要开启 --enable-cors；如需限制来源，用 --cors-domains="https://app.example.com"（实测：值需带协议，裸域名 example.com 不会匹配 Origin: http://example.com）。

11.7 写入返回 422 并提示 memory/disk 保护

实例进入降级保护（内存/磁盘水位超限或开启 --skip-writes），详细阈值与恢复方法见《Typesense 30.2 配置参数详解》。

十二、参考链接

1. 官方安装文档（Docker Compose 节）：https://typesense.org/docs/guide/install-typesense.html
2. 官方镜像：https://hub.docker.com/r/typesense/typesense
3. 服务器配置参数参考：https://typesense.org/docs/30.2/api/server-configuration.html
4. 健康检查端点：https://typesense.org/docs/30.2/api/health.html
5. 快照 API：https://typesense.org/docs/30.2/api/server-operations.html