speed on speed documentation

快速开始

Mon, 01 Jan 0001 00:00:00 +0000

快速开始

目前还没有任何发布物。 speed 的第一个正式 tag 要到里程碑 M4 才会出现（见实现状态）；在那之前不存在 go get github.com/vislake/speed/...，也不存在从任何 registry npm install @speed/...。下面这条路径——本地 checkout 加 go run——就是当下试用 speed 真实、现行的方式，不是对某个已发布流程的简化版本。

1. 克隆仓库

git clone https://github.com/vislake/speed
cd speed

仓库根目录是一个 Go workspace（go.work），不是一个 Go module——运行 Go 命令时的注意事项见下文。

2. 用 `saasctl new` 生成一个起始项目

saasctl 是 speed 面向业务方的 CLI：它从一棵内嵌的模板树中生成一个可直接启动的起始项目，而不是临时拼出一个骨架。可以直接在 checkout 里用 go run 运行：

go run ./go/saasctl new ../my-app --speed-root .

目标目录不能已经存在（或者必须是空目录）。生成项目的 go.mod 里带有指向 --speed-root 的 replace 指令——这是每一个生成项目在第一个正式发布之前都会带有的过渡态形态，因为目前还没有任何按版本号可依赖的 registry 条目。

模块索引

Mon, 01 Jan 0001 00:00:00 +0000

模块索引

speed 是一系列独立发布的 Go module 与 npm 包，不是一个应用程序。业务方项目按需接入其中的一部分。下表每一行都链接到该模块自己在仓库里的 AGENTS.md 或 README.md——本站不保留模块文档的副本，所以链接始终指向最新的那一份。

这个页面列出的是"存在什么"，不是"什么已经被同等程度证明可靠"。凡事自己核实仍然是规则：仓库根 CLAUDE.md 的 Repository Status 一节（见面向 AI Agent）才是"哪些模块今天真的能在 CI 里通过 go build / go vet / golangci-lint / go test -race“的唯一权威来源——按 fast-check.yml 自己的 go-modules 矩阵，全部 21 个都在内， go/admin 也不例外。

Go module（`go/`，共 21 个）

go.work 里每一条 use 对应下表一行。依赖关系严格自底向上——粗略的顺序见面向 AI Agent。

模块	是什么	文档
`pkgcore`	依赖的最底层：`Module`/`Registry`/`Kernel` 装配契约、租户上下文原语、`apperr`、seam registry 机制（`EventBus`/`KVStore`/`Mailer`/`ObjectStore`）、部署模式 preset，以及合并后的 i18n 消息目录。	AGENTS.md
`dbkit`	双方言（SQLite/PostgreSQL）的 `*gorm.DB` 封装：强制使用的泛型 `Repository[T]`、带版本的迁移、字段级加密、支持精确匹配查询的盲索引、软删除/硬删除，以及审计捕获写插件。	AGENTS.md
`tenancy`	租户解析中间件、经过审计的 `WithSystemContext` 逃生通道，以及所有其他模块的 repository 都必须跑的 `AssertIsolated` / `AssertNotTenantScoped` 测试套件。	AGENTS.md
`observability`	两种部署模式下的 OpenTelemetry 初始化、默认开启 PII/密钥脱敏的上下文感知结构化日志器，以及带基数上限的请求指标 HTTP 中间件。	AGENTS.md
`config`	动态配置：每个模块在注册时声明自己的配置 schema；配置值按 system→tenant 分层作用域、带缓存，Sensitive 项在静态存储时加密。提供登录页所需的两个免认证端点。	AGENTS.md
`jobs`	两种部署模式共用的 `Queue`/`Task`/`Job`/`Handler` 契约：`StandaloneQueue`（基于 SQLite 的进程内实现）与面向分布式模式的 Redis 实现，后者拆到独立子包，让只用 `StandaloneQueue` 的消费者不必为它付出依赖代价。	AGENTS.md
`ratelimit`	一个基于 `KVStore` 的限流器，被 `authn`、`integration` 等需要限制某件事发生频率的模块共用。	AGENTS.md
`pki`	签名密钥与 X.509 证书生命周期：`Signer` seam、内部 CA 签发、吊销、CRL 生成与 JWKS 导出。`authn` 的 `KeySource` 是它真实、API 已冻结的消费方；X.509/CA 那一层还没有真实消费方，这是一个有记录的已知例外。	AGENTS.md
`authn`	身份认证——回答"调用者是谁”，从不回答"可以做什么"。argon2id 密码、Ed25519 签名的访问令牌、一次性轮换的刷新令牌、TOTP 多因素认证，以及社交/企业单点登录（Google、GitHub、微信、钉钉、飞书、OIDC）。	AGENTS.md
`rbac`	基于角色的访问控制，默认拒绝、精确匹配 `resource:action`。刻意从不 import `authn`——它看到的永远只是认证方组装好的 `Subject{TenantID, UserID}`。	AGENTS.md
`org`	一个租户的组织树（邻接表加物化路径）、绑定在其上的成员关系，以及创建这些成员关系的邀请流程。	AGENTS.md
`storage`	租户对象存储：基于 `ObjectStore` seam 的上传/完成/派生生命周期、结构化元数据剥离、缩略图派生，以及可崩溃收敛的删除加过期清扫。	AGENTS.md
`notification`	平台的消息通知层：业务模块声明进去的实时通知类型注册表、按用户的偏好设置、带 SSE 推送的站内信箱，以及经过同意验证的外部渠道投递（邮件/短信）。	AGENTS.md
`billing`	Plan/Feature/Grant/Entitlements、渠道无关的 Subscription/Invoice 生命周期、并发安全的信用点账本，以及真实的支付网关接入（Stripe、支付宝、微信支付）。	AGENTS.md
`metering`	带两档可靠性的用量记录——失败即放行的分析级，以及基于 outbox、不会静默丢事件的计费级——两者最终汇聚到实时聚合计数器上。	AGENTS.md
`sharing`	公开分享链接：256 位 token、强制的默认过期时间、下一次访问检查即刻生效的吊销、完整的访问日志，以及无论拒绝原因是什么、对外表现完全一致的拒绝应答。	AGENTS.md
`integration`	租户对外的 API 接入层：API key 签发与分层限流，以及带 HMAC 签名和二次 SSRF/DNS 重绑定防护的出站 webhook。	AGENTS.md
`ai-gateway`	与厂商无关的 LLM 对话与图像生成网关（`ChatProvider`/`ImageProvider` seam、零依赖的 OpenAI 兼容默认实现、按作用域分层加密存储的 BYOK 凭据）。	AGENTS.md
`compliance`	按租户的保留期清扫、带已证明跨租户不擦除他人数据性质的即时"被遗忘权"擦除、经由 `sharing` 的导出投递，以及只读的审计查询。	AGENTS.md
`admin`	运维控制台后端：租户台账、带双重身份审计轨迹的完整模拟登录流程、跨租户用户搜索，以及只读的审计查询外壳。第二轮工作——角色管理、用量看板、按租户强制执行——尚未落地。	AGENTS.md
`saasctl`	面向业务方的 CLI——它的四个命令见快速开始。	AGENTS.md

Web 包（`web/packages/`，共 11 个）加消费方壳应用

每一行是一个 @speed/ 作用域下的 npm 包，全部运行在同一个根目录为 web/ 的 pnpm workspace 里。

面向 AI Agent

Mon, 01 Jan 0001 00:00:00 +0000

面向 AI Agent

如果你是一个正在帮某人接入 speed 的编码 Agent，或者被指向本站作为上下文，这一页就是写给你的。speed 自己的文档规范把 Agent 和人类同等视为一等读者（见 docs/internal/13，中文设计说明）——这一页与站点根部的 llms.txt 就是本站对这条规范的回应。

先按这个顺序读

仓库根 AGENTS.md —— 面向任何 AI 编码工具的入门：顶层架构形态、模块依赖方向、最容易踩坑的规则，以及其余一切内容在哪里。写得可以在几分钟内从头读到尾。
目标模块自己的 AGENTS.md（go/<name>/AGENTS.md 或 web/packages/<name>/AGENTS.md）—— 模块特定的纪律、文件布局、已知限制、测试方式。完整清单和直达链接见模块索引。
仓库根 CLAUDE.md 的 Repository Status 一节 —— 见下文，这是你绝不能让它在自己的认知里过期的那一份。

“这东西到底有没有真正实现"的唯一权威来源

仓库根 CLAUDE.md 的 Repository Status 一节，是"今天 CI 里到底真的能跑通并通过什么"这个问题唯一、权威、当前有效的答案。它逐模块指明：具体实现了什么、由哪个 CI 工作流验证（以及在什么触发条件下—— 每一个 PR、打了 full-ci 标签的 PR、还是手动触发），以及哪些还只是占位的桩代码。这个静态站点没办法跟上那一节变化的速度——不要把本站上的任何内容当作阅读那一节的替代品，任何状态断言（包括本站自己的实现状态页面）在你没有对照它或对照仓库本身核实之前，都不要轻信。

那一节自己陈述、这一页也重申的实用规则是：一个模块目录存在，不等于它背后有真正的代码——有些还只是一个 go.mod 加一行 doc.go 加一个指向设计文档的 AGENTS.md。在依赖某个模块之前，先确认它不止是个桩。

最容易踩坑的架构规则

模块依赖方向

依赖关系严格自底向上：

关于

Mon, 01 Jan 0001 00:00:00 +0000

关于 speed

speed 是一个多租户 SaaS 产品家族的共享基础设施。它不是一个应用程序：它是一组版本锁步、独立发布的 Go module 与 npm 包，由业务方项目接入后编译成单一的二进制文件。各模块在进程内互相调用——没有服务发现，也没有 Kubernetes 那一套基础设施。

整体形态

方面	设计
依赖关系	严格自底向上：基础模块（`pkgcore`、`dbkit`、`observability`、`ratelimit`、`tenancy`）支撑着上层的一切。
部署模式与实现组合	两条正交的轴。每一个基础设施依赖都是一个接口，可以有多种实现（一种进程内实现，加上 PostgreSQL、Redis、S3 等外部实现）。部署模式并不选择实现，它只约束实现：每个实现声明自己的能力，当某种组合无法在声明的模式下运行时，装配会失败。单进程部署可以连接真实的外部服务。业务代码从不对模式分支判断。
多租户	共享数据库配合 `tenant_id` 隔离，由 GORM 插件、强制使用的泛型 repository 基类，以及分布式模式下的 PostgreSQL 行级安全三重把关。
版本管理	锁步版本：所有模块与包共享同一个版本号、一起发布；只支持相同版本号的组合。

文档如何分发

每个模块都在自己内部带一份 AGENTS.md——面向 AI 编码工具的速览：职责边界、公开 API、典型用法，以及明确的禁止事项——再加一份普通的 README.md，让文档随代码一起分发，并且始终与业务方实际拉取的版本保持一致。（每模块一份的 docs/usage.md 是 docs/internal/13 记录的长期计划；截至本文写作，恰好只有一个模块 go/notification 建了这样一份—— go/notification/docs/usage.md，其自己的文件头就说明这是写给其他模块参考的模板——其余每一个 Go module 和每一个 npm 包目前都还只靠自己的 AGENTS.md 加 README.md。）本站是跨模块的中心参考——完整索引见模块索引——计划按发布版本分目录，模块自己的文档会指向这里获取总览。

本站现状与计划的对照

机制决策已经落定：本站基于 Hugo 和 hugo-book 主题构建，把 docs/internal/13-documentation-standards.md 刻意推迟到 M4 的静态站点生成器决策提前落地——这与本仓库 storage/notification 两个模块此前"提前排期落地"的先例是同一种模式。在候选主题之间选择 hugo-book 而不是 Docsy 的原因：Docsy 需要 Hugo Modules 加一整套 Node/PostCSS 资源构建流水线（按其现行的安装文档，它的 Bootstrap 与 Font Awesome 资源来自 npm，且需要 PATH 上存在一个 Dart Sass 编译器），这会重新引入本目录此前一直刻意回避的 Node 依赖，而 hugo-book 没有这个依赖——它现行的版本（v0.15.0）甚至去掉了更早版本里的 Sass 依赖——只需要 Hugo 这一个二进制本身。中英双语内容靠的是 Hugo 自身的多语言机制，不是某个主题的功能：两个候选主题本可以同样好地满足 i18n 这条需求，因为无论是 Docsy 的 Bootstrap 外观还是 hugo-book 朴素的外观，底下都是同一套 Hugo 核心的语言机制。

实现状态

Mon, 01 Jan 0001 00:00:00 +0000

实现状态

权威、始终最新的说法在仓库根 CLAUDE.md 的 Repository Status 一节，本页刻意不重复它——逐模块的重复统计只会在下一个模块下一轮落地的那一刻就开始过期。下面是在本页最后一次写作时对照真实仓库核实过的粗粒度快照；请把它当作一个方向性参考，而不是信息源本身。

用里程碑编号来描述状态已经不再是这里有用的框架 —— 实现进度早已远远超出本站最初跟踪的 M0 里程碑。规划中的模块图谱大部分已经落地；路线图的里程碑编号（docs/internal/15-roadmap.md）仍然记录着每个模块最初被排在哪一轮，但有几个模块的交付明显早于那个排期窗口。

今天真实存在的

领域	状态
Go module	根 `go.work` 里列出的模块全部 21 个都有真实、经过测试的实现——`go build`、`go vet`、`golangci-lint run ./...` 和 `go test -race` 全部通过。清单见模块索引。
Go 的 CI 覆盖	全部 21 个模块都在 `fast-check.yml`（每一个 pull request，加上每一次推送到 `main`）里有自己的矩阵行——`golangci-lint`、`go vet`、开启 race 检测的单元测试、workspace 上下文构建，以及 `GOWORK=off` 的独立构建，逐模块执行，`go/admin` 也不例外。
npm 包	`web/packages/` 下的 11 个 `@speed/*` 包，加上 reference app 自己的 web host 作为未纳入版本管理的第十二个 workspace 成员，都已实现、经过测试，lint/typecheck/build 全部干净通过。
API 契约	六份 OpenAPI 片段（notes、org、authn、storage、notification、sharing）驱动 spec 先行的生成流程；其中三份（notes、authn、notification）汇入合并后的文档，同时生成 `@speed/api-sdk` 前端。`admin` 与 `pki` 也各自有自己的片段，但还没有接入 `api-contract` 流水线。

CI 流水线

流水线	触发条件	覆盖范围
`fast-check.yml`	每一个 pull request，加上每一次推送到 `main`	21 个模块矩阵的 lint、vet 与开启 race 检测的单元测试；11 个 npm 包加 reference-app web host 的 lint/typecheck/test/build；仓库级检查（`docs/internal` 之外的 CJK 扫描、workspace 级构建、`go.work` 漂移检测、架构纪律相关的 semgrep 规则）。
`full-check.yml`	打了 `full-ci` 标签的 PR，加上每一次推送到 `main`	同一份模块矩阵，再加上基于 Docker 的 PostgreSQL/Redis/MinIO 集成测试层，以及 reference app 自己的组合式 HTTP 流程测试。
`docs-check.yml`	触碰文档或 i18n 资源的 PR	i18n key 集合的一致性（zh-CN 对 en-US），以及本站自己的结构检查（`tools/check_docs_site.py`，现在对照一次真实的 `hugo build` 产物执行）。
`api-contract.yml`	触碰 API 契约工具链的 PR	从 OpenAPI spec 重新生成后端接口（对已合并的片段，同时重新生成前端 SDK），并重新构建 reference app，让没有对应实现的 spec 变更无法通过编译。
`security.yml`	每一个 PR，加上每天一次的定时任务	依赖审计、密钥扫描、CodeQL、许可证检查。
`release.yml`	仅手动触发	完全离线校验一份锁步、单一版本号的发布计划。目前没有接入任何发布凭据——真正的发布是更晚的 v1.0 里程碑。
`docs-site-deploy.yml`	推送到 `main` 且触碰 `docs/site/**`，加上手动触发	用 `hugo --minify` 构建本站，把 `public/` 部署到 GitHub Pages。

e2e.yml、nightly.yml 与 scaffold-verify.yml 目前是刻意保持门控关闭的桩，还没有在任何 pull request 上触发。

speed on speed documentation

快速开始

快速开始

1. 克隆仓库

2. 用 saasctl new 生成一个起始项目

模块索引

模块索引

Go module（go/，共 21 个）

Web 包（web/packages/，共 11 个）加消费方壳应用

面向 AI Agent

面向 AI Agent

先按这个顺序读

“这东西到底有没有真正实现"的唯一权威来源

最容易踩坑的架构规则

模块依赖方向

关于

关于 speed

整体形态

文档如何分发

本站现状与计划的对照

实现状态

实现状态

今天真实存在的

CI 流水线

2. 用 `saasctl new` 生成一个起始项目

Go module（`go/`，共 21 个）

Web 包（`web/packages/`，共 11 个）加消费方壳应用