@umacloud/knowledge 1.0.1

package/database/02-playbooks/postgresql-production-playbook.md

@@ -0,0 +1,146 @@
+---
+id: postgresql-production-playbook
+title: PostgreSQL 生产环境调优手册
+domain: database
+category: 02-playbooks
+difficulty: advanced
+tags: [database, postgresql, postgres, production, tuning, index, query, optimization, partitioning, vacuum, connection-pool, configuration]
+quality_score: 94
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-14
+---
+
+# PostgreSQL 生产环境调优手册
+
+> 基于 [Instaclustr Top 15 PostgreSQL Best Practices](https://www.instaclustr.com/education/postgresql/top-10-postgresql-best-practices-for-2025/) + [Mydbops Tuning Guide](https://www.mydbops.com/blog/postgresql-parameter-tuning-best-practices)
+
+## 索引策略
+
+### 索引类型选择
+| 类型 | 场景 | 示例 |
+|------|------|------|
+| B-tree（默认） | 等值/范围/排序 | `WHERE id = 123` / `ORDER BY created_at` |
+| GIN | JSONB/全文/数组 | `WHERE attrs @> '{"color":"red"}'` |
+| GiST | 地理/范围 | `WHERE point <@ box` |
+| BRIN | 大表时间序列 | 百万行日志按时间分区 |
+| Hash | 纯等值 | `WHERE id = 123`（PG 10+ WAL 支持）|
+
+### 复合索引列顺序
+```sql
+-- 最左前缀：等值列在前，范围列在后
+-- 查询: WHERE user_id = ? AND created_at > ?
+CREATE INDEX idx_orders_user_created ON orders(user_id, created_at DESC);
+-- ✅ user_id（等值）在前，created_at（范围）在后
+
+-- ❌ 反过来：created_at 在前无法用 user_id 过滤
+CREATE INDEX idx_orders_bad ON orders(created_at, user_id);
+```
+
+### 部分索引（省空间 + 快）
+```sql
+-- 只索引活跃数据（90% 订单已完成，不需要索引）
+CREATE INDEX idx_active_orders ON orders(user_id) WHERE status = 'pending';
+```
+
+## 查询优化
+
+### EXPLAIN ANALYZE 诊断
+```sql
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT * FROM orders WHERE user_id = 123 ORDER BY created_at DESC LIMIT 20;
+
+-- 看关键指标:
+-- Seq Scan → 全表扫描（需要索引）
+-- Index Scan → 索引扫描（好）
+-- Bitmap Heap Scan → 批量索引（还行）
+-- Sort → 排序（可能需要索引优化）
+-- actual time → 真实耗时（毫秒）
+-- rows → 实际返回行数 vs 预估行数（差异大 = 统计信息过期）
+```
+
+### 大表分页优化
+```sql
+-- ❌ OFFSET 10000 = 扫描 10020 行后丢弃前 10000
+SELECT * FROM products ORDER BY id OFFSET 10000 LIMIT 20;
+
+-- ✅ Keyset 分页 = WHERE 直接定位 20 行
+SELECT * FROM products WHERE id > 5000 ORDER BY id LIMIT 20;
+
+-- ✅ 游标分页（排序复杂时）
+SELECT * FROM products
+WHERE (created_at, id) < ('2024-06-14', 5000)
+ORDER BY created_at DESC, id DESC LIMIT 20;
+```
+
+## 服务器调优
+
+### 关键参数
+```ini
+# postgresql.conf — 按 RAM 调整
+shared_buffers = 4GB          # 总 RAM 的 25%
+effective_cache_size = 12GB   # 总 RAM 的 75%
+work_mem = 64MB               # 排序/哈希内存（注意：每连接×每操作）
+maintenance_work_mem = 1GB    # VACUUM/CREATE INDEX
+max_connections = 100         # 配合连接池用
+
+# WAL（写入日志）
+wal_buffers = 16MB
+checkpoint_completion_target = 0.9
+max_wal_size = 4GB
+
+# Autovacuum（自动清理）
+autovacuum = on
+autovacuum_naptime = 30s
+autovacuum_vacuum_scale_factor = 0.1   # 变更 10% 后触发
+```
+
+### 连接池
+```
+# PgBouncer（必须！直接连数据库会耗尽连接）
+[databases]
+app = host=localhost port=5432 dbname=app
+
+[pgbouncer]
+pool_mode = transaction     # 事务级池化
+max_client_conn = 500       # 客户端连接
+default_pool_size = 25      # 到 PostgreSQL 的连接
+```
+
+## 分区（大表 > 1000 万行）
+
+```sql
+-- 按范围分区（时间序列）
+CREATE TABLE events (
+    id BIGSERIAL,
+    created_at TIMESTAMPTZ NOT NULL,
+    data JSONB
+) PARTITION BY RANGE (created_at);
+
+CREATE TABLE events_2024_06 PARTITION OF events
+    FOR VALUES FROM ('2024-06-01') TO ('2024-07-01');
+
+-- 按列表分区（租户隔离）
+CREATE TABLE orders (
+    id UUID DEFAULT gen_random_uuid(),
+    tenant_id TEXT NOT NULL,
+    ...
+) PARTITION BY LIST (tenant_id);
+
+CREATE TABLE orders_tenant_a PARTITION OF orders
+    FOR VALUES IN ('tenant_a');
+```
+
+## VACUUM 与膨胀
+
+```sql
+-- 检查表膨胀
+SELECT relname, n_live_tup, n_dead_tup,
+       round(n_dead_tup::numeric / NULLIF(n_live_tup, 0) * 100, 2) AS bloat_pct
+FROM pg_stat_user_tables
+WHERE n_live_tup > 10000
+ORDER BY bloat_pct DESC;
+
+-- 膨胀 > 20% 需要处理
+VACUUM (ANALYZE, VERBOSE) orders;  -- 常规清理
+VACUUM FULL orders;                 -- 锁表重建（生产慎用！）
+```

package/database/02-playbooks/redis-caching-playbook.md

@@ -0,0 +1,117 @@
+---
+id: redis-caching-playbook
+title: Redis 缓存实战手册
+domain: database
+category: 02-playbooks
+difficulty: advanced
+tags: [redis, caching, cache-aside, write-through, write-behind, invalidation, ttl, stampede, production, database, performance]
+quality_score: 93
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-15
+---
+
+# Redis 缓存实战手册
+
+> 基于 [AWS Redis Caching Strategies](https://docs.aws.amazon.com/whitepapers/latest/database-caching-strategies-using-redis/caching-patterns.html) + [Azure Cache-Aside Pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/cache-aside) + [Redis Blog](https://redis.io/blog/why-your-caching-strategies-might-be-holding-you-back-and-what-to-consider-next/)
+
+## 四种缓存模式
+
+### 1. Cache-Aside（最常用）
+应用先查缓存，miss 时查 DB 并回填。最终一致（TTL 控制）。
+```python
+def get_user(user_id):
+    cached = redis.get(f"user:{user_id}")
+    if cached:
+        return json.loads(cached)
+    user = db.query(User).get(user_id)
+    redis.setex(f"user:{user_id}", 300, json.dumps(user.to_dict()))  # TTL 5min
+    return user
+```
+
+### 2. Write-Through（强一致）
+写操作同时更新缓存和 DB（同步双写）。
+```python
+def update_user(user_id, data):
+    user = db.update(User, user_id, data)
+    redis.set(f"user:{user_id}", json.dumps(user.to_dict()))  # 同步更新缓存
+    return user
+```
+
+### 3. Write-Behind（高写吞吐）
+先写缓存，异步刷 DB。容忍短暂不一致。
+```python
+def increment_counter(key):
+    redis.incr(key)                    # 先写缓存
+    enqueue_job("persist_counter", key) # 异步刷 DB
+```
+
+### 4. Refresh-Ahead（热数据预热）
+过期前主动刷新。
+```python
+def get_hot_data(key):
+    cached = redis.get(key)
+    ttl = redis.ttl(key)
+    if cached and ttl < 60:  # 快过期了
+        enqueue_job("refresh_cache", key)  # 异步刷新
+    return cached
+```
+
+## 模式选择决策表
+| 场景 | 推荐模式 | 一致性 |
+|------|---------|--------|
+| 读多写少（用户资料/配置） | Cache-Aside | 最终一致 |
+| 写多且需强一致 | Write-Through | 强一致 |
+| 超高写吞吐（计数器/排行） | Write-Behind | 最终一致 |
+| 热点数据不可过期 | Refresh-Ahead | 最新 |
+
+## 缓存失效策略
+
+```python
+# TTL 失效（最简单，推荐基础方案）
+redis.setex(key, 300, value)  # 5 分钟后自动过期
+
+# 主动失效（数据变更时立刻删缓存）
+def update_product(product_id, data):
+    product = db.update(Product, product_id, data)
+    redis.delete(f"product:{product_id}")  # 主动删
+    return product
+
+# 版本化 key（适合批量失效）
+redis.set(f"products:v{version}", data)
+# 版本号+1 → 旧 key 自然过期
+```
+
+## 防缓存击穿（Stampede）
+
+```python
+# ❌ 缓存 miss 时 1000 个请求同时查 DB
+def get_product(pid):
+    cached = redis.get(f"product:{pid}")
+    if not cached:
+        return db.query(Product).get(pid)  # 1000 并发 = DB 爆
+
+# ✅ 互斥锁（singleflight）—— 只让一个请求查 DB
+import fcntl
+def get_product(pid):
+    cached = redis.get(f"product:{pid}")
+    if cached:
+        return json.loads(cached)
+    lock = redis.set(f"lock:product:{pid}", "1", nx=True, ex=10)
+    if lock:
+        product = db.query(Product).get(pid)       # 只有 1 个请求查 DB
+        redis.setex(f"product:{pid}", 300, json.dumps(product.to_dict()))
+        redis.delete(f"lock:product:{pid}")
+        return product
+    else:
+        time.sleep(0.1)                              # 其他请求等一下重试
+        return get_product(pid)
+```
+
+## 生产检查清单
+- [ ] 每个缓存 key 有 TTL（无永久缓存）
+- [ ] 写操作更新/删除缓存（cache-aside + invalidation）
+- [ ] 热点 key 有防击穿（互斥锁/singleflight）
+- [ ] Redis 有降级策略（Redis 挂了仍能服务，直查 DB）
+- [ ] 缓存命中率 > 90%（`INFO stats` 监控）
+- [ ] 内存淘汰策略设置（`maxmemory-policy allkeys-lru`）
+- [ ] 序列化用 JSON/MessagePack（不用 pickle——跨语言 + 安全）

package/database/03-checklists/database-review-checklist.md

@@ -0,0 +1,50 @@
+---
+id: database-review-checklist
+title: 数据库 Schema 审查清单
+domain: database
+category: 03-checklists
+difficulty: intermediate
+tags: [database, sql, postgresql, review, checklist, index, foreign-key, migration, performance, schema]
+quality_score: 89
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-14
+---
+
+# 数据库 Schema 审查清单
+
+## Schema 设计
+- [ ] 每张表有 UUID 主键 (`id UUID PRIMARY KEY DEFAULT gen_random_uuid()`)
+- [ ] 每张表有 `created_at` + `updated_at` (TIMESTAMPTZ NOT NULL DEFAULT now())
+- [ ] 表名复数蛇形 (`users`, `order_items`，不用单数/驼峰/前缀)
+- [ ] 列名蛇形语义清晰 (`assignee_id`，不用缩写)
+- [ ] 软删除用 `deleted_at TIMESTAMPTZ`（可选），不用 `is_deleted BOOLEAN`
+- [ ] 金额用 `NUMERIC(19,2)` 或整数分（不用 FLOAT/REAL）
+- [ ] 状态用 `TEXT + CHECK` 约束（不用 ENUM 类型）
+- [ ] 时间用 `TIMESTAMPTZ`（不用 TIMESTAMP WITHOUT TIME ZONE）
+
+## 外键关系
+- [ ] 每个外键列有显式 `FOREIGN KEY` 约束
+- [ ] ON DELETE 策略明确（CASCADE/SET NULL/RESTRICT）
+- [ ] 自引用关系（如评论树 parent_id）有约束
+- [ ] 外键列有索引（FK 列默认无索引！）
+
+## 索引
+- [ ] 每个 WHERE/JOIN/ORDER BY 的列有索引
+- [ ] 复合索引遵循最左前缀原则
+- [ ] JSONB 列用 GIN 索引
+- [ ] 大表的部分索引（WHERE deleted_at IS NULL）
+- [ ] 没有 unused indexes（`pg_stat_user_indexes` 检查）
+
+## Migration 安全
+- [ ] 新增列有 DEFAULT 值（PG 11+ 不锁表）
+- [ ] 大表加索引用 `CONCURRENTLY`（不锁写）
+- [ ] 删除列分两步：先标弃用 → 下个版本删除
+- [ ] 数据回填脚本幂等（可重跑）
+- [ ] 有 down migration（可回滚）
+
+## 查询安全
+- [ ] 没有 `SELECT *`（只查需要的列）
+- [ ] 没有 N+1 查询（用 JOIN/eager loading）
+- [ ] list 查询有 LIMIT（无上限 = OOM 风险）
+- [ ] 大表 COUNT 用估算（`pg_class.reltuples`）
+- [ ] 参数化查询（防 SQL 注入）

package/database/04-antipatterns/database-antipatterns.md

@@ -0,0 +1,112 @@
+---
+id: database-antipatterns
+title: 数据库设计反模式（避坑指南）
+domain: database
+category: 04-antipatterns
+difficulty: intermediate
+tags: [database, sql, postgresql, antipattern, n-plus-1, eav, premature-optimization, no-index, float-money, enum-type]
+quality_score: 88
+maintainer: platform-team@umadev.com
+last_updated: 2024-06-14
+---
+
+# 数据库设计反模式（避坑指南）
+
+## 1. 用 FLOAT 存金额
+```sql
+-- ❌ 浮点丢精度
+price FLOAT  -- 0.1 + 0.2 = 0.30000000000000004
+
+-- ✅ 定点数或整数分
+price NUMERIC(19,2)    -- 精确
+price_cents INTEGER    -- 整数，绝对精确
+```
+
+## 2. EAV（实体-属性-值）反模式
+```sql
+-- ❌ 万能表（查询噩梦，无类型安全）
+CREATE TABLE attributes (
+    entity_id UUID,
+    attribute_name TEXT,
+    attribute_value TEXT
+);
+
+-- ✅ 显式列 + JSONB 补充
+CREATE TABLE products (
+    id UUID PRIMARY KEY,
+    name TEXT NOT NULL,
+    price_cents INTEGER NOT NULL,
+    extra_attrs JSONB DEFAULT '{}'  -- 灵活字段用 JSONB + GIN
+);
+```
+
+## 3. N+1 查询
+```python
+# ❌ 循环内查子资源（100 用户 = 101 次查询）
+for user in users:
+    user.orders = db.query("SELECT * FROM orders WHERE user_id = ?", user.id)
+
+# ✅ 批量查 + 内存关联（100 用户 = 2 次查询）
+orders = db.query("SELECT * FROM orders WHERE user_id IN ?", [u.id for u in users])
+# 或 ORM eager loading
+users = db.query(User).options(selectinload(User.orders)).all()
+```
+
+## 4. 无索引的外键
+```sql
+-- ❌ FK 约束创建后，默认无索引！JOIN/WHERE 会全表扫描
+ALTER TABLE orders ADD CONSTRAINT fk_orders_users FOREIGN KEY (user_id) REFERENCES users(id);
+-- 忘了建索引！
+
+-- ✅ 每个 FK 列必须有索引
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+```
+
+## 5. ENUM 类型（不灵活）
+```sql
+-- ❌ ENUM 加值需要 ALTER TYPE（锁表）
+CREATE TYPE order_status AS ENUM ('pending', 'paid');
+
+-- ✅ TEXT + CHECK（加值只需改约束）
+status TEXT NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'paid', 'shipped', 'cancelled'))
+```
+
+## 6. 不带 LIMIT 的查询
+```sql
+-- ❌ 全表扫描（10 万行 OOM）
+SELECT * FROM events ORDER BY created_at DESC;
+
+-- ✅ 强制分页
+SELECT * FROM events ORDER BY created_at DESC LIMIT 100;
+```
+
+## 7. 过度规范化（过度拆表）
+```sql
+-- ❌ 把 email 拆到单独表（每次查用户都要 JOIN）
+CREATE TABLE user_emails (user_id UUID, email TEXT);
+
+-- ✅ 高频字段内联，只有多值/大字段才拆表
+CREATE TABLE users (id UUID, email TEXT, name TEXT, ...);
+```
+
+## 8. 同步锁表 Migration
+```sql
+-- ❌ 生产环境直接加索引（锁写操作）
+CREATE INDEX idx_big_table_col ON big_table(col);
+
+-- ✅ 并发建索引（不锁写）
+CREATE INDEX CONCURRENTLY idx_big_table_col ON big_table(col);
+```
+
+## 9. 不用事务
+```python
+# ❌ 转账操作不在事务里（可能转出成功转入失败）
+db.execute("UPDATE accounts SET balance -= 100 WHERE id = ?", from_id)
+db.execute("UPDATE accounts SET balance += 100 WHERE id = ?", to_id)  # 如果这步崩了？
+
+# ✅ 事务包裹
+with db.transaction():
+    db.execute("UPDATE accounts SET balance -= 100 WHERE id = ?", from_id)
+    db.execute("UPDATE accounts SET balance += 100 WHERE id = ?", to_id)
+```