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
skillhub/document/docs/05-reference/troubleshooting.md
FenjuFu 183729613c
docs(faq): add CLI namespace-not-found and PostgreSQL permission entries (#743) 
Add two entries collected from community support, to both the zh docs and
the en i18n mirror:

- FAQ: installing a skill via CLI reporting `namespace not found` — set the
  registry / log in with an API token, and use the correct namespace slug
  (`@team/skill` -> `team--skill`); the web UI Install button provides a
  ready-made command.
- Troubleshooting: PostgreSQL container failing to start with
  `operation not permitted` on bind mounts — fix data volume ownership
  (`chown 999:999`), check SELinux, or use the `runtime.sh` script.

Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
2026-08-24 13:39:49 +08:00

1.6 KiB
Raw Blame History

title sidebar_position description
故障排查 2 常见问题诊断和解决方案

故障排查

服务无法启动

检查清单

  1. 检查容器状态：docker compose ps
  2. 查看服务日志：docker compose logs <service>
  3. 验证环境变量：检查 .env.release 配置
  4. 检查端口占用：netstat -tlnp

常见原因

  • 端口被占用
  • 数据库连接失败
  • Redis 连接失败
  • 环境变量缺失

PostgreSQL 容器启动报 operation not permitted（写 postmaster.pid / pg_wal 失败）

内网/自建环境使用绑定挂载时常见，根因是数据卷目录权限与容器内 postgres 用户（UID 999）不匹配：

  1. 将数据卷目录属主改为 postgres 用户：chown -R 999:999 <数据目录>。
  2. 在 RHEL/CentOS 上检查 SELinux 是否拦截了容器写入宿主目录。
  3. 推荐直接使用官方 runtime.sh 部署脚本，它会处理相关初始化步骤，避免手工编写 compose 时漏配权限。

上传失败

技能包上传失败

  1. 检查文件大小
  2. 检查文件类型
  3. 检查 SKILL.md 格式
  4. 查看服务端日志

认证问题

无法登录

  1. 检查 OAuth 配置
  2. 检查回调地址配置
  3. 检查 SKILLHUB_PUBLIC_BASE_URL 配置

性能问题

搜索慢

  1. 检查 PostgreSQL 全文索引
  2. 考虑升级到 Elasticsearch（后续版本）

下载慢

  1. 检查对象存储配置
  2. 检查网络带宽

获取帮助

如以上方案无法解决问题：

  1. 查看日志
  2. 提交 Issue
  3. 联系技术支持

下一步