# 先读我：在另一台电脑部署

这是移动应用相似度工作台 v2.2.0 的完整工程交付版。请把整个文件夹解压到接收方自己的电脑，例如 `~/Applications/mobile-similarity-service`，不要只复制其中几个文件，也不要直接在压缩包内运行。

包内包含前后端完整源码、可直接使用的前端构建、匹配规则、安装/启动/停止脚本、锁定依赖、深度引擎安装器、Docker 配置、测试夹具、示例报告与验证记录。**不含原使用者的 APK/IPA、数据库、报告库、日志、备份、账户配置或虚拟环境。** `examples/` 与 `tests/ios-fixtures/` 中是明确标注的工程测试示例。

这是完整源码与可联网安装的部署包，**不是离线软件镜像**。首次安装需要联网取得 Python 依赖；开启深度模式还会下载约 840 MB 的官方工具归档，并核验固定 SHA-256。

## 一、先确认电脑类型

| 接收方环境 | 此工程的部署范围 |
|---|---|
| macOS / Apple Silicon（M 系列） | 本次已验证的完整方案：Android + iOS 标准分析，以及 iOS 深度比对 |
| Intel Mac / Linux | 基础 Python 服务可能可运行，但未在本次验收；随附深度安装器不适用 |
| Windows | 不提供 Windows 原生启动脚本；后端使用 Unix 进程与文件锁机制，不能直接双击 Mac 脚本运行 |
| Docker / Docker Desktop | 随附双端标准分析配置，未在本次测试；不包含 macOS 深度工具链 |

iOS“深度”指同架构可读主程序的 Ghidra/BinDiff 函数与控制流比对；Android 标准模式已包含 DEX 函数实现、一层直接调用上下文、分项阈值及结论；ELF/native 函数级深度匹配未实现。加密 IPA 不会被自动解密。

## 二、M 系列 Mac 的首次安装

### 1. 安装 uv

如果终端中 `uv --version` 已正常返回版本，可以跳过。否则在终端按 [uv 官方安装说明](https://docs.astral.sh/uv/getting-started/installation/) 安装。以下固定为工程原始部署使用的版本：

```sh
curl -LsSf https://astral.sh/uv/0.11.19/install.sh | sh
```

关闭并重新打开终端。工程的安装入口也会查找 uv 默认的 `~/.local/bin/uv`，不要求手工修改 PATH。

### 2. 安装基础服务

双击 `安装.command`。它用锁定的依赖清单创建这台电脑自己的 Python 3.12 环境。项目附带已经构建的网页，因此这一步不需要 Node.js。

如果解压工具没有保留脚本执行权限，可在终端进入解压目录后运行：

```sh
zsh 安装.command
```

### 3. 安装深度引擎

如果只需要双端标准分析，可先使用基础服务。需要 iOS 深度比对时，先准备 Apple Command Line Tools：

```sh
xcode-select -p
```

如提示未安装，执行 `xcode-select --install` 并完成系统安装，然后双击 `安装深度引擎.command`。安装器会：

1. 下载并核验 Ghidra、BinDiff、JDK、Protobuf 编译器。
2. 在工程 `.tools/` 内安装工具，针对本机编译 BinExport 和 ARM64 反编译组件。
3. 使用随附自建 IPA 做真实端到端自检；只有自检成功才显示深度引擎“已就绪”。

无需预先安装系统 Java，不会执行 BinDiff `.pkg` 内的系统安装脚本。无需下载完整 Xcode 即可使用已附带的夹具；只有自行重建 iOS 夹具才需要带 iOS SDK 的完整 Xcode。

安装和保存样本需要磁盘空间；建议先预留至少 10 GB，长期保存安装包所需空间另计。默认分析进程内存上限 4 GB、方法容量 50 万、指令容量 1,000 万，可在规则中调整。Android 的方法计数包含 SDK，并跨 DEX / split 累计。

### 4. 启动与检查

双击 `启动.command`，浏览器打开 [本机工作台](http://127.0.0.1:8765/)。

- “系统状态”中 Android、iOS 应为“已就绪”。
- 安装并自检深度工具后，Ghidra / BinDiff 也应为“已就绪”。
- 新安装的样本库为空；不会带上原电脑的检测记录。
- 使用随附 `tests/ios-fixtures/baseline.ipa` 作为基准、`renamed.ipa` 作为待测，可验证上传和报告流程；这些是工程夹具，并非真实商业应用。

日后正常打开只需双击 `启动.command`；停止请双击 `停止.command`。关闭网页不会停止后台任务，电脑重启后需要再次启动服务。

## 三、常见问题

**提示找不到 uv**：按第二节安装 uv，再重新运行入口脚本。

**深度工具下载失败**：检查网络是否可访问 GitHub、Maven Central 与 Python 包源，再运行同一个安装入口重试。下载分段可以复用；哈希不符时安装器会拒绝使用文件。

**8765 端口被占用**：如果是本工程已启动，直接打开工作台；需要停止时使用本工程的停止入口。脚本不会随意关闭其他占用程序。

**网页已打开，但深度引擎未就绪**：查看“系统状态”的原因，运行 `安装深度引擎.command`。首次未安装深度工具是正常状态，不影响双端标准分析。

**想修改网页源码**：安装 Node.js 22.13+，在工程目录运行 `npm ci --prefix frontend`、`npm run build --prefix frontend`，然后重启服务。普通部署不需要这一步。

**换文件夹或另一台电脑**：先停止服务。不要复制 `.venv/` 到另一台电脑；在目标位置重新执行安装入口。深度工具需要按目标机器架构重新安装/自检。

**想备份检测记录**：先停止服务，再复制整个 `data/`；还原时使用相容的工程版本。转交工程文件无需把个人 `data/` 一起发送。

## 四、Docker 标准分析（备选，未验收）

接收方已安装 Docker 与 Compose 时，可在工程根目录运行：

```sh
docker compose up -d --build
docker compose logs --tail=100
```

访问地址仍为 `http://127.0.0.1:8765/`。停止并保留数据卷：

```sh
docker compose down
```

该配置只提供 Android/iOS 标准分析，不会把 Mac 的 `.tools` 挂进 Linux 容器。不要用 `down -v` 删除想保留的数据卷。Compose 基础用法可参阅 [Docker 官方说明](https://docs.docker.com/compose/gettingstarted/)。

## 五、工程完整性与后续开发

- `SHA256SUMS`：每个交付文件的哈希清单。
- `scripts/verify_package.py`：验证所有列出的文件是否齐全且未修改。
- `README.zh-CN.md`：完整使用与运维说明。
- `MATCHING_RULES.zh-CN.md`：双端规则、门槛、误报控制及限制。
- `VALIDATION.zh-CN.md`、`validation/`：原始工程的历史测试与部署记录，v2.1 另见 validation/v2.1-checks.json；其中日期和自检状态属于原验收环境，不代表新电脑已经安装。
- `THIRD_PARTY.md`、`vendor/binexport/LICENSE`：第三方来源与授权说明。

安装完成后，在工程根目录验证文件清单：

```sh
.venv/bin/python scripts/verify_package.py
```

安装产生的 `.venv/`、`.tools/` 与 `data/` 不在交付清单内。校验脚本验证的是文件完整性，不是数字签名。对自己的应用正式使用前，请用已知正负样本校准阈值；相似分数不是抄袭概率。