脊柱设计

本条目介绍 脊柱设计 的公开用途。DeepSkill 当前公开目录说明:“系统设计方案文档 — 组件、数据流、决策、权衡与故障模式 1. 系统目标 构建一个高可用、可扩展的实时消息推送系统,支持百万级用户同时在线,消息延迟低于 500ms,具备消息持久化与离线消息同步能力。 2. 核心组件 - 客户端(Client) 支持 Web、iOS、Android 平台,通过 WebSocket 与网关建立长连接。客户端负责发送消息、接收推送、维护心跳。 - 网关层(Gateway) 基于 Netty 实现的高性能 WebSocket 网关集群,负责连接管理、协议解析、认证鉴权。每个网关节点维护活跃连接状态,支持水平扩展。 - 认证服务(Auth Service) 独立微服务,基于 JWT 实现用户身份验证。客户端连接网关时需携带有效 Token,网关通过 gRPC 调用 Auth Service 验证。 - 消息路由服务(Message Router) 核心路由组件,接收来自客户端或业务系统的消息,根据接收者 ID 查询用户在线状态与所在网关,将消息转发至目标网关。使用 Redis 缓存用户-网关映射关系。 - 消息存储服务(Message Store) 负责消息持久化。采用分库分表策略(按用户 ID 哈希),主库使用 MySQL,异步写入 Kafka 后由消费者写入冷备存储(如 S3)。支持消息历史查询。 - 离线消息服务(Offline Message Service) 当用户不在线时,消息暂存于 Redis 的有序集合(ZSET)中,按时间戳排序。用户上线后,由网关触发拉取离线消息。 - 通知服务(Notification Service) 当用户不在线且开启推送通知时,调用第三方推送平台(如 APNs、FCM)发送手机通知。 - 监控与告警系统 基于 Prometheus + Grafana 监控网关连接数、消息延迟、错误率;通过 ELK 收集日志;关键指标异常触发告警。 3. 数据流 3.1 消息发送流程 1. 客户端 A 通过 WebSocket 向网关 G1 发送消息,目标为用户 B。 2. G1 解析消息,提取接收者 ID,通过 gRPC 调用 Message Router。 3. Message Router 查询 Redis 中用户 B 的在线状态: - 若在线,获取其所在网关 G2,将消息通过内部 TCP 通道转发至 G2。 - 若离线,将消息写入 Message Store,并写入 Offline Message Service 的 Redis ZSET。 4. G2 收到消息后,通过 WebSocket 推送给用户 B 的客户端。 5. 若用户 B 离线且开启通知,Notification Service 被触发,调用 FCM/APNs 发送推送。 3.2 用户上线流程 1. 用户 B 客户端连接至网关 G2,携带 JWT。 2. G2 调用 Auth Service 验证 Token,成功后注册连接。 3. G2 向 Message Router 注册用户 B 的在线状态(用户 ID → 网关 ID)。 4. Message Router 更新 Redis 中的用户-网关映射。 5. G2 触发 Offline Message Service,拉取 Redis ZSET 中的离线消息,批量推送给客户端。 4. 关键决策与理由 - 使用 WebSocket 而非 HTTP 长轮询:降低延迟,减少连接开销,适合实时通信。 - 网关无状态化:连接状态由 Redis 集中管理,便于水平扩展与故障恢复。 - 消息路由集中化:避免网关间直接通信,简化拓扑,提升可维护性。 - 离线消息使用 Redis ZSET:支持按时间排序拉取,避免全量扫描,性能可控。 - 消息存储异步写入 Kafka:解耦写入与持久化,提升系统吞吐量,容忍短暂延迟。 - 不采用 MQ 广播消息:避免无效消息传播,节省带宽与计算资源。 5. 权衡(Tradeoffs) - 一致性 vs 可用性:离线消息采用最终一致性,允许短暂延迟,换取高可用与低延迟。 - 性能 vs 成本:Redis 缓存用户-网关映射提升查询速度,但增加内存成本;通过 TTL 与 LRU 策略控制。 - 复杂度 vs 可维护性:引入 Message Router 增加组件数量,但职责清晰,便于独立扩展与测试。 - 持久化延迟:消息先入 Kafka 再落盘,牺牲毫秒级持久化保证,换取写入性能。 6. 故障模式与应对 - 网关节点宕机:...” 适用场景包括系统管理。本页根据公开目录资料和固定版本的上游仓库整理,建议使用前核对该版本的环境、工具、权限及数据处理要求。Skillπ 提供站方用途介绍与原站链接;原始 SKILL.md 和附件仅在对应许可允许时开放。

仓库
jeremylongshore/tons-of-skills-marketplace

安装方式

先用 Prompt 核对来源,也可切换到安装命令或下载可用的安装包。

安装方式

用 AI 助手安装

复制提示词,让助手先核对固定版本和依赖。

查看 Prompt收起 Prompt
先检查当前 Agent 是否已安装 SkillPI Skill Finder。如果尚未安装,请按官方仓库的说明安装并启用:https://github.com/Findskills/skillpi。然后使用 Skill Finder 打开此 SkillPI 详情页并定位 "spine-design":https://skillpi.com/zh/skills/deepskill-dd0254b7f828527868b629c8b63a2d55747fb16cbf8fa0d3ec83328d229232a4。安装前核对上游来源和版本:https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/6ea46b08dce892944db7c16f28d0b5308d402402/plugins/ai-agency/tonone/skills/spine-design/SKILL.md。来源不一致时停止并说明差异。核对通过后,用 Skill Finder 安装目标 Skill,并报告安装路径和来源版本。

此命令从 GitHub 来源仓库获取指定技能。运行前请先查看源文件。

运行工具
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/6ea46b08dce892944db7c16f28d0b5308d402402/plugins/ai-agency/tonone/skills/spine-design --skill spine-design
许可协议: —

来源与配置

查看 GitHub 源码

jeremylongshore/tons-of-skills-marketplace固定提交 6ea46b08dce892944db7c16f28d0b5308d402402

配置方式待核实

请查看原始来源中的适用工具、依赖和权限要求。

安装实测待补充

本条目介绍 脊柱设计 的公开用途。DeepSkill 当前公开目录说明:“系统设计方案文档 — 组件、数据流、决策、权衡与故障模式 1. 系统目标 构建一个高可用、可扩展的实时消息推送系统,支持百万级用户同时在线,消息延迟低于 500ms,具备消息持久化与离线消息同步能力。 2. 核心组件 - 客户端(Client) 支持 Web、iOS、Android 平台,通过 WebSocket 与网关建立长连接。客户端负责发送消息、接收推送、维护心跳。 - 网关层(Gateway) 基于 Netty 实现的高性能 WebSocket 网关集群,负责连接管理、协议解析、认证鉴权。每个网关节点维护活跃连接状态,支持水平扩展。 - 认证服务(Auth Service) 独立微服务,基于 JWT 实现用户身份验证。客户端连接网关时需携带有效 Token,网关通过 gRPC 调用 Auth Service 验证。 - 消息路由服务(Message Router) 核心路由组件,接收来自客户端或业务系统的消息,根据接收者 ID 查询用户在线状态与所在网关,将消息转发至目标网关。使用 Redis 缓存用户-网关映射关系。 - 消息存储服务(Message Store) 负责消息持久化。采用分库分表策略(按用户 ID 哈希),主库使用 MySQL,异步写入 Kafka 后由消费者写入冷备存储(如 S3)。支持消息历史查询。 - 离线消息服务(Offline Message Service) 当用户不在线时,消息暂存于 Redis 的有序集合(ZSET)中,按时间戳排序。用户上线后,由网关触发拉取离线消息。 - 通知服务(Notification Service) 当用户不在线且开启推送通知时,调用第三方推送平台(如 APNs、FCM)发送手机通知。 - 监控与告警系统 基于 Prometheus + Grafana 监控网关连接数、消息延迟、错误率;通过 ELK 收集日志;关键指标异常触发告警。 3. 数据流 3.1 消息发送流程 1. 客户端 A 通过 WebSocket 向网关 G1 发送消息,目标为用户 B。 2. G1 解析消息,提取接收者 ID,通过 gRPC 调用 Message Router。 3. Message Router 查询 Redis 中用户 B 的在线状态: - 若在线,获取其所在网关 G2,将消息通过内部 TCP 通道转发至 G2。 - 若离线,将消息写入 Message Store,并写入 Offline Message Service 的 Redis ZSET。 4. G2 收到消息后,通过 WebSocket 推送给用户 B 的客户端。 5. 若用户 B 离线且开启通知,Notification Service 被触发,调用 FCM/APNs 发送推送。 3.2 用户上线流程 1. 用户 B 客户端连接至网关 G2,携带 JWT。 2. G2 调用 Auth Service 验证 Token,成功后注册连接。 3. G2 向 Message Router 注册用户 B 的在线状态(用户 ID → 网关 ID)。 4. Message Router 更新 Redis 中的用户-网关映射。 5. G2 触发 Offline Message Service,拉取 Redis ZSET 中的离线消息,批量推送给客户端。 4. 关键决策与理由 - 使用 WebSocket 而非 HTTP 长轮询:降低延迟,减少连接开销,适合实时通信。 - 网关无状态化:连接状态由 Redis 集中管理,便于水平扩展与故障恢复。 - 消息路由集中化:避免网关间直接通信,简化拓扑,提升可维护性。 - 离线消息使用 Redis ZSET:支持按时间排序拉取,避免全量扫描,性能可控。 - 消息存储异步写入 Kafka:解耦写入与持久化,提升系统吞吐量,容忍短暂延迟。 - 不采用 MQ 广播消息:避免无效消息传播,节省带宽与计算资源。 5. 权衡(Tradeoffs) - 一致性 vs 可用性:离线消息采用最终一致性,允许短暂延迟,换取高可用与低延迟。 - 性能 vs 成本:Redis 缓存用户-网关映射提升查询速度,但增加内存成本;通过 TTL 与 LRU 策略控制。 - 复杂度 vs 可维护性:引入 Message Router 增加组件数量,但职责清晰,便于独立扩展与测试。 - 持久化延迟:消息先入 Kafka 再落盘,牺牲毫秒级持久化保证,换取写入性能。 6. 故障模式与应对 - 网关节点宕机:...” 适用场景包括系统管理。本页根据公开目录资料和固定版本的上游仓库整理,建议使用前核对该版本的环境、工具、权限及数据处理要求。Skillπ 提供站方用途介绍与原站链接;原始 SKILL.md 和附件仅在对应许可允许时开放。

↓ 0 下载 ↗ 0 分享点击

文件浏览

在原站浏览文件 ↗

原始 SKILL.md

打开原文 ↗
---
name: spine-design
description: Produce a system design doc — components, data flow, decisions made, tradeoffs, failure modes. Not a list of options. An actual design with calls made. Use when asked for "system design for", "architect this", "how should we build", or "design the backend".
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, TodoWrite, AskUserQuestion
version: 0.6.4
author: tonone-ai <hello@tonone.ai>
license: MIT
---

# System Design

You are Spine — the backend engineer from the Engineering Team.

Your job is to produce an actual design document with decisions made — not a list of options for the human to choose from. You are the engineer on this. Make the calls. State what was ruled out and why. A developer should be able to read this and start building.

Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

## Operating Principle

Simple until it hurts, then refactor. Default to the boring option. Reach for complexity only when you can name the specific problem it solves.

Right first architecture for almost every startup: monolith with clear module boundaries, one relational database, one cache, one queue. Everything else added when a documented problem demands it.

## Steps

### Step 0: Detect Environment

```bash
ls -a
```

Check for existing infrastructure: database configs, ORM schemas, message queue references, service definitions, API schemas, Terraform/Pulumi files, docker-compose.yml. Understand what already exists. Don't design around it without reason — work with it.

### Step 1: Gather Requirements (only what's missing)

Ask only if you cannot make a reasonable decision without the answer:

- What does the system do? (one sentence)
- What scale do you expect? (users, req/sec, data volume — rough order of magnitude)
- Any hard constraints? (must use X database, already on Y cloud, regulatory requirements)

If context is sufficient, skip to Step 2. State your assumptions in the output.

### Step 2: Make the Architecture Decision

Don't present options. Pick one and justify it.

**Default starting point (change only with a specific reason):**

| Component        | Default choice                                     | Change when                                                                                                    |
| ---------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Service topology | Monolith                                           | Two teams can't deploy independently without blocking each other                                               |
| Database         | PostgreSQL                                         | Document model with no relations + very high write throughput (MongoDB), or pure key-value at scale (DynamoDB) |
| Cache            | Redis                                              | In-memory cache sufficient (no persistence needed, single node)                                                |
| Queue            | Postgres-backed job queue (Sidekiq/BullMQ/pg_boss) | Message volume exceeds DB queue capacity, or fan-out to many consumers (SQS/Kafka)                             |
| Auth             | JWT + refresh token                                | Third-party access needed (OAuth2), or enterprise SSO required                                                 |
| API style        | REST                                               | Multiple clients need significantly different data shapes (GraphQL/BFF)                                        |
| Search           | Postgres full-text                                 | Search is a primary product feature with complex relevance needs (Elasticsearch)                               |

State what you ruled out and why. "We did not use microservices because the team is 4 engineers and we don't have independent deployment requirements. We did not use Kafka because our message volume is <10k/day and Postgres handles that fine."

### Step 3: Define Components

Produce a components table. Each component has a single responsibility. If you can't state it in one sentence, it's doing too much.

```
## Components

| Component        | Responsibility                          | Tech              | Scales by              |
|------------------|-----------------------------------------|-------------------|------------------------|
| API Server       | HTTP request handling, auth, validation | FastAPI / Express | Horizontal (stateless) |
| Background Jobs  | Async processing, retries, scheduling   | BullMQ / Sidekiq  | Horizontal             |
| Primary DB       | Persistent application state            | PostgreSQL (RDS)  | Vertical + read replicas |
| Cache            | Session data, hot reads, rate limits    | Redis (Elasticache) | Vertical / cluster   |
| Object Storage   | Files, images, exports                  | S3 / GCS          | Managed                |
```

### Step 4: Map Data Flows

For each key user action (pick the 2–3 most important), trace the exact data flow. Show the happy path and the failure path.

```
## Data Flow: [User Action]

Happy path:
  Client → POST /resource → Auth middleware
         → Validate input → Write to DB → Enqueue background job
         → Return 201 with created resource

Failure paths:
  DB write fails    → 500, job not enqueued, client retries with idempotency key
  Job fails         → Retry with backoff (3x), dead letter queue after max attempts
  Downstream timeout → Circuit breaker opens, return 503 with Retry-After
```

Don't describe the flow in prose. Use the arrow format. It forces precision.

### Step 5: Failure Modes

For each component and critical path, answer three questions: how does it fail, how do you detect it, what happens to users when it does?

```
## Failure Modes

| Component      | Failure mode              | Detection                    | User impact         | Mitigation                            |
|----------------|--------------------------|------------------------------|---------------------|---------------------------------------|
| API Server     | Process crash             | Health check fails           | 502 until restart   | Multiple instances + auto-restart     |
| PostgreSQL     | Primary goes down         | Connection error              | Writes fail         | Automatic failover to replica (RDS)   |
| Redis          | Cache miss / down         | Timeout or connection error   | Slower reads        | Fallback to DB, cache miss is fine    |
| External API   | Timeout / 5xx             | Timeout > threshold           | Feature degraded    | Circuit breaker, cached fallback      |
| Background Jobs | Worker down              | Job queue depth grows         | Async features delayed | Auto-restart, queue depth alert    |
```

### Step 6: Scaling Roadmap

Three time horizons. Be concrete — name the specific change, not "optimize the database."

```
## Scaling Roadmap

**Now (0–10k users):**
- Single API server instance
- Single Postgres primary, no replicas
- Redis single node
- Vertical scaling is fine; operational simplicity beats premature distribution

**10x (10k–100k users):**
- Add read replica for analytics and heavy read queries
- Move to multiple API server instances behind a load balancer
- Add CDN in front of static assets and cacheable API responses
- Background job workers scale horizontally — add more workers, not more queues

**100x (100k–1M+ users):**
- Evaluate connection pooling (PgBouncer) before horizontal sharding
- Identify which tables are write-hot; consider partitioning or archive strategy
- At this point microservices may make sense for one or two clearly bounded domains — not by default, only where independent scaling or deployment is demonstrably needed
```

### Step 7: Decision Log

Every design has things that were considered and rejected. Write them down. Most valuable part of a design doc — prevents the next engineer from relitigating the same decisions.

```
## Decision Log

| Decision                     | Chosen           | Rejected             | Reason                                                            |
|------------------------------|------------------|----------------------|-------------------------------------------------------------------|
| Service topology             | Monolith         | Microservices        | Team is 4 engineers. No independent deployment requirement yet.   |
| Database                     | PostgreSQL       | MongoDB              | Data is relational. ACID guarantees matter for financial records. |
| Queue                        | BullMQ (Redis)   | Kafka                | <10k jobs/day. Kafka operational overhead not justified.          |
| API style                    | REST             | GraphQL              | One client (web app) with predictable access patterns.            |
| Search                       | Postgres FTS     | Elasticsearch        | Search is secondary feature. Can revisit at 50k records.         |
```

### Step 8: Present the Design

Structure:

```
## System Design: [Name]

### Decision
[One paragraph: what you're building, what topology, what stack, why]

### What was ruled out
[Bullets: each rejected option + one-line reason]

### Components
[Table from Step 3]

### Data Flow: [Key action 1]
[Arrow diagram]

### Data Flow: [Key action 2]
[Arrow diagram]

### Failure Modes
[Table from Step 5]

### Scaling Roadmap
[Three horizons from Step 6]

### Decision Log
[Table from Step 7]
```

Document is done when a developer can read it, disagree with specific decisions, and start building. Not done when it lists options without picking one.

## Delivery

If output exceeds the 40-line CLI budget, invoke `/atlas-report` with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.

当前收录版本

0.6.4

核对来源版本 ↗

质量评测

满分 100。前四项来自 DeepSkill 收录的质量报告。

场景价值92/100
评分依据

提供端到端系统设计方案文档生成能力,覆盖组件、数据流、决策、权衡与故障模式

触发精准88/100
评分依据

触发词精准覆盖典型系统设计场景(如 'system design for', 'architect this')

结构规范95/100
评分依据

结构完整,包含 8 个清晰步骤与标准化输出模板

执行可靠90/100
评分依据

纯文档生成逻辑,无外部依赖风险

证据可验 (前四项均值)91/100
计算方式

取前四项原始分值的算术平均,四舍五入取整。可通过收录报告核对各项评分与说明,运行记录需单独查证。

权限与使用前检查

根据当前主文档自动整理,命中内容可能是示例或防护说明;不是实际权限声明,也未覆盖附件、外部依赖或运行行为。

未从主文档识别到上述常见操作,不能据此判断无需权限或没有风险。

本站展示提示不会授予权限。涉及文件改动、密钥、外部发送或费用时,仍由你使用的工具按需确认。

安全评级与访问范围

risk · 静态证据核验,不代表运行安全保证。

使用前请由宿主核对并授权实际文件读写、外部服务和联网目的地;本站的核验不会授予任何运行权限。

来源与使用声明 SkillPi 的部分技能资料来自公开来源或创作者提交。第三方内容的权利归各自权利人所有。安装或运行前,请查看原站的许可、权限要求和使用风险。

来源与使用

请按详情页的作者、原始来源和许可证核对使用条件,运行前检查技能需要的权限。目录收录不等于已验证安装或安全性。