Static User Provider

GreptimeDB 提供了简单的内置身份验证机制，允许你配置一个固定的帐户以方便使用，或者配置一个帐户文件以支持多个用户帐户。通过传入文件，GreptimeDB 会加载其中的所有用户。

单机模式

GreptimeDB 从配置文件中读取用户配置，每行定义一个用户及其密码和可选的权限模式。

基本配置

基本格式使用 = 作为用户名和密码之间的分隔符：

greptime_user=greptime_pwd
alice=aaa
bob=bbb

以这种方式配置的用户默认拥有完整的读写权限。

权限模式

你可以选择性地指定权限模式来控制用户的访问级别。格式为：

username:permission_mode=password

可用的权限模式：

• rw 或 readwrite - 完整的读写权限（未指定时的默认值）
• ro 或 readonly - 只读权限
• wo 或 writeonly - 只写权限

混合权限模式的配置示例：

admin=admin_pwd
alice:readonly=aaa
bob:writeonly=bbb
viewer:ro=viewer_pwd
editor:rw=editor_pwd

在此配置中：

• admin 拥有完整的读写权限（默认）
• alice 拥有只读权限
• bob 拥有只写权限
• viewer 拥有只读权限
• editor 明确设置了读写权限

密码格式

从 v1.1 起，密码可以使用显式的 verifier 格式，从而无需在配置文件中保存明文密码。默认情况下密码以明文存储：

• plain:<password> — 明文。未指定前缀时的默认格式。
• pbkdf2_sha256:<iterations>:<hex_salt>:<hex_hash> — 以 PBKDF2-SHA256 哈希形式存储。
• mysql_native_password:<hex_sha1_sha1_password> — 哈希形式的 verifier，同时仍可服务 MySQL mysql_native_password 握手。
• pg_scram_sha256:<iterations>:<hex_salt>:<hex_stored_key>:<hex_server_key> — SCRAM-SHA-256 verifier，用于 PostgreSQL 的 SASL 握手。从 v1.2 起支持。

示例：

admin=plain:admin_pwd
alice=pbkdf2_sha256:4096:73616c74:c5e478d59288c841aa530db6845c4c8d962893a001ce4e11a4963873aa98134a
bob=mysql_native_password:6bb4837eb74329105ee4568dda7dc67ed2ca2ad9
carol=pg_scram_sha256:4096:73616c74:53706a13f10b3c031b4c355d75ebd6500d3478062ce7d262710c3e60de02b93f:a19ce79824bd7ad68d96b8c00b0f1cc776bd0feca54d663301bb9866a860545b

权限模式可与 verifier 格式组合使用，verifier 写在 = 之后：

alice:readonly=pbkdf2_sha256:4096:73616c74:c5e478d59288c841aa530db6845c4c8d962893a001ce4e11a4963873aa98134a

协议兼容性

单一 verifier 格式无法服务所有协议。请根据客户端的连接方式选择格式：

Verifier	HTTP/gRPC Basic	PostgreSQL SCRAM-SHA-256	PostgreSQL cleartext	MySQL clear password	MySQL mysql_native_password
plain:<password>（或旧式 user=password）	是	是	是	是	是
pbkdf2_sha256:...	是	否	是	是	否
mysql_native_password:...	否	否	否	否	是
pg_scram_sha256:...	是	是	是	是	否

pbkdf2_sha256 只保护静态存储的密码，并不改变链路安全性。支持明文传输的协议在生产环境中仍需启用 TLS。

破坏性变更

密码现在按前缀解析。如果旧式明文密码恰好以 plain:、pbkdf2_sha256:、mysql_native_password: 或 pg_scram_sha256: 开头，其含义会发生变化。请使用 plain: 前缀保留字面值。例如，若要保留字面密码 plain:secret，应配置为 user=plain:plain:secret。

PostgreSQL SCRAM-SHA-256

SCRAM-SHA-256 让 PostgreSQL 客户端不必以明文发送密码。

PostgreSQL 在连接建立时就要确定唯一一种鉴权方式。此时服务端其实已经拿到了用户名，但如果按用户来选鉴权方式，就会暴露这个用户是否存在、以及它用的是哪种 verifier 格式。所以 GreptimeDB 是全局判断的：只有凭证文件里所有用户都支持 SCRAM 时才提供 SCRAM——也就是所有 verifier 都是 plain: 或 pg_scram_sha256:。对于不存在的用户名，服务端会用一个临时构造的 verifier 走完整个握手流程，因此登录失败和密码错误在客户端看来是一样的。

注意

只要有一个 pbkdf2_sha256: 或 mysql_native_password: 用户，整个实例的 PostgreSQL 鉴权就会退回明文，包括那些自身 verifier 支持 SCRAM 的用户。想用 SCRAM 就不要混用 verifier 格式。

不支持 channel binding（SCRAM-SHA-256-PLUS）。

可以用 libpq 的 require_auth 参数确认服务端提供的是哪种方式，这个参数需要 libpq 或 psql 16 及以上版本：

psql "host=127.0.0.1 port=4003 user=carol dbname=public require_auth=scram-sha-256"

如果实例已经退回明文，这条命令会报 server requested a cleartext password。

生成密码 Verifier

从 v1.1 起，可以使用 greptime user hash-password 命令生成 verifier 字符串。该命令独立运行，不会启动任何服务端组件：

./greptime user hash-password --password-stdin

它从标准输入读取明文密码，并将 verifier 打印到标准输出。交互式运行时，输入密码后按回车；在脚本中，使用不回显的方式读取再通过管道传入，避免明文出现在 shell 历史或进程列表中：

read -rs PASSWORD && printf '%s' "$PASSWORD" | ./greptime user hash-password --password-stdin

将输出复制到用户文件中作为密码：

admin=pbkdf2_sha256:4096:<random_hex_salt>:<hex_hash>

可用选项：

• --format <FORMAT> — verifier 格式，pbkdf2_sha256（默认）、mysql_native_password 或 pg_scram_sha256。
• --password <PASSWORD> — 明文密码。与 --password-stdin 互斥，二者必须且只能指定其一。脚本中优先使用 --password-stdin，因为 --password 可能通过 shell 历史或进程列表泄露。
• --password-stdin — 从标准输入读取明文密码。
• --iterations <N> — PBKDF2-SHA256 / SCRAM-SHA-256 迭代次数（默认 4096，范围 1..=1000000）。
• --salt-len <N> — 随机盐长度，单位字节（默认 16，范围 1..=1024）。
• --salt-hex <HEX> — 使用固定的十六进制盐替代随机盐，用于确定性的自动化场景。

生成 mysql_native_password 格式的 verifier：

./greptime user hash-password --password-stdin --format mysql_native_password

生成 PostgreSQL SCRAM-SHA-256 格式的 verifier：

./greptime user hash-password --password-stdin --format pg_scram_sha256

启动服务器

在启动服务端时，需添加 --user-provider 参数，并将其设置为 static_user_provider:file:<path_to_file>（请将 <path_to_file> 替换为你的用户配置文件路径）：

./greptime standalone start --user-provider=static_user_provider:file:<path_to_file>

用户及其权限将被载入 GreptimeDB 的内存。使用这些用户账户连接至 GreptimeDB 时，系统会严格执行相应的访问权限控制。

注意

static_user_provider:file 模式下，文件的内容只会在启动时被加载到数据库中，在数据库运行时修改或追加的内容不会生效。

动态文件重载

如果你需要在不重启服务器的情况下更新用户凭证，可以使用 watch_file_user_provider 替代 static_user_provider:file。该 provider 会监控凭证文件的变化并自动重新加载：

./greptime standalone start --user-provider=watch_file_user_provider:<path_to_file>

watch_file_user_provider的特点：

• 使用与 static_user_provider:file 相同的文件格式
• 自动检测文件修改并重新加载凭证
• 允许在不重启服务器的情况下添加、删除或修改用户
• 如果文件临时不可用或无效，会保持上次有效的配置

这在需要动态管理用户访问的生产环境中特别有用。

Kubernetes 集群

你可以在 values.yaml 文件中配置鉴权用户。 更多详情，请参考 Helm Chart 配置。