TLS — Xray-core

Xray 的 TLS 设置位于 streamSettings.tlsSettings 之下，前提是 streamSettings.security 为 "tls"。该结构体还涵盖 ECH 与 uTLS 指纹家族。REALITY 见 REALITY —— 它是与 TLS 并列的另一种 streamSettings.security 值，拥有自己的块。

TLS 设置

字段	类型	默认值	允许值	描述
`allowInsecure`	`bool`	`false`	`true \| false`	跳过服务端证书校验。仅供测试使用 —— 生产配置绝不应启用。
`certificates`	`[]*TLSCertConfig`	`[]`	`[TLSCertConfig]`	服务端证书（入站）或受信 CA 校验（出站）。多条目可在入站启用按 SNI 选择证书。
`serverName`	`string`	`(inferred)`	`<hostname>`	期望的服务器名。出站时作为发送的 SNI，并用作校验对端 leaf 证书的依据。入站时为 ACME 自动配证时使用的 SNI。
`alpn`	`*StringList`	`["h2", "http/1.1"]`	`<ALPN string>`	向对端宣告的应用层协议协商列表。
`enableSessionResumption`	`bool`	`false`	`true \| false`	启用 TLS session-ticket 复用（客户端侧）。
`disableSystemRoot`	`bool`	`false`	`true \| false`	忽略操作系统根 CA 集合。为 true 时只接受 `verify` 模式下的 `certificates` 条目。
`minVersion`	`string`	`1.2`	`1.0 \| 1.1 \| 1.2 \| 1.3`	可接受的最低 TLS 版本。
`maxVersion`	`string`	`1.3`	`1.0 \| 1.1 \| 1.2 \| 1.3`	可接受的最高 TLS 版本。
`cipherSuites`	`string`	`(library default)`	`<comma-separated cipher list>`	覆盖加密套件列表，使用 OpenSSL 风格名（如 `TLS_AES_128_GCM_SHA256:...`）。注意：TLS 1.3 会忽略此字段 —— 仅 TLS 1.2 的加密选择可配置。
`fingerprint`	`string`	`(unset)`	`chrome \| firefox \| safari \| edge \| 360 \| qq \| ios \| android \| random \| randomized`	uTLS ClientHello 指纹。会驱动整个 ClientHello 的形态（加密套件、扩展、签名算法），覆盖显式的 `cipherSuites` 字段。
`rejectUnknownSni`	`bool`	`false`	`true \| false`	入站 —— 拒绝 SNI 不匹配任何已配置证书的 TLS 连接。
`curvePreferences`	`*StringList`	`(library default)`	`X25519 \| P-256 \| P-384 \| P-521 \| X25519MLKEM768`	覆盖密钥交换曲线偏好列表。顺序敏感。
`masterKeyLog`	`string`	`(unset)`	`<file path>`	用于抓取 TLS 密钥的 SSLKEYLOGFILE 风格路径（供 Wireshark 解密）。生产环境切勿启用。
`pinnedPeerCertSha256`	`string`	`(unset)`	`<base64 SHA-256>`	锚定对端证书。仅出站 —— leaf 证书的 SHA-256 不匹配则拒绝连接。
`verifyPeerCertByName`	`string`	`(unset)`	`<hostname>`	设置后，按该名称校验对端证书的 Subject CN / SAN，而不按 `serverName`。SNI 与规范证书名不同时（REALITY 形态）很有用。
`verifyPeerCertInNames`	`[]string`	`[]`	`[<hostname>]`	`verifyPeerCertByName` 的列表形式 —— 列表中任一名称匹配即接受。
`echServerKeys`	`string`	`(unset)`	`<base64 ECHConfigList>`	入站 —— ECH 服务端密钥集合。
`echConfigList`	`string`	`(unset)`	`<base64 ECHConfigList>`	出站 —— 锚定的 ECH 配置列表。未设置时通过 HTTPS-record DNS 查询自动发现。
`echForceQuery`	`string`	`(unset)`	`hkdf \| dns`	强制使用特定的 ECH 发现机制。为空则按默认级联回落。
`echSockopt`	`*SocketConfig`	`(unset)`	`SocketConfig`	应用于 ECH 发现 DNS 请求的套接字选项。

源码： infra/conf/transport_internet.go:638-659 · 锚定版本 v26.6.1 (94ffd50)

`certificates[]`

字段	类型	默认值	允许值	描述
`certificateFile`	`string`	`(unset)`	`<PEM file path>`	PEM 证书文件路径。与 `certificate` 互斥。
`certificate`	`[]string`	`(unset)`	`[<PEM line>]`	内联 PEM 证书，字符串数组形式（每行一个元素，或整个 PEM 作为一个元素）。
`keyFile`	`string`	`(unset)`	`<PEM file path>`	PEM 私钥文件路径。
`key`	`[]string`	`(unset)`	`[<PEM line>]`	内联 PEM 私钥。
`usage`	`string`	`encipherment`	`encipherment \| verify \| issue`	证书用途：`encipherment`（服务端证书）、`verify`（用于校验对端的受信 CA）、`issue`（在部分转发模式中用作签发每连接证书的 CA）。
`ocspStapling`	`uint64`	`3600`	`<seconds>`	OCSP staple 刷新频率（秒）。0 关闭。
`oneTimeLoading`	`bool`	`false`	`true \| false`	启动时只读取一次证书与密钥，而不在重载时再次读取。使用内联 `certificate` / `key` 时自动置 true（没有可重读的路径）。
`buildChain`	`bool`	`false`	`true \| false`	PEM 只含 leaf 时，自动拉取中间 CA 拼接完整链。

源码： infra/conf/transport_internet.go:569-578 · 锚定版本 v26.6.1 (94ffd50)

示例

出站 —— 校验系统根证书、强制 TLS 1.3、锚定 chrome 指纹：

json

{
  "streamSettings": {
    "security": "tls",
    "tlsSettings": {
      "serverName": "example.com",
      "alpn": ["h2", "http/1.1"],
      "minVersion": "1.3",
      "maxVersion": "1.3",
      "fingerprint": "chrome"
    }
  }
}

入站 —— 部署 Let's Encrypt 证书：

json

{
  "streamSettings": {
    "security": "tls",
    "tlsSettings": {
      "serverName": "example.com",
      "certificates": [
        {
          "certificateFile": "/etc/ssl/cert.pem",
          "keyFile": "/etc/ssl/key.pem",
          "usage": "encipherment",
          "ocspStapling": 3600
        }
      ],
      "rejectUnknownSni": true
    }
  }
}

锚定证书的出站（绑定到特定 SHA-256）：

json

{
  "streamSettings": {
    "security": "tls",
    "tlsSettings": {
      "serverName": "example.com",
      "pinnedPeerCertSha256": "<base64-SHA256-of-leaf-cert>"
    }
  }
}

说明

fingerprint 走的是 uTLS —— 它会重写整个 ClientHello 来模拟所选浏览器。设置后 cipherSuites、curvePreferences 与 minVersion / maxVersion 大多会被忽略，因为 uTLS 自己控制这些。
按 Go 标准库，TLS 1.3 会忽略 cipherSuites —— 只有 TLS 1.2 的加密选择可配置。要在 TLS 1.3 中影响密钥交换，请使用 curvePreferences。
certificates[].usage 字段很关键：
- encipherment —— 普通服务端证书。
- verify —— 出站侧作为受信 CA 根使用。配合 disableSystemRoot: true 可忽略系统根证书。
- issue —— 在部分转发模式（MITM HTTPS 直通）中用于签发每连接证书。
verifyPeerCertByName 把 SNI 与被校验的名称解耦 —— 在 REALITY 风格部署中（SNI 是公共站点而真实证书属于 Xray 服务器时）很有用。
masterKeyLog 是调试辅助；文件格式遵循 Wireshark 接受的 SSLKEYLOGFILE 规范。生产环境切勿启用。

跨内核说明

sing-box 在每个入站 / 出站上内嵌单一的 tls: { ... } 块。字段名采用 snake_case（server_name、cipher_suites），REALITY / ECH / uTLS 以嵌套子块形式存在。参见 TLS — sing-box。
mihomo 把 TLS 字段直接散布到每个 proxy 适配器上 —— tls、 sni、alpn、skip-cert-verify 等。没有集中化的 TLS 块。参见 TLS — mihomo。

源码： infra/conf/transport_internet.go:569-659 · v26.6.1 (94ffd50)

TLS — Xray-core ​

TLS 设置 ​

certificates[] ​

示例 ​

说明 ​

跨内核说明 ​

TLS — Xray-core

TLS 设置

`certificates[]`

示例

说明

跨内核说明