[{"template":"item","lang":"zh-CN","langs":["zh-CN"],"summary":{"raw":"vCards 是一个中国黄页开源项目，整理了一批常用的企业联系人，并精心设定了头像；可以导入到手机、电脑中，优化来电和信息界面的使用体验。支持 vcf 文件下载，要求使用者手动导入；如果后续有变动，仍需重复手动导入操作。本文探讨使用 Radicale 在 Ubuntu 24.04 中搭建 CardDav 服务，以实现方便在各个设备上订阅导入，以及让黄页联系人自动保持最新的目标。","html":"

vCards 是一个中国黄页开源项目，整理了一批常用的企业联系人，并精心设定了头像；可以导入到手机、电脑中，优化来电和信息界面的使用体验。支持 vcf 文件下载，要求使用者手动导入；如果后续有变动，仍需重复手动导入操作。本文探讨使用 Radicale 在 Ubuntu 24.04 中搭建 CardDav 服务，以实现方便在各个设备上订阅导入，以及让黄页联系人自动保持最新的目标。

\n"},"visible":true,"routable":true,"title":"使用 Radicale 在 Ubuntu 24.04 中搭建 vCards CardDav 服务","comment":{"enabled":true,"reply":true},"discuss":{"enabled":true},"keywords":["vCards 同步","企业联系人","公共通讯录","中国黄页","自建 Radicale"],"webmention":{"enabled":true,"accept":true,"callback":{"secret":{"hash":{"sha256":"44bb9da44b424c6dfc9233819e907029ff2ccdfaa89919d3696ddf8db7ff6647"}}}},"pingback":{"enabled":true,"accept":true},"slug":"build-vcards-carddav-service-with-radicale-on-ubuntu-24-04","taxonomy":{"category":["Software"],"tag":["Radicale","CardDav","Ubuntu"],"series":[]},"route":"/build-vcards-carddav-service-with-radicale-on-ubuntu-24-04/","toc":{"enabled":true},"published":{"date":"2024-10-17 10:17"},"modified":{"date":"2025-01-02T15:44:02.000Z"},"data":{},"license":"CC-BY-NC-SA-4.0","author":[{"email":{"value":{"encrypted":"ODgyZjdiZDg4OTVmMjllOGZkNmFmYg==","algorithm":"aes-256-gcm","iv":"067f6d66f2ba5dd50c8443be"},"hash":{"md5":"8770854a9222b6bf1ee195220793bcf1"}},"url":"https://dallas.lu","name":"达拉斯・卢","lang":"zh-CN","user":"dallaslu"}],"contributor":[],"sponsor":[],"image":[],"audio":[],"video":[],"photo":[],"content":{"html":"

\n\n

$\"\"$

提示如果你并不想自行搭建，只想体验订阅同步，可以前往使用介绍，或者访问图文并茂的使用教程：快速实现在 iPhone通讯录中添加中国黄页的步骤。

准备工作

出于安全考虑，建议使用专用的用户：

sudo useradd --system --user-group --home-dir /home/radicale --shell /sbin/nologin radicale\n

创建 Radicale 数据目录：

sudo mkdir -p /home/radicale/collections/collection-root\nsudo chown -R radicale: /home/radicale\n

vCards

vCards 项目已经可以直接输出 Radicale 所支持的数据格式。

sudo apt install git npm\n\n# 切换到用户 radicale\nsudo su -l radicale -s /bin/bash\ncd ~\ngit clone https://github.com/metowolf/vCards.git\ncd vCards\nnpm install\nnpm run radicale\n

完成后，数据会输出在 vCards 目录中的 radicale，创建一个软链接，以供 Radicale 使用：

ln -s /home/radicale/vCards/radicale /home/radicale/collections/collection-root/cn\n

运行 crontab -e，添加一个定时任务，以使得数据自动保持最新。鉴于项目更新频率，可设置为每周更新一次：

0 5 * * 1 cd /home/radicale/vCards && git pull && npm run radicale\n

Radicale

Radicale 是一个开源的 CalDav 和 CardDav 服务器软件，基于 Python 编写。

安装

安装 Radicale

sudo apt install python3-pip python3.12-venv\n\npython3 -m venv /home/radicale/python3-env\nsource /home/radicale/python3-env/bin/activate\npip install radicale\n

配置

创建配置目录：

mkdir /etc/radicale\n

因为联系人数据是由 vCards 项目自动生成，为避免日后数据混乱，所以要关闭 Radicale 的修改写入功能。创建权限配置 /etc/radicale/rights：

[root]\nuser: .+\ncollection:\npermissions: R\n\n# (same as user name)\n[principal]\nuser: .+\ncollection: {user}\npermissions: R\n\n[collections]\nuser: .+\ncollection: {user}/[^/]+\npermissions: rR\n

参考官方文档，创建 Radicale 配置文件 /etc/radicale/config：

[rights]\ntype = from_file\nfile = /etc/radicale/rights\n[storage]\ntype = multifilesystem\nfilesystem_folder = /home/radicale/collections\n

创建服务配置 /etc/systemd/system/radicale.service：

[Unit]\nDescription=A simple CalDAV (calendar) and CardDAV (contact) server\nAfter=network.target\nRequires=network.target\n\n[Service]\nExecStart=/home/radicale/python3-env/bin/python -m radicale\nRestart=on-failure\nUser=radicale\n# Deny other users access to the calendar data\nUMask=0027\n# Optional security settings\nPrivateTmp=true\nProtectSystem=strict\n#ProtectHome=true\nPrivateDevices=true\nProtectKernelTunables=true\nProtectKernelModules=true\nProtectControlGroups=true\nNoNewPrivileges=true\nReadWritePaths=/home/radicale/collections\n\n[Install]\nWantedBy=multi-user.target\n

启动服务并查看状态：

sudo systemctl deamon-reload\nsudo systemctl enable --now radicale\nsudo systemctl status radicale\n

提供 HTTPS 访问

Caddy

安装 Caddy 并编辑配置文件：

sudo apt install caddy\n\nsudo vim /etc/caddy/CaddyFile\n

配置：

vcards.example.com {\n    reverse_proxy localhost:5232\n}\n

启动：

sudo caddy validate --config /etc/caddy/Caddyfile\nsudo systemctl enable --now caddy\nsudo systemctl status caddy\n

请确保 80/443 端口开放：

sudo ufw allow 80,443/tcp\n

Nginx

参考以下配置：

server {\n        listen          443 ssl http2;\n        listen          [::]:443 ssl http2;\n        server_name vcards.example.com;\n\n        # ssl cert ...\n        # security ...\n\n        location ^~ /{\n                proxy_pass          http://localhost:5232;\n        }\n        access_log off;\n}\n

使用

访问 https://vcards.example.com，如果一切正常，会看到 Radicale 的登录页面，用户名 cn 密码任意填写，即可登录并查看到 vCards 提供的联系人信息。

订阅相关参数：

服务器：vcards.example.com
用户名: cn
密码：cn 或任意填写

在设备中添加订阅：

iOS: 「设置」--「通讯录」--「账户」--「添加账户」-- 「其他」--「添加 CardDAV 账户」。因为 iOS 的 Bug，并不能随时修改描述，建议将描述填写为「中国黄页」。
Mac：「通讯录」--「设置」--「账户」--「其他通讯录账户」
ThunderBird\n
- 旧版：需要安装 TbSync 及 Provider for CalDav & CardDav 扩展。「工具」--「Synchronization Settings(TbSync)」--「Account actions」--「CalDav & CardDav」-- 「Manual Configuration
- 新版：等待官方支持
\n
Android：需要安装 DAVx5。「+」--「使用 URL 和用户名登录」

可尝试使用由 vCards 的作者 metowolf 提供的公开订阅服务：vcards.metowolf.com (以 vcards.metowolf.com替换vcards.example.com)

结语

本方案中 Radicale 对于订阅用户来说，是只读的。如果你有需要临时加入一些号码，建议在本地另建一个与主联系人的有相同主号码的联系人，iOS 会自动将 vCards 中的黄页联系人和本地联系人自动合并显示。

订阅同步的方式，可能会消耗相当的服务器流量，如果你有资源，可以搭建公开的同步服务并分享给他人使用；如果你在白嫖他们提供的服务，建议设置为最慢的同步频率，以节省你的电量、流量，以及英雄们的服务器带宽和流量。

\n","headings":[{"level":2,"text":"准备工作","id":"准备工作"},{"level":2,"text":"vCards","id":"vcards"},{"level":2,"text":"Radicale","id":"radicale"},{"level":3,"text":"安装","id":"安装"},{"level":3,"text":"配置","id":"配置"},{"level":2,"text":"提供 HTTPS 访问","id":"提供-https-访问"},{"level":3,"text":"Caddy","id":"caddy"},{"level":3,"text":"Nginx","id":"nginx"},{"level":2,"text":"使用","id":"usage"},{"level":2,"text":"结语","id":"结语"}],"meta":{"prism":true},"links":[{"href":"https://www.dalao.net/thread-27691.htm","type":"mention"},{"href":"https://github.com/metowolf/vCards","type":"mention"},{"href":"https://github.com/Kozea/Radicale","type":"mention"},{"href":"https://radicale.org/3.0.html#documentation/configuration","type":"mention"},{"href":"https://i-meto.com","type":"mention"}]},"newer":"/released-from-prison-of-v2ex/","earlier":"/domain-successfully-removed-from-surbl-blacklist/"},{"template":"item","lang":"zh-CN","langs":["zh-CN"],"summary":{"raw":"vCards 是一个黄页开源项目，整理了一批常用的企业联系人，并精心设定了头像；可以导入到手机、电脑中，优化来电和信息界面的使用体验。但该项目仅提供 vcf 文件下载，要求使用者手动导入；如果后续有变动，仍需重复手动导入操作。本文探讨使用 Radicale 搭建 CardDav 服务，以实现方便在各个设备上订阅导入，以及让黄页联系人自动保持最新的目标。","html":"

vCards 是一个黄页开源项目，整理了一批常用的企业联系人，并精心设定了头像；可以导入到手机、电脑中，优化来电和信息界面的使用体验。但该项目仅提供 vcf 文件下载，要求使用者手动导入；如果后续有变动，仍需重复手动导入操作。本文探讨使用 Radicale 搭建 CardDav 服务，以实现方便在各个设备上订阅导入，以及让黄页联系人自动保持最新的目标。

\n"},"visible":true,"routable":true,"title":"为 vCards 搭建 Radicale CardDav 服务器","comment":{"enabled":true,"reply":true},"discuss":{"enabled":true},"keywords":["vCards 同步","企业联系人","公共通讯录","中国黄页","自建 Radicale"],"webmention":{"enabled":true,"accept":true,"callback":{"secret":{"hash":{"sha256":"44bb9da44b424c6dfc9233819e907029ff2ccdfaa89919d3696ddf8db7ff6647"}}}},"pingback":{"enabled":true,"accept":true},"slug":"radicale-server-for-vcards","taxonomy":{"category":["Software"],"tag":["Radicale","CardDav","Ubuntu"],"series":[]},"route":"/radicale-server-for-vcards/","toc":{"enabled":true},"published":{"date":"2021-12-01 18:00"},"modified":{"date":"2024-10-18T04:58:02.000Z"},"data":{},"license":"CC-BY-NC-SA-4.0","author":[{"email":{"value":{"encrypted":"ODgyZjdiZDg4OTVmMjllOGZkNmFmYg==","algorithm":"aes-256-gcm","iv":"067f6d66f2ba5dd50c8443be"},"hash":{"md5":"8770854a9222b6bf1ee195220793bcf1"}},"url":"https://dallas.lu","name":"达拉斯・卢","lang":"zh-CN","user":"dallaslu"}],"contributor":[],"sponsor":[],"image":[],"audio":[],"video":[],"photo":[],"content":{"html":"

\n\n

WARNING2024-10-17 本文内容已过时，请访问最新教程：使用 Radicale 在 Ubuntu 24.04 中搭建 vCards CardDav 服务

vCards

vCards 项目中的原始数据是 YAML 格式，头像使用 png 格式；并且设定了诸如「互联网」「快递物流」的分类目录。使用 vcards-js 基于原始数据来生成最终的 vcf 文件。我们可以修改生成过程，以生成 Radicale 所需的联系人文件；同时设定自动更新 Git 仓库、打包部署的脚本，以供设备同步。

Radicale

Radicale 是一个开源的 CalDav 和 CardDav 服务器软件，基于 Python 编写。

搭建 Radicale 实例

我们的目标是在 Ubuntu 上搭建服务。

安装

# 创建运行服务的专用用户\nsudo useradd --system --user-group --home-dir /home/radicale --shell /sbin/nologin radicale\n\nsudo mkdir -p /home/radicale/collections\nsudo chown -R radicale: /home/radicale\n\nsudo python3 -m pip install --upgrade radicale\nsudo mkdir -p /etc/radicale\n\n# 安装 radicale\npython3 -m pip install --upgrade radicale\n

权限配置

因为联系人数据是由脚本生成，数据来源于 vCards 项目，所以要关闭 Radicale 的修改写入功能。编辑 /etc/radicale/rights 文件：

[root]\nuser: .+\ncollection:\npermissions: R\n\n# (same as user name)\n[principal]\nuser: .+\ncollection: {user}\npermissions: R\n\n[collections]\nuser: .+\ncollection: {user}/[^/]+\npermissions: rR\n

配置文件

参考官方文档编辑配置文件 /etc/radicale/config：

[rights]\ntype = from_file\nfile = /etc/radicale/rights\n[storage]\ntype = multifilesystem\nfilesystem_folder = /home/radicale/collections\n

私有 Radicale 的额外配置

如果不想对外提供公开服务，应该按文档创建密码文件：

sudo apt install apache-utils\nhtpasswd -c /home/radicale/.htpasswd username\n

同时在配置文件中增加：

[auth]\ntype = htpasswd\nhtpasswd_filename = /home/radicale/.htpasswd\nhtpasswd_encryption = bcrypt\n

以及在权限文件中，为 permissions 增加 w 及 W 值。

系统服务

/usr/lib/systemd/system/radicale.service:

[Unit]\nDescription=A simple CalDAV (calendar) and CardDAV (contact) server\nAfter=network.target\nRequires=network.target\n\n[Service]\nExecStart=python3 -m radicale\nRestart=on-failure\nUser=radicale\n# Deny other users access to the calendar data\nUMask=0027\n# Optional security settings\nPrivateTmp=true\nProtectSystem=strict\n#ProtectHome=true\nPrivateDevices=true\nProtectKernelTunables=true\nProtectKernelModules=true\nProtectControlGroups=true\nNoNewPrivileges=true\nReadWritePaths=/home/radicale/collections\n\n[Install]\nWantedBy=multi-user.target\n

启动测试：

systemctl enable --now radicale\nsystemctl status radicale\n

如有异常，请增加配置：

[logging]\nlevel = debug\n

Nginx 反代提供 SSL 访问

参考以下配置：

server {\n        listen          443 ssl http2;\n        listen          [::]:443 ssl http2;\n        server_name radicale.example.com;\n        index index.html index.htm index.php default.html default.htm default.php;\n\n        # ssl cert ...\n        # security ...\n\n        location ^~ /{\n                proxy_pass          http://localhost:5232;\n        }\n        access_log off;\n}\n

nginx -t\nsystemctl reload nginx\n

Radicale 使用

访问 https://radicale.example.com ，在界面中输入任意的（或在上面步骤中使用 htpasswd 创建的）用户名和密码，即可登录。

vCards 打包脚本改造

2022-04-13 vCards 已经支持输出 Radicale 格式的数据文件。在 vCards 目录中执行 npm run-script radicale，然后再链接 radicale 目录到 /home/radicale/collections/collection-root/cn 即可。

2022-04-12 vCards 版本更新，以下代码不再具参考性。

sudo su -l radicale -s /bin/bash\ncd ~\ngit clone https://github.com/metowolf/vCards.git\n

编辑 package.json

    \"build\": \"npm run gulp build\",\n+    \"build-radicale\": \"npm run radicale build\",\n    \"gulp\": \"gulp --gulpfile src/gulpfile.js --cwd ./\",\n+    \"radicale\": \"gulp --gulpfile src/gulpfile-radicale.js --cwd ./\",\n

cd vCards\ncp src/plugins/vcard.js src/plugins/vcard-radicale.js\ncp src/gulpfile.js src/gulpfile-radicale.js\n

编辑 src/plugins/vcard-radicale.js

const vCardsJS = require('vcards-js')\n+const execSync = require('child_process').execSync\n...\n    vCard[key] = value\n  }\n+ if (!vCard.uid){\n+    vCard.uid = vCard.organization\n+  }\n+\n+  vCard.photo.embedFromFile(path.replace('.yaml', '.png'))\n+  let lastYamlChangeDateString = execSync('git log -1 --pretty=\"format:%ci\" ' + path).toString().trim().replace(/\\s\\+\\d+/, '')\n+  let lastPngChangeDateString = execSync('git log -1 --pretty=\"format:%ci\" ' + path.replace('.yaml', '.png')).toString().trim().replace(/\\s\\+\\d+/, '')\n+\n+  let rev = new Date(Math.max(new Date(lastYamlChangeDateString), new Date(lastPngChangeDateString))).toISOString()\n+\n+  formatted = vCard.getFormattedString()\n+  formatted = formatted.replace(/REV:[\\d\\-:T\\.Z]+/, 'REV:' + rev)\n+  file.contents = Buffer.from(formatted)\n-  file.contents = Buffer.from(vCard.getFormattedString())   \n

编辑 src/gulpfile-radicale.js

+const fs = require('fs')\nconst del = require('del')\n...\n+const createRadicale = () => {\n+  let folders = fs.readdirSync('temp')\n+    .filter(function(f) {\n+      return fs.statSync(path.join('temp', f)).isDirectory();\n+    })\n+  folders.map(function(folder){\n+    fs.writeFileSync(path.join('temp', folder, '/.Radicale.props'), '{\"D:displayname\": \"' + folder + '\", \"tag\": \"VADDRESSBOOK\"}')\n+  })\n+  return src('temp/**', {})\n+}\n+\n+const cleanRadicaleCN = () => {\n+  return del([\n+    '/home/radicale/collections/collection-root/cn'\n+  ], {force: true})\n+}\n+\n+const distRadicaleCN = () => {\n+  return src('temp/**', {dot: true})\n+    .pipe(dest('/home/radicale/collections/collection-root/cn'))\n+}\n...\nexports.archive = archive\n-exports.build = series(test, clean, generator, combine, allinone, archive)\n+exports.build = series(test, clean, generator, createRadicale, cleanRadicaleCN, distRadicaleCN)\n

执行任务

npm run-script build-radicale\n

定时任务

可参考：

cd /home/radicale/vCards\ngit pull\nnpm run-script build-radicale\n

并以 radicale 用户身份添加 crontab 定时任务。

订阅导入

iOS

设置>邮件>账户>添加账户>其他>（通讯录）添加 CardDAV 账户：

服务器： radicale.example.com (或 https://radicale.example.com)
用户名： cn
密码：任意填写
描述：任意填写（因为 iOS 的 Bug，并不能随时修改，建议填写为「中国黄页」）

点击右上存储，在接下来弹出的提示中选择「保留通讯录」。

ThunderBird

需要安装 TbSync 及 Provider for CalDav & CardDav 扩展。工具>Synchronization Settings(TbSync)，Account actions > CalDav & CardDav，选择 Manual Configuration。

Account name: 中国黄页
User name: cn
Password: 任意填写
CalDAV server address: 留空
CardDAV Server address: radicale.example.com (或 https://radicale.example.com)

勾选 Enable and synchronize this account，然后选择要同步的分组，点击 Synchronize now 按钮。

其他

注意：路径 /home/radicale/collections/collection-root/cn 中最后一级目录 cn 与订阅导入所需要的用户名一致，必须为英文，否则在某些客户端（如 iOS）中将无法同步。

2022-01-11 可尝试使用由 vCards 的作者 metowolf 提供的公开订阅服务：vcards.metowolf.com (使用方法参考上方「订阅导入」，以 vcards.metowolf.com替换radicale.example.com)

\n","headings":[{"level":2,"text":"vCards","id":"vcards"},{"level":2,"text":"Radicale","id":"radicale"},{"level":3,"text":"搭建 Radicale 实例","id":"搭建-radicale-实例"},{"level":4,"text":"安装","id":"安装"},{"level":4,"text":"权限配置","id":"权限配置"},{"level":4,"text":"配置文件","id":"配置文件"},{"level":4,"text":"私有 Radicale 的额外配置","id":"私有-radicale-的额外配置"},{"level":4,"text":"系统服务","id":"系统服务"},{"level":4,"text":"Nginx 反代提供 SSL 访问","id":"nginx-反代提供-ssl-访问"},{"level":3,"text":"Radicale 使用","id":"radicale-使用"},{"level":2,"text":"vCards 打包脚本改造","id":"vcards-打包脚本改造"},{"level":3,"text":"定时任务","id":"定时任务"},{"level":2,"text":"订阅导入","id":"订阅导入"},{"level":3,"text":"iOS","id":"ios"},{"level":3,"text":"ThunderBird","id":"thunderbird"},{"level":2,"text":"其他","id":"其他"}],"meta":{"prism":true},"links":[{"href":"https://dallas.lu/build-vcards-carddav-service-with-radicale-on-ubuntu-24-04/","type":"mention"},{"href":"https://github.com/metowolf/vCards","type":"mention"},{"href":"https://github.com/Kozea/Radicale","type":"mention"},{"href":"https://radicale.org/3.0.html#documentation/configuration","type":"mention"},{"href":"https://radicale.example.com","type":"mention"},{"href":"https://i-meto.com","type":"mention"}]},"newer":"/apache-subversion-behind-nginx/","earlier":"/ubuntu-fava-server/"}]

标签: Radicale

使用 Radicale 在 Ubuntu 24.04 中搭建 vCards CardDav 服务

2024

为 vCards 搭建 Radicale CardDav 服务器

2021