FerretDB v2.5 故障排查指南连接、认证、兼容性与性能问题定位【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址: https://gitcode.com/gh_mirrors/fe/FerretDBFerretDB 是一款真正的开源 MongoDB 替代品v2.x 使用 PostgreSQL 加 DocumentDB 扩展作为存储引擎。本文以 Troubleshooting overview 为骨架系统梳理 FerretDB v2.5 最常见的连接、认证、兼容性与性能问题并结合仓库源码与实际配置给出可复现的解决方案。读完本文你将掌握如何定位 Docker 环境下 DocumentDB 初始化失败、PLAIN认证被拒绝等典型报错并学会借助预迁移测试与可观测性工具主动排查问题。连接类问题Connectivity issues连接问题是 FerretDB 用户最常遇到的一类故障主要集中在两个场景Docker 中初始化 PostgreSQL 与 DocumentDB 扩展失败以及客户端使用不受支持的认证机制连接被拒。Docker 中初始化 PostgreSQL 与 DocumentDB 扩展报错报错现象在 Docker 中首次启动带 DocumentDB 扩展的 PostgreSQL 时如果初始化失败日志中通常会出现如下错误schema documentdb_api does not exist根因分析该错误的根源在于你挂载给容器的数据目录data directory或数据卷volume中已经存在一份未安装 DocumentDB 扩展的旧 PostgreSQL 数据。容器启动时 PostgreSQL 发现已有数据目录便跳过初始化流程但旧数据里没有documentdb_api等 DocumentDB 扩展所需 schema于是后续连接或初始化操作直接失败。从官方镜像的启动方式也能印证这一点FerretDB 官方提供的 PostgreSQL with DocumentDB 镜像如ghcr.io/ferretdb/postgres-documentdb:17-0.106.0-ferretdb-2.5.0在首次启动时会创建扩展所需的 schema参见 Docker 安装指南而数据目录的挂载路径直接决定了初始化是否重新执行。解决方案若旧数据目录已无用处直接删除它让容器重新初始化若旧数据仍需保留则更换数据目录路径。例如原路径为./data可改为./postgres-datadocker run -d \ --restart on-failure \ -e POSTGRES_USERusername \ -e POSTGRES_PASSWORDpassword \ -e POSTGRES_DBpostgres \ -v ./postgres-data:/var/lib/postgresql/data \ -p 5432:5432 \ ghcr.io/ferretdb/postgres-documentdb:17-0.106.0-ferretdb-2.5.0如果旧数据目录中有需要保留的业务数据需要先将其导出/迁移到新的 PostgreSQL 数据目录具体步骤可参考 MongoDB 迁移指南。提示官方镜像强烈建议使用完整镜像标签如17-0.106.0-ferretdb-2.5.0以保证各环境部署的一致性。更多初始化细节见 DocumentDB Docker 安装指南。连接 FerretDB 时出现认证错误PLAIN机制被拒绝报错现象使用PLAIN认证机制连接 FerretDB v2.x 时例如连接串mongodb://username:password127.0.0.1:27017/ferretdb?authMechanismPLAIN会收到如下错误Error: Received authentication for mechanism PLAIN which is not enabled.根因分析FerretDB v2.x 已不再支持PLAIN认证机制只支持SCRAM-SHA-256且认证默认开启。这一点在源码中有直接体现在 internal/handler/msg_saslstart.go 中saslStart命令处理逻辑会读取客户端请求的mechanism参数凡是mechanism ! SCRAM-SHA-256的情况都会返回Received authentication for mechanism %s which is not enabled并附带MechanismUnavailable错误码if mechanism ! SCRAM-SHA-256 { msg : fmt.Sprintf( Received authentication for mechanism %s which is not enabled, mechanism, ) return nil, mongoerrors.NewWithArgument(mongoerrors.ErrMechanismUnavailable, msg, mechanism) }也就是说PLAIN、MONGODB-X509、SCRAM-SHA-1等机制在 v2.x 中都会触发同样的拒绝逻辑客户端只能使用SCRAM-SHA-256。项目还专门编写了认证测试来验证这一行为见 integration/auth_test.go。解决方案去掉连接串中的authMechanismPLAIN让客户端默认使用SCRAM-SHA-256mongodb://username:password127.0.0.1:27017/认证机制的完整说明包括如何在 PostgreSQL 中创建用户、如何通过createUser命令创建用户、以及如何关闭认证参见 FerretDB 认证指南。需要特别提醒两点连接串中的用户名密码必须已存在于 PostgreSQL。FerretDB 自身不存储任何认证信息所有用户凭据都由 PostgreSQL 管理和校验即使不提供凭据匿名客户端也能建立到 FerretDB 的 TCP 连接但无法访问或操作数据库。兼容性问题Compatibility issuesFerretDB 的目标是与 MongoDB 保持高度兼容但任何替代方案在迁移前都值得做一次系统性验证。如果你在迁移或日常使用中遇到命令不兼容、行为不一致等问题官方推荐先阅读 预迁移测试指南它能在数据正式迁移之前帮你识别潜在兼容性风险。预迁移测试的核心思路是利用操作模式operation modes让 FerretDB 充当代理与真实 MongoDB 并行处理同一请求并比对结果diff-normal模式FerretDB 正常处理请求若某个命令尚未实现错误会直接返回给客户端方便第一时间暴露问题diff-proxy模式FerretDB 将请求转发给代理指向的 MongoDB并输出两份响应的差异diff用于发现细微行为差异。例如在diff-proxy模式下执行db.runCommand({ dataSize: DB-NAME.locations })MongoDB 返回了正常结果但 diff 输出会显示 FerretDB 对该命令返回NotImplemented从而精准定位未实现的功能。两种模式的启动方式与参数--mode、--proxy-addr、--listen-addr等详见 操作模式文档 与 flags 文档。性能问题Performance issues如果你的 FerretDB 出现性能问题或希望提前评估性能表现可观测性observability工具是第一道防线。官方 可观测性指南 覆盖了日志、OpenTelemetry 追踪、debug 处理器、指标与健康探针五个维度日志LoggingFerretDB 将结构化日志写入标准错误流stderr支持console、textlogfmt、json、mongo类 MongoDB 的 Relaxed Extended JSON四种格式以及error、warn、info、debug四个级别默认级别为info。注意debug级别会输出完整的查询/响应体、错误信息甚至认证凭据且会显著影响性能生产环境切勿开启OpenTelemetry 追踪可通过--otel-traces-url配置将追踪数据发送到 OTLP 端点如http://host:4318/v1/tracesDebug 处理器默认监听http://127.0.0.1:8088/debug/提供/debug/archive调试信息 zip 归档、/debug/metricsPrometheus 格式指标无需外部导出器等端点健康探针/debug/livez存活探针检查是否可接受 MongoDB 协议连接与/debug/readyz就绪探针通过发送ping验证 PostgreSQL 连接与 DocumentDB 安装是否正确返回 2xx 表示正常、5xx 表示异常可直接用于 Kubernetes 健康检查。此外预迁移测试中提到的响应指标response metrics也能辅助性能定位在开发构建development build退出时指标会写入标准输出其中ferretdb_client_requests_total与ferretdb_client_responses_total可以直接显示应用发起的每条命令及其结果如resultNotImplemented快速圈定不兼容或拖慢整体响应的命令。其他问题Other issues如果上述方案未能解决你的问题或者你遇到了文档未覆盖的其他异常请按以下步骤处理查看日志Docker 部署场景可直接使用docker compose logs ferretdb获取日志其他部署方式可用docker ps找到容器后执行docker logs提供详细信息在向社区求助时附上完整的日志片段、复现步骤、FerretDB 版本如 v2.5.x、PostgreSQL 与 DocumentDB 扩展版本能显著加快问题定位访问社区渠道可前往 项目介绍页的社区部分 寻找官方社区联系方式。小结本文围绕 FerretDB v2.5 的常见故障场景给出了从现象 → 根因 → 解决的完整排查路径Docker 环境下schema documentdb_api does not exist提示数据目录不匹配需更换或清理数据目录PLAIN认证报错源于 v2.x 仅支持SCRAM-SHA-256源码 internal/handler/msg_saslstart.go 中有明确的机制白名单判断兼容性问题可借助diff-normal/diff-proxy模式做预迁移验证性能问题则通过日志、追踪、指标与健康探针组合定位。掌握这些手段后无论是日常排障还是迁移评估你都能快速找到问题症结。【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址: https://gitcode.com/gh_mirrors/fe/FerretDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考