> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 实时同步

> 本地优先应用，支持离线和自动后台同步。

## 工作原理

具有实时同步功能的应用在设备上保持本地数据库。读取是即时的（本地），写入在本地排队，所有内容在后台同步到服务器。

```text theme={"theme":"material-theme-darker"}
用户写入 -> 本地数据库 -> 上传队列 -> 服务器 -> Postgres
                                                    |
用户读取  <- 本地数据库 <- 同步复制 <---------+
```

结果：即时读取、无加载动画，以及在弱网或离线状态下仍能正常工作的应用。

## AI 设置的内容

要求 AI 构建实时应用。它会重用现有的合适活跃数据库；否则会创建数据库、启用同步服务，并构建一个两部分应用：

* **UI** - 客户端应用，包含本地数据库、实时查询和同步连接器
* **Process** - 令牌端点、同步上传路由和迁移运行器

凭证存储在[保险库](/work/vault)中。AI 使用 `db` 工具将数据库环境变量连接到流程组件。

应用被认为就绪前，数据库必须显示 `sync: ready`。如果同步未就绪，应用可能会渲染，但跨设备实时数据将无法工作。

## 经验法则

* 先在本地写入。让同步在后台上传。
* 本地数据存在后，显示空状态而非加载动画。
* 将用户可见的状态保存在同步表中，以便在刷新和离线使用时保留。
* 将相关的本地写入分组，使 UI 一步更新。
* 在完成实时应用前验证同步健康状态。

## 离线应用壳

UI 模板可以包含离线应用壳，使应用在首次访问后无需网络即可重新打开。应用壳是静态 HTML、JS、CSS 和图标。

* **离线壳** 使应用无需网络即可打开
* **同步** 使应用数据在离线时保持可用

结合使用：应用无需网络即可打开，显示最新同步数据，排队新写入，并在连接恢复时同步。

## 何时使用实时同步

| 适合          | 过度设计     |
| ----------- | -------- |
| 任务管理器和笔记应用  | 静态营销页面   |
| 协作工具        | 一次性表单提交  |
| 弱网连接的现场应用   | 只读宣传册网站  |
| 任何应该感觉即时的应用 | 无离线价值的应用 |

## 平台变量

Kazzle 自动向每个应用流程注入一小组环境变量。这些与你自己的[保险库密钥](/work/vault)分开。

| 变量                                | 说明                     |
| --------------------------------- | ---------------------- |
| `PORT`                            | 流程应监听的端口               |
| `HOST`                            | 要绑定的主机名（通常为 `0.0.0.0`） |
| `KAZZLE_API_URL`                  | Kazzle 运行时助手使用的基础 URL  |
| `KAZZLE_APP_COMPONENT_<NAME>_URL` | 同级组件的运行时 URL           |

### 同级 URL

当应用有多个组件（例如 `web` UI 和 `server` 流程）时，Kazzle 可以注入同级组件的 URL：

```
# 在"web"部分：
KAZZLE_APP_COMPONENT_SERVER_URL=http://localhost:3001

# 在"server"部分：
KAZZLE_APP_COMPONENT_WEB_URL=http://localhost:3000
```

当同级已部署时，注入的值指向该已部署组件。否则它指向该同级的当前开发地址。