快速开始

从交付包到能登录管理台的最短路径：一台 Rocky / RHEL 9 主机、一台跑 ansible 的控制节点，填一份 customer.env，跑一遍 playbook。

准备

项	要求
目标主机	RHEL / Rocky / AlmaLinux 9（8 可用），2 vCPU / 4 GB / `/var` 20 GB 以上；干净系统，未装过 FreeIPA
主机名	`hostname -f` 是 FQDN（如 `idm.corp.example`），正反解都通，不能落在 `127.0.0.1` / `::1`
时间	与 AD 域控或上游 NTP 时差小于 5 分钟。Kerberos 对时钟敏感，超过就全域登录失败
端口	目标主机上 80 / 443 / 389 / 636 / 88 / 464 / 53 / 123 未被占用
控制节点	内网另一台 Linux，装 `ansible-core` 和 `gettext`，能 ssh 到目标主机并免密 sudo。拿不出第二台时用 all-in-one，见下
交付包	`idmatrix-host-<版本>.tar.gz`，带 playbook、管理台、许可层、ansible collections 和 376 MB 离线 RPM 仓，不需要目标主机联网

向客户要四样：IPA 的 FQDN / realm（大写）/ 域名（小写）/ NetBIOS 名（大写）；有 AD 的话再要 AD 域名、域控 IP、能建信任的 AD 管理员；内网 DNS 地址。

安装

解包，装 collections

在控制节点：

sha256sum -c idmatrix-host-<版本>.tar.gz.sha256
tar xzf idmatrix-host-<版本>.tar.gz && cd idmatrix-host-<版本>
( cd collections && ansible-galaxy collection install -r requirements.yml )

ansible-galaxy 必须在 collections/ 目录内跑：清单里写的是裸 tarball 名，按当前目录解析。

All-in-one（控制节点就是目标主机）多一步：sudo ./bootstrap-controller.sh。它从包内 rpms/ 装 ansible-core 和 gettext，用临时源，不写 /etc/yum.repos.d。

填 `customer.env`

cd deploy && cp customer.env.example customer.env && chmod 600 customer.env
vi customer.env

必改的项：

字段	值
`ANSIBLE_CONNECTION`	双机 `ssh`；all-in-one `local`
`IPA_HOSTNAME` / `IPA_HOST_ALIAS`	目标主机 FQDN，与 `hostname -f` 一致
`IPA_REALM` / `IPA_DOMAIN` / `IPA_NETBIOS`	`CORP.EXAMPLE` / `corp.example` / `CORP`
`IPA_ADMIN_PASSWORD` / `IPA_DM_PASSWORD`	两个不同的强口令，装完存进密码库。`admin` 登管理台；Directory Manager 做备份恢复与复制维护，找不回就要停机重置
`SSH_USER` / `SSH_HOST` / `SSH_PRIVATE_KEY`	双机填；all-in-one 全部留空
`IDM_LIC_SRC` / `IDM_WEBUI_DIST_SRC`	`<bundle>/license` / `<bundle>/dist`
`IPA_SETUP_FIREWALLD` / `IPA_NO_NTP`	裸机 `true` / `false`

DNS 三选一，填错装机在校验转发器那步失败：

客户情况	填法
有可达的内网 DNS	`IPA_FORWARDERS=10.0.0.53`，多个用引号
纯气隙，没有上游	`IPA_AUTO_FORWARDERS=false`，`IPA_FORWARDERS` 留空
客户自有 DNS，不让 IPA 管	`IPA_SETUP_DNS=false`，在客户 DNS 手工加 A / PTR / SRV

默认的 IPA_AUTO_FORWARDERS=true 会抓 /etc/resolv.conf，里面常有不可达地址，别留它。全部变量见配置项。

渲染，连通性自检

./render-inventory.sh
cd .. && ansible -i deploy/inventory.generated.yml all -m ping

render-inventory.sh 把 customer.env 渲染成 deploy/inventory.generated.yml，缺必填项会直接报出字段名。ping 返回 pong 才往下。

跑 playbook

ansible-playbook -i deploy/inventory.generated.yml deploy-ipaserver.yml

10 到 20 分钟，用 tmux 防掉线。它依次：注册离线 RPM 源 → 装 FreeIPA 服务端 → ipa-server-install（目录、KDC、CA、DNS、adtrust）→ 部署管理台与许可层 → 装每日备份 timer。结尾 failed=0。

失败不要直接重跑：先在目标主机 sudo ipa-server-install --uninstall -U 清干净，再从这一步开始。

验收

在目标主机：

sudo ipactl status                                      # 11 个服务全 RUNNING
curl -sk -o /dev/null -w '%{http_code}\n' https://<FQDN>/ipa/modern-ui/   # 200 或 301
cat /var/lib/idmatrix-license/status.json               # valid:false，未激活是正常的
echo '<admin口令>' | kinit admin && ipa pwpolicy-mod --minlength=9    # 期望 Forbidden
sudo systemctl list-timers idmatrix-backup.timer        # NEXT 是次日 02:30
chronyc sources

第四条最要紧：未激活时写操作必须被拒。它成功了说明许可门控没生效，不要交付。门控失效的症状是「该拦的没拦」，不报任何错。

装完之后

激活许可：管理台「License Activation」页复制主机指纹，交给 Reallysec，收到 .lic 回同一页上传。激活前管理台只读。
有 AD 就建信任：先过前置检查单，再 ipa trust-add。
让 Linux 客户端信任 IPA 的 CA：包里 export-ca.sh 导出，分发到客户端信任库。
备份产物在 /var/lib/ipa/backup/，每日 02:30 自动跑在线数据备份。离机同步要客户自己配。
把 admin 和 Directory Manager 口令存进密码库。customer.env 含明文口令，不要交给客户，不要进版本库。

升级

新交付包解到控制节点，同一份 customer.env，再跑一次 playbook。playbook 幂等，只更新管理台、许可层和 RPM。FreeIPA 本体的大版本升级走 ipa-server-upgrade，见升级与备份。

许可绑定 /etc/machine-id。重装系统、换机器、克隆虚拟机后指纹变了，许可失效，要重新签发。备份恢复到新机器同样如此。

排障

症状	看哪里
`ipa-server-install` 在 DNS 转发器校验失败	`IPA_FORWARDERS` 指向了不可达地址，或留了 `IPA_AUTO_FORWARDERS=true`
装机一开始就报主机名	`hostname -f` 与 `IPA_HOSTNAME` 不一致，或主机名解析到 `127.0.0.1` / `::1`（查 `/etc/hosts` 和 `getent hosts <FQDN>`）
登录后一切操作 403	未激活，或许可不含该模块。看 `status.json` 的 `valid` 和 `mods`
浏览器证书错误	用了 IP，换 FQDN
`kinit` 报时钟偏差	`chronyc sources`，与域控对时
重跑 playbook 在 `ipa-server-install` 卡住	上次没清干净，先 `ipa-server-install --uninstall -U`

更多见排障。

本页内容