docs(store): document the auto-sized RocksDB memory budget

content/cn/docs/guides/hugegraph-docker-cluster.md

@@ -196,10 +196,19 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \
 | `HG_STORE_GRPC_PORT` | 否 | `8500` | `grpc.port` |
 | `HG_STORE_REST_PORT` | 否 | `8520` | `server.port` |
 | `HG_STORE_DATA_PATH` | 否 | `/hugegraph-store/storage` | `app.data-path` |
+| `HG_STORE_ROCKSDB_TOTAL_MEMORY_SIZE` | 否 | 无 | `rocksdb.total_memory_size`，`auto` 或字节数 |
 {.td-table--wide}
 
 > **已弃用的别名**：`PD_ADDRESS` → `HG_STORE_PD_ADDRESS`、`GRPC_HOST` → `HG_STORE_GRPC_HOST`、`RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS`
 
+RocksDB 缓存位于 Java 堆外。不设置 `HG_STORE_ROCKSDB_TOTAL_MEMORY_SIZE` 时，将按容器内存限制自动计算；若容器未设置限制，则按宿主机（或 Docker Desktop 虚拟机）内存计算。
+前提是加载到的 `rocksdb.total_memory_size` 为 `auto`（或缺失、为 `0`）：沿用旧版本的 `application-pd.yml` 仍是 `32000000000`，会保留该预算，PD 保存并下发给各 Store 的副本也是如此，
+请按 [HStore 配置参考](/cn/docs/quickstart/hugegraph/hugegraph-hstore/)中 `rocksdb.total_memory_size` 一行的升级说明处理。
+上面的 Compose 文件默认未设置内存限制，每个 Store 均会按整台宿主机估算预算；多 Store 共用单机时，建议为服务配置内存限制，或将该变量显式设为字节数。
+需要注意，容器限制仅约束 RocksDB 预算：Store 启动脚本仍会按宿主机空闲内存自动分配 `-Xmx`（最多 2 GiB），并将直接内存设为相同大小。
+因此请同步通过 `JAVA_OPTS`（镜像会以 `-j` 传给启动脚本）显式约束 JVM 内存，例如容器限制为 4 GiB 时可设置 `JAVA_OPTS="-Xmx1g -XX:MaxDirectMemorySize=512m"`；
+若直接使用默认值，堆内存、直接内存、1.5 GiB 预留加上 256 MiB 最低预算总和已超过 2 GiB。详见 [HStore 配置参考](/cn/docs/quickstart/hugegraph/hugegraph-hstore/)中的 `rocksdb.total_memory_size`。
+
 ### Server 变量
 
 与 PD、Store 不同，Server 入口脚本没有必填变量：只有实际设置了的变量才会被写入配置文件。但分布式部署至少需要 `HG_SERVER_BACKEND` 和 `HG_SERVER_PD_PEERS`。

content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md

@@ -133,6 +133,7 @@ docker run -d \
 | `HG_STORE_GRPC_PORT` | 否 | `8500` | `grpc.port` | gRPC 服务端口。 |
 | `HG_STORE_REST_PORT` | 否 | `8520` | `server.port` | REST API 端口。 |
 | `HG_STORE_DATA_PATH` | 否 | `/hugegraph-store/storage` | `app.data-path` | 数据存储路径。 |
+| `HG_STORE_ROCKSDB_TOTAL_MEMORY_SIZE` | 否 | 无 | `rocksdb.total_memory_size` | RocksDB 内存预算：`auto` 或字节数。空值视为未设置；其他值会使入口脚本以退出码 2 退出。未设置时使用 `application-pd.yml` 中的值或自动计算。 |
 {.td-table--wide}
 
 当前主线 entrypoint 将这些变量写入 `SPRING_APPLICATION_JSON`，覆盖镜像内 `conf/application.yml`；其余配置仍从该文件和 `application-pd.yml` 读取，然后以前台方式启动 Java。旧变量 `PD_ADDRESS`、`GRPC_HOST`、`RAFT_ADDRESS` 仍可用，但会输出弃用警告。
@@ -148,7 +149,7 @@ Store 从 `conf/` 读取两个配置文件。1.7.0 发布标签的源文件见 [
 
 #### 4.1 application.yml
 
-以下配置参考表核对的是 server 主线提交 `2f827d6e8c9c62ae858f2fc122b3a192d015e2f4` 的发行目录值和 Java 默认注入值；1.7.0 发布包请使用其版本标签对应的配置文件，不要跨版本覆盖。
+以下配置参考表核对的是 server 主线提交 `2f827d6e8c9c62ae858f2fc122b3a192d015e2f4` 的发行目录值和 Java 默认注入值，其中 `rocksdb.total_memory_size`、`rocksdb.write_buffer_size` 和 `raft.disruptorBufferSize` 三行描述的是 apache/hugegraph#3355 的行为；1.7.0 发布包请使用其版本标签对应的配置文件，不要跨版本覆盖。
 
 #### 4.2 application-pd.yml
 
@@ -180,7 +181,7 @@ Store 从 `conf/` 读取两个配置文件。1.7.0 发布标签的源文件见 [
 | 配置项 | 当前主线目录值 | 代码默认值 | 说明 |
 |--------|--------|------------|------|
 | `raft.address` | `127.0.0.1:8510` | 必填 | 本节点的 Raft 服务地址，格式为 `host:port`，必须能被其他 Store 节点访问。这里不需要配置 peer 列表：分区 Raft 组的成员由 PD 下发。 |
-| `raft.disruptorBufferSize` | `1024` | `0` | Raft 任务队列大小。设为 `0` 时按 `rocksdb.total_memory_size` 推导：将该内存量的 GB 数取最接近的 2 的幂，再乘以 32。 |
+| `raft.disruptorBufferSize` | `1024` | `0` | Raft 任务队列大小。设为 `0` 时按 `rocksdb.total_memory_size` 推导：将该内存量的 GB 数（至少为 1）取最接近的 2 的幂，再乘以 32。 |
 | `raft.max-log-file-size` | `600000000000` | `50000000000` | Raft 日志的最大字节数。 |
 | `raft.snapshotInterval` | `1800` | `300` | 生成 Raft 快照的时间间隔，单位秒。 |
 | `raft.snapshotLogIndexMargin` | 未设置 | `0` | 距上次快照的最小 applied index 差值，达到后才真正生成快照。设为 `0` 关闭该判断。 |
@@ -209,8 +210,8 @@ Store 从 `conf/` 读取两个配置文件。1.7.0 发布标签的源文件见 [
 
 | 配置项 | 当前主线目录值 | 代码默认值 | 说明 |
 |--------|--------|------------|------|
-| `rocksdb.total_memory_size` | `32000000000` | `51539607552` | 本节点所有 RocksDB 实例共享的内存预算。缺失或为 `0` 时使用 JVM 最大堆内存。 |
-| `rocksdb.write_buffer_size` | `32000000` | `33554432` | memtable 大小，单位字节。缺失或为 `0` 时取 `total_memory_size / 1000`。 |
+| `rocksdb.total_memory_size` | `auto` | 自动计算，见说明 | 本节点所有 RocksDB 实例共享的内存预算，取值为 `auto` 或字节数，按 `write_buffer_ratio` 分为写缓存和 block cache。两者都在堆外，不受 `-Xmx` 限制，另有固定 1 GiB 的 Raft 日志缓存不计入其中；所有分区的 Raft 日志 memtable 共用一个 256 MiB 的写缓冲，并计入这 1 GiB 缓存，不会额外占用内存。该预算是容量目标，并非硬上限：`rocksdb.write_buffer_allow_stall` 默认为 `false`，写缓存写满时不会阻塞写入，因此在大量写入时本地内存可能超出预算，容器仍可能被 OOM 终止。将其设为 `true` 能更严格地守住上限，但会增加写入延迟。取值为 `auto` 时（缺失、空值或 `0` 与之等同），取物理内存减去 JVM 最大堆、`MaxDirectMemorySize`（未设置时按堆大小计算；`bin/start-hugegraph-store.sh` 默认把它设为所选的堆大小；`-j` 自行设置了 `-Xmx`、`-XX:MaxHeapSize` 或该上限，或 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS` 设置了该上限时不再添加）和 1.5 GiB 预留（1 GiB Raft 日志缓存加 512 MiB 其他本地内存）后剩余部分的一半，并限制在 256 MiB 到 32 GB 之间；容器内设置了内存限制时以 cgroup 内存限制为准，Store 能看到的父 cgroup 上的限制也会计入；否则以宿主机内存为准。Store 看不到的限制（例如私有 cgroup 命名空间之上的限制）不会被猜测：Store 使用可见的最低限制并输出警告，此时请显式设置该值。启动日志会输出预算及其模式、物理内存限制及来源、堆、直接内存、预留，以及 cgroup 视图是否完整。JVM 和 cgroup 文件都拿不到可用的内存大小时，改用 JVM 最大堆，同样限制在 256 MiB 到 32 GB 之间。沿用旧版本的 `application-pd.yml` 仍是 `32000000000`，需改为 `auto` 才会自动计算。PD 模式下 PD 还可能保存一份副本（KV 键 `S:FS`），由第一个启动的 Store 上传。Store 只有在没有本地文件，或本地文件不比 `S:Timestamp` 新时，才会加载这份副本并覆盖本地文件；上传时不会写入时间戳，缺失的时间戳按 0 处理，因此只修改 `S:FS` 不会生效。升级时，请在每个 Store 上设置 `HG_STORE_ROCKSDB_TOTAL_MEMORY_SIZE=auto` 或 `-Drocksdb.total_memory_size=auto` 并重启，Store 会让这个值优先于本地文件和 PD 的副本。也可以先在 `S:FS` 中把该值改为 `0` 或删除它，再通过 PD 的 KV 服务（gRPC `KvService.put`）把当前时间（毫秒）写入 `S:Timestamp`：所有运行中的 Store 会重新加载 PD 的副本、覆盖本地文件，并在 60 秒内运行 `bin/restart-hugegraph-store.sh`，因此所有 Store 会在同一分钟内重启；已停止的 Store 会在下次启动时加载它。只有所有 Store 都已运行支持 `auto` 的版本后，才能在 `S:FS` 中写入 `auto`：旧版本无法解析 `auto`，会启动失败，而 `0` 在旧版本中按原来的堆大小默认值处理。PD 中原本没有副本、由新版本 Store 上传的副本也是如此，因为发行的配置文件写的是 `auto`。自行重启时不带任何参数，最初启动时的 `-j` 和 `-g` 会丢失，启动脚本改用默认堆大小；只有导出的 `JAVA_OPTIONS` 中的 JVM 设置会保留，因此对使用自定义堆大小启动的 Store，建议采用逐个 Store 覆盖的方式。Docker 中的 Store 根本不会重启：Java 是入口脚本的最后一个进程，停止它会使容器连同其中的重启脚本一起以退出码 143 退出。设置了重启策略的容器（Compose 文件使用 `restart: unless-stopped`）会通过入口脚本重新启动，并保留 `JAVA_OPTS`；像 3.3 节中独立运行的 `docker run -d` 示例那样未指定 `--restart` 启动的容器，则会一直处于停止状态。在 Docker 中请设置 `HG_STORE_ROCKSDB_TOTAL_MEMORY_SIZE`，不要写入 `S:Timestamp`。其他值按原值使用，且必须是纯字节数，最小为 `1048576`（1 MiB）；更小的值或 `4GB` 之类的值会导致启动失败。 |
+| `rocksdb.write_buffer_size` | `32000000` | 自动推导，见说明 | memtable 大小，单位字节。缺失或为 `0` 时取 `total_memory_size / 1000`，最小为 `1048576`（1 MiB）。 |
 | `rocksdb.min_write_buffer_number_to_merge` | `16` | `16` | 落盘前合并的 memtable 数量。 |
 | `rocksdb.write_buffer_ratio` | 未设置 | `0.66` | `total_memory_size` 中分配给写缓存的比例，其余作为 block cache。 |
 {.td-table--wide}
@@ -327,7 +328,10 @@ master 构建接受 `g1`、`G1`、`zgc` 和 `ZGC`。
 - `-d true`（默认）：以后台守护进程方式运行，脚本立即返回，并把 Java 进程号写入 `bin/pid`。
 - `-d false`：以前台模式运行，脚本通过 `exec` 替换为 Java 进程，容器或进程管理器的进程即为 Java 本身。在 Docker 或进程管理器（systemd、supervisord）下运行时请使用此参数，以便在崩溃时自动检测并重启服务。
 
-JVM 内存方面，如果没有自行设置 `JAVA_OPTIONS`：`-Xms512m`，`-Xmx` 取空闲内存的一半并限制在 512 MB 到 2048 MB 之间。脚本还会加上 `-XX:MetaspaceSize=256M`、OOM 时把堆转储写入 `logs/`，以及滚动的 GC 日志 `logs/gc.log`。生产节点通常需要大得多的堆，请显式指定，例如 `-j "-Xmx32g -Xms32g"`。
+JVM 内存方面，如果没有自行设置 `JAVA_OPTIONS`：`-Xms512m`，`-Xmx` 取空闲内存的一半并限制在 512 MB 到 2048 MB 之间。
+脚本还会加上与该堆大小相同的 `-XX:MaxDirectMemorySize`、`-XX:MetaspaceSize=256M`、OOM 时把堆转储写入 `logs/`，以及滚动的 GC 日志 `logs/gc.log`。
+生产节点通常需要大得多的堆，请显式指定，并同时设置直接内存上限，例如 `-j "-Xmx32g -Xms32g -XX:MaxDirectMemorySize=2g"`。
+不设上限时，JVM 允许的直接内存与 32 GB 的堆相同，RocksDB 预算会把它计算在内，在内存不足约 66 GB 的主机上会降到 256 MiB 的下限。
 
 当 `ulimit -n` 或 `ulimit -u` 低于 1024 时脚本会拒绝启动；在 x86_64 和 arm64 上，如果能成功下载并校验对应的动态库，脚本会预加载 jemalloc。
 

content/en/docs/guides/hugegraph-docker-cluster.md

@@ -196,10 +196,22 @@ The following tables describe current master entrypoints and Compose files, not
 | `HG_STORE_GRPC_PORT` | No | `8500` | `grpc.port` |
 | `HG_STORE_REST_PORT` | No | `8520` | `server.port` |
 | `HG_STORE_DATA_PATH` | No | `/hugegraph-store/storage` | `app.data-path` |
+| `HG_STORE_ROCKSDB_TOTAL_MEMORY_SIZE` | No | None | `rocksdb.total_memory_size`, `auto` or bytes |
 {.td-table--wide}
 
 > **Deprecated aliases**: `PD_ADDRESS` → `HG_STORE_PD_ADDRESS`, `GRPC_HOST` → `HG_STORE_GRPC_HOST`, `RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS`.
 
+RocksDB caches live outside the Java heap. Leave `HG_STORE_ROCKSDB_TOTAL_MEMORY_SIZE` unset to size them from the container memory limit, or from the
+memory of the Docker host (such as the Docker Desktop VM) when the container has no limit. That needs the loaded
+`rocksdb.total_memory_size` to be `auto` (or missing, or `0`): an `application-pd.yml` kept from an earlier release still sets `32000000000`
+and keeps that budget, as does the copy PD keeps and hands to every Store, so follow the upgrade note under `rocksdb.total_memory_size` in the
+[HStore configuration reference](/docs/quickstart/hugegraph/hugegraph-hstore/). The Compose files above set no limit, so each Store sizes its budget
+from the whole host; set a memory limit on Store services or set this variable to a plain number of bytes when several Stores share one host.
+A container limit bounds only the RocksDB budget: the Store launcher still picks `-Xmx` from the host's free memory (up to 2 GiB) and sets direct memory to the
+same size. Size those for the limit too through `JAVA_OPTS` (passed to the launcher as `-j`), for example `JAVA_OPTS="-Xmx1g -XX:MaxDirectMemorySize=512m"` for
+a 4 GiB container limit; with defaults, heap plus direct memory, the 1.5 GiB reserve, and the 256 MiB minimum budget already exceed a 2 GiB limit.
+See `rocksdb.total_memory_size` in the [HStore configuration reference](/docs/quickstart/hugegraph/hugegraph-hstore/).
+
 ### Server Variables
 
 Unlike PD and Store, Server has no mandatory entrypoint variables: only set values are written to configuration. Distributed deployment nevertheless requires at least `HG_SERVER_BACKEND` and `HG_SERVER_PD_PEERS`.