ORY Keto 项目升级指南：版本迁移与重大变更解析

ORY Keto 项目升级指南：版本迁移与重大变更解析

keto Open Source (Go) implementation of "Zanzibar: Google's Consistent, Global Authorization System". Ships gRPC, REST APIs, newSQL, and an easy and granular permission language. Supports ACL, RBAC, and other access models. 项目地址: https://gitcode.com/gh_mirrors/ke/keto

前言

ORY Keto 作为一款开源的访问控制服务，在其发展过程中经历了多次架构重构和功能增强。本文将从技术专家的角度，系统梳理 ORY Keto 各主要版本的升级注意事项，帮助开发者顺利完成版本迁移。

0.4.0 版本升级要点

SDK 架构重构

0.4.0 版本对 SDK 体系进行了彻底重构，主要变化包括：

1. 多语言 SDK 支持：官方现在为以下语言提供了独立的 SDK 包：

   • Python (通过 PyPI 分发)
   • PHP (通过 Packagist 分发)
   • Go (专用客户端库)
   • NodeJS (包含 TypeScript 支持)
   • Java (通过 Maven 中央仓库分发)
   • Ruby (通过 RubyGems 分发)

2. 旧版 SDK 移除：原仓库中 /sdk/ 目录下的所有 SDK 实现已被移除，开发者必须迁移到新版官方 SDK。

3. 兼容性变化：

   • Go SDK 中部分结构体和字段被重命名，但核心逻辑保持不变
   • 所有 SDK 改用 openapi-generator 生成，提供了更好的代码质量和 TypeScript 支持

升级建议：对于 Go 项目，预计需要 30-60 分钟完成字段重命名工作；其他语言项目由于生成器变更，可能需要更仔细的测试验证。

0.3.0 版本升级要点

配置系统改进

1. 配置文件支持：新增 YAML 格式的配置文件支持，同时保留了环境变量配置方式
2. 环境变量变更：部分环境变量名称已更新，旧变量仍可使用但会显示警告

API 行为变更

• /engines/acp/ory/{flavor}/allowed 端点现在对未授权的请求返回 403 状态码（原为其他错误码）

SDK 生成器切换

Go SDK 生成器从 swagger-codegen 迁移到 go-swagger，生成代码结构有所变化。

0.2.0 版本重大重构

架构变更概述

这是 ORY Keto 的一次重大架构升级，主要目标包括：

1. 增强访问控制机制的可扩展性
2. 提升系统稳定性和响应能力
3. 支持多种访问控制模型（未来将支持 RBAC、ACL、AWS IAM 策略等）

废弃的功能

1. 旧版 Authorizers 机制
2. 原有的存储实现

核心变更

1. 策略引擎替换：从 ORY Ladon 迁移到 Open Policy Agent (OPA)，使用 Rego 语言实现策略逻辑
2. 旧版概念废弃：被新的 API 设计取代
3. CLI 命令重构：除 serve、version 和 migrate sql 外，其他命令均有变更

API 迁移指南

端点重命名

• 策略管理端点从 /policies 迁移到 /engines/acp/ory/<matching-strategy>/policies
• 角色管理端点从 /roles 迁移到 /engines/acp/ory/<matching-strategy>/roles

重要行为变更

1. POST 合并为 PUT：原 POST 创建操作现在统一通过 PUT 实现（支持 upsert 语义）
2. 旧版 API 废弃：包括令牌验证等端点已被移除

新增端点

• /version：获取服务版本
• /health/ready：服务就绪检查
• /health/alive：服务存活检查

数据迁移警告

特别注意：SQL 数据库模式已完全重构，无法通过简单的 migrate sql 命令完成自动迁移。需要制定专门的数据迁移方案。

0.0.1 版本注意事项

CORS 默认禁用

新增 CORS_ENABLED 环境变量控制跨域支持，默认值为禁用（"false"）。如需启用需显式配置为 "true"。

升级最佳实践

1. 充分测试：在预发布环境中全面验证新版本功能
2. 逐步迁移：考虑采用蓝绿部署策略降低风险
3. 监控观察：升级后密切监控系统指标和日志
4. 备份优先：执行任何升级操作前确保完整数据备份

对于复杂的迁移场景，建议联系 ORY 官方支持获取针对性指导。每次升级前，请务必完整阅读对应版本的变更说明和已知问题列表。

keto Open Source (Go) implementation of "Zanzibar: Google's Consistent, Global Authorization System". Ships gRPC, REST APIs, newSQL, and an easy and granular permission language. Supports ACL, RBAC, and other access models. 项目地址: https://gitcode.com/gh_mirrors/ke/keto