scriptoriumadmin/skillhub
1
0
Fork 0
mirror of https://github.com/iflytek/skillhub.git synced 2026-08-27 11:14:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs(troubleshooting): broaden postgres volume permission guidance (#745)

Browse source 
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
This commit is contained in:
XiaoSeS 2026-08-24 14:25:28 +08:00 • committed by GitHub
parent 183729613c
commit 9fa6c52a4d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 14 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
document/docs/05-reference/troubleshooting.md
View file

@ -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 <uid>:<gid> <数据目录>`。不要固定假设所有环境都是 `999:999`。
3. 在 RHEL/CentOS 上检查 SELinux；在启用 AppArmor、rootless Docker、NFS/CIFS/NAS 等环境时，也要确认宿主文件系统是否允许 PostgreSQL 需要的写入、锁和权限变更。
4. 不建议把 PostgreSQL `PGDATA` 放在不支持完整 POSIX 权限语义的网络文件系统上；生产环境优先使用本地盘、Docker named volume、块存储或外部 PostgreSQL。
## 上传失败

11
document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md
View file

@ -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 <data-dir>`.
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 <uid>:<gid> <data-dir>`. 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