From 180c85a060ab7fb2fd39543aba1c961720887264 Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Thu, 10 Sep 2026 16:59:38 +0800
Subject: [PATCH] docs(faq): preserve PostgreSQL permission guidance

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 docs/skillhub/en/faq.md | 11 +++++++++++
 docs/skillhub/faq.md    | 11 +++++++++++
 2 files changed, 22 insertions(+)

diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md
index 83ba79f2..e1ed7ec4 100644
--- a/docs/skillhub/en/faq.md
+++ b/docs/skillhub/en/faq.md
@@ -301,6 +301,17 @@ A: PostgreSQL and Redis are required. Object storage supports both `local` and S
 
 The release Compose file already bundles PostgreSQL and Redis, bound to `127.0.0.1` by default.
 
+## Q: What should I do when PostgreSQL reports `operation not permitted` while writing `postmaster.pid` or `pg_wal`?
+
+A: SkillHub's default Compose and `runtime.sh` use a Docker named volume (`postgres_data`), so host-directory permissions normally do not need manual changes. This error is more common after replacing that volume with a host bind mount, such as `/data/skillhub/postgres:/var/lib/postgresql/data`.
+
+Check the following in order:
+
+1. Prefer switching back to a Docker named volume, or use the official `runtime.sh` to avoid missing permission settings in a hand-written Compose file.
+2. If a bind mount is required, run `docker run --rm postgres:16-alpine id postgres` to identify the actual UID/GID of the `postgres` user in the selected image. Then change the data-directory owner accordingly, for example `chown -R <uid>:<gid> <data-dir>`. Do not assume every environment uses `999:999`.
+3. Check SELinux on RHEL/CentOS. With AppArmor, rootless Docker, NFS, CIFS, or NAS storage, also verify that the host filesystem permits PostgreSQL to write, lock files, and change permissions.
+4. Avoid placing PostgreSQL `PGDATA` on network filesystems without full POSIX permission semantics. For production, prefer local disks, Docker named volumes, block storage, or an external PostgreSQL service.
+
 ## Q: How does an account created through OAuth (GitHub / GitLab, etc.) get admin rights?
 
 A: The first OAuth login creates a regular user. An existing `SUPER_ADMIN` (for example the bootstrap admin created during initialization) has to promote it from the admin console.
diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md
index 10d255b2..e1094551 100644
--- a/docs/skillhub/faq.md
+++ b/docs/skillhub/faq.md
@@ -301,6 +301,17 @@ A: 必需 PostgreSQL 和 Redis；对象存储支持 `local` 与 S3 两种模式
 
 发布版 Compose 已内置 PostgreSQL 与 Redis，默认只绑定在 `127.0.0.1`。
 
+## Q: PostgreSQL 容器写入 `postmaster.pid` 或 `pg_wal` 时报告 `operation not permitted` 怎么办？
+
+A: SkillHub 默认的 Compose 和 `runtime.sh` 使用 Docker named volume（`postgres_data`），通常不需要手工处理宿主机目录权限。这个错误更常见于将 PostgreSQL 数据目录改成宿主机 bind mount，例如 `/data/skillhub/postgres:/var/lib/postgresql/data`。
+
+按以下顺序排查：
+
+1. 优先恢复为 Docker named volume，或使用官方 `runtime.sh`，避免手写 Compose 时漏配权限。
+2. 如果必须使用 bind mount，先运行 `docker run --rm postgres:16-alpine id postgres`，确认当前镜像中 `postgres` 用户的 UID/GID，再按实际值调整数据目录属主，例如 `chown -R <uid>:<gid> <数据目录>`。不要固定假设所有环境都是 `999:999`。
+3. 在 RHEL/CentOS 上检查 SELinux；使用 AppArmor、rootless Docker、NFS、CIFS 或 NAS 时，也要确认宿主文件系统允许 PostgreSQL 写入、加锁和更改权限。
+4. 不建议把 PostgreSQL `PGDATA` 放在缺少完整 POSIX 权限语义的网络文件系统上。生产环境优先使用本地盘、Docker named volume、块存储或外部 PostgreSQL。
+
 ## Q: 通过 OAuth（GitHub / GitLab 等）登录的账号，如何取得管理员权限？
 
 A: OAuth 首次登录创建的是普通用户。需要由已有的 `SUPER_ADMIN`（例如初始化时的 bootstrap admin）在后台将其提升为管理员。