tls certificates

TLS 证书

Meridian 支持原生 HTTPS，也可以放在已有 HTTPS 网关后面。此页介绍“全局设置 → TLS 设置”中的原生证书管理；外部网关见 反向代理。

先确定域名与端口

配置	示例	含义
面板访问域名	panel.example.com	完整域名，不含协议、端口和路径。
监听端口	9090	Meridian 进程实际监听的端口。
节点泛域名	*.example.com	域名前缀站点使用的通配域名；Cloudflare 自动申请流程需要它。

页面分别显示当前生效地址与已保存设置。监听端口表单以已保存的内部端口为准；公开网关端口可以与内部端口不同，不能把浏览器显示的 443 或 8443 当成内部监听端口。

端口或 TLS 状态变化需要按提示重启，并同步调整反向代理。单纯更新有效证书时可热重载。

外部代理使用的公网端口不能同时交给 Meridian 原生 HTTPS。切换前先调整代理与 PANEL_BIND_ADDR；外部代理模式禁止直接切换内部端口或在面板中申请、导入原生 HTTPS 证书。

检查、保存与应用

1. 填写域名、节点泛域名和监听端口，点击“检查配置”。
2. 页面持续显示检查结果与处理原因。DNS 不可用、Cloudflare 代理不支持所选端口、浏览器禁用端口、本机端口占用和站点冲突会阻止保存。
3. 点击“检查并保存”时会重新检查。拒绝保存时，原域名、端口、证书及凭据保持原值。
4. 保存后页面标记“等待应用”；当前进程仍使用原地址。需要更换证书时，先完成证书配置。
5. 点击“应用设置并重启”时再次检查 DNS、端口与证书。新地址就绪后页面自动跳转；更换域名后需要重新登录。

已通过的检查不会绕过后续校验。例如检查后把记录改为 Cloudflare 代理，或者保存后端口被其他程序占用，保存或重启仍会被拒绝。HTTP 初次配置可以先保存 Cloudflare 支持的 HTTPS 端口，但需要先应用证书才能按 HTTPS 重启。

检查能确认服务器看到的 DNS、标准代理端口和本机配置，不能证明所有客户端网络、云防火墙、容器端口映射或外部代理回源均可用。页面中的“配置检查通过”不代表这些外部设置已自动完成。特殊的 Cloudflare Spectrum 转发不在面板的标准代理校验范围内。

Cloudflare 代理与泛域名记录

普通 Cloudflare 代理支持的 HTTPS 端口为 443、2053、2083、2087、2096、8443。使用其他 HTTPS 端口时，把面板域名对应的记录设为“仅 DNS”，并指向服务器。

例如 *.example.com 为“仅 DNS”，但单独的 panel.example.com 仍开启代理，访问 panel.example.com:6551 仍会经过 Cloudflare。单独记录优先于泛域名记录，需修改单独的 panel 记录。面板根据实际解析的 IP 判断代理状态，不会仅因域名托管在 Cloudflare 就禁止自定义端口。

证书来源

来源	适用情况	更新方式
Cloudflare 自动申请	DNS 在 Cloudflare，需要泛域名证书	Meridian 定期检查并在到期前续签。
服务器文件路径	已有 certbot、acme.sh 或其他证书管理工具	检查文件变化并热重载。
上传证书	已有 PEM 文件，或不便提供服务器路径	到期前重新上传。

导入时验证 PEM 格式、私钥配对、证书时间和域名覆盖。使用完整证书链与未加密的 PEM 私钥；只有证书而没有匹配私钥不能使用。

页面分别展示“当前提供的证书”和“已保存的证书”，并显示覆盖域名、有效期和服务器信任链检查。信任链检查使用服务器的根证书库；内部 CA 或自签名证书可以导入，但客户端需要单独信任对应 CA。域名匹配或时间有效不代表客户端一定信任。

Cloudflare 自动申请

1. 先保存面板域名、节点泛域名和监听端口。
2. 选择 Cloudflare 自动申请，填写 ACME 邮箱。
3. 在 Cloudflare 创建 API Token，只授予目标 Zone 的 Zone Read 与 DNS Edit 权限。
4. 填写 Token，申请证书。
5. 查看签发结果，并按提示重启启用 HTTPS。

此流程使用 DNS-01，不依赖公网 80 端口。它签发节点的通配证书，面板应是该基础域下一层子域，例如 panel.example.com 对应 *.example.com。

申请证书只会创建临时验证 TXT 记录，不会自动创建面板或节点的 A / AAAA 记录。访问前需将这些域名解析到服务器；使用 Cloudflare 不支持的 HTTPS 端口时，代理状态应设为“仅 DNS”。

自动续签需要有效的邮箱、Token、持久密钥和出站网络。Meridian 每 12 小时检查一次，在证书到期前 30 天进入续签窗口。失败后通常一小时重试；签发方要求更长等待时遵守其 Retry-After。页面显示最近检查、最近更新成功、维护失败原因与下次检查或重试时间；这些记录在重启后保留。

“测试签发”只验证签发流程，产物单独保存在 TLS 数据目录的 acme-test 子目录，不替换服务证书，也不修改正式续签凭据。通过后取消测试选项，再申请正式证书。命令行 tls issue --staging 同样仅作测试；测试产物不纳入服务 TLS 备份。

旧版本启用的测试环境不会自动续签为新的测试证书，需要主动申请正式证书。正式申请不会复用旧测试环境或未通过服务器信任链检查的证书；只有正式申请和证书校验成功后才保存新的邮箱、Token 与证书来源，失败时保留原配置。

DNS 验证时会同时查询系统 DNS 和域名的权威 DNS，避免系统缓存的“记录不存在”（NXDOMAIN）阻塞刚写入的 TXT 记录。验证最多等待两分钟，单次 DNS 查询也有超时；签发流程设有五分钟超时。失败原因会保留在页面上。

如果提示 DNS-01 记录未传播，请在仍显示“签发中”时检查 _acme-challenge.<基础域名> 的 TXT 记录、Cloudflare 域名托管是否生效，以及服务器能否访问 DNS 的 UDP/TCP 53 端口。签发成功或失败后，程序都会清理本次临时验证记录，因此超时后查不到该记录不能单独证明写入失败。

服务器路径

例如：

证书链：/etc/meridian-certs/fullchain.pem
私钥：/etc/meridian-certs/privkey.pem

必须填写服务器上的绝对路径，服务账户需要读取文件及其父目录的权限。Docker 中路径指容器内部路径，需要事先挂载。

Meridian 每分钟检查外部文件变化，验证成功后热重载。更新为无效文件不会立即替换当前有效证书；仍须确保原证书到期前完成有效续期。

存在待应用域名或证书时，后台维护继续使用当前生效配置的域名、来源与凭据。当前证书续签或重载不会提前启用待应用证书，也不会覆盖为新配置保存的证书文件；只有显式应用并重启才切换到新配置。

不应通过把私钥改成全局可读来解决权限问题。使用专用目录或适当的只读挂载，让服务账户具备必要读取权限。

上传证书

选择完整 PEM 证书链与未加密私钥，再提交导入。上传后由 Meridian 管理副本；证书提供方续期时不会自动替你上传新文件。

上传适合已有证书或迁移场景。来源为上传时，界面会提示到期前重新上传。

泛域名覆盖

*.example.com 覆盖 panel.example.com、cinema.example.com 等一层子域，不覆盖根域 example.com，也不覆盖 deep.cinema.example.com。

配置了节点泛域名时，导入证书必须同时满足面板与节点域名覆盖要求；否则导入失败并保留原配置。

面板和站点可以使用不同的基础域名，例如 panel.example.com 与 *.example.net。原生 HTTPS 需要同一张证书同时覆盖两者；当前共用一套证书，不支持两张独立证书按域名选择。内置 Cloudflare 自动申请仍要求面板属于节点基础域名。使用两套独立证书时，可由外部 Nginx 分别提供 HTTPS，见 分域名反向代理。

常见问题

现象	检查
Cloudflare 申请失败	Token 的目标 Zone 与权限、DNS-01 传播、出站网络和签发限制。
文件路径不可读取	是否填写本机 / 容器中的真实路径，服务账户是否有读取与目录遍历权限。
私钥不匹配	证书与私钥是否来自同一套签发结果。
域名不匹配	是否包含完整面板域名与配置的通配域名。
更新后仍访问旧端口	当前端口与设置端口是否不同，服务和网关是否已重启 / 调整。
独立站点端口仍是 HTTP	核对原生 TLS 状态，不只看网关外层 HTTPS。

证书到期不会自动关闭 HTTPS、改为 HTTP 或触发重启。ACME 自动续签继续按重试计划运行，成功后热加载证书；路径或上传证书需由对应管理工具或管理员更新。更新成功前，普通客户端仍会拒绝过期证书。面板无法通过可信 HTTPS 打开时，可通过服务器上的证书工具或 meridian tls issue 恢复；CLI 操作应按部署方式先停止服务并以服务账户执行，成功后再启动服务。

安装器也支持泛域名配置及失败回滚，见 Linux 安装。