wechat-decrypt-toolkit

WeChat 数据库解密工具包：多实例友好，密钥按 wxid 隔离存储。

核心设计

多实例隔离：每个微信实例（wxid）有独立的 .keys 文件：

~/.wechat-decrypt-toolkit/keys/
├── wxid_xxx.keys    # 实例 A
└── wxid_yyy.keys    # 实例 B

工作流：

1. 初始化：python cli.py init --pid <PID> --wxid wxid_xxx
           → 扫描所有 key → 保存到 ~/.wechat-decrypt-toolkit/keys/wxid_xxx.keys

2. 启动服务：python cli.py serve --db-path /path/to/Contact.db --port 58081
           → 从路径提取 wxid → 检查 .keys → 启动 HTTP 服务

3. 多开：每个实例不同端口/路径
           实例A → --port 58081
           实例B → --port 58082

安装

# 自动创建虚拟环境 + 编译扫描器
./setup.sh

注：macOS 需要虚拟环境来安装 pycryptodome。setup.sh 会自动处理。

快速开始

# 查看所有实例
python cli.py instances

# 初始化实例（首次必须）
python cli.py init --pid 12345 --wxid wxid_xxx

# 启动 HTTP 服务
python cli.py serve \
  --db-path ~/Library/Containers/.../xwechat_files/wxid_xxx/db_storage/Contact/Contact.db

CLI 子命令

命令	说明
instances	列出所有 WeChat 实例 + keys 状态
init	初始化：扫描并保存密钥到 ~/.wechat-decrypt-toolkit/keys/{wxid}.keys
scan	全量扫描（兼容旧版）
decrypt	解密指定 DB
verify	验证 DB 结构
serve	启动 HTTP 服务（多实例 namespaced）
launch	一键启动（旧版兼容）

多实例自动同步（推荐）

sync_instances.py — 一键发现所有 WeChat 实例、自动解析 wxid、智能同步 keys：

python3 sync_instances.py               # 查看状态
python3 sync_instances.py --export     # 自动导出缺失 keys
python3 sync_instances.py --watch      # 持续监控，新实例自动处理

详细文档：docs/SYNC_INSTANCES.md

HTTP API（多实例 namespaced）

# 健康检查
GET /health

# 查询单个联系人（按 wxid 命名空间）
GET /<wxid>/contact?wxid=xxx

# 联系人列表
GET /<wxid>/contacts?page=1&limit=50

# 搜索
GET /<wxid>/contacts/search?q=关键词

# keys 状态
GET /<wxid>/keys/status

# 重新扫描密钥
POST /<wxid>/keys/refresh

Python API

from wechat_db import (
    # 密钥管理（多实例）
    export_keys,       # 初始化：scan → 保存到 ~/.wechat-decrypt-toolkit/keys/{wxid}.keys
    load_keys,         # 加载指定 wxid 的密钥
    has_keys,          # 检查是否已初始化
    list_instances,     # 列出所有实例
    extract_wxid,      # 从路径提取 wxid

    # 扫描
    scan_keys,         # 全量扫描（兼容旧版）
    scan_targeted,     # 定向扫描：只找指定 DB 的 key

    # 解密/验证
    decrypt_database,
    verify_contact_schema,
    ContactService,
)

# 初始化实例
export_keys(pid=12345, wxid="wxid_xxx")

# 查询
store = load_keys("wxid_xxx")
key = store.get("Contact/Contact.db")

# HTTP 服务
ContactService("/path/to/decrypted.db").load()