Spaces:
Runtime error
Runtime error
File size: 7,820 Bytes
927965d |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 |
# 日常运行指南
本指南介绍如何在完成首次认证设置后进行日常运行。项目提供了多种启动方式，推荐使用基于 `.env` 配置文件的简化启动方式。
## 概述
完成首次认证设置后，您可以选择以下方式进行日常运行：
- **图形界面启动**: 使用 [`gui_launcher.py`](../gui_launcher.py) 提供的现代化GUI界面
- **命令行启动**: 直接使用 [`launch_camoufox.py`](../launch_camoufox.py) 命令行工具
- **Docker部署**: 使用容器化部署方式
## ⭐ 简化启动方式（推荐）
**基于 `.env` 配置文件的统一配置管理，启动变得极其简单！**
### 配置优势
- ✅ **一次配置，终身受益**: 配置好 `.env` 文件后，启动命令极其简洁
- ✅ **版本更新无忧**: `git pull` 后无需重新配置，直接启动
- ✅ **参数集中管理**: 所有配置项统一在 `.env` 文件中
- ✅ **环境隔离**: 不同环境可使用不同的配置文件
### 基本启动（推荐）
```bash
# 图形界面启动（推荐新手）
python gui_launcher.py
# 命令行启动（推荐日常使用）
python launch_camoufox.py --headless
# 调试模式（首次设置或故障排除）
python launch_camoufox.py --debug
```
**就这么简单！** 所有配置都在 `.env` 文件中预设好了，无需复杂的命令行参数。
## 启动器说明
### 关于 `--virtual-display` (Linux 虚拟显示无头模式)
* **为什么使用?** 与标准的无头模式相比，虚拟显示模式通过创建一个完整的虚拟 X 服务器环境 (Xvfb) 来运行浏览器。这可以模拟一个更真实的桌面环境，从而可能进一步降低被网站检测为自动化脚本或机器人的风险，特别适用于对反指纹和反检测有更高要求的场景，同时确保无桌面的环境下能正常运行服务
* **什么时候使用?** 当您在 Linux 环境下运行，并且希望以无头模式操作。
* **如何使用?**
1. 确保您的 Linux 系统已安装 `xvfb` (参见 [安装指南](installation-guide.md) 中的安装说明)。
2. 在运行 [`launch_camoufox.py`](../launch_camoufox.py) 时添加 `--virtual-display` 标志。例如:
```bash
python launch_camoufox.py --virtual-display --server-port 2048 --stream-port 3120 --internal-camoufox-proxy ''
```
## 代理配置优先级
项目采用统一的代理配置管理系统，按以下优先级顺序确定代理设置：
1. **`--internal-camoufox-proxy` 命令行参数** (最高优先级)
- 明确指定代理：`--internal-camoufox-proxy 'http://127.0.0.1:7890'`
- 明确禁用代理：`--internal-camoufox-proxy ''`
2. **`UNIFIED_PROXY_CONFIG` 环境变量** (推荐，.env 文件配置)
3. **`HTTP_PROXY` 环境变量**
4. **`HTTPS_PROXY` 环境变量**
5. **系统代理设置** (Linux 下的 gsettings，最低优先级)
**推荐配置方式**:
```env
# .env 文件中统一配置代理
UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890
# 或禁用代理
UNIFIED_PROXY_CONFIG=
```
**重要说明**：此代理配置会同时应用于 Camoufox 浏览器和流式代理服务的上游连接，确保整个系统的代理行为一致。
## 三层响应获取机制配置
项目采用三层响应获取机制，确保高可用性和最佳性能。详细说明请参见 [流式处理模式详解](streaming-modes.md)。
### 模式1: 优先使用集成的流式代理 (默认推荐)
**使用 `.env` 配置（推荐）:**
```env
# 在 .env 文件中配置
STREAM_PORT=3120
UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890 # 如需代理
```
```bash
# 然后简单启动
python launch_camoufox.py --headless
```
**命令行覆盖（高级用户）:**
```bash
# 使用自定义流式代理端口
python launch_camoufox.py --headless --stream-port 3125
# 启用代理配置
python launch_camoufox.py --headless --internal-camoufox-proxy 'http://127.0.0.1:7890'
# 明确禁用代理（覆盖 .env 中的设置）
python launch_camoufox.py --headless --internal-camoufox-proxy ''
```
在此模式下，主服务器会优先尝试通过端口 `3120` (或 `.env` 中配置的 `STREAM_PORT`) 上的集成流式代理获取响应。如果失败，则回退到 Playwright 页面交互。
### 模式2: 优先使用外部 Helper 服务 (禁用集成流式代理)
**使用 `.env` 配置（推荐）:**
```bash
# 在 .env 文件中配置
STREAM_PORT=0 # 禁用集成流式代理
GUI_DEFAULT_HELPER_ENDPOINT=http://your-helper-service.com/api/getStreamResponse
# 然后简单启动
python launch_camoufox.py --headless
```
**命令行覆盖（高级用户）:**
```bash
# 外部Helper模式
python launch_camoufox.py --headless --stream-port 0 --helper 'http://your-helper-service.com/api/getStreamResponse'
```
在此模式下，主服务器会优先尝试通过 Helper 端点获取响应 (需要有效的 `auth_profiles/active/*.json` 以提取 `SAPISID`)。如果失败，则回退到 Playwright 页面交互。
### 模式3: 仅使用 Playwright 页面交互 (禁用所有流式代理和 Helper)
**使用 `.env` 配置（推荐）:**
```bash
# 在 .env 文件中配置
STREAM_PORT=0 # 禁用集成流式代理
GUI_DEFAULT_HELPER_ENDPOINT= # 禁用 Helper 服务
# 然后简单启动
python launch_camoufox.py --headless
```
**命令行覆盖（高级用户）:**
```bash
# 纯Playwright模式
python launch_camoufox.py --headless --stream-port 0 --helper ''
```
在此模式下，主服务器将仅通过 Playwright 与 AI Studio 页面交互 (模拟点击"编辑"或"复制"按钮) 来获取响应。这是传统的后备方法。
## 使用图形界面启动器
项目提供了一个基于 Tkinter 的图形用户界面 (GUI) 启动器：[`gui_launcher.py`](../gui_launcher.py)。
### 启动 GUI
```bash
python gui_launcher.py
```
### GUI 功能
* **服务端口配置**: 指定 FastAPI 服务器监听的端口号 (默认为 2048)。
* **端口进程管理**: 查询和停止指定端口上的进程。
* **启动选项**:
1. **启动有头模式 (Debug, 交互式)**: 对应 `python launch_camoufox.py --debug`
2. **启动无头模式 (后台独立运行)**: 对应 `python launch_camoufox.py --headless`
* **本地LLM模拟服务**: 启动和管理本地LLM模拟服务 (基于 [`llm.py`](../llm.py))
* **状态与日志**: 显示服务状态和实时日志
### 使用建议
* 首次运行或需要更新认证文件：使用"启动有头模式"
* 日常后台运行：使用"启动无头模式"
* 需要详细日志或调试：直接使用命令行 [`launch_camoufox.py`](../launch_camoufox.py)
## 重要注意事项
### 配置优先级
1. **`.env` 文件配置** - 推荐的配置方式，一次设置长期使用
2. **命令行参数** - 可以覆盖 `.env` 文件中的设置，适用于临时调整
3. **环境变量** - 最低优先级，主要用于系统级配置
### 使用建议
- **日常使用**: 配置好 `.env` 文件后，使用简单的 `python launch_camoufox.py --headless` 即可
- **临时调整**: 需要临时修改配置时，使用命令行参数覆盖，无需修改 `.env` 文件
- **首次设置**: 使用 `python launch_camoufox.py --debug` 进行认证设置
**只有当你确认使用调试模式一切运行正常（特别是浏览器内的登录和认证保存），并且 `auth_profiles/active/` 目录下有有效的认证文件后，才推荐使用无头模式作为日常后台运行的标准方式。**
## 下一步
日常运行设置完成后，请参考：
- [API 使用指南](api-usage.md)
- [Web UI 使用指南](webui-guide.md)
- [故障排除指南](troubleshooting.md)
|