Chroma 教程 收藏

鉴权:在反向代理层做

🎉摘要:Chroma 1.x Rust 版本移除内置鉴权模块,无法直接暴露公网。本文介绍通过 Nginx 反向代理实现安全部署,包括 Chroma 仅监听内网、Nginx 承担 TLS 证书、Basic Auth 身份校验、Bearer Token 鉴权以及限流等防护,并给出详细配置与客户端连接示例。

Chroma 1.x(Rust 重写版本)已经移除了内置鉴权模块,没有自带账号、Token 认证能力,旧的 CHROMA_SERVER_AUTHN_* 一系列环境变量全部失效、不再生效 。所以 Chroma 服务只能监听内网,对外用 Nginx 挡一层,Nginx 实现鉴权。

Chroma 安全部署原则如下:

(1)chroma run 后端本身只监听内网 / 127.0.0.1,不要直接暴露公网。

(2)对外暴露的是 Nginx,由 Nginx 承担:

  • TLS 证书(HTTPS)

  • 身份校验(BasicAuth / Bearer Token)

  • 限流、IP 黑名单、请求大小限制、CORS

(3)Nginx 校验通过之后,才转发请求到内网 Chroma。校验失败直接拦截,流量根本到不了 Chroma。

安装 Nginx

Nginx 是一款高性能的开源 Web / 反向代理服务器。

下面将介绍在 Ubuntu 中使用 apt 安装(非源码,官方源):

# 更新软件索引
sudo apt update

# 安装 nginx
sudo apt install nginx -y

安装成功后,检查版本 & 验证:

Nginx + Basic Auth

Basic Auth 指 HTTP Basic Authentication(基础认证),是一种标准简单的 HTTP 身份校验方式:

(1)客户端请求时,在请求头带上 Authorization: Basic <base64(username:password)>

(2) 浏览器访问时,如果没有携带这个头,会自动弹出账号密码输入弹窗

(3)Nginx 收到请求后,读取用户名密码,和本地 .htpasswd 文件内存储的加密密码比对

(3)校验通过 → 转发请求给后端(你的 Chroma);校验失败 → 返回 401 Unauthorized,拒绝访问

注意:Basic Auth 的账号密码只是做 Base64 编码,不是加密!裸 HTTP 传输极易被抓包还原。生产环境必须搭配 HTTPS(SSL/TLS)使用。

使用 apt install 安装 apache2-utils( 它提供 htpasswd 工具,用来生成、维护 username:加密密码 格式的认证文件,Nginx 原生识别这个格式):

# 安装工具
sudo apt install apache2-utils

# 生成密码文件
htpasswd -c /etc/nginx/.chroma_htpasswd myuser

执行过程如下:

# 生成密码文件,myuser 是用户名
root@localhost:/etc/nginx# htpasswd -c /etc/nginx/.chroma_htpasswd myuser
New password: 密码
Re-type new password: 确认密码
Adding password for user myuser

# 查看密码文件
root@localhost:/etc/nginx# cat /etc/nginx/.chroma_htpasswd
myuser:$apr1$/ApM7k43$K.vK1Wu4bwgZwDnm0zm8S0

配置 nginx,进入到 /etc/nginx/sites-enabled 目录,创建 chroma 文件,文件内容如下:

# /etc/nginx/sites-enabled/chroma
upstream chroma {
    server 127.0.0.1:8000;
}

server {
    listen 8080;
    server_name localhost;

    # 请求体上限,别太小,批量写入会超
    client_max_body_size 64m;

    location / {
        auth_basic "Chroma";
        auth_basic_user_file /etc/nginx/.chroma_htpasswd;

        proxy_pass http://chroma;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 检索可能稍慢,超时放宽一点
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }

    # 健康检查不鉴权
    location = /api/v2/heartbeat {
        proxy_pass http://chroma;
        access_log off;
    }
}

注意:

为什么要将配置文件 /etc/nginx/sites-enabled 目录下面,这是因为在 nginx.conf 配置文件中,指定了导入目录,如下:

执行如下命令重新加载 nginx(nginx -t 用来检测 nginx 配置文件语法是否正确,通过了才会执行后面的 reload nginx):

sudo nginx -t && sudo systemctl reload nginx

命令执行成功后,使用 netstat -ano 命令查看一下端口情况:

8080 和 8000 端口都正常。

客户端连接:

import base64
import chromadb

user, pwd = "myuser", "123456"
token = base64.b64encode(f"{user}:{pwd}".encode()).decode()

client = chromadb.HttpClient(
    host="localhost",
    port=8080,
    ssl=False,
    headers={"Authorization": f"Basic {token}"},
)
print(client.heartbeat()) # 1794306412257887061

看见了吗?正常输出了时间戳信息,成功了。如果将密码修改,再次运行,将返回如下错误:

Nginx + Bearer Token

如果你的网关统一发 JWT,可以用 auth_request 模块把鉴权交给外部服务,这里给个简化版(用 map 做静态 token 校验):

map $http_authorization $chroma_allowed {
    default 0;
    "Bearer my-secret-token" 1;
}

server {
    listen 443 ssl;
    server_name chroma.example.com;

    location / {
        if ($chroma_allowed = 0) {
            return 401;
        }
        proxy_pass http://chroma;
        proxy_set_header Host $host;
    }
}

生产环境别这么写死 token,用 auth_request 转发到你的鉴权服务。

什么是 auth_request?

auth_request 是 Nginx 的外部子请求鉴权模块(ngx_http_auth_request_module),核心思想:Nginx 收到请求后,先发起一个内部子请求,去调用独立的认证服务;根据认证服务返回的 HTTP 状态码,决定放行还是拦截原始请求

网络层的保险

就算加了鉴权,也建议:

  • Chroma 只监听 127.0.0.1,不对外暴露端口

  • 用防火墙(ufw / 安全组)限制访问来源 IP

  • 走内网/VPN 访问

最后提示,生产环境一定不要将 Chroma 暴露在公网,很危险。

  

说说我的看法
全部评论()
没有评论
关于
本网站专注于 Java、数据库(MySQL、Oracle)、Linux、软件架构及大数据等多领域技术知识分享。涵盖丰富的原创与精选技术文章,助力技术传播与交流。无论是技术新手渴望入门,还是资深开发者寻求进阶,这里都能为您提供深度见解与实用经验,让复杂编码变得轻松易懂,携手共赴技术提升新高度。如有侵权,请来信告知:hxstrive@outlook.com
其他应用
公众号