故障排查

诊断工具

检查服务状态

# 查看所有服务状态
docker compose ps

# 查看服务健康状态
docker inspect glean-backend --format='{{.State.Health.Status}}'

查看日志

# 查看所有服务日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f backend
docker compose logs -f worker

# 查看最近 100 行
docker compose logs --tail=100 backend

资源使用

# 查看资源使用情况
docker stats

常见问题

服务无法启动

端口冲突

症状：服务启动失败，日志显示端口已被占用。

解决方案：

# 检查端口占用
lsof -i :80
lsof -i :3001

# 修改端口
echo "WEB_PORT=8080" >> .env
echo "ADMIN_PORT=8081" >> .env

数据库连接失败

症状：后端服务启动失败，日志显示数据库连接错误。

解决方案：

# 检查 PostgreSQL 状态
docker compose ps postgres

# 等待数据库就绪
docker exec glean-postgres pg_isready -U glean

# 检查数据库日志
docker compose logs postgres

后端服务不健康

检查健康端点

curl http://localhost/api/health

检查日志错误

docker compose logs backend | grep -i error

重启服务

docker compose restart backend

Worker 不工作

检查 Worker 状态

docker compose ps worker
docker compose logs worker

检查 Redis 连接

docker exec glean-redis redis-cli ping
# 应返回 PONG

重启 Worker

docker compose restart worker

RSS 订阅不更新

检查 Worker 日志

docker compose logs worker | grep -i feed

手动触发刷新

通过 Web 界面点击订阅源的刷新按钮。

检查订阅源状态

在 Web 界面查看订阅源是否显示错误状态。

无法访问 Web 界面

检查 Web 服务

docker compose ps web
docker compose logs web

检查 Nginx 配置

docker exec glean-web nginx -t

检查后端连接

# 直接访问后端 API
curl http://localhost:8000/api/health

管理后台无法访问

检查 Admin 服务

docker compose ps admin
docker compose logs admin

验证端口

curl http://localhost:3001

内存不足

检查内存使用

docker stats --no-stream

解决方案

1. 使用精简部署（不含 Milvus）
2. 增加系统内存
3. 设置资源限制

docker-compose.yml

services:
  backend:
    deploy:
      resources:
        limits:
          memory: 1G

磁盘空间不足

检查磁盘使用

docker system df

清理未使用资源

# 清理未使用的镜像
docker image prune -a

# 清理未使用的卷（注意不要删除 glean 的卷）
docker volume prune

# 清理停止的容器
docker container prune

日志轮转

# 截断 Docker 日志
truncate -s 0 $(docker inspect --format='{{.LogPath}}' glean-backend)

数据库问题

数据库迁移失败

# 检查迁移日志
docker compose logs backend | grep -i migration

# 手动执行迁移
docker exec -it glean-backend bash
cd /app && uv run alembic upgrade head

数据库连接数过多

检查并增加 PostgreSQL 连接数限制：

docker-compose.yml

services:
  postgres:
    command:
      - postgres
      - -c
      - max_connections=200

Milvus 问题（完整版）

Milvus 启动失败

# 检查 Milvus 依赖服务
docker compose ps milvus-etcd milvus-minio

# 检查 Milvus 日志
docker compose logs milvus

Milvus 内存不足

Milvus 需要较多内存，可以：

1. 增加系统内存
2. 使用精简部署模式

获取帮助

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

1. 查看文档：Glean 文档
2. GitHub Issues：提交 Issue
3. Discord 社区：加入 Discord

提交 Issue 时请包含：

• Glean 版本
• 部署方式（完整/精简）
• 错误日志
• 复现步骤