CardDAV / CalDAV

Bonds 内置 CardDAV 和 CalDAV 服务器，可以与 Apple 通讯录、Thunderbird、GNOME Contacts 等 DAV 兼容客户端同步联系人和日历。

端点

协议	URL	说明
CardDAV	/dav/	联系人同步
CalDAV	/dav/	日历同步（重要日期、任务）
发现	/.well-known/carddav	自动发现重定向
发现	/.well-known/caldav	自动发现重定向

认证

DAV 客户端使用 HTTP Basic Auth（非 JWT），这是因为大多数 DAV 客户端不支持 Token 认证。

场景	凭据
两步验证未启用	邮箱 + 密码，或邮箱 + 个人访问令牌
两步验证已启用	邮箱 + 个人访问令牌 仅此方式（密码被禁止）

适用于 DAV 同步的个人访问令牌

即使未启用两步验证，我们也强烈推荐为 DAV 客户端生成专属的个人访问令牌。

• 你可以在 设置 > API 令牌 中生成令牌。
• 为令牌指定清晰的描述以及可选的有效期。
• 令牌仅在创建时显示一次，请务必立即复制。
• 在 DAV 客户端配置中，用户名填写你的邮箱，密码填写刚生成的以 bonds_ 开头的个人访问令牌。

WARNING

启用两步验证后，使用密码的 DAV 客户端将停止同步。请使用个人访问令牌重新配置客户端。

同步内容

CardDAV（联系人 → 兼容性 vCard 3.0）

CardDAV 服务使用 UTF-8 vCard 3.0，以兼容 Apple 通讯录及其他 DAV 客户端。手动下载和 REST API 导出的 vCard 仍为 4.0。

Bonds 字段	vCard 属性
名 + 姓	FN、N
电话号码	TEL
邮箱地址	EMAIL
地址	ADR
联系人选定的头像	PHOTO

上传的 PNG、JPEG、GIF、WebP 头像会内嵌到 vCard，客户端无需另行认证下载。只返回选定的头像，不包含其他相册照片或自动生成的首字母头像。本地图片的内嵌上限为 10 MiB。缺失的文件、不支持的内容类型及超过 10 MiB 的文件会被省略，不阻断联系人同步；选定头像和存储文件保持不变。已有的远程照片 URL 仍作为 URI 属性返回，服务器不会抓取远程图片。

请在 Bonds 中上传、选择或移除头像。CardDAV 不导入客户端提交的照片；从 DAV 客户端编辑其他联系人字段时，会保留选定的头像。返回照片发生变化时，联系人 ETag 也会变化。

Linux 上的安全照片读取使用 openat2（Linux 5.6+），无需上传目录的列表读取权限。若该系统调用不可用或被禁止，或运行于其他操作系统，则回退到标准库方式，需要上传目录可读。所有情况下，本地照片路径及符号链接都必须限制在上传目录内。

CalDAV

Bonds 实体	iCal 类型	备注
重要日期	VEVENT	带 RRULE=YEARLY 的周期事件
任务	VTODO	任务截止日期和状态

DAV 同步订阅

除了将 Bonds 作为 DAV 服务器暴露给外部客户端，每个 Vault 还可以在 DAV 同步 页面订阅外部 CardDAV 通讯录。

• 创建订阅：填写远程服务器地址、用户名、密码、可选通讯录路径、同步方向和同步频率。
• 测试连接：保存前检测远程服务器并发现可用通讯录。如果只发现一个通讯录，Bonds 会自动选中。
• 同步方向：仅拉取会把远程联系人导入 Vault；仅推送会把本地联系人变更发送到远程通讯录；双向同步会同时执行两者。
• 定时与手动运行：默认频率为 180 分钟，可选 30 分钟到 24 小时。点击 立即同步 可立刻触发一次同步。
• 同步日志：记录每个订阅中的创建、更新、删除、推送、跳过和错误事件。
• 远程密码会使用基于 JWT_SECRET 派生的密钥进行静态加密。

客户端配置

Apple 通讯录 / 日历（macOS / iOS）

1. 前往 设置 > 账户 > 添加账户 > 其他。
2. 选择 添加 CardDAV 账户 或 添加 CalDAV 账户。
3. 输入：
   • 服务器：https://your-bonds-domain.com
   • 用户名：你的邮箱
   • 密码：你的密码（若启用了两步验证，则使用个人访问令牌）

Well-known URL（/.well-known/carddav、/.well-known/caldav）支持自动发现。

Thunderbird

1. 打开 通讯录 > 新建 > CardDAV 通讯录。
2. 输入 URL：https://your-bonds-domain.com/dav/
3. 使用 Bonds 账户认证。

ETag

CardDAV 地址对象的 ETag 由完整序列化后的 vCard 内容生成，因此电话号码、电子邮件地址和其他关联数据发生变化时也会触发同步。其他 DAV 资源继续使用其 UpdatedAt 时间戳。客户端通过这些 ETag 检测变更并高效同步。