andig/carddav2fb

CardDAV联系人导入工具 for AVM FRITZ!Box

这是https://github.com/jens-maus/carddav2fb%E7%9A%84%E5%AE%8C%E5%85%A8%E4%BF%AE%E8%AE%A2%E7%89%88%EF%BC%8C%E7%94%A8%E4%BA%8E%E5%B0%86CardDAV%E8%81%94%E7%B3%BB%E4%BA%BA%E5%AF%BC%E5%85%A5AVM FRITZ!Box电话簿。

镜像概述与主要用途

该Docker镜像包含carddav2fb工具及其所有依赖，用于从CardDAV服务器或本地VCF文件下载联系人，并将其转换为FRITZ!Box兼容的电话簿格式上传，同时支持联系人图片、快速拨号等属性的保留与管理。

核心功能与特性

• 支持从多个CardDAV服务器下载联系人
• 可选读取本地*.vcf文件
• 按类别或组（如iCloud）筛选联系人（包含/排除）
• 上传联系人图片至FRITZ!Fon显示
• 自动保留FRITZ!Box Web界面中设置的电话号码快速拨号（QuickDial）和vanity属性，无需额外配置
• 自动保留内部号码（如用于群组通话功能）
• 当联系人包含超过9个电话号码时，自动拆分为对应数量的电话簿条目（电子邮件地址分配给第一个条目，无数量限制）
• 电话号码按类型排序，排序顺序由配置中的'phoneTypes'转换值决定
• 将CardDAV服务器的联系人UID添加到电话簿条目（FRITZ!Box界面不可见）
• 快速拨号和vanity属性数据保存在FRITZ!Box内部内存../FRITZ/mediabox/Atrributes.csv中，防止丢失
• 生成包含快速拨号号码（2-9）的键盘背景图片，可上传至指定手持设备

使用场景与适用范围

适用于需要将CardDAV联系人（如来自Nextcloud、iCloud等）同步到AVM FRITZ!Box电话簿的用户，特别适合使用FRITZ!Fon C4/C5手持设备并希望显示联系人图片的场景，支持定期自动同步更新电话簿。

使用方法与配置说明

Docker镜像基本信息

• 镜像包含工具及所有依赖
• 配置文件位于/data卷，若配置缺失，入口程序会报错并复制示例文件到该卷

Docker部署示例

1. 执行单个命令

console
docker run --rm -v ./carddav2fb-config:/data andig/carddav2fb [command]

示例：列出所有命令

console
docker run --rm -v ./carddav2fb-config:/data andig/carddav2fb list

示例：完整处理（下载并上传联系人）

console
docker run --rm -v ./carddav2fb-config:/data andig/carddav2fb run

示例：获取命令帮助

console
docker run --rm -v ./carddav2fb-config:/data andig/carddav2fb run -h

2. 定期自动执行

不带命令时，容器会进入循环，按指定间隔重复执行carddav2fb run以自动更新电话簿：

console
docker run -v ./carddav2fb-config:/data andig/carddav2fb

前置条件

使用前需在FRITZ!Box中完成以下设置：

• 内存（USB设备）已索引：【家庭网络 -> 存储（NAS）-> FRITZ!Box存储】
• FTP访问已激活：【家庭网络 -> 存储（NAS）-> 家庭网络共享】
• 创建独立用户（非dslf-config）并授予权限：【系统 -> FRITZ!Box用户 -> [用户] -> 权限】，需包含FRITZ!Box设置访问、NAS内容访问及所有可用内存的读写权限

上传FRITZ!Fon背景图片

使用background-image命令可将快速拨号号码作为背景图片上传至FRITZ!Fon：

console
docker run --rm -v ./carddav2fb-config:/data andig/carddav2fb background-image

也可在上传电话簿时包含图片上传：

console
docker run --rm -v ./carddav2fb-config:/data andig/carddav2fb run -i

图片上传前置条件

• 需FRITZ!Fon C4或C5手持设备
• FRITZ!Fon设置：【设置 -> 显示 -> 起始屏幕 -> 经典 -> 选项 -> 背景图片】
• 在config.php的'fritzfons'数组中通过手持设备内部号码分配，内部号码需在610-615之间，无'**'前缀

配置说明

1. 首次运行容器后，配置文件示例会复制到./carddav2fb-config/config.example.php
2. 复制示例文件并重命名为config.php：

   console
   cp ./carddav2fb-config/config.example.php ./carddav2fb-config/config.php
   

3. 编辑config.php配置CardDAV服务器信息、本地文件路径、筛选规则等参数

调试

如需调试，在config.php中设置：

php
'http' => [
    'debug' => true
]

许可证

本脚本以公共领域发布，部分组件基于GNU AGPL或MIT许可证。请确认各部分的许可条款。

作者

Copyright (c) 2012-2020 Andreas Götz, Volker Püschel, Karl Glatz, Christian Putzke, Martin Rost, Jens Maus, Johannes Freiburger