FoxDesk

安装与启动

方式一：直接运行（推荐开发者）

git clone https://github.com/BB0813/foxdesk.git
cd foxdesk
python -m pip install -r requirements.txt
# Camoufox：应用内系统页 Install / Fetch
# 可选 Chromium 双引擎（1.4.0）：
#   playwright install chromium
#   patchright install chromium
python desktop.py

或双击 Start-FoxDesk.bat（旧名 Start-CamoufoxManager.bat 仍可用）

用户数据目录：%APPDATA%\FoxDesk（旧版 CamoufoxManager 会自动迁移）。

方式二：下载 exe 安装包

从 GitHub Releases 下载版本：当前稳定线 v1.4.0（双引擎 + Patchright）。安装或解压后运行 FoxDesk.exe。

无需安装 Python 环境（安装包形态）。

方式三：Web 调试模式

python -m uvicorn backend.app:app --host 127.0.0.1 --port 8765 --reload
# 浏览器打开 http://127.0.0.1:8765

首次启动

Camoufox：进入「系统」标签页，按顺序执行：

Chromium（可选）：系统页可查看 Playwright / Patchright / 本机 Chrome 状态；推荐 chromium_backend=auto。模板「AI 工作档案」面向自有账号正常使用 ChatGPT/Claude/Gemini，不保证注册/订阅通过。

快速上手

1. 启动 FoxDesk
2. 点击「新建」创建一个 Profile
3. 在「基础」标签页设置名称和启动网址
4. 在「代理」标签页填写代理地址（可选）
5. 在「指纹环境」标签页点击「随机生成」
6. 点击「保存」
7. 点击「启动」打开浏览器

配置档案

Profile 是 FoxDesk 的核心概念，每个 Profile 对应一个独立的浏览器身份。

操作

• 新建 — 创建空 Profile
• 保存 — 保存当前编辑的 Profile
• 复制 — 克隆当前 Profile
• 删除 — 右键菜单删除
• 导入/导出 — JSON 格式导入导出
• 右键菜单 — 在 Profile 列表右键可启动、编辑、复制、导出、删除

指纹参数

在「指纹环境」标签页可以精确控制浏览器指纹：

随机生成

点击「随机生成」按钮，会根据选择的 OS 自动生成一套完整的指纹参数组合。

指纹检测

点击编辑器顶栏「检测」按钮，FoxDesk 会分析当前 Profile 的指纹一致性，给出 0-100 分评分并列出潜在问题。

代理设置

支持的代理协议：

支持认证：socks5://user:pass@host:port

只填 host:port 会自动补全为 http://host:port

代理测试

点击「测试代理」按钮，FoxDesk 会通过代理连接到检测服务器，返回：

• 出口 IP 地址
• 连接延迟
• 成功/失败状态

批量导入

在代理标签页底部，每行一个代理地址，点击「批量导入」会自动分配给 Profile。

会话管理

每个启动的浏览器是一个「会话」。在「运行会话」标签页可以看到所有运行中的会话。

• 展开详情 — 点击会话行的下拉箭头
• 查看 / 下载日志 — 展开后可下载（GET/POST + 本机 Token）
• 导航 / 指纹探测 / 截图 / 表达式 — browser 模式运行时控制
• 刷新端点 — server 模式尝试刷新 ws_endpoint
• 批量停止 — 勾选运行中会话后批量停止
• 全部停止 — 一键停止所有会话
• 并发 / 空闲 — 系统设置里可配置最大并发与空闲自动停止

Cookie 管理

在「指纹环境」标签页底部：

• 导出 Cookie — 从 Profile 的 cookies.sqlite 读取并下载为 JSON
• 导入 Cookie — 上传 JSON 格式的 Cookie 文件

下载源

在「系统」标签页可以选择不同的 Camoufox 下载源：

系统架构

FoxDesk
├── desktop.py              # 桌面启动器（pywebview / 浏览器回退）
├── backend/
│   ├── app.py              # FastAPI 主服务（API + 静态文件）
│   └── camoufox_worker.py  # Camoufox 启动 worker 进程
├── static/
│   ├── index.html          # 前端 SPA
│   ├── styles.css          # 样式（深浅色双主题）
│   ├── app.js              # 前端逻辑（原生 JS，无框架）
│   └── logo.png            # 品牌 Logo
├── data/
│   ├── profiles.json       # Profile 数据
│   ├── channels.json       # 下载源配置
│   ├── activity.json       # 操作日志
│   └── runtime/            # 运行时临时文件
└── foxdesk.spec            # PyInstaller 打包配置

数据流

桌面启动流程：

1. desktop.py 找可用端口
2. 启动 uvicorn 后端（子进程或内嵌）
3. 等待后端就绪
4. 用 pywebview 打开窗口（或回退到浏览器）

会话启动流程：

1. 前端调用 POST /api/sessions
2. 后端验证 Profile → 写入 runtime JSON
3. 启动 camoufox_worker.py 子进程
4. Worker 读取 Profile → 调用 Camoufox API
5. Worker 通过 stdout 输出 JSON 日志事件
6. 后端捕获日志 → 前端轮询显示

API 接口

所有接口基础路径：http://127.0.0.1:8765

系统

Profile

会话

其他

本机 API 使用请求头 X-FoxDesk-Token（页面 bootstrap 注入；勿映射到公网）。

构建与打包

本地构建

双击 build.bat

构建产物：dist/FoxDesk/FoxDesk.exe

CI/CD 自动构建

推送 v* tag 自动触发 GitHub Actions：

git tag v1.4.0
git push origin v1.4.0

自动构建 Windows exe / 安装包并创建 GitHub Release（含 SHA256SUMS）。

参与贡献

1. Fork 本仓库
2. 创建特性分支 git checkout -b feature/amazing
3. 提交更改 git commit -m 'Add amazing feature'
4. 推送分支 git push origin feature/amazing
5. 创建 Pull Request

更新日志