# Distributed

> Use when working with distributed systems — consensus, replication, fault tolerance, data locality

- Skill: `liaosw97/distributed` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add liaosw97/distributed`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liaosw97/distributed/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: liaosw97 (https://skillmd.com/u/liaosw97)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/liaosw97/distributed

---


## 核心原则
- **任务粒度合理**：平衡任务开销与并行度，避免过多细粒度任务
- **数据本地化**：将计算调度到数据所在节点，减少网络传输
- **容错与恢复**：设计自动故障检测和任务重试机制
- **资源隔离**：多租户场景下保证资源公平分配

## 技术栈
- Ray - 分布式计算框架，支持 Actor 模型
- Dask - Python 并行计算库
- Apache Spark - 大数据批处理引擎
- Celery - 分布式任务队列
- Kubernetes - 容器编排与资源调度
- Redis/RabbitMQ - 任务消息队列

## 最佳实践
1. **资源管理**
   - 合理配置集群资源池（CPU、内存、GPU）
   - 使用 Placement Group 控制任务放置
   - 实现资源弹性伸缩
   - 监控资源利用率并动态调整

2. **容错机制**
   - 配置任务最大重试次数（通常 3 次）
   - 设计 Checkpoint 保存中间状态
   - 实现心跳检测和节点健康监控
   - 使用 Lineage 重建丢失数据

3. **数据本地化**
   - 优先调度到数据所在节点
   - 使用共享存储（如 S3、HDFS）减少数据移动
   - 对大数据集进行分区和缓存
   - 避免在节点间传输大对象

4. **监控告警**
   - 统一指标收集（Prometheus 格式）
   - 监控任务延迟、吞吐量、失败率
   - 设置资源耗尽告警阈值
   - 实现分布式追踪（Tracing）

5. **安全隔离**
   - 多租户使用 Namespace 隔离
   - 配置 Resource Quota 限制资源使用
   - 实现任务优先级调度
   - 敏感数据加密传输和存储

## 关键约定
1. **命名规范**
   - 任务: `<domain>_<action>_<entity>` (如 `ml_train_model`)
   - Actor: `<purpose>_<id>` (如 `inference_worker_01`)
   - 队列: `<domain>_<priority>_queue`

2. **任务配置**
   - 任务超时 = 预估时间 × 2
   - 重试间隔：指数退避，最大 60s
   - 并行度 = 核心数 × 1.5（IO 密集型）
   - 并行度 = 核心数（CPU 密集型）

3. **资源配额**
   - 单任务默认内存：1GB
   - 单任务默认 CPU：1 核
   - GPU 任务显式声明资源需求
   - 预留 10% 资源给系统组件

4. **错误处理**
   - 可恢复错误：重试
   - 不可恢复错误：记录并跳过
   - 死信队列：存储失败任务
   - 告警：连续失败超过阈值触发