https://engine.speedle.io/zh/categories/docs/ Recent content in Docs on Speedle Hugo -- gohugo.io zh-cn Fri, 18 Jan 2019 21:19:44 +0800 https://engine.speedle.io/zh/docs/api/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/api/ Java、Python、Go、.NET、Rust 和 Node.js/TypeScript 的客户端库见 SDK。 REST API 这些接口说明面向你配置的 PMS、ADS 或断言服务端点。speedle.io 提供文档与浏览器 Playground，不托管 PMS/ADS 后端。发送 JSON 时必须设置 Content-Type: application/json，并配置 TLS/mTLS 与调用方访问控制。 策略管理 API 授权决策 API 令牌断言 webhook 策略和角色策略的 ID 是字符串，PMS 返回扁平对象；授权权限字段为复数 permissions。REST 决策请求使用带类型的属性数组，诊断响应及断言 webhook 的属性则为对象。 gRPC API PMS proto：pb.PolicyManager ADS proto：pb.Evaluator 当前 proto 必须与生成客户端配套使用。PMS 的服务名为 pb.PolicyManager，ADS 为 pb.Evaluator。这两份历史协议重用了消息名，应分别生成和加载，不要合并进同一 descriptor set。默认不启用 gRPC；需通过 --grpc-endpoint 显式开启，其 TLS 配置与 REST 相同。 历史 gRPC 的 ContextRequest.attributes 是字符串 map，不是 REST 的带类型属性数组，也不提供同样的数值、布尔、日期类型。条件需要这些类型时，应使用 REST 或嵌入式 Go，除非你的 gRPC 适配层明确实现了相应转换。 https://engine.speedle.io/zh/docs/usecases/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/usecases/ 嵌入到 GO 语言编写的应用程序 张先生是一个程序员，他用 GO 语言开发了一套应用系统，现在他希望在这套系统中增加权限控制功能。他可以在程序中直接调用 Speedle 的 GO API 轻松完成任务。 利用 Speedle 管理应用系统的权限 H 公司正在开发一套远程医疗系统。健康数据属于个人隐私，根据合规的需要，H 公司必须提供严格的权限控制，确保每位用户只能接触到自己的数据。该系统还需定期接受第三方机构的审计。H 公司使用 Speedle 来达成一下目标： 构建 RBAC/ABAC 兼容的授权模型 自然语言定义的授权策略，方便审计部门分析审计 详尽的审计数据，可以跟踪用户每一次访问 利用 Speedle 集中管理组织内所有信息系统 陈先生是某大型跨国公司的信息安全负责人。在过去的十年里该公司飞速发展，并购了数十家中小型公司。这给陈先生和他的团队出了个难题，被并购的公司都有自己的信息系统，实现这些信息系统的技术各不相同。有基于 JavaEE 的，有基于 NodeJS 的，有 Ruby on Rails，还有基于 CORBA 的遗留系统。这些系统的权限管理机制也不一致，有的是硬编码的权限管理模块，有的基于 JaaS，有的基于 OASIS XACML，有些策略模型是 RBAC，有些是 ABAC，有些是普通的 ACL，甚至有些是原始的黑名单白名单。陈先生和他的团队为了管理这些系统不得不学习数十种权限模型和语言，每次修改授权策略需要在数十个系统上做不同的操作。非常繁琐也容易出现错误。 如何解决这个问题？Speedle 能帮上忙。 Speedle 的授权策略语言足够灵活，可以完美支持 ABAC，RBAC，ACL 等各种流行的模型。 Speedle 提供 REST，gRPC 和 GO API，很容易和各种系统集成。 Speedle 可以支持百万量级的授权策略，足够支持一个企业的所有业务需求。 Speedle 运行速度很快，可以在数毫秒内处理一个授权请求。不会拖慢现有系统。 一个 Speedle 实例每秒钟可以处理 30,000 - 40,000 次并发授权请求。如果这还不够，再启动一个实例，Speedle 有几乎无限的可扩展性。 基于以上特性，陈先生可以启动一组 Speedle 服务，把各个系统的权限控制模块指向 Speedle 服务。这样就可以用统一个授权模型和语言来管理这些系统了。 https://engine.speedle.io/zh/docs/pms/policy-mgmt/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/pms/policy-mgmt/ 什么是 Speedle 策略？ 策略管理服务（PMS）管理服务、授权策略、角色策略与自定义函数，由已注册的存储后端持久化这些对象。 服务与授权策略 服务限定策略的作用范围。授权策略允许或拒绝主体对资源执行操作，并可附带条件。除全局角色策略外，一个服务的策略不会自动在另一个服务中生效。 grant group Administrators list,watch,get expr:^c1/default/core/pods/.*$ 此正则只匹配 c1/default/core/pods/ 下的资源，不匹配 c1/default/core/podssecret 或带额外前缀的路径。expr: 使用正则表达式，不是 shell 通配符：任意字符使用 .*，需要匹配完整标识符时加 ^、$。 角色策略 grant user alan manager on res1 grant role manager update res1 第一行把指定资源上的角色分配给 Alan，第二行才为该角色授予操作权限。仅分配角色不会自动产生权限。适用的显式拒绝优先于允许。 主体与条件 主体可以是用户、组、实体或角色。实体表示服务等非人身份，集成代码必须从可信来源获取这些身份。 AND 主体组要求组内所有身份均匹配，多组之间为 OR。以下例子要求两个角色都有效： grant (role designer, role dba) update db_design_doc 资源是被保护的对象，操作是应用定义的动作。条件是由可信属性、常量、运算符与受支持函数构成的布尔表达式。 语法见 SPDL，完整决策示例见 RBAC 与 ABAC。 运行示例前 先按快速入门编译仓库根目录下的 ./bin/spctl、./bin/speedle-pms 和 ./bin/speedle-ads，需要 Go 1.26.10 或 Go 1.27.3（也可使用同一大版本的更新补丁版本）、Bash、curl 和 Python 3。下面各终端都从仓库根目录运行。为本页使用一个新的策略文件；仅在两个服务都停止后重建该文件。 初始化空策略文件： printf '{}\n' > docs-policies. https://engine.speedle.io/zh/docs/pms/global-policy/ Fri, 18 Jan 2019 21:19:44 +0800 https://engine.speedle.io/zh/docs/pms/global-policy/ 什么时候使用全局角色？ 普通角色限定在某个服务中。当多个服务需要共享角色分配时，可以在特殊的 global 服务中定义角色策略，再在各服务自己的授权策略中引用该角色。 当前仅支持全局角色策略。全局角色分配本身并不授予任意操作，各普通服务仍需定义自己的权限；全局授权策略尚不支持。 运行示例前 先按快速入门编译仓库根目录下的 ./bin/spctl、./bin/speedle-pms 和 ./bin/speedle-ads，需要 Go 1.26.10 或 Go 1.27.3（也可使用同一大版本的更新补丁版本）、Bash、curl 和 Python 3。下面各终端都从仓库根目录运行。为本页使用一个新的策略文件；仅在两个服务都停止后重建该文件。 初始化空策略文件： printf '{}\n' > docs-policies.json 终端一启动 PMS，并保持运行： ./bin/speedle-pms --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6733 --grpc-endpoint 127.0.0.1:0 --insecure=true 终端二启动 ADS，并保持运行： ./bin/speedle-ads --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6734 --grpc-endpoint 127.0.0.1:0 --insecure=true 在第三个终端运行后续命令。PMS/ADS 共享同一个文件，策略更新通过 watch 异步到达 ADS；先查询确认已更新，再依赖新策略做决策。--insecure=true 仅用于回环地址上的本地示例，生产连接见安全配置。示例显式指定 PMS 地址，不修改 ~/.spctlconfig。完成后在两个服务终端按 Ctrl-C。 创建全局角色与本地权限 ./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ create service global ./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ create rolepolicy -c "grant user Emma AdminRole" --service-name global . https://engine.speedle.io/zh/docs/overview/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/overview/ Speedle 是一个开源的授权引擎（authorization engine）。应用向它提出“这个用户能否对这个资源执行这个操作”这样的问题，Speedle 根据集中管理的策略回答允许或拒绝。本页把常见的授权术语和 Speedle 中实现它们的组件对应起来，并链接到相应的文档。 下面的示例使用名为 library 的服务。每条策略都通过策略管理服务的 REST API 创建，每个决策都由授权决策服务的 REST API 返回。reason 代码的含义见授权查询。 授权引擎（Authorization engine） 授权引擎根据策略评估访问请求并返回决策，使授权逻辑独立于应用代码。Speedle 由策略管理服务（PMS）、策略存储和授权决策服务（ADS）组成。ADS 可以作为独立服务运行，也可以嵌入 Go 应用。 授权与访问控制（Authorization and access control） 认证（authentication）确认调用者是谁；授权（authorization）决定调用者能做什么；访问控制（access control）则是执行这些决策。Speedle 只负责授权：它接收已经认证过的主体，返回决策，由调用它的应用或网关执行。参见授权查询。 细粒度访问控制（Fine-grained access control，FGA） 细粒度访问控制按用户、资源和操作逐一决定访问权限，还可以结合请求上下文，而不是对整个应用一次性放行。Speedle 的策略写明主体、操作和资源，并可以附加条件；角色策略可以只在某一个资源上授予角色。参见 SPDL。 PAP：策略管理点（Policy Administration Point） PAP 是创建和管理策略的地方。在 Speedle 中，PAP 就是 PMS，可以通过 REST API、gRPC API 或命令行工具 spctl 使用。参见策略管理。 PDP：策略决策点（Policy Decision Point） PDP 根据策略评估请求并返回决策。在 Speedle 中，PDP 是 ADS；Speedle 嵌入 Go 进程运行时，则是嵌入式求值器。一个决策请求如下： curl --header 'Content-Type: application/json' --data '{"subject":{"principals":[{"type":"user","name":"alice"}]},"serviceName":"library","resource":"book","action":"update"}' http://127. https://engine.speedle.io/zh/docs/pms/diagnosis/ Fri, 18 Jan 2019 15:46:59 +0800 https://engine.speedle.io/zh/docs/pms/diagnosis/ 授权诊断提供什么？ Diagnose 用于解释一次授权评估：决策、原因、有效角色、属性及参与评估的策略。其请求上下文与 IsAllowed 相同；REST 路径为 /authz-check/v1/diagnose，Go/gRPC 方法均名为 Diagnose。 诊断会暴露策略定义和请求上下文，必须通过API 安全配置限制为可信运维人员访问，不能作为公开调试端点。 运行示例前 先按快速入门编译仓库根目录下的 ./bin/spctl、./bin/speedle-pms 和 ./bin/speedle-ads，需要 Go 1.26.10 或 Go 1.27.3（也可使用同一大版本的更新补丁版本）、Bash、curl 和 Python 3。下面各终端都从仓库根目录运行。为本页使用一个新的策略文件；仅在两个服务都停止后重建该文件。 初始化空策略文件： printf '{}\n' > docs-policies.json 终端一启动 PMS，并保持运行： ./bin/speedle-pms --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6733 --grpc-endpoint 127.0.0.1:0 --insecure=true 终端二启动 ADS，并保持运行： ./bin/speedle-ads --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6734 --grpc-endpoint 127.0.0.1:0 --insecure=true 在第三个终端运行后续命令。PMS/ADS 共享同一个文件，策略更新通过 watch 异步到达 ADS；先查询确认已更新，再依赖新策略做决策。--insecure=true 仅用于回环地址上的本地示例，生产连接见安全配置。示例显式指定 PMS 地址，不修改 ~/.spctlconfig。完成后在两个服务终端按 Ctrl-C。 创建示例策略 测试文件允许 user1 对 ^/api/v1/example/.*$ 下的资源执行 get，但显式拒绝 /api/v1/example/res1。 https://engine.speedle.io/zh/docs/sdks/go/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/sdks/go/ Go SDK 支持最新的两个 Go 版本，只使用标准库。模块：github.com/teramoby/speedle-sdk/go v0.1.0，包名 speedle。参考文档：speedle-sdk/go。 示例检查的策略见 SDK 概览。 添加依赖 在新模块中执行： go mod init example.com/speedle-example go get github.com/teramoby/speedle-sdk/go@v0.1.0 调用本地 Speedle 按 SDK 概览中的说明启动 Speedle 并创建示例策略。将以下程序保存为 main.go： package main import ( "context" "fmt" "os" speedle "github.com/teramoby/speedle-sdk/go" ) func main() { client, err := speedle.NewClient(speedle.Config{ Backend: speedle.BackendSpeedlePlus, Endpoint: "http://localhost:6734", Auth: speedle.NoAuth(), ServiceName: "docs", }) if err != nil { fmt.Fprintln(os.Stderr, "Speedle error:", err) os.Exit(1) } defer client.Close() ctx := context.Background() allowed, err := client. https://engine.speedle.io/zh/docs/sdks/java/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/sdks/java/ Java SDK 需要 Java 17 或更高版本，没有运行时依赖。软件包：Maven Central 上的 io.speedle:speedle-sdk 0.1.0。参考文档：speedle-sdk/java。 示例检查的策略见 SDK 概览。 添加依赖 Maven，完整的 pom.xml： <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>speedle-example</artifactId> <version>1.0</version> <properties> <maven.compiler.release>17</maven.compiler.release> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <dependencies> <dependency> <groupId>io.speedle</groupId> <artifactId>speedle-sdk</artifactId> <version>0.1.0</version> </dependency> </dependencies> </project> Gradle，完整的 build.gradle.kts（另需一个设置 rootProject.name 的 settings.gradle.kts）： plugins { application } repositories { mavenCentral() } dependencies { implementation("io.speedle:speedle-sdk:0.1.0") } application { mainClass = "Main" } 调用本地 Speedle 按 SDK 概览中的说明启动 Speedle 并创建示例策略。将以下程序保存为 src/main/java/Main. https://engine.speedle.io/zh/docs/store/mongodb/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/store/mongodb/ 本指南使用 MongoDB 7.0.16 单节点副本集和 Docker 持久化卷。PMS 写入策略，ADS 通过 change stream 跟踪同一个数据库。本地示例只监听回环地址且不开启身份认证，用于开发环境；生产环境的身份认证、TLS 与副本集配置见后文。 MongoDB 必须以副本集或分片集群方式运行：ADS 使用 change stream 监听数据库，整体替换策略存储时使用事务，独立运行的 mongod 两者都不支持。开发环境使用单节点副本集即可。 1. 编译 Speedle 准备 Bash、Git、curl、已启动的 Docker，以及 Go 1.26.10 或 Go 1.27.3，然后从源码编译： git clone --depth 1 https://github.com/teramoby/speedle-plus.git cd speedle-plus mkdir -p bin go build -o ./bin/ ./cmd/spctl ./cmd/speedle-pms ./cmd/speedle-ads 后续命令均在这个代码目录执行。确认 27017、6733、6734 端口可用；修改端口时要同步修改命令和配置。 2. 启动 MongoDB 命名卷保存 MongoDB 数据。--replSet 让 mongod 作为副本集 speedle-rs 的成员启动；只把数据库端口发布到宿主机的回环地址。 docker run --name speedle-mongodb --detach \ --publish 127. https://engine.speedle.io/zh/docs/store/mysql/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/store/mysql/ 本指南使用 MySQL 8.4 LTS，分别启动 PMS 和 ADS：PMS 写入策略，ADS 使用独立的只读账号读取同一个数据库。本地演示使用 Docker，HTTP 服务只监听本机回环地址。远程部署可使用已有的 MySQL，并参考安全配置。 1. 编译包含 MySQL 后端的 Speedle 准备 Git、Bash、curl、已启动的 Docker，以及支持的 Go 工具链（Go 1.26.10 或 Go 1.27.3）。从当前源码编译，确保两个服务都包含 mysql 后端；已安装的旧版本可能没有该后端。 git clone --depth 1 https://github.com/teramoby/speedle-plus.git cd speedle-plus mkdir -p bin go build -o ./bin/ ./cmd/spctl ./cmd/speedle-pms ./cmd/speedle-ads 后续命令都在这个 speedle-plus 目录执行。确认 3306、6733、6734 端口未被占用；若修改端口，需同步修改下文的命令和配置。 2. 启动 MySQL 8.4 下列固定密码仅为本地演示凭据。部署时请使用自己的凭据与密钥交付方式。命名卷会在容器停止或重建后保留数据库。 docker run --name speedle-mysql --detach \ --publish 127.0.0.1:3306:3306 \ --volume speedle-mysql-data:/var/lib/mysql \ --env MYSQL_ROOT_PASSWORD=SpeedleDemoRoot84 \ mysql:8. https://engine.speedle.io/zh/docs/sdks/node/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/sdks/node/ Node.js SDK 需要 Node.js 22 或更高版本，同时提供 ESM 和 CommonJS 构建及 TypeScript 类型，没有运行时依赖。软件包：npm 上的 @speedle/sdk 0.1.0，发布后可用。参考文档：speedle-sdk/node。 示例检查的策略见 SDK 概览。 添加依赖 新建 ES 模块包并安装（发布后可用）： mkdir speedle-example cd speedle-example npm init -y npm pkg set type=module npm install @speedle/sdk@0.1.0 调用本地 Speedle 按 SDK 概览中的说明启动 Speedle 并创建示例策略。将以下程序保存为 main.ts： import { Auth, Reason, SpeedleClient, SpeedleError } from "@speedle/sdk"; try { const speedle = new SpeedleClient({ backend: "speedle-plus", endpoint: "http://localhost:6734", auth: Auth.none(), serviceName: "docs", }); try { const allowed = await speedle. https://engine.speedle.io/zh/docs/sdks/python/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/sdks/python/ Python SDK 需要 Python 3.10 或更高版本，唯一的运行时依赖是 httpx。它提供同步的 Client 和 asyncio 的 AsyncClient，两者参数相同。软件包：PyPI 上的 speedle 0.1.0。参考文档：speedle-sdk/python。 示例检查的策略见 SDK 概览。 添加依赖 使用 pip，在虚拟环境中安装： python3 -m venv .venv . .venv/bin/activate pip install speedle==0.1.0 或者使用 uv，在 uv 项目中添加： uv add speedle==0.1.0 调用本地 Speedle 按 SDK 概览中的说明启动 Speedle 并创建示例策略。将以下程序保存为 main.py： import sys from speedle import Auth, Client, SpeedleError try: with Client( backend="speedle-plus", endpoint="http://localhost:6734", auth=Auth.none(), service_name="docs", ) as speedle: allowed = speedle.is_allowed("alice", "get", "/docs/public") print(f"alice get /docs/public: allowed={allowed}") decision = speedle. https://engine.speedle.io/zh/docs/sdks/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/sdks/ Speedle SDK 是决策 API POST /authz-check/v1/is-allowed 的客户端库，既可用于自托管的 Speedle ADS，也可用于 Speedle Cloud。每个语言页面说明如何添加软件包，并分别给出两种场景下经过实测的完整程序。源代码和完整参考见 teramoby/speedle-sdk。 软件包 所有软件包的版本均为 0.1.0，安装命令见各语言页面。 Java：Maven Central io.speedle:speedle-sdk，已发布。 Python：PyPI speedle，已发布。 Go：Go 模块 github.com/teramoby/speedle-sdk/go，已发布。 C#/.NET：NuGet Speedle.Sdk，已发布。 Rust：crates.io speedle，已发布。 Node.js / TypeScript：npm @speedle/sdk，尚未发布。 功能 功能 状态 isAllowed：返回授权结果 六个 SDK 均支持 check：返回授权结果及原因，例如没有适用的策略 六个 SDK 均支持 自托管 Speedle ADS 六个 SDK 均支持 Speedle Cloud 即将上线 方法名遵循各语言的命名习惯：Python 和 Rust 中为 is_allowed 与 check，Go 中为 IsAllowed 与 Check，. https://engine.speedle.io/zh/docs/spdl/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/spdl/ 基本的策略定义语言 保留关键字 grant、deny、user、group、entity、role、from、on、if、in 在各自语法位置有特定含义，策略语句的关键字大小写不敏感；条件成员运算使用 in 或 IN，函数名区分大小写。主体、操作和资源名称也区分大小写。当前解析器在部分名称位置可接受类似关键字的名称，不能把“所有位置都禁止关键字”当作验证规则。为便于审查与客户端互通，建议避免这类名称。 命名规范 推荐使用简明、稳定的标识符；名称包含空格或分隔符时使用解析器支持的单引号或双引号形式，并测试实际输入。不应把历史 Java 正则字符类当作当前 Go 解析器的严格校验。资源前缀 expr: 表示 Go 正则表达式，不是 shell 通配符。条件的属性与函数名称另见下文。 语法 POLICY = EFFECT SUBJECT ACTION RESOURCE [if CONDITION] EFFECT = grant | deny SUBJECT = AND_PRINCIPALS (, AND_PRINCIPALS)* AND_PRINCIPALS = PRINCIPAL | \( PRINCIPAL_LIST \) PRINCIPAL_LIST = PRINCIPAL (, PRINCIPAL)* PRINCIPAL = PRINCIPAL_TYPE PRINCIPAL_NAME [PRINCIPAL_IDD] PRINCIPAL_TYPE = user|group|entity|role PRINCIPAL_IDD = from IDD_IDENTIFIER IDD_IDENTIFIER = NAME ACTION = (ACTION_IDENTIFIER)(, ACTION_IDENTIFIER)* RESOURCE = RESOURCE_IDENTIFIER PRINCIPAL_NAME = NAME ACTION_IDENTIFIER = NAME RESOURCE_IDENTIFIER = NAME ROLE_POLICY = EFFECT SUBJECT ROLE (on RESOURCE)? https://engine.speedle.io/zh/docs/deployment/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/deployment/ 选择部署方式 通过嵌入模式可以在 Go 进程内运行决策引擎；如果应用通过 REST 或 gRPC 调用 Speedle，则运行独立的 PMS 和 ADS。快速入门提供了完整的本地策略管理和授权验证步骤。 使用当前 Go 版本构建 在 Linux 或 macOS 上准备 Go 1.26.10 或 Go 1.27.3（也可使用同一大版本的更新补丁版本）（推荐 Go 1.27.3）、Git 和命令行 shell。使用 Go modules，源码可放在任意可写目录，无需手工配置 GOROOT、GOPATH、dep 或 GOPATH 源码路径。 git clone --depth 1 https://github.com/teramoby/speedle-plus.git cd speedle-plus mkdir -p bin go build -o ./bin/ ./cmd/spctl ./cmd/speedle-pms ./cmd/speedle-ads 生成的可执行文件为 bin/spctl、bin/speedle-pms 和 bin/speedle-ads。从源码根目录运行下面的本地示例，两个服务共享同一策略文件： ./bin/speedle-pms --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6733 --insecure=true 保持 PMS 运行，在同一源码目录的另一个终端启动 ADS： ./bin/speedle-ads --store-type file --filestore-loc . https://engine.speedle.io/zh/docs/pms/ Fri, 18 Jan 2019 21:19:44 +0800 https://engine.speedle.io/zh/docs/pms/ Policy Management Global Policy Policy Discovery Policy Diagnosis https://engine.speedle.io/zh/docs/store/etcd/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/store/etcd/ 本指南使用独立的 etcd v3.6.14 和 Docker 持久化卷。PMS 写入策略，ADS 监听同一个 key prefix。本地单节点示例通过回环地址提供 HTTP 服务；生产环境的 TLS 与集群配置见后文。 1. 编译 Speedle 准备 Bash、Git、curl、已启动的 Docker，以及 Go 1.26.10 或 Go 1.27.3，然后从源码编译： git clone --depth 1 https://github.com/teramoby/speedle-plus.git cd speedle-plus mkdir -p bin go build -o ./bin/ ./cmd/spctl ./cmd/speedle-pms ./cmd/speedle-ads 后续命令均在这个代码目录执行。确认 2379、6733、6734 端口可用；修改端口时要同步修改命令和配置。 2. 启动独立 etcd 服务 命名卷保存 etcd 数据。这里只把客户端端口发布到宿主机，单节点内部通信使用的 peer 端口保留在容器内。 docker run --name speedle-etcd --detach \ --publish 127.0.0.1:2379:2379 \ --volume speedle-etcd-data:/etcd-data \ gcr. https://engine.speedle.io/zh/docs/decisions/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/decisions/ 什么是授权决策？ Speedle 在指定服务内评估主体、操作与资源，由应用执行结果。应区分评估错误、超时与正常的 Deny，并在出错时拒绝访问。REST、gRPC、嵌入式 Go 的数据表示不同，应分别遵循各自的 API 契约。 运行示例前 先按快速入门编译仓库根目录下的 ./bin/spctl、./bin/speedle-pms 和 ./bin/speedle-ads，需要 Go 1.26.10 或 Go 1.27.3（也可使用同一大版本的更新补丁版本）、Bash、curl 和 Python 3。下面各终端都从仓库根目录运行。为本页使用一个新的策略文件；仅在两个服务都停止后重建该文件。 初始化空策略文件： printf '{}\n' > docs-policies.json 终端一启动 PMS，并保持运行： ./bin/speedle-pms --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6733 --grpc-endpoint 127.0.0.1:0 --insecure=true 终端二启动 ADS，并保持运行： ./bin/speedle-ads --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6734 --grpc-endpoint 127.0.0.1:0 --insecure=true 在第三个终端运行后续命令。PMS/ADS 共享同一个文件，策略更新通过 watch 异步到达 ADS；先查询确认已更新，再依赖新策略做决策。--insecure=true 仅用于回环地址上的本地示例，生产连接见安全配置。示例显式指定 PMS 地址，不修改 ~/.spctlconfig。完成后在两个服务终端按 Ctrl-C。 创建可重复的测试策略 测试文件给 Alan 分配 role1、role2；其中 role1 可以下载 /books/HarryPotter。 ./bin/spctl --pms-endpoint http://127. https://engine.speedle.io/zh/docs/pms/discover/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/pms/discover/ 策略发现的作用 发现模式记录请求，成功记录时返回 allowed=true、reason 5，不代表既有策略曾授权该操作。仅在隔离测试环境使用，审核生成的授权，并在结束后恢复正常的 is-allowed 检查。断言或存储错误仍需单独处理，不能把错误当作授权成功。 启动可复现的本地示例 先按快速入门编译二进制。下面各终端均从源码根目录运行，使用新的策略文件，并先停止其他页面示例的服务。 printf '{}\n' > docs-policies.json 终端一： ./bin/speedle-pms --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6733 --insecure=true 终端二： ./bin/speedle-ads --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6734 --insecure=true 保持两个服务运行。在终端三记录一个请求： curl --fail --silent --show-error -H 'Content-Type: application/json' \ -d '{"subject":{"principals":[{"type":"user","name":"alice"}]},"serviceName":"observed","resource":"book","action":"read"}' \ http://127.0.0.1:6734/authz-check/v1/discover 检查记录的请求，再生成待审核的服务定义： ./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ discover request --service-name observed ./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ discover policy --service-name observed > discovered-service.json 审核 discovered-service.json 中的角色、身份域和资源。本例尚不存在名为 observed 的策略服务，因此可以直接导入；已有同名服务时应合并和审核其策略，而不是直接重复创建。 ./bin/spctl --pms-endpoint http://127. https://engine.speedle.io/zh/docs/idd/ Thu, 17 Jan 2019 13:20:07 +0800 https://engine.speedle.io/zh/docs/idd/ 什么是身份域？ 身份域（idd）为主体提供显式命名空间。同名的 user1 可以属于不同的域。域字符串由可信应用或已配置的令牌断言服务提供，本身不代表完成了身份认证。Speedle 不会仅根据域名称推断或验证身份提供方的租户模型。 在策略与请求中表示身份域 grant user user1 from github read book grant user user1 from IDCS.tenant01 read book 在主体名后使用 from <identity-domain>。PMS JSON 策略中的等价编码为 idd=github:user:user1；决策请求中的主体表示为： { "type": "user", "name": "user1", "idd": "github" } 带 from github 的策略只匹配该域；省略 from 则按主体名跨域匹配。多租户应用应明确审查这一选择；域字符串不能用于验证令牌。更多内容见身份与 IAM和令牌断言。 运行示例前 先按快速入门编译仓库根目录下的 ./bin/spctl、./bin/speedle-pms 和 ./bin/speedle-ads，需要 Go 1.26.10 或 Go 1.27.3（也可使用同一大版本的更新补丁版本）、Bash、curl 和 Python 3。下面各终端都从仓库根目录运行。为本页使用一个新的策略文件；仅在两个服务都停止后重建该文件。 初始化空策略文件： printf '{}\n' > docs-policies.json 终端一启动 PMS，并保持运行： ./bin/speedle-pms --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6733 --grpc-endpoint 127. https://engine.speedle.io/zh/docs/sdks/dotnet/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/sdks/dotnet/ .NET SDK 面向 .NET 8 或更高版本，没有依赖。软件包：NuGet 上的 Speedle.Sdk 0.1.0，命名空间 Speedle.Sdk。参考文档：speedle-sdk/dotnet。 示例检查的策略见 SDK 概览。 添加依赖 新建控制台项目并添加软件包： dotnet new console -o SpeedleExample cd SpeedleExample dotnet add package Speedle.Sdk --version 0.1.0 调用本地 Speedle 按 SDK 概览中的说明启动 Speedle 并创建示例策略。将 Program.cs 替换为： using Speedle.Sdk; try { await using var speedle = new SpeedleClient(new SpeedleClientOptions { Backend = Backend.SpeedlePlus, Endpoint = new Uri("http://localhost:6734"), Auth = Auth.None(), ServiceName = "docs", }); bool allowed = await speedle.IsAllowedAsync("alice", "get", "/docs/public"); Console. https://engine.speedle.io/zh/docs/sdks/rust/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/sdks/rust/ Rust SDK 需要 Rust 1.75 或更高版本，基于 tokio 和 reqwest（rustls）实现异步调用；下面使用的阻塞客户端由 blocking 特性提供。crate：crates.io 上的 speedle 0.1.0。参考文档：speedle-sdk/rust。 示例检查的策略见 SDK 概览。 添加依赖 新建包并添加依赖： cargo new speedle-example cd speedle-example cargo add speedle@0.1.0 --features blocking 调用本地 Speedle 按 SDK 概览中的说明启动 Speedle 并创建示例策略。将 src/main.rs 替换为： use speedle::blocking::Client; use speedle::{Auth, Backend}; fn main() { if let Err(e) = run() { eprintln!("Speedle error: {e}"); std::process::exit(1); } } fn run() -> Result<(), speedle::Error> { let speedle = Client::builder(Backend::SpeedlePlus, "http://localhost:6734", Auth::none(), "docs"). https://engine.speedle.io/zh/docs/assertor/ Mon, 21 Jan 2019 09:28:30 +0800 https://engine.speedle.io/zh/docs/assertor/ 令牌断言服务负责什么？ 已配置的断言服务验证令牌，并返回显式主体及其身份域，再由 Speedle 使用这些身份评估策略。生产实现必须验证签名或 introspection 结果、签发者、受众、有效期及身份提供方要求。仅有 webhook 接口并不意味着自动兼容任意 OAuth/OIDC 令牌。 令牌断言 API中的 errCode 为整数，可选的属性是对象，不是带类型的属性数组。asserterWebhookConfig.endpoint 是完整 URL，下面的示例使用 /v1/assert。 启动确定性的本地 mock 此 mock 只识别 githubtoken/github、googletoken/google、gitlabtoken/gitlab 三组输入，分别表示对应域的 user1。令牌与提供方不匹配时失败。它是测试 fixture，不验证真实令牌。 不会记录令牌值。仅绑定回环地址，生产环境必须替换为真实身份集成。 从仓库根目录在单独终端运行： go run ./website/tests/examples/asserter // A deterministic mock for the token-assertion tutorial. Never use for real tokens. package main import ( "encoding/json" "flag" "log" "net/http" "strings" "time" ) type principal struct { Type string `json:"type"` Name string `json:"name"` IDD string `json:"idd"` } type response struct { Principals []principal `json:"principals,omitempty"` ErrCode int `json:"errCode"` ErrMessage string `json:"errMessage,omitempty"` } func assert(w http. https://engine.speedle.io/zh/docs/store/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/store/ 内置存储与扩展接口 独立服务在 pkg/store 下注册 file、etcd、MongoDB、MySQL 实现。可用不代表具有相同的运维保证，部署前应分别审查后端认证、持久化、事务与 watch 行为。下方配置说明属性名称，本地示例不涉及启动 etcd/MongoDB 集群。 完整后端实现 pms.PolicyStoreManager：服务、授权策略、角色策略、函数管理，以及快照读取与 watch/stop。ADS 接受较窄的只读/watch 接口 PolicyStoreManagerADS。实现新后端时应以实际接口为准，不能照搬历史文档中不完整的方法列表。 逐步部署教程：MySQL 配置指南、etcd 配置指南与 MongoDB 配置指南。 存储故障与缓存授权 file、etcd、MySQL、MongoDB 使用相同的 ADS 故障策略。 storeFailureGracePeriod 默认是 "0s"：检测到存储故障后，授权返回 allowed:false 和求值错误。ADS 保持运行并持续重试；连接恢复后，还必须成功 加载完整策略快照，才能恢复授权。启用 watch 时，还必须先重新建立故障的订阅； watch 未恢复时，成功读取数据不会重置故障或宽限期的截止时间。文件被删除时会持续重试，不再退出 ADS。 如果部署方明确接受撤权延迟，可在 ADS JSON 配置的顶层设置有限时长，例如 "storeFailureGracePeriod": "5s"。对应参数为 --store-failure-grace-period=5s，环境变量为 SPDL_STORE_FAILURE_GRACE_PERIOD，继续遵循“显式参数 → 环境变量 → 配置文件 → 默认值”。 重试失败不会延长宽限期。宽限期内按最后一份完整快照授权，因此撤权要等同步恢复 才能生效。缓存部分更新失败和授权计算 panic 不适用宽限期，仍然立即拒绝。 内置存储约每秒执行一次轻量健康检查，单次检查超时为一秒；watch 可能更早报告 故障，正在执行的存储读取也受各自后端超时限制。故障检测和正常策略传播均为异步， 不提供瞬时撤权保证。设置 enableWatch:false 时，请求仍检查存储健康，普通策略 变更需要显式刷新；故障恢复时，即使关闭 watch，也必须加载完整快照。首次加载 失败时没有可用缓存，不适用宽限期。自定义存储可以实现 pms.StoreHealthChecker 并发送 pms.STORE_UNAVAILABLE 事件，接入相同故障策略。 https://engine.speedle.io/zh/docs/security/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/security/ 同时保护两种 API 传输 独立运行的 PMS 与 ADS 都提供 REST 和 gRPC。现在两者共同使用 --insecure、--cert、--key、--client-cert 和 --force-client-cert 配置。证书或信任配置无效时启动失败，安全模式不会降级为明文。 TLS 加密连接并认证服务端。若要强制认证客户端，必须通过 --client-cert 提供客户端 CA，同时设置 --force-client-cert=true。只提供 CA 时，仅在客户端主动发送证书的情况下验证该证书。TLS 本身不决定谁有管理员权限，也不提供 Bearer token 校验。管理、诊断、发现接口需要认证网关或等价的访问控制。--enable-authz 参数不提供内置的端点授权策略。 监听地址与兼容性 服务 默认 REST 地址 默认 gRPC 地址 PMS 0.0.0.0:6733 默认关闭；需设置 --grpc-endpoint ADS 0.0.0.0:6734 默认关闭；需设置 --grpc-endpoint REST 与 gRPC 的地址分别配置。仅设置 --endpoint 不会启用 gRPC；请显式使用 --grpc-endpoint 127.0.0.1:50001（PMS）或 127.0.0.1:50002（ADS）。127.0.0.1:0 为隔离测试选择临时端口。需要 IPv6 时显式指定 IPv6 监听地址。 https://engine.speedle.io/zh/docs/logging/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/logging/ 概述 Speedle 使用了下面两个开源项目来处理日志, 1. https://github.com/sirupsen/logrus 2. https://github.com/natefinch/lumberjack Logrus 是一个针对 go 语言的结构化的日志处理器，它与 go 语言标准的 logger 库完全 API 兼容。因为 logrus 不支持对日志循环滚动处理（rotation），所以我们引入了另外一个开源项目 lumberjack。Logrus 与 lumberjack 之间通过 io.Writer 接口交互，如下图所示, 日志配置 可以通过两种方式对 Speedle 的日志模块进行配置，即命令行参数或者配置文件。 通过命令行参数配置日志 所有的命令行参数如下所示。level、formatter、reportcaller 配置 logrus，文件与滚动相关设置配置 lumberjack。 --log-level string --log-formatter string --log-reportcaller bool --log-filename string --log-maxsize int --log-maxbackups int --log-maxage int --log-localtime bool --log-compress bool 上面每一个参数的详细信息包含在下面的表格中。所有的参数都收可选的。 如果所有参数都没有配置，那么日志消息默认会输出到标准错误输出（stderr），而且默认的日志级别是 info。 配置项 描述 默认值 –log-level 日志级别, 有效的日志级别包括：panic、fatal、error、warn、info、debug info –log-formatter 日志格式, 有效的日志格式包括：text、json text –log-reportcaller 用于控制是否将调用信息 (文件名, 行数和函数名)包含在日志消息中 false –log-filename 日志文件名 没有默认值。 如果没有配置，那么日志消息默认会输出到标准错误输出（stderr） –log-maxsize 每个日志文件的最大尺寸。 注意该参数只有在”–log-filename”已经配置的情况下才有效 100M –log-maxbackups 历史日志文件保留的最大数量。 注意该参数只有在”–log-filename”已经配置的情况下才有效 0, 保留所有历史日志文件（注意历史日志文件可能由于达到了 maxAge 设定的时间限制而被删除） –log-maxage 历史日志文件保留的最多天数。注意该参数只有在”–log-filename”已经配置的情况下才有效 0, 不删除任何历史日志文件（注意历史日志文件可能由于达到了 maxbackups 的限制而被删除） –log-localtime 用于控制在生成滚动日志文件时是否使用本地时间。注意该参数只有在”–log-filename”已经配置的情况下才有效 false, 使用 UTC 时间 –log-compress 用于控制在生成滚动日志文件时是否需要压缩。注意该参数只有在”–log-filename”已经配置的情况下才有效 false, 不压缩 下面是两个日志消息的示例，第一个使用 text 格式输出，第二个则是使用 json 格式输出， https://engine.speedle.io/zh/docs/versions/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/versions/ Speedle 发布版本 已发布版本及发行说明以 GitHub Releases 为准。v1.6.0 是当前嵌入式 Go 示例固定使用的版本。为确保模块依赖可复现，应指定已发布版本；安装方式见嵌入模式。 Oracle Speedle 历史版本 0.1.0 是原项目首次开源的版本，包含策略管理、授权决策、命令行工具及集成示例。历史文档中的 0.2.0 规划不是当前 Speedle 的发布路线图。 https://engine.speedle.io/zh/docs/custom-function/ Mon, 21 Jan 2019 10:43:02 +0800 https://engine.speedle.io/zh/docs/custom-function/ 为什么使用自定义函数？ 当内置运算或函数不能表达规则时，SPDL 条件可以调用已配置的函数。Speedle 向其 REST 端点发送 POST {"params":[...]}，预期返回 {"result":...} 或 {"error":"..."}。参数顺序、类型和返回类型必须与条件一致。函数失败是评估错误，应用应拒绝访问。 启动本地示例 示例接受 100 至 50000 之间的数值。参数类型错误或列表为空时返回 HTTP 错误。只有回环 IP 可以使用明文，其他监听地址必须提供 TLS。 在单独终端运行： go run ./website/tests/examples/custom-function package main import ( "encoding/json" "flag" "log" "net" "net/http" "time" ) type request struct { Params []interface{} `json:"params"` } type response struct { Result interface{} `json:"result,omitempty"` Error string `json:"error,omitempty"` } func isValid(w http.ResponseWriter, r *http.Request) { send := func(status int, value response) { w. https://engine.speedle.io/zh/docs/api/decision_api/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/api/decision_api/ 已配置 ADS 的接口参考。请求属性是带类型的数组，诊断响应属性是对象。 请配置安全连接与端点访问控制。这是接口契约，speedle.io 不托管授权后端。 (function() { var url = "\/swagger\/policy-check.zh.yaml"; const ui = SwaggerUIBundle({ url: url, dom_id: '#swagger-ui', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], validatorUrl: null, layout: "BaseLayout" }) window.ui = ui })(); https://engine.speedle.io/zh/docs/api/management_api/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/api/management_api/ 已配置 PMS 的接口参考。请求与响应使用 JSON，策略 ID 为字符串，响应为扁平对象。 请配置安全连接与端点访问控制。这是接口契约，speedle.io 不托管授权后端。 (function() { var url = "\/swagger\/policy-manage.zh.yaml"; const ui = SwaggerUIBundle({ url: url, dom_id: '#swagger-ui', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], validatorUrl: null, layout: "BaseLayout" }) window.ui = ui })(); https://engine.speedle.io/zh/docs/ Thu, 17 Jan 2019 13:20:07 +0800 https://engine.speedle.io/zh/docs/ https://engine.speedle.io/zh/docs/api/asserter_api/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/zh/docs/api/asserter_api/ 令牌断言 webhook 参考。errCode 为整数，attributes 为对象。实际端点由 ADS 断言配置指定。 请配置安全连接与端点访问控制。这是接口契约，speedle.io 不托管授权后端。 (function() { var url = "\/swagger\/asserter.zh.yaml"; const ui = SwaggerUIBundle({ url: url, dom_id: '#swagger-ui', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], validatorUrl: null, layout: "BaseLayout" }) window.ui = ui })(); https://engine.speedle.io/zh/integrations/ Mon, 10 Apr 2017 16:41:54 +0100 https://engine.speedle.io/zh/integrations/