[Bug] 社区版源码部署时，Celery 自定义序列化器默认密钥是 UUID 对象，导致所有异步任务无法投递

オープン 初心者向け
  • 何か問題がありますか？
#7,780 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
2/5
見積もり時間
1〜3時間
初心者へのやさしさ
76/100
issue の種類
バグ
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
python
領域
backend, distributed-systems

調査の方向性

apps/ops/celery/hmac_signed_serializer.py から始めて、secure_dumps が .encode() を呼び出す前に _local_secret_key がどのように選ばれるかを追ってください。issue の単独スクリプトを使って失敗を再現し、このシリアライザーに関する近くのテストや起動時チェックを確認してください。デフォルトのキーが文字列として機能し、環境変数を必要とせずにシリアライズが成功すれば完了です。

索引モデルが issue の本文から書いたものです。

説明

环境

  • MaxKB 版本：2.10.8（镜像）／ 源码 HEAD 2ac52b3（2026-11-09）仍在
  • 部署方式：Docker Engine（WSL2），从源码构建，未使用官方商用镜像（无 xpack）
  • Python 3.11，celery 5.5.3，uuid-utils 0.14.0
  • 相关文件：apps/ops/celery/hmac_signed_serializer.py

现象

文档上传成功、记录能创建，但永远停在「待处理 / 0 段落」，后台不执行任何向量化任务。
前端无任何报错，日志中仅有一行被吞掉的 AttributeError。

排查后确认：所有 Celery 任务都无法投递（不只是文档解析）。

根因

apps/ops/celery/hmac_signed_serializer.py:

import uuid_utils.compat as uuid
...
_local_secret_key = os.environ.get(
    'MAXKB_HMAC_SIGNED_SERIALIZER_SECRET_KEY',
    os.getenv('MAXKB_SECRET_KEY', uuid.uuid7())   # ← 默认值是 UUID 对象，不是 str
)
...
def secure_dumps(obj):
    data = pickle.dumps(obj)
    signature = hmac.new(_local_secret_key.encode(), data, hashlib.sha256).digest()
    #                        ^^^^^^^^ UUID 没有 encode() → AttributeError

uuid_utils.compat.uuid7() 的返回值是 uuid.UUID 对象（已实测，见下），没有 .encode() 方法。

日志里没有明显报错，是因为任务投递点被 try/except 包住，
异常只落一条 error 日志，文档状态停在「待处理」——用户侧看起来就是「卡住了」。

复现

不启动 Django / Celery / Redis，直接加载上面这个真实文件即可复现：

import sys, types, importlib.util
kombu = types.ModuleType('kombu'); ser = types.ModuleType('kombu.serialization')
ser.register = lambda *a, **k: None
kombu.serialization = ser
sys.modules['kombu'] = kombu; sys.modules['kombu.serialization'] = ser

spec = importlib.util.spec_from_file_location(
    's', 'apps/ops/celery/hmac_signed_serializer.py')
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
m.secure_dumps({'task': 'x'})

输出：

_local_secret_key : type='UUID'  value=UUID('80d34868-8213-47e9-b353-e0fadd316c1c')
AttributeError: 'UUID' object has no attribute 'encode'
  File ".../apps/ops/celery/hmac_signed_serializer.py", line 17, in secure_dumps

设置环境变量后正常：

$ MAXKB_HMAC_SIGNED_SERIALIZER_SECRET_KEY=dev-secret python repro.py
_local_secret_key : type='str'  value='dev-local-secret'
secure_dumps(...) -> OK, 185 bytes

期望

  1. 默认值应转换为 str，例如：
_local_secret_key = os.environ.get(
    'MAXKB_HMAC_SIGNED_SERIALIZER_SECRET_KEY',
    os.getenv('MAXKB_SECRET_KEY') or str(uuid.uuid7())
)
  1. 建议在 ok/启动自检里显式校验 _local_secret_key 类型，或至少把它变成显式必填配置，
    避免不同部署方式（源码 / 官方镜像 / 含 xpack 的版本）表现不一致。

临时规避

-e MAXKB_HMAC_SIGNED_SERIALIZER_SECRET_KEY=<任意字符串>

补充说明（供维护者判断）

  • 该文件第 9–13 行有一个 from xpack import get_md5 的兜底：
    含 xpack 的版本会用它覆盖密钥，因此官方商用镜像可能不受影响；
    而源码构建 / 自行打镜像的社区用户会稳定踩到。
  • MAXKB_SECRET_KEY 在全仓库中除本文件外没有任何写入点（README 的 docker run
    也不传它），所以未设置环境变量是默认路径。
主要言語
Python
スター
23.1k
フォーク
3.2k
平均マージ
41分
マージ済み PR（30日）
480

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

1Panel-dev/MaxKB のほかの issue

1Panel-dev/MaxKB の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。