Neon proxy 如何在本地搭配 Docker Postgres 与自签证书测试 TLS 连接

Neon proxy 如何在本地搭配 Docker Postgres 与自签证书测试 TLS 连接

【免费下载链接】neonNeon: Serverless Postgres. We separated storage and compute to offer autoscaling, code-like database branching, and scale to zero.项目地址: https://gitcode.com/GitHub_Trending/ne/neon

这篇文章解决一个具体任务：在 Neon 源码仓库本地把 proxy 跑起来，用一个 Docker 启动的 Postgres 实例作为鉴权后端，再配合一张自签证书，让客户端以sslmode=verify-full完成一次受证书校验的 TLS 连接。完整流程来自仓库 proxy/README.md 的 "Test proxy locally" 小节，文中命令均取自该文档及其指向的源码。

准备环境

在开始之前，本地需要具备：

• 已获取 Neon 仓库源码，并能用cargo构建。仓库的 rust-toolchain.toml 指定 Rust 版本为1.88.0，rustup 会自动切换到该工具链；
• Docker，用于启动 Postgres（以及可选的 Redis）；
• openssl，用于生成自签证书；
• psql客户端，用于最后发起 TLS 连接。

启动 Docker Postgres 并搭建鉴权表

proxy 使用--auth-backend postgres时，把指定的 Postgres 实例当作 mock 控制面：它从pg_catalog.pg_authid里按角色名读取密码信息（rolpassword），并从neon_control_plane.endpoints表读取allowed_ips，这两处查询逻辑见 proxy/src/control_plane/client/mock.rs。因此这个 Postgres 实例既是鉴权数据源，也是连接最终要到达的数据面，需要先启动并建好 schema、表与角色：

docker run \ --detach \ --name proxy-postgres \ --env POSTGRES_PASSWORD=proxy-postgres \ --publish 5432:5432 \ postgres:17-bookworm

容器起来后，执行三条建表/建角色语句：

docker exec -it proxy-postgres psql -U postgres -c "CREATE SCHEMA IF NOT EXISTS neon_control_plane" docker exec -it proxy-postgres psql -U postgres -c "CREATE TABLE neon_control_plane.endpoints (endpoint_id VARCHAR(255) PRIMARY KEY, allowed_ips VARCHAR(255))" docker exec -it proxy-postgres psql -U postgres -c "CREATE ROLE proxy WITH SUPERUSER LOGIN PASSWORD 'password';"

其中proxy这个角色就是稍后客户端登录时使用的用户名，其密码password会被 mock 控制面取出用于 SCRAM 校验。

如果还要顺带测试 query cancellation，文档要求再起一个 Redis（这也是下面 proxy 启动命令携带--redis-*参数的原因）：

docker run --detach --name proxy-redis --publish 6379:6379 redis:7.0

生成自签证书

proxy 从主机名的子域里解析 endpoint 名称，例如请求round-rice-566201.somedomain.tld会被路由到名为round-rice-566201的 project。由于/etc/hosts不支持通配域名，文档使用解析到127.0.0.1的*.local.neon.build域，并让自签证书的 CN 采用通配形式：

openssl req -new -x509 -days 365 -nodes -text -out server.crt -keyout server.key -subj "/CN=*.local.neon.build"

生成server.crt和server.key两个文件。通配 CN 并非随意选择：proxy 的证书解析逻辑会把CN=*.local.neon.build剥掉CN=*.前缀得到local.neon.build，再按 SNI 主机名逐级匹配（见 proxy/src/tls/server_config.rs），这正是客户端sslmode=verify-full能校验通过的前提。

构建并启动 proxy

RUST_LOG=proxy LOGFMT=text cargo run -p proxy --bin proxy --features testing -- \ --auth-backend postgres --auth-endpoint 'postgresql://postgres:proxy-postgres@127.0.0.1:5432/postgres' \ --redis-auth-type="plain" --redis-plain="redis://127.0.0.1:6379" \ -c server.crt -k server.key

参数与适用条件说明：

• --features testing：postgres这一 auth backend 只在testingfeature 下编译，见 proxy/src/binary/proxy.rs 中AuthBackendType的#[cfg(any(test, feature = "testing"))]标注。README 中postgres后端被描述为 "Useful for local testing"。
• --auth-endpoint：指向第 1 步的 Docker Postgres。源码要求 URL 里带密码；如果 URL 不带密码，则必须设置环境变量PGPASSWORD，否则 proxy 启动时报错。
• -c server.crt -k server.key：客户端 TLS 连接的证书与私钥路径，源码要求两者要么同时给出、要么都不给，且verify-full测试必须同时提供。
• --redis-auth-type/--redis-plain：指定 Redis 连接方式。proxy 启动时会尝试连接 Redis，失败会重试 3 次后退出，所以执行本命令前需要先起好上面的proxy-redis容器。
• 未显式指定的--proxy监听地址默认为127.0.0.1:4432，这是后面 psql 连接的端口。

用 psql 发起 verify-full TLS 连接

proxy 运行起来后，从客户端执行：

PGSSLROOTCERT=./server.crt psql "postgresql://proxy:password@endpoint.local.neon.build:4432/postgres?sslmode=verify-full"

这条命令各部分的含义：

• PGSSLROOTCERT=./server.crt：把上一步生成的自签证书作为信任根，客户端据此完成verify-full模式下的证书与主机名校验；
• endpoint.local.neon.build：该域名解析到127.0.0.1，第一段子域endpoint即 proxy 使用的 endpoint 名称；
• proxy:password：对应第 1 步创建的登录角色及其密码；
• sslmode=verify-full：启用最严格的 TLS 校验模式，校验失败会直接拒绝连接。

连接成功时 psql 进入交互式会话（文档未给出具体输出示例）；此时可以执行任意 SQL 验证查询是否经过 proxy 转发到了 Docker Postgres。

如果连接失败，文档中唯一明确的失败现象是：登录角色在 Postgres 中不存在时，proxy 日志会输出user '{role}' does not exist的 warning（来自 mock.rs 中do_get_auth_info的分支），鉴权随即失败——此时应回到第 1 步确认proxy角色已按文档创建。

边界与限制

• postgres这个 auth backend 只服务于本地测试场景，文档原文标注 "Useful for local testing"；生产环境使用的是 console 类鉴权后端，不在本文范围内。
• verify-full依赖客户端发送 SNI 且 SNI 与证书域匹配。proxy/src/tls/server_config.rs 的注释说明：不带 SNI 的连接会退回到默认证书，"This will error if the customer uses anything stronger than sslmode=require"，因此客户端应始终携带 SNI（即使用域名而非裸 IP 连接）。
• 本文的端口（Postgres5432、proxy4432、Redis6379）均沿用文档命令；如果本地端口被占用，需要自行调整对应监听参数并保持客户端连接串一致。

【免费下载链接】neonNeon: Serverless Postgres. We separated storage and compute to offer autoscaling, code-like database branching, and scale to zero.项目地址: https://gitcode.com/GitHub_Trending/ne/neon