Issue 40 - ShaoClean/Alune GitHub Wiki

Issue #40：网络代理与远端 Git 转发

2026-09-28 实现方案

新增“设置 → 应用 → 网络代理”，支持 HTTP、HTTPS、SOCKS5 和可选认证。编辑草稿后显式保存；可放弃或保存后离开。普通读取只返回认证是否存在，用户名和密码不回显，区分保留、替换、清除。凭据与代理地址、端口、类型绑定，改变目标后不能将旧凭据自动发送给新代理。

配置独立保存在设备的 network-proxy.json，使用共享 SecretsModule。桌面复用 Electron safeStorage，独立服务复用本机 AES-256-GCM 密钥。加载或解密失败时明确失败；允许关闭代理并保留暂时无法解密的认证数据。独立服务中的“本机”是后端设备，页面明确提示浏览器设备的回环地址不一定可用。

链路 实现与生效时机
AI 生成、模型列表、连接测试 每个请求使用当前配置对应的 dispatcher；旧请求继续完成，内部 HTTP/WebSocket 不受影响。
macOS 更新 Release 元数据、SHA256SUMS、DMG 和受限重定向使用代理 fetch。
Electron 更新 updater 独立会话经本机 HTTP 桥接进入已保存代理；下一次检查或下载前清理旧连接，保存不取消活动下载。关闭设置恢复既有系统网络策略。
SSH HTTP(S) CONNECT 或 SOCKS5 套接字；快照固定在连接实例上，断线自动重连及业务触发的重连沿用旧快照。
远端 Git SSH 远端回环转发返回本机桥接，再连接用户代理；HTTPS remote 使用命令级 HTTP proxy，SSH remote 使用内存内嵌的 Python CONNECT helper。

连接状态、任务与安全边界

保存新配置后已有 SSH 显示待应用。只有“重新连接并应用”使用新快照，忙碌或连接中拒绝重连；完整 Git/AI 操作、命令、文件传输、排队和仍在关闭的 SSH 通道均参与保护，主仓库和关联 Worktree 共享连接。

SSH 连接状态与 Git 转发能力独立。请求 127.0.0.1 监听后仍检查实际监听范围，拒绝服务器强制通配地址的情况。Linux 检查 /proc/net/tcp*，其他系统使用 netstat -an；不满足回环约束、工具缺失或禁止转发时清理监听并报错。断线关闭转发、桥接与活动套接字。

远端需要 Python 3、Git、OpenSSH（非 Linux 还需 netstat），不自动安装。代理用户名和密码留在本机。Git 的 HTTP 代理覆盖项和 SSH ProxyCommand 只作用于当前进程；不更改用户全局配置，保留 Git SSH 主机密钥校验，禁用控制连接复用及额外跳板。代理失败不回退直连；HTTP(S)/SSH/file 之外的 Git 传输助手被禁止。

测试与范围

HTTP、SSH、Git 测试使用保存且启用的配置，分别显示耗时与结果。HTTP 使用无内嵌凭据 URL 的 HEAD；SSH 使用临时独立连接；Git 使用当前版本的池连接，对所选仓库 fetch/push 地址执行 ls-remote，不提交或推送。编辑配置、切换目标、配置版本变化均使旧结果失效。

本地 Git 网络操作、PR/MR 查询、系统自动代理、PAC、按域名分流不属于本次覆盖范围。真实平台安装升级、Windows 远端适配及跨设备部署仍待验证；详细证据见 功能验收。

历史记录说明

以下保留 2026-09-17 的 UI 原型状态、当时的未完成清单和验证结论。其“待实现”“未修改业务代码”等表述仅描述历史交付，不覆盖上方当前状态；模拟原型检查不计入真实网络验收。

2026-09-17 UI 原型历史记录

  • 类型：功能
  • 状态：UI 设计与原型验证已完成；真实代理功能待实现（Todo）
  • Issue：https://github.com/ShaoClean/Alune/issues/40
  • PR：未创建；本次未修改业务代码
  • 最近更新：2026-09-17
  • 代码基线：development / f0fddaabdf7f6614c9228ad3998f085494c8b12e
  • 参考版本：本机安装的 LobeHub Desktop 2.2.17

设计稿与附件

下载可交互原型 ZIP · HTML 文件 · 使用说明 · 39 项原型检查记录

下载 ZIP 后解压并在浏览器打开 proxy-settings.html，无需依赖或服务器。HTML 原始文件链接可能显示源码，需要另存为 HTML 后打开。原型所有请求、耗时和服务器均为模拟数据；保存只影响当前页面，刷新重置，不写入设备配置，不建立真实 SSH 连接。顶部有独立演示工具，可切换 15 种状态。

桌面主页面

网络代理主页面，1440 像素

认证设置与测试结果

代理认证与已保存密码

HTTP、SSH、远端 Git 分别测试成功

远端转发失败

SSH 可连接，但服务器禁止转发

其余截图：输入校验 · 保存失败 · 390 像素窄屏 · 1024 像素布局 · 离开提醒。截图尺寸与状态清单。

背景、目标与范围

Alune 当前设置中心包含 AI 服务商、提交生成、布局和版本更新，未提供代理配置。AI 请求来自本机 Node 服务，更新使用桌面网络模块，SSH 使用 ssh2，Git 网络操作在远端服务器执行。浏览器设置或单一 HTTP dispatcher 不能覆盖所有链路。

设计增加“应用 → 网络代理”，用一套本机配置覆盖 AI、应用更新、SSH 和远端 Git。用户已选择远端 Git 通过 SSH 转发复用本机代理，无需第二套代理地址。本次交付 UI 原型、截图、说明和待办；真实网络接入、业务 API 和安全存储尚未实现。

首版 UI 提供 HTTP、HTTPS、SOCKS5 手动代理；默认关闭，新用户配置不预填真实地址。原型首屏为了评审方便展示启用的虚构示例，可选择“首次配置”查看新用户状态。系统自动代理、PAC、按域名分流不纳入本稿。

参考来源与视觉规则

只读检查 LobeHub Desktop 2.2.17 的安装包，确认其代理表单包含启用、类型、服务器、端口、可选认证、测试地址、测试连接和保存／重置；类型包含 HTTP、HTTPS、SOCKS5。主进程包含 ProxyDispatcherManager，Node 请求通过 dispatcher 接入代理，SOCKS5 使用相应 dispatcher。参考模块包括 settings-CnTcvY39.js、dispatcher-Bt5L8RwO.js、tester-Cx8a0J2R.js。官网指向的官方 GitHub 仓库在本次核对时返回 404，参考结论来自已安装版本，不假定最新源码相同。

Alune 沿用现有品牌图标、浅色左栏、蓝色选中态、13px 正文、圆角表单与设置导航。桌面左侧配置和测试，右侧生效范围与服务器状态；底部固定可见的保存区。1050px 以下左栏变窄，850px 以下内容改为单列，740px 以下使用现有设置分类下拉框。重点验证 1440、1024、390px。

交互规范

区域 确定行为
启用代理 修改草稿，点击“保存配置”后生效。关闭不删除字段或凭据。页面顶部徽标表示已保存状态，底栏标识未保存修改。
配置 HTTP / HTTPS / SOCKS5；地址不含协议或端口；端口为 1–65535 的整数。认证开启后显示用户名、密码并校验。
凭据 已保存密码仅显示配置状态；留空保留。显隐只影响新输入的值，提供清除入口；仍开启认证时清除后需提供新密码。
保存 未修改时按钮禁用；保存中显示忙碌状态；失败保留草稿与原配置。保存成功使旧测试结果失效。
放弃 恢复最后保存的内容，清除当前测试结果和字段错误。
离开 有修改时显示“继续编辑／放弃修改／保存并离开”；保存失败留在代理页。弹窗支持 Escape 和键盘焦点循环。
HTTP 测试 仅使用已保存、已启用配置；测试地址仅允许无内嵌凭据的 HTTP(S) URL。展示测试中、成功耗时、网络或认证失败与重试。
SSH 与 Git 测试 选择已登记服务器，分别运行；SSH 成功不等于 Git 转发可用。无服务器时提供添加连接入口。
修改与测试 修改配置、切换服务器或测试地址使旧结果失效；未保存时禁用测试。
配置生效 本机新请求应用新配置；已有 SSH 连接标记“重新连接后生效”。关闭代理也遵守此规则。
重连 用户点击“重新连接并应用”；有运行中任务时阻止并提示先结束任务，不中断当前工作。

“添加连接”在本原型中打开明确标注的演示服务器弹窗；真实功能应复用应用已有的连接创建流程。非代理设置分类与工作区只提供导航占位，不表示其他页面已经重构。

服务器状态

状态 呈现与操作
未连接 提供“连接服务器”。
准备中 显示正在准备远端 Git 代理，等待连接结果。
可用 可测试并使用远端 Git；绿色文本和状态点。
待应用 显示“重新连接后生效”和“重新连接并应用”，不自动中断 SSH。
连接中断 明确远端 Git 暂停，提供重试。
不允许转发 SSH 可以独立连通；远端 Git 提示检查服务器转发权限，不声称全部请求成功。
代理关闭 配置保留；存在旧 SSH 连接时仍显示待重连，应用后恢复原有网络策略。

演示菜单：配置完成、代理关闭、首次配置、代理认证、输入错误、未保存修改、保存失败、测试成功、代理不可达、认证失败、服务器不允许转发、连接中断、待重新连接、服务器有运行中任务、尚未添加服务器。测试耗时固定用于演示，不是性能测量。

功能实现约束与接口线索

以下为后续实现的约束，不是本次已交付的后端能力：

  1. 本机 HTTP 请求适配服务端 AI 与各平台桌面更新栈；保留应用内部回环通信。不能仅修改前端 Axios，也不能把设置全局 Node dispatcher 等同于覆盖 Electron 更新和 SSH。
  2. SSH 建连经用户配置的代理建立目标套接字。远端 Git 使用绑定在远端回环地址的转发入口，经现有 SSH 通道返回本机代理；连接断开时清理入口。HTTPS 代理的 TLS 主机名与证书验证、HTTP CONNECT、SOCKS5 和 DNS 解析需要分别验证。
  3. 远端 Git 的 HTTPS 与 SSH remote 分别提供适配；代理设置限定在本次命令环境，不永久改写服务器用户全局 Git 配置。所需远端工具缺失、禁止转发或权限不足时明确失败；不自动安装工具或静默直连。
  4. 代理凭据遵循现有设备安全存储边界。普通读取响应返回密码配置状态；新密码写入、保留、清除需区分，禁止在日志或错误中拼出含凭据的 URL。
  5. 后续业务接口需提供配置读写及版本、HTTP / SSH / Git 独立测试、各服务器转发和待重连状态、运行中任务检测与手动重连能力。本次未新增公共 API 或共享类型，也未锁定端点路径。
  6. 独立服务部署时“本机”指实际发起请求与 SSH 连接的服务进程所在设备。浏览器访问另一台服务器时不能将浏览器电脑的 127.0.0.1 当成服务端可用代理；实现和文案需验证此场景。

相关代码：设置中心、AI 请求、SSH 连接管理。

验收标准

本次 UI 交付

  • 独立 HTML 可交互原型，15 个演示状态，明确标识模拟测试。
  • 保存、放弃、认证、密码显隐、校验、离开提醒、测试、重连及空状态可操作。
  • 1440 / 1024 / 390px 布局无水平溢出，表单控件在视口内，窄屏为单列。
  • 9 张关键状态截图完成视觉检查；39 项原型行为与布局检查通过。
  • 无外部依赖、无真实网络请求；CSP 限制 connect-src 'none'。

后续真实功能

  • 代理设置与认证信息安全持久化，重启可恢复。
  • AI、模型列表、测试、应用更新请求确实经过代理。
  • SSH 初次连接与重连确实经过代理。
  • 远端 HTTPS / SSH Git remote 的 fetch / pull / push 经转发复用本机代理。
  • 不可达、认证失败、禁止转发、中断、配置变化和禁用行为有独立证据，不静默直连。
  • 保留已有工作流、运行中任务和应用内部通信；完成平台回归。

验证记录

日期 环境 场景 结果与证据
2026-09-17 macOS，ego-lite Chromium 152 原型语法检查 通过；无依赖脚本可解析。
2026-09-17 同上 首轮键盘检查 发现原生弹窗在末项 Tab 时焦点未按设计回到首项；已添加显式焦点循环，后续复验通过。
2026-09-17 同上 保存、认证、表单校验、离开、模拟测试、重连、空服务器与旧结果失效 通过；包含关闭代理后待重连、运行中任务阻止重连、SSH 与转发分别反馈。
2026-09-17 同上，1440 / 1024 / 390px 响应式与键盘回归 39 项全部通过，见 JSON 记录。
2026-09-17 同上 9 张 PNG 视觉检查 通过；导出时关闭控件动画以捕获稳定状态，见 截图清单。
2026-09-17 真实服务与跨平台 代理、SSH、Git 和持久化 未运行；本阶段只交付模拟 UI，真实功能尚未实现。

风险、未决事项与回退

真实请求路由、远端转发权限、远端适配工具、DNS、HTTPS 证书及 macOS / Windows / Linux 差异需要功能阶段验证。用户已确认复用本机代理，不以填写远端第二套代理替代该目标。真实 Git 测试应使用受控只读目标和专用测试仓库，连接测试不执行提交或推送。

本次不修改代码仓库、设备网络设置或服务器。原型可通过“重置演示”恢复；Wiki 附件和说明可按 Wiki 修订历史回退。功能实现后补充 PR、真实验证证据及状态，再关闭 Issue。

关联资料