认证鉴权后端【免费下载链接】openfgaA high-performance and flexible authorization/permission engine built for developers and inspired by Google Zanzibar.项目地址https://gitcode.com/gh_mirrors/op/openfga点击查看免费下载本指南围绕 OpenFGA v1.18.0 随附的 MySQL 迁移008_collate_identifiers.sql展开说明为何要将tuple、changelog、authorization_model三张表的标识符列转换为大小写敏感的utf8mb4_bin排序规则以及运维人员如何在带写入流量的生产环境安全地执行该迁移。读完本文你将掌握迁移的 SQL 细节、openfga migrate命令的完整用法、迁移期间的锁与连接池行为、验证与回滚流程以及在线变更工具gh-ost / pt-online-schema-change的替代方案。背景为什么标识符必须大小写敏感OpenFGA 的身份标识identity是大小写区分的例如user:Alice与user:alice在授权语义中是两个完全不同的实体。如果底层数据库使用大小写不敏感的排序规则collation这两条 tuple 会被存储引擎视为同一行导致授权判定出现严重漏洞——本应互相独立的两个身份被合并处理。v1.18.0 之前MySQL 迁移初始化的表结构见 001_initialize_schema.sql中tuple、changelog、authorization_model的标识符列均未显式指定排序规则默认继承了库级或表级的 case-insensitive collation。v1.18.0 发布的 goose 迁移008_collate_identifiers.sql正是为了修复这一问题将相关列统一转换为utf8mb4_bin确保大小写不同的 OpenFGA 身份被存储和比较为不同的值。迁移覆盖范围008_collate_identifiers.sql共修改三张表涉及的列如下表受影响列tupleobject_type、relation、_user、condition_namechangelogobject_type、object_id、relation、_user、condition_nameauthorization_modeltype其中tuple.object_id已由更早的迁移007_collate_object_id.sql见 007_collate_object_id.sql先行转换为utf8mb4_bin008 完成其余列的收尾工作。需要注意ULID 列如tuple.ulid、store/authorization_model 的 ID 列是仅使用大写 Crockford-base32 字符集生成的不受大小写不敏感排序规则影响因此迁移刻意不触碰这些列。同时迁移在每条MODIFY COLUMN中显式指定了CHARACTER SET utf8mb4这保证了即使部署环境的既有列是在非 utf8mb4 字符集如老版本 MySQL 默认的 utf8mb3下创建的迁移也能干净地应用不会因为字符集不一致而出错。迁移 SQL 逐条拆解以 008_collate_identifiers.sql 的实际内容为准Up 方向共三条ALTER TABLE均在末尾使用LOCK SHARED-- goose Up ALTER TABLE tuple MODIFY COLUMN object_type VARCHAR(128) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL, MODIFY COLUMN relation VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL, MODIFY COLUMN _user VARCHAR(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL, MODIFY COLUMN condition_name VARCHAR(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NULL, LOCK SHARED; ALTER TABLE changelog MODIFY COLUMN object_type VARCHAR(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL, MODIFY COLUMN object_id VARCHAR(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL, MODIFY COLUMN relation VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL, MODIFY COLUMN _user VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL, MODIFY COLUMN condition_name VARCHAR(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NULL, LOCK SHARED; ALTER TABLE authorization_model MODIFY COLUMN type VARCHAR(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL, LOCK SHARED;关键细节说明列长度保持不变MODIFY COLUMN必须完整重写列定义迁移严格保留了原列的长度与NULL/NOT NULL约束如condition_name保持可空、其余标识符列保持非空避免副作用LOCK SHARED是唯一可选方案MySQL 不支持对排序规则变更使用LOCK NONE因此迁移只能以共享锁方式执行Down 迁移的风险Down 方向同样以LOCK SHARED恢复旧的 case-insensitive 排序规则省略COLLATE即回落到默认排序规则这在语义上重新引入漏洞生产环境回滚需极度谨慎。迁移如何被调度执行migrate 命令与 goose所有 MySQL/Postgres/SQLite 迁移脚本通过go:embed嵌入 OpenFGA 二进制见 assets.goMySQLMigrationDir migrations/mysql。迁移执行器基于 goose v3核心入口为pkg/storage/migrate.RunMigrations见 pkg/storage/migrate/migrate.go它负责解析 DSN、按引擎选择迁移目录、以指数退避策略重试数据库连通性、读取当前 goose 版本号然后执行goose.Up/goose.UpTo/goose.DownTo。命令行入口定义在 cmd/migrate/migrate.gomigrate子命令支持以下参数参数默认值说明--datastore-engine必填数据引擎MySQL 场景传mysql--datastore-uri必填数据库连接 URI--datastore-username/--datastore-password空可选覆盖连接串中的用户名/密码--version0最新版迁移到指定版本号--timeoutDefaultDatastorePingRetryMaxElapsedTime连接数据库的重试总超时--verbosefalse开启详细迁移日志所有参数同时支持环境变量形式如OPENFGA_DATASTORE_ENGINE、OPENFGA_DATASTORE_URI由 cmd/migrate/flags.go 中的 viper 绑定逻辑处理。迁移进程运行到完成即退出不是常驻服务器进程。迁移期间的可用性风险锁与连接池耗尽排序规则变更在 MySQL 层使用LOCK SHARED允许读取、阻止写入受影响表。但官方 runbook 明确警告原文见 collation_migrations.md在非平凡的写入负载下OpenFGA 服务器可能同时失去读写能力。原因链如下被阻塞的写请求会一直持有数据库连接直到超时——即--request-timeout默认3s定义于 pkg/server/config/config.go 的DefaultRequestTimeout一旦这些等待中的写请求占满连接池--datastore-max-open-conns默认30见 cmd/run/run.go 的 flag 注册后续所有请求——包括读请求——都会因无法获取连接而失败。因此官方建议在带活跃写入流量的部署上执行迁移前先在负载均衡器处停止流量或排空写入。此外还有两条硬性约束运行时随表大小增长先在 staging 副本上执行迁移做基准测试据此规划生产维护窗口磁盘空间排序规则变更强制 MySQL 以ALGORITHMCOPY重建每张表服务器会临时同时持有原表与重建副本请确保数据卷上的空闲空间至少约为受影响表自身大小。标准迁移流程Procedure在 staging 副本上预检将近期生产备份恢复到 staging 实例先在那里执行迁移验证迁移可干净应用并得到一个近似运行时长用于预估生产维护窗口安排维护窗口时长需大于 staging 运行时长以容纳生产环境的波动排空流量在负载均衡器处停止流量执行前备份紧接迁移之前对生产库做一份全新备份运行迁移二进制方式./openfga migrate --datastore-engine mysql --datastore-uri $URIDocker 方式docker run --rm openfga/openfga:patched-tag migrate --datastore-engine mysql --datastore-uri $URI迁移运行至完成即退出并非常驻服务器进程。验证迁移结果SELECT version_id FROM goose_db_version ORDER BY id DESC LIMIT 1; -- expect 10 SHOW CREATE TABLE tuple\G -- expect utf8mb4_bin on identifier cols SHOW CREATE TABLE changelog\G SHOW CREATE TABLE authorization_model\G第一句确认 goose 版本号已推进到迁移 008 对应的版本后三句逐表确认标识符列已带上utf8mb4_bin。回滚 OpenFGA 到已打补丁的版本部署新二进制或拉取openfga/openfga:patched-tag并重启容器然后在负载均衡器恢复流量。回滚与风险提示008 的 Down 迁移会恢复大小写不敏感的排序规则重新引入本迁移要修复的漏洞。官方 runbook 明确警告除非完全理解后果否则不要在生产环境回滚。这意味着升级路径应当是单向的——先排空流量、备份、迁移、验证、滚动新版本而不是先升级后回滚。无法排空流量时的替代方案如果部署环境无法接受排空流量造成的写停机可以使用在线 schema 变更工具在不产生写停机的情况下应用同样的ALTERgh-ostGitHub 开源的在线 DDL 工具通过向影子表shadow table复制数据并在完成时切换来实现无锁变更pt-online-schema-changePercona Toolkit 中的在线变更工具原理类似——复制到影子表后原子切换。这两种工具都可以在后台完成与 008 相同的列排序规则转换而无需在负载均衡器处中断写入流量。小结008_collate_identifiers.sql是 OpenFGA 保证身份标识大小写语义正确性的关键修复它把tuple、changelog、authorization_model的标识符列统一转为utf8mb4_bin消除user:Alice与user:alice被混淆存储的隐患。由于 MySQL 排序规则变更不支持LOCK NONE该迁移必然伴随短暂写阻塞运维上必须遵循staging 预检 → 排空流量 → 备份 → 执行 → 验证 → 滚动发布的完整流程若无法接受写停机则借助 gh-ost / pt-online-schema-change 等在线变更工具执行相同的ALTER。回滚会重新引入漏洞生产环境应视为单向升级。延伸阅读仓库内相关资源迁移 SQL 原文008_collate_identifiers.sql、前置迁移 007_collate_object_id.sql初始表结构001_initialize_schema.sql迁移命令实现cmd/migrate/migrate.go、cmd/migrate/flags.go迁移执行内核goose 集成pkg/storage/migrate/migrate.go服务器配置默认值request-timeout、datastore-max-open-connspkg/server/config/config.go赞分享认证鉴权后端【免费下载链接】openfgaA high-performance and flexible authorization/permission engine built for developers and inspired by Google Zanzibar.项目地址https://gitcode.com/gh_mirrors/op/openfga点击查看免费下载相关推荐如何完美处理MySQL字符集Node.js客户端完整支持指南如何完美处理MySQL字符集Node.js客户端完整支持指南 GitHub 加速计划 / my / mysql 是一个纯 Node.js JavaScript后端数据库ConvNeXt V2图像分类入门PyTorch-NPU版5分钟快速开始指南ConvNeXt V2图像分类入门PyTorch NPU版5分钟快速开始指南 想要快速上手ConvNeXt V2图像分类模型吗 这篇终极指南将带你5分钟OHIF 3.13 到 3.14 迁移指南Display Set 日期/时间排序规则详解OHIF 3.13 到 3.14 迁移指南Display Set 日期/时间排序规则详解 Display Set显示集的排序在 OHIF 中决定了系列列表医疗健康前端音视频上一篇IronClaw Google Sheets 扩展 format_cells 能力详解单元格格式化工具的输入契约与底层实现下一篇cytoscape.js 渲染事件监听与解绑onRender / offRender 完整使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考