django-simpletask5 0.2.6__tar.gz → 0.2.8__tar.gz

{django_simpletask5-0.2.6 → django_simpletask5-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-simpletask5
-Version: 0.2.6
+Version: 0.2.8
 Summary: Lightweight async task execution framework for Django
 Author-email: rRR0VrFP <rrr0vrfp@qq.com>
 Maintainer-email: rRR0VrFP <rrr0vrfp@qq.com>
@@ -23,7 +23,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: globallock>=0.1.4
+Requires-Dist: globallock>=0.2.0
 Requires-Dist: django-safe-fields>=0.2.3
 Requires-Dist: django-app-requires>=0.3.6
 Requires-Dist: django-admin-dashboards>=0.1.1
@@ -143,6 +143,7 @@ DJANGO_SIMPLETASK_BROKER_URL = 'amqp://guest:guest@127.0.0.1:5672//'
 # DJANGO_SIMPLETASK_REDIS_MQ_HOST = '127.0.0.1'       # MESSAGE_QUEUE_TYPE='redis' 时
 # DJANGO_SIMPLETASK_REDIS_MQ_PORT = 6379
 # DJANGO_SIMPLETASK_REDIS_MQ_DB = 0
+# DJANGO_SIMPLETASK_REDIS_MQ_PASSWORD = None          # Redis MQ 需认证时设置
 
 # ── 分布式锁与 Worker 注册中心（Redis）────────────────────────
 # 默认锁引擎 DjangoRedisGlobalLock 复用 CACHES['default']，需为 Redis 缓存
@@ -153,13 +154,16 @@ CACHES = {
         'OPTIONS': {'CLIENT_CLASS': 'django_redis.client.DefaultClient'},
     },
 }
-# 如需独立连接参数（锁与 Worker 注册中心共用同一 host/port/db）：
+# 如需独立连接参数（锁与 Worker 注册中心共用同一 host/port/db/password）：
 # DJANGO_SIMPLETASK_LOCK_CONFIG = {
 #     'global_lock_engine_class': 'globallock.redis_global_lock.RedisGlobalLock',
-#     'global_lock_engine_options': {'host': '127.0.0.1', 'port': 6379, 'db': 0},
+#     'global_lock_engine_options': {'host': '127.0.0.1', 'port': 6379, 'db': 0,
+#                                    'password': '<redis 密码，无需认证可省略>'},
 # }
-DJANGO_SIMPLETASK_LOCK_TIMEOUT = 600                 # 锁超时（秒）
-DJANGO_SIMPLETASK_LOCK_RENEW_INTERVAL = 60           # 锁续期间隔（秒）
+# 注：globallock>=0.2.0 已取消按 timeout 自动释放的概念。锁的有效期由
+# lockman/lock 作用域自行管理，作用域未结束前锁持续有效（内置看门狗自动续期），
+# 锁在 `with` 块退出或进程消亡时自动释放。已移除 DJANGO_SIMPLETASK_LOCK_TIMEOUT
+# 与 DJANGO_SIMPLETASK_LOCK_RENEW_INTERVAL，请勿再配置这两项。
 
 # ── Key 前缀与队列路由 ───────────────────────────────────────
 DJANGO_SIMPLETASK_KEY_PREFIX = 'myproject'           # Redis key 前缀，默认取 ROOT_URLCONF 首段
@@ -209,11 +213,9 @@ django_app_requires_patch_all()
 | `DJANGO_SIMPLETASK_BROKER_URL` | `None` | **优先级最高**，设置后忽略下方 MQ 类型/连接参数。生产建议统一使用完整 URL，便于复用云厂商连接串与凭据管理 |
 | `DJANGO_SIMPLETASK_MESSAGE_QUEUE_TYPE` | `'memory'` | `memory` 仅用于开发调试；**生产必须改为 `rabbitmq` 或 `redis`**，否则消息不持久化、跨进程 Worker 无法消费 |
 | `DJANGO_SIMPLETASK_RABBITMQ_HOST/PORT/USER/PASSWORD` | `127.0.0.1 / 5672 / guest / guest` | 类型为 `rabbitmq` 且未设 `BROKER_URL` 时生效。生产务必更换默认 `guest` 凭据 |
-| `DJANGO_SIMPLETASK_REDIS_MQ_HOST/PORT/DB` | `127.0.0.1 / 6379 / 0` | 类型为 `redis` 时生效。建议与锁/缓存使用**不同 db**，避免 key 冲突与互相阻塞 |
+| `DJANGO_SIMPLETASK_REDIS_MQ_HOST/PORT/DB/PASSWORD` | `127.0.0.1 / 6379 / 0 / None` | 类型为 `redis` 时生效。建议与锁/缓存使用**不同 db**，避免 key 冲突与互相阻塞。Redis 需认证时设置 `PASSWORD` |
 | `CACHES['default']` | — | 默认锁引擎 `DjangoRedisGlobalLock` 依赖它，**必须配置为 Redis 缓存** |
-| `DJANGO_SIMPLETASK_LOCK_CONFIG` | `None`（默认复用缓存锁） | 需要独立连接参数时显式配置。**注意**：Worker 注册中心（心跳/状态）也读取该配置的 `host/port/db`，未配置时固定连 `127.0.0.1:6379/0` |
-| `DJANGO_SIMPLETASK_LOCK_TIMEOUT` | `600` | 锁自动释放时间，应**大于单任务最长执行时长**；过短会导致长任务执行中被其他 Worker 抢锁 |
-| `DJANGO_SIMPLETASK_LOCK_RENEW_INTERVAL` | `60` | 锁续期间隔，应**远小于 `LOCK_TIMEOUT`**（默认 600 的 1/10） |
+| `DJANGO_SIMPLETASK_LOCK_CONFIG` | `None`（默认复用缓存锁） | 需要独立连接参数时显式配置（`global_lock_engine_options` 支持 `host/port/db/password`）。**注意**：Worker 注册中心（心跳/状态）也读取该配置的 `host/port/db/password`，未配置时固定连 `127.0.0.1:6379/0`。globallock>=0.2.0 起锁有效期由 lockman/lock 作用域管理（内置看门狗自动续期），**不再需要配置 `LOCK_TIMEOUT` / `LOCK_RENEW_INTERVAL`** |
 | `DJANGO_SIMPLETASK_KEY_PREFIX` | 自动取 `ROOT_URLCONF` 首段 | 生产建议**显式指定**，多项目共用 Redis 时避免 key 冲突 |
 | `DJANGO_SIMPLETASK_DEFAULT_QUEUE` | `{prefix}:...:queue:default` | 默认队列名。多环境（dev/staging/prod）建议加环境后缀隔离 |
 | `DJANGO_SIMPLETASK_HIGH_PRIORITY_QUEUE` | `{prefix}:...:queue:high_priority` | 高优先级队列，**需单独启动 Worker 消费** |
@@ -276,7 +278,7 @@ class OrderTask(Task):
 ```
 
 要点：
-- 主键为 Django 默认自增 `id`；内置 `task_id`（UUID，`unique=True`）作为业务唯一标识，**不是**主键
+- 主键为 Django 默认自增 `id`。`Task` 不再内置 `task_id` 字段，业务标识由业务模型自行定义（自定义主键或自然键均可）
 - 保存 / 删除 / 批量创建自动触发事件，详见「事件处理机制」
 - 事件上下文、update 字段判定、delete 拦截等行为的完整说明见对应章节
 
@@ -352,7 +354,7 @@ OrderTask.objects.create(order_id='ORD-001', customer_name='Test', amount=Decima
 | `update` | 字段值发生变化后保存 | `task_id`、`trigger_event`、`data`、`old_data`、`new_data`、`changed_fields` |
 | `delete` | 调用 `instance.delete()` | `task_id`、`trigger_event`、`data` |
 
-执行器通过 `execution.get_context_dict()` 获取以上上下文。
+执行器通过 `execution.get_context_dict()` 获取以上上下文。其中 `task_id` 是业务对象主键的字符串表示（如 `"42"`、UUID 字符串或自定义键）；业务对象反查见「模型与生命周期」。
 
 #### update 事件的字段变更判定
 
@@ -391,6 +393,8 @@ class OrderDeleteExecutor(BaseExecutor):
 
 这样实现删除操作与外部系统清理的解耦，且支持失败重试。
 
+`confirm_delete()` 与 `execution.get_task()` 都会通过 `TaskExecution.task_id`（业务主键字符串）反查业务对象，反查逻辑由业务模型上的 `get_task_instance()` 提供（见「模型与生命周期」）。
+
 ### 事件 → 执行器映射
 
 每个事件消息最终要由一个执行器处理。`executor_class` 声明「事件名 → 执行器类路径」的分派表，可以是字符串（所有事件共用同一个执行器）或字典（按事件分派）：
@@ -566,10 +570,38 @@ class OrderCreateExecutor(BaseExecutor):
 
 所有业务任务模型继承 `Task`：
 
-- 内置 `task_id`（UUID，`unique=True`）；主键为 Django 默认自增 `id`，无需自定义
+- 主键为 Django 默认自增 `id`，无需自定义；**不内置** `task_id` 字段，业务标识由业务模型按需定义
 - 提供 `trigger(event, extra_context)`、`skip_publish()`、`get_executor_class_path(event)`、`get_queue_name(event)` 等方法
 - 保存、删除、批量创建自动触发事件（见「事件处理机制」）
 
+#### 业务对象反查：`get_task_instance()`
+
+`TaskExecution.task_id` 存的是业务对象主键的字符串表示（`CharField`）。需要反查业务对象时（`execution.get_task()` / `execution.confirm_delete()`），框架先通过 `task_model` 解析出模型类，再调用该类的 `get_task_instance(task_id)` 完成查询。
+
+默认实现在 `Task` 基类中按主键 `pk` 查询，并通过内置的 `_coerce_task_pk()` 兼容常见主键类型：
+
+- `AutoField` / `BigAutoField` / `SmallAutoField` — 字符串转为 `int`
+- `UUIDField` — 字符串转为 `uuid.UUID`
+- `CharField` / `TextField` 等字符串主键 — 原样使用
+
+```python
+task = execution.get_task()          # 返回业务对象（反查不到返回 None）
+execution.confirm_delete()          # 反查并真实删除业务对象
+```
+
+业务模型使用自定义主键或非主键自然键时，**重载 `get_task_instance()`** 即可，框架会自动改走你的实现：
+
+```python
+class OrderTask(Task):
+    code = models.CharField(max_length=64, unique=True)   # 非主键自然键
+
+    @classmethod
+    def get_task_instance(cls, task_id):
+        if task_id is None:
+            return None
+        return cls.objects.filter(code=task_id).first()
+```
+
 ### TaskExecution 状态机
 
 每条事件消息对应一条 `TaskExecution` 记录，状态流转如下：
@@ -686,6 +718,8 @@ python3 -m pytest django_simpletask5_example/tests
 
 测试套件覆盖 Redis、DB、MQ 连接中断后的自动恢复场景，详见 `django_simpletask5_example/tests/test_resilience_recovery.py`。
 
+**测试输出约定**：单元测试中对预期会触发的错误（如无效 UUID 校验、毒消息丢弃、消费者断连、执行器加载失败等）所输出的错误日志，必须在测试内屏蔽，避免污染测试输出。统一使用 `django_simpletask5_example.tests.suppress_expected_errors` 上下文管理器（整体禁用日志）或 `patch.object(..., 'logger')`（断言同时校验日志）进行屏蔽。
+
 ## 架构
 
 ```
@@ -698,6 +732,21 @@ Worker 消费消息 → 获取分布式锁 → 加载执行器 → 执行并保
 
 ## Releases
 
+### 0.2.8
+
+- **移除 `Task` 冗余的 `task_id` 字段** — `TaskExecution.task_id` 由 UUID 改为 `CharField(max_length=255)`，直接用于存放业务对象主键字符串（`str(instance.pk)`），不再维护一份与业务主键重复的 UUID。消息上下文中的 `task_id` 字段名不变，值语义从 UUID 变为业务主键字符串（如 `"42"`）
+- **业务对象反查下沉到模型层** — 新增 `Task.get_task_instance(task_id)` 类方法作为默认反查实现（按 `pk` 查询，内置 `_coerce_task_pk()` 兼容 `int` / `UUID` / 字符串主键）；`TaskExecution.get_task()` / `confirm_delete()` 改为解析 `task_model` 后委托给该方法。业务模型使用自定义主键或自然键时重载 `get_task_instance()` 即可
+- **新增迁移** — `django_simpletask5.0013_alter_taskexecution_task_id`（字段改 CharField）、`django_simpletask5_example.0003_remove_ordertask_task_id`
+- **破坏性变更**: 依赖 `TaskExecution.task_id` 为 UUID 类型的外部消费方需适配为业务主键字符串；业务 `Task` 子类若曾使用内置 `task_id` 字段需移除
+
+### 0.2.7
+
+- **运行中任务回收机制重构** — 取消原先按 `expire_time` 将 running 直接判为超时的语义；`StatusCheckExecutor` 仅兜底回收长期未被 Worker 获取的 pending。新增 `core/reclaim`，由 crontab 每 ~5 秒基于执行锁探测运行中任务：锁已过期（执行器异常退出）即快速重投或直接置失败，降低孤儿任务滞留时间
+- **重试不再搁浅任务** — 失败重试先落库 `retry` 再发布重试消息，发布失败则 requeue 当前消息，杜绝任务永久停在无人处理的 `retry` 状态；KombuQueue 依据 AMQP `x-death` 上限丢弃毒消息，避免无限 requeue 造成的队头阻塞与空转
+- **消费者重连提示** — Worker 断连重连成功后输出 `Consumer connection restored` 恢复日志，便于运维确认消费通道已恢复
+- **安全与健壮性加固** — broker 账号/密码按百分号编码、脚本白名单按路径段边界匹配、signals 快照按实例隔离，覆盖相关回归测试
+- **新增测试约定** — 单元测试中对预期触发（如无效 UUID 校验、毒消息丢弃、消费者断连、执行器加载失败等）产生的错误日志必须屏蔽输出，统一使用 `django_simpletask5_example.tests.suppress_expected_errors` 或替换 logger，保证测试输出干净可读；本次同步清理全部此类预期错误日志
+
 ### 0.2.6
 
 - **新增 `canceled` 状态** — 取消已发布但未执行的任务改为独立的终态 `canceled`（原复用 `failed`），Worker 消费到已取消消息时直接跳过；Admin 取消操作、归档/清理/统计（新增 `canceled_count`）、Dashboard 状态图均纳入该状态，取消与执行失败可清晰区分
@@ -714,7 +763,7 @@ Worker 消费消息 → 获取分布式锁 → 加载执行器 → 执行并保
 
 - **破坏性变更**: `TaskExecution` 主键由 `execution_id`（UUID）改为默认自增 `id`，`execution_id` 变为 `unique=True` 的唯一标识字段。已有数据库需要执行迁移 `0010_taskexecution_id_alter_taskexecution_execution_id`
 - **定期存活日志** — Worker 与 Crontab 主循环在长时间无消息/无任务时按 `DJANGO_SIMPLETASK_LOG_INTERVAL`（默认 300 秒）定期输出存活日志，并统一带时间戳格式，便于运维确认进程未死循环
-- **MQ 日志降噪** — MQ 消费/发布异常及 Redis 连接失败、锁续期失败改为 `error`/`warning` 级别且无堆栈（默认按间隔节流），避免刷屏；提供 `--debug` 时输出完整堆栈
+- **MQ 日志降噪** — MQ 消费/发布异常及 Redis 连接失败改为 `error`/`warning` 级别且无堆栈（默认按间隔节流），避免刷屏；提供 `--debug` 时输出完整堆栈。注：此处所指的"锁续期失败"是 0.2.4 版本引入的自定义锁续期机制，自 globallock>=0.2.0 起该机制已**移除**，改由 globallock 内置看门狗在 lockman/lock 作用域内自动续期，无需（也无从）单独记录续期失败日志
 - **新增配置** — `DJANGO_SIMPLETASK_LOG_INTERVAL` 控制死循环存活日志与异常节流日志的输出间隔（秒）
 
 ### 0.2.3

{django_simpletask5-0.2.6 → django_simpletask5-0.2.8}/README.md

@@ -103,6 +103,7 @@ DJANGO_SIMPLETASK_BROKER_URL = 'amqp://guest:guest@127.0.0.1:5672//'
 # DJANGO_SIMPLETASK_REDIS_MQ_HOST = '127.0.0.1'       # MESSAGE_QUEUE_TYPE='redis' 时
 # DJANGO_SIMPLETASK_REDIS_MQ_PORT = 6379
 # DJANGO_SIMPLETASK_REDIS_MQ_DB = 0
+# DJANGO_SIMPLETASK_REDIS_MQ_PASSWORD = None          # Redis MQ 需认证时设置
 
 # ── 分布式锁与 Worker 注册中心（Redis）────────────────────────
 # 默认锁引擎 DjangoRedisGlobalLock 复用 CACHES['default']，需为 Redis 缓存
@@ -113,13 +114,16 @@ CACHES = {
         'OPTIONS': {'CLIENT_CLASS': 'django_redis.client.DefaultClient'},
     },
 }
-# 如需独立连接参数（锁与 Worker 注册中心共用同一 host/port/db）：
+# 如需独立连接参数（锁与 Worker 注册中心共用同一 host/port/db/password）：
 # DJANGO_SIMPLETASK_LOCK_CONFIG = {
 #     'global_lock_engine_class': 'globallock.redis_global_lock.RedisGlobalLock',
-#     'global_lock_engine_options': {'host': '127.0.0.1', 'port': 6379, 'db': 0},
+#     'global_lock_engine_options': {'host': '127.0.0.1', 'port': 6379, 'db': 0,
+#                                    'password': '<redis 密码，无需认证可省略>'},
 # }
-DJANGO_SIMPLETASK_LOCK_TIMEOUT = 600                 # 锁超时（秒）
-DJANGO_SIMPLETASK_LOCK_RENEW_INTERVAL = 60           # 锁续期间隔（秒）
+# 注：globallock>=0.2.0 已取消按 timeout 自动释放的概念。锁的有效期由
+# lockman/lock 作用域自行管理，作用域未结束前锁持续有效（内置看门狗自动续期），
+# 锁在 `with` 块退出或进程消亡时自动释放。已移除 DJANGO_SIMPLETASK_LOCK_TIMEOUT
+# 与 DJANGO_SIMPLETASK_LOCK_RENEW_INTERVAL，请勿再配置这两项。
 
 # ── Key 前缀与队列路由 ───────────────────────────────────────
 DJANGO_SIMPLETASK_KEY_PREFIX = 'myproject'           # Redis key 前缀，默认取 ROOT_URLCONF 首段
@@ -169,11 +173,9 @@ django_app_requires_patch_all()
 | `DJANGO_SIMPLETASK_BROKER_URL` | `None` | **优先级最高**，设置后忽略下方 MQ 类型/连接参数。生产建议统一使用完整 URL，便于复用云厂商连接串与凭据管理 |
 | `DJANGO_SIMPLETASK_MESSAGE_QUEUE_TYPE` | `'memory'` | `memory` 仅用于开发调试；**生产必须改为 `rabbitmq` 或 `redis`**，否则消息不持久化、跨进程 Worker 无法消费 |
 | `DJANGO_SIMPLETASK_RABBITMQ_HOST/PORT/USER/PASSWORD` | `127.0.0.1 / 5672 / guest / guest` | 类型为 `rabbitmq` 且未设 `BROKER_URL` 时生效。生产务必更换默认 `guest` 凭据 |
-| `DJANGO_SIMPLETASK_REDIS_MQ_HOST/PORT/DB` | `127.0.0.1 / 6379 / 0` | 类型为 `redis` 时生效。建议与锁/缓存使用**不同 db**，避免 key 冲突与互相阻塞 |
+| `DJANGO_SIMPLETASK_REDIS_MQ_HOST/PORT/DB/PASSWORD` | `127.0.0.1 / 6379 / 0 / None` | 类型为 `redis` 时生效。建议与锁/缓存使用**不同 db**，避免 key 冲突与互相阻塞。Redis 需认证时设置 `PASSWORD` |
 | `CACHES['default']` | — | 默认锁引擎 `DjangoRedisGlobalLock` 依赖它，**必须配置为 Redis 缓存** |
-| `DJANGO_SIMPLETASK_LOCK_CONFIG` | `None`（默认复用缓存锁） | 需要独立连接参数时显式配置。**注意**：Worker 注册中心（心跳/状态）也读取该配置的 `host/port/db`，未配置时固定连 `127.0.0.1:6379/0` |
-| `DJANGO_SIMPLETASK_LOCK_TIMEOUT` | `600` | 锁自动释放时间，应**大于单任务最长执行时长**；过短会导致长任务执行中被其他 Worker 抢锁 |
-| `DJANGO_SIMPLETASK_LOCK_RENEW_INTERVAL` | `60` | 锁续期间隔，应**远小于 `LOCK_TIMEOUT`**（默认 600 的 1/10） |
+| `DJANGO_SIMPLETASK_LOCK_CONFIG` | `None`（默认复用缓存锁） | 需要独立连接参数时显式配置（`global_lock_engine_options` 支持 `host/port/db/password`）。**注意**：Worker 注册中心（心跳/状态）也读取该配置的 `host/port/db/password`，未配置时固定连 `127.0.0.1:6379/0`。globallock>=0.2.0 起锁有效期由 lockman/lock 作用域管理（内置看门狗自动续期），**不再需要配置 `LOCK_TIMEOUT` / `LOCK_RENEW_INTERVAL`** |
 | `DJANGO_SIMPLETASK_KEY_PREFIX` | 自动取 `ROOT_URLCONF` 首段 | 生产建议**显式指定**，多项目共用 Redis 时避免 key 冲突 |
 | `DJANGO_SIMPLETASK_DEFAULT_QUEUE` | `{prefix}:...:queue:default` | 默认队列名。多环境（dev/staging/prod）建议加环境后缀隔离 |
 | `DJANGO_SIMPLETASK_HIGH_PRIORITY_QUEUE` | `{prefix}:...:queue:high_priority` | 高优先级队列，**需单独启动 Worker 消费** |
@@ -236,7 +238,7 @@ class OrderTask(Task):
 ```
 
 要点：
-- 主键为 Django 默认自增 `id`；内置 `task_id`（UUID，`unique=True`）作为业务唯一标识，**不是**主键
+- 主键为 Django 默认自增 `id`。`Task` 不再内置 `task_id` 字段，业务标识由业务模型自行定义（自定义主键或自然键均可）
 - 保存 / 删除 / 批量创建自动触发事件，详见「事件处理机制」
 - 事件上下文、update 字段判定、delete 拦截等行为的完整说明见对应章节
 
@@ -312,7 +314,7 @@ OrderTask.objects.create(order_id='ORD-001', customer_name='Test', amount=Decima
 | `update` | 字段值发生变化后保存 | `task_id`、`trigger_event`、`data`、`old_data`、`new_data`、`changed_fields` |
 | `delete` | 调用 `instance.delete()` | `task_id`、`trigger_event`、`data` |
 
-执行器通过 `execution.get_context_dict()` 获取以上上下文。
+执行器通过 `execution.get_context_dict()` 获取以上上下文。其中 `task_id` 是业务对象主键的字符串表示（如 `"42"`、UUID 字符串或自定义键）；业务对象反查见「模型与生命周期」。
 
 #### update 事件的字段变更判定
 
@@ -351,6 +353,8 @@ class OrderDeleteExecutor(BaseExecutor):
 
 这样实现删除操作与外部系统清理的解耦，且支持失败重试。
 
+`confirm_delete()` 与 `execution.get_task()` 都会通过 `TaskExecution.task_id`（业务主键字符串）反查业务对象，反查逻辑由业务模型上的 `get_task_instance()` 提供（见「模型与生命周期」）。
+
 ### 事件 → 执行器映射
 
 每个事件消息最终要由一个执行器处理。`executor_class` 声明「事件名 → 执行器类路径」的分派表，可以是字符串（所有事件共用同一个执行器）或字典（按事件分派）：
@@ -526,10 +530,38 @@ class OrderCreateExecutor(BaseExecutor):
 
 所有业务任务模型继承 `Task`：
 
-- 内置 `task_id`（UUID，`unique=True`）；主键为 Django 默认自增 `id`，无需自定义
+- 主键为 Django 默认自增 `id`，无需自定义；**不内置** `task_id` 字段，业务标识由业务模型按需定义
 - 提供 `trigger(event, extra_context)`、`skip_publish()`、`get_executor_class_path(event)`、`get_queue_name(event)` 等方法
 - 保存、删除、批量创建自动触发事件（见「事件处理机制」）
 
+#### 业务对象反查：`get_task_instance()`
+
+`TaskExecution.task_id` 存的是业务对象主键的字符串表示（`CharField`）。需要反查业务对象时（`execution.get_task()` / `execution.confirm_delete()`），框架先通过 `task_model` 解析出模型类，再调用该类的 `get_task_instance(task_id)` 完成查询。
+
+默认实现在 `Task` 基类中按主键 `pk` 查询，并通过内置的 `_coerce_task_pk()` 兼容常见主键类型：
+
+- `AutoField` / `BigAutoField` / `SmallAutoField` — 字符串转为 `int`
+- `UUIDField` — 字符串转为 `uuid.UUID`
+- `CharField` / `TextField` 等字符串主键 — 原样使用
+
+```python
+task = execution.get_task()          # 返回业务对象（反查不到返回 None）
+execution.confirm_delete()          # 反查并真实删除业务对象
+```
+
+业务模型使用自定义主键或非主键自然键时，**重载 `get_task_instance()`** 即可，框架会自动改走你的实现：
+
+```python
+class OrderTask(Task):
+    code = models.CharField(max_length=64, unique=True)   # 非主键自然键
+
+    @classmethod
+    def get_task_instance(cls, task_id):
+        if task_id is None:
+            return None
+        return cls.objects.filter(code=task_id).first()
+```
+
 ### TaskExecution 状态机
 
 每条事件消息对应一条 `TaskExecution` 记录，状态流转如下：
@@ -646,6 +678,8 @@ python3 -m pytest django_simpletask5_example/tests
 
 测试套件覆盖 Redis、DB、MQ 连接中断后的自动恢复场景，详见 `django_simpletask5_example/tests/test_resilience_recovery.py`。
 
+**测试输出约定**：单元测试中对预期会触发的错误（如无效 UUID 校验、毒消息丢弃、消费者断连、执行器加载失败等）所输出的错误日志，必须在测试内屏蔽，避免污染测试输出。统一使用 `django_simpletask5_example.tests.suppress_expected_errors` 上下文管理器（整体禁用日志）或 `patch.object(..., 'logger')`（断言同时校验日志）进行屏蔽。
+
 ## 架构
 
 ```
@@ -658,6 +692,21 @@ Worker 消费消息 → 获取分布式锁 → 加载执行器 → 执行并保
 
 ## Releases
 
+### 0.2.8
+
+- **移除 `Task` 冗余的 `task_id` 字段** — `TaskExecution.task_id` 由 UUID 改为 `CharField(max_length=255)`，直接用于存放业务对象主键字符串（`str(instance.pk)`），不再维护一份与业务主键重复的 UUID。消息上下文中的 `task_id` 字段名不变，值语义从 UUID 变为业务主键字符串（如 `"42"`）
+- **业务对象反查下沉到模型层** — 新增 `Task.get_task_instance(task_id)` 类方法作为默认反查实现（按 `pk` 查询，内置 `_coerce_task_pk()` 兼容 `int` / `UUID` / 字符串主键）；`TaskExecution.get_task()` / `confirm_delete()` 改为解析 `task_model` 后委托给该方法。业务模型使用自定义主键或自然键时重载 `get_task_instance()` 即可
+- **新增迁移** — `django_simpletask5.0013_alter_taskexecution_task_id`（字段改 CharField）、`django_simpletask5_example.0003_remove_ordertask_task_id`
+- **破坏性变更**: 依赖 `TaskExecution.task_id` 为 UUID 类型的外部消费方需适配为业务主键字符串；业务 `Task` 子类若曾使用内置 `task_id` 字段需移除
+
+### 0.2.7
+
+- **运行中任务回收机制重构** — 取消原先按 `expire_time` 将 running 直接判为超时的语义；`StatusCheckExecutor` 仅兜底回收长期未被 Worker 获取的 pending。新增 `core/reclaim`，由 crontab 每 ~5 秒基于执行锁探测运行中任务：锁已过期（执行器异常退出）即快速重投或直接置失败，降低孤儿任务滞留时间
+- **重试不再搁浅任务** — 失败重试先落库 `retry` 再发布重试消息，发布失败则 requeue 当前消息，杜绝任务永久停在无人处理的 `retry` 状态；KombuQueue 依据 AMQP `x-death` 上限丢弃毒消息，避免无限 requeue 造成的队头阻塞与空转
+- **消费者重连提示** — Worker 断连重连成功后输出 `Consumer connection restored` 恢复日志，便于运维确认消费通道已恢复
+- **安全与健壮性加固** — broker 账号/密码按百分号编码、脚本白名单按路径段边界匹配、signals 快照按实例隔离，覆盖相关回归测试
+- **新增测试约定** — 单元测试中对预期触发（如无效 UUID 校验、毒消息丢弃、消费者断连、执行器加载失败等）产生的错误日志必须屏蔽输出，统一使用 `django_simpletask5_example.tests.suppress_expected_errors` 或替换 logger，保证测试输出干净可读；本次同步清理全部此类预期错误日志
+
 ### 0.2.6
 
 - **新增 `canceled` 状态** — 取消已发布但未执行的任务改为独立的终态 `canceled`（原复用 `failed`），Worker 消费到已取消消息时直接跳过；Admin 取消操作、归档/清理/统计（新增 `canceled_count`）、Dashboard 状态图均纳入该状态，取消与执行失败可清晰区分
@@ -674,7 +723,7 @@ Worker 消费消息 → 获取分布式锁 → 加载执行器 → 执行并保
 
 - **破坏性变更**: `TaskExecution` 主键由 `execution_id`（UUID）改为默认自增 `id`，`execution_id` 变为 `unique=True` 的唯一标识字段。已有数据库需要执行迁移 `0010_taskexecution_id_alter_taskexecution_execution_id`
 - **定期存活日志** — Worker 与 Crontab 主循环在长时间无消息/无任务时按 `DJANGO_SIMPLETASK_LOG_INTERVAL`（默认 300 秒）定期输出存活日志，并统一带时间戳格式，便于运维确认进程未死循环
-- **MQ 日志降噪** — MQ 消费/发布异常及 Redis 连接失败、锁续期失败改为 `error`/`warning` 级别且无堆栈（默认按间隔节流），避免刷屏；提供 `--debug` 时输出完整堆栈
+- **MQ 日志降噪** — MQ 消费/发布异常及 Redis 连接失败改为 `error`/`warning` 级别且无堆栈（默认按间隔节流），避免刷屏；提供 `--debug` 时输出完整堆栈。注：此处所指的"锁续期失败"是 0.2.4 版本引入的自定义锁续期机制，自 globallock>=0.2.0 起该机制已**移除**，改由 globallock 内置看门狗在 lockman/lock 作用域内自动续期，无需（也无从）单独记录续期失败日志
 - **新增配置** — `DJANGO_SIMPLETASK_LOG_INTERVAL` 控制死循环存活日志与异常节流日志的输出间隔（秒）
 
 ### 0.2.3

{django_simpletask5-0.2.6 → django_simpletask5-0.2.8}/django_simpletask5/core/cronjob_registry.py

@@ -94,10 +94,10 @@ def register_builtin_cronjobs():
 
     register_cronjob(
         uid='simpletask_status_check',
-        display_name=_('Task Timeout Detection'),
+        display_name=_('Pickup Timeout Detection'),
         cron_expression='* * * * *',
         executor_class='django_simpletask5.executors.status_check.StatusCheckExecutor',
-        description='Scan long-running pending/running tasks and mark them as timeout',
+        description='Scan pending tasks that were never picked up and mark them as timeout for retry. Running tasks are not time-limited: orphans are reclaimed by the scheduler based on execution-lock expiry',
     )
     register_cronjob(
         uid='simpletask_retry_timeout',

{django_simpletask5-0.2.6 → django_simpletask5-0.2.8}/django_simpletask5/core/defaults.py

@@ -13,9 +13,6 @@ def _compute_key_prefix() -> str:
 
 DJANGO_SIMPLETASK_KEY_PREFIX = _compute_key_prefix()
 
-DJANGO_SIMPLETASK_LOCK_TIMEOUT = getattr(settings, 'DJANGO_SIMPLETASK_LOCK_TIMEOUT', 600)
-DJANGO_SIMPLETASK_LOCK_RENEW_INTERVAL = getattr(settings, 'DJANGO_SIMPLETASK_LOCK_RENEW_INTERVAL', 60)
-
 DJANGO_SIMPLETASK_SHUTDOWN_TIMEOUT = getattr(settings, 'DJANGO_SIMPLETASK_SHUTDOWN_TIMEOUT', 30)
 DJANGO_SIMPLETASK_LOG_INTERVAL = getattr(settings, 'DJANGO_SIMPLETASK_LOG_INTERVAL', 300)
 DJANGO_SIMPLETASK_WORKER_HEARTBEAT_INTERVAL = getattr(settings, 'DJANGO_SIMPLETASK_WORKER_HEARTBEAT_INTERVAL', 60)

{django_simpletask5-0.2.6 → django_simpletask5-0.2.8}/django_simpletask5/core/message_queue.py

@@ -1,6 +1,7 @@
 import logging
 import socket
 import time
+from urllib.parse import quote
 
 from django.conf import settings
 from kombu import Connection, Exchange, Queue, Producer, Consumer
@@ -10,6 +11,11 @@ from django_simpletask5.core.defaults import DJANGO_SIMPLETASK_LOG_INTERVAL
 logger = logging.getLogger(__name__)
 
 
+def _quote_url_component(value):
+    """URL 编码账号/密码，避免密码含 @ : / % 等保留字符破坏连接串解析。"""
+    return quote(str(value), safe='')
+
+
 def _get_broker_url():
     url = getattr(settings, 'DJANGO_SIMPLETASK_BROKER_URL', None)
     if url:
@@ -20,12 +26,16 @@ def _get_broker_url():
         port = getattr(settings, 'DJANGO_SIMPLETASK_RABBITMQ_PORT', 5672)
         user = getattr(settings, 'DJANGO_SIMPLETASK_RABBITMQ_USER', 'guest')
         pw = getattr(settings, 'DJANGO_SIMPLETASK_RABBITMQ_PASSWORD', 'guest')
+        user = _quote_url_component(user)
+        pw = _quote_url_component(pw)
         return f'amqp://{user}:{pw}@{host}:{port}//'
     if transport == 'redis':
         host = getattr(settings, 'DJANGO_SIMPLETASK_REDIS_MQ_HOST', '127.0.0.1')
         port = getattr(settings, 'DJANGO_SIMPLETASK_REDIS_MQ_PORT', 6379)
         db = getattr(settings, 'DJANGO_SIMPLETASK_REDIS_MQ_DB', 0)
-        return f'redis://{host}:{port}/{db}'
+        pw = getattr(settings, 'DJANGO_SIMPLETASK_REDIS_MQ_PASSWORD', None)
+        auth = f':{_quote_url_component(pw)}@' if pw else ''
+        return f'redis://{auth}{host}:{port}/{db}'
     return 'memory://'
 
 
@@ -89,15 +99,42 @@ class KombuQueue:
         try:
             result = callback(body)
             if result is False:
+                if KombuQueue._exceeds_max_redeliveries(message):
+                    logger.error(
+                        'Dropping message after too many redeliveries (possible poison message): %s',
+                        body,
+                    )
+                    message.ack()
+                    return
                 message.reject(requeue=True)
                 return
         except Exception as e:
             logger.error('Error in message callback: %s', e)
+            if KombuQueue._exceeds_max_redeliveries(message):
+                logger.error('Dropping message after too many redeliveries (possible poison message): %s', body)
+                message.ack()
+                return
             message.reject(requeue=True)
             return
         if auto_ack:
             message.ack()
 
+    @staticmethod
+    def _exceeds_max_redeliveries(message):
+        """判断一条消息是否已被反复重投过多次（AMQP x-death 计数）。
+
+        防止“无法服务/暂时性失败”的消息被无限 requeue 造成队头阻塞与 CPU 空转。
+        非 AMQP 传输（memory / redis）不提供 x-death 头，返回 False 保持原行为。
+        """
+        limit = getattr(settings, 'DJANGO_SIMPLETASK_MAX_REQUEUE_DELIVERIES', 100)
+        headers = getattr(message, 'headers', None) or {}
+        x_death = headers.get('x-death') or []
+        total = 0
+        for entry in x_death:
+            if isinstance(entry, dict):
+                total += int(entry.get('count', 0) or 0)
+        return total >= limit
+
     def stop(self):
         self._stopped = True
 

{django_simpletask5-0.2.6 → django_simpletask5-0.2.8}/django_simpletask5/core/publisher.py

@@ -39,7 +39,7 @@ def create_and_publish(task, trigger_event, extra_context=None):
     queue_name = task.get_queue_name(event=trigger_event)
 
     context = {
-        'task_id': str(task.task_id),
+        'task_id': _task_identity(task),
         'trigger_event': trigger_event,
         'data': _model_to_dict(task),
     }
@@ -49,7 +49,7 @@ def create_and_publish(task, trigger_event, extra_context=None):
     serialized_context = _serialize_context(context)
 
     execution = TaskExecution(
-        task_id=task.task_id,
+        task_id=_task_identity(task),
         task_model=task._meta.label,
         trigger_event=trigger_event,
         executor_class=executor_class_path,
@@ -74,7 +74,7 @@ def bulk_create_and_publish(tasks, trigger_event, extra_context=None):
         queue_name = task.get_queue_name(event=trigger_event)
 
         context = {
-            'task_id': str(task.task_id),
+            'task_id': _task_identity(task),
             'trigger_event': trigger_event,
             'data': _model_to_dict(task),
         }
@@ -84,7 +84,7 @@ def bulk_create_and_publish(tasks, trigger_event, extra_context=None):
         serialized_context = _serialize_context(context)
 
         execution = TaskExecution(
-            task_id=task.task_id,
+            task_id=_task_identity(task),
             task_model=task._meta.label,
             trigger_event=trigger_event,
             executor_class=executor_class_path,
@@ -165,6 +165,14 @@ def _serialize_value(value):
     return str(value)
 
 
+def _task_identity(instance):
+    """返回业务对象唯一标识字符串，用作 TaskExecution.task_id。
+
+    业务实例唯一性由其真实主键承载，而非额外的 task_id UUID。
+    """
+    return str(instance.pk) if instance.pk is not None else None
+
+
 def _model_to_dict(instance):
     data = {}
     for field in instance._meta.fields: