SpacetimeDB 深度实战：当数据库就是服务器——从「零基础设施」架构到生产级实时应用完全指南（2026）

引言：一场后端架构的范式革命

你有没有想过，为什么我们写一个实时应用需要这么多基础设施？Web 服务器、应用服务器、数据库、缓存、消息队列、WebSocket 网关、容器编排、Kubernetes 集群……一个简单的多人聊天室，光部署就要折腾三天。

2026 年，一个叫 SpacetimeDB 的开源项目正在颠覆这一切。它的核心理念极其大胆：数据库就是服务器。你把业务逻辑直接写进数据库模块，客户端直连数据库，中间没有任何服务器。没有 Web 框架，没有容器，没有 DevOps，没有缓存层——因为你所有的数据本来就在内存里。

这不是玩具项目。Clockwork Labs 用 SpacetimeDB 构建了他们的 MMORPG BitCraft Online——整个后端，包括聊天、物品系统、地形、玩家位置，全部作为一个 SpacetimeDB 模块运行，实时同步给数千名玩家。

GitHub 上 2 万+ Star，3400+ 次提交，支持 Rust、C#、TypeScript、C++ 四种语言编写模块，客户端 SDK 覆盖 React/Next.js/Vue/Svelte/Angular/Node.js/Bun/Deno/Unity/Unreal Engine——这不是 MVP，这是生产级基础设施。

今天我们就来深入拆解 SpacetimeDB 的架构原理、核心概念、代码实战和性能调优，让你真正理解「数据库即服务器」到底意味着什么。

一、架构革命：为什么「数据库即服务器」可行？

1.1 传统架构的痛点

一个典型的实时应用后端架构长这样：

客户端 → CDN → 负载均衡 → Web 服务器 → 应用服务器 → 缓存(Redis) → 数据库
                ↓
           WebSocket 网关 → 消息队列 → 消费者 → 数据库

这个架构的问题显而易见：

• 延迟叠加：每一层都是一次网络跳转，数据从数据库到客户端至少经过 4-5 跳
• 状态同步复杂：数据库 → 缓存 → 应用内存 → 客户端，四份状态要保证一致
• 运维成本爆炸：每个组件都要监控、扩容、故障恢复
• 开发效率低：改一个字段，ORM、API、客户端类型定义全部要改

1.2 SpacetimeDB 的极简架构

客户端 ←→ SpacetimeDB（数据库 + 业务逻辑 + 实时推送）

就这么简单。SpacetimeDB 把数据库和应用服务器的功能合二为一：

1. 应用逻辑在数据库内运行：你写的模块代码被编译成 WASM，直接在数据库进程内执行
2. 全内存存储：所有数据驻留内存，纳秒级访问，同时通过 commit log 保证持久性
3. 自动实时同步：客户端通过订阅（Subscription）获取数据，变更自动推送，无需轮询

关键洞察：传统架构中，应用服务器 90% 的时间在做的事情就是——从数据库读数据、转换格式、推给客户端。SpacetimeDB 说：那为什么不直接让客户端连数据库？

1.3 但这不是「直接暴露数据库」

听到「客户端直连数据库」，你的第一反应可能是：这不安全！

SpacetimeDB 的模块不是裸 SQL 接口。你在模块里定义的 Reducer（归约器）就是你的 API 端点——它们和传统的 REST/GraphQL 端点扮演同样的角色。你可以在 Reducer 里写权限检查、数据校验、业务规则，就像在传统服务器里一样。

// 只有本人可以更新自己的位置
#[spacetimedb::reducer]
pub fn move_player(ctx: &ReducerContext, x: f32, y: f32) {
    let player = ctx.db.player().identity().find(&ctx.sender);
    match player {
        Some(mut p) => {
            p.x = x;
            p.y = y;
            ctx.db.player().identity().update(p);
        }
        None => log::warn!("未认证的移动请求"),
    }
}

客户端不能直接执行 SQL，只能调用你暴露的 Reducer。权限逻辑、数据校验全部在模块内完成——这和传统服务器的安全模型完全等价。

二、核心概念深度解析

2.1 Tables（表）：数据即真理

SpacetimeDB 中的表不仅仅是存储——它是整个应用状态的唯一真相来源。所有状态必须存在表里，不允许使用全局变量或静态变量来跨 Reducer 传递状态。

这不是限制，而是设计哲学。为什么？

1. 热更新安全：发布新模块时，SpacetimeDB 会创建全新的执行环境，全局变量不会迁移
2. 崩溃恢复：进程重启后，只有表中的数据能恢复
3. 并发安全：未来 MVCC 实现中，多个 Reducer 可能并发执行，全局变量的行为不可预测
4. 重放安全：如果检测到可串行化异常，SpacetimeDB 可能用相同参数重新执行 Reducer

表的定义（Rust）：

#[spacetimedb::table(accessor = player, public)]
pub struct Player {
    #[primary_key]
    identity: Identity,
    name: String,
    x: f32,
    y: f32,
    health: u32,
    level: u32,
}

表的定义（TypeScript）：

import { schema, table, t } from 'spacetimedb/server';

const player = table(
  { name: 'player', public: true },
  {
    identity: t.Identity.primaryKey(),
    name: t.string(),
    x: t.f32(),
    y: t.f32(),
    health: t.u32(),
    level: t.u32(),
  }
);

const spacetimedb = schema({ player });
export default spacetimedb;

2.2 表分解的艺术：按访问模式组织数据

这是 SpacetimeDB 文档中最精彩的设计建议，值得深入理解。

传统 SQL 开发倾向于把相关数据塞进一张宽表（因为 JOIN 有性能开销）。但 SpacetimeDB 的全内存架构改变了游戏规则——索引查找是纳秒级的，join 的成本接近于零。

因此，SpacetimeDB 推荐按访问模式而不是实体归属来拆表：

反面例子（合并大表）：

Player
├── id
├── name
├── position_x, position_y, velocity_x, velocity_y  (60Hz 更新)
├── health, max_health, mana, max_mana               (偶尔更新)
├── total_kills, total_deaths, play_time             (罕见更新)
└── audio_volume, graphics_quality                   (极少更新)

正面例子（按频率拆表）：

Player          PlayerState         PlayerStats         PlayerSettings
├── id    ←──   ├── player_id       ├── player_id       ├── player_id
└── name        ├── position_x      ├── total_kills     └── audio_volume
                ├── position_y      ├── total_deaths
                ├── velocity_x      └── play_time
                └── velocity_y

PlayerResources
├── player_id
├── health
├── max_health
├── mana
└── max_mana

为什么这很重要？三个原因：

带宽优化：客户端订阅玩家位置时，不需要接收设置变更。1000 个玩家以 60Hz 更新位置，带宽差异是巨大的。

缓存效率：相同更新频率的数据在内存中连续排列。更新位置时不会加载/失效包含统计数据的缓存行。

语义清晰：每张表单一职责。PlayerState 处理性能关键的游戏循环，PlayerStats 服务排行榜查询，PlayerSettings 支持选项界面。

2.3 Reducers（归约器）：你的 API 端点

Reducer 是 SpacetimeDB 中唯一修改数据的方式。每个 Reducer 运行在一个数据库事务中，提供：

• 隔离性：Reducer 看不到其他并发 Reducer 的变更
• 原子性：要么全部成功，要么全部回滚
• 一致性：失败的 Reducer 不会留下部分变更

Rust 定义 Reducer：

#[spacetimedb::reducer]
pub fn send_message(ctx: &ReducerContext, text: String) {
    // 输入校验
    if text.is_empty() {
        log::warn!("空消息，忽略");
        return;
    }
    if text.len() > 500 {
        log::warn!("消息过长，截断");
        return;
    }

    // 插入消息
    ctx.db.messages().insert(Message {
        id: 0, // auto_inc 自动赋值
        sender: ctx.sender,
        text,
        timestamp: ctx.timestamp.into(),
    });
}

TypeScript 定义 Reducer：

export const send_message = spacetimedb.reducer(
  { text: t.string() },
  (ctx, { text }) => {
    if (text === '') {
      throw new Error('消息不能为空');
    }
    ctx.db.messages.insert({
      id: 0n,
      sender: ctx.sender,
      text,
      timestamp: ctx.timestamp,
    });
  }
);

关键限制：Reducer 是纯函数

Reducer 不能做这些事：

• ❌ 网络请求
• ❌ 文件系统访问
• ❌ 系统调用
• ✅ 只能操作数据库表

这是为了保证事务语义。如果你需要外部调用，用 Procedure（后面讲）。

2.4 Procedures（过程）：有副作用的操作

Procedure 是 SpacetimeDB 中与外部世界交互的通道。它们可以发起 HTTP 请求、访问文件系统，但有不同的事务语义。

// 定义一个 Procedure 来调用外部 API
export const fetch_weather = spacetimedb.procedure(
  { arg: fetchSchedule.rowType },
  t.unit(),
  (ctx, { arg }) => {
    const response = ctx.http.fetch(arg.url);
    // 处理响应...
    return {};
  }
);

从 Reducer 调度 Procedure：Reducer 不能直接调用 Procedure（因为事务语义不兼容），但可以通过 Schedule Table 来调度：

const fetchSchedule = table(
  { name: 'fetch_schedule', scheduled: (): any => fetch_weather },
  {
    scheduled_id: t.u64().primaryKey().autoInc(),
    scheduled_at: t.scheduleAt(),
    url: t.string(),
  }
);

// 在 Reducer 中调度
export const queueFetch = spacetimedb.reducer(
  { url: t.string() },
  (ctx, { url }) => {
    ctx.db.fetchSchedule.insert({
      scheduled_id: 0n,
      scheduled_at: ScheduleAt.interval(0n), // 立即执行
      url,
    });
  }
);

这个设计非常巧妙——它保持了 Reducer 的事务纯性，同时通过调度表提供异步外部交互能力。

2.5 Subscriptions（订阅）：实时数据的生命线

订阅是 SpacetimeDB 最强大的功能。客户端订阅查询，服务端立即推送匹配的行，之后任何变更都实时推送。

客户端订阅（TypeScript）：

import { DbConnection, tables } from './module_bindings';

const conn = DbConnection.builder()
  .withUri('wss://maincloud.spacetimedb.com')
  .withDatabaseName('my_game')
  .onConnect((ctx) => {
    ctx.subscriptionBuilder()
      .onApplied(() => {
        console.log('订阅就绪！');
        for (const player of ctx.db.player.iter()) {
          console.log(`在线玩家: ${player.name}`);
        }
      })
      .subscribe([tables.player, tables.message]);
  })
  .build();

// 响应数据变更
conn.db.player.onInsert((ctx, player) => {
  console.log(`${player.name} 加入了游戏`);
});

conn.db.player.onDelete((ctx, player) => {
  console.log(`${player.name} 离开了游戏`);
});

conn.db.player.onUpdate((ctx, oldPlayer, newPlayer) => {
  console.log(`${oldPlayer.name} 位置: (${newPlayer.x}, ${newPlayer.y})`);
});

条件订阅——只看自己关心的数据：

// 只订阅附近玩家的位置
ctx.subscriptionBuilder()
  .subscribe([
    tables.playerState.where(r => 
      r.x.gte(myX - 100).and(r.x.lte(myX + 100))
         .and(r.y.gte(myY - 100)).and(r.y.lte(myY + 100))
    ),
  ]);

订阅的最佳实践：

1. 按生命周期分组订阅：全局数据（公告、配置）和临时数据（商店、附近玩家）分成两组订阅，避免不必要的取消/重订阅
2. 先订阅再取消：更新订阅时，先订阅新的，再取消旧的。SpacetimeDB 的订阅是零拷贝的，重叠部分不会重复处理
3. 避免重叠查询：tables.user 和 tables.user.where(r => r.id.ne(5)) 会导致大量行被处理和序列化两次

三、代码实战：构建一个实时协作白板

理论讲完了，让我们动手构建一个完整的应用——实时协作白板。多个用户可以同时画线、添加文本、移动元素，所有变更实时同步。

3.1 项目初始化

# 安装 SpacetimeDB CLI
curl -sSf https://install.spacetimedb.com | sh

# 登录
spacetime login

# 创建项目（使用 TypeScript 模板）
spacetime dev --template chat-react-ts my-whiteboard
cd my-whiteboard

3.2 定义数据模型（Rust 模块）

// server/src/lib.rs
use spacetimedb::reducer;
use spacetimedb::table;
use spacetimedb::Identity;

/// 白板元素 - 所有可视元素的基表
#[table(accessor = elements, public)]
pub struct Element {
    #[primary_key]
    #[auto_inc]
    id: u64,
    /// 创建者
    owner: Identity,
    /// 元素类型：0=线条, 1=文本, 2=矩形, 3=圆形
    element_type: u8,
    /// 画布 ID
    canvas_id: String,
    /// 层级（z-index）
    z_index: i32,
    /// 创建时间
    created_at: u64,
    /// 最后更新时间
    updated_at: u64,
}

/// 线条数据
#[table(accessor = lines, public)]
pub struct Line {
    #[primary_key]
    element_id: u64,
    /// 点序列，编码为 "x1,y1;x2,y2;..."
    points: String,
    /// 颜色，如 "#FF5500"
    color: String,
    /// 线宽
    width: f32,
}

/// 文本数据
#[table(accessor = texts, public)]
pub struct Text {
    #[primary_key]
    element_id: u64,
    content: String,
    x: f64,
    y: f64,
    font_size: f32,
    color: String,
}

/// 矩形数据
#[table(accessor = rectangles, public)]
pub struct Rectangle {
    #[primary_key]
    element_id: u64,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
    fill_color: String,
    stroke_color: String,
}

/// 用户光标位置（高频更新，单独拆表）
#[table(accessor = cursors, public)]
pub struct Cursor {
    #[primary_key]
    identity: Identity,
    name: String,
    x: f64,
    y: f64,
    color: String,
    /// 最后活跃时间
    last_active: u64,
}

/// 画布元数据（低频更新）
#[table(accessor = canvases, public)]
pub struct Canvas {
    #[primary_key]
    #[auto_inc]
    id: u64,
    name: String,
    owner: Identity,
    width: f64,
    height: f64,
    background: String,
}

/// 用户会话（用于在线状态管理）
#[table(accessor = sessions)]
pub struct Session {
    #[primary_key]
    identity: Identity,
    name: String,
    canvas_id: String,
    connected_at: u64,
}

注意我们严格遵循了表分解原则：

• Element 存通用元数据（低频更新）
• Cursor 存光标位置（60Hz 高频更新）
• Canvas 存画布配置（极低频更新）
• Session 是私有表，只给模块内部用

3.3 实现 Reducer

/// 用户连接时初始化
#[reducer]
pub fn connect(ctx: &ReducerContext) {
    // 在 Session 表中记录用户上线
    ctx.db.sessions().insert(Session {
        identity: ctx.sender,
        name: String::new(), // 稍后通过 set_name 设置
        canvas_id: "default".to_string(),
        connected_at: ctx.timestamp.to_micros_since_epoch(),
    });

    // 初始化光标
    ctx.db.cursors().insert(Cursor {
        identity: ctx.sender,
        name: String::new(),
        x: 0.0,
        y: 0.0,
        color: random_cursor_color(&ctx.sender),
        last_active: ctx.timestamp.to_micros_since_epoch(),
    });
}

/// 用户断开时清理
#[reducer]
pub fn disconnect(ctx: &ReducerContext) {
    ctx.db.sessions().identity().delete(&ctx.sender);
    ctx.db.cursors().identity().delete(&ctx.sender);
}

/// 设置用户名
#[reducer]
pub fn set_name(ctx: &ReducerContext, name: String) {
    if name.is_empty() || name.len() > 32 {
        return;
    }

    if let Some(mut session) = ctx.db.sessions().identity().find(&ctx.sender) {
        session.name = name.clone();
        ctx.db.sessions().identity().update(session);
    }

    if let Some(mut cursor) = ctx.db.cursors().identity().find(&ctx.sender) {
        cursor.name = name;
        ctx.db.cursors().identity().update(cursor);
    }
}

/// 移动光标（高频调用，保证轻量）
#[reducer]
pub fn move_cursor(ctx: &ReducerContext, x: f64, y: f64) {
    if let Some(mut cursor) = ctx.db.cursors().identity().find(&ctx.sender) {
        cursor.x = x;
        cursor.y = y;
        cursor.last_active = ctx.timestamp.to_micros_since_epoch();
        ctx.db.cursors().identity().update(cursor);
    }
}

/// 创建线条元素
#[reducer]
pub fn create_line(ctx: &ReducerContext, canvas_id: String, points: String, color: String, width: f32) {
    // 校验
    if points.is_empty() || color.is_empty() {
        return;
    }

    let now = ctx.timestamp.to_micros_since_epoch();

    // 插入基础元素
    let element_id = ctx.db.elements().insert(Element {
        id: 0, // auto_inc
        owner: ctx.sender,
        element_type: 0, // 线条
        canvas_id,
        z_index: 0,
        created_at: now,
        updated_at: now,
    }).id;

    // 插入线条数据
    ctx.db.lines().insert(Line {
        element_id,
        points,
        color,
        width,
    });
}

/// 创建文本元素
#[reducer]
pub fn create_text(
    ctx: &ReducerContext,
    canvas_id: String,
    content: String,
    x: f64,
    y: f64,
    font_size: f32,
    color: String,
) {
    if content.is_empty() || content.len() > 10000 {
        return;
    }

    let now = ctx.timestamp.to_micros_since_epoch();

    let element_id = ctx.db.elements().insert(Element {
        id: 0,
        owner: ctx.sender,
        element_type: 1,
        canvas_id,
        z_index: 0,
        created_at: now,
        updated_at: now,
    }).id;

    ctx.db.texts().insert(Text {
        element_id,
        content,
        x,
        y,
        font_size,
        color,
    });
}

/// 创建矩形
#[reducer]
pub fn create_rectangle(
    ctx: &ReducerContext,
    canvas_id: String,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
    fill_color: String,
    stroke_color: String,
) {
    let now = ctx.timestamp.to_micros_since_epoch();

    let element_id = ctx.db.elements().insert(Element {
        id: 0,
        owner: ctx.sender,
        element_type: 2,
        canvas_id,
        z_index: 0,
        created_at: now,
        updated_at: now,
    }).id;

    ctx.db.rectangles().insert(Rectangle {
        element_id,
        x,
        y,
        width,
        height,
        fill_color,
        stroke_color,
    });
}

/// 删除元素（只有创建者可以删除）
#[reducer]
pub fn delete_element(ctx: &ReducerContext, element_id: u64) {
    if let Some(element) = ctx.db.elements().id().find(element_id) {
        if element.owner != ctx.sender {
            log::warn!("非元素所有者尝试删除");
            return;
        }

        // 删除关联的子表数据
        match element.element_type {
            0 => { ctx.db.lines().element_id().delete(&element_id); }
            1 => { ctx.db.texts().element_id().delete(&element_id); }
            2 => { ctx.db.rectangles().element_id().delete(&element_id); }
            _ => {}
        }

        // 删除元素本身
        ctx.db.elements().id().delete(&element_id);
    }
}

/// 生成随机光标颜色（基于 Identity 的简单哈希）
fn random_cursor_color(identity: &Identity) -> String {
    let bytes = identity.to_byte_array();
    let r = (bytes[0] as u16 + 100) % 256;
    let g = (bytes[1] as u16 + 100) % 256;
    let b = (bytes[2] as u16 + 100) % 256;
    format!("#{:02X}{:02X}{:02X}", r, g, b)
}

3.4 客户端实现（React + TypeScript）

// client/src/App.tsx
import { DbConnection, tables } from './module_bindings';
import { useEffect, useState, useRef, useCallback } from 'react';

function App() {
  const [connection, setConnection] = useState<DbConnection | null>(null);
  const [elements, setElements] = useState<any[]>([]);
  const [cursors, setCursors] = useState<Map<string, any>>(new Map());
  const [myName, setMyName] = useState('');
  const canvasRef = useRef<HTMLCanvasElement>(null);

  // 连接 SpacetimeDB
  useEffect(() => {
    const conn = DbConnection.builder()
      .withUri('wss://maincloud.spacetimedb.com')
      .withDatabaseName('whiteboard')
      .onConnect((ctx) => {
        // 订阅当前画布的所有数据
        ctx.subscriptionBuilder()
          .onApplied(() => {
            console.log('白板数据就绪');
            // 初始化本地状态
            const allElements = Array.from(ctx.db.elements.iter());
            setElements(allElements);
          })
          .subscribe([
            tables.elements,
            tables.lines,
            tables.texts,
            tables.rectangles,
            tables.cursors,
            tables.canvases,
          ]);
      })
      .build();

    // 监听元素变更
    conn.db.elements.onInsert((ctx, element) => {
      setElements(prev => [...prev, element]);
    });

    conn.db.elements.onDelete((ctx, element) => {
      setElements(prev => prev.filter(e => e.id !== element.id));
    });

    // 监听光标移动
    conn.db.cursors.onInsert((ctx, cursor) => {
      setCursors(prev => new Map(prev).set(cursor.identity.toHexString(), cursor));
    });

    conn.db.cursors.onUpdate((ctx, oldCursor, newCursor) => {
      setCursors(prev => new Map(prev).set(newCursor.identity.toHexString(), newCursor));
    });

    conn.db.cursors.onDelete((ctx, cursor) => {
      setCursors(prev => {
        const next = new Map(prev);
        next.delete(cursor.identity.toHexString());
        return next;
      });
    });

    setConnection(conn);
    return () => conn.disconnect();
  }, []);

  // 画布鼠标移动 → 更新光标
  const handleMouseMove = useCallback((e: React.MouseEvent<HTMLCanvasElement>) => {
    if (!connection) return;
    const canvas = canvasRef.current;
    if (!canvas) return;
    const rect = canvas.getBoundingClientRect();
    const x = e.clientX - rect.left;
    const y = e.clientY - rect.top;
    connection.reducers.moveCursor(x, y);
  }, [connection]);

  // 画线
  const handleDrawLine = useCallback((points: string, color: string) => {
    if (!connection) return;
    connection.reducers.createLine('default', points, color, 2.0);
  }, [connection]);

  return (
    <div className="whiteboard-app">
      <div className="toolbar">
        <input
          value={myName}
          onChange={(e) => {
            setMyName(e.target.value);
            connection?.reducers.setName(e.target.value);
          }}
          placeholder="输入你的名字"
        />
      </div>
      <canvas
        ref={canvasRef}
        onMouseMove={handleMouseMove}
        width={1200}
        height={800}
        className="whiteboard-canvas"
      />
      {/* 渲染其他用户的光标 */}
      {Array.from(cursors.entries()).map(([id, cursor]) => (
        <div
          key={id}
          className="remote-cursor"
          style={{
            left: cursor.x,
            top: cursor.y,
            borderColor: cursor.color,
          }}
        >
          <div className="cursor-pointer" style={{ color: cursor.color }}>▶</div>
          <div className="cursor-label" style={{ background: cursor.color }}>
            {cursor.name || '匿名'}
          </div>
        </div>
      ))}
    </div>
  );
}

export default App;

3.5 部署

# 发布到 SpacetimeDB 云（Maincloud）
spacetime publish whiteboard --project-path ./server

# 或者用 Docker 自托管
docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start

# 本地开发模式（自动热重载）
spacetime dev --project-path ./server

四、架构深度剖析：SpacetimeDB 是怎么做到这么快的？

4.1 全内存 + Commit Log：鱼和熊掌兼得

SpacetimeDB 的存储模型是全内存的——所有数据都驻留在内存中，表查找是纳秒级的。但这并不意味着数据不安全。

持久化通过 Commit Log 实现：

• 每次 Reducer 执行完毕，变更被追加写入磁盘的 commit log
• 崩溃恢复时，从头回放 commit log 重建内存状态
• 这和传统数据库的 WAL（Write-Ahead Log）原理类似，但更简单——因为没有磁盘读操作

这意味着：

• 读取：纯内存，纳秒级
• 写入：内存写入 + 异步刷盘，微秒级
• 崩溃恢复：回放日志，秒级

4.2 自定义二进制协议：减少序列化开销

SpacetimeDB 没有使用 JSON 或 gRPC，而是设计了自己的二进制序列化协议（SATe 文档中称为 SpacetimeDB Algebraic Type System）。这带来几个好处：

1. 更小的消息体积：二进制比 JSON 紧凑 3-10 倍
2. 更快的序列化/反序列化：无需文本解析，直接内存映射
3. 类型安全：编译时生成类型绑定，运行时零拷贝

客户端 SDK 自动生成的类型绑定保证编译时类型安全，无需手写任何序列化代码。

4.3 订阅引擎：增量推送的魔法

SpacetimeDB 的订阅系统是它性能的关键。传统实时架构的痛点在于推送——你需要自己维护「谁关心什么数据」。

SpacetimeDB 的订阅引擎：

1. 声明式订阅：客户端用查询声明感兴趣的数据
2. 增量推送：数据变更时，只推送变更的行（insert/delete/update），不重发全量
3. 零拷贝去重：同一行被多个订阅匹配时，只序列化一次
4. 条件推送：只有匹配订阅条件的变更才会推送给对应客户端

这意味着 1000 个玩家在一个游戏里，每个人只收到自己视野范围内的数据，服务端不会傻乎乎地把所有人的位置推给所有人。

4.4 WASM 沙箱：安全执行用户代码

你的模块代码被编译成 WASM 在数据库内运行。WASM 沙箱提供了：

• 内存隔离：模块不能访问数据库进程的原始内存
• 能力限制：模块不能发起网络请求、访问文件系统（Reducer 模式下）
• 资源控制：可以限制 CPU 和内存使用
• 热更新：发布新模块时，可以热替换 WASM 代码，不影响在线客户端

SpacetimeDB 支持 Rust 和 C# 直接编译到 WASM，TypeScript 通过 V8 引擎运行，C++ 通过 Emscripten 编译。

五、性能优化实战

5.1 索引策略

SpacetimeDB 支持 BTree 索引。在内存数据库中，索引的意义不是减少磁盘 IO，而是减少比较次数和 CPU 缓存缺失。

#[table(accessor = elements, public)]
pub struct Element {
    #[primary_key]
    #[auto_inc]
    id: u64,
    owner: Identity,
    element_type: u8,
    #[index(btree)]  // 按画布 ID 索引，加速订阅过滤
    canvas_id: String,
    z_index: i32,
    created_at: u64,
    updated_at: u64,
}

什么时候加索引？

• 订阅查询中频繁过滤的列
• Reducer 中频繁查找的列（非主键）
• 数据量大于 100 行的表

什么时候不加？

• 小表（几十行以下，全表扫描比索引查找还快）
• 从不在查询条件中出现的列

5.2 订阅优化：减少不必要的数据推送

// ❌ 订阅全表，收到所有元素的所有变更
ctx.subscriptionBuilder().subscribe([tables.elements]);

// ✅ 只订阅当前画布的元素
ctx.subscriptionBuilder()
  .subscribe([
    tables.elements.where(r => r.canvas_id.eq('my-canvas')),
  ]);

对于我们的白板应用，这意味着：

• 用户只在某个画布时，订阅该画布的数据
• 切换画布时，取消旧订阅，建立新订阅
• 光标数据单独订阅，因为更新频率远高于元素

5.3 Reducer 设计原则

保持 Reducer 轻量：

// ❌ 在 Reducer 里做重计算
#[reducer]
pub fn generate_terrain(ctx: &ReducerContext) {
    let terrain = expensive_noise_generation(); // 耗时操作
    // ...
}

// ✅ 预计算，Reducer 只做简单写入
#[reducer]
pub fn place_terrain_chunk(ctx: &ReducerContext, chunk_data: String) {
    // chunk_data 由客户端或 Procedure 预计算
    ctx.db.terrain_chunks().insert(TerrainChunk {
        id: 0,
        data: chunk_data,
    });
}

批量操作优于逐条操作：

// ❌ 多次 Reducer 调用，每次插入一条
// 客户端循环调用 connection.reducers.createLine(...)

// ✅ 一次 Reducer 调用，批量插入
#[reducer]
pub fn create_drawing(ctx: &ReducerContext, lines: Vec<LineInput>) {
    for line in lines {
        // 在同一个事务中批量处理
        let id = ctx.db.elements().insert(Element { /* ... */ }).id;
        ctx.db.lines().insert(Line { element_id: id, ..line.into() });
    }
}

5.4 表设计的性能考量

行大小优化：全内存数据库中，每行的内存占用直接决定服务器能承载多少数据。

// ❌ 存储冗余数据
pub struct Message {
    id: u64,
    sender: Identity,      // 32 字节
    sender_name: String,   // 冗余！可以通过 Identity 查找
    text: String,
}

// ✅ 通过关联查找
pub struct Message {
    id: u64,
    sender: Identity,      // 32 字节
    text: String,          // 客户端通过 sender 关联 User 表获取名字
}

使用合适的类型：

// ❌ 用 String 存枚举
element_type: String,  // "line", "text", "rectangle"

// ✅ 用 u8 存枚举
element_type: u8,  // 0, 1, 2 — 节省内存，加速比较

六、与传统方案的对比

6.1 SpacetimeDB vs Firebase/Supabase Realtime

Firebase 和 Supabase 的实时能力很强，但业务逻辑还是在「函数层」运行，数据要经过「数据库 → 函数 → 客户端」的路径。SpacetimeDB 把函数层和数据库合并了，减少了延迟和复杂度。

6.2 SpacetimeDB vs 传统 Web 框架 + Redis + PostgreSQL

传统方案的优势在于生态——你遇到任何问题都能找到答案。SpacetimeDB 的优势在于极简——当你的应用核心是「实时状态同步」时，它是最直接的解决方案。

6.3 适用场景判断

适合用 SpacetimeDB 的场景：

• 多人游戏（MMO、回合制、卡牌）
• 实时协作工具（白板、文档编辑、项目管理）
• 实时仪表盘（监控、交易、IoT）
• 聊天/社交应用
• 任何「多人实时状态同步」场景

不太适合的场景：

• 纯内容展示（没有实时同步需求）
• 批处理/数据分析（OLAP 场景）
• 需要复杂 SQL 查询的报表系统
• 数据量远超内存容量的场景

七、生产级部署指南

7.1 Maincloud（托管服务）

最简单的方式是部署到 SpacetimeDB 的云平台 Maincloud：

spacetime publish my-app

一行命令完成部署。Maincloud 自动处理扩容、备份、监控。

7.2 自托管（Docker）

docker run -d \
  --name spacetimedb \
  -p 3000:3000 \
  -v spacetimedb-data:/data \
  clockworklabs/spacetime start

7.3 从源码编译

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 编译
git clone https://github.com/clockworklabs/SpacetimeDB
cd SpacetimeDB
cargo build --locked --release -p spacetimedb-standalone -p spacetimedb-update -p spacetimedb-cli

# 安装
mkdir -p ~/.local/bin
STDB_VERSION="$(./target/release/spacetimedb-cli --version | sed -n 's/.*spacetimedb tool version \([0-9.]*\);.*/\1/p')"
mkdir -p ~/.local/share/spacetime/bin/$STDB_VERSION
cp target/release/spacetimedb-update ~/.local/bin/spacetime
cp target/release/spacetimedb-cli ~/.local/share/spacetime/bin/$STDB_VERSION
cp target/release/spacetimedb-standalone ~/.local/share/spacetime/bin/$STDB_VERSION
export PATH="$HOME/.local/bin:$PATH"
spacetime version use $STDB_VERSION

7.4 生产环境注意事项

1. 内存规划：所有数据驻留内存，确保服务器内存 > 数据量 × 1.5（含索引开销）
2. Commit Log 清理：定期归档或截断过老的日志，防止磁盘空间耗尽
3. 监控：关注内存使用率、Reducer 执行时间、订阅数量
4. 备份：虽然 commit log 保证持久性，但定期快照可以加速恢复
5. 模块版本管理：发布新模块前在测试环境验证，自动迁移功能会自动处理 schema 变更

八、许可证与商业考量

SpacetimeDB 使用 Business Source License 1.1 (BSL)，4 年后转换为 AGPL v3 + Linking Exception。

这意味着：

• 开发阶段：免费使用，但云服务商不能直接提供 SpacetimeDB 服务（保护 Clockwork Labs 的 Maincloud 商业模式）
• 4 年后：自动转为开源，任何人可以使用，但修改 SpacetimeDB 本身需要开源修改
• Linking Exception：使用 SpacetimeDB 的应用不需要开源自己的代码

这是一个合理的商业模式——对开发者友好，同时保护了项目方的商业利益。

九、总结与展望

SpacetimeDB 代表了一种大胆的架构思想：当数据库足够快、足够智能，我们是否还需要应用服务器？

答案是：对于实时应用，不需要。

传统架构中，应用服务器扮演的角色是「数据搬运工」——从数据库读数据、转换格式、推给客户端。SpacetimeDB 让数据库直接承担了这个角色，消除了中间层，带来了极低的延迟和极简的架构。

当然，SpacetimeDB 不是银弹。对于复杂的业务编排、多数据源聚合、批处理等场景，传统架构仍然更合适。但在「多人实时状态同步」这个越来越重要的领域，SpacetimeDB 提供了一个令人兴奋的新选择。

BitCraft Online 的成功证明了这条路的可行性——一个完整的 MMORPG 后端，跑在一个数据库模块里。这在几年前是难以想象的。

随着 AI Agent 对实时数据交互的需求爆发（多 Agent 协作、实时推理、低延迟决策），SpacetimeDB 的「数据库即服务器」理念可能会找到更多应用场景。未来的 AI 应用可能不再需要复杂的微服务架构——一个 SpacetimeDB 模块就能搞定。

关键要点：

1. SpacetimeDB 把业务逻辑和数据库合并，消除了中间层
2. 全内存 + Commit Log 兼顾速度和持久性
3. Reducer + Subscription 构成了完整的状态管理模型
4. 按访问模式拆表是 SpacetimeDB 中最重要的设计原则
5. 适合实时/多人场景，不适合 OLAP 或纯内容展示
6. BSL 许可证对开发者友好，4 年后自动开源

如果你在构建实时应用，SpacetimeDB 值得认真评估。它可能不会取代你所有的后端，但在合适的场景下，它能帮你省掉 80% 的基础设施复杂度。

参考资源：

• GitHub 仓库：https://github.com/clockworklabs/SpacetimeDB
• 官方文档：https://spacetimedb.com/docs
• BitCraft Online：https://bitcraftonline.com
• SpacetimeDB 定价：https://spacetimedb.com/pricing