# 安装并启动 macOS 客户端：从下载到排障

文档用途：给首次安装的 Mac 用户使用，也给 AI/远程协助人员按症状定位问题。
操作顺序：先确认机器和安装包，再安装，再首次放行，最后用本机状态接口验证。

## 0. AI 先读取的固定事实

- 安装包文件名：`data_interface_macos_arm64.dmg`
- 支持架构：Apple Silicon ARM64。终端执行 `uname -m` 必须看到 `arm64`。
- 最低系统版本：macOS 11.0。
- 应用名称：`DataInterface.app`
- 应用安装位置：推荐 `/Applications/DataInterface.app`
- 本机状态接口：`http://127.0.0.1:9527/api/status`
- 管理端口：9527，固定不变。
- 数据服务端口：默认 8080；管理页可以在启动前改成其他未占用端口。
- macOS 用户数据目录：`~/Library/Application Support/DataInterface/`
- 配置文件：`~/Library/Application Support/DataInterface/config.ini`
- 崩溃诊断目录：`~/Library/Application Support/DataInterface/diagnostics/crash/`
- 应用默认后台运行，不一定显示窗口或 Dock 图标；这不是没有启动的证据。
- 默认不会随系统自动启动；登录管理页后可点击“自启”开启。

如果用户是 Intel Mac，`uname -m` 会显示 `x86_64`。当前发布包不是 Intel 架构，不能靠反复点击或删除隔离属性解决，应该先获取适配架构的安装包。

## 1. 下载

1. 打开项目提供的下载页面，点击“下载客户端”，选择“macOS ARM64”。
2. 确认下载完成，文件名应为 `data_interface_macos_arm64.dmg`。如果仍显示 `.part`、`.download` 等临时后缀，先等待下载结束。
3. 在“关于本机”中确认“芯片”是 Apple Silicon；也可以打开“终端”执行：

```bash
uname -m
```

预期结果：

```text
arm64
```

不要直接运行下载目录中的半成品文件，也不要为了绕过架构不匹配而执行隔离属性命令。

## 2. 安装

1. 在“访达”的“下载”目录双击 `data_interface_macos_arm64.dmg`。
2. 在弹出的磁盘映像窗口中，把 `DataInterface.app` 拖到 `Applications` 文件夹图标上，等待复制完成。
3. 关闭磁盘映像窗口。
4. 在访达左侧边栏找到已挂载的磁盘映像，点击旁边的推出按钮；也可以右键选择“推出”。
5. 后续必须从“应用程序”目录启动 `/Applications/DataInterface.app`，不要一直从 DMG 窗口或下载目录启动。

如果复制到“应用程序”时要求输入密码，这是 macOS 对系统应用目录的正常权限确认。输入当前 Mac 用户有权限使用的管理员凭据即可。

## 3. 首次启动与 macOS 放行

首次启动只需按下面方法放行一次。不要关闭系统安全功能，也不要给不明来源的程序执行放行命令。

### macOS 14 及更早版本

1. 打开“应用程序”目录。
2. 按住 Control 点按（或右键点按）`DataInterface.app`，选择“打开”。
3. 弹出确认框后再次点击“打开”。

### macOS 15 及以后版本

1. 先双击一次 `DataInterface.app`。如果出现“无法验证”或类似提示，点击“完成”关闭提示。
2. 打开“系统设置”→“隐私与安全性”。
3. 向下滚动，在安全性区域找到刚才被阻止的应用，点击“仍要打开”。
4. 输入 Mac 登录密码或使用指纹确认。
5. 回到“应用程序”目录，再次双击 `DataInterface.app`。

放行成功的标志是进程开始运行；应用是后台程序，不一定出现独立窗口。

## 4. 启动成功验证

1. 启动 `DataInterface.app` 后等待约 1～10 秒。
2. 默认会尝试打开管理页面。最终应以本机管理页为准；如果浏览器没有自动打开，手动访问：

```text
http://127.0.0.1:9527/
```

3. 也可以在“终端”执行状态检查：

```bash
curl -fsS --max-time 5 http://127.0.0.1:9527/api/status
```

4. 只要返回 JSON，就说明管理端进程和 9527 端口已经正常工作。正常响应通常包含类似字段：

```json
{"exeConnected":true,"adminPort":9527,"proxyPort":8080}
```

字段可能随版本增加，不要要求响应文本必须完全相同。

5. 在管理页输入账号信息并登录。账号已验证后，点击“启动”开启数据服务；默认端口是 8080。客户端调用本地接口时，使用管理页显示的 `proxyPort` 和 `d1`～`d6`、`d101`、`d201`、`d202` 等本地接口编号。

注意：打开管理页不等于数据服务已经启动。`/api/status` 能返回 JSON 只能证明管理端正常；还要看页面状态是否显示“数据服务运行中”。

## 5. 日常使用、退出、升级与卸载

### 每次开机

默认不会开机自启。每次开机后从“应用程序”双击 `DataInterface.app`，然后打开本机管理页即可。

登录管理页后点击“自启”，按钮显示“自启 ✓”时表示已开启。再次点击可关闭。建议先把应用安装到 `/Applications`，再开启自启；不要频繁移动 App 位置。

“开页”控制启动后是否自动打开本机管理页。关闭“开页”不会停止数据服务。

### 正常退出

1. 在管理页点击“退出”，这是退出整个应用；“停止”只停止数据服务。
2. 如果管理页无法访问，打开“活动监视器”，搜索 `data_interface`，选中对应进程后点击左上角的停止/结束按钮。
3. 退出旧进程后等待 1～2 秒再重新启动。

macOS 使用单实例保护：旧进程还在时，第二次启动不会再创建第二个进程，新的启动会直接退出。这是预期行为。

### 升级

1. 先在管理页点击“退出”；如果页面打不开，就用“活动监视器”结束旧进程。
2. 下载新的 `data_interface_macos_arm64.dmg`，重复第 2 节，把新 App 拖入“应用程序”，选择“替换”。
3. 如果新版首次运行再次被系统拦截，重复第 3 节的放行流程。

账号、配置和设备数据保存在用户数据目录，不在 App 包内；正常替换 App 不会丢失这些数据。

### 卸载

1. 先退出应用，并在管理页关闭“自启”。
2. 把 `/Applications/DataInterface.app` 移到废纸篓。
3. 如果只是卸载程序，建议保留 `~/Library/Application Support/DataInterface/`，以后重装可继续使用原配置。
4. 只有明确要“全新初始化”时，才在退出程序后备份或移走这个目录。不要直接删除唯一副本。

## 6. 按症状排障

以下编号适合 AI 远程协助时直接引用。每次先记录 macOS 版本、CPU 架构、安装包文件名和完整报错原文。

### [MAC-01] 提示“无法验证开发者”“无法打开”

判断：这是首次启动的系统安全拦截，不代表端口或账号有问题。

处理：

1. 先确认 App 位于 `/Applications`。
2. 按第 3 节使用 Control/右键“打开”。
3. macOS 15 及以后，到“系统设置”→“隐私与安全性”点击“仍要打开”。
4. 再次启动，并用 `curl` 检查 9527。

### [MAC-02] 提示“应用已损坏，无法打开”

常见原因是下载文件不完整，或 App 带有下载隔离属性。只对确认来自项目可信下载页的 App 执行下面命令。

先查看属性：

```bash
xattr -l "/Applications/DataInterface.app"
```

确认来源可信后，可移除隔离属性：

```bash
xattr -dr com.apple.quarantine "/Applications/DataInterface.app"
```

然后 Control/右键点 App 选择“打开”。如果仍然失败，优先重新下载 DMG、删除旧 App 后重新拖入“应用程序”，不要继续对疑似损坏的文件反复放行。

### [MAC-03] 双击后没有任何窗口

判断：正常。应用默认以后台服务运行，没有独立窗口或 Dock 图标。

验证：

```bash
curl -fsS --max-time 5 http://127.0.0.1:9527/api/status
```

有 JSON 就是已启动；然后在浏览器打开 `http://127.0.0.1:9527/`。如果没有 JSON，再按 [MAC-04] 排查进程和端口。

### [MAC-04] 本机管理页打不开，9527 连接失败

先依次执行：

```bash
pgrep -fl data_interface
lsof -nP -iTCP:9527 -sTCP:LISTEN
curl -v --max-time 5 http://127.0.0.1:9527/api/status
```

分流：

- 没有 `data_interface` 进程：从“应用程序”重新启动，或检查 [MAC-01]/[MAC-02]。
- 有进程但没有 9527 监听：应用可能启动后立即退出，查看 [MAC-08] 的崩溃诊断。
- 9527 被其他 PID 占用：按 [MAC-05] 处理，不要盲目结束不认识的进程。
- 9527 有监听但浏览器打不开：确认访问的是 `127.0.0.1` 而不是远程地址，重新执行 `curl`，再尝试无痕窗口。

### [MAC-05] 9527 端口被占用

执行：

```bash
lsof -nP -iTCP:9527 -sTCP:LISTEN
```

记录输出中的 `COMMAND`、`PID` 和 `NAME`。如果占用者是旧的 `data_interface`，先在“活动监视器”退出旧实例；如果是其他程序，先正常退出该程序或联系设备管理员。管理端口 9527 是固定端口，普通配置不能改成别的端口。

### [MAC-06] 管理页能打开，但“启动”失败或数据接口不可用

先看 `/api/status` 中的 `isLoggedIn`、`isVerified`、`running` 和 `proxyPort`：

- `isLoggedIn=false`：先登录。
- `isVerified=false`：账号尚未完成有效期/权限验证，按页面提示处理。
- `running=false`：点击“启动”，管理页端口正常不代表数据服务已启动。
- `running=true` 但请求失败：确认客户端请求的是 `127.0.0.1:<proxyPort>`，并且路径使用管理页提供的本地接口编号。

### [MAC-07] 默认 8080 被占用

检查：

```bash
lsof -nP -iTCP:8080 -sTCP:LISTEN
```

在管理页“启动”按钮左侧的端口输入框改成未占用端口，再点击“启动”。启动成功后，以 `/api/status` 返回的 `proxyPort` 为准，并同步修改客户端请求地址。不要把 8080 占用问题误判成 9527 管理端故障。

### [MAC-08] 应用启动后立即退出、反复崩溃

崩溃日志目录：

```text
~/Library/Application Support/DataInterface/diagnostics/crash/
```

用访达打开：

```bash
open "$HOME/Library/Application Support/DataInterface/diagnostics/crash"
```

也可以查看最近的系统记录：

```bash
log show --last 10m --style compact --predicate 'process == "data_interface" OR eventMessage CONTAINS[c] "data_interface"'
```

把最新一份崩溃日志和发生时间交给 AI/技术人员。不要只说“打不开”，要说明是双击后立即退出，还是运行几分钟后退出。

### [MAC-09] 浏览器没有自动打开，或打开后不是本机管理页

1. 手动打开 `http://127.0.0.1:9527/`。
2. 确认 [MAC-04] 的状态检查能返回 JSON。
3. 管理页顶部的“开页 ✓”表示启动后自动打开网页；如果显示“开页”，点击一次开启。
4. 若手动编辑配置，先退出应用，在配置文件的 `[General]` 节中设置：

```ini
OpenWebOnLaunch=1
```

如果只想关闭自动开页，设置为 `0`。修改后重新启动应用。不要把完整 `config.ini` 发给别人。

### [MAC-10] 提示“已有实例运行”，或第二次双击没有反应

这是单实例保护。先执行：

```bash
pgrep -fl data_interface
```

如果能看到旧进程，优先在管理页点击“退出”，否则用“活动监视器”结束对应进程。等待 1～2 秒后再启动。不要同时从 DMG、下载目录和“应用程序”启动多个副本。

### [MAC-11] 登录失败、验证失败或接口请求超时

当 9527 能返回 JSON 时，安装和本机管理端通常已经正常；此类问题优先检查：

1. Mac 是否能正常联网。
2. 系统日期和时间是否正确。
3. VPN、代理、防火墙或网络安全软件是否拦截程序联网。
4. 账号、密码和权限/有效期是否正确。
5. 是否只启动了管理端，尚未在页面点击“启动”开启数据服务。

不要因为登录失败反复安装 App，也不要把密码、卡密、Token 或完整配置文件粘贴到聊天记录中。

### [MAC-12] 升级后仍启动旧版本，或自启失效

1. 退出所有旧进程：`pgrep -fl data_interface`。
2. 确认实际启动的是 `/Applications/DataInterface.app`，不要从旧 DMG 或旧下载目录启动。
3. 升级后重新打开本机管理页，查看页面显示的版本号。
4. 自启失效时，在管理页先点击“自启”关闭，再点击一次开启；应用位置固定后再做此操作。
5. 如果不再需要自启，卸载前务必先关闭“自启”。

## 7. 给 AI/远程协助的安全采集模板

只采集定位问题所需的信息，不要索要完整账号配置。可以让用户执行下面命令并回传已脱敏结果：

```bash
sw_vers -productVersion
uname -m
pgrep -fl data_interface
lsof -nP -iTCP:9527 -sTCP:LISTEN
lsof -nP -iTCP:8080 -sTCP:LISTEN
curl -fsS --max-time 5 http://127.0.0.1:9527/api/status
```

同时记录：

- 现象编号，例如 `[MAC-02]` 或 `[MAC-05]`；
- 用户执行到第几步；
- macOS 版本和 `uname -m` 结果；
- 安装包完整文件名；
- 弹窗完整文字或截图；
- 是否能返回 `/api/status`；
- 最新崩溃日志的文件名和时间。

脱敏要求：`config.ini` 可能包含账号凭据、设备信息或其他敏感配置；只能提供相关键名和错误现象，不能直接发送完整文件、密码、卡密或 Token。