使用 Docker Compose 一键部署 Chroma 向量数据库（RAG 必备）

17次阅读

Chroma 是轻量开源向量数据库，非常适合本地 RAG、知识库检索、语义搜索。用 docker compose 部署，一行命令拉起，数据持久化，开箱即用，不用折腾 Python 环境。

一、前置条件

已安装 Docker + Docker Compose（新版 docker 内置 compose，命令为docker compose，不带短横线）
服务器 / 本地机器开放 8000 端口（可自行修改端口映射）
磁盘空间：基础镜像很小，数据量取决于你的向量文档数量

验证环境：

docker -v
docker compose version

二、编写 docker-compose.yml

新建一个文件夹，例如 chroma-stack，进入目录创建 docker-compose.yml，内容如下：

services:
  chromadb:
    image: chromadb/chroma:latest
    container_name: chromadb
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      # 持久化向量数据，容器删除数据不会丢失
      - chroma-data:/data
    environment:
      - IS_PERSISTENT=TRUE
      - ANONYMIZED_TELEMETRY=FALSE
      - CHROMA_SERVER_LOG_LEVEL=INFO
      # 生产环境建议关闭重置接口
      - CHROMA_ALLOW_RESET=FALSE
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat"]
      interval: 10s
      timeout: 5s
      retries: 3
    networks:
      - chroma-net

volumes:
  chroma-data:
    driver: local

networks:
  chroma-net:
    driver: bridge

配置说明

image：chromadb/chroma 官方镜像，推荐固定版本号，避免 latest 意外升级
volumes：chroma-data 命名卷，向量库、集合、embedding 索引全部保存在这里，重点！没有卷，重启容器数据全部丢失Chroma
环境变量
- IS_PERSISTENT=TRUE：开启持久化存储
- ANONYMIZED_TELEMETRY=FALSE：关闭匿名遥测上报
- CHROMA_ALLOW_RESET=FALSE：禁止调用 reset 清空全量数据，生产环境务必关闭，本地测试可改为 TRUE
- CHROMA_SERVER_LOG_LEVEL：日志级别，可选 DEBUG / INFO / WARN / ERROR
healthcheck：健康检查，compose 会自动判断服务是否正常启动
restart: unless-stopped：容器意外退出自动重启，宿主机重启后自动拉起

三、启动服务

在 docker-compose.yml 所在目录执行：

docker compose up -d

-d：后台守护进程运行

查看日志：

docker compose logs -f chromadb

查看容器状态：

docker compose ps

服务启动成功后，访问地址：

http://localhost:8000/api/v1/heartbeat

返回 {"nanosecond_heartbeat":xxxx} 代表服务正常。

四、Python SDK 简单测试连接

安装依赖：

pip install chromadb

测试代码：

import chromadb

# 连接远程chroma服务
client = chromadb.HttpClient(host="localhost", port=8000)

# 创建集合
collection = client.create_collection(name="demo_kb")

# 写入向量数据
collection.add(
    documents=["Docker Compose部署Chroma向量数据库", "Chroma用于RAG知识库"],
    metadatas=[{"source": "blog"}],
    ids=["doc1", "doc2"]
)

# 语义检索
res = collection.query(
    query_texts=["向量数据库部署"],
    n_results=1
)
print(res)

如果是远端服务器部署，把host替换成服务器 IP，同时注意防火墙放行 8000 端口。

五、常用运维命令

# 停止服务（保留数据卷）
docker compose down

# 停止并删除数据卷（⚠️ 向量数据全部清空！谨慎使用）
docker compose down -v

# 重启服务
docker compose restart chromadb

# 查看存储卷位置
docker volume inspect chroma-stack_chroma-data

六、进阶配置（生产环境可选）

1. 开启跨域 CORS

前端网页直接访问 chroma 接口时，添加环境变量：

- CHROMA_SERVER_CORS_ALLOW_ORIGINS='["http://localhost:3000"]'

多个域名逗号分隔，开发临时测试可写["*"]，生产不建议。

2. 开启基础认证（Basic Auth）

增加身份校验，防止公开访问：

- CHROMA_SERVER_AUTHN_PROVIDER=chromadb.auth.basic.BasicAuthServerProvider
- CHROMA_SERVER_AUTHN_CREDENTIALS=admin:123456

生产不要明文写密码，推荐使用外部 htpasswd 文件挂载。

3. 自定义配置文件挂载

新建chroma_config.yaml，挂载到容器内：

volumes:
  - ./chroma_config.yaml:/chroma/config.yaml:ro

七、常见踩坑点

重启容器后数据丢失：忘记挂载 volume，本地测试最常见问题。
外部无法访问 8000 端口：检查宿主机防火墙、安全组，确认端口放行；不要绑定 127.0.0.1。
连接超时：确认容器内服务监听 0.0.0.0，chroma 默认配置无需额外修改 host。
版本兼容：Python SDK 版本和服务端 chroma 版本尽量保持一致，否则会出现 API 报错。

八、总结

Chroma 搭配 Docker Compose 是本地 RAG、私有知识库最简单的向量库方案。优势： ✅ 部署极简，一条命令启动 ✅ 数据持久化，容器销毁不丢向量 ✅ 可扩展，方便和 Ollama、LangChain、FastAPI 组合成完整 RAG 栈 ✅ 轻量，资源占用低，个人电脑、小服务器都能跑