快速开始

从交付包到登录管理台的最短路径。一台 Rocky 或 RHEL 9 主机、一台运行 ansible 的控制节点，填写 customer.env，执行一次 playbook。

本页覆盖单台 IPA 服务器的最短安装路径。第二台服务器、AD 信任、升级与备份见安装各页。

前提条件

项目	要求
目标主机	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 中执行以防断线。playbook 注册离线 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`

更多见排障。

本页内容