distributed-systems

分布式系统模式

构建可靠分布式系统的全面模式。每个类别都在 rules/ 中有单独的规则文件，按需加载。

快速参考

类别	规则数	影响	适用场景
分布式锁	1	严重	栅栏令牌、所有者验证；Redis/Redlock 和 Postgres advisory 锁请参阅上游文档
弹性	3	严重	熔断器、带退避的重试、舱壁隔离
幂等性	1	高	幂等键；去重和基于数据库的存储请参阅上游文档
速率限制	2	高	令牌桶、滑动窗口；SlowAPI 集成请参阅上游文档
边缘计算	2	高	边缘工作器、V8 隔离区、CDN 缓存、地理路由
事件驱动	2	高	事件溯源、CQRS、事务发件箱、Saga

共计：6 个类别中的 11 条规则。 已移除的主题请参阅上游覆盖内容中的一手资料；Ork 特有的经验教训记录在 references/ork-delta.md 中。

快速开始

# Redis distributed lock with Lua scripts
async with RedisLock(redis_client, "payment:order-123"):
    await process_payment(order_id)

# Circuit breaker for external APIs
@circuit_breaker(failure_threshold=5, recovery_timeout=30)
@retry(max_attempts=3, base_delay=1.0)
async def call_external_api():
    ...

# Idempotent API endpoint
@router.post("/payments")
async def create_payment(
    data: PaymentCreate,
    idempotency_key: str = Header(..., alias="Idempotency-Key"),
):
    return await idempotent_execute(db, idempotency_key, "/payments", process)

# Token bucket rate limiting
limiter = TokenBucketLimiter(redis_client, capacity=100, refill_rate=10)
if await limiter.is_allowed(f"user:{user_id}"):
    await handle_request()

分布式锁

协调多个服务实例对资源的独占访问。

规则	文件	核心模式
栅栏令牌	rules/locks-fencing-tokens.md	所有者验证、TTL、心跳续期

Redis 单节点锁、Redlock 多数派锁和 PostgreSQL advisory 锁已有一手文档；请参阅上游覆盖内容。

弹性

适用于生产环境的分布式系统容错机制。

规则	文件	核心模式
熔断器	rules/resilience-circuit-breaker.md	CLOSED/OPEN/HALF_OPEN 状态、滑动窗口
重试与退避	rules/resilience-retry-backoff.md	指数退避、抖动、错误分类
舱壁隔离	rules/resilience-bulkhead.md	信号量分级、拒绝策略、队列深度

幂等性

确保操作可以安全重试，不会产生意外副作用。

规则	文件	核心模式
幂等键	rules/idempotency-keys.md	确定性哈希、Stripe 风格的标头

事件消费者去重和基于数据库的幂等存储遵循 Stripe 模式；请参阅上游覆盖内容。

速率限制

使用 Redis 通过分布式速率限制保护 API。

规则	文件	核心模式
令牌桶	rules/ratelimit-token-bucket.md	Redis Lua 脚本、突发容量、补充速率
滑动窗口	rules/ratelimit-sliding-window.md	有序集合、精确计数、无边界突增

SlowAPI 与 Redis 的配置以及分级限制已有一手文档；请参阅上游覆盖内容。

边缘计算

适用于 Cloudflare Workers、Vercel Edge 和 Deno Deploy 的边缘运行时模式。

规则	文件	核心模式
边缘工作器	rules/edge-workers.md	V8 隔离区限制、Web API、地理路由、边缘身份验证
边缘缓存	rules/edge-caching.md	边缘缓存旁路模式、CDN 标头、KV 存储、过期后后台刷新

事件驱动

事件溯源、CQRS、Saga 编排和可靠消息传递模式。

规则	文件	核心模式
事件溯源	rules/event-sourcing.md	事件溯源聚合、CQRS 读模型、乐观并发控制
事件消息传递	rules/event-messaging.md	事务发件箱、Saga 补偿、幂等消费者

上游覆盖范围（不要重复说明）

以下主题已于 2026-07-31 从此技能中移除（wrap-plus-delta 精简），因为一手来源维护了这些内容。请查阅来源；不要在此处重新添加教程。这些主题中 Ork 特有的经验教训保留在 references/ork-delta.md 中。

主题	一手来源
Redis 单节点锁、Redlock 算法和法定数量	https://redis.io/docs/latest/develop/use/patterns/distributed-locks/
PostgreSQL 咨询锁（会话级和事务级）	https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS
熔断器模式、阈值、设置和推出指南	https://learn.microsoft.com/azure/architecture/patterns/circuit-breaker
舱壁模式深入介绍（线程池、信号量、层级）	https://learn.microsoft.com/azure/architecture/patterns/bulkhead
重试策略、指数退避、抖动、重试预算	https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/ and https://tenacity.readthedocs.io
HTTP 和 LLM 提供商错误分类（可重试与不可重试）	https://docs.claude.com/en/api/errors and https://platform.openai.com/docs/guides/error-codes
幂等键、请求去重、数据库支持的幂等性	https://docs.stripe.com/api/idempotent_requests
令牌桶算法和 Redis 限流模式	https://redis.io/glossary/rate-limiting/
FastAPI 分布式限流（SlowAPI 中间件、层级）	https://slowapi.readthedocs.io/
LLM 回退链、提供商故障转移、成本跟踪	https://vercel.com/docs/ai-gateway; model ids and pricing at https://docs.claude.com/en/docs/about-claude/pricing

关键决策

决策	建议
锁后端	追求速度时使用 Redis，已在使用 PostgreSQL 时使用 PostgreSQL，追求高可用时使用 Redlock
锁 TTL	预期操作耗时的 2-3 倍
熔断器恢复	使用滑动窗口进行半开探测
重试算法	指数退避 + 全抖动
舱壁隔离	基于信号量的层级（关键/标准/可选）
幂等性存储	Redis（速度）+ DB（持久性），TTL 为 24-72 小时
限流算法	大多数 API 使用令牌桶，严格配额使用滑动窗口
限流存储	Redis（分布式，通过 Lua 脚本保证原子性）

不适用场景

不存在单独的事件溯源／Saga／CQRS 技能；它们是分布式系统中的规则。但大多数项目根本用不上它们。

模式	面试	黑客马拉松	MVP	增长期	企业级	更简单的替代方案
事件溯源	过度设计	过度设计	过度设计	过度设计	有充分理由时使用	带状态列的仅追加表
Saga 编排	过度设计	过度设计	过度设计	有选择地使用	适用	顺序调用服务并手动回滚
熔断器	过度设计	过度设计	临界	适用	必需	使用超时的 try/except
分布式锁	过度设计	过度设计	临界	适用	必需	数据库行级锁（SELECT FOR UPDATE）
CQRS	过度设计	过度设计	过度设计	过度设计	有充分理由时使用	读写共用单一模型
事务型 Outbox	过度设计	过度设计	过度设计	有选择地使用	适用	提交后直接发布
限流	过度设计	过度设计	仅简单限流	适用	必需	Nginx 限流或云 WAF

经验法则： 如果你只有一个服务器进程，就不需要分布式系统模式。请使用进程内替代方案。只有在实际拥有多个实例时，才引入分布式方案。

反模式（禁止）

# LOCKS: Never forget TTL (causes deadlocks)
await redis.set(f"lock:{name}", "1")  # WRONG - no expiry!

# LOCKS: Never release without owner check
await redis.delete(f"lock:{name}")  # WRONG - might release others' lock

# RESILIENCE: Never retry non-retryable errors
@retry(max_attempts=5, retryable_exceptions={Exception})  # Retries 401!

# RESILIENCE: Never put retry outside circuit breaker
@retry  # Would retry when circuit is open!
@circuit_breaker
async def call(): ...

# IDEMPOTENCY: Never use non-deterministic keys
key = str(uuid.uuid4())  # Different every time!

# IDEMPOTENCY: Never cache error responses
if response.status_code >= 400:
    await cache_response(key, response)  # Errors should retry!

# RATE LIMITING: Never use in-memory counters in distributed systems
request_counts = {}  # Lost on restart, not shared across instances

详细文档

资源	描述
scripts/	模板：锁实现、熔断器、限流器
references/ork-delta.md	wrap-plus-delta 精简后保留的 Ork 特有经验教训和内部决策

相关技能

• caching - Redis 缓存模式，将缓存用作回退方案
• background-jobs - 任务去重、带重试的异步处理
• observability-monitoring - 熔断器状态变化的指标与告警
• error-handling-rfc9457 - 用于弹性故障的结构化错误响应
• auth-patterns - API 密钥管理、身份验证集成