litestream-coder

Litestream Coder

概述

Litestream 可将 SQLite 数据库持续流式备份到兼容 S3 的存储中。对于在生产环境中使用 SQLite，并搭配 Solid Queue、Solid Cache 和 Solid Cable 的 Rails 8+ 应用来说，这是必不可少的。

配置文件

创建 config/litestream.yml：

dbs:
  - path: /rails/storage/production.sqlite3
    replicas:
      - type: s3
        bucket: ${BUCKET_NAME}
        path: sqlite/production
        endpoint: ${S3_ENDPOINT}
        region: ${S3_REGION}
        access-key-id: ${LITESTREAM_ACCESS_KEY_ID}
        secret-access-key: ${LITESTREAM_SECRET_ACCESS_KEY}
        force-path-style: true       # Required for S3-compatible storage
        sync-interval: 5s            # How often to sync WAL
        snapshot-interval: 1h        # Full snapshot frequency
        retention: 168h              # 7 days
        retention-check-interval: 1h
        validation-interval: 12h

按数据库类型设置保留策略

主数据库（production.sqlite3）：

• sync-interval: 5s - 频繁同步，确保数据持久性
• snapshot-interval: 1h - 每小时创建快照
• retention: 720h - 保留 30 天以便恢复

缓存数据库（production_cache.sqlite3）：

• sync-interval: 10s - 重要性较低，可减少负载
• snapshot-interval: 6h - 降低快照频率
• retention: 24h - 保留 1 天即可

队列数据库（production_queue.sqlite3）：

• sync-interval: 5s - 对确保作业持久性很重要
• snapshot-interval: 1h - 每小时创建快照
• retention: 72h - 保留 3 天以便调试

Cable 数据库（production_cable.sqlite3）：

• sync-interval: 10s - 数据是临时性的
• snapshot-interval: 6h - 降低快照频率
• retention: 24h - 保留 1 天

完整配置示例

dbs:
  - path: /rails/storage/production.sqlite3
    replicas:
      - type: s3
        bucket: myapp-backups
        path: sqlite/production
        endpoint: https://fsn1.your-objectstorage.com
        region: fsn1
        access-key-id: ${LITESTREAM_ACCESS_KEY_ID}
        secret-access-key: ${LITESTREAM_SECRET_ACCESS_KEY}
        force-path-style: true
        sync-interval: 5s
        snapshot-interval: 1h
        retention: 720h
        retention-check-interval: 1h
        validation-interval: 12h

  - path: /rails/storage/production_cache.sqlite3
    replicas:
      - type: s3
        bucket: myapp-backups
        path: sqlite/cache
        endpoint: https://fsn1.your-objectstorage.com
        region: fsn1
        access-key-id: ${LITESTREAM_ACCESS_KEY_ID}
        secret-access-key: ${LITESTREAM_SECRET_ACCESS_KEY}
        force-path-style: true
        sync-interval: 10s
        snapshot-interval: 6h
        retention: 24h

  - path: /rails/storage/production_queue.sqlite3
    replicas:
      - type: s3
        bucket: myapp-backups
        path: sqlite/queue
        endpoint: https://fsn1.your-objectstorage.com
        region: fsn1
        access-key-id: ${LITESTREAM_ACCESS_KEY_ID}
        secret-access-key: ${LITESTREAM_SECRET_ACCESS_KEY}
        force-path-style: true
        sync-interval: 5s
        snapshot-interval: 1h
        retention: 72h

  - path: /rails/storage/production_cable.sqlite3
    replicas:
      - type: s3
        bucket: myapp-backups
        path: sqlite/cable
        endpoint: https://fsn1.your-objectstorage.com
        region: fsn1
        access-key-id: ${LITESTREAM_ACCESS_KEY_ID}
        secret-access-key: ${LITESTREAM_SECRET_ACCESS_KEY}
        force-path-style: true
        sync-interval: 10s
        snapshot-interval: 6h
        retention: 24h

使用 Kamal 2 部署

在 config/deploy.yml 中将 Litestream 添加为辅助服务：

accessories:
  litestream:
    image: litestream/litestream:0.3
    host: <SERVER_IP>
    cmd: replicate
    volumes:
      - "myapp_storage:/rails/storage:ro"  # Read-only access
    files:
      - config/litestream.yml:/etc/litestream.yml
    env:
      secret:
        - LITESTREAM_ACCESS_KEY_ID
        - LITESTREAM_SECRET_ACCESS_KEY
    options:
      health-cmd: "litestream databases || exit 1"
      health-interval: 30s
      health-timeout: 5s
      health-retries: 3

要点：

• 将存储挂载为只读（:ro）——Litestream 只读取 WAL 文件
• 使用与主应用相同的卷名称
• 健康检查会验证 Litestream 能否访问数据库

密钥配置

在 .kamal/secrets 中：

LITESTREAM_ACCESS_KEY_ID=$(op read "op://myproject/production-s3/access_key_id")
LITESTREAM_SECRET_ACCESS_KEY=$(op read "op://myproject/production-s3/secret_access_key")

灾难恢复

恢复数据库

# Stop application first
kamal app stop

# Restore from latest backup
docker run --rm \
  -v myapp_storage:/rails/storage \
  -e LITESTREAM_ACCESS_KEY_ID="$(op read 'op://myproject/production-s3/access_key_id')" \
  -e LITESTREAM_SECRET_ACCESS_KEY="$(op read 'op://myproject/production-s3/secret_access_key')" \
  litestream/litestream:0.3 restore \
  -config /etc/litestream.yml \
  /rails/storage/production.sqlite3

# Restart application
kamal app start

时间点恢复

docker run --rm \
  -v myapp_storage:/rails/storage \
  -e LITESTREAM_ACCESS_KEY_ID="..." \
  -e LITESTREAM_SECRET_ACCESS_KEY="..." \
  litestream/litestream:0.3 restore \
  -config /etc/litestream.yml \
  -timestamp "2025-01-15T10:30:00Z" \
  /rails/storage/production.sqlite3

监控

检查备份状态：

# Via Kamal
kamal accessory exec litestream -- litestream databases

# Direct on server
docker exec myapp-litestream litestream databases

兼容 S3 的存储

Litestream 可与任何兼容 S3 的存储搭配使用：

提供商	端点示例
Hetzner 对象存储	https://fsn1.your-objectstorage.com
Backblaze B2	https://s3.us-west-002.backblazeb2.com
DigitalOcean Spaces	https://nyc3.digitaloceanspaces.com
AWS S3	（省略端点，使用区域）

重要： 对于非 AWS 的兼容 S3 存储，务必设置 force-path-style: true。

VACUUM 对 Litestream 的影响

完整的 VACUUM 会重写整个数据库文件。Litestream 会将其检测为整体变更，并触发上传一个完整快照（而非增量 WAL 同步）。

运维注意事项：

• 在保留期限内，旧快照和新快照都会保留，因此 VACUUM 会暂时增加备份存储用量
• 在不同数据库上错开执行 VACUUM，以避免带宽峰值：主数据库在 3:00，缓存数据库在 3:15，队列数据库在 3:30
• 这是预期行为，也是安全的——不要为了避免创建快照而禁用 VACUUM
• VACUUM 后使用 litestream databases 进行监控，确认快照已完成

有关 VACUUM 调度策略，请参阅 resources/database-admin/sqlite.md。

最佳实践

• 根据保留需求拆分数据库 - 主数据库需要比缓存更长的保留期限
• 监控备份延迟 - litestream databases 会显示复制状态
• 定期测试恢复 - 不要等到发生灾难时才验证备份是否可用
• 使用只读挂载 - Litestream 只读取 WAL 文件，:ro 可防止意外操作
• 错开 VACUUM 操作 - 避免多个数据库同时创建完整快照