# 三平台安装、启动、注册、登录与自测

> 面向第一次使用 `data_interface` 的客户。照着做完后，你应该能看到“数据服务运行中”，并完成第一条本地接口请求。
>
> 如果服务器没有桌面或客户由 AI 全程操作，请直接看[无界面服务器与 AI 自动化操作](无界面服务器与AI自动化操作.md)。

## 先记住：启动客户端不等于启动数据服务

客户端分两层：

| 层 | 默认地址 | 作用 | 成功标志 |
|---|---|---|---|
| 管理端 | `http://127.0.0.1:9527` | 注册/登录、充值、启动/停止、查看状态 | `/api/status` 能返回 JSON；有网页资源时可打开管理页 |
| 数据端 | `http://127.0.0.1:8080` | 给你的程序提供 HTTP/WebSocket 数据 | 管理页显示“数据服务运行中”，数据端口能返回接口结果 |

“登录/注册”是同一个按钮：新手机号会自动注册，已有手机号会直接登录，不需要寻找单独的注册页面。

最短成功路径是：

```text
下载正确平台包 → 安装/运行客户端 → 打开网站管理页或调用管理 API
→ 输入手机号和密码，点击“登录/注册”
→ 如果提示充值，输入卡密并点击“充值”
→ 端口保留 8080，点击“启动”
→ 查看“数据服务运行中” → 做一次自测
```

## 0. 开始前准备

### 0.1 账号准备

- 一个有效的 11 位手机号；
- 密码至少 6 个字符；
- 如果账号没有有效权限，准备对应的卡密；
- 注册、登录和取数时需要网络可用；
- 不需要安装编译器，也不需要先安装 Python 才能运行客户端。Python 只用于后续的可选自动化测试。

### 0.2 下载包和架构

从产品下载页的“下载客户端”选择与机器匹配的包。当前包名和支持架构如下：

| 系统 | 下载包 | 当前支持架构 | 包内内容 |
|---|---|---|---|
| Windows | `data_interface_win_amd64.zip` | AMD64 / x64 | 仅 `data_interface.exe` |
| macOS | `data_interface_macos_arm64.dmg` | Apple Silicon / ARM64 | 仅 `DataInterface.app` 程序本体 |
| Linux | `data_interface_linux_amd64.tar.gz` | AMD64 / x86_64 | `data_interface` 和 `res/data_interface_icon_b.png` |

当前没有 Windows ARM64、macOS Intel 或 Linux ARM64 包。架构不匹配时，反复双击、重新安装或修改安全属性都不能解决问题，应先取得匹配版本。

检查架构：

Windows PowerShell：

```powershell
$env:PROCESSOR_ARCHITECTURE
```

预期为 `AMD64`。如果是 ARM Windows，请联系技术人员确认适配包。

macOS / Linux 终端：

```bash
uname -m
```

macOS 预期为 `arm64`；Linux 预期为 `x86_64`。

## 1. Windows 安装与启动

### 1.1 安装

1. 下载 `data_interface_win_amd64.zip`。
2. 将 ZIP 解压到一个固定目录，例如 `C:\Users\你的用户名\DataInterface`。
3. 进入解压后的目录，确认能看到 `data_interface.exe`。
4. 不要直接在压缩包预览窗口里运行，后续也不要频繁移动这个目录。

发布包默认不含 `web/`，因此不影响服务器/API 使用；如果要在本机直接打开 9527 管理页和 `/api/catalog`，再把网站源目录中的 `web/` 放到 EXE 同级目录。也可以直接打开 `http://127.0.0.1:9527/`，网页会调用本机正在运行的管理 API。

这个包是免安装程序，没有安装向导；“解压到固定目录 + 运行 EXE”就是完整安装。

### 1.2 启动

双击 `data_interface.exe`。客户端通常在后台运行，不一定出现主窗口；稍等 1～10 秒后打开：

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

如果浏览器没有自动打开，手动输入上面的地址即可。只做服务器/API 操作时无需浏览器；也可以在 PowerShell 中启动并检查：

```powershell
Set-Location "$env:USERPROFILE\DataInterface"
Start-Process -FilePath ".\data_interface.exe" -WorkingDirectory (Get-Location)
Start-Sleep -Seconds 2
Invoke-RestMethod -TimeoutSec 5 "http://127.0.0.1:9527/api/status"
```

看到 JSON 就说明管理端已经启动。若 Windows 安全提示拦截，请先确认文件来自产品下载页；不要为了一个不明文件关闭系统安全功能。

## 2. macOS 安装与启动

### 2.1 安装

1. 在“关于本机”确认芯片为 Apple Silicon，或在终端执行 `uname -m`，结果应为 `arm64`。
2. 双击 `data_interface_macos_arm64.dmg`。
3. 将 `DataInterface.app` 拖到 `Applications` 文件夹。
4. 关闭磁盘映像窗口，并推出已挂载的磁盘映像。
5. 后续从“应用程序”中的 `DataInterface.app` 启动，不要长期从 DMG 窗口或下载目录启动。

最低系统版本是 macOS 11.0。把应用复制到“应用程序”时要求输入当前 Mac 用户密码，是系统目录的正常权限确认。

### 2.2 首次放行

macOS 14 及更早版本：在“应用程序”中按住 Control 点按 `DataInterface.app`，选择“打开”，再确认一次。

macOS 15 及以后版本：先双击一次；如果系统阻止运行，打开“系统设置”→“隐私与安全性”，在安全性区域对刚才被阻止的应用点击“仍要打开”，完成确认后再次从“应用程序”启动。

客户端是后台服务，启动后不一定有窗口或 Dock 图标。桌面用户可打开 `http://127.0.0.1:9527/`；若已手动放入 `Contents/Resources/web`，也可打开本地页面：

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

也可以在终端验证：

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

macOS 的详细放行、升级和崩溃排查见 [`mac启动教程.txt`](mac启动教程.txt)。

## 3. Linux 安装与启动

### 3.1 安装

确认 `uname -m` 为 `x86_64`，然后执行：

```bash
mkdir -p "$HOME/data-interface"
tar -xzf data_interface_linux_amd64.tar.gz -C "$HOME/data-interface"
cd "$HOME/data-interface"
chmod +x ./data_interface
```

Linux 包只有可执行文件，没有安装向导，也不需要复制到系统目录。建议保留这个目录，因为配置文件和运行日志会跟随它保存。若要使用本地 9527 网页或 `/api/catalog`，再把网站源目录中的 `web/` 放到 `data_interface` 同级；无界面/API 使用不需要它。

### 3.2 启动

第一次建议前台启动，便于看到错误：

```bash
cd "$HOME/data-interface"
./data_interface
```

另开一个终端检查：

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

确认正常后，可用后台方式运行：

```bash
cd "$HOME/data-interface"
nohup ./data_interface > data_interface.log 2>&1 &
```

如果机器没有桌面环境，先在 `config.ini` 中关闭启动后自动开页：

```ini
[General]
OpenWebOnLaunch=0
```

如果 `config.ini` 已经存在，请只修改这一项，不要用示例覆盖整个文件。

之后不需要浏览器，直接用本机管理 API 操作；完整流程见[无界面服务器与 AI 自动化操作](无界面服务器与AI自动化操作.md)。

## 4. 注册、登录和充值

打开管理页后，按页面顶部从左到右操作。

### 4.1 新用户

1. 在“手机号”输入 11 位手机号。
2. 在“密码”输入至少 6 个字符的密码。
3. 点击“登录/注册”。
4. 新手机号会自动创建账号。页面可能提示“注册成功，请先购买卡密充值”。
5. 联系产品支持获取卡密后，登录状态不需要重新注册；在“卡密”输入框输入卡密，点击“充值”。

### 4.2 老用户

1. 输入原手机号和密码。
2. 点击“登录/注册”。
3. 页面提示“登录成功”后，查看顶部手机号和状态。

登录成功但没有有效权限时，页面可能显示“需充值”。这不代表安装失败，也不需要反复注册；登录后直接充值即可。

### 4.3 登录状态怎么判断

成功登录并有有效权限时，通常可以看到：

- 顶部显示脱敏后的手机号；
- 状态显示“数据服务已关闭”或“数据服务运行中”，而不是“未认证”；
- 到期信息中有已开通产品的日期。

同一个账号同时只建议保持一个活动会话。在另一台机器重新登录可能使原机器的会话失效；遇到这种情况，停止原机器上的服务后再决定在哪台机器使用。

## 5. 启动数据服务

1. 登录后，如果页面提示充值，先完成充值并等待状态刷新。
2. 端口输入框先保留 `8080`。
3. 点击“启动”。
4. 确认顶部状态变为“数据服务运行中”。

管理页能打开，只代表管理端正常；只有点击“启动”后，`8080` 数据端才会提供接口。

如果 `8080` 被占用，在端口框改成一个未占用端口，例如 `18080`，再次点击“启动”。之后你的程序必须使用状态接口返回的 `proxyPort`，不能继续假定是 `8080`。

“停止”只关闭数据端；“退出”会关闭整个客户端。关闭浏览器不会停止后台服务。

## 6. 基本自测：按三个层级逐步确认

### 6.1 第一级：管理端自测

Windows PowerShell：

```powershell
Invoke-RestMethod -TimeoutSec 5 "http://127.0.0.1:9527/api/status"
```

macOS / Linux：

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

登录并点击“启动”后，重点确认以下字段：

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

响应可能增加字段，不要求文本完全相同；以上字段的含义比字段顺序更重要。

### 6.2 第二级：数据端自测

先从 `/api/status` 读取 `proxyPort`，再按 6.3 的 D1 HTTP 示例发送第一条业务请求。
数据端不再提供单独的实时通道探活路径；D1 请求返回 JSON 即表示代理端口和业务链路已响应。

### 6.3 第三级：完成第一条业务请求

最简单的方式是回到管理页：

1. 左侧选择一个已开通的 `d1`～`d6` 接口分类。
2. 选择一个接口，先保留页面给出的默认参数。
3. 点击“发送”。
4. 右侧出现 HTTP 响应正文，且不是“服务未启动”提示，即完成页面自测。

D1 的请求字段 `a`、`c` 是固定协议字段，不要自行改名。若要用命令行测试 D1 资讯请求，可复制下面这条：

```powershell
curl.exe -fsS --max-time 15 -X POST http://127.0.0.1:8080/d1/article -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" --data "a=GetListByID&c=PCNewsFlash&LastID=0&st=1&Type=0"
```

Windows PowerShell 请使用 `curl.exe`，避免旧版 PowerShell 将 `curl` 当作其他命令。macOS / Linux 使用反斜杠续行：

```bash
curl -fsS --max-time 15 -X POST http://127.0.0.1:8080/d1/article \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data 'a=GetListByID&c=PCNewsFlash&LastID=0&st=1&Type=0'
```

返回 JSON（通常包含 `List` 或业务结果字段）即可证明 D1 的本地 HTTP 链路已打通。具体字段解释见 [D1 HTTP 接口](d1_http_api.md)。

## 7. 常见问题按现象处理

| 现象 | 判断 | 处理 |
|---|---|---|
| 双击后没有窗口 | 正常现象，客户端是后台服务 | 打开 `http://127.0.0.1:9527/` 或检查 `/api/status`；未放置可选 `web/` 时本地根页面可能没有内容 |
| 浏览器没有自动打开 | 自动开页失败，不等于客户端未启动 | 手动访问本机管理页；服务器请关闭 `OpenWebOnLaunch` |
| 9527 连接失败 | 客户端未运行、启动即退出或端口被占用 | 重新运行客户端，检查进程和 9527 端口 |
| 页面显示“未认证” | 还没有成功登录 | 输入手机号和密码，点击“登录/注册” |
| 登录成功但显示“需充值” | 账号存在，但没有有效权限 | 输入卡密点击“充值”，不要反复注册 |
| “启动”后仍不能请求 | 数据端没有真正运行或端口不一致 | 确认状态为“数据服务运行中”，以 `proxyPort` 为准 |
| D1 业务请求返回 403 | 目标 D1 产品未授权或登录状态失效 | 重新登录并确认有效期；这不是解压问题 |
| 8080 被占用 | 另一个程序正在使用数据端口 | 改用未占用端口，并同步修改调用方 |
| macOS 提示无法验证/无法打开 | 首次安全放行未完成 | 按 macOS 首次放行步骤处理 |
| macOS 显示应用已损坏 | 下载不完整或来源不可信 | 先从产品下载页重新下载；不要对不明文件执行放行命令 |
| Linux 提示 Permission denied | 文件没有执行权限 | 在程序目录执行 `chmod +x ./data_interface` |
| 第二次启动提示已有实例 | 旧实例仍在运行 | 先在管理页点击“退出”，再等待 1～2 秒重启；macOS/Linux 不会自动杀掉旧实例 |

不要把“安装问题”和“账号/权限问题”混在一起判断：只要 `/api/status` 能返回 JSON，本机管理端通常已经安装成功。

## 8. 给 AI 或技术支持的安全信息

如果仍有问题，提供以下信息即可：

- 操作系统和 CPU 架构；
- 下载包的完整文件名；
- 卡在哪一步，以及弹窗的完整文字；
- `/api/status` 的返回结果；
- D1 业务请求是否返回 JSON；
- 端口是否改过。

不要发送密码、卡密、Token、完整 `config.ini` 或未脱敏的日志。服务器没有界面时，按照[无界面服务器与 AI 自动化操作](无界面服务器与AI自动化操作.md)提供结构化状态即可。