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 是一款高性能的开源 Web / 反向代理服务器。
下面将介绍在 Ubuntu 中使用 apt 安装(非源码,官方源):
# 更新软件索引
sudo apt update
# 安装 nginx
sudo apt install nginx -y安装成功后,检查版本 & 验证:

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

如果你的网关统一发 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 暴露在公网,很危险。