docs(docker): document the non-root PD, Store and Server images

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

@@ -312,6 +312,17 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \
 
 5. **数据在意料之外地保留了下来**：`docker compose down` 会保留命名卷。要同时删除该拓扑的数据，请使用 `docker compose down -v`
 
+6. **升级到 master 构建的镜像后出现 `Permission denied`**：基于当前 master 构建的 PD、Store 和 Server 镜像以非 root 用户 `hugegraph`（UID/GID `10001`）运行。
+   旧镜像以 root 运行，写入的卷仍归 root 所有。先执行 `docker compose down`（不要用 `down -v`），对每个数据卷执行一次属主变更，再重新启动：
+
+   ```bash
+   docker run --rm -u 0 --entrypoint chown -v <volume>:/data <new-image> -R 10001:10001 /data
+   ```
+
+   不要对运行中的容器直接执行 `up -d` 升级：Compose 会重新挂载保存旧镜像应用目录（归 root 所有）的匿名卷。请先执行 `down`，或使用 `up -d --renew-anon-volumes`。
+   作为 bind mount 的宿主机目录必须对 UID `10001` 可写。在 Kubernetes 上，Pod 安全上下文需要 `fsGroup: 10001`，Helm Chart 已为 PD 和 Store 设置，参见
+   [Helm 升级和验证](/cn/docs/quickstart/hugegraph/hugegraph-helm/#5-升级和验证)。
+
 **查看运行时日志**：使用 `docker logs <container-name>`（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的
 `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；Hadoop、Netty 和 Commons 的
 INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。`/hugegraph-server/logs` 中包含 `hugegraph-server.log`、JVM

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

@@ -222,6 +222,36 @@ helm test hugegraph -n hugegraph --logs --timeout 5m
 
 已有配置中的显式 helper 镜像也会保留。添加 `--set-string store.waitImage= --set-string server.waitImage=` 可清空覆盖并复用组件镜像。
 要采用新的默认值，先审阅已有配置，再使用 `--reset-values` 和保留镜像、凭据、存储、拓扑设置的配置文件。
+
+基于当前 master 构建的 PD、Store 和 Server 镜像以 UID/GID `10001` 运行。除非 `podSecurityContext` 已设置 `fsGroup`，Chart 会为 PD 和 Store Pod 设置
+`fsGroup: 10001`（以及 `fsGroupChangePolicy: OnRootMismatch`），即使 `--reuse-values` 保留了旧 Release 的空值也是如此，使其能写入旧镜像（以 root 运行）创建的 PVC。
+
+请在首次应用 `fsGroup` 的同一次滚动更新中，将 PD 和 Store 切换到基于此版本构建的镜像，使 kubelet 在 `10001` 镜像启动前修改卷的属主。不要先用仍以 root
+运行的镜像（例如尚未更新到此版本的 `latest`）运行此 Chart：这些镜像创建的文件归 root 所有，而 `OnRootMismatch` 只检查卷的根目录，之后不会再修正它们。
+请将 `pd.image` 和 `store.image` 固定为基于此版本构建的镜像，而不要依赖 `latest`。
+
+如果 Release 已在设置了 `fsGroup` 的情况下运行过 root 镜像，请在首次滚动更新到 `10001` 镜像的同时执行一次递归属主变更。请在同一条命令中设置镜像标签，
+使递归变更作用于 `10001` 镜像，而不是已固定的 root 镜像：
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.image.tag=<this-version> \
+  --set store.image.tag=<this-version> \
+  --set pd.podSecurityContext.fsGroupChangePolicy=Always \
+  --set store.podSecurityContext.fsGroupChangePolicy=Always \
+  --wait --timeout 15m
+```
+
+`--reuse-values` 会保留 `Always`，而它会在每次 Pod 启动时遍历整个卷，因此请在这些 Pod 运行后改回原策略：
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --wait --timeout 15m
+```
+
+CSI 驱动忽略 `fsGroup` 的卷（例如许多 NFS 驱动）和 `hostPath` 卷需要改为执行一次 `chown -R 10001:10001`。
 PD 成员、持久存储和共享凭据变更需要按生命周期说明协调处理。
 
 `server.storageWaitTimeoutSeconds` 默认 300，通过 `WAIT_STORAGE_TIMEOUT_S` 传给启动脚本。

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

@@ -111,6 +111,8 @@ set -a; . ./.env; set +a
 单独运行当前主线构建的 Store 时，将示例地址换成 Store 与 PD 均可路由的实际地址：
 
 ```bash
+# master 构建的镜像以 UID 10001 运行，宿主机数据目录必须对该用户可写
+mkdir -p /path/to/storage && sudo chown 10001:10001 /path/to/storage
 docker run -d \
   -p 8520:8520 -p 8500:8500 -p 8510:8510 \
   -e HG_STORE_PD_ADDRESS=192.168.1.10:8686 \

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

@@ -83,6 +83,8 @@ docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .
 
 ```bash
 export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)"
+# master 构建的镜像以 UID 10001 运行，宿主机数据目录必须对该用户可写
+mkdir -p /path/to/data && sudo chown 10001:10001 /path/to/data
 docker run -d \
   -p 8620:8620 -p 8686:8686 -p 8610:8610 \
   -e HG_PD_GRPC_HOST=192.168.1.10 \

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

@@ -670,6 +670,8 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK
           - 8080:8080
     ```
 
+    基于当前 master 构建的 Server 镜像以非 root 的 UID `10001` 运行，挂载的脚本必须对该用户可读。
+
     使用命令 `docker compose up -d` 启动容器
 
 使用 RESTful API 请求 `HugeGraphServer` 得到如下结果：

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

@@ -317,6 +317,19 @@ Standalone publishes only `8080` and `8088`; minimal HStore publishes `8620` (PD
 
 5. **Unexpected retained data**: `docker compose down` keeps named volumes. To delete topology data too, use `docker compose down -v`.
 
+6. **`Permission denied` after upgrading to master-built images**: PD, Store and Server images built from current master run as the non-root user
+   `hugegraph`, UID/GID `10001`. Volumes written by older images, which ran as root, stay owned by root. Stop with `docker compose down` (not `down -v`),
+   change the owner of each data volume once, then start again:
+
+   ```bash
+   docker run --rm -u 0 --entrypoint chown -v <volume>:/data <new-image> -R 10001:10001 /data
+   ```
+
+   Do not upgrade running containers with a plain `up -d`: Compose reattaches the anonymous volume holding the previous image's root-owned application
+   directory. Run `down` first, or use `up -d --renew-anon-volumes`. A host directory used as a bind mount must be writable by UID `10001`. On Kubernetes,
+   the pod security context needs `fsGroup: 10001`, which the Helm chart sets for PD and Store; see [Helm upgrade and
+   verification](/docs/quickstart/hugegraph/hugegraph-helm/#5-upgrade-and-verification).
+
 **Runtime logs**: `docker logs <container-name>` (for example, `docker logs hg-pd0`) shows logs without entering containers. In images built from current
 master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout.
 For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; INFO from Hadoop, Netty and Commons and the audit and

content/en/docs/quickstart/hugegraph/hugegraph-helm.md

@@ -230,6 +230,38 @@ helm test hugegraph -n hugegraph --logs --timeout 5m
 Existing explicit helper images also remain under `--reuse-values`;
 add `--set-string store.waitImage= --set-string server.waitImage=` to reuse component images.
 Adopt new defaults deliberately with `--reset-values` and a reviewed file retaining your image, credential, storage and topology settings.
+
+PD, Store and Server images built from current master run as UID/GID `10001`. The chart gives the PD and Store pods `fsGroup: 10001` (with
+`fsGroupChangePolicy: OnRootMismatch`) unless their `podSecurityContext` sets `fsGroup`, also when `--reuse-values` keeps an older release's empty value,
+so they can write PVCs created by older images, which ran as root.
+
+Switch PD and Store to images built from this version in the same rollout that first applies `fsGroup`, so the kubelet changes the volume ownership right
+before the `10001` image starts. Do not run images that still run as root with this chart first, for example a `latest` that has not moved to this version:
+files they create stay owned by root, and `OnRootMismatch` checks only the volume root, so it does not fix them later. Pin `pd.image` and `store.image` to a
+build from this version rather than relying on `latest`.
+
+If a release already ran root images with `fsGroup` set, roll out the first `10001` image together with a one-time recursive ownership change. Set the
+image tags in the same command, so the recursive change runs for the `10001` image rather than for a pinned root image:
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.image.tag=<this-version> \
+  --set store.image.tag=<this-version> \
+  --set pd.podSecurityContext.fsGroupChangePolicy=Always \
+  --set store.podSecurityContext.fsGroupChangePolicy=Always \
+  --wait --timeout 15m
+```
+
+`--reuse-values` keeps `Always`, which walks the whole volume on every Pod start, so set the policy back once those Pods are running:
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --wait --timeout 15m
+```
+
+Volumes whose CSI driver ignores `fsGroup` (for example many NFS drivers) and `hostPath` volumes need a one-time `chown -R 10001:10001` instead.
 Do not treat PD membership, storage or credential changes as ordinary independent overrides; consult the lifecycle reference.
 
 `server.storageWaitTimeoutSeconds` defaults to 300 and is passed as `WAIT_STORAGE_TIMEOUT_S`. An unspecified startup probe threshold is derived

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

@@ -112,6 +112,8 @@ Multi-node service names are `pd0`–`pd2`, `store0`–`store2`, and `server0`
 To run master-built Store alone, replace example addresses with actual routable Store and PD addresses:
 
 ```bash
+# Master-built images run as UID 10001; the host data directory must be writable by it
+mkdir -p /path/to/storage && sudo chown 10001:10001 /path/to/storage
 docker run -d \
   -p 8520:8520 -p 8500:8500 -p 8510:8510 \
   -e HG_STORE_PD_ADDRESS=192.168.1.10:8686 \

content/en/docs/quickstart/hugegraph/hugegraph-pd.md

@@ -84,6 +84,8 @@ To run master-built PD alone, first set a deployment-specific secret and replace
 
 ```bash
 export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)"
+# Master-built images run as UID 10001; the host data directory must be writable by it
+mkdir -p /path/to/data && sudo chown 10001:10001 /path/to/data
 docker run -d \
   -p 8620:8620 -p 8686:8686 -p 8610:8610 \
   -e HG_PD_GRPC_HOST=192.168.1.10 \

content/en/docs/quickstart/hugegraph/hugegraph-server.md

@@ -694,6 +694,8 @@ Set the environment variable `PRELOAD=true` when starting Docker so that sample
           - 8080:8080
     ```
 
+    Server images built from current master run as the non-root UID `10001`, so a mounted script must be readable by that user.
+
     Use `docker compose up -d` to start the container.
 
 And use the RESTful API to request `HugeGraphServer` and get the following result: