From 08094c26605b53550be8c0ec2803a31c200b3f91 Mon Sep 17 00:00:00 2001
From: xiaojunnuo <xiaojunnuo@qq.com>
Date: Sat, 11 Oct 2025 16:59:28 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20ipv6=E5=9C=B0=E5=9D=80=E6=8F=90?=
 =?UTF-8?q?=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docker/run/docker-compose.yaml                  |  2 ++
 docs/guide/qa/use.md                            | 15 ++++++++++++++-
 packages/ui/certd-server/src/configuration.ts   |  5 +++++
 .../ui/certd-server/src/modules/auto/auto-z.ts  |  3 +++
 .../src/modules/auto/https/server.ts            | 17 +++++++++++++++--
 5 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/docker/run/docker-compose.yaml b/docker/run/docker-compose.yaml
index 76e0eaae..6af51df1 100644
--- a/docker/run/docker-compose.yaml
+++ b/docker/run/docker-compose.yaml
@@ -47,6 +47,8 @@ services:
 #     配置规则： certd_ + 配置项, 点号用_代替
 #                                    #↓↓↓↓ ----------------------------- 如果忘记管理员密码，可以设置为true，docker compose up -d 重建容器之后，管理员密码将改成123456，然后请及时修改回false
       - certd_system_resetAdminPasswd=false
+                        # ↓↓↓ 如果启动时报address family not supported错误，将此配置修改为0.0.0.0
+#      - certd_koa_hostname=::
 
 #     默认使用sqlite文件数据库，如果需要使用其他数据库，请设置以下环境变量
 #     注意： 选定使用一种数据库之后，不支持更换数据库。
diff --git a/docs/guide/qa/use.md b/docs/guide/qa/use.md
index c75407dd..6bc289d9 100644
--- a/docs/guide/qa/use.md
+++ b/docs/guide/qa/use.md
@@ -19,7 +19,7 @@
 "detail": too many certificates (5) already issued for this exact set of idantifiers in the last 168hm0s
 ```
 
-## ssl.com报错  CAA record does not include ssl.com which is required to issue the certificate
+## 4. ssl.com报错  CAA record does not include ssl.com which is required to issue the certificate
 ssl.com申请证书要求必须设置CAA记录，表示允许ssl.com为该域名颁发证书
 请按如下格式添加CAA记录
 
@@ -29,5 +29,18 @@ ssl.com申请证书要求必须设置CAA记录，表示允许ssl.com为该域名
 | 一级泛域名 | CAA | * | 0         | issue/issuewild | "ssl.com" |
 | 固定子域名 | CAA | sub |  0         | issue  |"ssl.com" |
 
+## 5. address family not supported
+启动时出现此错误，是由于您的服务器不支持绑定ipv6地址
+
+请配置环境变量 certd_koa_hostname=0.0.0.0
+
+在docker-compose.yml中添加如下配置
+
+```yaml
+service:
+  certd:
+    environment:
+      certd_koa_hostname: 0.0.0.0
+```
 
 
diff --git a/packages/ui/certd-server/src/configuration.ts b/packages/ui/certd-server/src/configuration.ts
index a730e592..718866dc 100644
--- a/packages/ui/certd-server/src/configuration.ts
+++ b/packages/ui/certd-server/src/configuration.ts
@@ -20,9 +20,13 @@ import * as commercial from '@certd/commercial-core';
 import * as upload from '@midwayjs/upload';
 import { setLogger } from '@certd/acme-client';
 import {HiddenMiddleware} from "./middleware/hidden.js";
+
 process.on('uncaughtException', error => {
   console.error('未捕获的异常：', error);
   // 在这里可以添加日志记录、发送错误通知等操作
+  if(error?.message?.includes('address family not supported')){
+    logger.error("您的服务器不支持监听IPV6格式的地址（::），请配置环境变量: certd_koa_hostname=0.0.0.0");
+  }
 });
 
 @Configuration({
@@ -107,5 +111,6 @@ export class MainConfiguration {
     });
 
     logger.info('当前环境：', this.app.getEnv()); // prod
+    // throw new Error("address family not supported")
   }
 }
diff --git a/packages/ui/certd-server/src/modules/auto/auto-z.ts b/packages/ui/certd-server/src/modules/auto/auto-z.ts
index af459ff3..3fe49988 100644
--- a/packages/ui/certd-server/src/modules/auto/auto-z.ts
+++ b/packages/ui/certd-server/src/modules/auto/auto-z.ts
@@ -19,6 +19,8 @@ export class AutoZPrint {
 
   @Config('https')
   httpsConfig: HttpsServerOptions;
+  @Config('koa')
+  koaConfig: any;
 
   @Init()
   async init() {
@@ -58,6 +60,7 @@ export class AutoZPrint {
     httpsServer.start({
       ...this.httpsConfig,
       app: this.app,
+      hostname: this.httpsConfig.hostname || this.koaConfig.hostname,
     });
   }
 }
diff --git a/packages/ui/certd-server/src/modules/auto/https/server.ts b/packages/ui/certd-server/src/modules/auto/https/server.ts
index 67d7ef5a..8e995bca 100644
--- a/packages/ui/certd-server/src/modules/auto/https/server.ts
+++ b/packages/ui/certd-server/src/modules/auto/https/server.ts
@@ -7,6 +7,7 @@ import {logger, safePromise} from '@certd/basic';
 export type HttpsServerOptions = {
   enabled: boolean;
   app?: Application;
+  hostname?: string;
   port: number;
   key: string;
   cert: string;
@@ -58,7 +59,7 @@ export class HttpsServer {
       opts.app.callback()
     );
     this.server = httpServer;
-    const hostname = '::';
+    let hostname = opts.hostname ||  '::';
     // A function that runs in the context of the http server
     // and reports what type of server listens on which port
     function listeningReporter() {
@@ -70,7 +71,19 @@ export class HttpsServer {
       httpServer.listen(opts.port, hostname, listeningReporter);
       return httpServer;
     } catch (e) {
-      logger.error('启动https服务失败', e);
+      if ( e.message?.includes("address family not supported")) {
+        hostname = "0.0.0.0"
+        logger.error(`${e.message}，尝试监听${hostname}`, e);
+        try{
+          httpServer.listen(opts.port, hostname, listeningReporter);
+          return httpServer;
+        }catch (e) {
+          logger.error('启动https服务失败', e);
+        }
+      }else{
+        logger.error('启动https服务失败', e);
+      }
+
     }
   }
 }