Radicale 3.9 配置参数详解

目标：逐一讲清 Radicale 3.9.0 全部 12 个配置 section（server/encoding/auth/group/rights/storage/sharing/hook/web/logging/headers/reporting）的参数含义、默认值与生产建议，并给出可直接落地的生产配置模板。参数默认值取自本机安装的 radicale 3.9.0 包内配置模式（DEFAULT_CONFIG_SCHEMA）实取，配置生效行为经 Ubuntu 22.04 实测。

一、环境信息

• 操作系统：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（INI 格式）
• 数据目录：/var/lib/radicale/collections
• 参数口径：本文「默认值」全部实取自 radicale 3.9.0 安装包内 radicale/config.py 的 DEFAULT_CONFIG_SCHEMA（3.9.0 真实内置值，非文档转述）；「实测」指在本环境真实执行并记录回显。
• 服务管理：systemd（unit 名 radicale.service）

二、前置条件

阅读与验证本文需要：

1. 已按《Ubuntu 22.04 安装 Radicale 3.9 指南（pip + venv + systemd）》完成安装并确认服务运行：

systemctl is-active radicale    # 确认服务在跑

实测回显：

active

2. 了解 INI 配置格式（[section] 分节、key = value 键值对）与 systemd 基本操作（systemctl restart/daemon-reload）。

三、参数查看与修改方式

Radicale 的配置有三个来源层，优先级从高到低：命令行参数 > 配置文件 > 内置默认值。三者键名一一对应（如配置键 [server] hosts 对应命令行 --hosts），运维中最常用的是「配置文件为主、命令行临时覆盖」。

3.1 查看全部命令行参数

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

实测回显（节选，总选项与 server 段）：

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

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
  ...

--help 输出按 section 分组（server/auth/storage/web/logging/headers…），每个键都有对应的 --<section>-<key> 长选项，帮助文本中标注了默认值（如 --server-max-content-length 默认 100 Mbyte）。全部命令行用法见《Radicale 3.9 常用 CLI 命令与运维详解》。

3.2 修改配置的标准流程

改 /etc/radicale/config 后必须重启服务才生效：

vi /etc/radicale/config    # 编辑配置
systemctl restart radicale    # 重启生效
systemctl is-active radicale    # 确认重启成功

实测回显（演示把日志级别改为 debug 再改回 info 的完整循环）：

sed -i "s/^level = info/level = debug/" /etc/radicale/config    # 日志级别 info → debug
systemctl restart radicale

（重启后无输出，is-active 返回 active 即成功）

journalctl -u radicale --no-pager -n 3    # debug 级别下日志明显变多

Oct 30 02:50:50 radicale radicale[2857]: [2857] [INFO] rights type is 'radicale.rights.owner_only'
Oct 30 02:50:50 radicale radicale[2857]: [2857] [INFO] rights type is 'radicale.rights.owner_only'
Oct 30 02:50:51 radicale radicale[2857]: [2857/Thread-1 (process_request_thread)] [INFO] MKCOL request for '/admin/contacts/' received from 10.89.57.1 using 'curl/8.18.0' HTTP/1.1

⚠️ 注意：配置文件写错（如 section 名拼错、布尔值写成 yes/1 之外的字符串）时，服务可能启动失败。此时 systemctl status radicale 显示 failed，journalctl -u radicale -n 30 里会有具体解析错误行，改正后再次 systemctl restart radicale 即可。

四、参数总览

Radicale 3.9.0 共 12 个 section。下表为全景速览（各 section 的默认值均实取自 3.9.0 包内 DEFAULT_CONFIG_SCHEMA）：

💡 技术拓展：配置「层级合并」是 INI 类服务器的通用设计——

方式	优先级	典型用途
命令行参数	最高	临时调试、脚本启动
配置文件（-C 指定或默认路径）	中	生产持久配置（本文主线）
内置默认值	最低	兜底，不写即用默认

Radicale 还允许 -C 传入多个配置文件（后者覆盖前者同名键），便于「基础配置 + 环境差异化配置」分层管理。本文方案采用 /etc/radicale/config 单文件，理由是服务器场景无需多环境。

五、核心参数分类详解

以下按 section 逐组讲解。加粗的是生产环境最该关注的键。

5.1 [server]：监听与连接

控制服务如何对外提供服务，是所有部署第一步要改的 section。

💡 技术拓展：对外 TLS 放在哪一层？常见三选——

方案	说明	取舍
Radicale 内置 SSL（ssl = True）	服务自己上 TLS	配置简单，但证书续期要自己处理
Nginx/Caddy 反代终结 TLS	反代对外 443，对内 HTTP 5232	证书统一管理，最主流（本文推荐）
不加密（内网裸奔）	仅限受信内网	快捷但明文传输口令

本文实测环境用内置 HTTP（ssl = False）+ 直连 5232 验证协议链路；生产对外推荐反代终结 TLS，可参考《Ubuntu 22.04 安装 Nginx 指南（apt/官方源/编译多方案）》或《Ubuntu 22.04 安装 Caddy 指南（apt 官方源 编译多方案）》。

5.2 [auth]：认证后端

Radicale 3.9 支持的认证后端（type 可选值实取自包内配置）：none、remote_user、http_x_remote_user、http_remote_user、denyall、htpasswd、ldap、imap、oauth2、pam、dovecot。

⚠️ 注意：本文 B1 安装篇实测采用 type = htpasswd + htpasswd_encryption = md5——零额外依赖且 htpasswd 命令原生支持；LDAP/IMAP/PAM 等后端适合企业已有账号体系的场景，切换后需重启服务。

5.3 [group]：用户组

组功能本身默认关闭（type = none）；个人/小团队单用户模式无需关注，需要「按组授权日历」时启用。

5.4 [rights]：权限模型

💡 技术拓展：3.9 的权限字母体系（实取自 3.9.0 包内 rights 模块常量 INTERNAL_PERMISSIONS = "RrifWwDdOoTtMmPpEel"）比旧版细得多，常用的几个：大写 R/W 为元数据级读/写（能否看到集合、能否创建/删除集合本体），小写 r/w 为内容级读/写（能否读写集合内的事件/联系人）。实测验证：默认 owner_only 下，用户 principal 根（/admin/）授 RW，两层路径（/admin/calendar/）授 rw——这正是「MKCOL 无类型集合报 403 缺 W」现象的根因（详见 B1 篇 FAQ Q2）。

5.5 [storage]：文件存储

⚠️ 注意：filesystem_folder 改动后必须保证该目录属主是运行用户（本文为 radicale），并重启服务；更换数据目录时先把旧目录完整拷贝再改配置。

5.6 [sharing]：集合共享（3.9 新增能力）

5.7 [hook]：变更通知（RabbitMQ/SMTP）

典型用途：把 Radicale 的日程变更推送到内部消息总线（RabbitMQ，运行时依赖 pika 已随主包装好）或给参会人发邮件。

5.8 [web] 与 [logging] 与 [headers] 与 [reporting]

[web]：

[logging]：

[headers]：默认空。按需添加自定义 HTTP 响应头，键即头名：

[headers]
X-Frame-Options = DENY

[reporting]：

5.9 [encoding]

保持默认即可；仅在与老旧客户端对接出现乱码时调整。

六、生产配置模板

以下模板适用于「2C4G 云服务器、NVMe SSD、小团队（≤50 人）个人日历/联系人自托管」场景，可直接替换到 /etc/radicale/config（示例域名 dav.example.com、反代后端形态、htpasswd 认证）：

[server]
hosts = 127.0.0.1:5232
max_connections = 16

[auth]
type = htpasswd
htpasswd_filename = /etc/radicale/users
htpasswd_encryption = bcrypt
delay = 1
cache_logins = true

[rights]
type = owner_only
permit_delete_collection = True

[storage]
filesystem_folder = /var/lib/radicale/collections
use_cache_subfolder_for_item = True
use_cache_subfolder_for_history = True
use_cache_subfolder_for_synctoken = True
skip_broken_item = True

[web]
type = internal

[logging]
level = warning
mask_passwords = True

[headers]
X-Frame-Options = DENY

[reporting]
max_expand_occurrence = 10000

模板要点解说：

1. hosts = 127.0.0.1:5232：只监听回环，对外一律走反代的 443 TLS（Nginx/Caddy 均可，见《Ubuntu 22.04 安装 Caddy 指南（apt 官方源 编译多方案）》）。
2. htpasswd_encryption = bcrypt：需先在 venv 内 pip install radicale[bcrypt]；口令文件改用 htpasswd -B 生成。若不愿装扩展，退回 md5（MD5-APR1）。
3. 缓存子目录三开关：把缓存移出集合目录，备份时整目录拷贝 collections 即可少拷缓存、且可对缓存目录单独排除。
4. level = warning：正常运行少刷日志，排障时临时调回 info/debug。

七、常见问题（FAQ）

Q1：改了配置不生效？ 三个检查点：① 是否 systemctl restart radicale（改文件不重启不生效）；② 键名是否写对（拼错会被忽略并回退默认值，journalctl 里留意警告）；③ 是否被更高优先级的命令行参数覆盖（检查 unit 的 ExecStart 是否带了 -- 参数）。

Q2：[auth] 保持默认 denyall 会怎样？ 所有请求（包括 Web 界面）一律 401。这是 3.9 的安全默认设计，见 B1 篇 FAQ Q1 的实测现象。

Q3：bcrypt 类型报错「bcrypt 未安装」？ htpasswd_encryption = bcrypt 依赖可选扩展：/opt/radicale-venv/bin/pip install radicale[bcrypt] 后重启；或改用 md5（无依赖）。argon2 同理装 radicale[argon2]。

Q4：自定义权限规则文件（type = from_file）怎么调试？ 规则不生效时：① 确认 file 路径正确、重启过服务；② 临时把 [logging] level 调到 debug 并开 rights_rule_doesnt_match_on_debug = True，日志会输出未命中的规则行；③ 注意权限字母大小写语义（R/W 元数据、r/w 内容，见 5.4 的技术拓展）。

Q5：反代之后路径多了前缀（如 /dav/）导致客户端 404？ 反代把 X-Script-Name: /dav 传给后端，或固定配置 [server] script_name = /dav；Radicale 会自动剥离该前缀（见 5.1 的 script_name 参数）。

八、参考链接

• Radicale 官方配置文档：https://radicale.org/v3.html#configuration
• 官方教程（含反代/认证章节）：https://radicale.org/tutorial.html
• GitHub 仓库（rights 模块源码）：https://github.com/Kozea/Radicale

站内相关阅读：

• 《Radicale 介绍与选型指南》
• 《Ubuntu 22.04 安装 Radicale 3.9 指南（pip + venv + systemd）》
• 《Radicale 3.9 常用 CLI 命令与运维详解》
• 《Nginx HTTPS 与证书配置方案（certbot/自签名）》：https://www.quzuo.net/document/5edEKp5tnuw2
• 《Ubuntu 22.04 安装 Nextcloud 指南》：https://www.quzuo.net/document/1T3AYvb8zbMj
• 《Nextcloud 配置参数详解》：https://www.quzuo.net/document/Zn9TlUIyxGqO