codenotary/immudb

immudb

概述

immudb是一个具有内置加密证明和验证功能的数据库，旨在跟踪敏感数据的变更并确保数据历史的完整性。其核心特性是不可变性：用户可添加现有记录的新版本，但无法修改或删除已有记录，从而防止数据被篡改。immudb同时支持键值存储和关系型数据库（SQL）两种模式，能处理百万级事务/秒，可作为独立服务部署或嵌入应用中，适用于从IoT设备到云端的多种环境。

核心功能与特性

核心能力

• 不可变性：数据一旦写入无法修改或删除，仅可添加新版本，确保历史记录完整。
• 加密验证：数据存储具有密码学一致性，客户端可独立验证数据完整性，无需信任数据库服务。
• 多模式支持：同时作为键值存储（支持3D访问：tx-key-value）和关系型数据库（SQL）运行。
• 高性能：支持每秒数百万事务，远超传统***方案。
• 可嵌入性：可作为库嵌入应用，也可独立部署为服务。

技术规格

使用场景

immudb适用于需确保数据完整性和防篡改的场景，典型案例包括：

• 存储敏感数据库字段（如***、银行账户）的每次更新记录
• 保护CI/CD构建和部署流程中的配方（recipe）数据
• 存储公钥证书和数字对象校验和
• 记录审计日志、系统日志等需防篡改的日志流
• 存储物联网设备（如传感器、渔船、潜艇）的位置或状态数据
• 作为不可变的审计追踪系统，确保关键操作可追溯

使用方法

Docker部署

基本运行

使用Docker快速启动immudb容器：

bash
# 使用host网络（推荐，直接使用主机网络栈）
docker run -d --net host -it --rm --name immudb codenotary/immudb:latest

# 非host网络（需暴露端口）
docker run -d -p 3322:3322 -p 9497:9497 -it --rm --name immudb codenotary/immudb:latest

说明：3322为gRPC API端口，9497为其他服务端口。

持久化存储

如需持久化数据，挂载本地目录：

bash
docker run -d -p 3322:3322 -p 9497:9497 -v /path/to/local/data:/var/lib/immudb -it --rm --name immudb codenotary/immudb:latest

Kubernetes部署

通过Helm Chart部署：

bash
# 添加Helm仓库
helm repo add immudb https://packages.codenotary.org/helm
helm repo update

# 安装immudb（自动生成名称）
helm install immudb/immudb --generate-name

存储配置（子路径设置）

Helm Chart默认使用持久卷的子路径（如immudb目录）存储数据，避免与卷根目录下的系统文件（如/lost+found）冲突。如需禁用子路径或修改路径：

bash
# 禁用子路径（适用于已有数据迁移）
helm install immudb/immudb --generate-name --set volumeSubPath.enabled=false

# 自定义子路径
helm install immudb/immudb --generate-name --set volumeSubPath.path=my-subdir

配置参数

环境变量

immudb支持通过环境变量配置，关键参数如下：

S3存储示例

配置immudb使用Amazon S3或兼容服务（如MinIO）存储数据：

bash
export IMMUDB_S3_STORAGE=true
export IMMUDB_S3_ACCESS_KEY_ID=AKIAEXAMPLE
export IMMUDB_S3_SECRET_KEY=secret
export IMMUDB_S3_BUCKET_NAME=my-immudb-bucket
export IMMUDB_S3_LOCATION=us-east-1
export IMMUDB_S3_PATH_PREFIX=immudb-data
export IMMUDB_S3_ENDPOINT="https://my-immudb-bucket.s3.us-east-1.amazonaws.com"

# 启动容器（传递环境变量）
docker run -d -p 3322:3322 -p 9497:9497 \
  -e IMMUDB_S3_STORAGE=true \
  -e IMMUDB_S3_ACCESS_KEY_ID=AKIAEXAMPLE \
  -e IMMUDB_S3_SECRET_KEY=secret \
  -e IMMUDB_S3_BUCKET_NAME=my-immudb-bucket \
  -e IMMUDB_S3_LOCATION=us-east-1 \
  -e IMMUDB_S3_PATH_PREFIX=immudb-data \
  -e IMMUDB_S3_ENDPOINT="https://my-immudb-bucket.s3.us-east-1.amazonaws.com" \
  --name immudb codenotary/immudb:latest

客户端连接

使用官方客户端immuclient连接immudb：

Docker客户端

bash
# 交互式连接（需与immudb在同一网络）
docker run -it --rm --net host --name immuclient codenotary/immuclient:latest

# 执行单条命令
docker run -it --rm --net host codenotary/immuclient:latest help

基本操作示例

bash
# 连接后设置键值对
immuclient> set mykey "sensitive data"

# 获取并验证键值
immuclient> get mykey

# 查看历史版本
immuclient> history mykey

开发集成

immudb提供多语言SDK，方便应用集成：

• Java：https://github.com/codenotary/immudb4j
• Golang：https://pkg.go.dev/github.com/codenotary/immudb/pkg/client%E3%80%81https://github.com/codenotary/immugorm
• .NET：https://github.com/codenotary/immudb4net
• Python：https://github.com/codenotary/immudb-py
• Node.js：https://github.com/codenotary/immudb-node

更多文档和示例可参考 官方文档 或 https://github.com/codenotary/immudb-client-examples%E3%80%82

许可证

immudb基于 https://github.com/codenotary/immudb/blob/master/LICENSE 开源。