从GitHub仓库更新应用遇KeyError与JSON反序列化错误求助

DevOps 小满

2026-7-8

问题根源

你的核心问题是客户端请求的是GitHub的Blob页面URL，而非原始元数据文件的URL。从日志里的请求地址https://github.com/username/updater/blob/main/metadata/timestamp.json可以看出，这个URL返回的是GitHub的网页（HTML格式），不是纯JSON元数据文件，所以TUF解析时找不到signed字段，触发反序列化错误。

解决方案

替换元数据文件的基础URL：将客户端配置中的仓库地址替换为GitHub原始文件服务地址，格式为：
```
https://raw.githubusercontent.com/<用户名>/<仓库名>/<分支名>/<元数据目录>/
```
比如把原来的https://github.com/username/updater/blob/main/metadata/改成https://raw.githubusercontent.com/username/updater/main/metadata/，确保下载的是纯JSON内容。
核对元文件路径与版本：日志中出现2.root.json返回404，需确认GitHub仓库中存在对应版本的root文件，且路径与客户端配置一致，避免因文件缺失或路径错误导致的加载失败。
无需额外签名操作：本地生成并签名好的元数据文件，上传到GitHub后不需要再做特殊签名，TUF仅验证本地签名后的文件内容，GitHub仅作为托管载体。

原报错信息

Traceback (most recent call last):
  File "main.py", line 12, in <module>
  File "myapp\__init__.py", line 75, in main
  File "myapp\__init__.py", line 36, in update
  File "tufup\client.py", line 154, in check_for_updates
  File "tuf\ngclient\updater.py", line 133, in refresh
  File "tuf\ngclient\updater.py", line 346, in _load_timestamp
  File "tuf\ngclient\_internal\trusted_metadata_set.py", line 211, in update_timestamp
  File "tuf\api\metadata.py", line 263, in from_bytes
  File "tuf\api\serialization\json.py", line 40, in deserialize
tuf.api.serialization.DeserializationError: Failed to deserialize JSON
[11720] Failed to execute script 'main' due to unhandled exception!
PS C:\Users\username\AppData\Local\Programs\my_app> .\main.exe
INFO:__main__:my_app 1.0
DEBUG:tuf.ngclient._internal.trusted_metadata_set:Updating initial trusted root
DEBUG:tuf.ngclient._internal.trusted_metadata_set:Loaded trusted root v1
DEBUG:tuf.ngclient.fetcher:Downloading: https://github.com/username/updater/blob/main/metadata/2.root.json
DEBUG:tuf.ngclient._internal.requests_fetcher:Made new session ('https', 'github.com')
DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): github.com:443
DEBUG:urllib3.connectionpool:https://github.com:443 "GET /username/updater/blob/main/metadata/2.root.json HTTP/1.1" 404 None
DEBUG:tuf.ngclient._internal.trusted_metadata_set:Updated timestamp v3
DEBUG:tuf.ngclient.fetcher:Downloading: https://github.com/username/updater/blob/main/metadata/timestamp.json
DEBUG:tuf.ngclient._internal.requests_fetcher:Reusing session ('https', 'github.com')
DEBUG:urllib3.connectionpool:Resetting dropped connection: github.com
DEBUG:urllib3.connectionpool:https://github.com:443 "GET /username/updater/blob/main/metadata/timestamp.json HTTP/1.1" 200 2321
DEBUG:tuf.ngclient.fetcher:Downloaded 6205 out of 16384 bytes
Traceback (most recent call last):
  File "tuf\api\serialization\json.py", line 37, in deserialize
  File "tuf\api\metadata.py", line 172, in from_dict
KeyError: 'signed'

内容的提问来源于stack exchange，提问作者TheSlant