Ghostunnel：TLS 双向认证代理

项目简介

Ghostunnel 是一个简单的 TLS 代理，支持双向认证（mutual TLS），用来保护本身不具备 TLS 能力的后端应用。

它有两种运行模式：

• 服务器模式：运行在后端服务器前面，接受 TLS 加密连接，再代理转发到（不安全的）后端。后端可以是 TCP 主机/端口，也可以是 UNIX domain socket。
• 客户端模式：通过 TCP 或 UNIX domain socket 接受（不安全的）连接，再代理到 TLS 加密的服务。

Ghostunnel 在 Linux、macOS、Windows 上开发和测试，也能运行在 Go 支持的其他多数 UNIX 系统上，如 FreeBSD、OpenBSD、NetBSD。

主要功能

• 认证与授权：强制双向 TLS 认证，要求客户端提供有效证书；可对证书字段（CN、OU、DNS/URI SAN）做细粒度访问控制，也支持通过 Open Policy Agent（OPA）编写声明式授权策略，并支持基于 SPKI 公钥固定的 --allow-spki-pin 认证。
• 证书热替换：通过 SIGHUP/SIGUSR1 信号或定时重载间隔，无需重启即可重新加载证书，方便使用短期证书。
• 灵活的证书来源：支持 PEM/PKCS#12 文件、ACME（Let's Encrypt）、硬件安全模块（PKCS#11）、macOS Keychain、Windows 证书存储，以及 SPIFFE Workload API。
• 默认安全：除非显式使用 --unsafe-listen 或 --unsafe-target，监听地址与目标地址都限制在 localhost 和 UNIX socket，避免意外对外暴露；在 Linux 上默认启用 Landlock 沙箱限制进程权限。
• 指标与性能分析：内置 status 端口，提供 JSON 与 Prometheus 指标端点，并可选用 pprof 性能分析。
• 其他能力：UNIX domain socket、PROXY protocol v2、systemd/launchd socket 激活、Windows 服务管理（SCM）等。

安装与使用

Ghostunnel 通过 GitHub releases 和 Docker Hub 分发。官方发布二进制为尽力提供，通常在最新镜像上通过 GitHub Actions 构建；如需特定操作系统版本的兼容性，建议自行构建。

项目使用 mage 构建系统，mage 作为 Go 工具依赖提供，无需单独安装：

# 编译二进制
go tool mage go:build

# 构建容器
go tool mage docker:build

也可以运行 go tool mage -l 查看全部构建目标，并在 mage 命令后加 -v 获得更详细的输出。

Docker 镜像在每次发布时推送到 Docker Hub，提供三个变体：

镜像	Tag
Alpine	ghostunnel/ghostunnel:latest-alpine、ghostunnel/ghostunnel:v1.x.x-alpine
Debian	ghostunnel/ghostunnel:latest-debian、ghostunnel/ghostunnel:v1.x.x-debian
Distroless	ghostunnel/ghostunnel:latest-distroless、ghostunnel/ghostunnel:v1.x.x-distroless

latest 标签始终指向最新版本；不带后缀的 ghostunnel/ghostunnel:latest 与 ghostunnel/ghostunnel:v1.x.x 是 Alpine 变体的别名。

生成测试证书

快速测试和开发时，可用内置生成器创建一次性测试证书：

# 生成测试证书和密钥
go tool mage test:keys

这会在 test-keys 目录下创建测试所需的全部证书和密钥。

服务器模式示例

监听 localhost:8443 的 TLS 连接并转发到 localhost:8080（listen 和 target 也都可以接受 UNIX domain socket 路径）：

# 启动后端服务
nc -l localhost 8080

# 启动服务器模式的 Ghostunnel
ghostunnel server \
    --listen localhost:8443 \
    --target localhost:8080 \
    --keystore test-keys/server-keystore.p12 \
    --cacert test-keys/cacert.pem \
    --allow-cn client

用客户端证书验证能否连接：

openssl s_client \
    -connect localhost:8443 \
    -cert test-keys/client-combined.pem \
    -key test-keys/client-combined.pem \
    -CAfile test-keys/cacert.pem

客户端模式示例

监听 localhost:8080 并代理到 localhost:8443 的 TLS 服务端：

# 启动后端 TLS 服务
openssl s_server \
    -accept 8443 \
    -cert test-keys/server-combined.pem \
    -key test-keys/server-combined.pem \
    -CAfile test-keys/cacert.pem

# 启动客户端模式的 Ghostunnel
ghostunnel client \
    --listen localhost:8080 \
    --target localhost:8443 \
    --keystore test-keys/client-combined.pem \
    --cacert test-keys/cacert.pem

验证能否连接：nc -v localhost 8080

两种模式还可以组合成完整隧道（客户端 + 服务器），启动顺序不限。查看可用命令与参数可运行 ghostunnel --help，或用 ghostunnel server --help、ghostunnel client --help 查看子命令详情；项目还为 Linux 和 macOS 提供了 man page。

注意事项

• go tool mage test:keys 生成的是测试证书，不可用于生产环境。生产请使用现有 PKI，或借助 mkcert、cloudflare/cfssl 等工具构建。
• 服务器模式必须至少指定 --allow-all、--allow-cn、--allow-ou、--allow-dns、--allow-uri、--allow-policy 之一，或使用 --allow-spki-pin；多个标志之间是逻辑或（OR）关系，任一匹配即可连接。
• 默认前台运行并输出日志到 stdout；可用 --syslog 改为写入 syslog，如需后台运行建议交给服务管理器。
• 可用 --quiet=... 静默特定类型的日志，支持 all、conns、conn-errs、handshake-errs，该标志可重复传入。在 Kubernetes 中对监听端口做 TCP 健康检查时，建议加 --quiet=handshake-errs 避免每次检查产生握手失败日志。
• --keystore 可接受 PKCS#12 keystore 或证书链与私钥合并的 PEM 文件（格式自动识别），也兼容 JCEKS/JKS；--cert / --key 则用于分别加载 PEM 证书链和私钥。

---

本作品整理自 GitHub 开源项目 ghostunnel/ghostunnel，原作者 @ghostunnel，许可证 Apache-2.0。中文介绍由 AI 根据项目 README 整理，以原仓库为准。