#快速开始

本章节将引导您完成沙特协作的安装、配置和首次使用。

#环境要求

• Node.js: v18.0.0 或更高版本
• pnpm: 推荐使用 pnpm 作为包管理器
• 操作系统：
  • Web 模式：任意操作系统
  • Tauri 模式：Windows 10+、macOS 10.15+、Linux（带 GUI）

#1. 获取源码

# 克隆仓库
git clone <repository-url>
cd shater-collab

# 安装依赖
pnpm install

#2. 启动 Web 模式

Web 模式适合快速调试，无需打包桌面应用。

# 同时启动前端和后端服务
pnpm dev

# 或者分别启动
pnpm dev:server  # 后端服务（内网端口 8080，对外由 Caddy 反代 HTTPS 443）
pnpm dev:client  # 前端服务（端口 8686）

启动成功后，浏览器会自动打开 http://localhost:8686。

#Web 模式功能限制

• ❌ 不支持系统级菜单
• ❌ 不支持反向代理功能
• ❌ 文件导出使用浏览器下载（无原生对话框）
• ✅ 其他功能完整可用

#3. 启动 Tauri 桌面模式

桌面模式提供完整功能体验，包括系统菜单、原生文件操作、反向代理等。

# 开发模式
pnpm tauri:dev

#Tauri 模式功能优势

• ✅ 系统级菜单集成（macOS 顶部菜单栏、Windows 标题栏下拉菜单）
• ✅ 原生文件保存对话框
• ✅ 反向代理（HTTP→HTTPS 桥接）
• ✅ 独立应用窗口，支持全屏
• ✅ 后端服务自动启动

#4. 手机端配置

#方式一：扫描入口码（推荐）

1. 桌面端启动后，左侧面板顶部会显示入口码二维码
2. 打开手机 App，进入设置页面
3. 点击"扫描二维码"按钮
4. 扫描桌面端显示的二维码
5. 自动填充服务器地址和 sessionId

#方式二：手动配置

1. 在桌面端左侧面板找到入口码下方的 Session ID（15 位字符）
2. 在手机 App 设置页面填写：
   • 服务器地址: https://<服务器IP>/shater/raw-data?sessionId=<SessionID>
   • 例如：https://shater.online/shater/raw-data?sessionId=abc123def456ghi

#获取服务器 IP

桌面端启动时会自动检测局域网 IP 并显示在控制台：

========================================
  沙特协作 - 服务端已启动
========================================
  公网地址:   https://shater.online
  报文收集:   https://shater.online/shater/raw-data?sessionId=xxx
========================================

#5. 开始抓包

配置完成后，在手机 App 中正常操作，接口请求会实时推送到桌面端。

#查看拦截记录

中间面板显示拦截到的接口列表：

• 接口名称：请求的 API 路径（如 /api/user/info）
• 请求方法：GET、POST 等
• 耗时：从请求到响应的时间（毫秒）
• 时间戳：请求发生的时间

#查看报文详情

点击任意记录，右侧面板会显示详细信息：

• 请求头：包含 User-Agent、Content-Type 等
• 请求体：POST 请求的参数（JSON 或字符串）
• 响应头：服务器返回的响应头信息
• 响应体：服务器返回的数据（JSON 树或原始文本）

#筛选和搜索

在中间面板顶部可以：

• API 筛选：输入接口路径关键词，模糊匹配
• 方法筛选：选择 GET、POST 等请求方法
• 关键词搜索：在报文内容中搜索特定字段值

#6. 常用操作

#暂存重要记录

选中一条记录后，按下 Ctrl/Cmd+S 暂存到右侧面板的"暂存记录"区域。

暂存的记录不会在清空操作时被删除，方便后续对比分析。

#对比两条记录

1. 在拦截记录或暂存记录中，点击卡片右侧的"加入对比"按钮
2. 选择对比面板的位置（左侧或右侧）
3. 选择第二条记录
4. 自动跳转到对比面板，显示差异高亮

#导出数据

Web 模式：

• 点击右上角的应用标题，选择"导出"
• 选择"当前记录"或"所有记录"
• 浏览器自动下载 JSON 文件

Tauri 模式：

• macOS：系统菜单栏 → 操作 → 导出
• Windows/Linux：标题栏左侧应用图标 → 导出
• 弹出原生保存对话框，选择保存位置

#7. 高级功能

#反向代理（仅 Tauri 模式）

反向代理允许您将 App 的请求先发送到本地服务，再由本地服务转发到真实服务器。

适用场景：

• 绕过 SSL Pinning（无需安装 CA 证书）
• 调试生产环境接口（转发真实流量到本地）
• 修改请求参数后再转发

配置步骤：

1. 打开偏好设置（Ctrl/Cmd+,）
2. 切换到"反向代理"标签
3. 填写目标服务器 URL（如 https://uat-tms.sinopharmlogistics.com）
4. 设置本地监听端口（默认 8889）
5. 开启"启用反向代理"开关

手机 App 配置：

• 将请求地址改为 http://<服务器IP>:8889/api/...
• 本地服务会自动转发到目标服务器

#推送链接（仅 Tauri 模式）

将当前的入口码和服务器地址生成分享链接，发送给团队成员。

配置步骤：

1. 系统菜单栏 → 操作 → 推送链接
2. 在弹出的对话框中查看生成的链接
3. 点击"复制"按钮，发送给同事

对方打开链接后，会自动填充 Session ID 并连接到您的服务器。

#8. 故障排查

#无法接收数据

1. 检查手机和桌面是否在同一局域网
2. 确认手机配置的 Session ID 与桌面端一致
3. 检查防火墙是否拦截了 80 端口
4. 查看桌面端控制台是否有错误日志

#HTTPS 拦截失败

1. 确认手机已安装并信任 CA 证书
2. 检查证书是否过期（有效期为 10 年）
3. 尝试重启手机 App
4. 使用反向代理替代正向代理

#WebSocket 断线重连

如果右上角显示"重连中"：

1. 检查后端服务是否正常运行
2. 查看浏览器控制台的网络请求
3. 确认 WebSocket 连接地址正确（wss://IP/ws?sessionId=xxx）

#下一步

• 功能详解：深入了解每个功能模块
• API 文档：了解服务端接口规范
• 常见问题：查看更多问题解决方案