# 管理端 mTLS 证书轮换

管理端客户端证书应至少每 180 天轮换一次；设备丢失、人员离职或私钥疑似泄露时立即轮换。
当前配置未启用 CRL，因此单个客户端证书无法被可靠撤销。出现紧急事件时必须轮换整个管理端
CA，不能只删除本地 `.p12` 文件。

## 零中断轮换

1. 在离线受信设备上生成一套新的 CA 和客户端证书，输出到带日期的新目录。不要覆盖现有目录。
2. 校验新证书的有效期、用途和私钥匹配关系：

   ```shell
   openssl verify -CAfile admin-client-ca.pem admin-client.pem
   openssl x509 -in admin-client.pem -noout -dates -subject -issuer
   openssl pkcs12 -in admin-client.p12 -info -noout
   ```

3. 将旧 CA 与新 CA 的公开证书按顺序合并为临时信任包。信任包不得包含任何 CA 私钥：

   ```shell
   cp current-admin-client-ca.pem admin-client-ca-transition.pem
   printf '\n' >> admin-client-ca-transition.pem
   openssl x509 -in new-admin-client-ca.pem -outform PEM >> admin-client-ca-transition.pem
   ```

4. 通过 1Panel 将临时信任包替换到 OpenResty 配置引用的
   `/www/server/openresty/conf/mtls/admin-client-ca.pem`，先执行 `openresty -t`，成功后再平滑重载。
5. 分别使用旧客户端证书和新客户端证书验证 `/admin/` 与 `/v1/admin/auth/session`。
6. 通过受控的点对点渠道交付新的 `.p12` 与独立密码。不得使用工单附件、群聊、Git 或公开网盘。
7. 确认所有获准设备完成安装后，将服务器信任包替换为仅包含新 CA 的证书，再次执行
   `nginx -t` 和平滑重载。
8. 验证新证书成功、旧证书返回 404，然后安全销毁旧客户端私钥和旧 CA 私钥。

## 验收记录

每次轮换必须在安全审计记录中保存以下非敏感信息：

- 轮换时间、执行人与复核人
- 新 CA 和客户端证书的 SHA-256 指纹与失效时间
- 新旧证书切换验证结果
- 旧证书停止信任的准确时间
- 触发原因：计划轮换、设备丢失、人员变更或疑似泄露

不得记录 `.p12` 密码、TOTP 密钥、私钥内容或管理员密码。