证书提供方 — sing-box

证书提供方为入站获取并续期 TLS 服务端证书。在顶层 certificate_providers 数组中声明它们，并在入站 tls 块中通过 certificate_provider 引用 —— 按 tag 引用，或以带自身 type 的对象内联。共有三种类型：acme（Let's Encrypt、ZeroSSL 或任意 ACME CA）、cloudflare-origin-ca（来自 Cloudflare Origin CA 的证书）和 tailscale（经由 Tailscale 端点获取的节点 tailnet 证书）。它们取代了内联 tls.acme 块，后者已弃用。

信封

每个 certificate_providers[] 条目包含 type 和 tag，以及同一层级上该类型的字段：

字段	类型	默认值	允许值	描述
type	string	(required)	acme | cloudflare-origin-ca | tailscale	证书提供方类型；决定适用下方哪一组字段。未知类型会在启动时失败。
tag	string	(unset)	<string>	入站 tls.certificate_provider 引用的名称。内联证书提供方不使用。

源码： option/certificate_provider.go:18-22 · 锚定版本 v1.14.2 (af6e64c)

入站通过 tls.certificate_provider 使用证书提供方：字符串是 certificate_providers 条目的 tag，对象则是带自身 type 的内联证书提供方。它与 certificate / key、内联 acme 块及 REALITY 的关系见 TLS。

acme

字段	类型	默认值	允许值	描述
domain	badoption.Listable[string]	(required)	<domain> | <IP address>	要申请证书的名称。接受 IP 地址（见 profile）。
data_directory	string	$XDG_DATA_HOME/certmagic	<dir path>	ACME 账户数据和证书的存放目录。回退为 $HOME/.local/share/certmagic。
default_server_name	string	(unset)	<hostname>	ClientHello 不带 SNI 时用于挑选证书的服务器名。
email	string	(unset)	<e-mail>	用于创建或选择 ACME 账户的电子邮件地址。
provider	string	letsencrypt	letsencrypt | zerossl | <https:// directory URL>	ACME CA。使用 zerossl 时，external_account、email、account_key 至少需要其一；设置了 email 而没有 external_account 时会自动申请 EAB 凭据。
account_key	string	(unset)	<PEM key>	要复用的已有 ACME 账户的 PEM 私钥。
disable_http_challenge	bool	false	true | false	禁用 HTTP-01 质询。
disable_tls_alpn_challenge	bool	false	true | false	禁用 TLS-ALPN-01 质询。
alternative_http_port	uint16	80	<port>	HTTP-01 质询监听器使用的端口（代替 80）；80 端口仍须能到达它。
alternative_tls_port	uint16	443	<port>	TLS-ALPN-01 质询监听器使用的端口（代替 443）；系统必须把 443 转发到该端口。
external_account	*ACMEExternalAccountOptions	(unset)	{ key_id, mac_key }	外部账户绑定（EAB）：CA 通过带外方式签发的密钥标识和 MAC 密钥。
dns01_challenge	*ACMEProviderDNS01ChallengeOptions	(unset)	ACMEProviderDNS01ChallengeOptions	使用 DNS-01 质询（见下文）。设置后其他质询类型会被禁用。
key_type	ACMEKeyType	(library default)	ed25519 | p256 | p384 | rsa2048 | rsa4096	新签发证书的私钥类型。
profile	string	(unset)	<ACME profile>	请求的 ACME profile。使用 Let's Encrypt 且任一域名为 IP 地址时，自动选择 shortlived。
http_client	*HTTPClientOptions	(default client)	<http_clients tag> | HTTPClientOptions	所有 ACME 请求使用的 HTTP 客户端：内联对象，或 http_clients 条目的 tag。

源码： option/acme.go:15-31 · 锚定版本 v1.14.2 (af6e64c)

DNS-01 质询

dns01_challenge 接受一个 provider 及该服务商的凭据，外加以下调节字段：

字段	类型	默认值	允许值	描述
ttl	badoption.Duration	(provider default)	<duration>	临时 _acme-challenge TXT 记录的 TTL。
propagation_delay	badoption.Duration	0s	<duration>	创建记录后等待该时长再开始检查传播。
propagation_timeout	badoption.Duration	(library default)	<duration> | -1	等待传播的最长时间；-1 禁用传播检查。
resolvers	badoption.Listable[string]	(system)	<resolver> | …	传播检查使用的 DNS 解析器。
override_domain	string	(unset)	<domain>	改为在该域名下写入质询记录 —— 用于 _acme-challenge 被委派到其他区域的情况。

源码： option/acme.go:41-47 · 锚定版本 v1.14.2 (af6e64c)

provider	凭据字段
alidns	access_key_id、access_key_secret、region_id、security_token（STS 临时凭据）
cloudflare	api_token、zone_token（可选，具有 Zone:Read 权限的令牌，使 api_token 可限定到单个区域）
acmedns	username、password、subdomain、server_url（一个 ACME-DNS 服务器）

cloudflare-origin-ca

字段	类型	默认值	允许值	描述
domain	badoption.Listable[string]	(required)	<domain> | *.<domain>	写入证书的主机名，可包含通配符。
data_directory	string	$XDG_DATA_HOME/certmagic	<dir path>	存放签发的证书、私钥和元数据的根目录。默认值与 ACME 证书提供方相同。
api_token	string	(unset)	<token>	具有 Zone / SSL and Certificates / Edit 权限的 Cloudflare API 令牌。api_token 与 origin_ca_key 必须且只能设置其一。
origin_ca_key	string	(unset)	<key>	Cloudflare Origin CA Key，另一种凭据。与 api_token 互斥。
request_type	CloudflareOriginCARequestType	origin-rsa	origin-rsa | origin-ecc	请求的密钥类型：RSA 或 ECDSA P-256。
requested_validity	CloudflareOriginCARequestValidity	5475	7 | 30 | 90 | 365 | 730 | 1095 | 5475	证书有效期（天）（5475 = 15 年）。
http_client	*HTTPClientOptions	(default client)	<http_clients tag> | HTTPClientOptions	调用 Cloudflare API 使用的 HTTP 客户端：内联对象，或 http_clients 条目的 tag。

源码： option/origin_ca.go:12-20 · 锚定版本 v1.14.2 (af6e64c)

tailscale

字段	类型	默认值	允许值	描述
endpoint	string	(required)	<endpoint tag>	Tailscale 端点的 tag，使用其节点证书（其 *.ts.net 名称）。必须在 Tailscale 管理控制台中启用 MagicDNS 和 HTTPS。

源码： option/tailscale.go:78-80 · 锚定版本 v1.14.2 (af6e64c)

示例

使用 Cloudflare DNS-01 质询的共享 ACME 证书提供方，按 tag 引用：

{
  "certificate_providers": [
    {
      "type": "acme",
      "tag": "le",
      "domain": ["example.com"],
      "email": "admin@example.com",
      "dns01_challenge": {
        "provider": "cloudflare",
        "api_token": "<cloudflare-api-token>"
      }
    }
  ],
  "inbounds": [
    {
      "type": "trojan",
      "tag": "trojan-in",
      "listen": "::",
      "listen_port": 443,
      "users": [{ "name": "user", "password": "<password>" }],
      "tls": {
        "enabled": true,
        "certificate_provider": "le"
      }
    }
  ]
}

Tailscale 端点的 tailnet 证书；入站随后设置 "certificate_provider": "ts-cert"：

{
  "endpoints": [
    { "type": "tailscale", "tag": "ts-ep", "auth_key": "tskey-auth-xxxxxxxxxxxx" }
  ],
  "certificate_providers": [
    { "type": "tailscale", "tag": "ts-cert", "endpoint": "ts-ep" }
  ]
}

从内联 tls.acme 迁移

把 tls.acme 的字段原样移到 tls.certificate_provider 中并加上 "type": "acme"（或移到按 tag 引用的 certificate_providers 条目中）：

// 之前（已弃用）
"tls": { "enabled": true, "acme": { "domain": ["example.com"], "email": "admin@example.com" } }

// 之后
"tls": { "enabled": true, "certificate_provider": { "type": "acme", "domain": ["example.com"], "email": "admin@example.com" } }

说明

• 构建标签：acme 需要 with_acme，tailscale 需要 with_tailscale；缺少时该类型仍存在，但会在启动时失败。cloudflare-origin-ca 始终编译在内。
• 带 tag 的证书提供方可以被多个入站引用。
• Cloudflare Origin CA 证书只受 Cloudflare 自身边缘节点信任。请用于位于 Cloudflare 代理之后的源站，而不是供客户端直连使用。证书提供方会在到期前自动续期。
• 若 endpoint 为空、不存在或不是 Tailscale 端点，tailscale 证书提供方会在启动时失败。
• ACME 字段与已弃用的内联 tls.acme 块一致，另有 account_key、key_type、profile 和 http_client。

跨内核说明

• Xray-core 没有内置 ACME 或证书提供方：服务端证书来自 tlsSettings.certificates 中的文件或内联 PEM。参见 TLS — Xray-core。
• mihomo 也没有：监听器直接接受证书和私钥。参见 TLS 概览 — mihomo。

源码： option/certificate_provider.go:18-69 · v1.14.2 (af6e64c)