向量数据库-认识Chroma并安装配置密码访问

Chroma 向量数据库学习指南

基于 Node.js / TypeScript、专门讲解 Chroma 的安装、核心概念、完整 API 用法和生产注意事项。

1. Chroma 是什么

Chroma 是一个开源的向量数据库，专为 AI 应用设计。和普通数据库存储结构化数据不同，Chroma 存储的是向量（高维数字数组），并能根据向量之间的相似度进行检索。

和普通数据库的核心区别

普通数据库（MySQL）：
  查询："找出 name = '张三' 的记录"  → 精确匹配

向量数据库（Chroma）：
  查询："找出和 '什么是量子纠缠' 语义最相似的内容"  → 语义匹配

Chroma 的定位

2. 安装与启动

Chroma 分为服务端（数据库进程）和客户端（你的代码）两部分。

2.1 启动 Chroma 服务端

方式一：Docker（推荐，最简单）

# 下载镜像
docker pull chromadb/chroma
# 启动 Chroma，数据持久化到本地 ./chroma_data 目录
docker run -d \
  --name chromadb \
  -p 8000:8000 \
  -v $(pwd)/chroma_data:/chroma/chroma \
  chromadb/chroma:latest

# 验证是否启动成功
curl http://localhost:8000/api/v2/heartbeat
# 返回 {"nanosecond heartbeat": 123456789} 表示成功

我们的文档就是以docker安装为例的

方式二：pip 安装（需要 Python 环境）

pip install chromadb
# 启动服务，数据存在 ./chroma_data
chroma run --path ./chroma_data --port 8000

方式三：纯内存模式（仅用于测试，重启数据丢失）

// 代码内直接创建，无需启动服务端
// 见第 4 节的内存模式示例

2.2 安装 TypeScript 客户端

npm install chromadb

2.3 验证连接

import { ChromaClient } from 'chromadb'
const client = new ChromaClient({
    path: 'http://192.168.31.249:8000',
});
async function main() {
    // 心跳检测
    const heartbeat = await client.heartbeat()
    console.log('Chroma 连接正常：', heartbeat)
    // 查看版本
    const version = await client.version()
    console.log('Chroma 版本：', version)
}
main();

目前使用 path 参数连接数据库已经不再被推荐了，官方推荐的是使用：ssl、host、port 的方式进行连接：

import { ChromaClient } from 'chromadb'
const client = new ChromaClient({
    ssl: false, // 是否使用https
    host: '192.168.31.249',
    port: 8000
});

2.4 设置密码

我们前面连接chromadb服务端的时候，并没有提供密码就能访问，这意味着所有人只要地址到host地址和端口，都可以进行数据库连接，很明显这是不安全的。我们需要对连接进行验证，早期版本内置的有验证功能，但是从v1.0.x 以后得版本，则移除了这个功能，因此我们要部署到内网中，然后在chromadb 之前加一层反向代理，使用反向代理进行验证。我们这里以使用Nginx作为反向代理。

• 首先安装 htpasswd 库

   # Ubuntu/Debian：sudo apt-get install apache2-utils -y
   # RHEL 系请用：
   dnf install nginx httpd-tools -y
  

• 创建用户名密码

  htpasswd -c /etc/nginx/.chromadbPasswd admin
  

  然后会提示让输入密码和重复输入密码

• 配置 Nginx 反向代理 + 鉴权

  vim /etc/nginx/conf.d/chroma.conf
  

  增加配置：

  server {
      listen 7777;
      server_name _;
  
      # ===== Basic Auth =====
      auth_basic "Chroma Protected";
      auth_basic_user_file /etc/nginx/.chromadbPasswd;
  
      location / {
          proxy_pass http://127.0.0.1:8000;
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      }
  }
  

  别忘了重载nginx配置：nginx -s reload

• 验证鉴权是否生效

  curl http://192.168.31.249:7777/api/v2/heartbeat
  

• 一定要注意，Chroma 只监听本机，不然别人还是能通过原地址访问

  docker run -d \
    --name chromadb \
    -p 127.0.0.1:8000:8000 \
    -v $(pwd)/chroma_data:/chroma/chroma \
    chromadb/chroma:latest
  

• 然后我们使用客户端连接的时候传入验证信息就行了

  import { ChromaClient } from 'chromadb'
  // 生成密码
  const auth = Buffer.from("admin:123456").toString("base64");
  const client = new ChromaClient({
      ssl: false,
      host: '192.168.31.249',
      port: 7777,
      headers: {
          Authorization: `Basic ${auth}`,
      },
  });
  async function main() {
      // 心跳检测
      const heartbeat = await client.heartbeat();
  }
  main()
  

  如果能正确打印出信息，就表示连接成功，连接不成功会抛出异常