v24 第 22 批:名册加 CardDAV 同步 + 一把通用 DAV 口令(日历与通讯录共用)

用户 2 条原话:
  ①「名册,增加cardav同步功能。」
  ②「caldav和cardav,都增加一个创建口令的功能,这样,就使用用户名和口令来同步,
     避免在第三方客户端进行同步时自己的密码泄露。」

用户拍板的两个岔路(AskUserQuestion):
  · 口令范围 = **一把通用 DAV 口令**(日历 + 通讯录共用),不是两个 ——
    手机上填一次就都通;两把会让用户要在两个页面各配一遍、还容易只配一半。
  · 同步范围 = 与**名册页完全一致**(Person::roster(kind='member')),不另发明判据。

════ 一、 口令统一:caldav_credentials → dav_credentials(Schema v23)════
表**改名**(不是新建一张 carddav_credentials):
  · 老站 RENAME → 已配好的口令一字不动,**所有设备不用重配**;
  · 新装时两表都不在 → 跳过(直接 RENAME 一张不存在的表会抛异常、把升级打断);
  · 两表并存(上次升级跑一半 / 有人手工建过)→ 搬行(INSERT IGNORE)+ DROP 旧表。
⚠️ 迁移**必须**是 RENAME + 存在性守卫(新增 Schema::hasTable),
   只改建表语句里的名字的话,老库会**再建一张空表**、旧表留在原地没人读 →
   用户所有已配好的同步设备立刻全部 401(而且改密码也修不好:新口令写进了新表)。

Auth:caldavIssue/Revoke/Auth/hasCalDav → davIssue/davRevoke/davAuth/hasDav,
新增 davLastUsed()(UI 上显示"最近使用")。

口令管理入口搬到**个人设置 → DAV 同步**(它管的是"我的凭据",同时服务日历与通讯录;
放在日历页会让只想同步通讯录的人在日程里找半天)。
  · 旧路由 calendar/caldav_token|caldav_revoke 保留为 302 → 老书签不 404;
  · 日历本页只留地址 + 一个指路按钮(密码类的东西只该有一个管理入口,
    两处各放一套按钮迟早对不上:这页重置了、那页还显示"已配置")。

════ 二、 CardDAV(全新)════
· app/Vcard.php —— 名册 → vCard **3.0**(iOS/DAVx⁵ 推荐;4.0 在 iOS 上会被降级丢字段)。
  FN 必须有(缺了 iOS 会**整张卡丢掉**)、UID 用 person id(稳定,不随改名变)、
  标签能对上固定词就走 TYPE(手机上显示成"手机/工作"),对不上就原样放进
  X-ABLabel(**不猜**成 HOME —— 猜错了用户看到"家"其实是"奶奶家")。
· app/CardDav.php —— books/rows/one/cardOf/etag/parsePath;ROOT='/carddav/'。
· carddav.php —— OPTIONS / PROPFIND(0,1) / GET / REPORT;**写方法一律 403**。
  只读是与 CalDAV 同样的取舍:与其"半支持"(客户端以为改成功了、服务端却没落库),
  不如明确拒绝,用户至少知道"手机上加的联系人不会同步回来"。
· **地址空间分离、鉴权同一套**:/carddav/ 与 /dav/ 各自独立(资源类型与命名空间
  完全不同,混在一棵树里要靠猜客户端意图,猜错的表现是"连上了但一本都看不到");
  但两者调**同一个** Auth::davAuth、读**同一张** dav_credentials 表 ——
  这正是"一把口令管两种同步"的落点,也保证不会出现"日历能连、通讯录连不上"。
· 路由三处:router.php(本地 php -S)+ .htaccess(书面来源)+ 部署脚本 5c 段。
  ⚠️ 线上用**独立标记块** `# >>> FamilyBook CardDAV`:老站已经有
  `# >>> FamilyBook CalDAV`,把新规则并进那一段会被"标记在不在"的幂等判断
  **整段跳过** → /carddav/ 永远 404,而本地(走 router.php)完全正常。
· 打包白名单加 carddav.php(站点根下的独立入口最容易漏 —— dav.php / upload_stage.php
  都漏过一次,症状都是"线上那个功能 404、本地一切正常")。

════ 三、 🔴 三个真 bug(全是"本地校验全绿"型,靠 vCard 往返测试抓出来)════
把 App\Vcard(导出)与 App\ContactImport(导入)各自单测都是绿的,
但**导出→导入跑一遍**立刻翻出三个:

 ① Vcard::fold **漏了"续行补前导空格"**(照抄 Ics::fold 时抄漏了最后一步)。
    后果:折出来的那几段变成**独立的属性行** → 客户端把半个名字/半个地址当垃圾丢掉。
    而"每行 ≤75 字节""确实折行了"全是绿的 —— 只有「**折行可无损还原**」这条断言能抓。

 ② ContactImport 用 `explode(';')` 给 ADR / N 分段 —— PHP 的 explode **不认识转义**,
    值里写了 `\;`(字面分号)照样在那里拆开 → 地址「青岛市,市南区;某某路1号」被
    从中间切断,后半截(含省名)跑到别的段上;导进来的人地址只剩前半句、
    而且看着像"省没填"。手机通讯录里带分号的地址("XX路1号;3单元")不算罕见。
    → 新增 `splitVcardSegments()`:**按未转义的分号**切,切完再逐段 unescape。
    ⚠️ "先 unescape 再分段"是同一个错的另一种写法(本轮第一版就这么改,往返照样红)。

 ③ Vcard::adrField 的**分号数量对、但位置错一位**(省落到了"邮编"格)。
    第一版 `;;` + 街道 + `;;;` + 省 + `;` —— 总数也是 6,可多出来的那个挤在前面 →
    解析器读段 4 拿到空串。**段数对、总数对、只有位置错一位**,
    所以"数分号个数"的检查发现不了它。

════ 四、 顺带修的一个 ETag 一致性 bug ════
同一张卡在 PROPFIND(清单)与 REPORT(取正文)里原本算出**两个不同的 ETag**
(一个用不带结尾 CRLF 的正文、一个用带 CRLF 的)→ 客户端认为这张卡一直在变、
**反复重拉**(同步永远不收敛),而服务端看不出任何异常(两边都合法)。
→ 新增 `CardDav::cardOf()`,把**正文与 ETag 成对返回**,结尾 CRLF 只加在正文上、
不参与 ETag。修法不是"两处改成一样",而是**让它们没有机会不一样**。

════ 五、 UI ════
· 个人设置页「DAV 同步」卡:两个地址(/dav/ 与 /carddav/)+ 用户名预填 + 一次性明文
  (只显示这一次,走一次性会话槽位)+ 生成/重置/撤销 + "最近使用"。
· 名册页 CardDAV 卡:地址 + "这 N 个人"(人数与名册页一致,用户当场能对上)+
  指路口令的按钮。**不放**生成表单。
· 日历本页改口径:只留 /dav/ 地址 + 指路链接。

════ 六、 验证 ════
- e2e **1106/0**(本批新增约 45 条:CardDAV 全协议、越权 404、只读 403、
  一把口令开两把锁、撤销后两处**同时**失效、口令一次性/不落库、ETag 一致性)
- **vCard 规格体检 36/36**(新工具 `_fb_b22_vcf_spec.php`:转义/折行/多值/标签/
  空名兜底 + **导出→导入往返一致**)
- **真机探针 28/0**(新工具 `_fb_b22_ui.py`:两块 UI 渲染、**在浏览器里点按钮**生成
  口令、刷新后明文消失但状态留下、名册页人数对得上、日历本页改口径、
  撤销后两处 401、全程零 JS 报错)
- 桌面几何 428/0 · 移动端几何(360/375/390/414)684/0 · 结构升级 149/0
- 部署静态断言空跑 **307/0** · 线上部署 134 项自检 0 失败
- **反向验证 14/14**(`_fb_b22_falsify.py`):迁移不干活 / 读旧表 / 断入口 /
  去掉 addressbook 声明 / 只读守卫失效 / 不校验口令 / 越权不再查名册 /
  折行不补空格 / 分段改回 explode / ADR 错位 / UI 卡拿掉 / 明文不再一次性 /
  撤销不删凭据 —— 逐条改回旧行为,对应断言都变红,还原后复绿。

════ 七、 🔴🔴 线上实测挖出的**最重要**的一条:DAV 鉴权在 Apache 上一直是坏的 ════
部署后在线上以 **Web 用户(www)** 身份做端到端验收时,DAV 全部 401 ——
而本地 e2e 全绿。追下去发现两层原因:

 ① **测试假象**:我把 DAV 请求放进了一个**临时探针文件**里,用 `curl` 打它。
    但 Apache 请求 `.php` 文件时**不套用站点根 .htaccess 的 URL 重写** ——
    所以探针里的请求根本没被转给 dav.php/carddav.php,拿到的是**探针自己的 401**,
    不是 DAV 的。第一轮"全 401"有一半是探针自己造的假象。

 ② **真问题**:Apache 默认**不把 `Authorization` 头交给 PHP-FPM** ——
    `$_SERVER['PHP_AUTH_USER']` 与 `HTTP_AUTHORIZATION` **全是 null**。
    实测(这台服务器 Apache 2.4.53,直接监听 80/443,**没有 nginx**):
        基线            : {"PHP_AUTH_USER":null,"HTTP_AUTHORIZATION":null}
        `CGIPassAuth On`: {"PHP_AUTH_USER":"abc","HTTP_AUTHORIZATION":"(有)"}
    ⇒ **线上 CalDAV 从来没被真实客户端连上过**(服务端代码是对的、环境少了这一行)。
      本轮 e2e 用 `php -S`,那里 `PHP_AUTH_USER` 是**自己填好的**,所以一路全绿 ——
      又一个"本地好好的、线上不行"。

  修法:部署脚本 5c 段追加**独立标记块** `# >>> FamilyBook DAV auth`,内容
  `CGIPassAuth On`(Apache **2.4.13+ 的核心指令**,不需要额外模块、**不用动宝塔面板**)。
  仓库 `.htaccess` 同步写上(它是那段规则唯一的书面来源)。

  修完后线上端到端**全部通过**(以 www 身份、真实 HTTP 服务、真实数据):
    · CalDAV:`PROPFIND → 207`、**8 本日历本**、`PUT → 403`
    · CardDAV:根 `207` + `<card:addressbook/>`;清单 `207`、**1089 张卡**、1089 个 ETag;
      整本 vcf `200`、1089 张、全是 3.0、`text/vcard`;**最长行 75 字节**(真实数据上
      折行真的发生了);`REPORT → 207` 带 `address-data`;`PUT → 403`;
      `OPTIONS → 200 DAV: 1, 2, 3, addressbook`
    · 导出的卡数 **1089 == 名册人数 1089**(口径一致)
    · 口令错 → `401`
  临时探针用完即删并复验 404;临时插入的口令用完即清(不动用户已配的凭据)。

════ 八、 关于 CalDAV「本来是好的」这件事 ════
严格说:**服务端实现一直是对的**,缺的是 Apache 那一行 `CGIPassAuth`。
也就是说这个仓库里的 CalDAV 之前**上线即不可用**(只是没人用真实客户端试过)。
本批顺手把它一起修好了 —— 现在 /dav/ 与 /carddav/ 都能被 iOS / DAVx⁵ 正常连上。
This commit is contained in:
2026-10-06 17:33:48 +08:00
parent 41572b77e7
commit 6ceae11293
16 changed files with 1292 additions and 81 deletions
+4
View File
@@ -107,6 +107,10 @@ $backView = $curView;
<div class="cal-set-links">
<a href="<?= e(url('calendar/calendars')) ?>"<?= $setOn('books') ?>><?= $setIcon('books') ?><span>日历本 · 颜色 / 共享 / 导入</span></a>
<a href="<?= e(url('calendar/calendars')) ?>#caldav"><?= $setIcon('dav') ?><span>CalDAV 订阅(在手机日历里看)</span></a>
<?php /* v24 第 22 批:口令改成通用 DAV 口令(日历 + 通讯录共用)。这条不再直接跳
日历本页那个卡片,而是跳到**口令管理**页 —— 用户从这里点进来十有八九
是"要配同步",那就该落到能生成口令的地方(日历本页现在只有地址)。 */ ?>
<a href="<?= e(url('settings/me', [], 'dav')) ?>"><?= $setIcon('dav') ?><span>DAV 口令(日历 + 通讯录)</span></a>
</div>
</div>
</details>
+15 -31
View File
@@ -199,17 +199,21 @@ $canWrite = \App\Auth::canWrite();
</div>
<?php endif; ?>
<?php /* v24 第 7 条后半:CalDAV —— 把我的日历本订阅到手机/别的日历程序里 */ ?>
<div class="card card-pad">
<?php /* v24 第 7 条后半:CalDAV —— 把我的日历本订阅到手机/别的日历程序里。
v24 第 22 批:口令改成**通用 DAV 口令**(日历 + 通讯录共用一把),
管理入口也搬到了「个人设置 → DAV 同步」—— 这里只留地址与一个指路按钮。
⚠️ 这一页**不再有**生成/撤销表单:同一个口令在两处各放一套按钮,
迟早出现"在这里重置了、那页还显示已配置"的对不上(而且密码类的东西
有两个入口本身就是坏味道)。 */ ?>
<div class="card card-pad" id="caldav">
<h2 class="cinema-h2">
CalDAV 订阅
<span class="hint">在手机日历 / DAVx⁵ / Thunderbird 里订阅你的日历本</span>
</h2>
<p class="small muted" style="margin:0 0 12px">
填下面这个地址 + 你的<b>姓名或手机号</b> + <b>CalDAV 口令</b>,就能把「我的日历本」
填下面这个地址 + 你的<b>姓名或手机号</b> + <b>DAV 口令</b>,就能把「我的日历本」
同步到别的日历程序里。这是<b>只读</b>订阅的 —— 在手机上改日程请回到本站来改。
<br>口令与登录密码是<b>分开的</b>:订阅凭据会被客户端长期存着,所以另发一个,
随时可换、不影响登录。
<br>口令与登录密码是<b>分开的</b>,而且<b>通讯录同步也用同一把</b>(不用配两遍)。
</p>
<div class="field">
<label>服务器地址</label>
@@ -217,32 +221,12 @@ $canWrite = \App\Auth::canWrite();
value="<?= e(rtrim((string)fb_config('base_url', ''), '/') . '/dav/') ?>">
<span class="tip">在日历客户端里填这一条即可,会列出你所有的日历本。</span>
</div>
<?php if (!empty($cdPlain)): ?>
<p class="tip" style="background:#FFF6E5;border-color:#E8C98A;padding:8px 12px;border-radius:8px">
<b>这是你的新口令,只显示这一次,请立刻复制走:</b>
<br><code class="mono" style="font-size:15px"><?= e($cdPlain) ?></code>
</p>
<?php endif; ?>
<?php if ($canWrite): ?>
<div class="btn-row">
<form method="post" action="<?= e(url('calendar/caldav_token')) ?>" class="res-inline">
<?= csrf_field() ?>
<button class="btn btn-sm" type="submit">
<?= !empty($cdHas) ? '重置 CalDAV 口令' : '生成 CalDAV 口令' ?>
</button>
</form>
<?php if (!empty($cdHas)): ?>
<form method="post" action="<?= e(url('calendar/caldav_revoke')) ?>" class="res-inline">
<?= csrf_field() ?>
<button class="btn btn-ghost btn-sm" type="submit"
onclick="return confirm('撤销后所有已订阅的客户端都会失去访问。')">撤销口令</button>
</form>
<span class="node-badge">口令已配置</span>
<?php else: ?>
<span class="node-badge">还没配置口令</span>
<?php endif; ?>
</div>
<?php endif; ?>
<div class="btn-row">
<a class="btn btn-sm" href="<?= e(url('settings/me', [], 'dav')) ?>">
<?= !empty($cdHas) ? 'DAV 口令已配置(去管理 / 重置)' : '去生成 DAV 口令' ?>
</a>
<span class="node-badge">口令在「个人设置 → DAV 同步」里管理</span>
</div>
</div>
<?php if ($shared): ?>
+40
View File
@@ -326,6 +326,46 @@ $renderBlock = function (int $gid, string $name, array $list) use ($renderGrid):
<?php endif; ?>
</div>
<?php /* ==================== CardDAV 同步(v24 第 22 批)====================
用户原话:「名册,增加cardav同步功能。caldav和cardav,都增加一个创建口令的功能,
这样,就使用用户名和口令来同步,避免在第三方客户端进行同步时自己的密码泄露。」
⚠️ 口令在**个人设置**里生成(一把通用 DAV 口令,日历与通讯录共用),
这里只给地址 + 一个指路按钮 —— 密码类的东西只该有一个管理入口,
两处各放一套按钮迟早对不上(这页重置了、那页还显示"已配置")。
⚠️ 同步范围 = **这一页看到的人**(同一个 Person::roster 口径):
下面那句里的人数就是名册页的人数,用户当场能对上,不必猜"到底同步了谁"。 */ ?>
<div class="card card-pad" style="margin-top:20px" id="carddav">
<h2 class="section-title">
通讯录同步(CardDAV)
<span class="hint">把这 <?= (int)$total ?> 个人放进手机通讯录</span>
</h2>
<p class="small muted" style="margin:0 0 12px">
在 iOS「通讯录」、安卓 <b>DAVx⁵</b>、Thunderbird、群晖 Contacts 里填下面这个地址 +
<b>你的姓名或手机号</b> + <b>DAV 口令</b>,就能把<b>这份名册</b>同步过去。
<br>同步的就是你在这一页看到的这些人(<b><?= (int)$total ?></b> 个)——
谁加进你的名册、谁就会出现在手机通讯录里。
<br>目前是<b>只读</b>同步:在手机上改的联系人<b>不会</b>写回家书,要改请回到本站来改。
</p>
<div class="field">
<label>通讯录地址</label>
<input class="input mono" readonly value="<?= e(rtrim((string)fb_config('base_url', ''), '/') . '/carddav/') ?>">
<span class="tip">填这一条即可;点进去之后 iOS/DAVx⁵ 会自动发现这本通讯录。</span>
</div>
<div class="btn-row">
<a class="btn btn-sm" href="<?= e(url('settings/me', [], 'dav')) ?>">
<?= !empty($davHas) ? 'DAV 口令已配置(去管理 / 重置)' : '去生成 DAV 口令' ?>
</a>
<?php /* ⚠️ 这句徽标原本写得很长("口令在「个人设置 → DAV 同步」里管理(日历也用同一把)"),
而 `.node-badge` 是 `white-space: nowrap`、`.btn-row` 不换行 ——
在 360/375/390px 上它把整页**撑出横向滚动**(真机几何实测:
scrollW 412 > clientW 360,越界元素就是它)。
页面变宽在手机上是最刺眼的问题(整页可以左右拖),
所以文案压到八个字以内、并允许在窄屏折行。 */ ?>
<span class="node-badge">日历与通讯录共用一把</span>
</div>
</div>
<?php /* ==================== 卡片动作的**共享浮层**(v24 第 10 批 #6)====================
这里只有**一份**「分组」表单和**一份**「移出名册」表单,全页共用。
每一行的按钮只带数据(data-pg-open / data-pm-open),点开时由 JS 把数据灌进来。
+90
View File
@@ -43,6 +43,96 @@ $rosterCount = $rosterCount ?? 0;
② 「我怎么称呼家人」卡片(require _nicknames.php)
下面直接接天气地点。改登录密码在右上角头像下拉里也有入口。 */ ?>
<!-- ==================== DAV 同步(v24 第 22 批)==================== -->
<?php /* 用户原话:「caldav和cardav,都增加一个创建口令的功能,这样,就使用用户名和口令
来同步,避免在第三方客户端进行同步时自己的密码泄露。」
为什么这张卡在**个人设置**而不是「日程 → 日历本」:
它管的是"我的凭据",同时服务**日历(CalDAV)与通讯录(CardDAV)**两件事 ——
放在日历页会让只想同步通讯录的人在日程里找半天。
⚠️ 明文口令**只显示一次**(走一次性会话槽位,见 render_me_settings 末尾的 unset):
设备上要填的是这串,页面上能反复看到等于把它变成"又一个可被偷看的密码"。
⚠️ 口令与登录密码**必须**分开:第三方客户端会把这串长期存在设备上并反复自动发送,
用登录密码就等于把主密码复制到每一台设备(这正是用户要避开的事)。 */ ?>
<div class="card card-pad" id="dav" style="margin-top:20px">
<h2 class="section-title">
DAV 同步
<span class="hint">日历本 + 通讯录,一个口令在手机 / 电脑上同步</span>
</h2>
<p class="small muted" style="margin:0 0 14px">
在 iOS「日历/通讯录」、安卓 <b>DAVx⁵</b>、Thunderbird、群晖日历里,
填下面这两个地址 + <b>你的姓名或手机号</b> + <b>DAV 口令</b>,就能把
<b>我的日历本</b>和<b>我的名册</b>同步过去。
<br><b>口令和登录密码是分开的</b> —— 第三方客户端会把凭据长期存在设备上并反复自动发送,
用登录密码等于把主密码复制到每一台设备;所以这里单独发一个,随时可换、不影响登录。
<br>目前是<b>只读</b>同步:在手机上改日程 / 加联系人<b>不会</b>写回家书,
要改请回到本站来改。
</p>
<div class="form-grid">
<div class="field full">
<label>日历(CalDAV)地址</label>
<input class="input mono" readonly
value="<?= e((string)$davBase . '/dav/') ?>">
</div>
<div class="field full">
<label>通讯录(CardDAV)地址</label>
<input class="input mono" readonly
value="<?= e((string)$davBase . '/carddav/') ?>">
<span class="tip">
同步的是「我的名册」里那 <b><?= (int)$davRosterN ?></b> 个人 —— 和你名册页上看到的一致。
</span>
</div>
<div class="field">
<label>用户名</label>
<input class="input mono" readonly value="<?= e((string)$person['name']) ?>">
<span class="tip">也可以填手机号,两个都认。</span>
</div>
<div class="field">
<label>口令</label>
<?php /* ⚠️ 一行只能有一个 value:库里有的是 sha256,**取不回明文**,
所以已经配过就显示一排圆点(表示"有,但不给你看"),
没配过就写一句说明。真正的明文只在刚生成那一次显示(上面那块黄条)。 */ ?>
<input class="input mono" readonly
value="<?= !empty($davHas) ? '••••••••••••••••••••••••' : '还没生成,点下面的按钮' ?>">
<span class="tip">生成后<b>只显示一次</b>,请先复制到设备里再关页面。</span>
</div>
</div>
<?php if (!empty($davPlain)): ?>
<p class="tip" style="background:#FFF6E5;border-color:#E8C98A;padding:10px 12px;border-radius:8px">
<b>这是你的新口令,只显示这一次,请立刻复制到设备的「密码」栏里:</b>
<br><code class="mono" style="font-size:15px"><?= e((string)$davPlain) ?></code>
</p>
<?php endif; ?>
<?php if (\App\Auth::canWrite()): ?>
<div class="btn-row">
<form method="post" action="<?= e(url('settings/dav_token')) ?>" class="res-inline">
<?= csrf_field() ?>
<button class="btn btn-sm" type="submit"><?= !empty($davHas) ? '重置 DAV 口令' : '生成 DAV 口令' ?></button>
</form>
<?php if (!empty($davHas)): ?>
<form method="post" action="<?= e(url('settings/dav_revoke')) ?>" class="res-inline">
<?= csrf_field() ?>
<button class="btn btn-ghost btn-sm" type="submit"
onclick="return confirm('撤销后,所有已同步的客户端(日历与通讯录)都会失去访问。确定吗?')">撤销口令</button>
</form>
<span class="node-badge">口令已配置<?= !empty($davLastUsed) ? ' · 最近使用 ' . e((string)$davLastUsed) : ' · 还没被用过' ?></span>
<?php else: ?>
<span class="node-badge">还没配置口令</span>
<?php endif; ?>
</div>
<?php if (!empty($davHas)): ?>
<p class="small muted" style="margin:10px 0 0">
「重置」会立刻换一串新口令:<b>已经配好的设备会连接失败</b>,
需要把新口令重新填进去。怀疑口令外泄时就用它。
</p>
<?php endif; ?>
<?php endif; ?>
</div>
<!-- ==================== 天气地点(用户 2026-10-03 第 1 条)==================== -->
<?php /* 原话:「天气这个这样吧,让用户在个人设置中填写自己的城市。」
所以地点从系统设置搬到了这里 —— 而且改成**城市名**,不是经纬度: