feat: macOS 自动检测微信数据目录 + 部署排错文档 (#80)
* feat: macOS 自动检测微信数据目录 新增 _auto_detect_db_dir_macos() 函数，搜索 ~/Library/Containers/ 下的 xwechat_files/*/db_storage 目录，按 mtime 排序优先最近活跃账号。 同时改进检测失败时的提示信息，macOS 给出正确的默认路径格式。 * docs: 记录 macOS 部署常见问题及修复方案 记录 task_for_pid failed:5、自动检测 db_dir 失败、 PEP 668 pip 安装拒绝三个问题的现象、原因和解决方法， 附完整 macOS 部署流程和修复状态汇总。 * docs: 增强 README macOS 部署说明和常见问题 - 安装依赖部分补充 PEP 668 虚拟环境解决方案 - 修正 macOS db_dir 路径为正确的 xwechat_files 格式 - 快速开始增加重签名前退出微信的步骤 - 新增 macOS 密钥扫描常见问题排错章节 - task_for_pid failed:5 的原因和完整排查步骤 - 自动检测数据目录失败的临时解决方案 --------- Co-authored-by: drulu <drulu@tencent.com>
This commit is contained in:
Dru / Lu Rui
93
README.md
93
README.md
@@ -50,9 +50,9 @@ macOS：
|
||||
- macOS 10.15+（Apple Silicon / Intel 均可）
|
||||
- 微信 4.x（macOS 版）
|
||||
- Xcode Command Line Tools：`xcode-select --install`
|
||||
- 需要对 `/Applications/WeChat.app` 做 ad-hoc 重签名（允许进程内存读取）
|
||||
- 需要对 `/Applications/WeChat.app` 做 ad-hoc 重签名（允许进程内存读取），重签名前须先退出微信
|
||||
- 需要 root 权限运行扫描器
|
||||
- `db_dir` 默认类似 `~/Library/Containers/com.tencent.xinWeChat/Data/Library/Application Support/com.tencent.xinWeChat/2.0b4.0.9/<hash>/Message`
|
||||
- `db_dir` 默认类似 `~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage`
|
||||
|
||||
### 安装依赖
|
||||
|
||||
@@ -60,7 +60,35 @@ macOS：
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Windows 如果遇到权限不足或全局环境不可写，可以改用：
|
||||
<details>
|
||||
<summary>⚠️ 安装失败？点击展开常见问题</summary>
|
||||
|
||||
**问题：`error: externally-managed-environment` (PEP 668)**
|
||||
|
||||
Homebrew Python (3.12+) 和部分 Linux 发行版禁止 `pip install` 直接写入系统 Python 环境，会报此错误。
|
||||
|
||||
**解决：使用虚拟环境**
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate # 激活虚拟环境
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 后续运行脚本时使用 .venv 中的 Python
|
||||
.venv/bin/python3 main.py
|
||||
.venv/bin/python3 decrypt_db.py
|
||||
```
|
||||
|
||||
或使用 Makefile（已配置 `.venv/bin/python3`）：
|
||||
|
||||
```bash
|
||||
make decrypt # 等价于 .venv/bin/python3 main.py decrypt
|
||||
make web # 等价于 .venv/bin/python3 main.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Windows 权限不足或全局环境不可写**，可以改用：
|
||||
|
||||
```bash
|
||||
py -m pip install --user -r requirements.txt
|
||||
@@ -68,6 +96,8 @@ py -m pip install --user -r requirements.txt
|
||||
|
||||
如果需要读取受保护的进程或把依赖安装到系统 Python，也可能需要以管理员身份打开终端。
|
||||
|
||||
</details>
|
||||
|
||||
### 快速开始
|
||||
|
||||
Windows：
|
||||
@@ -86,10 +116,11 @@ python3 main.py decrypt
|
||||
macOS（密钥扫描用 C 版本，见下文 [macOS 数据库密钥扫描](#macos-数据库密钥扫描-wechat-4x) 章节）：
|
||||
|
||||
```bash
|
||||
# 1. 重新签名（首次及微信升级后各一次）
|
||||
# 1. 退出微信，重新签名（首次及微信升级后各一次）
|
||||
killall WeChat
|
||||
sudo codesign --force --deep --sign - /Applications/WeChat.app
|
||||
|
||||
# 2. 编译并运行扫描器
|
||||
# 2. 重新打开微信并登录，然后编译并运行扫描器
|
||||
cc -O2 -o find_all_keys_macos find_all_keys_macos.c -framework Foundation
|
||||
sudo ./find_all_keys_macos
|
||||
|
||||
@@ -124,14 +155,14 @@ macOS 版 `config.json` 示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"db_dir": "/Users/yourname/Library/Containers/com.tencent.xinWeChat/Data/Library/Application Support/com.tencent.xinWeChat/2.0b4.0.9/<hash>/Message",
|
||||
"db_dir": "/Users/yourname/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/your_wxid/db_storage",
|
||||
"keys_file": "all_keys.json",
|
||||
"decrypted_dir": "decrypted",
|
||||
"wechat_process": "WeChat"
|
||||
}
|
||||
```
|
||||
|
||||
`db_dir` 路径：Windows 可在微信设置 → 文件管理中找到；Linux 默认在 `~/Documents/xwechat_files/<wxid>/db_storage`；macOS 在 `~/Library/Containers/com.tencent.xinWeChat/.../Message`（`<hash>` 是微信随机生成的账号目录）。
|
||||
`db_dir` 路径：Windows 可在微信设置 → 文件管理中找到；Linux 默认在 `~/Documents/xwechat_files/<wxid>/db_storage`；macOS 在 `~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage`（程序已支持自动检测）。
|
||||
|
||||
### Web UI 说明
|
||||
|
||||
@@ -350,6 +381,54 @@ sudo ./find_all_keys_macos <pid>
|
||||
python3 decrypt_db.py
|
||||
```
|
||||
|
||||
### 常见问题
|
||||
|
||||
#### `task_for_pid failed: 5`
|
||||
|
||||
以 root 运行扫描器后仍报此错，说明微信进程的 Hardened Runtime 签名未移除。
|
||||
|
||||
**原因**：macOS 会阻止对带有 Hardened Runtime 标志的进程进行内存读取，即使以 root 身份运行也不行。微信默认签名包含此标志。
|
||||
|
||||
**排查步骤**：
|
||||
|
||||
```bash
|
||||
# 1. 检查微信当前签名（如包含 flags=0x10000(runtime) 则需要重签名）
|
||||
codesign -dvvv /Applications/WeChat.app 2>&1 | grep flags
|
||||
|
||||
# 2. 必须先退出微信再重签名（微信在运行时重签名不会生效）
|
||||
killall WeChat
|
||||
sudo codesign --force --deep --sign - /Applications/WeChat.app
|
||||
|
||||
# 3. 验证签名已变更（应显示 flags=0x2，不再有 runtime 标志）
|
||||
codesign -dvvv /Applications/WeChat.app 2>&1 | grep flags
|
||||
|
||||
# 4. 重新打开微信并登录，然后运行扫描器
|
||||
sudo ./find_all_keys_macos
|
||||
```
|
||||
|
||||
**注意**：
|
||||
- 微信每次更新后签名会恢复原始状态，需重新执行上述步骤
|
||||
- `--deep` 参数确保签名覆盖 App Bundle 内所有嵌套二进制文件
|
||||
- 重签名后必须重启微信，否则进程仍使用旧的签名凭证
|
||||
|
||||
#### 未能自动检测微信数据目录
|
||||
|
||||
程序已支持 macOS 自动检测微信数据目录。如果检测失败，手动查找并配置：
|
||||
|
||||
```bash
|
||||
# 搜索 db_storage 目录
|
||||
find ~/Library/Containers/com.tencent.xinWeChat -type d -name "db_storage" 2>/dev/null
|
||||
```
|
||||
|
||||
如有多个账号（多个 `db_storage` 目录），按修改时间判断当前活跃账号：
|
||||
|
||||
```bash
|
||||
stat -f "%m %N" /path/to/account1/db_storage /path/to/account2/db_storage
|
||||
# 数值更大 = 最近活跃
|
||||
```
|
||||
|
||||
然后编辑 `config.json`，将找到的路径填入 `db_dir` 字段。
|
||||
|
||||
## 免责声明
|
||||
|
||||
本工具仅用于学习和研究目的，用于解密**自己的**微信数据。请遵守相关法律法规，不要用于未经授权的数据访问。
|
||||
|
||||
38
config.py
38
config.py
@@ -162,11 +162,47 @@ def _auto_detect_db_dir_linux():
|
||||
return _choose_candidate(candidates)
|
||||
|
||||
|
||||
def _auto_detect_db_dir_macos():
|
||||
"""自动检测 macOS 微信 db_storage 路径。
|
||||
|
||||
微信 4.x 数据目录位于 ~/Library/Containers/com.tencent.xinWeChat/.../xwechat_files/<wxid>/db_storage，
|
||||
路径中包含随机 hash，需要搜索定位。
|
||||
"""
|
||||
base = os.path.expanduser(
|
||||
"~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files"
|
||||
)
|
||||
if not os.path.isdir(base):
|
||||
return None
|
||||
|
||||
seen = set()
|
||||
candidates = []
|
||||
pattern = os.path.join(base, "*", "db_storage")
|
||||
for match in glob.glob(pattern):
|
||||
normalized = os.path.normcase(os.path.normpath(match))
|
||||
if os.path.isdir(match) and normalized not in seen:
|
||||
seen.add(normalized)
|
||||
candidates.append(match)
|
||||
|
||||
# 优先使用最近活跃账号：按 message 目录 mtime 降序
|
||||
def _mtime(path):
|
||||
msg_dir = os.path.join(path, "message")
|
||||
target = msg_dir if os.path.isdir(msg_dir) else path
|
||||
try:
|
||||
return os.path.getmtime(target)
|
||||
except OSError:
|
||||
return 0
|
||||
|
||||
candidates.sort(key=_mtime, reverse=True)
|
||||
return _choose_candidate(candidates)
|
||||
|
||||
|
||||
def auto_detect_db_dir():
|
||||
if _SYSTEM == "windows":
|
||||
return _auto_detect_db_dir_windows()
|
||||
if _SYSTEM == "linux":
|
||||
return _auto_detect_db_dir_linux()
|
||||
if _SYSTEM == "darwin":
|
||||
return _auto_detect_db_dir_macos()
|
||||
return None
|
||||
|
||||
|
||||
@@ -197,6 +233,8 @@ def load_config():
|
||||
print(f" 请手动编辑 {CONFIG_FILE} 中的 db_dir 字段")
|
||||
if _SYSTEM == "linux":
|
||||
print(" Linux 默认路径类似: ~/Documents/xwechat_files/<wxid>/db_storage")
|
||||
elif _SYSTEM == "darwin":
|
||||
print(" macOS 默认路径类似: ~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage")
|
||||
else:
|
||||
print(f" 路径可在 微信设置 → 文件管理 中找到")
|
||||
sys.exit(1)
|
||||
|
||||
259
docs/bugfix/mac-deploy-issues.md
Normal file
259
docs/bugfix/mac-deploy-issues.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# macOS 部署问题记录
|
||||
|
||||
> 环境：macOS (Apple Silicon / Intel), 微信 4.x, Python 3.14 (Homebrew)
|
||||
> 日期：2026-05-12
|
||||
|
||||
---
|
||||
|
||||
## 问题 1: `task_for_pid failed: 5` — 微信进程内存读取被拒绝
|
||||
|
||||
### 现象
|
||||
|
||||
```bash
|
||||
sudo ./find_all_keys_macos
|
||||
# 输出:
|
||||
# WeChat PID: 12276
|
||||
# task_for_pid failed: 5
|
||||
# Make sure: (1) running as root, (2) WeChat is ad-hoc signed
|
||||
```
|
||||
|
||||
以 root 运行扫描器，但仍无法读取微信进程内存。
|
||||
|
||||
### 原因
|
||||
|
||||
微信 App 使用了 Apple **Hardened Runtime**（`flags=0x10000(runtime)`），即使以 root 身份运行，macOS 也会阻止对带有此标志的进程进行 `task_for_pid` 调用。
|
||||
|
||||
验证方法：
|
||||
|
||||
```bash
|
||||
codesign -dvvv /Applications/WeChat.app 2>&1 | grep flags
|
||||
# 输出: flags=0x10000(runtime) ← 问题所在
|
||||
```
|
||||
|
||||
### 修复
|
||||
|
||||
1. **退出微信**（重签名需要进程不在运行）
|
||||
|
||||
```bash
|
||||
killall WeChat
|
||||
```
|
||||
|
||||
2. **执行 ad-hoc 重签名**（移除 Hardened Runtime 标志）
|
||||
|
||||
```bash
|
||||
sudo codesign --force --deep --sign - /Applications/WeChat.app
|
||||
```
|
||||
|
||||
3. **验证签名已变更**
|
||||
|
||||
```bash
|
||||
codesign -dvvv /Applications/WeChat.app 2>&1 | grep -E "flags|Authority"
|
||||
# 正确输出应类似: flags=0x2
|
||||
# 不应再出现 flags=0x10000(runtime) 或 Authority=Developer ID
|
||||
```
|
||||
|
||||
4. **重新打开微信并登录**，再运行扫描器
|
||||
|
||||
```bash
|
||||
sudo ./find_all_keys_macos
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 微信**每次更新**后签名会恢复为原始状态，需重新执行上述步骤
|
||||
- `--deep` 参数确保签名覆盖 App Bundle 内所有嵌套二进制文件
|
||||
- 重签名后必须重启微信，否则进程仍使用旧的签名凭证
|
||||
|
||||
---
|
||||
|
||||
## 问题 2: 自动检测微信数据目录失败
|
||||
|
||||
### 现象
|
||||
|
||||
```bash
|
||||
.venv/bin/python3 decrypt_db.py
|
||||
# 输出:
|
||||
# [!] 未能自动检测微信数据目录
|
||||
# 请手动编辑 config.json 中的 db_dir 字段
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```bash
|
||||
.venv/bin/python3 main.py
|
||||
# 输出:
|
||||
# [!] 未能自动检测微信数据目录
|
||||
```
|
||||
|
||||
### 原因
|
||||
|
||||
`config.py` 中的 `auto_detect_db_dir()` 函数仅实现了 Windows 和 Linux 的自动检测逻辑，macOS 分支直接返回 `None`：
|
||||
|
||||
```python
|
||||
def auto_detect_db_dir():
|
||||
if _SYSTEM == "windows":
|
||||
return _auto_detect_db_dir_windows()
|
||||
if _SYSTEM == "linux":
|
||||
return _auto_detect_db_dir_linux()
|
||||
return None # ← macOS 未实现
|
||||
```
|
||||
|
||||
macOS 微信数据目录位于 `~/Library/Containers/com.tencent.xinWeChat/...`，路径中包含随机 hash，需要搜索才能定位。
|
||||
|
||||
### 修复
|
||||
|
||||
已在 `config.py` 中实现 macOS 自动检测，同时改进了检测失败时的提示信息。
|
||||
|
||||
#### 代码改动
|
||||
|
||||
1. **新增 `_auto_detect_db_dir_macos()` 函数**（`config.py`）
|
||||
|
||||
```python
|
||||
def _auto_detect_db_dir_macos():
|
||||
"""自动检测 macOS 微信 db_storage 路径。"""
|
||||
base = os.path.expanduser(
|
||||
"~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files"
|
||||
)
|
||||
if not os.path.isdir(base):
|
||||
return None
|
||||
|
||||
seen = set()
|
||||
candidates = []
|
||||
pattern = os.path.join(base, "*", "db_storage")
|
||||
for match in glob.glob(pattern):
|
||||
normalized = os.path.normcase(os.path.normpath(match))
|
||||
if os.path.isdir(match) and normalized not in seen:
|
||||
seen.add(normalized)
|
||||
candidates.append(match)
|
||||
|
||||
# 优先使用最近活跃账号：按 message 目录 mtime 降序
|
||||
def _mtime(path):
|
||||
msg_dir = os.path.join(path, "message")
|
||||
target = msg_dir if os.path.isdir(msg_dir) else path
|
||||
try:
|
||||
return os.path.getmtime(target)
|
||||
except OSError:
|
||||
return 0
|
||||
|
||||
candidates.sort(key=_mtime, reverse=True)
|
||||
return _choose_candidate(candidates)
|
||||
```
|
||||
|
||||
2. **在 `auto_detect_db_dir()` 中接入 macOS 分支**
|
||||
|
||||
```python
|
||||
def auto_detect_db_dir():
|
||||
if _SYSTEM == "windows":
|
||||
return _auto_detect_db_dir_windows()
|
||||
if _SYSTEM == "linux":
|
||||
return _auto_detect_db_dir_linux()
|
||||
if _SYSTEM == "darwin":
|
||||
return _auto_detect_db_dir_macos() # ← 新增
|
||||
return None
|
||||
```
|
||||
|
||||
3. **改进检测失败时的提示**：macOS 提示正确的默认路径格式
|
||||
|
||||
```
|
||||
[!] 未能自动检测微信数据目录
|
||||
请手动编辑 config.json 中的 db_dir 字段
|
||||
macOS 默认路径类似: ~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage
|
||||
```
|
||||
|
||||
#### 临时解决方案（如自动检测仍失败）
|
||||
|
||||
手动查找并配置 `db_dir`：
|
||||
|
||||
```bash
|
||||
find ~/Library/Containers/com.tencent.xinWeChat -type d -name "db_storage" 2>/dev/null
|
||||
```
|
||||
|
||||
如有多个账号，按修改时间判断当前活跃账号：
|
||||
|
||||
```bash
|
||||
stat -f "%m %N" /path/to/account1/db_storage /path/to/account2/db_storage
|
||||
```
|
||||
|
||||
然后编辑 `config.json` 填入路径。
|
||||
|
||||
---
|
||||
|
||||
## 问题 3: Homebrew Python 拒绝全局 pip 安装
|
||||
|
||||
### 现象
|
||||
|
||||
```bash
|
||||
pip3 install -r requirements.txt
|
||||
# 报错: error: externally-managed-environment
|
||||
# 提示: PEP 668 — 不能直接向系统 Python 安装包
|
||||
```
|
||||
|
||||
### 原因
|
||||
|
||||
Homebrew 的 Python 3.14 遵循 [PEP 668](https://peps.python.org/pep-0668/)，禁止 `pip install` 直接写入系统 Python 环境，防止破坏包管理器的依赖关系。
|
||||
|
||||
### 修复
|
||||
|
||||
使用虚拟环境：
|
||||
|
||||
```bash
|
||||
cd /Users/drulu/Documents/GitHub/wechat-decrypt
|
||||
|
||||
# 创建虚拟环境
|
||||
python3 -m venv .venv
|
||||
|
||||
# 激活并安装依赖
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 后续运行脚本时使用 .venv 中的 Python
|
||||
.venv/bin/python3 main.py
|
||||
.venv/bin/python3 decrypt_db.py
|
||||
```
|
||||
|
||||
或使用 Makefile（已配置 `.venv/bin/python3`）：
|
||||
|
||||
```bash
|
||||
make decrypt # 等价于 .venv/bin/python3 main.py decrypt
|
||||
make web # 等价于 .venv/bin/python3 main.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完整部署流程（macOS）
|
||||
|
||||
将以上修复整合为正确的部署顺序：
|
||||
|
||||
```bash
|
||||
# 1. 安装 Xcode CLI 工具
|
||||
xcode-select --install
|
||||
|
||||
# 2. 创建虚拟环境并安装依赖
|
||||
cd ~/Documents/GitHub/wechat-decrypt
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 3. 退出微信 → 重签名 → 重启微信
|
||||
killall WeChat
|
||||
sudo codesign --force --deep --sign - /Applications/WeChat.app
|
||||
# 然后手动打开微信并登录
|
||||
|
||||
# 4. 编译 C 扫描器
|
||||
cc -O2 -o find_all_keys_macos find_all_keys_macos.c -framework Foundation
|
||||
|
||||
# 5. 提取密钥
|
||||
sudo ./find_all_keys_macos
|
||||
|
||||
# 6. 启动 Web UI（db_dir 已自动检测，无需手动配置）
|
||||
.venv/bin/python3 main.py # 启动 Web UI → http://localhost:5678
|
||||
.venv/bin/python3 decrypt_db.py # 或仅全量解密
|
||||
```
|
||||
|
||||
## 修复状态汇总
|
||||
|
||||
| 问题 | 代码修复 | 说明 |
|
||||
|------|---------|------|
|
||||
| `task_for_pid failed: 5` | ❌ 无法代码修复 | 系统级限制，需手动重签名微信 |
|
||||
| 自动检测 `db_dir` 失败 | ✅ 已修复 | `config.py` 新增 `_auto_detect_db_dir_macos()`，自动搜索 `~/Library/Containers/` |
|
||||
| Homebrew Python 拒绝 pip 安装 | ❌ 无法代码修复 | 环境限制，需使用虚拟环境 |
|
||||
Reference in New Issue
Block a user