个人画布是本地的，
共享画布才联网。
默认情况下，你的画布只存在这台设备上。只有主动创建或加入共享画布，节点、连线和位置才会通过 WebSocket 实时同步给房间里的其他人。
- 同步引擎
- Yjs 文档 + Hocuspocus Provider
- 通道
- WebSocket，独立协作服务
- 同步内容
- 节点、连线、文本、位置、拖动状态
- 不同步
- 媒体文件本体与预签名地址
- 降级
- 协作服务不可用时，本地画布照常使用
HOW IT STARTS
三步进入
三步进入
同一个房间。
- 01创建共享画布在画布右上角打开协作面板，点「创建共享画布」，服务端返回一个房间号。
- 02把房间号发出去协作面板内置分享，直接调用系统分享面板把邀请发到微信、邮件或任何地方。
- 03等文档同步完成面板会显示 Yjs 文档的同步进度。同步完成前面布是锁定的，避免多人同时初始化把内容冲掉。
共享画布需要一个可用的协作服务地址。服务未部署或不可达时，App 会明确提示连接失败并提供重试，不会悄悄退化成只有你一个人能编辑的状态。
3 人在线房间 canvas-7f2a · 已同步
Connected
ROLES & PERMISSIONS
谁能改，
谁能改，
谁只能看。
房间里的角色决定你能做什么。只读成员可以完整查看画布，但无法触发会产生费用的生成请求。
| 能力 | 房主 | 可编辑成员 | 只读成员 |
|---|---|---|---|
| 查看节点、连线与位置 | 可以 | 可以 | 可以 |
| 移动节点、改文本、连删线 | 可以 | 可以 | 不可 |
| 触发生图 / 视频生成 | 可以 | 可以 | 不可（不产生计费） |
| 上传素材到云端短链 | 本人账户 | 本人账户 | 本人账户 |
| 停止协作并收回本地 | 可以 | 不可 | 不可 |
| 另存一份本地副本 | 可以 | 可以 | 可以 |
在线状态不可信：成员列表里的身份信息来自 Awareness，服务端会按不可信数据处理，不能靠它提权。
WHAT GETS SYNCED
同步结构，
同步结构，
不同步文件。
画布的结构信息很小，走实时通道毫无压力；媒体文件很大，留给你自己决定要不要上传。
SYNCED
这些会实时同步
- 节点类型、位置、尺寸与选中状态
- 节点之间的连线关系
- 文字节点内容与生成节点参数
- 在线成员的拖动过程（看得见别人在动）
- 素材引用 ID、短链 ID 与稳定短链地址
NOT SYNCED
这些不会被上传
- 图片和视频文件的二进制内容
- 存储服务的预签名地址（会过期，同步无意义）
- 你的登录密码与账户密钥
- 提示词以外的个人数据、诊断日志
媒体文件要共享，需要你在协作面板里主动上传；不上传也不影响画布结构同步。
CLOUD ASSETS
两个账户，
两个账户，
互不干扰。
创作账户用来生成，云端素材账户用来存文件。它们是两套独立的登录：退出其中一个，另一个的会话和本地素材都还在。
- 01独立邮箱账户在协作面板里用短链接服务的邮箱和密码登录，与创作账户完全分开。
- 02按素材逐个上传素材库里的每一个条目都有独立的上传按钮，传完显示为已同步，避免误传整库。
- 03拿回一条稳定短链上传成功后得到短链地址，可以复制到任何地方，也可以被协作者的画布引用。
上传使用你自己的短链接账户 Token，单个文件失败不会影响其他条目
自己部署时的接入前提
FOR SELF-HOSTERS
CHECKLIST
服务端需要准备的东西
- 部署独立的协作 API 与 WebSocket 服务（Hocuspocus）
- 为账户授予
canvas业务访问权限 - 开放
assets.upload与links.create_asset功能权限 - 短链接服务的 CORS 允许
capacitor://localhost、http://localhost、https://localhost与实际 Web Origin - 画布生成请求的计费与模型路由按账户分组配置好
CLIENT CONFIG
客户端指向你的服务
协作地址与短链接地址通过构建期环境变量注入，不写死在代码里。本地开发时 Vite 会代理到目标服务，生产构建直连。
VITE_COLLAB_HTTP_URL=# 协作 API 地址
VITE_COLLAB_WS_URL= # WebSocket 地址
VITE_SHORT_LINK_URL= # 短链接服务地址
协作或短链接服务未部署时，不影响本地画布与生图功能，只是协作入口不可用。
协作相关的问题
FAQ不创建共享画布，别人能看到我的画布吗？
不能。个人画布只保存在设备本地，不会上传到任何服务器，也没有可供他人访问的地址。
协作中途断网会怎样？
断线期间画布会进入保护状态，避免你在没有同步的情况下改动内容造成分叉。恢复连接后重新同步，再继续编辑。
房主停止协作后，我做的内容会丢吗？
房主可以选择把画布保留为本地画布。成员如果希望继续使用这份内容，可以在停止协作之前先「另存为本地画布」，得到一份属于自己的副本。
为什么我上传的图片别人看不到？
画布只同步素材引用与短链地址，文件本体需要真的上传到云端。确认上传成功并且对方能访问该短链；如果上传时遇到网关限制，按提示检查服务端上传大小与存储额度。
只读成员为什么不能点生成？
生成会产生真实费用。只读角色被限制在浏览与查看范围内，所有计费请求都会在客户端与服务端两侧被拒绝。