Speedtest-Tracker 部署中遇到的加密配置问题解析

在使用 Speedtest-Tracker 进行网络测速监控时，一个常见的部署错误是环境变量配置不当导致的加密初始化失败。本文将深入分析这一问题的成因及解决方案。

问题现象

当用户按照标准文档部署 Speedtest-Tracker 容器后，访问 Web 界面时出现"Internal Server Error"。查看日志会发现如下关键错误信息：

Unsupported cipher or incorrect key length. Supported ciphers are: aes-128-cbc, aes-256-cbc, aes-128-gcm, aes-256-gcm

根本原因

这个问题通常源于 docker-compose.yml 文件中环境变量值的格式问题。具体表现为：

1. 环境变量值包含前导空格：在 YAML 语法中，环境变量值如果以空格开头，这些空格会被保留为值的一部分
2. APP_KEY 格式错误：Laravel 框架要求加密密钥必须是特定格式的 base64 字符串
3. 配置项解析异常：空格导致系统无法正确识别加密算法和密钥长度

解决方案

修正 docker-compose.yml 文件中的环境变量定义，确保所有值都不含前导空格：

environment:
  - PUID=1000
  - PGID=1000
  - APP_KEY=base64:Ra6wk3l4wsR4NXMx7NuJKSN8kj34oOPpp4CjZ2JgENE=
  - DB_CONNECTION=sqlite
  - SPEEDTEST_SCHEDULE=0 */4 * * *
  - SPEEDTEST_SERVERS=5400,47048,3974
  - PRUNE_RESULTS_OLDER_THAN=20

技术细节

1. Laravel 加密机制：Speedtest-Tracker 基于 Laravel 框架，使用 APP_KEY 进行数据加密
2. 密钥格式要求：必须是以"base64:"开头的 32 字符随机字符串
3. YAML 语法特性：YAML 对空格敏感，前导空格会被视为值的一部分
4. 加密算法支持：系统仅支持 AES-128/256 的 CBC 和 GCM 模式

最佳实践建议

1. 使用 docker-compose config 命令验证配置文件语法
2. 生成新的 APP_KEY 而非使用示例密钥
3. 在复杂配置场景下，考虑使用 .env 文件替代直接的环境变量定义
4. 部署前使用 YAML 验证工具检查格式

通过正确处理环境变量格式，可以确保 Speedtest-Tracker 的加密系统正常初始化，从而避免此类服务启动失败的问题。