FreshRSS Docker Compose 配置参数格式问题解析

在使用 Docker Compose 部署 FreshRSS 时，用户可能会遇到环境变量参数格式不匹配的问题。本文将从技术角度解析该问题的成因及解决方案。

问题现象

当用户按照文档配置 FreshRSS 的 Docker 环境时，若使用 api-enabled 这类带连字符的参数格式，容器会报出"unknown options"错误。这实际上是新旧版本参数命名规范的差异导致的兼容性问题。

技术背景

FreshRSS 在 1.24.0 版本中对 Docker 环境变量命名规范进行了标准化调整：

• 旧版本使用连字符格式：api-enabled
• 新版本改用下划线格式：api_enabled

这种变更是为了遵循 Docker 环境变量的通用命名惯例，通常建议使用下划线作为单词分隔符。

解决方案

根据使用场景不同，用户可采取以下两种方案：

方案一：使用稳定版本（1.23.x及以下）

environment:
  - api-enabled=true

方案二：使用开发版（1.24.0+）

environment:
  - api_enabled=true

版本选择建议

1. 生产环境：建议等待 1.24.0 正式发布后统一采用下划线格式
2. 测试环境：可使用 edge 标签体验最新特性

   image: freshrss/freshrss:edge
   

最佳实践

为避免此类问题，建议：

1. 明确标注使用的 FreshRSS 版本号
2. 查阅对应版本的官方文档
3. 在 CI/CD 流程中加入版本兼容性检查
4. 使用环境变量验证工具检查参数格式

通过理解参数格式变更的技术背景，开发者可以更灵活地应对不同版本的配置需求，确保服务稳定运行。