零依赖 PostgreSQL 任务队列引擎

postgres-job-queue

PostgreSQL 原生作业队列，零依赖实现优先级调度与进度跟踪，适合已有 PG 基础设施、追求架构简化的技术团队。

v1.0.0版本 A安全等级 自动化 / Agent / 发布 / 自媒体支持工具

01 场景说明

什么时候用这个 Skill？

PostgreSQL Job Queue 综合评估

核心用法

该技能提供了一套完整的基于 PostgreSQL 的生产级作业队列实现方案。核心机制利用 PostgreSQL 9.5+ 引入的 SKIP LOCKED 特性，通过 claim_job_batch 函数实现并发安全的作业批量认领，避免传统 "SELECT then UPDATE" 模式导致的竞态条件。方案支持优先级调度（默认 100，可配置 30-150）、作业状态机管理（pending/claimed/running/completed/failed）、自动重试机制（默认 3 次）以及进度跟踪（progress 字段 + current_stage）。开发者可通过 Go 的 pgx 驱动集成，利用部分索引（partial index）优化查询性能，确保在高并发场景下的 claiming 效率。

显著优点

最突出的优势是架构简化——无需引入 Redis、RabbitMQ 等外部依赖，直接复用现有 PostgreSQL 基础设施，降低运维复杂度和系统脆弱性。数据持久化由数据库事务保证，作业状态在服务端重启后依然可靠，解决了内存队列的数据丢失问题。进度跟踪机制（progress/events_count）为长时任务提供了可视性，便于监控和调试。此外，方案充分利用 SQL 的表达能力，通过 JSONB 字段存储灵活的任务数据，配合 GIN 索引可高效查询特定类型的作业。

潜在缺点与局限性

吞吐量存在明显瓶颈，文档明确指出超过 1000 jobs/s 时应考虑 Redis，超过 10000 jobs/s 必须引入 Redis 层。高频的 claiming 操作会增加数据库负载，特别是在高并发 worker 场景下，FOR UPDATE SKIP LOCKED 可能引发锁竞争。功能上缺乏延迟队列（delay queue）、死信队列（DLQ）等高级特性，需自行实现。此外，依赖 PostgreSQL 特定功能（如 gen_random_uuid() 要求 13+ 版本或 pgcrypto 扩展），对旧版本数据库兼容性有限。

适合的目标群体

特别适合中小型应用和初创团队，尤其是已使用 PostgreSQL 作为主力数据库、希望控制技术栈复杂度的场景。适用于对延迟不敏感（可接受毫秒级而非亚毫秒级）、需要强一致性保证的后台任务，如邮件发送、报表生成、数据同步、定时清理等。对于微服务架构中的轻量级任务调度，或作为现有消息队列的降级方案（fallback）也很合适。不适合高频交易、实时流处理或需要复杂路由规则的企业级消息总线场景。

使用风险与注意事项

性能风险：未正确配置连接池（pgx.Pool）可能导致连接泄漏，耗尽数据库资源。idx_jobs_claimable 部分索引对性能至关重要，若遗漏或维护不当，claiming 操作将随数据量增长而急剧变慢。配置风险：RecoverStaleJobs 的超时参数设置不当会导致作业被过早回收（重复执行）或过晚回收（延迟处理）。数据风险：虽然使用参数化查询防止 SQL 注入，但 data JSONB 字段存储的用户输入仍需应用层校验，避免存储过大 payload 拖垮数据库（文档明确建议仅存储引用）。版本兼容性：使用 gen_random_uuid() 需确保 PostgreSQL 版本支持，否则需改用 uuid-ossp 扩展或应用层生成 ID。

场景分类：agent databasebackenddevopsautomationdevelopment-engineering

02 使用方式

简单 3 步，立即在 AI 工具中使用

1

获取 Skill 文件

通过国内网盘直链下载解压包，或使用上方安装指令。
去下载资源
2

导入你的 AI 工具

在 Cursor / QoderWork / TRAE / Claude 等工具的 Skills 入口导入。
复制安装指令
3

用普通话描述任务

直接说出你的需求，AI 会自动按此 Skill 预设流程落地结果。

快捷方式

复制给 Agent 自动安装

选择你在用的工具，复制下方指令粘贴给 AI，AI 会先说明用途和权限，自动完成安装。

复制给 AI 的指令详细版

零依赖 PostgreSQL 任务队列引擎复制给 AI 自动安装

03 风险与前置

使用前注意事项与安全等级

安全等级 A：已整理并检查，正常使用无明显风险。 ## 核心用法 `postgres-job-queue` 提供了一套完整的 PostgreSQL 原生任务队列架构设计，涵盖数据库表结构设计、索引优化、事务安全的批量任务认领机制，以及 Go 语言客户端实现。核心特性包括： - **事务安全认领**：利用 PostgreSQL 9.5+ 的 `FOR UPDATE SKIP LOCKED` 语法，实现高并发下的无锁竞争任务分发，避免传统 `SELECT then UPDATE` 的竞态条件 - **优先级调度**：通过 `(priority DESC, created_at ASC)` 复合排序实现多级优先级队列 - **进度可视化**：内置 `progress`、`current_stage`、`events_count` 字段，支持长任务实时状态追踪 - **失效恢复**：自动检测超时未完成的僵尸任务，重新放回待处理队列 - **分级重试**：支持 `attempts`/`max_attempts` 计数与失败降级策略 ### 显著优点 1. **零外部依赖**：无需部署 Redis/RabbitMQ 等消息中间件，降低运维复杂度与基础设施成本 2. **持久化保障**：任务状态持久化存储，服务重启不丢数据，天然支持 ACID 语义 3. **查询友好**：可直接用 SQL 查询任务状态、统计报表、调试追踪，无需专用监控工具 4. **水平扩展**：配合 `SKIP LOCKED` 与批量认领（batch claiming），多 worker 实例可安全并行 5. **与业务数据同库**：任务数据与业务数据在同一事务内处理，简化分布式事务设计 ### 潜在局限 - **吞吐上限**：实测 < 1000 jobs/sec 表现良好，> 10000 jobs/sec 时建议叠加 Redis 层 - **延迟敏感场景**：PostgreSQL 的毫秒级响应无法满足亚毫秒级延迟要求的实时队列 - **严格顺序保证**：若需全局 FIFO，必须限制单类型单 worker，牺牲并行度 - **大消息体**：不建议直接存储大 payload，需外置对象存储（如 S3）存引用 - **运维复杂度**：需维护 `idx_jobs_claimable` 部分索引，否则高并发认领性能骤降 ### 适合人群 - 中小型项目（< 10K TPS）希望简化技术栈、避免引入消息队列的团队 - 已有 PostgreSQL 基础设施、希望复用现有运维能力的工程团队 - 需要任务状态持久化、进度可查询的批处理场景（如视频转码、报表生成、数据迁移） - 对运维成本敏感、优先考虑开发效率的初创团队 ### 常规风险 | 风险点 | 说明 | 缓解措施 | |--------|------|---------| | 索引缺失导致性能崩塌 | 未创建 `idx_jobs_claimable` 部分索引时，高并发认领全表扫描 | 严格按文档创建 `WHERE status = 'pending'` 部分索引 | | SKIP LOCKED 误用 | 遗漏 `SKIP LOCKED` 导致 worker 死锁 | 复制文档中的 `claim_job_batch` 函数实现 | | 大 payload 拖垮库表 | JSONB 字段存储大对象导致 WAL 膨胀、查询缓慢 | 仅存储元数据，payload 存 S3 并留 URL 引用 | | 僵尸任务堆积 | 崩溃 worker 遗留的 `claimed`/`running` 状态任务 | 部署 `RecoverStaleJobs` 定时任务 | | 无限重试风暴 | `max_attempts` 配置不当或失败不降级 | 设置合理的重试上限与指数退避 |

report_id: CLS-20260506-PJQ-A1F3
report_date: "2026-05-06T09:32:35Z"
scanner_version: CLS-Certify v2.1.0
scan_mode: Batch Mode (T-MD Strategy)
skill_name: postgres-job-queue
skill_version: 1.0.0
skill_path: /tmp/bss_skill_zhsllhbd
maintainer: wpank
license: unknown
source_url: https://github.com/openclaw/skills/tree/main/skills/backend/postgres-job-queue
trust_level: T3
trust_level_text: 个人开发者/社区项目
scan_duration: 8.3s
code_stats: 3 files · 292 lines · Markdown 96.2%
grade: A
score: 95
evaluation: 标准安全级别，纯文档型 Skill 无可执行代码
stamp_color: green
total_风险发现: 0
radar:

name: 静态代码分析
short: 静态分析
score: 95
status: pass
detail: 纯 Markdown 文档，无实际可执行代码，威胁扫描检出 3 处误报已排除
name: 动态行为分析
short: 动态分析
score: N/A
status: skip
detail: T-MD 分类跳过动态分析
name: 依赖审计
short: 依赖审计
score: N/A
status: skip
detail: T-MD 分类跳过依赖审计
name: 网络流量分析
short: 网络分析
score: 100
status: pass
detail: 未发现外部 API 调用或网络请求
name: 隐私合规检查
short: 隐私合规
score: 95
status: pass
detail: 无用户数据收集，无敏感环境变量访问
name: 威胁情报
short: 威胁情报
score: 90
status: warn
detail: 来源 T3（个人开发者 wpank），建议代码审查后使用

compliance:

text: 数据收集透明性
status: pass
text: 用户同意机制
status: pass
text: 数据最小化原则
status: pass
text: 安全存储要求
status: pass
text: 数据传输加密
status: pass
text: 用户删除权利
status: pass

sample_hash: sha256:373c69d419b34a630a29e57eb5a22e795533762f461afc6a7a796e6c78b358f3

disclaimer: 本认证结果仅代表检测时刻的安全状态，不构成对未来版本的保证。Skill 来源为个人开发者（T3），建议在使用前进行额外代码审查。

风险模式

success: 无高危威胁模式
success: 无敏感信息泄露
success: 无外部网络调用
info: 纯文档型 Skill
warning: T3 来源（个人开发者）

分析摘要

Skill 类型判定: 经分类检测，该 Skill 为 T-MD（纯 Markdown）类型，所有文件均为 Markdown 文档，无可执行代码文件，代码片段仅作为技术文档示例存在。
威胁扫描结果: 威胁扫描工具检出 3 处疑似 exec() 调用，经人工验证均为误报——实际为 Go 语言 pgx 数据库驱动中的 db.Exec(ctx, sql) 方法，用于执行预编译 SQL 语句，非动态代码执行。
网络与 API 审计: URL 审计未发现任何外部 API 端点或网络请求。README 中的 npx add 命令指向 GitHub 公开仓库，属于正常的 Skill 安装指引。
隐私与合规: 该 Skill 不收集用户数据、不访问敏感环境变量、不发起网络请求，符合 GDPR/CCPA 数据最小化原则。
来源可信度: 来源为 GitHub 用户 wpank，属于个人开发者（T3 级别）。该 Skill 隶属于 openclaw/skills 仓库，有一定的社区背景，但建议企业用户在使用前进行额外审查。

外部接口

endpoint	method	reputation	encryption	data_types	provider
N/A	N/A	N/A	N/A	N/A	N/A

风险发现

该 Skill 检测完成，未发现确认的安全风险。威胁扫描产生的 3 处候选命中均已验证为误报。

RISK-001（已排除 - 误报）

severity: info
category: false_positive
title: Go db.Exec() 误识别为 Python exec()
location: SKILL.md:137, 149, 171
description: 威胁扫描工具基于正则匹配检测到 err := q.db.Exec(ctx 模式，误识别为 Python 的 exec() 动态代码执行函数。实际上这是 Go 语言 pgx PostgreSQL 驱动库的标准方法，用于执行预编译 SQL 语句（如 UPDATE jobs SET status = 'completed'...）。
recommendation: 无需修复，已在评分阶段排除
verified: false_positive

改进建议

1. 对最终用户的建议

该 Skill 已通过 CLS 安全认证，评级为 A 级，可以安全使用。由于该 Skill 为纯文档型（提供 PostgreSQL 任务队列的设计模式和 SQL/Go 代码示例），不会执行任何系统操作或网络请求，风险极低。

2. 对来源可信度的建议

该 Skill 来源于个人开发者（T3 级别），虽然代码本身无害，但建议关注以下事项：

定期检查上游仓库是否有更新
在企业环境中使用前可由内部安全团队进行二次审查
关注 GitHub 仓库的维护活跃度（提交历史、Issue 响应等）

3. 提升至 S 级的建议

若要将评级提升至 S 级，建议维护者：

添加明确的 LICENSE 文件（当前未检测到许可证声明）
在 GitHub 上完善仓库信息（README、贡献指南等）
考虑将 Skill 贡献至知名开源组织（如 openclaw）以提升来源可信度至 T2 级别

报告生成时间: 2026-05-06 17:35:00 UTC
CLS-Certify Scanner v2.1.0 build 20260317.0002

04 会员优势

国内网盘直下载与运维维护

国内网盘直下载

百度/夸克直链转存，无需翻墙或挂代理。

国内镜像与版本固定

固定有效版本，经过实测排查，避免代码变动导致失效。

失效自动补链

专人维护网盘地址，发现链接失效 24h 内完成补链。

更新提醒与省心省时

随时获取最新修复说明，帮非技术用户节省大把调优时间。

源码与文件预览（2 个文件）

/README.md

正在加载代码…