Добавил policy HY2XS_DNS_AAAA_POLICY и управляемое AAAA-поведение в preflight

docs/12-operations-and-troubleshooting.md

@@ -120,6 +120,14 @@ curl -sS \
 - auth material
 - что используется совместимый клиентский конфиг
 
+### Install/reconfigure падает на DNS AAAA
+Проверить значение `HY2XS_DNS_AAAA_POLICY` в `/etc/hy2xs/hy2xs.env`:
+- `strict` (default): AAAA приводит к fail в IPv4-only профиле;
+- `warn`: warning + продолжение;
+- `off`: AAAA-check отключён.
+
+Для production baseline рекомендуется `strict`.
+
 ### Скорость не соответствует ожиданиям
 Проверить:
 - `bandwidth.*` на сервере

docs/13-production-runbook.md

@@ -82,6 +82,10 @@ hy2xs-orchestrator reconfigure --package-dir /usr/local/lib/hy2xs/package --conf
 
 - HY2XS работает в IPv4-only режиме.
 - если IPv6 включён на хосте/провайдере — это вне baseline и должно быть отдельно управляемо оператором.
+- `HY2XS_DNS_AAAA_POLICY` управляет реакцией preflight на DNS AAAA:
+  - `strict` (default) — install/reconfigure прекращается при наличии AAAA;
+  - `warn` — выводится warning и выполнение продолжается;
+  - `off` — AAAA-проверка игнорируется.
 
 ## 12. Validation command
 

orchestrator/src/config/env.ts

@@ -127,6 +127,14 @@ function normalizeAcmeType(value: string): "http" | "tls" | "dns" {
   throw new Error(`invalid HY2XS_ACME_TYPE: ${value}`);
 }
 
+function normalizeDnsAaaaPolicy(value: string | undefined): "strict" | "warn" | "off" {
+  const policy = value || "strict";
+  if (policy === "strict" || policy === "warn" || policy === "off") {
+    return policy;
+  }
+  throw new Error(`invalid HY2XS_DNS_AAAA_POLICY: ${value}`);
+}
+
 function normalizeFixedHysteriaAuthMode(value: string | undefined): "http" {
   const mode = value || "http";
   if (mode !== "http") {
@@ -180,12 +188,14 @@ export function parseRuntimeEnv(content: string): RuntimeConfig {
   const trafficStatsPort = parsePort("HY2XS_HYSTERIA_TRAFFIC_STATS_PORT", env.HY2XS_HYSTERIA_TRAFFIC_STATS_PORT, 36712);
   const tlsMode = normalizeTlsMode(env.HY2XS_TLS_MODE || "acme");
   const acmeType = normalizeAcmeType(env.HY2XS_ACME_TYPE || "http");
+  const dnsAaaaPolicy = normalizeDnsAaaaPolicy(env.HY2XS_DNS_AAAA_POLICY);
   const firewallMode = normalizeFirewallMode(env);
   const hysteriaAuthMode = normalizeFixedHysteriaAuthMode(env.HY2XS_HYSTERIA_AUTH_MODE);
   const hysteriaObfsType = normalizeFixedHysteriaObfsType(env.HY2XS_HYSTERIA_OBFS_TYPE);
 
   const config: RuntimeConfig = {
     domain: env.HY2XS_DOMAIN || "",
+    dnsAaaaPolicy,
     publicHost: normalizePublicHost(env.HY2XS_PUBLIC_HOST || env.HY2XS_DOMAIN || ""),
     publicPort: parsePort("HY2XS_PUBLIC_PORT", env.HY2XS_PUBLIC_PORT, hysteriaPort),
     ipv6Enabled: parseBool("HY2XS_IPV6_ENABLED", env.HY2XS_IPV6_ENABLED, false),
@@ -289,6 +299,7 @@ export function renderRuntimeEnv(config: RuntimeConfig): string {
     "# HY2XS runtime config (editable)",
     "HY2XS_IPV6_ENABLED=false",
     `HY2XS_DOMAIN=${config.domain}`,
+    `HY2XS_DNS_AAAA_POLICY=${config.dnsAaaaPolicy}`,
     `HY2XS_PUBLIC_HOST=${config.publicHost}`,
     `HY2XS_PUBLIC_PORT=${config.publicPort}`,
     `HY2XS_SSH_PORT=${config.sshPort}`,

orchestrator/src/steps/preflight.ts

@@ -143,10 +143,17 @@ export async function preflight(context: RuntimeContext): Promise<void> {
       }
     }
     if (aaaa.length > 0) {
+      if (context.config.dnsAaaaPolicy === "strict") {
         fail(
           `domain ${context.config.domain} has DNS AAAA record while HY2XS profile is IPv4-only; remove AAAA record before install`
         );
       }
+      if (context.config.dnsAaaaPolicy === "warn") {
+        info(
+          `warning: domain ${context.config.domain} has DNS AAAA record while HY2XS profile is IPv4-only; continuing due to HY2XS_DNS_AAAA_POLICY=warn`
+        );
+      }
+    }
   }
 
   const hysteriaUdpBusy = await isUdpPortListening(context.config.hysteriaPort);

orchestrator/src/types/context.ts

@@ -22,8 +22,11 @@ export type RunMode = "install" | "reconfigure";
 
 export type TlsMode = "acme" | "file" | "self_signed_dev";
 
+export type DnsAaaaPolicy = "strict" | "warn" | "off";
+
 export type RuntimeConfig = {
   domain: string;
+  dnsAaaaPolicy: DnsAaaaPolicy;
   publicHost: string;
   publicPort: number;
   ipv6Enabled: boolean;

package/config/hy2xs.env

@@ -1,6 +1,7 @@
 # HY2XS canonical production runtime config (packaged baseline)
 HY2XS_IPV6_ENABLED=false
 HY2XS_DOMAIN=uk.api.withen.pro
+HY2XS_DNS_AAAA_POLICY=strict
 HY2XS_PUBLIC_HOST=uk.api.withen.pro
 HY2XS_PUBLIC_PORT=443
 HY2XS_SSH_PORT=22