#常见问题（FAQ）

本章节汇总了用户在使用沙特协作过程中遇到的常见问题及解决方案。

#安装与启动

#1. 如何安装 Node.js？

推荐使用 nvm（Node Version Manager）安装：

# macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc  # 或 ~/.zshrc
nvm install 18
nvm use 18

# Windows
# 下载安装包：https://nodejs.org/

#2. pnpm 安装依赖失败？

尝试以下解决方案：

# 清除缓存
pnpm store prune

# 重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

#3. Tauri 启动报错 "WebView2 not found"？

Windows 用户需要安装 WebView2 运行时：

1. 下载：Microsoft Edge WebView2 Runtime
2. 安装后重启电脑
3. 重新运行 pnpm tauri:dev

#连接问题

#4. 手机无法连接到服务器？

检查清单：

1. 确认在同一局域网：

   • 手机和桌面需连接同一个 Wi-Fi
   • 检查手机的 Wi-Fi 设置

2. 确认服务器地址正确：

   • 桌面端控制台显示的公网地址
   • 不要使用 localhost 或 127.0.0.1

3. 检查防火墙设置：

   • macOS：系统偏好设置 → 安全性与隐私 → 防火墙
   • Windows：控制面板 → Windows 防火墙
   • 允许 Node.js 通过防火墙

4. 端口占用问题：

   # 检查 80 端口是否被占用
   lsof -i :443  # macOS/Linux
   netstat -ano | findstr :443  # Windows

#5. Session ID 不匹配？

确保手机端和桌面端的 Session ID 完全一致：

• 推荐方式：使用二维码扫描，自动填充
• 手动输入：注意大小写、空格、全角半角

#6. WebSocket 断线重连？

右上角显示"重连中"时：

1. 检查后端服务状态：

   # 重新启动后端
   pnpm dev:server

2. 检查 WebSocket 连接：

   • 打开浏览器控制台（F12）
   • 查看 Network 标签，筛选 WS
   • 确认连接地址为：wss://IP/ws?sessionId=xxx

3. 检查网络稳定性：

   • 尝试切换 Wi-Fi
   • 重启路由器

#功能问题

#7. 无法拦截 HTTPS 请求？

原因：HTTPS 加密通信需要安装 CA 证书。

解决方案：

1. 下载 CA 证书：

   • 桌面端左侧面板 → 点击"下载 CA 证书"按钮
   • 或访问：https://服务器IP/shater/config 获取证书路径

2. 安装并信任证书：

   • iOS：
     • 下载证书后，进入"设置" → "已下载描述文件"
     • 安装证书
     • 进入"设置" → "通用" → "关于" → "证书信任设置"
     • 启用该证书
   • Android：
     • 下载证书后，进入"设置" → "安全" → "加密与凭据" → "安装证书"
     • 选择"CA 证书"
     • 选择下载的证书文件安装

3. 验证证书安装：

   • 在手机浏览器访问：https://www.baidu.com
   • 查看桌面端是否拦截到请求

#8. 如何绕过 SSL Pinning？

方法一：使用反向代理（推荐）

• 无需安装 CA 证书
• App 直接请求本地服务，由本地服务转发到真实服务器
• 配置方法：参见功能详解

方法二：使用抓包工具

• Android：使用 Xposed + JustTrustMe 模块
• iOS：使用 SSL Kill Switch 插件

#9. 拦截记录太多，如何筛选？

多条件组合筛选：

1. API 路径筛选：输入关键词，如 user 匹配 /api/user/info
2. 请求方法筛选：选择 GET、POST 等
3. 关键词搜索：在报文内容中搜索特定字段

静态资源过滤：

• 打开偏好设置（Ctrl/Cmd+,）
• 取消勾选"显示静态资源"
• 自动过滤图片、JS、CSS、字体等请求

#10. 如何导出数据？

Web 模式：

• 点击右上角应用标题 → 导出 → 选择范围

Tauri 模式：

• macOS：系统菜单栏 → 操作 → 导出
• Windows/Linux：标题栏左侧应用图标 → 导出

导出范围：

• 当前记录：仅导出选中的记录
• 所有记录：导出当前 Session 的全部记录

#高级问题

#11. 如何修改监听端口？

默认通过 Caddy 反代对外提供 HTTPS（443 端口）；Koa 仅监听内网 8080，修改方法：

1. 修改环境变量：

   export PORT=8080
   pnpm start

2. 修改代码（永久修改）：

   • 打开 src-koa/server.ts
   • 修改第 32 行：const PORT = Number(process.env.PORT) || 8080;

#12. 如何部署到服务器？

方案一：使用 PM2

# 安装 PM2
npm install -g pm2

# 启动服务
pm2 start pnpm --name "沙特协作" -- start

# 开机自启
pm2 startup
pm2 save

方案二：使用 Docker

# Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
EXPOSE 443
CMD ["pnpm", "start"]

docker build -t 沙特协作 .
docker run -d -p 443:443 -p 80:80 沙特协作

#13. 如何查看后端日志？

开发模式：

• 后端日志直接输出到终端

生产模式：

• 日志文件位于：<DATA_DIR>/logs/session-<sessionId>.log
• DATA_DIR 默认为应用根目录
• 可通过环境变量 SHATER_COLLAB_DATA_DIR 修改

#14. 如何调试 Tauri 打包的应用？

Windows 打包后报错：

1. 检查 src-tauri/tauri.conf.json 的 bundle.resources 配置
2. 确认 sidecar 目录已正确打包
3. 查看日志：%APPDATA%\com.shatercollab.app\logs\

macOS 打包后报错：

1. 检查 Info.plist 的 NSAppTransportSecurity 配置
2. 确认 src-tauri/src/lib.rs 的 start_sidecar 函数
3. 查看日志：~/Library/Logs/com.shatercollab.app/

#其他问题

#15. 支持哪些操作系统？

• Web 模式：任意操作系统（Windows/macOS/Linux）
• Tauri 模式：
  • Windows 10+
  • macOS 10.15+
  • Linux（带 GUI，如 Ubuntu 18.04+）

#16. 是否支持多人协作？

支持！使用相同 Session ID 的团队成员可同时连接到同一台服务器，共享拦截数据。

注意事项：

• 离线暂存消息仅推送给第一个上线的客户端
• 清空操作会影响所有连接的客户端
• 建议使用推送链接功能分享 Session ID

#17. 数据是否安全？

• 所有数据存储在本地，不上传到云端
• Session 数据在所有客户端断开连接后自动清理
• CA 证书仅用于 HTTPS 解密，不会泄露给第三方

#18. 如何反馈问题？

• GitHub Issues：提交 Bug 报告或功能建议
• 即时通讯：联系开发团队

#未找到您的问题？

如果以上内容未能解决您的问题，请：

1. 查看项目 README
2. 搜索 GitHub Issues
3. 提交新的 Issue，附上：
   • 操作系统版本
   • Node.js 版本
   • 错误截图或日志
   • 复现步骤