AIBro 自托管云同步教程：用 HTTPS 与 SSH 部署独立服务，跨 Mac 同步知识、任务与资料

如果你想在多台 Mac 之间同步 AIBro 的知识、任务与资料，AIBro 内置的自托管云同步是最直接的选择：在任意一台 Linux 服务器上部署独立同步服务，即可让多个桌面工作区保持一致，无需官方云账号，也不依赖模型提供商。本教程将带你完成 HTTPS 与 SSH 两种部署方式，并教会你在 Mac 端连接账号、处理冲突与备份数据。

为什么选择 AIBro 自托管云同步 🤔

AIBro 是本地优先（local-first）的工作站：不连接服务器也能正常保存和使用。云同步是可选能力，首版已支持：

• 自动同步 + 手动"立即同步"：断网时本地内容照常可用，待上传操作会保留；
• 跨设备合并：按稳定 ID 与版本号核对记录，冲突需手动选择"保留本机"或"使用云端"；
• 附件去重：附件原件按 SHA-256 校验和去重，避免重复下载；
• 设备管理：可查看并撤销指定设备的访问权限。

完整的能力边界说明见 docs/CLOUD_SYNC.md。需要提醒的是：云服务可以读取同步内容明文，HTTPS/SSH 只保护传输过程，不提供端到端加密，因此服务器应由你信任的人管理。

两种部署方式怎么选 🧭

服务本体只有 app/cloud_server.py 和 app/cloud_web.py 两个 Python 文件，只依赖标准库，不运行桌面后端、不读取你电脑上的任何本地目录。

方式一：Docker Compose 部署 HTTPS 服务

仓库的 cloud/ 目录已备好完整部署文件，包括 cloud/compose.yaml、cloud/Caddyfile 与 cloud/Dockerfile。Caddy 负责自动签发 TLS 证书，Python 服务只在容器内部网络暴露 8787 端口，公网完全看不到明文端口。

第 1 步：启动服务。准备一个指向服务器的域名，然后在cloud目录执行：

export CLOUD_DOMAIN=sync.example.com docker compose up -d --build

第 2 步：创建云账号。账号由服务器操作者通过 CLI 创建，没有公开注册接口。密码从终端隐式输入，不会出现在命令行参数或环境变量中：

python3 -c 'import getpass; print(getpass.getpass("初始账号密码（至少12字符）: "))' | docker compose exec -T cloud python /app/cloud_server.py init --username admin --password-stdin

需要第二个独立账号时，把init换成add-user并更换--username即可。注意：一个账号代表"同一个人"，多设备共用同一账号并填不同设备名称，而不是为每台电脑新建账号。

第 3 步：验证健康检查。浏览器访问https://你的域名/v1/health，返回{"protocol":1}即部署成功。

⚠️ 不要把桌面的server.py（本机后端）暴露到公网，也不要另行公开云服务的明文 8787 端口。

方式二：SSH 隧道部署（无域名）

如果你只有 SSH 访问权限，这条路径不需要 Docker、域名和 TLS 证书：云服务只监听服务器127.0.0.1:8787，你的 Mac 通过 SSH 把它转发到本机127.0.0.1:18787。完整步骤在 cloud/SSH_DEPLOY.md，核心流程如下：

第 1 步：检查服务器环境。需要 Python 3.10+ 且包含hashlib.scrypt，同时需要 systemd 用户服务。在服务器上运行文档给出的检查脚本即可。

第 2 步：上传最小发布目录。在 Mac 上把cloud_server.py、cloud_web.py和用户服务文件 cloud/ai-workstation-cloud.service 传到~/.local/share/ai-workstation-cloud/下，并用符号链接current指向本次发布。发布代码与data数据目录严格分开。

第 3 步：初始化云账号并启动服务。

systemctl --user enable --now ai-workstation-cloud.service curl --fail --silent --show-error http://127.0.0.1:8787/v1/health

要让服务在你退出 SSH 后继续运行，需要管理员执行sudo loginctl enable-linger 用户名，并确认输出Linger=yes。

第 4 步：在 Mac 建立隧道。

ssh -N -T -o ExitOnForwardFailure=yes \ -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \ -L 127.0.0.1:18787:127.0.0.1:8787 \ my-sync-host

另开一个终端用curl http://127.0.0.1:18787/v1/health验证，返回{"protocol":1}即可连接。

在 Mac 上连接 AIBro 云账号 📱

1. 打开 AIBro 工作站的设置 → 账号与云同步，点击"连接云账号"；
2. 填写服务器地址（HTTPS 部署填https://你的域名，SSH 隧道填http://127.0.0.1:18787）、用户名、密码和本机设备名称；
3. 核对目标服务器，勾选"我确认将当前本地知识与云端合并"，点击"连接并合并"。

首次连接会把当前工作区支持同步的内容上传，并接收云端已有内容——这是双向合并，不是谁覆盖谁。同名但 ID 不同的项目、笔记不会自动视为同一条记录，独立导入的数据可能同时保留。

在另一台 Mac 上连接同一服务和账号时，同样需要确认首次合并。一个本地工作区会绑定首次连接的服务器与账号，断开后绑定、同步游标和本地内容都会保留，无法直接改填另一个地址混入第二套资料；需要连接其他目标时请使用独立本地工作区。

哪些内容会同步、哪些不会 📦

论文 Markdown、导出目录属于派生文件，会根据同步后的论文记录重新生成。特别注意：如果把密码等敏感文字直接写进笔记或对话正文，它们仍会作为内容同步——同步字段过滤不等于秘密识别。

自动同步与冲突处理 ⚖️

• 本机保存先写本地数据，网络同步由后台线程完成；关闭"自动同步"后仍可点"立即同步"，断网时待上传内容保留，重连后继续。
• 设置页会实时显示待同步数量、最近同步时间与离线/冲突状态；较大的资料库分批处理。
• 两台设备同时保存不同实体或不同字段时，可通过三方合并保留；但双方修改同一段笔记、同一字段，或一端删除另一端修改时，系统不会拼接文本，而是在"处理冲突"中让你选择"保留本机"或"使用云端"。
• 删除也是同步操作：移入回收站会同步状态与恢复记录，但永久删除不等于清除云端历史和附件副本。

备份与日常维护 🗂️

• 服务器端：升级前先停服务，备份整个cloud_data（或 SSH 部署的data目录），不要只复制运行中的.sqlite3而遗漏 WAL 和附件卷；步骤见 cloud/README.md 与 cloud/SSH_DEPLOY.md。
• Mac 端：本地 SQLiteworkspace.sqlite3是规范数据源，建议在应用停止写入后备份整个本地数据目录；跨设备恢复备份时应排除cloud-sync会话凭据文件，并在目标设备重新登录。
• 会话令牌由本地 Python 后端持有，保存在权限受限的cloud-session.json（目录 0700 / 文件 0600），服务端只存令牌哈希。
• 排障顺序：先看服务器健康检查 → 再查 SSH 会话与端口占用 → 登录失败时用云账号而非 SSH 账号 → 提示"目标不匹配"时核对 URL 与账号（当前版本不支持迁移绑定）。

总结 ✅

AIBro 自托管云同步让你用一台 Linux 服务器就能实现跨 Mac 的知识、任务与资料同步：有域名就上 Docker Compose + Caddy 的 HTTPS 方案，无域名就用 SSH 隧道方案。部署完成后，在"设置 → 账号与云同步"填写地址和账号，确认合并，两台电脑就能持续保持一致。记住三个关键点：地址绑定一经建立不可随意更改、冲突必须人工裁决、服务器端与本地端都要定期备份。

延伸阅读：docs/CLOUD_SYNC.md、cloud/README.md、cloud/SSH_DEPLOY.md