From 9fa6c52a4dd17e2de42a73fcccb7e3c1ad184c85 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Mon, 24 Aug 2026 14:25:28 +0800 Subject: [PATCH] docs(troubleshooting): broaden postgres volume permission guidance (#745) Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- document/docs/05-reference/troubleshooting.md | 11 +++++++---- .../current/05-reference/troubleshooting.md | 11 +++++++---- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/document/docs/05-reference/troubleshooting.md b/document/docs/05-reference/troubleshooting.md index 05d8a41f..a2237a7e 100644 --- a/document/docs/05-reference/troubleshooting.md +++ b/document/docs/05-reference/troubleshooting.md @@ -24,11 +24,14 @@ description: 常见问题诊断和解决方案 ### PostgreSQL 容器启动报 `operation not permitted`（写 `postmaster.pid` / `pg_wal` 失败） -内网/自建环境使用绑定挂载时常见，根因是**数据卷目录权限**与容器内 `postgres` 用户（UID 999）不匹配： +SkillHub 默认的 Compose / `runtime.sh` 使用 Docker named volume（`postgres_data`），通常不需要手工处理宿主机目录权限。这个错误更多出现在你把 PostgreSQL 数据目录改成宿主机 bind mount 时，例如 `/data/skillhub/postgres:/var/lib/postgresql/data`。 -1. 将数据卷目录属主改为 postgres 用户：`chown -R 999:999 <数据目录>`。 -2. 在 RHEL/CentOS 上检查 SELinux 是否拦截了容器写入宿主目录。 -3. 推荐直接使用官方 `runtime.sh` 部署脚本，它会处理相关初始化步骤，避免手工编写 compose 时漏配权限。 +排查顺序： + +1. 优先恢复为 Docker named volume，或直接使用官方 `runtime.sh` 部署脚本，避免手写 compose 时漏配权限。 +2. 如果必须使用 bind mount，先确认当前镜像中的 `postgres` 用户 UID/GID：`docker run --rm postgres:16-alpine id postgres`，再按实际 UID/GID 调整数据目录属主，例如 `chown -R : <数据目录>`。不要固定假设所有环境都是 `999:999`。 +3. 在 RHEL/CentOS 上检查 SELinux；在启用 AppArmor、rootless Docker、NFS/CIFS/NAS 等环境时，也要确认宿主文件系统是否允许 PostgreSQL 需要的写入、锁和权限变更。 +4. 不建议把 PostgreSQL `PGDATA` 放在不支持完整 POSIX 权限语义的网络文件系统上；生产环境优先使用本地盘、Docker named volume、块存储或外部 PostgreSQL。 ## 上传失败 diff --git a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md index e1eec4b9..4e236391 100644 --- a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md +++ b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md @@ -24,11 +24,14 @@ description: Common problem diagnosis and solutions ### PostgreSQL container fails to start with `operation not permitted` (cannot write `postmaster.pid` / `pg_wal`) -Common in intranet / self-hosted environments using bind mounts. The root cause is a mismatch between the **data volume directory permissions** and the container's `postgres` user (UID 999): +SkillHub's default Compose / `runtime.sh` deployment uses a Docker named volume (`postgres_data`), so you normally do not need to manage host directory permissions manually. This error is more common after changing PostgreSQL storage to a host bind mount, for example `/data/skillhub/postgres:/var/lib/postgresql/data`. -1. Change the data volume directory owner to the postgres user: `chown -R 999:999 `. -2. On RHEL/CentOS, check whether SELinux is blocking the container from writing to the host directory. -3. Prefer the official `runtime.sh` deployment script, which handles the relevant initialization steps and avoids permission gaps from hand-written compose files. +Recommended checks: + +1. Prefer switching back to a Docker named volume, or use the official `runtime.sh` deployment script to avoid permission gaps from hand-written compose files. +2. If you must use a bind mount, first check the `postgres` UID/GID in the image you run: `docker run --rm postgres:16-alpine id postgres`. Then change the data directory owner to the actual UID/GID, for example `chown -R : `. Do not assume every environment is `999:999`. +3. On RHEL/CentOS, check SELinux. If AppArmor, rootless Docker, NFS/CIFS/NAS, or another restricted filesystem is involved, also verify that PostgreSQL can write, lock files, and change permissions as required. +4. Avoid putting PostgreSQL `PGDATA` on network filesystems that do not provide full POSIX permission semantics. For production, prefer local disks, Docker named volumes, block storage, or an external PostgreSQL service. ## Upload Failed