feat: 卡网关按运营商账户限流并记录停复机调用
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s

- 新增网关限流:按本系统运营商账户(卡 carrier_id)→ 限流组 → 操作限制每秒请求数,每次 HTTP 尝试计量,默认限流、仅后台人工点击/通道阈值/自动续费/手动刷新豁免;支持只统计与拦截两种模式,默认只统计
- Asynq 遇限流不计失败、固定短延迟重试;轮询任务与停复机业务重试遇限流短延迟重排
- 停机、复机不再使用网关内部重试,只发一次请求
- 网关返回结构化错误;新增上游错误分类规则表与测试接口
- 新增按月分区的停复机记录表:系统自动停复机只写记录,不再写统一审计与集成日志;普通轮询查询不再写集成日志
- 新增限流组、错误分类、停复机记录、按账户调用统计与枚举后台接口
- 迁移 000243~000246;同步 OpenSpec 提案(含后续 6 个 change)与技术方案、工程约束
This commit is contained in:
邹进
2026-10-24 15:06:41 +09:00
parent 9e45097aa2
commit 42e881576d
106 changed files with 7173 additions and 48 deletions

View File

@@ -0,0 +1,6 @@
-- 回滚运营商账户网关限流组:删除 tb_carrier_rate_limit_group,与 up 严格倒序成对。
-- 删除后限流器对全部账户回落默认 QPS(只统计模式下无行为影响)。
DROP INDEX IF EXISTS idx_carrier_rate_limit_group_carrier;
DROP INDEX IF EXISTS uk_carrier_rate_limit_group_code;
DROP TABLE IF EXISTS tb_carrier_rate_limit_group;

View File

@@ -0,0 +1,44 @@
-- 运营商账户网关限流组(add-carrier-gateway-rate-limit)。
-- 背景:上游按运营商账户(tb_carrier 一行即一个上游账户)限频,现有轮询并发计数不以账户为单位且数值无依据。
-- 本表按账户配置卡的 5 个网关操作(查流量 / 查状态 / 查实名 / 停机 / 复机)的每秒请求上限。
--
-- 设计选择:
-- 1. carrier_id 为空表示全局组(可选,用于聚合网关总限流);同一账户下同一操作只能属于一个组,由应用层保存时校验。
-- 2. operations / high_priority_operations 为 JSON 字符串数组,取值见 pkg/constants 网关操作常量。
-- 3. 停用(status=0)的组不参与判断,组内操作回落为默认 QPS,不存在不限流的自动调用。
-- 4. 不使用数据库外键(ENG-MODEL-001);软删除,后台维护。
CREATE TABLE tb_carrier_rate_limit_group (
id BIGSERIAL PRIMARY KEY,
carrier_id BIGINT,
group_code VARCHAR(50) NOT NULL,
group_name VARCHAR(100) NOT NULL,
max_qps INTEGER NOT NULL,
operations JSONB NOT NULL DEFAULT '[]'::jsonb,
high_priority_operations JSONB NOT NULL DEFAULT '[]'::jsonb,
reserved_qps INTEGER NOT NULL DEFAULT 0,
status SMALLINT NOT NULL DEFAULT 1,
creator BIGINT NOT NULL DEFAULT 0,
updater BIGINT NOT NULL DEFAULT 0,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
deleted_at TIMESTAMPTZ,
CONSTRAINT ck_carrier_rate_limit_group_qps CHECK (max_qps > 0 AND reserved_qps >= 0 AND reserved_qps < max_qps),
CONSTRAINT ck_carrier_rate_limit_group_status CHECK (status IN (0, 1))
);
CREATE UNIQUE INDEX uk_carrier_rate_limit_group_code
ON tb_carrier_rate_limit_group (COALESCE(carrier_id, 0), group_code) WHERE deleted_at IS NULL;
CREATE INDEX idx_carrier_rate_limit_group_carrier ON tb_carrier_rate_limit_group (carrier_id) WHERE deleted_at IS NULL;
COMMENT ON TABLE tb_carrier_rate_limit_group IS '运营商账户网关限流组:按账户配置卡网关操作的每秒请求上限';
COMMENT ON COLUMN tb_carrier_rate_limit_group.carrier_id IS '运营商账户ID(tb_carrier.id),为空表示全局组';
COMMENT ON COLUMN tb_carrier_rate_limit_group.group_code IS '组标识,同一账户内唯一';
COMMENT ON COLUMN tb_carrier_rate_limit_group.group_name IS '组名称';
COMMENT ON COLUMN tb_carrier_rate_limit_group.max_qps IS '该组每秒请求上限';
COMMENT ON COLUMN tb_carrier_rate_limit_group.operations IS '组内操作:query_flow/query_status/query_realname/stop/start';
COMMENT ON COLUMN tb_carrier_rate_limit_group.high_priority_operations IS '组内高优先级操作,可用满 max_qps';
COMMENT ON COLUMN tb_carrier_rate_limit_group.reserved_qps IS '预留给高优先级操作的额度,普通操作最多使用 max_qps - reserved_qps';
COMMENT ON COLUMN tb_carrier_rate_limit_group.status IS '状态 0-停用 1-启用;停用后组内操作回落为默认 QPS';
COMMENT ON COLUMN tb_carrier_rate_limit_group.creator IS '创建人ID';
COMMENT ON COLUMN tb_carrier_rate_limit_group.updater IS '更新人ID';

View File

@@ -0,0 +1,5 @@
-- 回滚上游错误分类规则:删除 tb_gateway_error_classification(含初始规则),与 up 严格倒序成对。
-- 删除后分类器回落为"未命中规则即业务错误",后台新增的规则一并丢失。
DROP INDEX IF EXISTS idx_gateway_error_classification_active;
DROP TABLE IF EXISTS tb_gateway_error_classification;

View File

@@ -0,0 +1,61 @@
-- 上游错误分类规则(add-carrier-gateway-rate-limit)。
-- 背景:网关对各类上游错误统一返回 code=400,失败原因只拼在错误字符串里,无法区分频率限制、终态、临时故障与业务错误。
-- 本表把上游返回信息按关键字归入类别,供停复机与轮询的失败处理、告警与统计使用;后台可逐条增补。
--
-- 设计选择:
-- 1. match_type:contains(包含)/ prefix(前缀)/ regex(正则);operations 为空数组表示适用全部操作。
-- 2. priority 越小越先匹配;未命中任何规则的上游业务错误归为业务错误(business)。
-- 3. maybe_accepted 标记"上游可能已受理"(如"调用成功-5分钟内最多重复调用3次"),停复机下次执行前先查卡状态确认。
-- 4. 只有明确表示卡已处于目标状态的返回才可归入 already_target;老系统结束停机任务的关键字("已存在""密码错误"等)
-- 不代表停机成功,初始数据不据此归类为 already_target。
-- 5. 初始规则来自《轮询按运营商账户限流技术方案》第三部分 6.2 节(生产 2026-10-22 实测返回)。
CREATE TABLE tb_gateway_error_classification (
id BIGSERIAL PRIMARY KEY,
keyword VARCHAR(200) NOT NULL,
match_type VARCHAR(20) NOT NULL DEFAULT 'contains',
category VARCHAR(30) NOT NULL,
operations JSONB NOT NULL DEFAULT '[]'::jsonb,
priority INTEGER NOT NULL DEFAULT 100,
maybe_accepted BOOLEAN NOT NULL DEFAULT FALSE,
status SMALLINT NOT NULL DEFAULT 1,
remark VARCHAR(500) NOT NULL DEFAULT '',
creator BIGINT NOT NULL DEFAULT 0,
updater BIGINT NOT NULL DEFAULT 0,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
deleted_at TIMESTAMPTZ,
CONSTRAINT ck_gateway_error_classification_match CHECK (match_type IN ('contains', 'prefix', 'regex')),
CONSTRAINT ck_gateway_error_classification_category CHECK (category IN ('rate_limited_upstream', 'terminal', 'already_target', 'transient', 'business', 'account_config')),
CONSTRAINT ck_gateway_error_classification_status CHECK (status IN (0, 1))
);
CREATE INDEX idx_gateway_error_classification_active ON tb_gateway_error_classification (status, priority) WHERE deleted_at IS NULL;
COMMENT ON TABLE tb_gateway_error_classification IS '上游错误分类规则:按关键字把网关返回信息归入失败类别';
COMMENT ON COLUMN tb_gateway_error_classification.keyword IS '匹配关键字或正则';
COMMENT ON COLUMN tb_gateway_error_classification.match_type IS '匹配方式 contains-包含 prefix-前缀 regex-正则';
COMMENT ON COLUMN tb_gateway_error_classification.category IS '类别 rate_limited_upstream-上游频率限制 terminal-终态不可操作 already_target-已是目标状态 transient-临时故障 business-业务错误 account_config-账户配置错误';
COMMENT ON COLUMN tb_gateway_error_classification.operations IS '适用操作,空数组表示全部:query_flow/query_status/query_realname/stop/start';
COMMENT ON COLUMN tb_gateway_error_classification.priority IS '匹配优先级,越小越先匹配';
COMMENT ON COLUMN tb_gateway_error_classification.maybe_accepted IS '上游可能已受理(如返回含调用成功、操作进行中、请求被合并)';
COMMENT ON COLUMN tb_gateway_error_classification.status IS '状态 0-停用 1-启用';
COMMENT ON COLUMN tb_gateway_error_classification.remark IS '备注';
INSERT INTO tb_gateway_error_classification (keyword, match_type, category, priority, maybe_accepted, remark) VALUES
('仅允许一次', 'contains', 'rate_limited_upstream', 10, TRUE, '3分钟内同一张卡相同操作仅允许一次'),
('最多重复调用', 'contains', 'rate_limited_upstream', 10, TRUE, '调用成功-5分钟内最多重复调用3次'),
('只允许调用', 'contains', 'rate_limited_upstream', 10, TRUE, '调用成功-卡状态变更每十分钟只允许调用1次'),
('请求被合并', 'contains', 'rate_limited_upstream', 10, TRUE, '请求被合并,以最新一次为准'),
('操作进行中', 'contains', 'rate_limited_upstream', 10, TRUE, '操作进行中'),
('超频访问', 'contains', 'rate_limited_upstream', 10, FALSE, '超频访问'),
('已销户', 'contains', 'terminal', 20, FALSE, '当前用户已销户,无法操作'),
('仅支持风险复机', 'contains', 'terminal', 20, FALSE, '当前卡为风险停机状态,仅支持风险复机'),
('号码封存', 'contains', 'terminal', 20, FALSE, '用户状态是物联网号码封存,禁止办理物联网停机'),
('密码错误', 'contains', 'account_config', 30, FALSE, '账户凭证问题,影响该账户全部卡'),
('参数缺失', 'contains', 'account_config', 30, FALSE, '账户接入参数问题'),
('token 为空', 'contains', 'transient', 40, FALSE, '湖北省网获取到的 token 为空'),
('token为空', 'contains', 'transient', 40, FALSE, '获取到的 token 为空'),
('当前用户不允许办理', 'contains', 'business', 50, FALSE, '不视为已是目标状态'),
('防范实名', 'contains', 'business', 50, FALSE, '不视为已是目标状态'),
('请求失败', 'contains', 'transient', 90, FALSE, '上游通用失败');

View File

@@ -0,0 +1,7 @@
-- 回滚停复机调用记录:删除分区表 tb_card_stop_resume_record(含全部分区),与 up 严格倒序成对。
-- 不可逆说明(ENG-MIG-001 例外条件):记录删除后无法重建;只在代码已退回写统一审计、且无需追溯停复机调用时执行。
DROP INDEX IF EXISTS idx_card_stop_resume_record_result;
DROP INDEX IF EXISTS idx_card_stop_resume_record_carrier;
DROP INDEX IF EXISTS idx_card_stop_resume_record_card;
DROP TABLE IF EXISTS tb_card_stop_resume_record CASCADE;

View File

@@ -0,0 +1,71 @@
-- 停复机调用记录(add-carrier-gateway-rate-limit)。
-- 背景:系统自动停复机的上游调用此前写统一审计 tb_audit_event 与集成日志 tb_integration_log(生产约 1,500 万行、积压严重),
-- 且错误原因只在审计 error_summary 中可见。改为每次实际调用上游停机或复机写一条本表记录。
--
-- 设计选择:
-- 1. 按 created_at 月分区(声明式 RANGE 分区),主键 (id, created_at);建 DEFAULT 分区兜底,任何月份插入都不因分区缺失失败。
-- 2. 本迁移创建当前月起 4 个月的分区;之后由 Worker 定时任务提前创建未来分区,并按保留期整区删除过期分区。
-- 3. 记录写入与卡状态回写不在同一事务,写入失败只记日志与计数。
-- 4. provider_message 为脱敏截断后的上游信息;不使用数据库外键(ENG-MODEL-001)。
CREATE TABLE tb_card_stop_resume_record (
id BIGSERIAL,
card_id BIGINT NOT NULL,
iccid VARCHAR(30) NOT NULL DEFAULT '',
carrier_id BIGINT NOT NULL DEFAULT 0,
action VARCHAR(10) NOT NULL,
source VARCHAR(50) NOT NULL DEFAULT '',
scene VARCHAR(50) NOT NULL DEFAULT '',
reason VARCHAR(50) NOT NULL DEFAULT '',
command_id VARCHAR(64) NOT NULL DEFAULT '',
attempt INTEGER NOT NULL DEFAULT 1,
result VARCHAR(20) NOT NULL,
error_category VARCHAR(30) NOT NULL DEFAULT '',
provider_code VARCHAR(30) NOT NULL DEFAULT '',
provider_message VARCHAR(500) NOT NULL DEFAULT '',
duration_ms INTEGER NOT NULL DEFAULT 0,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
PRIMARY KEY (id, created_at),
CONSTRAINT ck_card_stop_resume_record_action CHECK (action IN ('stop', 'start')),
CONSTRAINT ck_card_stop_resume_record_result CHECK (result IN ('success', 'failed', 'unknown', 'already_target', 'skipped'))
) PARTITION BY RANGE (created_at);
CREATE TABLE tb_card_stop_resume_record_default PARTITION OF tb_card_stop_resume_record DEFAULT;
DO $$
DECLARE
month_start DATE := date_trunc('month', NOW() AT TIME ZONE 'Asia/Shanghai')::date;
i INTEGER;
from_date DATE;
to_date DATE;
BEGIN
FOR i IN 0..3 LOOP
from_date := (month_start + make_interval(months => i))::date;
to_date := (month_start + make_interval(months => i + 1))::date;
EXECUTE format(
'CREATE TABLE IF NOT EXISTS %I PARTITION OF tb_card_stop_resume_record FOR VALUES FROM (%L) TO (%L)',
'tb_card_stop_resume_record_' || to_char(from_date, 'YYYYMM'),
(from_date::timestamp AT TIME ZONE 'Asia/Shanghai'),
(to_date::timestamp AT TIME ZONE 'Asia/Shanghai'));
END LOOP;
END $$;
CREATE INDEX idx_card_stop_resume_record_card ON tb_card_stop_resume_record (card_id, created_at);
CREATE INDEX idx_card_stop_resume_record_carrier ON tb_card_stop_resume_record (carrier_id, created_at);
CREATE INDEX idx_card_stop_resume_record_result ON tb_card_stop_resume_record (result, created_at);
COMMENT ON TABLE tb_card_stop_resume_record IS '停复机调用记录:每次实际调用上游停机或复机一条,按月分区';
COMMENT ON COLUMN tb_card_stop_resume_record.card_id IS 'IoT卡ID';
COMMENT ON COLUMN tb_card_stop_resume_record.iccid IS 'ICCID';
COMMENT ON COLUMN tb_card_stop_resume_record.carrier_id IS '卡所属运营商账户ID';
COMMENT ON COLUMN tb_card_stop_resume_record.action IS '动作 stop-停机 start-复机';
COMMENT ON COLUMN tb_card_stop_resume_record.source IS '来源:轮询、业务事件、退款、激活、重置、订单、后台人工点击、通道阈值等';
COMMENT ON COLUMN tb_card_stop_resume_record.scene IS '场景';
COMMENT ON COLUMN tb_card_stop_resume_record.reason IS '停机原因';
COMMENT ON COLUMN tb_card_stop_resume_record.command_id IS '停复机指令标识,同一指令的多次尝试归为一组';
COMMENT ON COLUMN tb_card_stop_resume_record.attempt IS '尝试序号';
COMMENT ON COLUMN tb_card_stop_resume_record.result IS '结果 success-成功 failed-失败 unknown-结果未知 already_target-已是目标状态 skipped-跳过';
COMMENT ON COLUMN tb_card_stop_resume_record.error_category IS '错误类别';
COMMENT ON COLUMN tb_card_stop_resume_record.provider_code IS '上游返回码';
COMMENT ON COLUMN tb_card_stop_resume_record.provider_message IS '上游返回信息(脱敏截断)';
COMMENT ON COLUMN tb_card_stop_resume_record.duration_ms IS '耗时(毫秒)';

View File

@@ -0,0 +1,11 @@
-- 回滚网关限流相关的受控系统配置:删除 up 插入的 6 个 Key,与 up 成对。
-- 删除后代码按注册表默认值运行(限流模式回到 observe)。
DELETE FROM tb_system_config WHERE config_key IN (
'polling.rate_limit_mode',
'polling.gateway_default_qps',
'polling.rate_limited_retry_delay_seconds',
'polling.rate_limit_defer_alert_seconds',
'polling.stop_resume_record_retention_months',
'polling.stop_resume_record_premake_months'
);

View File

@@ -0,0 +1,18 @@
-- 网关限流相关的受控系统配置(add-carrier-gateway-rate-limit),module = polling。
-- 配置的权威定义(类型、取值范围、默认值)在代码注册表中;本迁移只落库初始值,便于后台列表展示与审计。
-- 已存在同名 Key 时不覆盖(ON CONFLICT DO NOTHING),避免覆盖运营已修改的值。
--
-- 1. polling.rate_limit_mode:observe 只统计不拦截(默认)/ enforce 拦截;全局生效,不按账户覆盖。
-- 2. polling.gateway_default_qps:未被任何启用限流组覆盖的操作使用的默认每秒请求上限(暂定,上线前由维护者按 observe 数据确认)。
-- 3. polling.rate_limited_retry_delay_seconds:Asynq 任务遇限流后的固定短延迟。
-- 4. polling.rate_limit_defer_alert_seconds:同一任务因限流累计推迟超过该时长时写告警。
-- 5. polling.stop_resume_record_retention_months / polling.stop_resume_record_premake_months:停复机记录保留月数与提前建分区月数。
INSERT INTO tb_system_config (config_key, config_value, value_type, module, description, is_readonly, is_sensitive, creator, updater, created_at, updated_at) VALUES
('polling.rate_limit_mode', 'observe', 'string', 'polling', '网关限流模式:observe 只统计不拦截,enforce 拦截', FALSE, FALSE, 0, 0, NOW(), NOW()),
('polling.gateway_default_qps', '10', 'int', 'polling', '未被启用限流组覆盖的卡网关操作的默认每秒请求上限', FALSE, FALSE, 0, 0, NOW(), NOW()),
('polling.rate_limited_retry_delay_seconds', '5', 'int', 'polling', 'Asynq 任务遇限流后的固定重试延迟(秒)', FALSE, FALSE, 0, 0, NOW(), NOW()),
('polling.rate_limit_defer_alert_seconds', '600', 'int', 'polling', '同一任务因限流累计推迟超过该时长(秒)时写告警', FALSE, FALSE, 0, 0, NOW(), NOW()),
('polling.stop_resume_record_retention_months', '6', 'int', 'polling', '停复机记录保留月数,到期整区删除', FALSE, FALSE, 0, 0, NOW(), NOW()),
('polling.stop_resume_record_premake_months', '3', 'int', 'polling', '停复机记录提前创建未来分区的月数', FALSE, FALSE, 0, 0, NOW(), NOW())
ON CONFLICT (config_key) DO NOTHING;