docs: 新增 sync_instances.py 使用文档
- docs/SYNC_INSTANCES.md: 完整使用文档（含命令行参数、输出示例、工作流程、FAQ、Python API） - README.md: 在 CLI 子命令后添加 sync_instances.py 推荐入口main
parent
3e7deb7a35
commit
11b3deb00a
12
README.md
12
README.md
|
|
@ -59,6 +59,18 @@ python cli.py serve \
|
|||
| `serve` | 启动 HTTP 服务（多实例 namespaced） |
|
||||
| `launch` | 一键启动（旧版兼容） |
|
||||
|
||||
## 多实例自动同步（推荐）
|
||||
|
||||
`sync_instances.py` — 一键发现所有 WeChat 实例、自动解析 wxid、智能同步 keys：
|
||||
|
||||
```bash
|
||||
python3 sync_instances.py # 查看状态
|
||||
python3 sync_instances.py --export # 自动导出缺失 keys
|
||||
python3 sync_instances.py --watch # 持续监控，新实例自动处理
|
||||
```
|
||||
|
||||
详细文档：[docs/SYNC_INSTANCES.md](docs/SYNC_INSTANCES.md)
|
||||
|
||||
## HTTP API（多实例 namespaced）
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -0,0 +1,194 @@
|
|||
# sync_instances.py 使用文档
|
||||
|
||||
> **功能**：WeChat 多实例自动发现 + wxid 解析 + keys 同步
|
||||
> **位置**：`wechat-decrypt-toolkit/sync_instances.py`
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 查看所有实例状态
|
||||
python3 sync_instances.py
|
||||
|
||||
# 自动导出缺失 keys
|
||||
python3 sync_instances.py --export
|
||||
|
||||
# JSON 输出（供脚本调用）
|
||||
python3 sync_instances.py --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 依赖
|
||||
|
||||
- Python 3.10+
|
||||
- 系统工具：`pgrep`、`lsof`（macOS）、`ps`（macOS）
|
||||
- 同一仓库：`wechat_db/` 模块
|
||||
- 扫描器：`bin/find_all_keys_macos`（C 编译二进制）
|
||||
|
||||
无需 frida，无需注入，无需关闭 SIP。
|
||||
|
||||
---
|
||||
|
||||
## 命令行参数
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| 无参数 | 扫描所有 WeChat 实例，显示 PID、wxid、keys 状态 |
|
||||
| `--export` | 为缺失 keys 的实例自动执行导出 |
|
||||
| `-f, --force` | 强制重新导出（覆盖已有 .keys 文件） |
|
||||
| `--watch` | 持续监控模式，新实例出现时自动导出 |
|
||||
| `--interval N` | watch 模式检测间隔（秒，默认 10） |
|
||||
| `--wxid <id>` | 只处理指定 wxid 的实例 |
|
||||
| `--json` | JSON 格式输出，适合脚本集成 |
|
||||
|
||||
---
|
||||
|
||||
## 输出示例
|
||||
|
||||
### 默认模式（人类可读）
|
||||
|
||||
```
|
||||
PID wxid keys 状态
|
||||
--------------------------------------------------------------
|
||||
85121 wxid_0368623686311 24 ✅ keys 已就绪 (24 个密钥)
|
||||
--------------------------------------------------------------
|
||||
共 1 个实例， 1 已就绪， 0 待导出
|
||||
```
|
||||
|
||||
### 缺失 keys
|
||||
|
||||
```
|
||||
PID wxid keys 状态
|
||||
--------------------------------------------------------------
|
||||
85121 wxid_0368623686311 0 ❌ keys 缺失
|
||||
--------------------------------------------------------------
|
||||
共 1 个实例， 0 已就绪， 1 待导出
|
||||
```
|
||||
|
||||
### watch 模式
|
||||
|
||||
```
|
||||
🔄 监控模式启动（间隔 10s）
|
||||
Ctrl+C 退出
|
||||
|
||||
[15:32:01] 🆕 新实例发现: {85121}
|
||||
[85121] → wxid_0368623686311 开始导出密钥...
|
||||
[85121] ✅ 导出完成，共 24 个密钥
|
||||
[15:33:45] 🔻 实例退出: {85121}
|
||||
^C
|
||||
👋 监控已停止
|
||||
```
|
||||
|
||||
### JSON 模式
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"pid": 85121,
|
||||
"wxid": "wxid_0368623686311",
|
||||
"wxid_raw": "wxid_0368623686311",
|
||||
"has_keys": true,
|
||||
"key_count": 24,
|
||||
"scanner_bin": ".../bin/find_all_keys_macos"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工作流程
|
||||
|
||||
```
|
||||
1. pgrep -x WeChat → 获取所有 WeChat PID 列表
|
||||
2. ps -o state → 过滤 Stopped(T) 状态进程（lsof 会阻塞）
|
||||
3. lsof -c WeChat + grep → 零开销获取 PID → wxid 映射
|
||||
（SIGPIPE trick：grep -m1 让 lsof 0.05s 内退出）
|
||||
4. ~/.wechat-decrypt-toolkit/keys/{wxid}.keys
|
||||
→ 检查 keys 缓存是否存在
|
||||
5. 若缺失 + --export → 调用 C 扫描器导出密钥
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 自动导出示例
|
||||
|
||||
```bash
|
||||
# 启动时自动检查并导出（一次性）
|
||||
python3 sync_instances.py --export
|
||||
|
||||
# 输出：
|
||||
# [85121] → wxid_0368623686311 开始导出密钥...
|
||||
# [85121] ✅ 导出完成，共 24 个密钥
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 退出码
|
||||
|
||||
| 退出码 | 含义 |
|
||||
|--------|------|
|
||||
| 0 | 正常执行（无论是否有实例） |
|
||||
| 1 | 指定 `--wxid` 但未找到对应运行实例 |
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: lsof 超时/卡住
|
||||
|
||||
A: 检查是否有 WeChat 进程处于 `T`（Stopped/Traced）状态：
|
||||
|
||||
```bash
|
||||
ps aux | grep WeChat | grep -v grep | awk '{print $2, $8}'
|
||||
```
|
||||
|
||||
若发现 `T` 状态，先恢复：
|
||||
|
||||
```bash
|
||||
kill -CONT <PID>
|
||||
```
|
||||
|
||||
`get_wechat_pids()` 会自动过滤 T 状态进程。
|
||||
|
||||
### Q: 所有实例都显示 `?（未登录?）`
|
||||
|
||||
A: lsof 在 `grep -m1` 时可能找到错误的 wxid（其他进程的路径）。检查实际路径：
|
||||
|
||||
```bash
|
||||
lsof -c WeChat 2>/dev/null | grep 'wxid_'
|
||||
```
|
||||
|
||||
### Q: 想只刷新某个 wxid 的 keys
|
||||
|
||||
```bash
|
||||
python3 sync_instances.py --wxid wxid_0368623686311 --export --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Python API
|
||||
|
||||
```python
|
||||
from sync_instances import (
|
||||
discover_instances,
|
||||
export_instance,
|
||||
export_all_missing,
|
||||
WeChatInstance,
|
||||
)
|
||||
|
||||
# 发现所有实例
|
||||
instances = discover_instances()
|
||||
for inst in instances:
|
||||
print(f"PID={inst.pid}, wxid={inst.wxid}, has_keys={inst.has_keys}")
|
||||
|
||||
# 导出指定实例
|
||||
inst = instances[0]
|
||||
export_instance(inst, force=False)
|
||||
|
||||
# 导出所有缺失的
|
||||
results = export_all_missing(force=False)
|
||||
print(results)
|
||||
# {'exported': [...], 'skipped': [...], 'failed': [...]}
|
||||
```
|
||||
Loading…
Reference in New Issue