Neon Proxy Service Design
Neon Proxy 服务化接入设计
1. 方案总览与改造范围
一期为新建 Compute 默认提供共享的 PostgreSQL 入口,由 Proxy 完成认证和选路,SC 保存元信息,节点 Agent 向管控上报唤醒请求。
flowchart LR
C["PG 客户端"] --> E["负载均衡器"] --> P["共享 Proxy 实例<br/>2 个节点,各运行 Proxy 和 Agent"]
P --> A["Compute A · main 分支"]
P --> B["Compute B · dev 分支"]
P -.->|"查路由和角色"| S["SC · MetaDB"]
P -.->|"Agent 上报唤醒请求"| M["云管控"]
实线是 SQL 连接。负载均衡器选 Proxy 副本,Proxy 按 endpoint 选分支和节点。每个分支的 Compute 对应一个唯一实例 ID,包含一个主节点,可配 2–4 个只读节点。
| 改动项目 | 本期交付 |
|---|---|
| Proxy 接入 | 复用 PG/TLS 和 SCRAM,新增 SC 客户端、按实例及节点选路、本地硬 TTL 缓存、并发回源控制和限时建连重试。 |
| 节点 Agent | 监督本机 Proxy 进程、采集指标、转发本机管理请求,通过管控通知通道单向上报激活意图。 |
| StorageController(SC) | 增加两张表和五个业务 API。Proxy 只读,管控写路由,Compute 写自身的角色。只有 SC 访问 MetaDB。 |
| Compute | 网页配置和角色 SQL 共用提交前同步。主节点默认启动 PgBouncer,普通端口和事务池端口分别验收。 |
| 云管控对接 | 创建节点并将其注册到负载均衡后端组,发布路由,根据实际状态处理唤醒,在 Compute 恢复后补发配置。 |
一期边界。 仅接入新实例,无 Redis。PG CancelRequest 到达 Proxy 后计数并结束取消连接,例如 psql 按 Ctrl+C 后原 SQL 仍可能继续执行。查询时长可由 Compute 的 statement_timeout 限制。
1.1 元信息与表结构
SC 将路由按实例和节点保存,将认证材料按实例和角色保存,同一 Compute 的主节点与只读节点共享角色目录。
| 表 | 写入者与数据 | 高频查询及索引 |
|---|---|---|
proxy_endpoints |
管控发布分支、主 VIP 或成员 IP、端口、TLS 名称、路由状态和版本 | (instance_id, node_key) 唯一索引,支持登录取址和切换后刷新 |
proxy_roles |
Compute 同步 LOGIN、SCRAM verifier、有效期、删除标记和角色版本 | (instance_id, role_name) 唯一索引,支持认证、对账和幂等写入 |
两表均用自增数值主键、创建和更新时间、三个预留列,无外键。各调用方遵守 DDL 中的长度上限,按 PG 目录保留角色名大小写。MetaDB 用 UTF8,timestamptz 按部署时配置的本机时区显示。角色表只接收合法 verifier 或显式空值。建表 SQL 如下。
-- PostgreSQL / UTF8。整份迁移在同一事务执行。
BEGIN;
CREATE TABLE proxy_endpoints (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
instance_id varchar(128) NOT NULL,
node_key varchar(16) NOT NULL CHECK (node_key IN ('primary','ro1','ro2','ro3','ro4')),
branch_id varchar(128) NOT NULL,
target_ip inet,
compute_port integer CHECK (compute_port BETWEEN 1 AND 65535),
pooler_port integer CHECK (pooler_port BETWEEN 1 AND 65535),
tls_server_name varchar(253),
route_state smallint NOT NULL CHECK (route_state IN (0,2,5)),
route_version bigint NOT NULL CHECK (route_version > 0),
reserve_1 varchar(256), reserve_2 varchar(256), reserve_3 varchar(256),
create_at timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP,
update_at timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP,
CHECK (route_state <> 2 OR (target_ip IS NOT NULL AND compute_port IS NOT NULL)),
CHECK (pooler_port IS NULL OR (node_key = 'primary' AND route_state = 2 AND pooler_port <> compute_port)),
CHECK (instance_id ~ '^[a-z0-9]+$'),
CHECK (target_ip IS NULL OR masklen(target_ip) = CASE family(target_ip) WHEN 4 THEN 32 ELSE 128 END)
);
COMMENT ON COLUMN proxy_endpoints.pooler_port IS '已发布的主节点 PgBouncer 端口,NULL 表示池化入口暂不可用';
COMMENT ON COLUMN proxy_endpoints.route_state IS '节点路由的发布状态:0 已登记但暂不可用,2 可连接,5 已退役';
COMMENT ON COLUMN proxy_endpoints.instance_id IS '路由域内唯一的分支 Compute 实例 ID,主备切换时沿用';
COMMENT ON COLUMN proxy_endpoints.node_key IS 'primary 对应主 VIP;ro1 至 ro4 各对应一个只读节点的可达地址';
CREATE UNIQUE INDEX proxy_endpoint_lookup ON proxy_endpoints(instance_id, node_key);
CREATE TABLE proxy_roles (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
instance_id varchar(128) NOT NULL CHECK (instance_id ~ '^[a-z0-9]+$'),
role_name varchar(128) NOT NULL,
can_login boolean NOT NULL,
scram_verifier varchar(1024),
valid_until timestamptz,
is_deleted boolean NOT NULL DEFAULT false,
role_version bigint NOT NULL CHECK (role_version > 0),
reserve_1 varchar(256), reserve_2 varchar(256), reserve_3 varchar(256),
create_at timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP,
update_at timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- 每个角色保留一行当前态(包括删除墓碑),精确查询和幂等 UPSERT 共用一个索引。
CREATE UNIQUE INDEX proxy_role_lookup ON proxy_roles(instance_id, role_name);
CREATE FUNCTION proxy_set_update_at() RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN
NEW.update_at := clock_timestamp();
RETURN NEW;
END;
$$;
CREATE TRIGGER proxy_endpoint_updated BEFORE UPDATE ON proxy_endpoints FOR EACH ROW EXECUTE FUNCTION proxy_set_update_at();
CREATE TRIGGER proxy_role_updated BEFORE UPDATE ON proxy_roles FOR EACH ROW EXECUTE FUNCTION proxy_set_update_at();
COMMIT;
2. SC 改造与接口
SC 为 Proxy 提供登录合查和单独取址,为管控和 Compute 分别提供路由发布与角色同步接口。
原版接口。 以下以本地 Neon fa504217c 为基线,原控制面路径均相对于配置的 base URL。
| 已有 API | 原用途与示例 | 本期用法 |
|---|---|---|
SC GET /ready、/status、/metrics |
curl -fsS "$SC_URL/ready" |
复用就绪、状态和指标接口 |
控制面 GET /get_endpoint_access_control |
查询参数含 endpointish=cmp1&role=app_user、session_id、application_name,返回 role_secret 和访问策略 |
登录改查 SC 的 access。原 IP/VPC 策略若需接入须另定义 |
控制面 GET /wake_compute |
参数含 endpointish、session_id、application_name,下例为成功响应 | 地址从 SC 读取,激活由 Agent 通知管控 |
Compute 扩展 PATCH ConsoleURL |
上报角色变更,下方示例删除 old_app。 | 保留 PRE_COMMIT 上报点,改发 SC 批接口 |
{
"address": "198.51.100.8:6432",
"server_name": "cmp1.example",
"aux": {
"endpoint_id": "cmp1",
"project_id": "p1",
"branch_id": "br1",
"compute_id": "c1",
"cold_start_info": "warm"
}
}
原 Compute 上报删除角色的请求体:
{
"roles": [
{
"op": "del",
"name": "old_app"
}
]
}
原控制面客户端携带 Bearer 凭据及 X-Request-ID。SC 路由注册 · Proxy 调用旧控制面 · wake 请求和响应处理 · Compute 原版 PATCH
一期新增 API(拟定)。 下列路径以 /v1/proxy 为前缀。SC 验证服务身份和实例访问范围,access 在同一快照内读两表,认证查询须能看到已确认的角色写入。
| 调用方 | 方法与路径 | 契约 |
|---|---|---|
| Proxy | GET /access?instance_id=…&node_key=…&mode=…&role=… |
返回 route 和 auth。缺失、已删除、过期或无 LOGIN 的角色拒绝登录。 |
| Proxy | GET /routes/{instance_id}/{node_key}?mode=… |
返回该入口的地址、有效端口、发布状态和版本。 |
| 管控 | PUT /routes/{instance_id}/{node_key} |
按版本提交完整节点快照,涵盖发布、切换、摘除和退役。 |
| Compute | PATCH /computes/{instance_id}/roles |
在一个 MetaDB 事务内应用一批角色变更。持久化后返回 200。 |
| Compute | GET /computes/{instance_id}/roles/{role_name} |
返回自身角色和版本。墓碑返回 is_deleted=true,从未登记返回 404。 |
路由发布。 下例发布主节点普通和池化端口。
PUT /v1/proxy/routes/cmp1/primary HTTP/1.1
Content-Type: application/json
{
"branch_id": "br1",
"target_ip": "198.51.100.8",
"compute_port": 5432,
"pooler_port": 6432,
"tls_server_name": "cmp1.example",
"route_state": 2,
"route_version": 8
}
路由发布成功(HTTP 200):
{
"instance_id": "cmp1",
"node_key": "primary",
"route_version": 8
}
角色同步。 set 给出完整角色状态,del 写墓碑。改名时将旧名 del 与新名 set 放入同一批次。
PATCH /v1/proxy/computes/cmp1/roles HTTP/1.1
Content-Type: application/json
{
"batch_id": "b-104",
"roles": [
{
"op": "set",
"role_name": "app_user",
"role_version": 4,
"can_login": true,
"scram_verifier": "<SCRAM verifier>",
"valid_until": null
}
]
}
角色同步成功或等价重试(HTTP 200):
{
"batch_id": "b-104",
"applied": true
}
首次登录合查。 示例以事务池为目标。服务通过 HTTPS 携带服务令牌和关联 ID,示例中的 verifier 为占位符。
GET /v1/proxy/access?instance_id=cmp1&node_key=primary&mode=pooled&role=app_user HTTP/1.1
{
"route": {
"instance_id": "cmp1",
"node_key": "primary",
"mode": "pooled",
"branch_id": "br1",
"target_ip": "198.51.100.8",
"port": 6432,
"tls_server_name": "cmp1.example",
"route_state": 2,
"route_version": 8
},
"auth": {
"role_name": "app_user",
"can_login": true,
"scram_verifier": "<SCRAM verifier>",
"role_version": 4,
"valid_until": null
}
}
刷新与对账。 GET /v1/proxy/routes/cmp1/primary?mode=direct 返回主节点路由和端口 5432。若路由版本 9 仅摘除池化端口,查询 mode=pooled 返回下例。角色对账示例为 GET /v1/proxy/computes/cmp1/roles/app_user,返回上述 auth 字段及 is_deleted。
{
"instance_id": "cmp1",
"node_key": "primary",
"mode": "pooled",
"branch_id": "br1",
"target_ip": "198.51.100.8",
"port": null,
"tls_server_name": "cmp1.example",
"route_state": 0,
"route_version": 9
}
| 异常 | 处理 |
|---|---|
| 400 非法参数,401/403 服务身份或范围错误 | 调用方修正请求或凭据。access 拒绝业务角色时,Proxy 对 PG 返回统一认证失败。 |
| 404 路由未登记 | 登录返回目标不可用。只有已登记且符合第 4 章条件的主路由可触发唤醒。 |
| 409 版本过旧或同版本内容冲突 | 批操作整体回滚,写方先核对权威状态。 |
| 503 SC 或 MetaDB 不可用 | 读请求在登录时限内退避。认证过期时拒绝新登录,PRE_COMMIT 上报最终失败则中止本地事务。 |
版本冲突响应(HTTP 409):
{
"code": "version_conflict",
"current_version": 8
}
3. 新连接、节点选择与缓存
客户端通过同一负载均衡器地址连接,Proxy 从 PG 启动参数 options 提取实例和节点,完成前端 SCRAM 后以业务角色登录目标后端。
instance=cmp1
conn='host=192.0.2.10 port=5432 dbname=postgres user=app_user sslmode=verify-full sslrootcert=/etc/pg/ca.pem'
psql "$conn options='endpoint=$instance'" # 当前主节点
psql "$conn options='endpoint=$instance-pooler'" # 当前主节点的事务池
psql "$conn options='endpoint=$instance-ro1'" # 指定只读节点 ro1
psql "$conn options='endpoint=$instance-ro2'" # 指定只读节点 ro2
IP 入口使用 sslmode=verify-full 时,证书须含负载均衡器 IP 的 SAN。沿用原版 endpoint=(旧别名 project=),客户端只发送一个路由标识。若 SNI 也提供 endpoint,两者须一致。后缀由适配层在规范化前解析,实例 ID 采用最多 128 位小写 ASCII 字母和数字。endpoint 解析与 SNI · 后端选项过滤
| endpoint 示例 | 目标 | 连接行为 |
|---|---|---|
cmp1 |
primary/direct | 经主 VIP 连 PostgreSQL,保留会话语义 |
cmp1-pooler |
primary/pooled | 经主 VIP 连 PgBouncer,事务结束后后端连接归池 |
cmp1-ro1 至 cmp1-ro4 |
指定成员/direct | 只读定向适配优先级较低;连接前验证成员资格,不可用时返回该成员错误 |
sequenceDiagram
participant C as PostgreSQL 客户端
participant P as Proxy(经负载均衡器接入)
participant S as SC
participant B as Compute A 主节点
C->>P: TLS 建连,发送 user、database、endpoint=cmp1
P->>P: 解析为实例 cmp1、主节点、普通连接;查本地缓存
opt 角色或路由缓存缺失、过期
P->>S: 角色需刷新时查 access;仅路由需刷新时查 routes
S-->>P: 返回所查元信息
end
P-->>C: SCRAM 质询
C->>P: 提交密码证明,Proxy 校验
P->>B: 经主 VIP,以客户端角色登录目标数据库
B-->>P: 后端登录成功
P-->>C: ReadyForQuery,可以执行 SQL
前后端都认证成功才返回 ReadyForQuery。数据库对象权限由 Compute 校验。池化请求只使用已发布的 pooler_port,不回落到普通端口。Lakebase 池化入口 · Neon Compute 配置
缓存与回源。 每个 Proxy 进程独立缓存路由 (instance_id, node_key, mode) 和角色 (instance_id, role_name)。两者均有效时直接认证;仅路由缺失或到期时查 routes;角色缺失或到期时查 access 合取两者。
- 两类缓存各设硬 TTL,命中不续期。角色还受 valid_until 限制。过期只影响下一次登录,旧会话继续转发。当 SC 不可达时禁止沿用过期认证。按允许的撤权生效窗口设角色 TTL,包含读取可见性延迟。
- 同副本对同键合并查询,限制 SC 总并发和排队长度。仅清理匹配代次的缓存,迟到响应不得覆盖新版本。部分原控制面错误约缓存 30 秒;一期按 SC 故障时长与恢复目标设置独立负缓存 TTL,区分 404 与 503。
- 原版 NodeInfoCache 的成功项默认按 4 分钟空闲期过期,新建连接读取可续期,老会话流量不会续期。原 Redis 通知用于失效角色和访问策略。节点取址仍依赖本地缓存和建连重试。一期按请求刷新。默认配置 · 订阅协议 · 缓存及 HTTP 调用
4. Proxy 节点部署、唤醒与切换
Agent 负责本机进程和唤醒通知,Proxy 根据 SC 发布的路由尝试真实后端登录,并在请求期限内结束重试。
部署。 Agent 挂载 TLS、SC 只读凭据和节点配置(pool_id、node_id、配置版本)。复用 Proxy CLI,拟增加 sc 后端及以下三个环境变量。VM 由 Agent 退避重启进程,容器部署须与平台约定唯一的重启责任方。
export PROXY_SC_URL=https://sc.example:8443
export PROXY_SC_TOKEN_FILE=/run/secrets/proxy-sc-token
export PROXY_WAKE_AGENT_SOCKET=/run/proxy-agent/wake.sock
exec /opt/neon/bin/proxy --auth-backend sc --proxy 0.0.0.0:5432 \
--http 127.0.0.1:7001 --tls-cert /run/tls/server.crt --tls-key /run/tls/server.key
节点先通过已有 GET /v1/status,再用第 3 章连接串直指待注册节点,执行 SELECT 1。两项通过后,管控将节点地址和 PG 端口注册到负载均衡后端组。以下为服务化接口示例,路径和字段由部署平台定义。Proxy 状态与指标
POST /load-balancer/pools/example-pool/backends HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-token>
{
"address": "192.0.2.11",
"port": 5432
}
激活。 原 Neon 在节点缓存未命中等情况下调用控制面 wake_compute 取址,调用前不查询 HA 或休眠状态。本方案由 SC 记录路由发布状态(0 暂不可用、2 可连接、5 退役),管控判断实例是否需要启动。原错误响应中的 retry_info.retry_delay_ms 是建议等待毫秒数,SC 无需提供唤醒 API。wake 请求和响应处理
| 已认证连接的观测结果 | Proxy 行为 |
|---|---|
| 主路由已登记但暂不可用 | 通过agent使用管控的通知机制,触发wake_compute |
| 主路由已发布,后端可重试故障 | 合并路由刷新后重试主 VIP,仍失败可通知 Agent。仅池化入口故障且普通入口可用时,按 PgBouncer 故障处理。 |
| 指定只读成员不可用 | 只刷新该成员并校验其只读资格。实例退役、认证拒绝、SC 无法提供必要元信息时结束登录。 |
{
"type": "wake_compute",
"request_id": "wake-104",
"instance_id": "cmp1",
"observed_route_version": 8,
"expires_at": "2026-11-19T09:01:00Z"
}
Agent 持久入队后可返回 202,向管控单向投递。重投沿用 request_id,管控按实例合并并检查 expires_at。Proxy 只重查 SC 并连接后端,同一副本的同实例共享通知,各登录独立计时。联调起点为剩余登录预算与 60 秒中的较短者,重试间隔从 0.5 秒退避至 5 秒并加抖动。VIP 未变也可重试。成功以完成指定入口的后端登录为准,超时返回暂不可用并记录一次最终结果。全部等待者退出后停止刷新。
HA 与只读节点。 主 VIP 漂移后,新连接沿用同一客户端入口。已断会话由应用或连接池重连,未确认的提交结果由应用核实。主节点提升时先摘除旧池化端口,待新 PgBouncer 指向新主并通过事务测试后再发布。
| 无只读 VIP 的场景 | 新连接如何选节点 | 成员升主时 |
|---|---|---|
| 客户端直连 | 管控提供成员列表,支持多主机参数的 libpq 按下例筛选物理备库 | 新读连接跳过新主,管控或应用连接池回收旧读会话 |
| 经 Proxy 定向 | endpoint=cmp1-ro1 只选 ro1,组级只读入口见第 8 章 |
管控撤下 ro1 路由并处理旧读会话,替代成员就绪后显式注册新版本 |
psql "host=pg-a.example,pg-b.example,pg-c.example port=5432 dbname=app user=reader target_session_attrs=standby load_balance_hosts=random connect_timeout=3 sslmode=verify-full"
直连示例要求证书覆盖各成员主机名。Lakebase 的组级 -ro 与排障用成员直连串用途不同,成员变动或提升时直连串可能变化。其 HA 成员不支持空闲自动 scale to zero,整组可手动暂停。libpq 连接参数 · Lakebase HA
4.1 SQL over HTTP 的入口与部署
应用可向共享 Proxy 发送 POST /sql 执行参数化 SQL,Proxy 校验业务角色、通过 PostgreSQL 协议访问 Compute,再将结果编码为 JSON。
| 调用方 | 原版监听参数与接口 | 服务化部署建议 |
|---|---|---|
| psql、普通 PG 驱动 | --proxy,PG/TLS 长连接 |
沿用负载均衡器 TCP 5432 → Proxy 节点 5432 |
| HTTP 客户端、Neon serverless driver | --wss,POST /sql 执行查询,OPTIONS /sql 处理浏览器预检;同一监听也可接受 WebSocket 升级 |
同一负载均衡器增设 TCP 443 → 两个 Proxy 节点的 8443,TLS 透传到 Proxy |
| 本机 Agent、采集器 | --http,GET /v1/status、GET /metrics |
绑定 127.0.0.1:7001,仅在节点内访问 |
进程部署。 本地源码中,普通控制面后端模式的同一个 proxy 进程可以同时运行 PG 和 serverless 监听,--wss 需显式指定。建议沿用两个 Proxy 节点和各自的 Agent,在本章启动命令追加 --wss 0.0.0.0:8443,挂载含业务 HTTPS 入口名称或 IP SAN 的证书。将两个节点的 8443 注册到 443 监听对应的后端组。若负载均衡器发送 PROXY protocol v2,须同步配置 Proxy 并检查 PG 和 HTTP 两个监听的兼容性。监听与任务启动 · 业务 HTTP 路由 · 管理接口
密码模式。 HTTPS URL 决定请求发往哪个 Proxy,Neon-Connection-String 请求头决定访问哪个数据库。原版从头内 PG URI 的主机名首段提取 endpoint,从 URI 取角色、密码和数据库。Proxy 对每次请求校验密码与角色 verifier,随后取得或建立该业务角色的后端 PG 连接。单条查询和同一请求内的事务批次均可走 HTTP;跨请求交互式事务使用 PG 或 WebSocket。连接信息解析 · 密码校验与后端建连 · Neon 驱动使用说明
适配 IP 入口。 可直接请求 https://192.0.2.10/sql,头内仍使用 cmp1.db.example 这类逻辑主机名。Proxy 从中提取 cmp1,经 SC 取真实后端地址,该逻辑名称无需为此请求解析到 Compute。HTTP 解析器没有用 URI 的 options=endpoint=cmp1 覆盖主机名前缀的逻辑;若要求头内也使用裸 IP,需新增解析与冲突校验。建议先沿用原版头格式,并复用第 3 章的 endpoint 后缀规则、角色校验和第 4 章的限时唤醒。仅支持密码接入时可复用现有 SC 表及 API。
以下示例使用负载均衡器测试地址和主节点普通入口,替换地址、CA 与测试角色即可联调。请求头中的密码须按 URI 规则编码,代理和负载均衡器日志应脱敏。
curl --fail-with-body --cacert /etc/pg/ca.pem 'https://192.0.2.10/sql' \
-H 'Content-Type: application/sql' \
-H 'Neon-Connection-String: postgresql://app_user:XXXXXXXXXX@cmp1.db.example/postgres' \
--data-binary @- <<'JSON'
{
"query": "SELECT $1::int AS answer",
"params": [
42
]
}
JSON
验收时检查 HTTP 200,响应的 rows[0].answer 为 42;再分别用错误密码、另一实例同名角色及休眠实例验证拒绝、隔离和唤醒。原版 HTTP 后端连接复用默认由请求头 Neon-Pool-Opt-In: true 开启,连接池位于 Proxy 进程内,Compute 侧 PgBouncer 可独立部署。若开启 HTTP 池,须按实例、目标成员、模式、角色和数据库隔离复用,并验证路由切换后旧连接能被淘汰。仓库 HTTP 用例 · HTTP 池与认证顺序
JWT 部署差异。 原版 --is-auth-broker=true 要求配置 --wss,该进程关闭常规 PG 监听。它验证 Authorization: Bearer JWT,按 endpoint 取得 JWKS 规则,再把请求转给 Compute 侧的 local_proxy 访问本地 PostgreSQL。若要同时保留现有 PG/密码服务,JWT broker 应独立运行,另行对接 JWKS、角色授权规则和 Compute 侧组件。普通 HTTP 密码部署只需共享 Proxy 到 Compute 的 PG 链路。broker 转发 · JWKS 规则
5. Compute 角色同步与管控对接
角色变更统一由 Compute 写 SC,管控负责路由发布、网页配置任务和实例激活。
Compute 改造。 SQL 的 CREATE/ALTER/DROP ROLE 与网页的 POST /configure 共用 PRE_COMMIT hook。原 configure 会话设置 neon.forward_ddl=false,需为受管理角色启用捕获并排除内部账号。例:ALTER ROLE app_user NOLOGIN 产生第 2 章角色 PATCH,set 中 can_login=false。覆盖改密、清空密码、有效期、改名和删除,发送目录内实际 verifier。普通 PostgreSQL 需等价 hook。配置会话禁用回传 · DDL 回调
角色 PATCH 整批取得 200 后 PG 才继续提交,最终失败则整笔事务回滚。新建或克隆实例先全量同步角色再接收增量,休眠期间 SC 保留角色目录。下面复用原 POST /configure 对完整 spec 中已有的角色改密。原版请求结构
jq --arg verifier "$SCRAM_VERIFIER" \
'(.spec.cluster.roles[] | select(.name == "app_user").encrypted_password) = $verifier' \
configure-request.json | curl -fsS -X POST "$COMPUTE_URL/configure" \
-H "Authorization: Bearer $COMPUTE_TOKEN" -H 'Content-Type: application/json' --data-binary @-
5.1 管控对接清单
管控串起新实例注册、配置任务和唤醒通知,按以下完成条件发布入口。
| 任务 | 接口及完成条件 |
|---|---|
| 创建和切换 | 注册 Proxy 节点到负载均衡后端组,分配实例 ID,用路由 PUT 发布主 VIP 和各成员。验证普通入口及池化端口后分别开放。 |
| 网页改密 | 按实例协调完整 spec 的下发,保存 task_id,同一角色的任务有序重试。后一次改密生效后,前一次迟到任务在管控侧结束。 |
| 休眠期间的 configure | 持久化待执行任务。唤醒后补发 configure 并确认角色同步,再发布就绪路由。尚未创建的账号由管控或已有授权身份触发唤醒。 |
| Agent 单向上报 | 管控判断运行状态、HA 和暂停策略,重复通知只执行一次激活。通道协议、任务持久化和重试能力待联调。 |
6. 一期新增功能的监控与告警
本期按一次新登录、一次激活通知或一批角色变更计量,区分用户可见的最终失败和内部重试。
| 新增功能 | 指标(拟定) | 告警条件与定位 |
|---|---|---|
| SC 接口与缓存回源 | 按 access/routes 统计错误率、P99,按缓存类型统计回源数、合并等待数及超预算拒绝数 | 多副本持续出现 5xx 或排队拒绝且新登录失败时,检查 SC 接口及 MetaDB 读取延迟。单独统计业务认证拒绝。 |
| 后端选路 | proxy_backend_attempts_total{stage,result,mode} 区分 TCP、TLS、后端认证及普通/池化入口 |
新连接连续在同一阶段失败时告警。仅 pooled 失败时检查池化端口发布和 PgBouncer。 |
| Agent 唤醒通知 | agent_wake_reports_total{result}、队列深度、最老待发时长 |
连续投递失败或排队接近事件有效期时通知 Agent 负责人。request_id 可关联管控接收日志。 |
| Proxy 激活等待 | proxy_wake_logins_total{result,last_stage,mode}、proxy_wake_wait_seconds、proxy_wake_waiters |
每条等待登录只记录一个最终结果。按池统计最终超时数、占比和最后失败阶段。 |
| Compute 角色同步 | PRE_COMMIT 上报失败数、PATCH 延迟、409 冲突数、对账差异数 | 持续阻塞角色 DDL 或对账差异未收敛时,关联 Compute 提交结果和 SC 批次日志。 |
复用已有 /metrics。抓取时补充 pool_id;实例 ID 和 request_id 只进受控日志,日志排除密码、verifier 和完整连接串。
curl -fsS http://127.0.0.1:7001/metrics
curl -fsS "$SC_URL/metrics"
联调告警示例。 同一池 5 分钟内至少 5 条登录最终超时,且占已结束唤醒等待的 10% 时告警,分母排除客户端提前断开。低流量时,同一实例连续 3 次超时用日志规则补充。连续两个窗口恢复且有成功样本时解除,生产阈值按基线校准。
(
sum by (pool_id) (increase(proxy_wake_logins_total{result="timeout"}[5m])) >= 5
)
and on (pool_id)
(
sum by (pool_id) (increase(proxy_wake_logins_total{result="timeout"}[5m]))
/ sum by (pool_id) (increase(proxy_wake_logins_total{result!="client_disconnected"}[5m])) >= 0.10
)
7. QA 与故障验收
用下列故障验证角色一致性、认证生效窗口和新连接的恢复边界。
| 问题或注入故障 | 预期行为与验收点 |
|---|---|
| SC 已写入,PATCH 响应丢失怎么办? | Compute 重投同一 batch_id、角色版本和内容。SC 对同版本同内容返回 200,冲突返回 409,整批原子处理。用户重新执行 SQL 属于新事务。 |
| SC 已返回 200,PG 随后回滚或宕机怎么办? | 存在 SC 短暂公开未提交认证信息的窗口。以当前可写 Compute 已提交的角色目录为准对账,用新版本修复 SC。HA 切换后拒绝旧主写入。 |
| 网页改密超时,或第一次重试迟于第二次怎么办? | 管控按任务顺序核对已提交状态。重放相同 spec 可能跳过 ALTER ROLE,须核对 SC 后再结束任务。验收 PG 与 SC 均保留最后一次生效密码。角色差异检查 |
| 两个 Proxy 缓存仍热,用户已改密或撤权? | 测量 PG 提交到两副本实际采用新版本的时长。硬 TTL 不因命中而延长,过期且 SC 不可用时拒绝新认证。已有会话独立处理。 |
| MetaDB 或 SC 中断,随后大量客户端重连? | 冷缓存和过期项影响新连接,角色上报失败影响 DDL。验证 MetaDB 主备切换、已确认写入可见、备份恢复。同一键单轮回源每副本至多一组;无新登录时缓存到期不产生回源、探活或唤醒。 |
| Agent 停止、通知丢失或重复? | Proxy 在最终时限内结束,每次登录只计一个结果,告警可触发并解除。管控对重复事件只实际激活一次,已运行实例无需重启。 |
| VIP 倒换或 ro1 升主? | 应用新连接恢复到新主,旧事务结果另行核实。指定 ro1 的新连接不得误入新主,ro2 仍可连接;原 ro1 读会话按 HA 流程回收。 |
| PgBouncer 单独停止? | 普通入口保持可用,池化入口独立返回故障。验证恢复发布、池化连接改密生效,以及空闲池对休眠判定的影响。 |
8. 其他计划功能点
以下条目列出后续可扩展的能力及设计时需要明确的问题。
| 功能点 | 概要 | 待细化 |
|---|---|---|
| 缓存批量版本检查 | 缩短各 Proxy 副本发现路由或角色变更的时间。 | 检查哪些缓存项、允许多长的发现延迟、SC 可承受多少额外负载? |
| HA 组级只读入口 | 应用通过统一入口连接可用的只读成员。 | 哪些成员可接流量、新连接如何分配、成员升主后如何处理已有读会话? |
| 只读连接池化 | 为只读访问提供事务池入口。 | 按成员还是按 HA 组提供入口、如何分配连接额度、成员退出时如何排空连接池? |
| 临时 Compute(可选) | 按需创建和释放运行实例。 | 哪些场景需要临时实例、何时可以接入、实例替换后如何隔离旧路由和旧写方? |
blog comments powered by Disqus