8个实战技巧：Terrakube开源项目常见问题全解析

🔍 配置类 | 服务启动失败问题

问题场景

当执行docker-compose up后，服务未正常启动且日志显示网络连接超时。

根因分析

容器间网络配置错误或端口冲突导致服务无法相互通信，主要与Docker网络模式和端口映射设置相关。

阶梯式解决方案

1. 检查docker-compose/docker-compose.yml文件中的网络配置，确保所有服务使用同一网络
2. 执行docker network ls确认terrakube网络存在
3. 修改冲突端口映射，如将默认8080端口改为8081
4. 执行docker-compose down -v清理残留网络后重新启动

[!NOTE] 适用于v1.5.0及以上版本，修改后需删除docker-compose目录下的.env文件重新生成配置

为什么这样有效

统一网络确保服务发现正常，端口冲突解决消除连接障碍，清理残留网络避免旧配置干扰。

预防措施

在docker-compose目录下创建.env.example模板文件，标注所有可配置端口及默认值，避免直接修改主配置文件。

⚠️ 高危问题 | 数据库连接失败

问题场景

应用启动后抛出"Connection refused"错误，数据库服务状态显示为healthy但无法建立连接。

根因分析

数据库连接字符串配置错误或服务依赖顺序问题，导致应用在数据库就绪前尝试连接。

阶梯式解决方案

1. 检查scripts/local/api.env中的数据库连接参数，确认SPRING_DATASOURCE_URL格式正确
2. 验证scripts/local/registry.env中的数据库认证信息与数据库容器配置一致
3. 在docker-compose.yml中添加服务依赖关系：depends_on: [postgres]
4. 重启数据库服务并观察日志确认初始化完成

[!NOTE] 适用于所有版本，生产环境建议使用数据库连接池配置SPRING_DATASOURCE_HIKARI_MAXIMUM-POOL-SIZE

为什么这样有效

正确的连接字符串是建立连接的基础，服务依赖确保启动顺序，连接池配置优化资源利用。

预防措施

在scripts/setup/目录下创建数据库初始化脚本，自动检查并配置必要的数据库用户和权限。

🔧 功能类 | 工作空间创建失败

问题场景

在UI中创建工作空间时提示"存储配置错误"，后台日志显示权限被拒绝。

根因分析

存储服务配置不正确或访问权限不足，导致无法创建工作空间元数据文件。

阶梯式解决方案

1. 检查registry/src/main/java/io/terrakube/registry/plugin/storage/目录下的存储实现类
2. 验证executor.env中的存储后端配置参数，确保访问密钥有效
3. 执行chmod -R 775 ./data修复本地存储目录权限
4. 重新启动registry服务使配置生效

[!NOTE] 适用于v1.4.0及以上版本，云存储需检查IAM策略是否允许服务账户读写操作

为什么这样有效

正确的存储实现确保使用合适的存储后端，权限修复消除文件系统访问障碍。

预防措施

在scripts/setupDevelopmentEnvironment.sh中添加存储权限自动检查步骤，部署时自动配置正确权限。

📊 性能类 | 执行器任务卡顿

问题场景

执行Terraform计划时任务长时间无响应，CPU使用率接近100%。

根因分析

执行器线程池配置不合理，导致资源竞争或任务队列溢出。

阶梯式解决方案

1. 打开executor/src/main/java/io/terrakube/executor/service/executor/ExecutorJobImpl.java
2. 调整corePoolSize参数从默认5增加到10，maxPoolSize增加到20
3. 设置queueCapacity为100避免任务排队溢出
4. 重启executor服务应用新配置

[!NOTE] 适用于v1.3.0及以上版本，调整时需考虑服务器CPU核心数，通常线程数不超过核心数2倍

为什么这样有效

合理的线程池配置平衡资源利用和任务处理效率，避免线程竞争和资源耗尽。

预防措施

在executor/src/main/resources/application.properties中添加线程池自动调整配置，根据系统负载动态调整参数。

🔗 集成类 | VCS Webhook配置问题

问题场景

代码提交后未触发自动执行，Webhook日志显示"403 Forbidden"错误。

根因分析

Webhook签名验证失败或请求URL配置错误，导致系统拒绝接收外部请求。

阶梯式解决方案

1. 检查api/src/main/java/io/terrakube/api/controller/WebhookController.java中的签名验证逻辑
2. 在VCS平台重新配置Webhook URL为http://<terrakube-api>/api/v1/webhook
3. 确保api.env中的WEBHOOK_SECRET与VCS平台配置一致
4. 使用curl -X POST命令测试Webhook端点连通性

[!NOTE] 适用于所有版本，建议使用HTTPS协议并配置正确的TLS证书

为什么这样有效

正确的URL和密钥确保请求来源可信，签名验证防止恶意请求，连通性测试验证网络路径。

预防措施

在ui/src/domain/Settings/VCS.tsx中添加Webhook测试功能，允许管理员验证配置正确性。

📝 数据类 | 状态文件访问失败

问题场景

执行terraform apply后提示"无法读取状态文件"，状态后端显示连接超时。

根因分析

状态后端配置错误或云存储服务访问权限不足，导致无法读写状态文件。

阶梯式解决方案

1. 检查executor/src/main/java/io/terrakube/executor/plugin/tfstate/configuration/目录下的状态配置
2. 验证executor.env中的云存储凭证是否有效且具有正确权限
3. 尝试手动使用terraform state pull命令测试状态访问
4. 重新配置状态后端为本地存储进行故障排除

[!NOTE] 适用于v1.2.0及以上版本，AWS S3后端需确保bucket名称符合DNS规范

为什么这样有效

正确的状态后端配置是状态文件访问的基础，权限验证确保服务账户有足够操作权限。

预防措施

在ui/src/domain/Workspaces/Settings/States.tsx中添加状态后端连接测试功能，创建工作空间时验证配置。

🔐 安全类 | 认证失败问题

问题场景

登录时提示"认证失败"，DEX服务日志显示"无效的客户端凭证"。

根因分析

DEX配置文件中的客户端ID或密钥与应用配置不匹配，导致OAuth2流程失败。

阶梯式解决方案

1. 检查scripts/setup/dex/docker-compose.yaml中的DEX配置
2. 验证api.env中的OAUTH_CLIENT_ID和OAUTH_CLIENT_SECRET与DEX配置一致
3. 清除浏览器缓存或使用无痕模式尝试重新登录
4. 重启DEX服务和API服务使配置生效

[!NOTE] 适用于所有版本，生产环境建议定期轮换客户端密钥

为什么这样有效

匹配的客户端凭证是OAuth2认证的基础，重启服务确保配置正确加载。

预防措施

在scripts/template/dex/template-config-ldap.yaml中使用环境变量替代硬编码凭证，便于配置管理。

🚀 前端类 | UI界面加载缓慢

问题场景

Terrakube UI加载时间超过10秒，浏览器控制台显示多个资源加载超时。

根因分析

前端资源未优化或CDN配置不当，导致静态资源加载延迟。

阶梯式解决方案

1. 检查ui/vite.config.mts中的构建配置，确保启用代码分割和压缩
2. 执行cd ui && yarn build重新构建优化后的前端资源
3. 验证ui/conf/conf.d/gzip.conf中的Gzip压缩配置是否启用
4. 清除浏览器缓存后重新访问UI

[!NOTE] 适用于v1.6.0及以上版本，生产环境建议使用CDN分发静态资源

为什么这样有效

代码分割减少初始加载资源大小，Gzip压缩降低传输数据量，CDN加速资源分发。

预防措施

在ui/package.json中添加预构建脚本，自动优化静态资源并生成缓存策略文件。

问题自检清单

检查项	检查方法	常见问题
网络配置	docker network inspect terrakube	网络隔离或IP冲突
数据库连接	telnet postgres 5432	连接字符串错误
存储权限	ls -la ./data	权限不足或所有者错误
线程池配置	查看executor日志	线程数过多导致资源耗尽
Webhook URL	检查VCS平台配置	URL错误或端口被防火墙阻止
状态后端	terraform state list	凭证过期或权限不足
DEX配置	查看DEX容器日志	客户端ID/密钥不匹配
前端资源	浏览器Network面板	未优化的大型JS文件
环境变量	cat scripts/local/*.env	缺失关键配置项
服务健康	docker-compose ps	依赖服务未正常启动

进阶技巧

1. 分布式追踪排查

通过配置Jaeger追踪执行器任务流程：

1. 在docker-compose.yml中添加Jaeger服务
2. 修改executor.env添加TRACING_ENABLED=true
3. 在UI的任务详情页面查看完整调用链

2. 性能基准测试

使用内置性能测试工具评估系统瓶颈：

1. 执行./scripts/setup/performance-test.sh
2. 查看reports/performance目录下的测试结果
3. 根据CPU、内存和响应时间数据优化配置