Radicale 3.9 常用 CLI 命令与运维详解

目标：汇总 Radicale 日常运维的全部命令工具——radicale 主命令（含存储校验）、htpasswd 用户管理、systemd 服务管理与日志排障、curl 协议自检、数据备份恢复，以及 Thunderbird/DAVx⁵ 客户端对接。所有命令与回显均为 Ubuntu 22.04 + Radicale 3.9.0 实测结果。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Radicale：3.9.0，venv 安装于 /opt/radicale-venv（安装见《Ubuntu 22.04 安装 Radicale 3.9 指南（pip + venv + systemd）》）
配置文件：/etc/radicale/config；口令文件：/etc/radicale/users；数据目录：/var/lib/radicale/collections
服务端口：5232（监听 0.0.0.0:5232）
演示账号：admin / root，密码 q1w2e3r4（htpasswd 认证）
服务管理：systemd（unit 名 radicale.service）

二、工具概览

Radicale 本身是单命令程序（没有多级子命令），日常运维由五类工具组合完成：

工具	角色	典型场景
`radicale`	服务主命令	启动服务、校验存储/条目/共享库
`htpasswd`	口令文件管理	增删改用户、换哈希类型
`systemctl` / `journalctl`	systemd 服务与日志	启停、开机自启、排障看日志
`curl`	CalDAV/CardDAV 协议自检	不装客户端验证服务健康
`tar`	数据备份	收集/恢复 collections 目录

💡 说明：Radicale 官方不提供「管理 CLI」（如建用户的子命令）——用户管理即维护 htpasswd 文件，数据管理即操作 collections 目录文件。这是「文件即数据库」设计的直接体现，也是它零依赖哲学的一部分。

三、前置条件

服务已安装并运行（确认命令与回显）：

systemctl is-active radicale    # 确认服务状态

active

命令 PATH 说明：Radicale 装在 venv 内，本文统一用全路径 /opt/radicale-venv/bin/radicale；也可 export PATH=/opt/radicale-venv/bin:$PATH 后直接敲 radicale。

四、各工具详解

4.1 radicale 主命令

4.1.1 帮助与版本

/opt/radicale-venv/bin/radicale --help

实测回显（节选，总选项组）：

usage: radicale [OPTIONS]

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --verify-storage      check the storage for errors and exit
  --verify-item VERIFY_ITEM
                        check the provided item file for errors and exit
  --verify-sharing      check the sharing database for errors and exit
  -C [CONFIG ...], --config [CONFIG ...]
                        use specific configuration files
  -D, --debug           print debug information

/opt/radicale-venv/bin/radicale --version

实测回显：

[2026-10-30 02:46:40 +0000] [36] [INFO] Logging level set to: 'INFO'
[2026-10-30 02:46:40 +0000] [36] [INFO] Logging of backtrace is disabled in this loglevel
3.9.0

--help 按 section 分组列出全部选项（server 段节选）：

server:
  backend specific options omitted

  --server-type VALUE   server to use (builtin|hypercorn), hypercorn also
                        serves H2C and needs the "h2" extra (pip install
                        radicale[h2])
  -H VALUE, --hosts VALUE, --server-hosts VALUE
                        set server hostnames including ports
  --server-max-connections VALUE
                        maximum number of parallel connections
  --server-max-content-length VALUE
                        maximum size of request body in bytes (default: 100
                        Mbyte)
  --server-delay-on-error VALUE
                        base delay in case of error 5xx response (seconds)
  --server-max-resource-size VALUE
                        maximum size of resource (default: 10 Mbyte)
  --server-max-vevent-rrule-occurrence VALUE
                        maximum occurrence by an RRULE (default: 10000)
  --server-timeout VALUE
                        socket timeout
  -s [VALUE], --ssl [VALUE], --server-ssl [VALUE]
                        use SSL connection
  -S, --no-ssl, --no-server-ssl
                        do not use SSL connection (opposite of --server-ssl)
  --server-protocol VALUE
                        SSL/TLS protocol (Apache SSLProtocol format)

参数含义与配置文件的对应关系见《Radicale 3.9 配置参数详解》。

4.1.2 前台启动与配置覆盖

不依赖 systemd 手动前台运行（调试常用），并用命令行覆盖监听地址：

/opt/radicale-venv/bin/radicale --config /etc/radicale/config --hosts 0.0.0.0:5232

实测回显（前台启动后立即打印的信息，节选）：

[2026-10-30 02:47:12 +0000] [2703] [INFO] Logging level set to: 'INFO'
[2026-10-30 02:47:12 +0000] [2703] [INFO] permit delete of collection: True

按 Ctrl+C 停止。调试期追加 -D（等价 [logging] level = debug）可看完整请求日志。

4.1.3 存储完整性校验（--verify-storage）

离线检查 collections 数据树的错误（服务可停可不停，建议维护窗口跑）：

/opt/radicale-venv/bin/radicale --config /etc/radicale/config --verify-storage 2>&1 | head -12

实测回显（节选）：

[2026-10-30 02:52:20 +0000] [2900] [INFO] Loaded default config
[2026-10-30 02:52:20 +0000] [2900] [INFO] Loaded config file '/etc/radicale/config'
[2026-10-30 02:52:20 +0000] [2900] [INFO] Verifying storage
[2026-10-30 02:52:20 +0000] [2900] [INFO] storage type is 'radicale.storage.multifilesystem'
[2026-10-30 02:52:20 +0000] [2900] [INFO] Storage folder umask (from system): '0022'
[2026-10-30 02:52:20 +0000] [2900] [INFO] Storage location: '/var/lib/radicale/collections'
[2026-10-30 02:52:20 +0000] [2900] [INFO] Storage location permissions: path='/var/lib/radicale/collections' owner=radicale(999) group=radicale(999) mode=40755

回显逐行给出存储后端类型、目录权限与属主核对结果——数据异常（断行/坏条目）时会输出 ERROR 行。配套的 --verify-item <文件路径> 校验单个 .ics/.vcf 文件，--verify-sharing 校验共享数据库（启用共享时）。

4.2 用户管理：htpasswd

Radicale 无「建用户」命令，htpasswd 认证下用户即口令文件行。首次创建文件用 -c（重复使用会清空文件），追加用户不带 -c：

htpasswd -mb -c /etc/radicale/users admin q1w2e3r4    # 创建口令文件并添加 admin（-m MD5-APR1，-b 命令行传密码）
htpasswd -mb /etc/radicale/users root q1w2e3r4        # 追加 root（无 -c）

实测回显：

Adding password for user admin
Adding password for user root

常用维护操作（命令即实测命令）：

htpasswd -mb /etc/radicale/users alice 'n3w-Pass'    # 新增用户 alice
htpasswd -mB /etc/radicale/users bob                  # 交互式设置 bob 密码（-B bcrypt，需 radicale[bcrypt] 扩展）
htpasswd -vb /etc/radicale/users admin q1w2e3r4       # 验证口令是否正确
htpasswd -D /etc/radicale/users alice                 # 删除用户 alice

实测回显（验证操作）：

Password for user admin correct.

⚠️ 注意：htpasswd -c 一定只在首次创建时用；加密类型（-m MD5-APR1 / -B bcrypt）要与 /etc/radicale/config 的 htpasswd_encryption 匹配（autodetect 可自动识别，混用哈希类型的文件也能读）。

改完口令文件立即生效（每次认证都读文件）；若开启了 [auth] htpasswd_cache = True，需 systemctl restart radicale。

4.3 服务管理与日志：systemctl / journalctl

systemctl start radicale      # 启动服务
systemctl stop radicale       # 停止服务
systemctl restart radicale    # 重启服务（改配置后）
systemctl status radicale     # 查看运行状态
systemctl enable radicale     # 设置开机自启
systemctl disable radicale    # 取消开机自启

状态详情实测回显（节选）：

* radicale.service - A simple CalDAV (calendar) and CardDAV (contact) server
     Loaded: loaded (/etc/systemd/system/radicale.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2026-10-30 02:47:12 UTC; 2s ago
   Main PID: 2703 (radicale)
      Tasks: 1 (limit: 2266)
     Memory: 19.5M
        CPU: 96ms

排障三板斧（journalctl 看 Radicale 日志）：

journalctl -u radicale -n 20 --no-pager    # 最近 20 行日志
journalctl -u radicale -f                             # 实时跟踪日志（Ctrl+C 退出）
journalctl -u radicale --since "1 hour ago" --no-pager    # 最近 1 小时日志

关键日志样例实测回显：

登录成功/失败（认证排障最常用）：

Oct 30 02:47:47 radicale radicale[2703]: [2703/Thread-8 (process_request_thread)] [INFO] Successful login: 'admin' (htpasswd)
Oct 30 03:07:22 radicale radicale[2891]: [2857/Thread-2 (process_request_thread)] [WARNING] Login verification failed for user: 'admin' (htpasswd/md5/MD5-APR1)
Oct 30 03:07:22 radicale radicale[2891]: [2857/Thread-2 (process_request_thread)] [WARNING] Failed login attempt from 10.89.57.1: 'admin' (htpasswd)

失败日志直接给出用户、来源 IP、认证方式与哈希类型，配合 [auth] delay 默认 1 秒延迟可缓解爆破。

权限拒绝（403 排障）：

Oct 30 02:50:51 radicale radicale[2857]: [2857/Thread-1 (process_request_thread)] [WARNING] MKCOL request '/admin/contacts/' (type:UNKNOWN): rejected because of missing rights 'W'
Oct 30 02:50:51 radicale radicale[2857]: [2857/Thread-1 (process_request_thread)] [NOTICE] Access to '/admin/contacts/' denied for 'admin'

4.4 协议自检：curl 一套

不装任何客户端，用 curl 验证服务健康度（四连，替换 -u 后的账号密码即可复用）：

# ① 未认证应 401
curl -s -o /dev/null -w "anonymous: %{http_code}\n" -X PROPFIND http://127.0.0.1:5232/admin/
# ② 认证后应 207（用户 principal 发现）
curl -s -o /dev/null -w "authed propfind: %{http_code}\n" -u admin:q1w2e3r4 -X PROPFIND -H "Depth: 0" http://127.0.0.1:5232/admin/
# ③ Web 界面应 200
curl -s -o /dev/null -w "web ui: %{http_code}\n" -u admin:q1w2e3r4 http://127.0.0.1:5232/.web/
# ④ 建一个测试日历（成功即 201；已存在返回对应冲突码也算服务正常）
curl -s -o /dev/null -w "mkcalendar: %{http_code}\n" -X MKCALENDAR -u admin:q1w2e3r4 http://127.0.0.1:5232/admin/healthcheck/

实测回显：

anonymous: 401
authed propfind: 207
web ui: 200
mkcalendar: 201

💡 说明：这四条覆盖了「认证拦截 → 认证通过 → 界面可用 → 可写集合」四个健康维度，可直接放进监控探活脚本；协议报文级完整验证（PROPFIND XML/MKCALENDAR/PUT 事件/REPORT 查询）见《Ubuntu 22.04 安装 Radicale 3.9 指南（pip + venv + systemd）》4.7 节。

4.5 数据备份与恢复

Radicale 的全部数据就是 collections 目录，备份/恢复是纯文件操作。

备份（tar 打包，文件名带日期）：

tar -C /var/lib/radicale -czf /var/backups/radicale-collections-$(date +%Y%m%d).tar.gz collections

实测回显（打包后核验包内容与体积）：

ls -lh /var/backups/radicale-collections-*.tar.gz

-rw-r--r-- 1 root root 1.5K Oct 30 03:07 /var/backups/radicale-collections-20261030.tar.gz

tar -tzf /var/backups/radicale-collections-20261030.tar.gz | head -5

collections/
collections/collection-root/
collections/collection-root/admin/
collections/collection-root/admin/contacts/
collections/collection-root/admin/contacts/.Radicale.props

⚠️ 注意：热备（服务运行中打包）有极小概率撞上写入瞬间，产生个别条目不一致；严格备份先 systemctl stop radicale 再打包，打完再 start。数据量小（千级条目 MB 级）时停机备份代价可忽略。建议用 systemd timer 或 crontab 每日备份并保留 7~30 天滚动。

恢复（换机/灾难场景）：

systemctl stop radicale                                       # 先停服务
tar -C /var/lib/radicale -xzf /var/backups/radicale-collections-20261030.tar.gz    # 解包覆盖
chown -R radicale:radicale /var/lib/radicale                  # 校正属主（关键）
/opt/radicale-venv/bin/radicale --config /etc/radicale/config --verify-storage    # 校验完整性
systemctl start radicale                                      # 启动并验证

恢复后跑一次 4.4 的 curl 四连自检即可确认业务恢复。

4.6 升级与版本管理

/opt/radicale-venv/bin/pip install -U radicale    # 升级到最新稳定版（配置与数据不受影响）
systemctl restart radicale                        # 重启加载新版本
/opt/radicale-venv/bin/radicale --version         # 复核版本

实测回显（--version 尾行）：

3.9.0

五、客户端对接（Thunderbird / DAVx⁵ / Apple 日历）

服务端就绪后，客户端只需两个信息：CalDAV/CardDAV 地址 与 htpasswd 账号密码。

5.1 Thunderbird（桌面日历+通讯录）

Thunderbird 内置 Calendar（Lightning 已合并进主程序），原生支持 CalDAV/CardDAV：

日历：左侧日历视图 → 右键「新建日历」→ 选「网络上的日历」→ 格式选 CalDAV → 地址填 http://<服务器IP>:5232/admin/（用户名 admin）→ 首次同步时输入密码 q1w2e3r4。
通讯录：地址簿 → 新建地址簿 → 类型选 CardDAV → URL 填 http://<服务器IP>:5232/admin/contacts/。
若服务前置了 HTTPS 反代，把地址换成 https://dav.example.com/admin/ 形态（推荐，口令不裸奔）。

对接成功后，Thunderbird 建的日程即写入服务端 collections/collection-root/admin/ 下对应日历目录的 .ics 文件，与 4.5 的备份体系无缝衔接。

5.2 DAVx⁵（Android 统一同步）

Android 无原生 CalDAV/CardDAV 客户端，标准方案是开源的 DAVx⁵（Play 商店/F-Droid 均有）：

添加账号：输入 基础 URL http://<服务器IP>:5232/admin/ + 用户名 admin + 密码 q1w2e3r4，DAVx⁵ 会自动做 principal 发现（对应服务端 PROPFIND current-user-principal，已在 4.4 验证）。
勾选要同步的日历与地址簿集合，授予 Android 联系人/日历权限。
系统日历 App 与联系人 App 中即出现对应账户的数据，双向实时同步。

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

系统设置 → 日历 → 账户 → 添加其他日历账户 → CalDAV：服务器 dav.example.com，用户名/密码即 htpasswd 账号。通讯录同理选 CardDAV。

⚠️ 注意：iOS/Apple 客户端对 HTTP 明文 CalDAV 限制严格，建议配合 Nginx/Caddy 反代上 HTTPS 后再对接；证书相关方案见《Nginx HTTPS 与证书配置方案（certbot/自签名）》。

六、注意事项

htpasswd -c 只在首次建文件时用——第二次带 -c 会清空全部已有用户。
改配置必重启：/etc/radicale/config 的变更不重启不生效；htpasswd 口令文件默认热读（开 htpasswd_cache 后除外）。
数据目录属主：任何手工搬移数据后执行 chown -R radicale:radicale /var/lib/radicale，否则服务写不进。
日志口令安全：[logging] mask_passwords = True 保持默认开启；排障临时开 debug 后记得改回。
不要多进程写同一数据目录：Radicale 是单机单实例设计，官方不支持两实例共享 collections 目录。

七、常见问题（FAQ）

Q1：radicale 命令提示找不到？ Radicale 装在 venv 里，直接敲 radicale 不在 PATH。用全路径 /opt/radicale-venv/bin/radicale，或 export PATH=/opt/radicale-venv/bin:$PATH。

Q2：--verify-storage 报某条目损坏？ 按报错行定位到具体 .ics/.vcf 文件，用文本编辑器查看断行/编码问题；修不好可把该文件移出集合目录（等价删除该条目），再跑一次校验确认通过。[storage] skip_broken_item = True（默认开）时服务端会跳过坏条目不停摆，但应尽快修复。

Q3：客户端（Thunderbird/DAVx⁵）连上但看不到任何日历？ 分三步查：① 服务端确认用户有集合：curl 四连（4.4）验证 207/201；② 权限模型：默认 owner_only 下客户端只能看到自己用户名目录下的集合，账号要匹配；③ 服务端日志 journalctl -u radicale -f 盯着客户端的请求，看 401（密码错）还是 403（权限规则拒绝）。

Q4：忘记某用户密码？ 重新生成即可（htpasswd 无加密恢复概念）：htpasswd -mb /etc/radicale/users 用户名新密码。

Q5：如何把一位用户的日历共享给另一位？ 默认 owner_only 不支持跨用户访问。两条路：改用 owner_write（他人可读）/authenticated（全共享），或 [rights] type = from_file 写细粒度规则（3.9 权限字母体系见《Radicale 3.9 配置参数详解》5.4）。

八、参考链接

Radicale 官方文档：https://radicale.org/v3.html
官方教程（客户端对接）：https://radicale.org/tutorial.html
htpasswd 命令手册：https://httpd.apache.org/docs/2.4/programs/htpasswd.html
DAVx⁵ 官网：https://www.davx5.com/
Thunderbird 日历帮助：https://support.mozilla.org/kb/calendar

站内相关阅读：

《Radicale 介绍与选型指南》
《Ubuntu 22.04 安装 Radicale 3.9 指南（pip + venv + systemd）》
《Radicale 3.9 配置参数详解》
《Nginx HTTPS 与证书配置方案（certbot/自签名）》：https://www.quzuo.net/document/5edEKp5tnuw2
《Nginx 运维与监控方案（变量/日志/stub_status）》：https://www.quzuo.net/document/ubEUkgsJUJsV
《Ubuntu 24.04 Docker CLI 常用命令与运维指南》：https://www.quzuo.net/document/KGiImqdTGb3W