From 0a7c719b628bb66eeb1bd5c4b08377f575d70f4f Mon Sep 17 00:00:00 2001 From: YinBo Date: Tue, 17 Mar 2026 20:36:27 +0800 Subject: [PATCH 1/4] docs: optimized docs --- zh_CN/admin/backup-restore.md | 21 ++++++++----- zh_CN/admin/datalayers-cli.md | 27 +++++++++------- zh_CN/admin/datalayers-configuration.md | 27 +++++++++++++--- zh_CN/admin/optimize-configuration.md | 8 +++++ zh_CN/admin/system-metrics.md | 26 ++++++++++++++-- zh_CN/admin/system-monitor-grafana.md | 6 ++++ zh_CN/admin/system-tune.md | 27 ++++++++++++++++ zh_CN/development-guide/connection.md | 2 +- .../development-guide/postgresql/overview.md | 5 +++ .../development-guide/prometheus/overview.md | 6 ++++ .../table-design/overview.md | 6 ++++ zh_CN/fulltext-search/overview.md | 31 ++++++++++++------- zh_CN/fulltext-search/quick-start.md | 20 +++++++----- zh_CN/getting-started/centos.md | 10 ++++-- zh_CN/getting-started/command-line-tool.md | 12 +++++-- zh_CN/getting-started/docker.md | 7 ++++- zh_CN/getting-started/ubuntu.md | 4 +-- zh_CN/index.md | 18 ++++++++--- zh_CN/integration/datalayers-with-dbeaver.md | 3 +- zh_CN/integration/datalayers-with-grafana.md | 7 ++++- .../datalayers-with-opentelemetry.md | 29 ++++++++++++----- zh_CN/key-value-data-model/quick-start.md | 4 ++- zh_CN/streaming/overview.md | 9 +++--- zh_CN/user-security/audit-logs.md | 14 +++++++++ .../user-security/authentication/overview.md | 6 ++++ zh_CN/user-security/authentication/static.md | 9 ++++-- zh_CN/user-security/password-policy.md | 8 +++++ zh_CN/user-security/rbac/overview.md | 6 ++++ zh_CN/user-security/tls.md | 2 ++ zh_CN/vector-search/overview.md | 12 ++++--- zh_CN/vector-search/quick-start.md | 4 +-- 31 files changed, 293 insertions(+), 83 deletions(-) diff --git a/zh_CN/admin/backup-restore.md b/zh_CN/admin/backup-restore.md index 7efa09b1..53c4883a 100644 --- a/zh_CN/admin/backup-restore.md +++ b/zh_CN/admin/backup-restore.md @@ -8,11 +8,13 @@ description: "Datalayers 数据备份与恢复指南：介绍 dldump 的核心 数据库备份和恢复用于保护数据安全、防止数据丢失或损坏。通过定期备份，可在系统故障、硬件损坏或人为错误时，将数据库恢复到最近可用状态，确保业务连续性与数据完整性。本文主要介绍数据备份与恢复能力。 +`dldump` 是 Datalayers 提供的数据导出与导入工具，适合用于单库、单表或全库级别的备份恢复操作。 + ## 工具使用说明 `dldump` 工具提供了丰富的选项以供配置，您可以通过执行 `dldump --help` 以查看 `dldump` 的所有子命令和选项。此处对一些重要的选项进行说明： -| 参数 |
简写
| 描述 | +| 参数 | 简写 | 描述 | | --- | --- | --- | | --host | -h | 指定 Datalayers 实例的地址，默认为：127.0.0.1 | | --port | -P | 指定 Datalayers 实例的 SQL 服务端口，默认为：8360 | @@ -20,15 +22,15 @@ description: "Datalayers 数据备份与恢复指南：介绍 dldump 的核心 | --password | -p | 指定用于鉴权的密码，默认为：public | | --output | -o | 指定备份时数据的存储路径。为了避免用户无意间覆盖之前的备份，要求导出时指定的目录为空 | | --input | -i | 指定恢复时数据的加载路径。如果指定的目录为空，则会中止恢复操作 | -| --meta | | 指定备份时是否要包含元信息（如：建库和建表语句），默认包含元信息。如果不备份元信息，您可以传入 --meta false | -| --data | | 指定备份时是否要包含表数据，默认包含表数据。如果要求不备份表数据，您可以传入 --data false | +| --meta | - | 指定备份时是否要包含元信息（如：建库和建表语句），默认包含元信息。如果不备份元信息，您可以传入 --meta false | +| --data | - | 指定备份时是否要包含表数据，默认包含表数据。如果要求不备份表数据，您可以传入 --data false | | --database | -d | 指定备份或恢复的数据库。如果不显式设定该选项，则默认转储所有数据库 | | --table | -t | 指定备份或恢复的表。如果指定了 table，则必须指定 database。如果不显式设定该选项，则默认备份 database 下所有表 | | --max-file-size | -s | 指定一个数据文件大小的最大值，默认为 8GiB。只支持整型作为合法的输入。单位为：GiB | -| --start | | 指定一个时间戳，时间戳大于或等于 start 的表数据才会被备份。合法的日期格式和整型均认为是合法的时间戳 | -| --end | | 指定一个时间戳，时间戳小于或等于 end 的表数据才会被备份。合法的日期格式和整型均认为是合法的时间戳 | -| --tls | | 通过 TLS 加密方式与数据库进行交互。自签证书则需指定 root ca，如：--tls /etc/datalayers/datalayers.crt | -| --help | | show this help, then exit | +| --start | - | 指定一个时间戳，时间戳大于或等于 start 的表数据才会被备份。合法的日期格式和整型均认为是合法的时间戳 | +| --end | - | 指定一个时间戳，时间戳小于或等于 end 的表数据才会被备份。合法的日期格式和整型均认为是合法的时间戳 | +| --tls | - | 通过 TLS 加密方式与数据库进行交互。自签证书则需指定 root ca，如：--tls /etc/datalayers/datalayers.crt | +| --help | - | show this help, then exit | ## 备份与恢复 @@ -170,3 +172,8 @@ test> SELECT * FROM device; +---------------------------+-----+-------+------+ 10 rows in set (0.002 sec) ``` + +## 下一步 + +- 想了解连接与查询验证，请参考 [Datalayers 命令行工具 dlsql 使用指南](../getting-started/command-line-tool.md) +- 想了解服务配置与数据目录设置，请参考 [配置文件介绍](./datalayers-configuration.md) diff --git a/zh_CN/admin/datalayers-cli.md b/zh_CN/admin/datalayers-cli.md index d3c04666..cd43abd6 100644 --- a/zh_CN/admin/datalayers-cli.md +++ b/zh_CN/admin/datalayers-cli.md @@ -57,12 +57,9 @@ sudo -u datalayers dlsql **Peer 认证注意事项**： -- **认证限制** - - 仅限本地访问：Peer 认证仅支持通过 Unix Socket 的本地连接 -- **连接端权限要求**：连接端账号必须满足以下条件之一： - - 具备超级管理员权限（root 用户） - - 用户的 UID 与数据库服务运行时的 UID 完全一致 -- **权限**：通过 Peer 认证建立的连接将获得系统级最高权限 +- 仅限本地访问：Peer 认证仅支持通过 Unix Socket 的本地连接 +- 连接端账号必须满足以下条件之一：具备超级管理员权限，或用户 UID 与数据库服务运行时的 UID 完全一致 +- 通过 Peer 认证建立的连接将获得系统级最高权限 - 配置 `Unix Socket` 服务后，需重启 Datalayers，以确保服务生效 ## Web 控制台 @@ -79,7 +76,7 @@ dlsql --web-console 9362 ## 连接参数详解 -| 参数 |
简写
| 描述 | +| 参数 | 简写 | 描述 | | --- | --- | --- | | --host | -h | 设置连接 Datalayers 服务器地址, 默认为本地路径通过 Unix Socket 方式连接: /var/lib/datalayers/run/datalayers.sock | | --username | -u | 设置连接 Datalayers 使用的用户名 | @@ -87,9 +84,15 @@ dlsql --web-console 9362 | --port | -P | 设置连接 Datalayers 的端口 | | --database | -d | 设置连接 Datalayers 时使用的数据库 | | --execute | -e | 运行一次 SQL STATEMENT 后退出 | -| --load-file | | 执行指定的 SQL 脚本文件 | -| --web-console | | 指定 Web 控制台的监听端口并启动 Web 控制台 | +| --load-file | - | 执行指定的 SQL 脚本文件 | +| --web-console | - | 指定 Web 控制台的监听端口并启动 Web 控制台 | | --version | -V | 显示 CLI 工具的版本 | -| --tls | | 通过 TLS 加密方式与数据库进行交互。自签证书则需指定 root ca，如：--tls /etc/datalayers/datalayers.crt | -| --max-display-rows | | 在使用 `dlsql` 查询数据时最多显示多少条记录，缺省值为：`40`，如需显示更多记录，则需通过该参数进行指定（`0` 表示无限制） | -| --help | | show this help, then exit | +| --tls | - | 通过 TLS 加密方式与数据库进行交互。自签证书则需指定 root ca，如：--tls /etc/datalayers/datalayers.crt | +| --max-display-rows | - | 在使用 `dlsql` 查询数据时最多显示多少条记录，缺省值为：`40`，如需显示更多记录，则需通过该参数进行指定（`0` 表示无限制） | +| --help | - | show this help, then exit | + +## 下一步 + +- 想快速完成连接、建库和查询，请参考 [Datalayers 命令行工具 dlsql 使用指南](../getting-started/command-line-tool.md) +- 想了解服务参数与认证配置，请参考 [配置文件介绍](./datalayers-configuration.md) +- 想通过浏览器或图形化工具访问实例，请参考 [Datalayers 集成 DBeaver 指南](../integration/datalayers-with-dbeaver.md) diff --git a/zh_CN/admin/datalayers-configuration.md b/zh_CN/admin/datalayers-configuration.md index d59be755..ab53c101 100644 --- a/zh_CN/admin/datalayers-configuration.md +++ b/zh_CN/admin/datalayers-configuration.md @@ -6,6 +6,15 @@ description: "Datalayers 配置文件介绍：说明 datalayers.toml 的路径 本文介绍 Datalayers 配置文件的结构、常见位置与使用方式。 +`datalayers.toml` 是 Datalayers 的核心配置入口，涉及服务监听、认证方式、查询资源、存储后端和引擎行为等关键参数。 + +## 配置修改建议 + +- 修改配置前先备份当前文件 +- 优先只修改与你当前场景直接相关的参数 +- 修改后按部署方式重启 Datalayers，使新配置生效 +- 在生产环境变更前先在测试环境验证配置效果 + ## 配置文件目录 Datalayers 配置文件为 `datalayers.toml`，根据安装方式其所在位置有所不同： @@ -18,6 +27,16 @@ Datalayers 配置文件为 `datalayers.toml`，根据安装方式其所在位置 主配置文件包含了大部分常用的配置项，如果您没有在配置文件中明确指定某个配置项，Datalayers 将使用默认配置。 +## 常见关注的配置分类 + +- `server`：服务启动模式、监听地址、HTTP 端口、时区等基础参数 +- `server.auth`：认证方式、默认账号密码、JWT 密钥、密码策略等安全相关参数 +- `server.tls`：TLS 证书与密钥配置 +- `server.redis`、`server.prometheus`、`server.postgres`、`server.mcp`：可选协议或服务能力配置 +- `query`：查询内存池和慢查询日志配置 +- `ts_engine`：时序引擎、缓存、WAL 和 schemaless 写入相关参数 +- `storage`：元数据、对象存储和存储后端配置 + ## 配置文件示例 ```toml @@ -525,10 +544,10 @@ username = "admin" 配置项与环境变量之前可以通过以下规则转换： -* 由于配置文件中的 `.` 分隔符不能使用于环境变量，因此 Datalayers 选用双下划线 `__` 作为配置分割； -* 为了与其他的环境变量有所区分，Datalayers 还增加了一个前缀 `DATALAYERS_` 来用作环境变量命名空间; +- 由于配置文件中的 `.` 分隔符不能使用于环境变量，因此 Datalayers 选用双下划线 `__` 作为配置分割； +- 为了与其他的环境变量有所区分，Datalayers 还增加了一个前缀 `DATALAYERS_` 来用作环境变量命名空间; ## 配置项优先级与覆盖规则 -* DATALAYERS 配置按以下顺序进行优先级排序：命令行参数 > 环境变量 > datalayers.toml > 操作系统设置(timezone)。 -* 以“DATALAYERS_”开头的环境变量设置具有最高优先级，并将覆盖 etc/datalayers.toml 文件中的任何设置。 +- DATALAYERS 配置按以下顺序进行优先级排序：命令行参数 > 环境变量 > datalayers.toml > 操作系统设置(timezone)。 +- 以“DATALAYERS_”开头的环境变量设置具有最高优先级，并将覆盖 etc/datalayers.toml 文件中的任何设置。 diff --git a/zh_CN/admin/optimize-configuration.md b/zh_CN/admin/optimize-configuration.md index 4032f7ed..2db64b3b 100644 --- a/zh_CN/admin/optimize-configuration.md +++ b/zh_CN/admin/optimize-configuration.md @@ -45,6 +45,8 @@ cpu_cores = 4 以上配置表示 CPU 的最后4个 Core 用于后台任务，其余的为前台线程。详见：[runtime](../admin/configuration-fields/runtime.md) +建议在 CPU 核数较多且后台任务占比较高的环境中启用该类隔离，以降低前台请求与后台维护任务之间的资源竞争。 + ## 自动改表 在通过 InfluxDB 行协议写入时，Datalayers 支持根据行协议约定进行自动建表与改表，系统在高负载情况下，改表过程中可能会对写入性能产生一定影响，因此在生产环境中我们建议将自动改表功能关闭掉。 @@ -56,3 +58,9 @@ cpu_cores = 4 # Default: false. auto_alter_table = false ``` + +## 下一步 + +- 想做系统层优化，请参考 [Datalayers 系统调优指南](./system-tune.md) +- 想查看配置字段细节，请参考 [runtime 配置字段](./configuration-fields/runtime.md) +- 想做查询层调优，请参考 [查询性能调优概述](../development-guide/query-performance-tuning-overview.md) diff --git a/zh_CN/admin/system-metrics.md b/zh_CN/admin/system-metrics.md index ae4309b4..5803d5f0 100644 --- a/zh_CN/admin/system-metrics.md +++ b/zh_CN/admin/system-metrics.md @@ -6,13 +6,27 @@ description: "Datalayers 提供丰富的监控指标，帮助用户全面掌握 Datalayers 提供丰富的监控指标，帮助用户全面掌握服务运行状态，快速识别和定位系统异常。 +本文适合在容量规划、性能分析、故障排查和日常运维场景中使用，可作为 Datalayers 指标查询与监控面板建设的参考入口。 + +## 适用场景 + +- 观察实例 CPU、内存、写入和查询负载 +- 判断 Flush、Compact、缓存与写入链路是否存在瓶颈 +- 配合 Prometheus 和 Grafana 构建可视化监控与告警规则 + ## 与监控系统集成 Datalayers 原生支持与 Prometheus 集成，实现高效的监控数据采集。将 Datalayers 接入第三方监控系统可带来以下优势： -* **统一监控视图**：将 Datalayers 的监控数据与其他系统指标（如服务器主机信息）整合，构建完整的监控体系 -* **可视化展示**：通过 Grafana 等工具创建丰富的监控仪表盘，直观呈现系统运行状态（详见 [Grafana监控](./system-monitor-grafana.md)） -* **智能告警**：利用 Prometheus Alertmanager 实现多通道告警通知，及时发现问题并快速响应 +- **统一监控视图**：将 Datalayers 的监控数据与其他系统指标整合，构建完整的监控体系 +- **可视化展示**：通过 Grafana 等工具创建监控面板，直观呈现系统运行状态，详见 [系统监控](./system-monitor-grafana.md) +- **智能告警**：利用 Prometheus Alertmanager 实现多通道告警通知，及时发现问题并快速响应 + +## 指标使用建议 + +- 优先关注带有明显阈值建议的核心指标，这些指标更适合作为初始告警规则候选项 +- 结合趋势变化而不是单点数值判断问题，例如持续升高的 pending 队列、持续偏高的内存占用 +- 将系统级指标与 Datalayers 进程级指标一起观察，避免只看单一指标造成误判 ## Datalayers Metrics @@ -54,3 +68,9 @@ Datalayers 原生支持与 Prometheus 集成，实现高效的监控数据采集 | **fdb_process_disk_free_bytes** | gauge | * 元数据存储磁盘已使用空间大小，单位：bytes, 使用空间超过 `95%` 会导致服务不可用 | | **fdb_exporter_latency_seconds** | gauge | * 访问元数据服务的时延，单位：秒。不应该大于 `1` | | fdb_process_disk_total_bytes | gauge | 元数据存储磁盘的总空间大小，单位：bytes | + +## 下一步 + +- 想了解如何采集和展示这些指标，请参考 [系统监控](./system-monitor-grafana.md) +- 想根据指标调整服务配置，请参考 [配置文件介绍](./datalayers-configuration.md) +- 想进行系统级性能优化，请参考 [Datalayers 系统调优指南](./system-tune.md) diff --git a/zh_CN/admin/system-monitor-grafana.md b/zh_CN/admin/system-monitor-grafana.md index 3b38c636..9e9885a8 100644 --- a/zh_CN/admin/system-monitor-grafana.md +++ b/zh_CN/admin/system-monitor-grafana.md @@ -92,3 +92,9 @@ docker run --name my-grafana --network host grafana/grafana 以下为监控面板示意图： ![metrics example](../assets/dashboard_metrics.png) + +## 下一步 + +- 想了解指标写入与协议兼容，请参考 [Datalayers Prometheus 协议兼容](../prometheus/overview.md) +- 想直接构建数据分析面板，请参考 [Datalayers 集成 Grafana 可视化指南](../integration/datalayers-with-grafana.md) +- 想调整服务参数和资源限制，请参考 [配置文件介绍](./datalayers-configuration.md) diff --git a/zh_CN/admin/system-tune.md b/zh_CN/admin/system-tune.md index ad6c2f9b..64ab0809 100644 --- a/zh_CN/admin/system-tune.md +++ b/zh_CN/admin/system-tune.md @@ -8,6 +8,20 @@ description: "Datalayers 作为高性能数据处理系统，其性能表现与 Datalayers 作为高性能数据处理系统，其性能表现与底层操作系统配置密切相关。通过合理的系统参数调优，可以显著提升系统处理能力和稳定性。本文档提供针对 Datalayers 的系统级优化配置方案。 +本文适用于性能优化、稳定性提升和生产环境部署准备场景，重点关注操作系统层面对 Datalayers 的影响。 + +## 适用场景 + +- 在生产环境上线前进行系统基线优化 +- 排查因系统资源限制带来的性能瓶颈 +- 提升高并发写入和查询场景下的稳定性 + +## 调优前建议 + +- 在变更前记录当前系统参数，便于回滚 +- 优先在测试环境验证调优效果，再推广到生产环境 +- 将系统调优与 Datalayers 配置调优、监控指标观察结合使用 + ## 关闭交换分区 Linux 交换分区会给 Datalayers 带来严重的性能问题，因此需要禁用交换分区。 @@ -28,3 +42,16 @@ echo "* hard nofile 65535" >> /etc/security/limits.conf ## 时钟同步 时序数据在处理时，很多数据处理逻辑是与时间信息强相关，因此需确保系统时间正确。 + +建议使用稳定的 NTP 服务保持节点时间同步，尤其是在集群部署、跨主机写入和时间窗口查询场景下。 + +## 调优后建议验证 + +- 检查交换分区、文件句柄和系统时间同步状态是否符合预期 +- 结合 [系统监控指标](./system-metrics.md) 观察 CPU、内存、Flush 和 Compact 指标是否改善 +- 在业务高峰或压测场景中复核系统稳定性和延迟表现 + +## 下一步 + +- 想查看监控指标与阈值建议，请参考 [系统监控指标](./system-metrics.md) +- 想配置服务资源和缓存参数，请参考 [配置文件介绍](./datalayers-configuration.md) diff --git a/zh_CN/development-guide/connection.md b/zh_CN/development-guide/connection.md index 9ddba944..5afa47c4 100644 --- a/zh_CN/development-guide/connection.md +++ b/zh_CN/development-guide/connection.md @@ -57,7 +57,7 @@ Datalayers 支持多种认证机制与细粒度权限控制。默认采用静态 ### Redis 协议 -- **兼容性**：完全兼容 Redis 协议 +- **兼容性**：兼容 Redis 协议 - **适用场景**：分布式、海量键值存储需求 ## 协议选择建议 diff --git a/zh_CN/development-guide/postgresql/overview.md b/zh_CN/development-guide/postgresql/overview.md index 2dc4efd4..9b7aac9f 100644 --- a/zh_CN/development-guide/postgresql/overview.md +++ b/zh_CN/development-guide/postgresql/overview.md @@ -12,6 +12,11 @@ Datalayers 兼容 PostgreSQL 网络连接协议，可对接 PostgreSQL 生态中 - 希望复用 PostgreSQL JDBC、连接池或 SQL IDE 进行开发调试 - 希望在不改动过多连接方式的前提下快速接入数据库 +## 前置条件 + +- 已启用 Datalayers 的 PostgreSQL 协议服务 +- 客户端侧已准备 PostgreSQL 兼容工具或驱动 + ## 使用说明 - 使用 PostgreSQL 连接协议时，需使用 PostgreSQL 方言。 diff --git a/zh_CN/development-guide/prometheus/overview.md b/zh_CN/development-guide/prometheus/overview.md index 4d04141f..60821974 100644 --- a/zh_CN/development-guide/prometheus/overview.md +++ b/zh_CN/development-guide/prometheus/overview.md @@ -8,6 +8,12 @@ description: "介绍 Datalayers 对 Prometheus Remote Write 与 PromQL 的兼容 Datalayers 兼容 Prometheus 的 Remote Write 协议与 PromQL 查询语言，可直接接入现有 Prometheus 与 Grafana 生态，用于承接监控指标写入、查询与可视化。 +## 适用场景 + +- 将现有 Prometheus 指标写入 Datalayers +- 复用 PromQL 查询已有监控数据 +- 与 Grafana 配合构建统一监控与分析看板 + 这意味着你可以： - 继续使用现有的 Prometheus 采集配置，只需调整 Remote Write 目标地址，即可将监控数据写入 Datalayers； diff --git a/zh_CN/development-guide/table-design/overview.md b/zh_CN/development-guide/table-design/overview.md index 98e86044..8f3efc31 100644 --- a/zh_CN/development-guide/table-design/overview.md +++ b/zh_CN/development-guide/table-design/overview.md @@ -55,3 +55,9 @@ Datalayers 中，表名大小写敏感，例如 `table1` 与 `Table1` 会被视 - **STORAGE_TYPE**：指定持久化文件的存储介质。可结合部署方式与成本目标选择本地或对象存储。 关于表属性的完整说明，请参考 [时序表引擎指南](../../sql-reference/table-engine/timeseries.md)。 + +## 下一步 + +- 想设计时序表，请参考 [时序存储使用指南](./timeseries-table-design.md) +- 想设计全文检索表，请参考 [全文检索使用指南](./fulltext-table-design.md) +- 想做查询层调优，请参考 [查询性能调优概述](../query-performance-tuning-overview.md) diff --git a/zh_CN/fulltext-search/overview.md b/zh_CN/fulltext-search/overview.md index c401926a..597ad0b8 100644 --- a/zh_CN/fulltext-search/overview.md +++ b/zh_CN/fulltext-search/overview.md @@ -1,22 +1,19 @@ --- title: "全文检索概述" -description: "介绍 Datalayers 基于倒排索引的全文检索能力，包括适用范围、核心函数、索引机制与典型使用流程。" +description: "介绍 Datalayers 基于倒排索引的全文检索能力，包括适用范围、核心函数、分词机制、索引刷新方式与典型使用流程。" --- # 全文检索概述 -## 什么是全文检索 +全文检索是一种基于倒排索引的文本检索能力，也常被称为日志检索、关键词检索或倒排索引检索。Datalayers 的全文检索面向 `STRING` 列中的文本内容提供关键词、短语和布尔表达式检索。相比直接对整列文本做扫描，全文检索更适合日志、事件、审计记录等文本密集型场景，可在海量数据中更快定位目标记录。 -Datalayers 的全文检索能力基于倒排索引，面向 `STRING` 列中的文本内容提供关键词、短语和布尔表达式检索。相比直接对整列文本做扫描，全文检索更适合日志、事件、审计记录等文本密集型场景，可在海量数据中更快定位目标记录。 +如果你需要在日志、消息、审计记录或业务文本中按关键词、短语、布尔逻辑快速查找目标内容，可以先阅读本页，再继续查看 [全文检索快速开始](./quick-start.md)。 -## 适用范围 +## 什么时候适合使用全文检索 -全文检索当前主要用于以下类型的数据： - -- 日志正文、错误信息、异常堆栈等运维数据 -- 事件描述、告警内容、审计说明等文本字段 -- 需要按关键词、短语或布尔条件进行检索的业务文本 - -待检索列建议使用 `STRING` 类型，并在该列上创建倒排索引，以获得稳定的检索性能与相关性排序能力。 +- 需要替代低效的 `LIKE '%keyword%'` 扫描 +- 需要对日志和事件文本做快速定位、筛选和排序 +- 需要对短语、布尔表达式或相关性评分进行查询 +- 需要与 SQL 过滤条件联合使用，以缩小检索范围 ## 核心能力 @@ -26,6 +23,12 @@ Datalayers 的全文检索能力基于倒排索引，面向 `STRING` 列中的 - 支持在 `STRING` 列上创建 `INVERTED INDEX` 以加速全文检索 - 支持通过 `tokenizer`、`filters`、`with_position` 配置索引行为 +## 如何选择 MATCH 与 QUERY + +- 当你只需要做简单关键词匹配时，优先使用 `MATCH` +- 当你需要短语匹配、布尔逻辑或集合表达式时，使用 `QUERY` +- 当你需要按命中相关性排序时，配合 `SCORE()` 使用 + ## 使用约束 - `MATCH` 和 `QUERY` 只能出现在 `WHERE` 子句中 @@ -40,6 +43,10 @@ Datalayers 的全文检索能力基于倒排索引，面向 `STRING` 列中的 3. 如有历史数据，执行 `REFRESH INDEX` 构建存量索引 4. 使用 `MATCH` 或 `QUERY` 发起检索，并可通过 `ORDER BY SCORE() DESC` 按相关性排序 +## 全文检索与向量检索的关系 + +全文检索擅长关键词、短语和布尔表达式匹配，适合日志排障、审计检索和明确关键字查询。向量检索擅长语义召回，适合 RAG 和相似内容搜索。两者可以组合使用，在同一系统中兼顾可解释性与语义匹配能力。 + ## 应用场景 ### 日志与事件检索 @@ -54,7 +61,7 @@ Datalayers 的全文检索能力基于倒排索引，面向 `STRING` 列中的 ### 向量混合检索 -- 向量与关键词的混合检索（RAG 场景） +- 在 RAG 或智能检索场景中，将关键词条件与向量召回结合使用，既保留明确条件过滤能力，也兼顾语义匹配效果 ## 相关文档 diff --git a/zh_CN/fulltext-search/quick-start.md b/zh_CN/fulltext-search/quick-start.md index 928ba88e..d3015a0c 100644 --- a/zh_CN/fulltext-search/quick-start.md +++ b/zh_CN/fulltext-search/quick-start.md @@ -1,6 +1,6 @@ --- title: "全文检索快速开始" -description: "通过一个日志表示例，快速了解在 Datalayers 中创建倒排索引、补建历史索引并执行全文检索的基本流程。" +description: "通过一个日志表示例，快速了解在 Datalayers 中创建倒排索引、补建历史索引、执行全文检索并验证结果的基本流程。" --- # 全文检索快速开始 @@ -12,7 +12,7 @@ description: "通过一个日志表示例，快速了解在 Datalayers 中创建 首先创建一张用于存放日志的示例表，其中 `message` 为待检索字段： -```SQL +```sql CREATE TABLE logs ( ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, service STRING, @@ -27,7 +27,7 @@ PARTITION BY HASH(service) PARTITIONS 1; 在 `message` 列上创建倒排索引： -```SQL +```sql CREATE INVERTED INDEX idx_message ON logs (message) WITH (tokenizer='standard', filters='lowercase,english_stop', with_position='true'); ``` @@ -42,7 +42,7 @@ WITH (tokenizer='standard', filters='lowercase,english_stop', with_position='tru 如果 `idx_message` 创建前表中已经存在历史数据，需要执行一次索引刷新，将存量数据纳入倒排索引： -```SQL +```sql REFRESH INDEX idx_message ON logs; ``` @@ -50,7 +50,7 @@ REFRESH INDEX idx_message ON logs; `MATCH` 适合直接按关键词或多个词项进行检索： -```SQL +```sql SELECT ts, service, level, message FROM logs WHERE MATCH('message', 'database timeout') @@ -60,7 +60,7 @@ LIMIT 20; `QUERY` 适合表达短语匹配、布尔逻辑或集合匹配： -```SQL +```sql SELECT ts, service, level, message FROM logs WHERE QUERY('message:"connection refused" OR message:in [timeout retry]') @@ -74,11 +74,15 @@ LIMIT 20; - `SCORE()` 必须与全文检索函数一起使用 - `ORDER BY SCORE() DESC` 可让最相关的结果排在前面 -## 5. 删除索引（可选） +## 5. 验证结果 + +如果查询能够返回包含目标关键词或短语的日志记录，并且最相关结果排在前面，说明倒排索引已生效，全文检索链路验证成功。 + +## 6. 删除索引（可选） 如果需要清理测试环境中的索引，可执行： -```SQL +```sql DROP INDEX idx_message ON logs; ``` diff --git a/zh_CN/getting-started/centos.md b/zh_CN/getting-started/centos.md index a4d34011..0c098bb8 100644 --- a/zh_CN/getting-started/centos.md +++ b/zh_CN/getting-started/centos.md @@ -52,7 +52,7 @@ sudo systemctl start datalayers 可通过以下命令查看其启动状态： ``` bash -systemctl status datalayers +sudo systemctl status datalayers ``` ### 停止服务 @@ -79,7 +79,7 @@ sudo systemctl restart datalayers sudo yum remove datalayers ``` -该命令会清理数据与配置文件。 +该命令会卸载软件包。建议在卸载前备份配置文件与数据目录，避免影响现有环境中的业务数据。 ## 体验功能 @@ -88,3 +88,9 @@ sudo yum remove datalayers - 使用[命令行工具](./command-line-tool.md)连接数据库进行操作 - 使用 [DBeaver](../integration/datalayers-with-dbeaver.md) 连接数据库进行操作 - 使用 [HTTP](../development-guide/rest-api/overview.md) 协议连接数据库进行操作 + +## 下一步 + +- 如需查看常用配置项，请参考 [配置文件介绍](../admin/datalayers-configuration.md) +- 如需进行图形化查询，请参考 [Datalayers 集成 DBeaver 指南](../integration/datalayers-with-dbeaver.md) +- 如需构建监控看板，请参考 [系统监控](../admin/system-monitor-grafana.md) diff --git a/zh_CN/getting-started/command-line-tool.md b/zh_CN/getting-started/command-line-tool.md index d171781c..80d99e8b 100644 --- a/zh_CN/getting-started/command-line-tool.md +++ b/zh_CN/getting-started/command-line-tool.md @@ -1,9 +1,11 @@ --- title: "Datalayers 命令行工具 dlsql 使用指南" -description: "介绍如何使用 Datalayers 命令行工具 dlsql 连接数据库、创建对象、写入查询数据并执行常见管理操作。" +description: "介绍如何使用 Datalayers 命令行工具 dlsql 连接数据库、创建数据库与表、写入和查询数据，并执行常见管理操作。" --- # Datalayers 命令行工具 dlsql 使用指南 +`dlsql` 是 Datalayers 提供的命令行 SQL 客户端，适合用于数据库连接验证、日常查询、对象管理和运维排查。 + ## 工具简介 `dlsql` 是 Datalayers 提供的命令行 SQL 交互工具，可用于连接数据库、执行 SQL、查看对象定义以及进行基础运维管理。 @@ -114,6 +116,8 @@ SELECT AVG(speed) FROM sensor_info; SELECT date_bin('1 days', ts) as timepoint, count(*) as total from sensor_info group by timepoint; ``` +你也可以结合聚合函数、过滤条件和时间窗口语法构造更复杂的分析查询。 + ## 其他常见操作 查看所有表： @@ -152,4 +156,8 @@ DROP DATABASE demo; 使用 `exit` 或者 `quit` 命令可退出交互终端。 -更多 SQL 语法和对象说明，可查看 [SQL 参考](../sql-reference/data-type.md)。 +## 下一步 + +- 了解更多命令参数和管理命令，请参考 [命令行工具](../admin/datalayers-cli.md) +- 了解完整 SQL 能力，请参考 [SQL 参考](../sql-reference/data-type.md) +- 如果你希望通过图形化工具连接实例，请参考 [Datalayers 集成 DBeaver 指南](../integration/datalayers-with-dbeaver.md) diff --git a/zh_CN/getting-started/docker.md b/zh_CN/getting-started/docker.md index 9b769387..7fa93809 100644 --- a/zh_CN/getting-started/docker.md +++ b/zh_CN/getting-started/docker.md @@ -1,6 +1,6 @@ --- title: "Datalayers Docker 安装指南" -description: "介绍如何通过 Docker 快速部署 Datalayers，包括镜像拉取、容器启动、端口说明与基础连接验证。" +description: "介绍如何通过 Docker 快速部署 Datalayers，包括镜像拉取、容器启动、端口映射、数据持久化与基础连接验证。" --- # Datalayers Docker 安装指南 @@ -61,3 +61,8 @@ docker exec -it datalayers bash - 使用[命令行工具](./command-line-tool.md)连接数据库进行操作 - 使用 [DBeaver](../integration/datalayers-with-dbeaver.md) 连接数据库进行操作 - 使用 [HTTP](../development-guide/rest-api/overview.md) 协议连接数据库进行操作 + +## 下一步 + +- 如果你需要长期运行或托管为系统服务，请参考 [Datalayers Ubuntu 安装指南](./ubuntu.md) +- 如果你希望验证交互式 SQL 操作，请参考 [Datalayers 命令行工具 dlsql 使用指南](./command-line-tool.md) diff --git a/zh_CN/getting-started/ubuntu.md b/zh_CN/getting-started/ubuntu.md index 12dff51d..51349544 100644 --- a/zh_CN/getting-started/ubuntu.md +++ b/zh_CN/getting-started/ubuntu.md @@ -1,6 +1,6 @@ --- title: "Datalayers Ubuntu 安装指南" -description: "介绍如何在 Ubuntu 上安装 Datalayers，包括安装包下载、升级、systemd 服务管理与基础连接验证。" +description: "介绍如何在 Ubuntu 上安装 Datalayers，包括安装包下载、升级、systemd 服务管理、卸载与基础连接验证。" --- # Datalayers Ubuntu 安装指南 @@ -108,7 +108,7 @@ sudo systemctl start datalayers 可通过以下命令查看其启动状态： ``` bash -systemctl status datalayers +sudo systemctl status datalayers ``` ### 停止服务 diff --git a/zh_CN/index.md b/zh_CN/index.md index ce263551..983ce3ab 100644 --- a/zh_CN/index.md +++ b/zh_CN/index.md @@ -1,6 +1,6 @@ --- title: "Datalayers 中文文档" -description: "Datalayers 中文文档中心，涵盖时序存储、全文检索、向量检索、流计算、键值存储、Prometheus 兼容、运维管理与安全能力。" +description: "Datalayers 中文文档中心，覆盖时序数据库、全文检索、向量检索、流计算、Redis 兼容键值存储、Prometheus 兼容、运维管理与安全配置。" --- # Datalayers 中文文档 @@ -25,7 +25,7 @@ Datalayers 是面向可观测性、物联网、日志分析与 AI 应用场景 ### 向量检索 -- 支持最高 16000 维 `FLOAT` 类型稠密向量 +- 支持 `VECTOR(dim)` 类型，维度范围为 `[1, 16383]` - 支持 IVF、HNSW 等向量索引算法，可在召回效率与检索精度之间灵活权衡 - 支持向量检索与 SQL 条件联合使用，在同一查询链路中完成召回、过滤与排序 @@ -58,9 +58,19 @@ Datalayers 是面向可观测性、物联网、日志分析与 AI 应用场景 - 在有限 CPU、内存和存储条件下，仍可提供高效、稳定的数据写入与查询能力 - 适用于边缘采集、边缘缓存与边云协同场景 -### 生态丰富 +## 应用集成 -- 以 SQL（兼容 MySQL 方言）作为主要查询语言，降低学习和迁移成本 - 支持 `Arrow Flight SQL`、`PostgreSQL` 连接协议 - 支持 InfluxDB Line Protocol、Prometheus 查询协议与 Remote Write 协议，便于接入现有监控与数据生态 - 支持 JDBC 驱动接入，同时提供多语言 SDK，支持应用、平台和数据工具的快速集成 +- 以 SQL（兼容 MySQL、PostgreSQL 方言）作为主要查询语言，降低学习和迁移成本 + +## 按任务快速导航 + +- 想快速安装和连接 Datalayers，请先阅读 [快速开始](./quick-start/) +- 想接入 Prometheus Remote Write、PromQL 和 Grafana，请阅读 [Prometheus 协议兼容](./prometheus/overview.md) +- 想做 RAG、语义检索、相似度搜索或向量数据库评估，请阅读 [向量检索概述](./vector-search/overview.md) +- 想做日志搜索、关键词检索、倒排索引检索或审计检索，请阅读 [全文检索概述](./fulltext-search/overview.md) +- 想做 Kafka、MQTT、HTTP 接入和实时 ETL，请阅读 [流计算概述](./streaming/overview.md) +- 想启用 Redis 兼容的分布式键值存储，请阅读 [Key-Value 键值存储概述](./key-value-data-model/overview.md) +- 想查看 SQL 语法、函数和管理语句，请阅读 [SQL 参考](./sql-reference/) diff --git a/zh_CN/integration/datalayers-with-dbeaver.md b/zh_CN/integration/datalayers-with-dbeaver.md index 79702984..3e73dcdb 100644 --- a/zh_CN/integration/datalayers-with-dbeaver.md +++ b/zh_CN/integration/datalayers-with-dbeaver.md @@ -1,6 +1,6 @@ --- title: "Datalayers 集成 DBeaver 指南" -description: "Datalayers 集成 DBeaver 指南：介绍 Arrow Flight SQL JDBC 驱动配置、连接参数设置与常见使用步骤，帮助你通过 DBeaver 管理 Datalayers 数据库。" +description: "介绍如何将 Datalayers 集成到 DBeaver，包括 Arrow Flight SQL JDBC 驱动配置、连接参数设置与常见使用步骤。" --- # Datalayers 集成 DBeaver 指南 @@ -13,6 +13,7 @@ description: "Datalayers 集成 DBeaver 指南：介绍 Arrow Flight SQL JDBC - 已安装 Datalayers，版本不低于 `v2.2.4` - 已安装 DBeaver，可参考 [DBeaver 安装文档](https://github.com/dbeaver/dbeaver/wiki/Installation) - 已下载 [Arrow Flight SQL JDBC Driver](https://mvnrepository.com/artifact/org.apache.arrow/flight-sql-jdbc-driver/18.3.0) +- 已获取 Datalayers 实例地址、端口、用户名和密码 ## 配置 DBeaver diff --git a/zh_CN/integration/datalayers-with-grafana.md b/zh_CN/integration/datalayers-with-grafana.md index 557b3ad8..ba522011 100644 --- a/zh_CN/integration/datalayers-with-grafana.md +++ b/zh_CN/integration/datalayers-with-grafana.md @@ -1,6 +1,6 @@ --- title: "Datalayers 集成 Grafana 可视化指南" -description: "Datalayers 集成 Grafana 可视化指南：介绍如何安装 Datalayers 与 Grafana 插件、完成数据源配置、执行 SQL 查询并构建 Dashboard，帮助你快速实现时序数据可视化。" +description: "介绍如何将 Datalayers 集成到 Grafana，包括插件安装、数据源配置、SQL 查询和 Dashboard 构建，帮助你快速实现时序数据可视化。" --- # Datalayers 集成 Grafana 可视化指南 @@ -166,3 +166,8 @@ git clone https://github.com/datalayers-io/datalayers-with-grafana.git 当你完成上述步骤后，就已经自动完成了上述所有的安装、配置、写入示例数据步骤，你可以直接进行数据查询、添加 Dashboard 相关操作。 通过将 Datalayers 与 Grafana 结合，可以更高效地完成时序数据可视化、指标分析与业务看板构建。 + +## 下一步 + +- 如果你还没有准备测试数据，请参考 [Datalayers 命令行工具 dlsql 使用指南](../getting-started/command-line-tool.md) +- 如果你希望使用图形化数据库工具排查查询结果，请参考 [Datalayers 集成 DBeaver 指南](./datalayers-with-dbeaver.md) diff --git a/zh_CN/integration/datalayers-with-opentelemetry.md b/zh_CN/integration/datalayers-with-opentelemetry.md index 9e3be4b9..3a81fddb 100644 --- a/zh_CN/integration/datalayers-with-opentelemetry.md +++ b/zh_CN/integration/datalayers-with-opentelemetry.md @@ -1,11 +1,23 @@ --- title: "Datalayers 集成 OpenTelemetry 指南" -description: "Datalayers 集成 OpenTelemetry 指南：介绍如何使用 OpenTelemetry Collector 的 InfluxDB Exporter 将链路与指标数据写入 Datalayers，并给出最简配置示例。" +description: "介绍如何使用 OpenTelemetry Collector 的 InfluxDB Exporter 将指标、日志或链路数据写入 Datalayers，并给出最简配置示例。" --- # Datalayers 集成 OpenTelemetry 指南 Datalayers 支持 InfluxDB Line Protocol，因此可以通过 OpenTelemetry Collector 的 InfluxDB Exporter 将指标、链路等观测数据写入 Datalayers。该方案适用于统一接入 OpenTelemetry 采集链路，并将数据存入 Datalayers 进行后续分析和存储。 +## 适用场景 + +- 将 OpenTelemetry 采集到的可观测数据统一写入 Datalayers +- 通过 Collector 聚合并转发指标、日志或链路数据 +- 为后续查询分析、存储归档和可视化提供统一数据入口 + +## 前置条件 + +- 已部署可用的 Datalayers 实例 +- 已安装 OpenTelemetry Collector，建议使用 Contrib 版本 +- 已创建目标数据库，并确认 Datalayers HTTP 写入地址可访问 + ![architecture diagram](../assets/architecture-diagram.png) ## OpenTelemetry Collector @@ -82,13 +94,14 @@ service: ## 配置说明 -* `endpoint` 需要替换为实际的 Datalayers HTTP 地址 -* 当前 Datalayers 默认以 InfluxDB v1 兼容方式接收 Line Protocol，因此需要开启 `v1_compatibility.enabled=true` -* 目标数据库需要提前在 Datalayers 中创建 -* `receivers` 接收的数据会先经过 `processors`，再发送到 `exporters`，最终写入 Datalayers -* 如果目标表不存在，系统会根据配置自动建表；如果关闭了自动建表功能，则需要提前创建表结构 +- `endpoint` 需要替换为实际的 Datalayers HTTP 地址 +- 当前 Datalayers 默认以 InfluxDB v1 兼容方式接收 Line Protocol，因此需要开启 `v1_compatibility.enabled=true` +- 目标数据库需要提前在 Datalayers 中创建 +- `receivers` 接收的数据会先经过 `processors`，再发送到 `exporters`，最终写入 Datalayers +- 如果目标表不存在，系统会根据配置自动建表；如果关闭了自动建表功能，则需要提前创建表结构 ## 相关文档 -* 想了解 InfluxDB 行协议写入方式，请参考 [使用 InfluxDB 行协议写入数据](../development-guide/writing-with-influxdb-line-protocol.md) -* 想了解 HTTP 接入方式，请参考 [Datalayers HTTP REST API 接入指南](../development-guide/rest-api/overview.md) +- 想了解 InfluxDB 行协议写入方式，请参考 [使用 InfluxDB 行协议写入数据](../development-guide/writing-with-influxdb-line-protocol.md) +- 想了解 HTTP 接入方式，请参考 [Datalayers HTTP REST API 接入指南](../development-guide/rest-api/overview.md) +- 想了解可视化展示方式，请参考 [Datalayers 集成 Grafana 可视化指南](./datalayers-with-grafana.md) diff --git a/zh_CN/key-value-data-model/quick-start.md b/zh_CN/key-value-data-model/quick-start.md index a6478fb8..a0b6ad76 100644 --- a/zh_CN/key-value-data-model/quick-start.md +++ b/zh_CN/key-value-data-model/quick-start.md @@ -1,6 +1,6 @@ --- title: "KV 存储快速开始" -description: "通过一个最小示例快速启用 Datalayers 的 Redis 兼容键值存储服务，并完成连接与读写验证。" +description: "通过一个最小示例快速启用 Datalayers 的 Redis 兼容键值存储服务，并完成连接、认证与读写验证。" --- # KV 存储快速开始 @@ -29,6 +29,8 @@ username = "admin" password = "public" ``` +其中，`addr` 决定 Redis 兼容服务监听的地址和端口。后续使用 `redis-cli` 连接时，请以这里配置的端口为准。 + ## 启动 Datalayers 注意：键值存储服务仅在集群模式下支持。 diff --git a/zh_CN/streaming/overview.md b/zh_CN/streaming/overview.md index 54b3d516..6574428e 100644 --- a/zh_CN/streaming/overview.md +++ b/zh_CN/streaming/overview.md @@ -1,13 +1,13 @@ --- title: "Datalayers 流计算概述" -description: "介绍 Datalayers 流计算的核心链路、Source 与 Pipeline 模型、支持的接入方式以及当前能力边界。" +description: "介绍 Datalayers 流计算的核心链路、Source 与 Pipeline 模型、支持的接入方式、典型场景以及当前能力边界。" --- # Datalayers 流计算概述 -## 什么是流计算 +流计算用于持续接收外部事件流，并在数据到达时完成处理和写入。它也可以理解为实时 ETL、实时数据清洗或轻量级流式处理。相比先落库再离线处理的方式，它更适合实时监控、告警预处理和在线数据清洗等低延迟场景。 -流计算用于持续接收外部事件流，并在数据到达时完成处理和写入。相比先落库再离线处理的方式，它更适合实时监控、告警预处理和在线数据清洗等低延迟场景。 +## 核心处理链路 在 Datalayers 中，流计算链路由三部分组成： @@ -33,8 +33,9 @@ Kafka / MQTT / HTTP ## 典型应用场景 - 从 Kafka、MQTT、HTTP 持续接收或拉取数据 -- 在数据入库前做字段筛选、投影、阈值过滤等实时计算 +- 在数据入库前做字段筛选、投影、阈值过滤等实时处理 - 将清洗、转换后的结果写入内部时序表，供 SQL 查询、看板或告警系统使用 +- 作为边缘采集或消息接入后的第一段在线处理链路 当前 `PIPELINE` 仅支持基于单个 source 的投影和过滤，暂不支持 join、聚合、窗口、排序、limit、union、子查询等复杂算子。 diff --git a/zh_CN/user-security/audit-logs.md b/zh_CN/user-security/audit-logs.md index e7db1fab..b1585533 100644 --- a/zh_CN/user-security/audit-logs.md +++ b/zh_CN/user-security/audit-logs.md @@ -8,10 +8,18 @@ Datalayers 提供数据库操作审计能力，可记录用户对数据库的查 审计日志适用于安全合规、操作追踪、问题排查和高风险行为审计等场景。 +## 适用场景 + +- 对数据库访问与操作行为进行留痕 +- 满足安全审计、合规检查或问题追踪要求 +- 结合日志平台对高风险行为进行分析与告警 + ## 开启审计日志 审计日志功能默认关闭，需要在配置文件中启用并配置。具体配置方法可参考 [审计日志配置字段](../admin/configuration-fields/audit-logs.md)。 +建议根据业务安全要求合理选择审计的对象种类和动作范围，避免无差别记录带来的日志膨胀。 + ## 查看审计日志 审计日志文件默认存储在以下目录： @@ -24,6 +32,12 @@ Datalayers 提供数据库操作审计能力，可记录用户对数据库的查 在生产环境中，建议根据实际安全合规要求，合理配置 kinds 和 actions 参数，平衡审计需求与系统性能。 +## 验证是否启用成功 + +- 启用配置并重启服务后，检查审计目录是否生成日志文件 +- 执行一次查询、写入或管理操作，确认对应日志记录已写入 +- 验证日志内容是否包含预期的用户、对象、动作和时间信息 + ## 相关文档 - 了解审计日志配置项，请参考 [审计日志配置字段](../admin/configuration-fields/audit-logs.md) diff --git a/zh_CN/user-security/authentication/overview.md b/zh_CN/user-security/authentication/overview.md index 11868431..9cccf755 100644 --- a/zh_CN/user-security/authentication/overview.md +++ b/zh_CN/user-security/authentication/overview.md @@ -15,3 +15,9 @@ Datalayers 提供 [静态认证](./static.md) 与 [RBAC](../rbac/overview.md) | 认证机制 | 配置文件预置凭证 | 基于角色的访问控制 | | 权限粒度 | 所有权限 | 细粒度权限控制 | | 管理复杂度 | 简单 | 中等 | + +## 下一步 + +- 了解静态认证配置，请参考 [静态认证](./static.md) +- 了解角色和权限模型，请参考 [Datalayers 访问控制概述](../rbac/overview.md) +- 了解传输加密，请参考 [Datalayers TLS 连接加密配置指南](../tls.md) diff --git a/zh_CN/user-security/authentication/static.md b/zh_CN/user-security/authentication/static.md index b07db12d..d1d2b118 100644 --- a/zh_CN/user-security/authentication/static.md +++ b/zh_CN/user-security/authentication/static.md @@ -30,13 +30,16 @@ password = "public" jwt_secret = "871b3c2d706d875e9c6389fb2457d957" ``` +修改配置后，需要重启 Datalayers 服务使其生效。 + ## 注意事项 - 静态认证模式下，通过认证的用户将拥有系统高权限 - 需要将配置文件中的 `server.auth.type` 设置为 `static` 才能启用静态认证 - 如果环境中存在多用户隔离或权限分级需求，建议改用 RBAC 认证 -## 相关文档 +## 下一步 -- 了解认证方式选择，请参考 [Datalayers 连接认证概述](./overview.md) -- 了解 RBAC 认证，请参考 [RBAC（基于角色的访问控制）](./rbac.md) +- 如果需要更细粒度的授权能力，请参考 [Datalayers 访问控制概述](../rbac/overview.md) +- 如果需要提升凭据安全性，请参考 [Datalayers 密码策略](../password-policy.md) +- 如果需要保护传输链路，请参考 [Datalayers TLS 连接加密配置指南](../tls.md) diff --git a/zh_CN/user-security/password-policy.md b/zh_CN/user-security/password-policy.md index 61e75a73..7d509679 100644 --- a/zh_CN/user-security/password-policy.md +++ b/zh_CN/user-security/password-policy.md @@ -6,6 +6,14 @@ description: "介绍 Datalayers 的密码强度策略与防暴力破解配置， Datalayers 的密码策略用于定义账户密码强度要求和认证安全机制，包括密码复杂度规则与防暴力破解保护。该能力适用于需要提升账户安全性和满足基础安全规范的部署场景。 +如果你的环境存在多用户访问、远程连接或基础安全合规要求，建议启用密码强度和登录失败锁定策略。 + +## 适用场景 + +- 提升默认认证环境下的账户安全性 +- 降低弱密码和暴力破解带来的风险 +- 满足企业内部安全基线或审计要求 + ## 配置 密码策略为全局配置，通过系统配置文件进行设置。默认情况下策略未启用，如需使用需要手动配置开启。 diff --git a/zh_CN/user-security/rbac/overview.md b/zh_CN/user-security/rbac/overview.md index b05e2530..a27766eb 100644 --- a/zh_CN/user-security/rbac/overview.md +++ b/zh_CN/user-security/rbac/overview.md @@ -8,6 +8,12 @@ description: "介绍 Datalayers 基于用户、权限和角色的访问控制模 该模型适用于多用户环境、最小权限控制、数据库对象隔离和权限统一治理等场景。 +## 适用场景 + +- 多用户共享同一 Datalayers 实例 +- 需要按角色、数据库或对象进行授权隔离 +- 希望通过最小权限原则降低误操作和越权访问风险 + ## 核心概念 ### 用户 diff --git a/zh_CN/user-security/tls.md b/zh_CN/user-security/tls.md index 32c59fa4..e8a966f0 100644 --- a/zh_CN/user-security/tls.md +++ b/zh_CN/user-security/tls.md @@ -6,6 +6,8 @@ description: "介绍如何为 Datalayers 配置 TLS 加密连接，包括服务 Datalayers 支持 TLS（Transport Layer Security）加密连接，用于保护客户端与服务端之间的网络通信安全。启用 TLS 后，可以降低明文传输凭据和数据内容带来的安全风险。 +如果你的部署环境对传输安全、合规审计或跨网络访问有要求，建议启用 TLS 保护客户端与服务端之间的通信链路。 + ## 配置 ### 服务端配置 diff --git a/zh_CN/vector-search/overview.md b/zh_CN/vector-search/overview.md index 3e4e70c8..e4f6d2be 100644 --- a/zh_CN/vector-search/overview.md +++ b/zh_CN/vector-search/overview.md @@ -1,12 +1,10 @@ --- title: "Datalayers 向量检索概述" -description: "介绍 Datalayers 向量检索能力，包括向量嵌入、相似度搜索、混合检索和典型应用场景，适用于 RAG、语义搜索与推荐系统。" +description: "介绍 Datalayers 向量检索能力，包括向量嵌入、相似度搜索、近似最近邻检索、混合检索和典型应用场景，适用于 RAG、语义搜索与推荐系统。" --- # Datalayers 向量检索概述 -## 概述 - -向量检索是一种面向非结构化数据的相似度搜索技术。它将文本、图像、音频、视频等对象编码为向量嵌入（Vector Embedding），再通过向量距离计算检索与目标最相近的数据。该能力常用于 RAG、语义搜索、推荐系统和多模态检索。 +向量检索是一种面向非结构化数据的相似度搜索技术，也常被称为语义检索、相似度检索或 ANN 检索。它将文本、图像、音频、视频等对象编码为向量嵌入，再通过向量距离计算检索与目标最相近的数据。该能力常用于 RAG、语义搜索、推荐系统和多模态检索。 ![向量检索框架](../assets/vector-search-arch.png) @@ -40,9 +38,13 @@ description: "介绍 Datalayers 向量检索能力，包括向量嵌入、相似 向量距离是两个向量在高维空间的距离。在向量检索应用中，它用来近似度量两个向量的语义相似度。例如给定三张图片，分别表示“游泳”、“太阳”、“水”。 从语义上来说，“游泳”与“水”在语义上更接近，因此它们所对应的向量的距离更小。 +## 向量检索与全文检索的关系 + +向量检索擅长处理语义相似度问题，全文检索擅长处理关键词、短语和布尔表达式匹配。实际生产环境中，两者通常会结合使用：先通过结构化条件缩小范围，再通过向量检索召回候选结果，必要时叠加全文条件提升可解释性和准确性。 + ## 应用场景 -### 增强生成 +### 检索增强生成 增强生成（Retrieval-Augmented Generation，RAG）是一个用来优化大语言模型（LLM）输出效果的框架。RAG 将知识输入到嵌入模型中，得到知识的向量表征，再将它们存储到向量数据库中。在大语言模型根据用户输入的提示词（Prompt）生成提示时，RAG 将提示词转换为向量表征，在向量数据库中执行近似搜索，得到与提示词语义相近的文档。这些文档可以用来提升模型输出的效果，使得响应更准确。 diff --git a/zh_CN/vector-search/quick-start.md b/zh_CN/vector-search/quick-start.md index fa3fe6f3..b614f45b 100644 --- a/zh_CN/vector-search/quick-start.md +++ b/zh_CN/vector-search/quick-start.md @@ -1,6 +1,6 @@ --- title: "向量检索快速开始" -description: "通过一个最小示例快速体验 Datalayers 向量检索，包括向量表创建、向量写入与相似度查询。" +description: "通过一个最小示例快速体验 Datalayers 向量检索，包括向量表创建、向量写入、相似度查询与结果验证。" --- # 向量检索快速开始 @@ -19,7 +19,7 @@ CREATE TABLE t( timestamp key (ts) ) PARTITION BY HASH(id) PARTITIONS 4 -ENGINE=TimeSeries +ENGINE=TimeSeries; ``` 其中，`embed VECTOR(3)` 表示创建一个名为 `embed` 的向量列，该列中每个向量的维度为 3。 From 4d749d362a1dd25253364f78a14e379cf345dcee Mon Sep 17 00:00:00 2001 From: YinBo Date: Tue, 17 Mar 2026 20:42:47 +0800 Subject: [PATCH 2/4] minor --- zh_CN/admin/backup-restore.md | 2 +- zh_CN/admin/datalayers-cli.md | 2 +- zh_CN/admin/optimize-configuration.md | 2 +- zh_CN/admin/system-metrics.md | 2 +- zh_CN/admin/system-monitor-grafana.md | 2 +- zh_CN/admin/system-tune.md | 2 +- zh_CN/development-guide/table-design/overview.md | 2 +- zh_CN/getting-started/centos.md | 2 +- zh_CN/getting-started/command-line-tool.md | 2 +- zh_CN/getting-started/docker.md | 2 +- zh_CN/integration/datalayers-with-grafana.md | 2 +- zh_CN/user-security/authentication/overview.md | 2 +- zh_CN/user-security/authentication/static.md | 2 +- 13 files changed, 13 insertions(+), 13 deletions(-) diff --git a/zh_CN/admin/backup-restore.md b/zh_CN/admin/backup-restore.md index 53c4883a..b2b19cf4 100644 --- a/zh_CN/admin/backup-restore.md +++ b/zh_CN/admin/backup-restore.md @@ -173,7 +173,7 @@ test> SELECT * FROM device; 10 rows in set (0.002 sec) ``` -## 下一步 +## 相关文档 - 想了解连接与查询验证，请参考 [Datalayers 命令行工具 dlsql 使用指南](../getting-started/command-line-tool.md) - 想了解服务配置与数据目录设置，请参考 [配置文件介绍](./datalayers-configuration.md) diff --git a/zh_CN/admin/datalayers-cli.md b/zh_CN/admin/datalayers-cli.md index cd43abd6..65a80eb3 100644 --- a/zh_CN/admin/datalayers-cli.md +++ b/zh_CN/admin/datalayers-cli.md @@ -91,7 +91,7 @@ dlsql --web-console 9362 | --max-display-rows | - | 在使用 `dlsql` 查询数据时最多显示多少条记录，缺省值为：`40`，如需显示更多记录，则需通过该参数进行指定（`0` 表示无限制） | | --help | - | show this help, then exit | -## 下一步 +## 相关文档 - 想快速完成连接、建库和查询，请参考 [Datalayers 命令行工具 dlsql 使用指南](../getting-started/command-line-tool.md) - 想了解服务参数与认证配置，请参考 [配置文件介绍](./datalayers-configuration.md) diff --git a/zh_CN/admin/optimize-configuration.md b/zh_CN/admin/optimize-configuration.md index 2db64b3b..e9d4699c 100644 --- a/zh_CN/admin/optimize-configuration.md +++ b/zh_CN/admin/optimize-configuration.md @@ -59,7 +59,7 @@ cpu_cores = 4 auto_alter_table = false ``` -## 下一步 +## 相关文档 - 想做系统层优化，请参考 [Datalayers 系统调优指南](./system-tune.md) - 想查看配置字段细节，请参考 [runtime 配置字段](./configuration-fields/runtime.md) diff --git a/zh_CN/admin/system-metrics.md b/zh_CN/admin/system-metrics.md index 5803d5f0..7734d457 100644 --- a/zh_CN/admin/system-metrics.md +++ b/zh_CN/admin/system-metrics.md @@ -69,7 +69,7 @@ Datalayers 原生支持与 Prometheus 集成，实现高效的监控数据采集 | **fdb_exporter_latency_seconds** | gauge | * 访问元数据服务的时延，单位：秒。不应该大于 `1` | | fdb_process_disk_total_bytes | gauge | 元数据存储磁盘的总空间大小，单位：bytes | -## 下一步 +## 相关文档 - 想了解如何采集和展示这些指标，请参考 [系统监控](./system-monitor-grafana.md) - 想根据指标调整服务配置，请参考 [配置文件介绍](./datalayers-configuration.md) diff --git a/zh_CN/admin/system-monitor-grafana.md b/zh_CN/admin/system-monitor-grafana.md index 9e9885a8..9dd13694 100644 --- a/zh_CN/admin/system-monitor-grafana.md +++ b/zh_CN/admin/system-monitor-grafana.md @@ -93,7 +93,7 @@ docker run --name my-grafana --network host grafana/grafana ![metrics example](../assets/dashboard_metrics.png) -## 下一步 +## 相关文档 - 想了解指标写入与协议兼容，请参考 [Datalayers Prometheus 协议兼容](../prometheus/overview.md) - 想直接构建数据分析面板，请参考 [Datalayers 集成 Grafana 可视化指南](../integration/datalayers-with-grafana.md) diff --git a/zh_CN/admin/system-tune.md b/zh_CN/admin/system-tune.md index 64ab0809..1727b641 100644 --- a/zh_CN/admin/system-tune.md +++ b/zh_CN/admin/system-tune.md @@ -51,7 +51,7 @@ echo "* hard nofile 65535" >> /etc/security/limits.conf - 结合 [系统监控指标](./system-metrics.md) 观察 CPU、内存、Flush 和 Compact 指标是否改善 - 在业务高峰或压测场景中复核系统稳定性和延迟表现 -## 下一步 +## 相关文档 - 想查看监控指标与阈值建议，请参考 [系统监控指标](./system-metrics.md) - 想配置服务资源和缓存参数，请参考 [配置文件介绍](./datalayers-configuration.md) diff --git a/zh_CN/development-guide/table-design/overview.md b/zh_CN/development-guide/table-design/overview.md index 8f3efc31..66831636 100644 --- a/zh_CN/development-guide/table-design/overview.md +++ b/zh_CN/development-guide/table-design/overview.md @@ -56,7 +56,7 @@ Datalayers 中，表名大小写敏感，例如 `table1` 与 `Table1` 会被视 关于表属性的完整说明，请参考 [时序表引擎指南](../../sql-reference/table-engine/timeseries.md)。 -## 下一步 +## 相关文档 - 想设计时序表，请参考 [时序存储使用指南](./timeseries-table-design.md) - 想设计全文检索表，请参考 [全文检索使用指南](./fulltext-table-design.md) diff --git a/zh_CN/getting-started/centos.md b/zh_CN/getting-started/centos.md index 0c098bb8..8c92a506 100644 --- a/zh_CN/getting-started/centos.md +++ b/zh_CN/getting-started/centos.md @@ -89,7 +89,7 @@ sudo yum remove datalayers - 使用 [DBeaver](../integration/datalayers-with-dbeaver.md) 连接数据库进行操作 - 使用 [HTTP](../development-guide/rest-api/overview.md) 协议连接数据库进行操作 -## 下一步 +## 相关文档 - 如需查看常用配置项，请参考 [配置文件介绍](../admin/datalayers-configuration.md) - 如需进行图形化查询，请参考 [Datalayers 集成 DBeaver 指南](../integration/datalayers-with-dbeaver.md) diff --git a/zh_CN/getting-started/command-line-tool.md b/zh_CN/getting-started/command-line-tool.md index 80d99e8b..9b71d268 100644 --- a/zh_CN/getting-started/command-line-tool.md +++ b/zh_CN/getting-started/command-line-tool.md @@ -156,7 +156,7 @@ DROP DATABASE demo; 使用 `exit` 或者 `quit` 命令可退出交互终端。 -## 下一步 +## 相关文档 - 了解更多命令参数和管理命令，请参考 [命令行工具](../admin/datalayers-cli.md) - 了解完整 SQL 能力，请参考 [SQL 参考](../sql-reference/data-type.md) diff --git a/zh_CN/getting-started/docker.md b/zh_CN/getting-started/docker.md index 7fa93809..0154670b 100644 --- a/zh_CN/getting-started/docker.md +++ b/zh_CN/getting-started/docker.md @@ -62,7 +62,7 @@ docker exec -it datalayers bash - 使用 [DBeaver](../integration/datalayers-with-dbeaver.md) 连接数据库进行操作 - 使用 [HTTP](../development-guide/rest-api/overview.md) 协议连接数据库进行操作 -## 下一步 +## 相关文档 - 如果你需要长期运行或托管为系统服务，请参考 [Datalayers Ubuntu 安装指南](./ubuntu.md) - 如果你希望验证交互式 SQL 操作，请参考 [Datalayers 命令行工具 dlsql 使用指南](./command-line-tool.md) diff --git a/zh_CN/integration/datalayers-with-grafana.md b/zh_CN/integration/datalayers-with-grafana.md index ba522011..42cd3b46 100644 --- a/zh_CN/integration/datalayers-with-grafana.md +++ b/zh_CN/integration/datalayers-with-grafana.md @@ -167,7 +167,7 @@ git clone https://github.com/datalayers-io/datalayers-with-grafana.git 通过将 Datalayers 与 Grafana 结合，可以更高效地完成时序数据可视化、指标分析与业务看板构建。 -## 下一步 +## 相关文档 - 如果你还没有准备测试数据，请参考 [Datalayers 命令行工具 dlsql 使用指南](../getting-started/command-line-tool.md) - 如果你希望使用图形化数据库工具排查查询结果，请参考 [Datalayers 集成 DBeaver 指南](./datalayers-with-dbeaver.md) diff --git a/zh_CN/user-security/authentication/overview.md b/zh_CN/user-security/authentication/overview.md index 9cccf755..1924de75 100644 --- a/zh_CN/user-security/authentication/overview.md +++ b/zh_CN/user-security/authentication/overview.md @@ -16,7 +16,7 @@ Datalayers 提供 [静态认证](./static.md) 与 [RBAC](../rbac/overview.md) | 权限粒度 | 所有权限 | 细粒度权限控制 | | 管理复杂度 | 简单 | 中等 | -## 下一步 +## 相关文档 - 了解静态认证配置，请参考 [静态认证](./static.md) - 了解角色和权限模型，请参考 [Datalayers 访问控制概述](../rbac/overview.md) diff --git a/zh_CN/user-security/authentication/static.md b/zh_CN/user-security/authentication/static.md index d1d2b118..5521d42d 100644 --- a/zh_CN/user-security/authentication/static.md +++ b/zh_CN/user-security/authentication/static.md @@ -38,7 +38,7 @@ jwt_secret = "871b3c2d706d875e9c6389fb2457d957" - 需要将配置文件中的 `server.auth.type` 设置为 `static` 才能启用静态认证 - 如果环境中存在多用户隔离或权限分级需求，建议改用 RBAC 认证 -## 下一步 +## 相关文档 - 如果需要更细粒度的授权能力，请参考 [Datalayers 访问控制概述](../rbac/overview.md) - 如果需要提升凭据安全性，请参考 [Datalayers 密码策略](../password-policy.md) From a8bb832c34213c8198af65456da7fdc13b7b106e Mon Sep 17 00:00:00 2001 From: YinBo Date: Tue, 17 Mar 2026 20:44:35 +0800 Subject: [PATCH 3/4] minor --- zh_CN/index.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/zh_CN/index.md b/zh_CN/index.md index 983ce3ab..d9ec5d9e 100644 --- a/zh_CN/index.md +++ b/zh_CN/index.md @@ -64,13 +64,3 @@ Datalayers 是面向可观测性、物联网、日志分析与 AI 应用场景 - 支持 InfluxDB Line Protocol、Prometheus 查询协议与 Remote Write 协议，便于接入现有监控与数据生态 - 支持 JDBC 驱动接入，同时提供多语言 SDK，支持应用、平台和数据工具的快速集成 - 以 SQL（兼容 MySQL、PostgreSQL 方言）作为主要查询语言，降低学习和迁移成本 - -## 按任务快速导航 - -- 想快速安装和连接 Datalayers，请先阅读 [快速开始](./quick-start/) -- 想接入 Prometheus Remote Write、PromQL 和 Grafana，请阅读 [Prometheus 协议兼容](./prometheus/overview.md) -- 想做 RAG、语义检索、相似度搜索或向量数据库评估，请阅读 [向量检索概述](./vector-search/overview.md) -- 想做日志搜索、关键词检索、倒排索引检索或审计检索，请阅读 [全文检索概述](./fulltext-search/overview.md) -- 想做 Kafka、MQTT、HTTP 接入和实时 ETL，请阅读 [流计算概述](./streaming/overview.md) -- 想启用 Redis 兼容的分布式键值存储，请阅读 [Key-Value 键值存储概述](./key-value-data-model/overview.md) -- 想查看 SQL 语法、函数和管理语句，请阅读 [SQL 参考](./sql-reference/) From d33f8d260210dd5544824f3fe90dc1b4b74e7a4c Mon Sep 17 00:00:00 2001 From: YinBo Date: Tue, 17 Mar 2026 20:52:41 +0800 Subject: [PATCH 4/4] minor --- en_US/admin/configuration-fields/server.md | 2 +- en_US/key-value-data-model/quick-start.md | 2 +- zh_CN/admin/configuration-fields/server.md | 2 +- zh_CN/admin/datalayers-configuration.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/en_US/admin/configuration-fields/server.md b/en_US/admin/configuration-fields/server.md index 1e24f1dd..59cb8d7d 100644 --- a/en_US/admin/configuration-fields/server.md +++ b/en_US/admin/configuration-fields/server.md @@ -24,7 +24,7 @@ These settings define the communication ports for different protocols used by th - **`redis`**: Specifies the Redis Service endpoint, which is only available in cluster mode. - - **Default**: `"0.0.0.0:8362"`. + - **Default**: `"0.0.0.0:6379"`. - Note: This option is commented out, so it is disabled by default. Uncomment it to enable. ## Session Management diff --git a/en_US/key-value-data-model/quick-start.md b/en_US/key-value-data-model/quick-start.md index e3c74ce5..75709e02 100644 --- a/en_US/key-value-data-model/quick-start.md +++ b/en_US/key-value-data-model/quick-start.md @@ -22,5 +22,5 @@ To launch the Datalayers Service with Redis support enabled (assuming the defaul 2. Once installed, connect to the Datalayers Redis Service using the following command: ```bash - redis-cli -p 8362 + redis-cli -p 6379 ``` diff --git a/zh_CN/admin/configuration-fields/server.md b/zh_CN/admin/configuration-fields/server.md index 1ca0baee..f75036f3 100644 --- a/zh_CN/admin/configuration-fields/server.md +++ b/zh_CN/admin/configuration-fields/server.md @@ -90,7 +90,7 @@ path = "run/datalayers.sock" # Users can start this service only when Datalayers server starts in cluster mode. # Do not support redis service by default. # Default: "". -# addr = "0.0.0.0:8362" +# addr = "0.0.0.0:6379" # The username. # Default: "admin". diff --git a/zh_CN/admin/datalayers-configuration.md b/zh_CN/admin/datalayers-configuration.md index ab53c101..40cb159a 100644 --- a/zh_CN/admin/datalayers-configuration.md +++ b/zh_CN/admin/datalayers-configuration.md @@ -125,7 +125,7 @@ path = "run/datalayers.sock" # Users can start this service only when Datalayers server starts in cluster mode. # Do not support redis service by default. # Default: "". -# addr = "0.0.0.0:8362" +# addr = "0.0.0.0:6379" # The username. # Default: "admin".