feat: 卡网关按运营商账户限流并记录停复机调用
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s
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:
6
migrations/000243_add_carrier_rate_limit_group.down.sql
Normal file
6
migrations/000243_add_carrier_rate_limit_group.down.sql
Normal 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;
|
||||
44
migrations/000243_add_carrier_rate_limit_group.up.sql
Normal file
44
migrations/000243_add_carrier_rate_limit_group.up.sql
Normal 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';
|
||||
@@ -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;
|
||||
61
migrations/000244_add_gateway_error_classification.up.sql
Normal file
61
migrations/000244_add_gateway_error_classification.up.sql
Normal 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, '上游通用失败');
|
||||
7
migrations/000245_add_card_stop_resume_record.down.sql
Normal file
7
migrations/000245_add_card_stop_resume_record.down.sql
Normal 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;
|
||||
71
migrations/000245_add_card_stop_resume_record.up.sql
Normal file
71
migrations/000245_add_card_stop_resume_record.up.sql
Normal 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 '耗时(毫秒)';
|
||||
@@ -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'
|
||||
);
|
||||
@@ -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;
|
||||
Reference in New Issue
Block a user