Ansible Semaphore 数据库连接端口配置问题分析与修复

Ansible Semaphore 是一款流行的开源 Ansible 自动化工具 Web 界面。在最近的 v2.10.33 版本中，用户报告了一个关键的数据库连接问题，特别是当 MySQL 服务器运行在非标准端口时会出现连接失败的情况。

问题背景

在 Docker 环境中部署 Semaphore 时，许多用户会选择使用外部 MySQL 数据库服务。正常情况下，用户可以通过环境变量 SEMAPHORE_DB_HOST 和 SEMAPHORE_DB_PORT 来配置数据库连接参数。然而，在 v2.10.33 版本中，当 MySQL 服务器运行在非标准端口（非 3306）时，系统会忽略指定的端口号，始终尝试连接默认的 3306 端口。

问题表现

从用户提供的日志中可以看到，虽然配置文件中正确指定了数据库主机和端口（3307），但实际连接时系统却尝试连接 3306 端口：

Pinging database on <fqdn> port 3307...
...
panic: dial tcp 192.168.17.21:3306: connect: connection refused

这种不一致行为导致服务无法启动，严重影响生产环境的使用。

技术分析

这个问题源于 v2.10.33 版本中数据库连接处理逻辑的变更。在之前的版本中，端口参数能够正确传递到数据库驱动层，但在新版本中，端口参数在解析过程中被意外丢弃或覆盖。

数据库连接配置通常涉及以下几个关键步骤：

1. 环境变量解析
2. 配置文件生成
3. 数据库驱动初始化
4. 连接建立

在 v2.10.33 中，第三步出现了问题，导致无论用户配置什么端口，系统都会回退到默认的 MySQL 端口 3306。

解决方案

开发团队迅速响应，在 v2.10.34 版本中修复了这个问题。修复的核心是确保：

1. 端口参数在整个连接流程中正确传递
2. 数据库驱动接收到完整的连接信息（包括非标准端口）
3. 连接字符串构建时包含指定的端口号

最佳实践

为避免类似问题，建议用户：

1. 在升级前总是检查版本变更日志
2. 在测试环境中验证新版本的关键功能
3. 对于数据库连接等关键配置，实施监控告警
4. 考虑使用连接池或重试机制增强鲁棒性

总结

这个案例展示了开源社区快速响应和修复问题的能力。对于使用 Ansible Semaphore 连接外部 MySQL 服务的用户，特别是使用非标准端口的情况，应及时升级到 v2.10.34 或更高版本以确保稳定性。同时，这也提醒我们在进行系统配置时，验证实际生效的参数与预期是否一致的重要性。