connect-domain

连接域名

让一个域名通过 HTTPS 提供 Hostinger 网站。最重要的一条规则：已有的有效记录——邮件（MX）、SPF、DKIM 和验证用的 TXT 记录——必须在每次 DNS 更改后保留。

调用操作

• 首次调用每项操作前，先阅读 search 返回的 inputSchema。如果下方某个名称被拒绝并提示未知，请按步骤要做的事进行 search（例如“DNS 记录”）。
• 使用 multi-execute 批量读取；值会通过 $steps.<i>.<path> 在步骤间传递。批次只能串联同一服务器上的操作——Hostinger Connector 会将 hosting、agency-hosting、domains 和 dns 作为独立服务器运行。如果 search 找不到某项操作，请让用户在 Connector 中启用相应的产品组。
• 这里的每项写入操作都会改变公众看到的内容。每次操作前都要说明更改内容并征得用户同意。

1. 收集事实（只读）

• 网站。 对 Shared 和 Cloud，使用 hosting_websites_list 并传入 domain（子字符串匹配，因此要选取完全匹配的条目）；对 Agency，使用 agency-hosting_websites_list-plan 并传入 domain。保留 username 和 order_id，或 details.uid 和 details.ipv4。如果该域名还没有网站，请找到用户所指的网站——通常是 *.hostingersite.com 域名下的网站——或者找到要用于创建网站的订单（hosting_orders_list、agency-hosting_orders_list）。
• 注册信息。 domains_portfolio_get 仅适用于在 Hostinger 注册的域名；其 name_servers 显示由谁运行 DNS。Hostinger 自有的名称服务器以 dns-parking.com 结尾。
• 当前 DNS，用于确认必须保留哪些内容：

dig +short NS DOMAIN; dig +short A DOMAIN; dig +short CNAME www.DOMAIN
dig +short MX DOMAIN; dig +short TXT DOMAIN; dig +short CAA DOMAIN

2. 将域名关联到主机服务

Shared 和 Cloud：

• 在该域名上创建新网站。 对于不属于此账户的域名，先运行 hosting_domains_verify-ownership。如果 is_accessible 为 false，请将其返回的 TXT 记录提供给用户，让用户将其添加到现有记录旁，然后再次验证（传播最多需要约 10 分钟）。使用 hosting_websites_create 创建网站（domain 不带 www.，并传入 order_id），然后每隔 10–15 秒使用 domain 调用 hosting_websites_list-setups，直到 status: completed。
• 将网站从免费子域名迁出。 Shared 和 Cloud 网站无法通过 API 重命名。可以在正式域名上创建网站，并在那里重新部署项目（使用 deploy-to-hosting 技能）——WordPress 必须采用此方式，因为它会将 URL 保存在数据库中；也可以对静态网站使用 hosting_domains_create-website-parked，将域名停放到现有网站上。
• 别名（另一个显示相同网站的域名）：使用 hosting_domains_create-website-parked。
• 子域名（shop.example.com）：使用 hosting_domains_create-website-subdomain。www 属于主域名——不要将其创建为子域名。

Agency Plan：

• agency-hosting_domains_link-to-website 会将域名添加到网站。
• agency-hosting_domains_change-website 会替换主域名，例如替换免费子域名。旧域名会立即停止提供服务——请先征得确认。

3. 将 DNS 指向 Hostinger

DNS 已在 Hostinger（名称服务器以 dns-parking.com 结尾）：通常，创建网站时会写入记录。使用 dns_records_list 查看区域；当 @ 和 www 已指向该网站时，不要更改任何内容。在进行任何编辑之前，记下最新的 dns_snapshots_list 条目——dns_snapshots_restore 会回滚到该条目。

dns_records_update 默认使用 overwrite: true，这会删除名称和类型相同的所有现有记录。以这种方式在 @ 添加 TXT 会清除 SPF 和验证记录。添加记录时发送 overwrite: false；仅在有意替换一组记录时使用 true，并先对同一负载运行 dns_records_validate。

DNS 在其他地方（在 Hostinger 注册但使用其他名称服务器，或在其他注册商注册）。有两个选项——让用户选择：

• 将名称服务器切换到 Hostinger。 此后由 Hostinger 管理所有记录。先使用 dns_records_update（overwrite: false）将当前 DNS 除网站记录外提供的每条记录——MX、TXT、服务 CNAME——复制到 Hostinger 区域；否则，名称服务器切换后电子邮件将无法正常工作。Hostinger 的名称服务器组合因域名而异（ns1/ns2.dns-parking.com、solar/lunar.dns-parking.com 等），因此请使用 hPanel 为该域名显示的组合，切勿猜测。对于在 Hostinger 注册的域名，使用 domains_portfolio_update-nameservers 应用设置；否则由用户在其注册商处更改。
• 保留当前 DNS 提供商，仅更改网站记录：@ 的 A 记录，以及 www 的 CNAME（或 A）记录。Agency 网站指向 details.ipv4。Shared 和 Cloud 网站指向该域名在 Hostinger 区域中的目标（dns_records_list）；若该区域不存在，则指向 hPanel 为该网站显示的 IP。用户在其 DNS 提供商处进行此更改。

4. SSL 和 HTTPS

仅当 dig 显示域名解析到 Hostinger 后才开始——证书颁发机构会根据服务器检查域名。

• Shared 和 Cloud：使用 hosting_ssl_status。当状态不是 active 时，调用 hosting_ssl_install 并轮询状态，直到变为 active（或状态为 failed 且带有 last_error），然后调用 hosting_ssl_toggle-https-redirect 并设置 is_enabled: true（证书存在之前会返回 422）。
• Agency：对每个域名调用 agency-hosting_ssl_install-website，然后轮询 agency-hosting_ssl_website-status。一个域名每七天最多允许设置三次，每分钟最多请求一次——DNS 正确后安装一次，切勿循环调用。
• 如果顶点上的 CAA 记录不允许 letsencrypt.org，就会阻止证书签发；用户需在现有记录旁添加 0 issue "letsencrypt.org"。

5. 验证

dig +short A DOMAIN; dig +short A www.DOMAIN
curl -sSI https://DOMAIN/ | grep -i -E "^(HTTP|platform|location)"
curl -sSI http://DOMAIN/ | grep -i -E "^(HTTP|location)"
dig +short MX DOMAIN

当两个名称都解析到 Hostinger、HTTPS 返回 platform: hostinger、HTTP 重定向到 HTTPS，且 MX 仍与步骤 1 一致时，即表示完成。名称服务器更改可能需要 24–48 小时才能传播到所有解析器；如果记录仍是旧值，请报告尚待完成的事项以及用于重新检查的命令，而不要连续轮询数小时。