证书与 HTTPS 拦截

为了在不解密的情况下转发 HTTPS 流量，传统的 HTTP 代理是做不到的——浏览器/客户端会拒绝中间人。RelayCore 通过动态签发证书实现透明 HTTPS 拦截：客户端与 RelayCore 之间使用 RelayCore 签发的证书（被客户端信任），RelayCore 与上游之间使用真正的 HTTPS 握手。

要让这个机制工作，必须先生成一个 CA 证书并将其安装到客户端的信任库中。

默认存储

所有 CA 相关文件都放在数据目录下（默认 ~/.relay-core）：

ca_cert.pem — CA 证书
ca_key.pem — CA 私钥
ca_cert.json — CA 元数据（持久化加载所需）

使用 RELAY_CA_CERT / RELAY_CA_KEY 可覆盖默认路径（须成对设置）。run 命令在 CA 文件缺失时会直接失败并提示先生成。

快速流程

# 1. 生成 CA（一次性）
relay-core-cli ca generate

# 2. 安装到系统信任库
relay-core-cli ca install   # macOS 自动；其他平台见下文

# 3. 启动代理
relay-core-cli run

`ca` 子命令

relay-core-cli ca <subcommand>

  generate [--force]        生成 CA（--force 覆盖已有）
  install                   安装到系统信任库
  uninstall                 从系统信任库移除
  status                    显示路径、存在性与信任状态
  export [-o PATH] [--der]  导出证书；--der 输出 Windows .cer 适用的二进制

平台说明

macOS

ca install 会把 CA 写入系统钥匙串。在写入前会先清理旧的 RelayCraft CA 条目（避免遗留指纹冲突）。

ca status 通过 SHA-1 比对本地证书与钥匙串里的条目：

$ relay-core-cli ca status
CA cert: /Users/me/.relay-core/ca_cert.pem
CA key:  /Users/me/.relay-core/ca_key.pem
Trusted in keychain: yes
Keychain SHA-1:       12:34:56:78:9a:bc:de:f0:12:34:56:78:9a:bc:de:f0:12:34:56:78
Local cert SHA-1:     12:34:56:78:9a:bc:de:f0:12:34:56:78:9a:bc:de:f0:12:34:56:78
Match:                OK

如果显示 Match: MISMATCH，通常是重新生成过 CA 但没有再次安装，重新运行 ca install 即可。

Linux

目前没有自动安装步骤。手动：

# Debian / Ubuntu
sudo cp ~/.relay-core/ca_cert.pem /usr/local/share/ca-certificates/relay-core.crt
sudo update-ca-certificates

# RHEL / Fedora
sudo cp ~/.relay-core/ca_cert.pem /etc/pki/ca-trust/source/anchors/relay-core.crt
sudo update-ca-trust

# Arch
sudo trust anchor ~/.relay-core/ca_cert.pem

# 验证
curl -vI https://example.com --proxy http://127.0.0.1:8080

Windows

用 --der 输出二进制 .cer：

relay-core-cli ca export -o relay-core.cer --der

双击 .cer → "安装证书" → "本地计算机" → "将所有证书放入下列存储" → "受信任的根证书颁发机构"。PowerShell 等价命令：

Import-Certificate -FilePath .\relay-core.cer `
  -CertStoreLocation Cert:\LocalMachine\Root

Firefox / 浏览器专属信任库

Firefox 单独维护自己的 CA 信任库，不使用系统证书。需要在 设置 → 隐私与安全 → 证书 → 查看证书 → 导入 中导入 ca_cert.pem，并勾选"信任由此证书标识的网站"。

CI 与容器环境

把 ca_cert.pem 编入 Docker 镜像的 /usr/local/share/ca-certificates/ 并在 Dockerfile 中执行 update-ca-certificates。
在 CI 中测试需要 HTTPS 拦截的链路时，可用 ca export --der 把证书喂给 runner 的 trust store。
使用 ca install --help 查看与代理并存时的冲突解决细节。

卸载

# macOS
relay-core-cli ca uninstall

# Linux
sudo rm /usr/local/share/ca-certificates/relay-core.crt
sudo update-ca-certificates --fresh

卸载后再次访问 HTTPS 站点会出现证书错误——这是预期行为，证明 CA 之前确实在工作。