mirror of
https://github.com/iflytek/skillhub.git
synced 2026-09-10 22:41:02 +00:00
74 lines
2.2 KiB
Markdown
74 lines
2.2 KiB
Markdown
---
|
||
title: 故障排查
|
||
sidebar_position: 2
|
||
description: 常见问题诊断和解决方案
|
||
---
|
||
|
||
# 故障排查
|
||
|
||
## 服务无法启动
|
||
|
||
### 检查清单
|
||
|
||
1. 检查容器状态：`docker compose ps`
|
||
2. 查看服务日志：`docker compose logs <service>`
|
||
3. 验证环境变量：检查 `.env.release` 配置
|
||
4. 检查端口占用：`netstat -tlnp`
|
||
|
||
### 常见原因
|
||
|
||
- 端口被占用
|
||
- 数据库连接失败
|
||
- Redis 连接失败
|
||
- 环境变量缺失
|
||
|
||
### PostgreSQL 容器启动报 `operation not permitted`（写 `postmaster.pid` / `pg_wal` 失败）
|
||
|
||
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，先确认当前镜像中的 `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。
|
||
|
||
## 上传失败
|
||
|
||
### 技能包上传失败
|
||
|
||
1. 检查文件大小
|
||
2. 检查文件类型
|
||
3. 检查 SKILL.md 格式
|
||
4. 查看服务端日志
|
||
|
||
## 认证问题
|
||
|
||
### 无法登录
|
||
|
||
1. 检查 OAuth 配置
|
||
2. 检查回调地址配置
|
||
3. 检查 `SKILLHUB_PUBLIC_BASE_URL` 配置
|
||
|
||
## 性能问题
|
||
|
||
### 搜索慢
|
||
|
||
1. 检查 PostgreSQL 全文索引
|
||
2. 考虑升级到 Elasticsearch（后续版本）
|
||
|
||
### 下载慢
|
||
|
||
1. 检查对象存储配置
|
||
2. 检查网络带宽
|
||
|
||
## 获取帮助
|
||
|
||
如以上方案无法解决问题：
|
||
1. 查看日志
|
||
2. 提交 Issue
|
||
3. 联系技术支持
|
||
|
||
## 下一步
|
||
|
||
- [变更日志](./changelog) - 版本历史
|