Xandikos 0.4.10 配置参数详解

Xandikos 0.4.10 配置面全量详解：serve 子命令 40+ 参数五类分组（基础/访问/出站 iMIP/LMTP/milter/WebDAV-Push）、htpasswd 哈希格式与 --autocert 启动红线、state-dir 与 Git 身份、环境变量等价、Docker env 映射，全部改参→重启→curl 验证闭环实测。

XandikosXandikosCalDAVCardDAV自托管2026/11/02

Xandikos 0.4.10 配置参数详解

Xandikos 没有配置文件，全部配置面 = xandikos serve 的 CLI 参数（iMIP 出站部分另有 XANDIKOS_* 环境变量等价）+ Docker 镜像的 env 映射 + Git 仓库自身的 config。本文按官方 --help 分组全量覆盖，每条关键参数给出"改参 → 重启 → 验证"实测闭环（取证：/opt/data/quzuo/tmp/xandikos/evidence.md §7）。

一、参数总览（serve 子命令）

组参数
存储与初始化-d/--directory（必填）、--autocreate、--defaults、--state-dir
身份与路由--current-user-principal、--route-prefix
监听-l/--listen-address（支持 unix socket 路径）、-p/--port、--socket-mode、--socket-group、--no-detect-systemd、--metrics-port
TLS 与认证--autocert、--htpasswd、--trust-x-remote-user-from
客户端兼容/调试--no-strict、--dump-dav-xml、--debug、--eager、--avahi
出站 iMIP (RFC 6047)--imip-send {off,sendmail,smtp}、--smtp-from、--smtp-host/--smtp-port/--smtp-encryption/--smtp-user/--smtp-password-file、--sendmail-binary
入站 iMIP--imip-listen（LMTP：unix:/sock 或 host:port）、--imip-listen-mode、--imip-listen-group
Milter--milter-listen、--milter-listen-mode、--milter-listen-group
推送--webdav-push

二、存储与初始化组

  • -d/--directory：数据根。每个 DAV 集合是其下独立 Git 仓库（实测 user/calendars/calendar/.git 等）。路径不存在且无 --autocreate 时拒绝启动。
  • --defaults：建 principal 时同时创建默认日历+地址簿+inbox/outbox（隐含 --autocreate）。实测日志逐字：Create calendar in .../user/calendars/calendar. 四行。
  • --autocreate：仅自动补目录结构，不建默认集合。
  • --state-dir DIR：TLS 证书、VAPID 密钥等服务状态，与用户数据分离。默认 $XDG_DATA_HOME/xandikos。实测 --autocert 生成 /root/.local/share/xandikos/certs/selfsigned.{crt,key}；Docker 镜像默认 /data/state（vapid/private.pem 实测落盘）。

三、身份与路由组

  • --current-user-principal /user/（默认）：单用户模式的核心身份参数，决定 PROPFIND 根的 current-user-principal 与写权限归属。实测改为 /foo/ 后根属性即变。
  • --route-prefix /dav：反代前缀。实测闭环： 
    $ xandikos serve -d data -p 8167 --route-prefix /dav
$ curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8167/dav/user/   # 200
$ curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8167/user/       # 404
    注意与反代 X-Forwarded-Prefix 方案二选一，官方口径是反代 strip 前缀 + 本参数。

四、监听组

  • -l/--listen-address：可传 IP 或 unix socket 路径（如 /run/xandikos.sock）。
  • -p/--port：默认 8080。实测本批次用 8165-8171 多实例并存。
  • --socket-mode 660 --socket-group www-data：仅 unix socket 生效，配合 nginx 反代免 TCP 暴露（实测支持）。
  • --no-detect-systemd：关闭 systemd socket activation 探测（serve 默认检测 LISTEN_FDS，官方 deployment 页双单元方案）。
  • --metrics-port：独立 Prometheus/OpenMetrics 端口。实测红线：--metrics-port == --port 启动即拒（源码校验）；缺 aiohttp-openmetrics 时仅警告 aiohttp-openmetrics not found; /metrics will not be available. 且 /metrics→404；pipx inject xandikos aiohttp-openmetrics 后重启 → /metrics 200（process_virtual_memory_bytes 1.52e8 等）。

五、TLS 与认证组（重点实测）

  • --autocert：自签 HTTPS，仅限开发测试（官方 help 原文 "do not use in production"）。缺 cryptography 时启动即退： 
    xandikos: error: The 'cryptography' package is required for --autocert. Install it with: pip install cryptography
  • --htpasswd FILE：Apache 风格 Basic 认证。三条实测红线/闭环：
    1. 必须搭配 --autocert（或反代 TLS），否则拒绝启动：--htpasswd requires --autocert. Basic authentication sends credentials in cleartext and must not be served over plain HTTP.；
    2. 哈希格式仅支持 bcrypt（$2y$/$2b$/$2a$，需 bcrypt 包，推荐 htpasswd -B）与 {SHA}；$apr1$/传统 crypt 明确拒绝并报可操作错误（源码 htpasswd.py）；
    3. 改参闭环：{SHA} 文件 + autocert 启动 8166 → 无凭据 PROPFIND 401、正确口令 207、错误口令 401；文件 mtime 变化热重载（_maybe_reload，无需重启）。
  • --trust-x-remote-user-from ADDR/CIDR（可多次）：仅当反代已鉴权并覆盖 X-Remote-User 头时使用；不加此参数该头一律忽略（防伪造 principal，官方 help 明确警告）。反代做认证时不要用 --htpasswd。

六、客户端兼容/调试组

  • --no-strict：对 buggy CalDAV/CardDAV 客户端开工作区（老版本部分 iOS/Android 客户端需要）。
  • --dump-dav-xml：把 DAV XML 请求/响应打到 stdout，协议排障第一开关。
  • --debug：DEBUG 级日志。
  • --eager：启动即预建全部集合索引（.xandikos 下 SQLite），换首查速度、牺牲冷启动；数据量大时配合 --index-threshold（Docker env 暴露，控制自动建索引的条目阈值）。
  • --paranoid：索引双重校验（源码 double_check_indexes）。
  • --avahi：mDNS 广播服务，局域网客户端自动发现。

七、iMIP 与 Milter 组（日程邮件面）

  • --imip-send {off,sendmail,smtp}：出站邀请投递模式，默认 off；env XANDIKOS_IMIP_SEND 等价。配套 --smtp-from（服务器身份，发起者走 Reply-To）、--smtp-host/--smtp-port（默认 25）/--smtp-encryption {none,starttls,ssl}/--smtp-user/--smtp-password-file、--sendmail-binary（默认 /usr/sbin/sendmail）。
  • --imip-listen unix:/sockets/imip.sock：LMTP 入站监听，Postfix/Sieve 可直接投递，替代管道 xandikos import-imip。
  • --milter-listen：进程内 SMFI milter，Postfix smtpd_milters=<target> 指向它；独立进程形态见 xandikos-milter 命令（D1 篇）。
  • --webdav-push：WebDAV-Push 草案（客户端省轮询）。缺依赖红线实测：py_vapid is required for WebDAV-Push; install xandikos[webdav-push]；Docker 镜像默认开启。

八、multi-user 子命令差异参数

xandikos multi-user 继承 serve 全部访问参数，替换/新增：

  • --principal-path-prefix / --principal-path-suffix：principal 路径模板；
  • --defaults：语义变为"每个新用户自动建默认集合"；
  • --hide-principals：根页不列 principal。
  • 实测启动即 WARNING 逐字：Multi-user mode is experimental, may not be stable and not yet provide sufficient isolation between users. Use with caution.；未认证时根 PROPFIND 返回 <unauthenticated/>。生产多用户建议反代鉴权 + 单用户实例矩阵，而非押注此模式。

九、Git 身份与钩子

  • commit 作者取宿主 Git 身份（config/env：实测本机为 myquzuo <myquzuo@163.com>），部署账号应显式配置 user.name/user.email，否则审计信息不可控；
  • 集合仓库是标准 Git 仓库，原生 git hooks 可用（如 post-commit 通知/同步远端备份），这是"钩子配置"的唯一形态——Xandikos 自身无 webhook 机制；
  • .xandikos INI 文件（type/displayname/color）由 PROPPATCH/create-collection 维护，勿手改。

十、Docker 镜像 env 映射

entrypoint.sh 将上述参数全部 env 化（布尔取 true/1）：PORT、METRICS_PORT、LISTEN_ADDRESS、DATA_DIR、CURRENT_USER_PRINCIPAL、ROUTE_PREFIX、AUTOCREATE、DEFAULTS、DUMP_DAV_XML、AVAHI、NO_STRICT、DEBUG、PARANOID、INDEX_THRESHOLD、EAGER、NO_DETECT_SYSTEMD、AUTOCERT、WEBDAV_PUSH（默认开）、STATE_DIR（默认 /data/state）、HTPASSWD、IMIP_LISTEN、IMIP_LISTEN_MODE/GROUP、MILTER_LISTEN/MODE/GROUP；socket 类可填 auto → unix:/sockets/*.sock。传任何命令行参数会绕过整套 env 逻辑（直接 python3 -m xandikos "$@"），官网示例因此失效（见 B2 纠偏）。

十一、改参验证方法学（速查）

改动验证命令预期
--route-prefixcurl -o /dev/null -w "%{http_code}" <prefix>/user/200；裸 /user/ 404
--htpasswd+--autocertcurl -k -u u:p -X PROPFIND ...401/207/401 三态
--metrics-portcurl :metrics/metrics缺依赖 404，注入后 200
--current-user-principalPROPFIND 根href 即新值
--defaults重启看日志Create calendar/addressbook/inbox/outbox 四行
--autocertss -tlnp + curl -kHTTPS 可连，certs 落 state-dir
Xandikos 0.4.10 配置参数详解 - Quzuo