FerretDB v1.22 初始用户设置Initial User Setup功能详解从启动配置到认证实战【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址: https://gitcode.com/gh_mirrors/fe/FerretDBFerretDB v1.22.0 作为 v1.x 系列后期版本带来了两项关键能力通过专用 flags 或环境变量在实例启动阶段完成初始用户的创建与认证启用以及将文档大小上限从固定的 16MiB 改为可配置。本文基于当前仓库中的发布文档release blog与 v1.x 官方文档authentication、flags结合仓库源码系统讲解初始用户设置功能的配置项、命令行与 Docker 实战以及文档大小限制的调整方法帮助读者在部署 FerretDB 的第一时间完成安全加固。发布背景v1.x 系列末期的功能收官v1.22.0 是 FerretDB v1.x 系列后期的版本之一。这个版本聚焦于提升开箱即用的安全性与部署体验用户可以在一开始就为实例配置初始认证用户按需调整文档大小限制同时收获一系列 Bug 修复与增强。按照发布文档的说明官方团队在持续推进 v2.0 的开发v2.0 将从根本上重构架构并大幅提升性能与兼容性因此 v1.22.0 中的这些能力可以视为 v1.x 架构下对认证与存储限制的一次系统性补齐。启用实验性认证模式初始用户设置功能建立在 FerretDB 的实验性认证模式experimental authentication mode之上。该模式支持SCRAM-SHA-1与SCRAM-SHA-256两种认证机制让 FerretDB 能够自行管理用户并提供createUser、dropAllUsersFromDatabase、dropUser、updateUser、usersInfo等用户管理命令对应仓库中的实现文件如 msg_createuser.go、msg_dropuser.go、msg_updateuser.go、msg_usersinfo.go认证机制实现位于 internal/scram。启用方式非常简单将--test-enable-new-auth设置为trueferretdb --test-enable-new-authtrue需要说明的是该模式在 v1.x 阶段以test-前缀标记属于实验性能力正如 v1.19 发布说明所述该 flag 在--help输出中默认隐藏主要用于测试与先行验证。在当前仓库的 v2.x 主分支中CLI 定义位于 cmd/ferretdb/main.go认证开关以--auth默认true可--no-auth关闭形式存在v1.x 的test-前缀 flag 体系已随架构演进发生变化使用 v1.22 及以上 v1.x 版本时请以版本化文档为准。初始用户设置一行命令完成安全启动启用实验性认证模式后即可通过三个专用配置项在实例启动阶段创建初始用户与数据库ferretdb --test-enable-new-authtrue --setup-usernameuser --setup-passwordpass --setup-databaseferretdb启动时 FerretDB 会按给定用户名、密码创建用户并同时创建指定的初始数据库。一旦这些 flags 被传入实例从第一个请求开始就具备可用的认证凭据。配置项速查表命令行 Flag环境变量说明--setup-usernameFERRETDB_SETUP_USERNAME要创建的初始用户名--setup-passwordFERRETDB_SETUP_PASSWORD该用户的密码可以为空--setup-databaseFERRETDB_SETUP_DATABASE初始化时创建的数据库名--setup-timeoutFERRETDB_SETUP_TIMEOUT初始化超时时间默认30s见 flags.md--test-enable-new-authFERRETDB_TEST_ENABLE_NEW_AUTH必须为true才会启用认证设置默认falseflags 与环境变量的对应机制FerretDB 的配置体系遵循“云原生友好”的设计原则每个 flag 都有对应的环境变量且不存在配置文件全部配置通过命令行或环境变量注入。这一机制在源码层面由 cmd/ferretdb/main.go 中的kong.DefaultEnvars(FERRETDB)实现CLI 解析器kong会自动为每个字段生成以FERRETDB_为前缀的环境变量名例如--setup-username对应FERRETDB_SETUP_USERNAME、--test-enable-new-auth对应FERRETDB_TEST_ENABLE_NEW_AUTH。这意味着在容器化或 Kubernetes 部署中完全可以通过环境变量完成初始化而无需改写启动命令。安全要点密码允许为空--setup-password可留空但生产环境强烈建议设置强密码实验性认证模式下用户名与密码的传输依赖 TLS 保护参见 tls-connections--test-enable-new-auth未开启时setup-*配置不会生效初始化流程不会创建用户与数据库。Docker 部署实战Postgres 后端在 Docker Compose 场景下推荐直接使用环境变量完成初始用户设置。以下是官方文档authentication.md给出的 Postgres 后端典型配置services: postgres: image: postgres environment: - POSTGRES_USERusername - POSTGRES_PASSWORDpassword - POSTGRES_DBferretdb volumes: - ./data:/var/lib/postgresql/data ferretdb: image: ghcr.io/ferretdb/ferretdb:1 restart: on-failure ports: - 27017:27017 environment: - FERRETDB_POSTGRESQL_URLpostgres://username:passwordpostgres:5432/ferretdb - FERRETDB_TEST_ENABLE_NEW_AUTHtrue - FERRETDB_SETUP_USERNAMEuser - FERRETDB_SETUP_PASSWORDpass - FERRETDB_SETUP_DATABASEferretdb networks: default: name: ferretdb启动服务docker compose up -d服务就绪后使用初始化阶段创建的凭据通过mongosh连接mongosh mongodb://user:passferretdb/ferretdb这条连接串中的user:pass正是FERRETDB_SETUP_USERNAME与FERRETDB_SETUP_PASSWORD创建的用户数据库名对应FERRETDB_SETUP_DATABASE。Docker 部署实战SQLite 后端使用 SQLite 后端--handlersqlite时同样可以配置初始用户。官方文档给出了对应的 Compose 示例services: ferretdb: image: ghcr.io/ferretdb/ferretdb:1 restart: on-failure ports: - 27017:27017 environment: - FERRETDB_HANDLERsqlite - FERRETDB_TEST_ENABLE_NEW_AUTHtrue - FERRETDB_SETUP_USERNAMEuser - FERRETDB_SETUP_PASSWORDpass - FERRETDB_SETUP_DATABASEferretdb volumes: - ./state:/state networks: default: name: ferretdbSQLite 后端与 Postgres 后端的初始化流程一致启动后即拥有user用户与ferretdb数据库连接方式与上文mongosh命令相同。注意 SQLite 后端通过FERRETDB_SQLITE_URL指定数据目录Docker 镜像默认指向/state因此需要挂载./state:/state持久化数据。与用户管理命令的配合使用初始用户设置并非孤立的启动行为它建立在完整的用户管理命令体系之上。仓库的集成测试目录 integration/auth 中包含create_user_test.go、drop_user_test.go、update_user_test.go、usersinfo_test.go等测试文件覆盖了用户创建、删除、更新与查询的完整生命周期。实际使用中初始设置创建的用户与后续通过createUser命令创建的用户存放在同一套用户存储中管理员可继续使用usersInfo查看用户列表用updateUser修改密码与角色用dropUser清理不再需要的账号需要清空某个数据库下所有用户时可使用dropAllUsersFromDatabase。也就是说初始用户设置解决了“第一个用户从哪里来”的引导问题而后续的账号治理则交给这些标准 MongoDB 兼容命令两者共同构成 v1.x 实验性认证模式的完整闭环。可配置的最大文档大小限制FerretDB 此前对单文档大小设有固定的 16MiB 上限。在处理超大文档或进行大规模数据迁移时这个限制并不总是实用。v1.22.0 将其改为可配置通过以下两个 flags 或对应环境变量调整命令行 Flag环境变量作用--test-batch-sizeFERRETDB_TEST_BATCH_SIZE调整批次大小相关行为--test-max-bson-object-size-mi-bFERRETDB_TEST_MAX_BSON_OBJECT_SIZE_MI_B设置单个 BSON 文档的最大体积单位 MiB例如将文档上限从默认 16MiB 提升到 64MiBferretdb --test-max-bson-object-size-mi-b64需要注意的是这两个参数同样以test-前缀标记属于 v1.x 阶段用于兼容性与迁移场景的调优手段并且 flag 命名中的mi-b后缀明确表示单位为 MiB二进制兆字节。在调整该值时还应同步评估后端存储PostgreSQL 的max_allowed_packet类限制或 SQLite 的页大小配置能否承载更大尺寸的文档写入。本次发布的 Bug 修复与增强除了上述两项新特性v1.22.0 还包含一系列部署与行为层面的改进发布文档中明确列出以下几点Docker 镜像以非 root 用户运行生产环境的 Docker 镜像现在以非 root 用户运行 FerretDB 进程避免容器内进程持有 root 权限。配套的Dockerfile显式设置了状态目录的所有权归属ferretdb用户确保即便使用匿名卷anonymous volumes挂载目录权限也是正确的。这降低了容器逃逸与权限滥用的风险面。state.json 所有权/权限错误信息改进当state.json文件的属主或权限不合法时FerretDB 会输出更清晰的错误信息并在日志中记录当前的用户与用户组便于运维人员快速定位是权限不足还是属主不匹配导致的状态文件读取失败。文档字段按字典序排序更新操作时文档字段现在按照字典序lexicographic order排序使字段顺序一致且可预测。例如bar排在foo之前7排在42之前bar.7排在bar.42之前。这一调整让序列化与比较行为更稳定对依赖字段顺序做哈希或校验的场景尤为重要。其他修复修复了 Docker 镜像中的 TCP 端口处理器问题修复了使用嵌入式 FerretDB 包embedded FerretDB package时出现的 batch-size 错误。总结与版本说明FerretDB v1.22.0 通过初始用户设置、可配置文档大小限制以及一系列安全与稳定性修复显著改善了 v1.x 的部署体验初始用户设置--setup-username/--setup-password/--setup-database及FERRETDB_*环境变量配合--test-enable-new-authtrue在实例启动瞬间完成认证用户与初始数据库的创建配合 Docker Compose 可直接落地文档大小限制可配置通过--test-max-bson-object-size-mi-b突破固定 16MiB 限制适配大文档与迁移场景安全与稳定性非 root 运行、更清晰的state.json错误信息、字段字典序排序等。需要特别提醒的是上述setup-*与test-*前缀参数属于 v1.x 版本的配置体系本文所引用的 flags 表格与认证文档均来自仓库的 version-v1.24 版本化文档。当前仓库主分支已演进至 v2.x 架构CLI 入口见 cmd/ferretdb/main.gov1.x 与 v2.x 的认证与配置方式存在差异实际部署时请务必对照与所使用版本匹配的文档。若想深入了解认证模式的完整机制与用户管理命令可继续阅读 authentication 文档 与 integration/auth 下的集成测试。【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址: https://gitcode.com/gh_mirrors/fe/FerretDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FerretDB v1.22 初始用户设置（Initial User Setup）功能详解：从启动配置到认证实战
FerretDB v1.22 初始用户设置Initial User Setup功能详解从启动配置到认证实战【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址: https://gitcode.com/gh_mirrors/fe/FerretDBFerretDB v1.22.0 作为 v1.x 系列后期版本带来了两项关键能力通过专用 flags 或环境变量在实例启动阶段完成初始用户的创建与认证启用以及将文档大小上限从固定的 16MiB 改为可配置。本文基于当前仓库中的发布文档release blog与 v1.x 官方文档authentication、flags结合仓库源码系统讲解初始用户设置功能的配置项、命令行与 Docker 实战以及文档大小限制的调整方法帮助读者在部署 FerretDB 的第一时间完成安全加固。发布背景v1.x 系列末期的功能收官v1.22.0 是 FerretDB v1.x 系列后期的版本之一。这个版本聚焦于提升开箱即用的安全性与部署体验用户可以在一开始就为实例配置初始认证用户按需调整文档大小限制同时收获一系列 Bug 修复与增强。按照发布文档的说明官方团队在持续推进 v2.0 的开发v2.0 将从根本上重构架构并大幅提升性能与兼容性因此 v1.22.0 中的这些能力可以视为 v1.x 架构下对认证与存储限制的一次系统性补齐。启用实验性认证模式初始用户设置功能建立在 FerretDB 的实验性认证模式experimental authentication mode之上。该模式支持SCRAM-SHA-1与SCRAM-SHA-256两种认证机制让 FerretDB 能够自行管理用户并提供createUser、dropAllUsersFromDatabase、dropUser、updateUser、usersInfo等用户管理命令对应仓库中的实现文件如 msg_createuser.go、msg_dropuser.go、msg_updateuser.go、msg_usersinfo.go认证机制实现位于 internal/scram。启用方式非常简单将--test-enable-new-auth设置为trueferretdb --test-enable-new-authtrue需要说明的是该模式在 v1.x 阶段以test-前缀标记属于实验性能力正如 v1.19 发布说明所述该 flag 在--help输出中默认隐藏主要用于测试与先行验证。在当前仓库的 v2.x 主分支中CLI 定义位于 cmd/ferretdb/main.go认证开关以--auth默认true可--no-auth关闭形式存在v1.x 的test-前缀 flag 体系已随架构演进发生变化使用 v1.22 及以上 v1.x 版本时请以版本化文档为准。初始用户设置一行命令完成安全启动启用实验性认证模式后即可通过三个专用配置项在实例启动阶段创建初始用户与数据库ferretdb --test-enable-new-authtrue --setup-usernameuser --setup-passwordpass --setup-databaseferretdb启动时 FerretDB 会按给定用户名、密码创建用户并同时创建指定的初始数据库。一旦这些 flags 被传入实例从第一个请求开始就具备可用的认证凭据。配置项速查表命令行 Flag环境变量说明--setup-usernameFERRETDB_SETUP_USERNAME要创建的初始用户名--setup-passwordFERRETDB_SETUP_PASSWORD该用户的密码可以为空--setup-databaseFERRETDB_SETUP_DATABASE初始化时创建的数据库名--setup-timeoutFERRETDB_SETUP_TIMEOUT初始化超时时间默认30s见 flags.md--test-enable-new-authFERRETDB_TEST_ENABLE_NEW_AUTH必须为true才会启用认证设置默认falseflags 与环境变量的对应机制FerretDB 的配置体系遵循“云原生友好”的设计原则每个 flag 都有对应的环境变量且不存在配置文件全部配置通过命令行或环境变量注入。这一机制在源码层面由 cmd/ferretdb/main.go 中的kong.DefaultEnvars(FERRETDB)实现CLI 解析器kong会自动为每个字段生成以FERRETDB_为前缀的环境变量名例如--setup-username对应FERRETDB_SETUP_USERNAME、--test-enable-new-auth对应FERRETDB_TEST_ENABLE_NEW_AUTH。这意味着在容器化或 Kubernetes 部署中完全可以通过环境变量完成初始化而无需改写启动命令。安全要点密码允许为空--setup-password可留空但生产环境强烈建议设置强密码实验性认证模式下用户名与密码的传输依赖 TLS 保护参见 tls-connections--test-enable-new-auth未开启时setup-*配置不会生效初始化流程不会创建用户与数据库。Docker 部署实战Postgres 后端在 Docker Compose 场景下推荐直接使用环境变量完成初始用户设置。以下是官方文档authentication.md给出的 Postgres 后端典型配置services: postgres: image: postgres environment: - POSTGRES_USERusername - POSTGRES_PASSWORDpassword - POSTGRES_DBferretdb volumes: - ./data:/var/lib/postgresql/data ferretdb: image: ghcr.io/ferretdb/ferretdb:1 restart: on-failure ports: - 27017:27017 environment: - FERRETDB_POSTGRESQL_URLpostgres://username:passwordpostgres:5432/ferretdb - FERRETDB_TEST_ENABLE_NEW_AUTHtrue - FERRETDB_SETUP_USERNAMEuser - FERRETDB_SETUP_PASSWORDpass - FERRETDB_SETUP_DATABASEferretdb networks: default: name: ferretdb启动服务docker compose up -d服务就绪后使用初始化阶段创建的凭据通过mongosh连接mongosh mongodb://user:passferretdb/ferretdb这条连接串中的user:pass正是FERRETDB_SETUP_USERNAME与FERRETDB_SETUP_PASSWORD创建的用户数据库名对应FERRETDB_SETUP_DATABASE。Docker 部署实战SQLite 后端使用 SQLite 后端--handlersqlite时同样可以配置初始用户。官方文档给出了对应的 Compose 示例services: ferretdb: image: ghcr.io/ferretdb/ferretdb:1 restart: on-failure ports: - 27017:27017 environment: - FERRETDB_HANDLERsqlite - FERRETDB_TEST_ENABLE_NEW_AUTHtrue - FERRETDB_SETUP_USERNAMEuser - FERRETDB_SETUP_PASSWORDpass - FERRETDB_SETUP_DATABASEferretdb volumes: - ./state:/state networks: default: name: ferretdbSQLite 后端与 Postgres 后端的初始化流程一致启动后即拥有user用户与ferretdb数据库连接方式与上文mongosh命令相同。注意 SQLite 后端通过FERRETDB_SQLITE_URL指定数据目录Docker 镜像默认指向/state因此需要挂载./state:/state持久化数据。与用户管理命令的配合使用初始用户设置并非孤立的启动行为它建立在完整的用户管理命令体系之上。仓库的集成测试目录 integration/auth 中包含create_user_test.go、drop_user_test.go、update_user_test.go、usersinfo_test.go等测试文件覆盖了用户创建、删除、更新与查询的完整生命周期。实际使用中初始设置创建的用户与后续通过createUser命令创建的用户存放在同一套用户存储中管理员可继续使用usersInfo查看用户列表用updateUser修改密码与角色用dropUser清理不再需要的账号需要清空某个数据库下所有用户时可使用dropAllUsersFromDatabase。也就是说初始用户设置解决了“第一个用户从哪里来”的引导问题而后续的账号治理则交给这些标准 MongoDB 兼容命令两者共同构成 v1.x 实验性认证模式的完整闭环。可配置的最大文档大小限制FerretDB 此前对单文档大小设有固定的 16MiB 上限。在处理超大文档或进行大规模数据迁移时这个限制并不总是实用。v1.22.0 将其改为可配置通过以下两个 flags 或对应环境变量调整命令行 Flag环境变量作用--test-batch-sizeFERRETDB_TEST_BATCH_SIZE调整批次大小相关行为--test-max-bson-object-size-mi-bFERRETDB_TEST_MAX_BSON_OBJECT_SIZE_MI_B设置单个 BSON 文档的最大体积单位 MiB例如将文档上限从默认 16MiB 提升到 64MiBferretdb --test-max-bson-object-size-mi-b64需要注意的是这两个参数同样以test-前缀标记属于 v1.x 阶段用于兼容性与迁移场景的调优手段并且 flag 命名中的mi-b后缀明确表示单位为 MiB二进制兆字节。在调整该值时还应同步评估后端存储PostgreSQL 的max_allowed_packet类限制或 SQLite 的页大小配置能否承载更大尺寸的文档写入。本次发布的 Bug 修复与增强除了上述两项新特性v1.22.0 还包含一系列部署与行为层面的改进发布文档中明确列出以下几点Docker 镜像以非 root 用户运行生产环境的 Docker 镜像现在以非 root 用户运行 FerretDB 进程避免容器内进程持有 root 权限。配套的Dockerfile显式设置了状态目录的所有权归属ferretdb用户确保即便使用匿名卷anonymous volumes挂载目录权限也是正确的。这降低了容器逃逸与权限滥用的风险面。state.json 所有权/权限错误信息改进当state.json文件的属主或权限不合法时FerretDB 会输出更清晰的错误信息并在日志中记录当前的用户与用户组便于运维人员快速定位是权限不足还是属主不匹配导致的状态文件读取失败。文档字段按字典序排序更新操作时文档字段现在按照字典序lexicographic order排序使字段顺序一致且可预测。例如bar排在foo之前7排在42之前bar.7排在bar.42之前。这一调整让序列化与比较行为更稳定对依赖字段顺序做哈希或校验的场景尤为重要。其他修复修复了 Docker 镜像中的 TCP 端口处理器问题修复了使用嵌入式 FerretDB 包embedded FerretDB package时出现的 batch-size 错误。总结与版本说明FerretDB v1.22.0 通过初始用户设置、可配置文档大小限制以及一系列安全与稳定性修复显著改善了 v1.x 的部署体验初始用户设置--setup-username/--setup-password/--setup-database及FERRETDB_*环境变量配合--test-enable-new-authtrue在实例启动瞬间完成认证用户与初始数据库的创建配合 Docker Compose 可直接落地文档大小限制可配置通过--test-max-bson-object-size-mi-b突破固定 16MiB 限制适配大文档与迁移场景安全与稳定性非 root 运行、更清晰的state.json错误信息、字段字典序排序等。需要特别提醒的是上述setup-*与test-*前缀参数属于 v1.x 版本的配置体系本文所引用的 flags 表格与认证文档均来自仓库的 version-v1.24 版本化文档。当前仓库主分支已演进至 v2.x 架构CLI 入口见 cmd/ferretdb/main.gov1.x 与 v2.x 的认证与配置方式存在差异实际部署时请务必对照与所使用版本匹配的文档。若想深入了解认证模式的完整机制与用户管理命令可继续阅读 authentication 文档 与 integration/auth 下的集成测试。【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址: https://gitcode.com/gh_mirrors/fe/FerretDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考