Baikal 0.10.1 配置参数详解

目标：把 Baikal 0.10.1 的配置体系（baikal.yaml 的 system 与 database 两大组、Specific/ 目录例外机制）逐参数讲透，覆盖查看/修改的四种途径、参数实测默认值、生产配置模板，以及实测踩到的两个坑（Web 后台切库异常、配置语法错误的降级行为）。全部默认值实取自本地 0.10.1 实例，行为均实测验证；部署背景见《Baikal 0.10.1 Docker Compose 部署指南》。

一、环境信息

• 软件版本：Baikal 0.10.1（官方 tar 包，包内 composer.json 声明 php: ^8.1、sabre/dav: ~4.7.0）
• 配置文件：/var/www/baikal/config/baikal.yaml（YAML 格式，Symfony Yaml 组件解析）
• 数据目录：/var/www/baikal/Specific/（数据库文件、安装器标记）
• 管理后台：https://dav.example.com/admin/（实测账号 admin / q1w2e3r4）
• 实测时区：Asia/Shanghai（安装向导中选择）

二、前置条件

1. 已完成部署与初始化向导（未部署先读部署指南）。
2. 能读到配置文件：管理后台「System Settings / Database settings」两页，或直接读服务器上的 config/baikal.yaml。
3. 修改文件前先备份：cp baikal.yaml baikal.yaml.bak（本文实测中所有破坏性验证均按此操作并已回滚）。

三、参数查看与修改方式

实测 Baikal 0.10.1 有四种修改途径，生效行为各不相同：

💡 说明：Baikal 0.10 起配置体系从早期版本的 PHP 数组文件（config.php 等）整体迁移为单一 baikal.yaml（Symfony Yaml 解析），本文所有键名以 0.10.1 实测文件为准。老资料里出现的 config.php 键名在 0.10.1 已不存在，迁移时按本篇键名对照。

⚠️ 注意：直接编辑 yaml 后用管理后台保存设置会以表单数据整体重写文件，手工注释会丢失；建议「手工改文件」与「后台改设置」不要混用于同一批键。

四、参数总览

实测 0.10.1 初始生成的完整配置文件（本机时区与发件地址已按示例填写）：

system:
    configured_version: 0.10.1
    timezone: Asia/Shanghai
    card_enabled: true
    cal_enabled: true
    dav_auth_type: Basic
    admin_passwordhash: 6d0d6c6b6555fbae363f90d862e8b11f8551196add2f99b1657e3759164bf2a5
    failed_access_message: 'user %u authentication failure for Baikal'
    auth_realm: BaikalDAV
    base_uri: ''
    invite_from: noreply@quzuo.net
database:
    sqlite_file: /var/www/baikal/Specific/db/db.sqlite
    backend: sqlite
    mysql_host: ''
    mysql_dbname: ''
    mysql_username: ''
    mysql_password: ''
    encryption_key: 364c3654d6fa672543f5ad13e7d531af
    pgsql_host: ''
    pgsql_dbname: ''
    pgsql_username: ''
    pgsql_password: ''

速查表：

五、核心参数分类详解

5.1 system 组：服务开关与基本行为

cal_enabled / card_enabled：实测管理后台 System Settings 页为两个复选框（data[cal_enabled]、data[card_enabled]，默认勾选）。作用在协议层：关闭后 DAV 入口不再挂载对应集合树——dav.php 下实测默认挂载 principals/、calendars/、addressbooks/ 三个顶层集合，关闭 CalDAV 则 calendars/ 不存在。后台 Dashboard 的 Services 区块同步显示 CalDAV/CardDAV 的 On/Off 状态（实测回显：Services | Web admin On | CalDAV On | CardDAV On）。

timezone：后台为下拉选择（实测选项为完整 PHP 时区表，从 Africa/Abidjan 起枚举）。写入 yaml 的就是 PHP 时区名。影响日历事件解析与日志时间戳，建议与系统时区一致。

base_uri：默认空。Baikal 需要部署在站点子路径（如 https://example.com/baikal/）时配置；源码逻辑为非空时覆盖应用基路径（自动补全首尾斜杠）。本文按独立域名部署，保持默认。

5.2 system 组：认证三件套（auth_realm / dav_auth_type / admin_passwordhash）

这是 Baikal 配置里最容易踩坑的一组，三者互相咬合：

dav_auth_type（可选 Digest / Basic / Apache）：DAV 协议层的认证方式。实测默认 Basic；源码分支显示 Basic 使用内置 PDO 认证后端，Apache 交由 Web 服务器认证，其余值走 sabre/dav 标准 Digest 后端。实测请求无凭据时的质询头：

WWW-Authenticate: Basic realm="sabre/dav", charset="UTF-8"

⚠️ 注意：协议层 401 质询的 realm 显示为 sabre/dav，与 yaml 里的 auth_realm: BaikalDAV 不是一回事——auth_realm 参与的是密码哈希运算，不是 HTTP 质询字符串。

auth_realm：认证域种子。DAV 用户密码以 Digest 兼容格式存储：digesta1 = md5(username:auth_realm:password)。实测验证：后台创建用户 root/q1w2e3r4 后，SQLite 库 users 表实查 digesta1 = 0660e66420d5bf6c32024ce32d471aa5，与 md5('root:BaikalDAV:q1w2e3r4') 逐字符一致。管理员密码哈希同样混入该值（见下）。修改 auth_realm 会使所有用户密码与管理员密码同时失效，必须同步重置，不要单独改它。

admin_passwordhash：Web 后台管理员（登录名固定 admin）的密码哈希，算法实测复算一致：

python3 -c "import hashlib;print(hashlib.sha256(b'admin:BaikalDAV:q1w2e3r4').hexdigest())"

实测回显：

6d0d6c6b6555fbae363f90d862e8b11f8551196add2f99b1657e3759164bf2a5

与 yaml 中的值逐字符相同。重置管理员密码见常见问题 3。

failed_access_message：认证失败时写入错误日志的文案，%u 为用户名占位。实测源码确认：为避免用户名泄露，日志中占位符被替换为 (name stripped-out) 而非原文；日志输出目标为错误日志通道（独立服务方式部署时进 stderr，由服务管理器收取；裸机部署进 PHP-FPM/nginx 错误日志）。

5.3 system 组：邀约邮件（invite_from）

invite_from 是会议邀请（IMIP）邮件的发件地址。实测源码行为：该值非空时 DAV 服务器才挂载 IMIP 插件，为空则完全不挂载。发信通道使用系统邮件客户端（如 msmtp，需先配置其发信账号）才真正可达。邮件收发与域名信誉问题不在 Baikal 管辖内。

5.4 database 组：三后端与切库实操

backend + sqlite_file（SQLite，默认）：sqlite_file 指向 Specific/ 下的库文件。实测后台 Database settings 页在 SQLite 模式下只暴露 backend 与 sqlite_file 两个字段，保存前会校验库文件与目录可写、14 张必需表结构完整（缺表时报错并列出缺失表名）。

MySQL/PostgreSQL 字段：mysql_host/dbname/username/password（另有 mysql_ca_cert，留空不启用证书校验）、pgsql_host/dbname/username/password。实测完整切库流程（全程可复现）：

1. 在 MySQL 服务器上建库授权（示例连接目标 10.89.62.11，库名 baikal，账号 baikal/q1w2e3r4）；
2. 导入官方表结构（0.10.1 程序包内 Core/Resources/Db/MySQL/db.sql，实测导入后 14 张表）：

mysql -h 10.89.62.11 -u baikal -p baikal < Core/Resources/Db/MySQL/db.sql

3. 直接编辑 baikal.yaml（实测此改法立即生效，无需重启）：

database:
    backend: mysql
    mysql_host: 10.89.62.11
    mysql_dbname: baikal
    mysql_username: baikal
    mysql_password: q1w2e3r4

4. 验证：空库时 DAV 用户全部失效（users 表为空，实测 PROPFIND 返回 401），Web 后台仍可登录（管理员哈希在 yaml 不在库里）；在后台重新建用户后 MySQL 侧实查 users 表出现记录，DAV 登录恢复 207。实测 MySQL 侧核心表与数据：

id  username  digesta1
1   root      0660e66420d5bf6c32024ce32d471aa5

5. 切回 SQLite：把 backend 改回 sqlite 即可，实测原 SQLite 数据完整无损（PROPFIND 207、日历/事件全部还在）。

⚠️ 注意：切换后端不做任何数据迁移，SQLite 里的用户、日历、事件不会出现在 MySQL 中；要做数据搬家请先用 ?export 导出或 sqlite3 .dump 导出（见《Baikal 0.10.1 管理与运维实战》备份章节）。

5.5 Specific/ 目录：配置体系外的例外机制

Specific/ 是可变数据的家，除数据库文件外有两个特殊成员：

• INSTALL_DISABLED：空标记文件，实测向导完成后自动创建（时间戳与向导完成时刻一致）。存在即永久禁用 /admin/install/；实测已禁用状态下访问安装器返回「Installation was already completed. Please head to the admin interface to modify any settings.」。
• .htaccess：Apache 环境下拒绝直读的保护文件；nginx 环境由服务器规则承担同等职责（常见 nginx 配置禁 /(\.ht|Core|Specific) 直读）。

六、生产配置模板

模板 A：SQLite 单机（≤50 用户、共享盘/NAS 场景，2GB 内存即可）

system:
    configured_version: 0.10.1
    timezone: Asia/Shanghai
    card_enabled: true
    cal_enabled: true
    dav_auth_type: Basic
    admin_passwordhash: <向导生成，勿手工编造>
    failed_access_message: 'user %u authentication failure for Baikal'
    auth_realm: BaikalDAV
    base_uri: ''
    invite_from: noreply@example.com
database:
    backend: sqlite
    sqlite_file: /var/www/baikal/Specific/db/db.sqlite
    encryption_key: <安装时随机生成，勿改动>

要点：零外部依赖，备份=拷 config/+Specific/ 两目录；数据量增大后（万级事件）建议换模板 B。

模板 B：MySQL 后端（多实例备份、团队场景，4GB+ 内存，MySQL 与应用同机房内网）

system:
    configured_version: 0.10.1
    timezone: Asia/Shanghai
    card_enabled: true
    cal_enabled: true
    dav_auth_type: Basic
    admin_passwordhash: <向导生成>
    failed_access_message: 'user %u authentication failure for Baikal'
    auth_realm: BaikalDAV
    base_uri: ''
    invite_from: noreply@example.com
database:
    backend: mysql
    mysql_host: 10.89.62.11
    mysql_dbname: baikal
    mysql_username: baikal
    mysql_password: q1w2e3r4
    encryption_key: <安装时随机生成>

要点：切库前先导入 db.sql；数据备份走 MySQL 通道（mysqldump）；mysql_ca_cert 需要链路加密时才配。通用建议：auth_realm 与 encryption_key 一经部署不要再动。

七、常见问题

7.1 Web 后台「Database settings」从 SQLite 切 MySQL 报异常

实测现象：在该页选择 backend=mysql、填好连接信息保存，页面直接返回 PHP 异常（HTTP 200 + 异常堆栈，实测全文）：

Exception: \Formal\Form\Morphology->element(): Element prop='sqlite_file' not found
in /var/www/baikal/Core/Frameworks/Formal/Form/Morphology.php:57
#1 .../BaikalAdmin/Controller/Settings/Database.php(165): Formal\Form\Morphology->element()

定位：0.10.1 源码中表单形态按提交值（mysql）构建——此时 sqlite_file 表单元素被移除；而校验逻辑仍按数据库里的旧 backend（sqlite）分支执行，去取已不存在的 sqlite_file 元素，必然抛异常。实测在 0.10.1 官方包源码第 165 行精确命中该调用。

解决：切库不走该页面，直接编辑 baikal.yaml（5.4 节完整流程）。反向（MySQL 切回 SQLite）同理直接改文件。

7.2 配置文件语法错误时全线报错

实测把 yaml 写入未闭合的行内数组后，首页与 DAV 入口立即返回（HTTP 200 + 原始异常页）：

Symfony\Component\Yaml\Exception\ParseException: Malformed inline YAML string at line 3.
in /var/www/baikal/vendor/symfony/yaml/Parser.php:1226

解决：恢复备份文件即可立即恢复（配置按请求实时解析，恢复即生效）。日常改文件前先 cp baikal.yaml baikal.yaml.bak。

7.3 管理员密码重置

后台登录密码遗失时，用 5.2 节算法重算哈希写回 yaml：

python3 -c "import hashlib;print(hashlib.sha256(b'admin:BaikalDAV:新密码').hexdigest())"

把输出替换 admin_passwordhash 的值，实测改完立即生效，无需重启。若修改过 auth_realm，公式中的 realm 也要同步替换。

7.4 DAV 用户集体 401

排查顺序：backend 与 sqlite_file 是否指向正确 → 库文件是否还在（Specific/db/db.sqlite）→ users 表是否有记录（sqlite3 db.sqlite 'SELECT username FROM users;'）→ 是否刚切过库（切库不迁数据，见 5.4）。实测空 users 表时所有 DAV 凭据 401，与配置语法无关。

7.5 auth_realm 改动后全部密码失效

auth_realm 同时参与 DAV 用户 digesta1 与管理员 admin_passwordhash 的哈希运算（5.2 节），单独修改它等于清空全部密码。确需修改时，先重算并写回所有用户哈希（或后台逐个重置密码），再改 realm。

八、参考链接

• Baikal 官方文档：https://sabre.io/baikal/
• Baikal 源码仓库（0.10.1 tag）：https://github.com/sabre-io/Baikal
• 官方数据库表结构（Core/Resources/Db/）：https://github.com/sabre-io/Baikal/tree/master/Core/Resources/Db
• Symfony Yaml 组件（解析行为来源）：https://symfony.com/components/Yaml
• sabre/dav 认证文档：https://sabre.io/dav/authentication/

站内相关阅读：

• 《Baikal 0.10.1 介绍与选型指南》：架构与协议行为实测
• 《Baikal 0.10.1 Docker Compose 部署指南》：部署与初始化
• 《Baikal 0.10.1 管理与运维实战》：用户管理/备份恢复/升级
• 《Radicale 3.9 配置参数详解》：同领域 Python 方案的配置体系对照