DooTask 桌面端代理设置完全指南:从系统代理到 Chromium 启动参数
DooTask 桌面端代理设置完全指南:从系统代理到 Chromium 启动参数
DooTask 桌面端是基于 Electron 38 打包的本地客户端(见 electron/package.json),其网络层复用 Chromium 内核,因此代理行为与 Chrome 浏览器高度一致。本文围绕 resources/ai-kb/zh/concept/electron-client/proxy.md 的核心结论,系统讲解 DooTask 桌面端的代理来源、适用场景、启动参数注入、鉴权代理、故障排查与能力边界,并结合仓库源码(electron/electron.js、electron/lib/utils.js、electron/lib/renderer.js)给出可验证的实现依据。
读完本文,你将掌握:在公司 HTTP 代理、VPN、抓包测试三种典型环境下让 DooTask 桌面端正确走代理的完整操作路径,以及排查 WebSocket 被阻断、登录失败等问题的可行步骤。
代理来源:桌面端没有内置代理面板
DooTask 桌面端没有内置代理设置面板,客户端内也不提供填写代理服务器地址或鉴权信息的入口。桌面端主窗口通过 webContents.loadURL(serverUrl) 加载服务器地址(见 electron/lib/utils.js),所有页面请求、WebSocket 长连接、下载任务都发生在 Chromium 网络栈内,因此默认继承操作系统层面的代理配置。
代理生效路径因平台而异:
| 平台 | 代理配置入口 |
|---|---|
| macOS | 系统设置 → 「网络」→ 当前网络 → 「详细信息」→「代理」 |
| Windows | 设置 → 「网络和 Internet」→「代理」 |
| Linux | 多数发行版位于「设置 → 网络 → 代理」 |
从源码结构看,electron/electron.js 主进程中并未调用 session.setProxy() 或 app.commandLine.appendSwitch('proxy-server') 等代理注入 API,说明代理完全交由 Chromium 继承系统配置,这一结论与文档“客户端内没有独立的代理配置入口”一致。
适用场景
DooTask 桌面端走代理的典型场景有三类:
- 内网部署走公司 HTTP 代理出公网:DooTask 部署在内网,但域名解析、静态资源或推送通道需要经过公司代理访问公网。
- 通过 VPN 客户端访问私有 DooTask 实例:VPN 通常以系统级路由或代理形式接管流量,客户端无需额外配置即可连通私有实例。
- 测试环境抓包:通过 mitmproxy / Charles 等工具配 PAC 或全局代理,观察客户端发出的 HTTP 与 WebSocket 请求。
启动参数(进阶):绕过系统代理的最高优先级方式
Electron(Chromium)支持在启动时通过命令行参数注入代理,这种方式绕过系统代理设置,生效优先级最高。
macOS 终端启动示例:
open -a DooTask --args \
--proxy-server="http://192.168.1.10:8080" \
--proxy-bypass-list="*.internal.com"
Windows 则在快捷方式属性中给 dootask.exe 添加同样的参数,例如在「目标」末尾追加:
--proxy-server="http://192.168.1.10:8080" --proxy-bypass-list="*.internal.com"
参数说明
| 参数 | 作用 | 补充说明 |
|---|---|---|
--proxy-server |
指定代理服务器地址 | 支持 http://、https://、socks5:// 等协议前缀;不加协议前缀默认按 HTTP 代理处理 |
--proxy-bypass-list |
指定不走代理的域名列表 | 多个条目以英文逗号分隔,支持通配符(如 *.internal.com);DooTask 服务器地址若在此列表内则直连 |
如何应用与生效前提
- 生效前提:参数必须在进程启动前注入,修改后需完全退出客户端再重新启动;如果只是关闭主窗口(macOS / Windows 上关闭即隐藏到托盘,见 electron/electron.js),进程仍在运行,参数不会重新生效。
- 验证方法:启动后通过抓包工具或代理服务器访问日志确认请求确实经过预期代理;也可在代理服务器上观察是否出现来自 DooTask 客户端的连接。
- 优先级关系:命令行注入参数优先级高于系统代理设置,适合在公司网络与个人网络之间频繁切换、但不想改动系统级代理的场景。
鉴权代理(需要用户名 / 密码)
当代理服务器需要认证时,DooTask 桌面端本身没有录入界面,需要借助操作系统或 Chromium 自身的凭证机制:
- 在操作系统代理面板中录入凭证:
- macOS:凭证存入钥匙串(Keychain);
- Windows:凭证存入凭据管理器(Credential Manager)。
- 在 Chromium 弹窗中输入:客户端请求经过代理时,Chromium 可能弹出代理鉴权对话框,直接输入用户名 / 密码即可。
注意:凭证是否被记住、是否需要每次输入,取决于操作系统凭证存储与代理服务器的认证策略(Basic / NTLM / Digest 等),这部分不在客户端控制范围内。
故障排查
遇到客户端打不开或登录失败时,可按以下顺序排查:
- 先用系统浏览器验证网络:确认系统默认浏览器能否直接打开 DooTask 网址。如果浏览器同样失败,问题大概率在系统代理或网络本身,而不是客户端。
- 抓包确认代理路径:检查请求是否真的经过了预期代理。若设置了
--proxy-bypass-list,还要确认服务器地址没有被误加入直连白名单。 - 检查 WebSocket 是否被阻断:DooTask 的消息推送依赖 WebSocket 长连接。部分企业代理只放行 HTTP/HTTPS,会拦截 CONNECT 隧道或
wss://流量,此时需要联系运维在代理上放通wss://协议。 - 检查本地健康检查:客户端启动后每 10 秒对
http://localhost:22223/health做一次健康检查(见 electron/electron.js),该检查走本地回环地址,不应受系统代理影响;如果日志显示健康检查异常,说明本地静态服务本身有问题,与代理无关。
不支持的能力边界
- 无代理配置 UI:客户端 UI 没有代理设置项,无法在 App 内切换代理或填写代理地址。
- 无协议自动切换:不支持 SOCKS5 / HTTP / HTTPS 协议的自动切换。
- 无单 App 独立代理:不支持仅为 DooTask 单独配置代理(全系统级生效);如需单应用代理,唯一途径是使用上述启动参数注入,但它同样会作用于整个 Electron 进程的网络栈。
实现层面的补充:网络请求链路
为了让读者对“代理作用于哪些流量”有更清晰的认识,这里补充说明桌面端的网络构成(依据仓库源码):
- 页面加载与 WebSocket:主窗口通过 electron/lib/utils.js 的
loadUrl调用webContents.loadURL(serverUrl)加载服务器页面,页面内的 WebSocket 长连接同样运行在 Chromium 网络栈中,二者都遵循系统代理或启动参数配置。 - Cookie 处理:客户端通过
session.defaultSession.webRequest.onHeadersReceived为Set-Cookie追加SameSite=None; Secure(见 electron/lib/utils.js),该过滤器同样作用于代理通道上的响应头。 - 外链打开方式:主窗口通过
setWindowOpenHandler拦截新窗口,非mailto/tel/callto链接交给shell.openExternal交给系统浏览器打开(见 electron/electron.js 与 electron/lib/renderer.js),因此外链走的是系统浏览器的代理配置,而不是客户端自身的代理通道。 - 健康检查:使用
axios.head(serverUrl + 'health')对本地 Express 静态服务做轮询(见 electron/electron.js),走 localhost 回环,不受外部代理影响。
小结
DooTask 桌面端的代理策略可以概括为一句话:跟随系统,不做内建,可用启动参数覆盖。日常办公使用直接配置操作系统代理即可;需要强制单客户端走特定代理时,用 --proxy-server 与 --proxy-bypass-list 启动参数注入;遇到登录失败优先怀疑代理放行规则与 WebSocket 阻断,并用系统浏览器对照排查。