CSGHub项目部署常见问题排查指南

部署环境检查要点

在部署CSGHub开源项目时，系统管理员需要特别注意以下几个关键服务组件的状态：

1. 核心依赖服务：

   • Gitea服务（用户认证基础）
   • User Server（用户管理服务）
   • CSGHub Server Runner（核心业务处理器）
   • Redis（缓存服务）

2. 数据库组件：

   • PostgreSQL（主数据库）
   • 需要确认git_server_access_tokens等核心表是否正常创建

典型问题解决方案

服务启动失败处理

Gitea服务启动异常：

• 检查挂载目录权限，确保/opt/bitnami/gitea目录具有755权限
• 验证docker-compose.yml中的volume配置是否正确映射

User Server初始化失败：

• 确认Gitea服务已正常启动并能连接
• 检查PostgreSQL中git_server_access_tokens表是否存在
• 查看csghub-server日志中的表结构初始化错误

Redis连接问题：

• 验证redis配置参数
• 检查网络连通性

前端访问异常处理

当出现"获取不到数据"错误时，建议按以下步骤排查：

1. 浏览器开发者工具检查XHR请求状态
2. 确认后端服务API端点是否可达
3. 检查跨域配置（CORS）
4. 验证JWT令牌有效性

配置注意事项

1. 网络配置：

   • 确保docker-compose.yml中的networks配置正确
   • 检查development.rb中的网络开放设置

2. 服务依赖：

   • 16个服务中关键服务必须全部启动
   • 特别注意gitea和user_server的启动顺序

3. 日志分析：

   • portal日志（位于安装目录log/文件夹）
   • starhub_server服务日志
   • 容器日志（通过docker logs命令获取）

最佳实践建议

1. 首次部署时建议逐步启动服务，观察每个组件的启动日志
2. 数据库初始化后验证核心表结构
3. 生产环境部署前进行完整的功能测试
4. 保持组件版本与官方文档要求一致

通过系统化的排查方法，可以快速定位和解决CSGHub部署过程中的各类问题，确保平台正常运转。