部署（模型 B）
playbook 在目标主机上执行的内容、文件位置、验收方法、失败后的清理，以及交付清单。
操作步骤见快速开始。本页说明 playbook 背后的动作，用于排障和二次交付。
playbook 的阶段
deploy-ipaserver.yml 分五段，全部幂等，重跑只补差异：
| 段 | 动作 | 位置 |
|---|---|---|
| 离线 RPM 源 | 把包内 rpms/ 推到目标机，注册为本地 yum 源，签名校验开启 | /opt/idmatrix-rpms/，/etc/yum.repos.d/idmatrix-offline.repo |
| FreeIPA 服务端 | freeipa.ansible_freeipa 的 ipaserver 角色：安装包、ipa-server-install（目录、KDC、CA、DNS、adtrust）；启用 oddjob-mkhomedir，用户首次登录自动创建家目录 | FreeIPA 标准路径 |
| 管理台 | 推送 dist/ 到目标机，在 /etc/httpd/conf.d/ipa.conf 添加 /ipa/modern-ui 别名指向它 | IDM_WEBUI_DIST_DST，默认 /opt/idmatrix/dist |
| 许可层 | 安装校验脚本、状态端点、请求闸门、主机数插件、每日校验 timer，然后立即执行一次校验 | /opt/idmatrix-license/，/var/lib/idmatrix-license/status.json |
| 每日备份 | 备份脚本与 idmatrix-backup.timer，每日 02:30 在线数据备份 | /var/lib/ipa/backup/ |
许可层三个组件的分工见许可。
目标机上新增的内容
| 路径 | 内容 |
|---|---|
/opt/idmatrix-license/ | 许可层程序 |
/var/lib/idmatrix-license/ | license.lic（激活后）、status.json（当前许可状态，管理台横幅和闸门都读取它） |
/etc/httpd/conf.d/ipa.conf | /ipa 的 WSGI 入口改为许可层的请求闸门；/ipa/modern-ui 别名 |
/etc/httpd/conf.d/idmatrix-license.conf | 状态查询、指纹请求、许可上传三个端点 |
| FreeIPA 插件目录 | idmatrix_hostlimit.py，服务端硬限受管主机数 |
/etc/systemd/system/ | idmatrix-license.{service,timer}、idmatrix-backup.{service,timer} |
验收
六条全部通过才算安装完成：
sudo ipactl status # 1 11 个服务全部 RUNNING
curl -sk -o /dev/null -w '%{http_code}\n' https://<FQDN>/ipa/modern-ui/ # 2 200 或 301
sudo systemctl list-timers idmatrix-backup.timer # 3 NEXT 为次日 02:30
sudo systemctl start idmatrix-backup.service && ls /var/lib/ipa/backup/ # 立即执行一次，确认产物
cat /var/lib/idmatrix-license/status.json # 4 未激活时 valid:false 为正常
echo '<admin口令>' | kinit admin && ipa pwpolicy-mod --minlength=9 # 5 期望 Forbidden
chronyc sources # 6 时间同步正常第 5 条检查许可门控是否存在。未激活时写操作被拒是设计行为；该命令成功说明许可层未正确接管 /ipa 入口，或 status.json 不可读导致闸门失效开放。门控失效不报任何错误。
11 个服务为：Directory Service、krb5kdc、kadmin、named、httpd、ipa-custodia、pki-tomcatd、ipa-otpd、ipa-dnskeysyncd、smb、winbind。IPA_SETUP_DNS=false 时没有 named 和 ipa-dnskeysyncd；IPA_SETUP_ADTRUST=false 时没有 smb 和 winbind。
安装失败的清理
ipa-server-install 不是原子操作，中途失败会留下不完整的目录实例和 KDC。不直接重跑 playbook，先在目标机清理：
sudo ipa-server-install --uninstall -U
ls -d /etc/dirsrv/slapd-* /etc/pki/pki-tomcat /etc/ipa/default.conf 2>&1 # 应全部 No such file
sudo getcert list | grep -c MONITORING # 应为 0有残留时手工补充：dsctl slapd-<REALM> remove --do-it、rm -rf /etc/pki/pki-tomcat、getcert stop-tracking -i <id>。ipa-client-install --uninstall 把 /etc/nsswitch.conf 还原为安装前的备份；安装前修改过 hosts: 行（去掉 myhostname）时，卸载后需再改一次。
常见失败原因按出现顺序：
| 卡在 | 原因 |
|---|---|
| 主机名检查 | hostname -f 与 IPA_HOSTNAME 不一致；FQDN 解析到 127.0.0.1 或 ::1 |
| DNS 转发器检查 | IPA_FORWARDERS 不可达，或 IPA_AUTO_FORWARDERS=true 读到 resolv.conf 中的不可达地址 |
| 时间 | 与 NTP 源或域控时差超过 5 分钟 |
configuring mod_ssl | 目标机缺少 mod_ssl。rpm -q mod_ssl 检查，包内 RPM 仓提供 |
setting up httpd keytab，或 pkispawn 无法创建日志 | 目标机不是干净系统，/var/lib/ipa/gssproxy、/var/log/pki 之类的目录被删除过。执行 rpm -Va --nofiledigest | grep ^missing 全盘检查，对相应包执行 dnf reinstall |
交付清单
交给客户：
| 项 | 说明 |
|---|---|
管理台地址、admin 口令、Directory Manager 口令 | 写入客户的密码库 |
包内 docs/ 全部手册 | |
COPYING 与 idmatrix-source.tar.gz | 管理台是 GPLv3 的 freeipa-webui 二次开发，必须随附对应源码 |
| 备份说明 | 备份产物在 /var/lib/ipa/backup/，离机同步由客户自行配置 |
不交给客户：customer.env（明文口令）、控制节点上的 ssh 私钥、厂商内部文档。