diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 190868908..7c3a17eb0 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/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 :/data -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 `（如 `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 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index 69eb34691..8b7ff2791 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/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= \ + --set store.image.tag= \ + --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` 传给启动脚本。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index b3649bbf5..f00f2bb53 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/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 \ diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index 337a63588..14351e204 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/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 \ diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 9ef4904a0..f590ec9af 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/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` 得到如下结果： diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 0deb2ffe1..ab2bedc41 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/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 :/data -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 ` (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 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index a87432cd3..1debbc058 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/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= \ + --set store.image.tag= \ + --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 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index ad62bf4e3..708931b9e 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/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 \ diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index 402142084..fa1e8b913 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/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 \ diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index f1c899be9..1869bad10 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/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: