Skip to content

Issue 107

Jump to bottom
clean edited this page Sep 28, 2026 · 2 revisions

Issue #107：设置页管理命名令牌，仓库按名称选择

实现进度（2026-09-28）

设置页、仓库按名称选择、加密持久化与逐远端关联已接入正式应用代码。下方保留原型设计和原型阶段的验证记录；它们与本次实际应用验证分别记录，不将演示原型当成持久化或真实平台验证依据。

  • 命名令牌使用稳定 ID；改名、更换值、删除及关联保存由 SQLite 事务和 revision 检查保证一致性，删除后清理密文及引用，并保留“原令牌已删除”的提示状态。
  • 共享 secrets 模块供 AI 和访问令牌使用，保留原 AI 兼容导出与 ai-master-key 文件。桌面使用 Electron safeStorage；独立服务使用本机 AES-GCM，常规 API 仅返回元数据。
  • 后端重新读取实际 Git 远端后才解析凭据，首次应用绑定平台与 HTTPS origin（含端口）；目标变更使旧关联失效，即使目标恢复也需重新应用。平台请求拒绝重定向，并拒绝凭据或关联变更后的过时响应。
  • 从独立数据库首次导入桌面时，事务性重加密命名令牌并保留 ID、作用域和关联；密钥不可用时保留原密文及待迁移标记，下次启动重试。
  • 仓库管理入口保留返回位置，新增后返回仓库仍需明确应用；WebSocket 仅通知元数据刷新。匿名读取与“仅本次输入”继续可用。

本次本地自动化共 374 项通过，另通过桌面构建、macOS Electron 跨进程恢复及浏览器交互检查。平台 API 响应使用隔离测试数据，尚未验证真实私有账号、SSO、自建 GitLab 实例或 Windows/Linux 原生桌面。Issue #107 保持打开，具体证据和限制见实际验证记录。

背景与目标

优化前，PR/MR 令牌仅存在于视图组件内，离开视图、切换仓库或远端后清除。用户希望在设置页保存“令牌名字 + 令牌值”，再在具体仓库按名字选择，避免重复输入。

本方案采用“设备级令牌管理 + 仓库远端独立关联”。名称是展示信息，关联使用稳定 ID。保存令牌及仓库选择均持久化，重启后恢复。无需再加一个“记住令牌”开关。

设置页

入口：设置 → 应用 → 访问令牌。沿用现有设置中心的导航、字号、月光主题及 Ant Design 组件。

页面标题“访问令牌”，说明“给令牌起个名字，在仓库的 PR/MR 页面按名称选择。”右上角提供“新增令牌”。

列表：

列 展示及行为
令牌名称 如“公司 GitLab”“项目只读”；次行显示已关联主机，未使用时显示“首次使用时关联主机”
令牌值 固定遮罩，不展示原值或可恢复密文；辅助显示更新时间
使用情况 “2 个仓库关联”或“尚未使用”；点击查看仓库与远端
操作 编辑、删除，均有文字提示和可访问名称

只有两个可填写的字段：

字段 规则
令牌名称 必填、去除首尾空格、1–50 个字符；此设备内忽略大小写后唯一
令牌值 新增时必填，默认隐藏，录入时允许切换显示；沿用后端格式/长度校验，不依据前缀猜测平台

编辑已保存的令牌时，名称预填；令牌值展示“已保存”和“更换令牌值”按钮。仅改名无需重新输入。点击更换才显示新值输入框，提示涉及的关联数量。保存后退出编辑，清空输入中的敏感值。

删除前展示受影响的“仓库 · 远端”清单，确认后删除凭据及关联。明确只删除 Alune 保存的配置，不会在 GitLab/GitHub 撤销令牌。不自动切换到其他令牌。

空状态：“还没有保存令牌”，主按钮“添加第一个令牌”。搜索与列表加载/保存失败使用现有设置页的交互规范。

仓库 PR/MR 页

在远端/项目/筛选区域下、请求列表上方，放置一行：

“访问令牌” → 名称下拉框 → “应用到此仓库”或“已记住选择” → “管理令牌”。

  1. 初次进入没有关联的仓库，默认“不使用令牌”，允许匿名读取。
  2. 下拉框支持搜索，展示未绑定主机或与当前主机、平台匹配的命名令牌。其他主机的条目不可选，并标注适用主机。
  3. 修改下拉框后显示“应用到此仓库”。选择本身不会立即发送凭据；点击应用才保存关联并读取列表。
  4. 应用前，界面始终可见实际目标主机和项目。未绑定主机的令牌另提示：“首次应用时，‘名称’将关联到 host。”
  5. 应用后显示“已记住选择”；下次进入、切换回来或重启应用，自动使用此前关联。
  6. 选择“不使用令牌”并应用，仅解除此仓库/远端的关联，不删除设置里的令牌。
  7. “管理令牌”进入设置并保留返回位置，包括仓库、远端和 PR/MR 视图。
  8. 没有可选令牌时提供“去添加令牌”。新增表单按钮为“保存并返回仓库”；返回后选中新名称，再由用户应用到已显示的目标。

关联粒度为“仓库 + 远端 + 远端目标”。同一主机下的多个仓库可主动选择同一个令牌，但不会因为某个仓库配置过，就自动用于其他仓库。

凭据作用域与生命周期

保持表单只有名称和值两项；主机/平台来自仓库现有远端识别，而非增加必填配置。

  • 首次明确应用时，记录平台与规范化 HTTPS origin（主机及端口）；同一令牌记录限制在这个 origin 和平台内使用。
  • 自建 GitLab 沿用现有的明确平台选择，并在关联中记住它。
  • 远端地址改变时，后端重新解析并校验；项目、主机、端口或平台不匹配则停止使用旧关联，提示重新选择。
  • 不跟随跨 origin 重定向携带凭据。沿用原有目标校验和请求限制。
  • 同主机多账号或项目/群组令牌，创建不同名称，逐仓库明确选择；不按名称、用户名或 token 前缀自动匹配。
  • 重命名不改变 ID，因此不破坏仓库关联。
  • 更换值保留 ID 和作用域；新请求使用新值，清除旧验证状态/缓存，旧请求不能覆盖新状态。
  • 删除后清除所有引用；仍打开的仓库立即提示重新选择，不静默回退到其他凭据。
  • 新建设置记录只代表已保存，不宣称已验证有效。实际访问结果属于特定项目、令牌版本和目标。

如果同一个凭据确实需要用于不同主机，首版为每个主机单独创建命名记录。解除或迁移主机绑定的高级管理可后续讨论。

异常状态

情况 提示与恢复
401 / 身份凭据无效 保留名称选择，提示重新配置或更换令牌
403 / 项目权限不足 提示检查项目访问、权限范围或组织授权，不把令牌标记为对所有仓库无效
404 说明项目不存在或当前身份不可见，不武断认定令牌过期
网络、超时、限流 保留令牌及关联，提供重试，不要求再次输入
已关联令牌被删除 提示“原令牌已删除，请重新选择”，不自动选中其他项
远端目标变化 展示新目标并要求重新应用，不将旧令牌自动发给新目标
加密存储不可用 明确说明保存失败；保留匿名读取，以及可按需使用原有“仅本次输入”作为次要入口

旧版临时输入不会被悄悄升级为持久保存；新建命名令牌必须经过保存动作。匿名读取和临时使用可作为兼容路径，命名选择是主路径。

原型阶段技术方案建议（历史记录）

本节保留实施前的方案与基线代码线索；最终模块、接口、迁移行为及验证结果见实际验证记录。

数据与接口

  • 命名令牌：稳定 ID、名称、是否已保存 secret、作用域、更新时间与版本号。响应不包含原文或密文。
  • 密文单独保存，复用现有 secret-storage 抽象的能力；可抽成通用凭据基础设施，避免访问令牌模块依赖 AI 业务配置。
  • 关联：repositoryId、remoteName、规范化目标指纹、provider、tokenId 或 null。
  • 新增/更换时前端单次提交明文给 Alune 本机后端；保存后清空表单。
  • 列表、选择和常规 PR/MR 请求只使用 ID/元数据。后端校验当前远端后读取凭据，并向指定平台添加认证头。
  • 应用关联与首次设定作用域需保证原子性；并发编辑/删除采用版本检查，保存失败不先展示成功。
  • 不增加全局默认令牌，不枚举所有令牌自动试错。

建议的 API 职责：令牌列表/新增/改名/更换/删除；仓库远端的关联读取/应用/解除；现有 PR/MR 查询由后端解析关联。具体端点命名在实现阶段与现有 controller 风格统一。

本机存储

桌面版复用主进程提供的 Electron safeStorage 能力；独立服务模式评估复用现有受限权限的本机 AES-GCM 存储。不得将令牌原文写入 localStorage、普通配置、日志、错误消息、URL 或导出数据。加密不可用时不静默降级成明文。

现有代码线索：

设计预览

以下为使用虚构项目、示例数据制作的交互原型截图，不代表功能已发布。

设置页

Alune 设置页访问令牌列表

新增令牌

Alune 新增令牌的名称和值表单

仓库按名称选择

Alune 仓库 PR/MR 令牌选择

深色主题

Alune 访问令牌深色主题

窄窗口预览：设置页 · 仓库页。

正式功能验收标准

以下保留最终验收清单；本地已通过的验证及其边界另见实际验证记录。真实平台及跨平台结果尚需补齐，不据此提前关闭 Issue。

  • 设置页以名称和值创建令牌，校验必填/重名，列表不泄露原文。
  • 仓库按名称选择并应用，切换视图/仓库/远端后返回，及重启后，恢复相应关联。
  • 改名不破坏关联；更换值对所关联仓库的新请求生效，不继续使用旧值。
  • 删除前展示影响，删除后旧引用不能继续使用凭据。
  • 平台、主机、端口、项目变化会阻止误用；多账号、项目令牌能明确区分。
  • 不同错误分别提示，不将网络错误或单项目权限不足当成全局凭据失效。
  • GitHub PR、GitLab.com、自建 GitLab、匿名读取、筛选、分页、刷新保持可用。
  • 桌面和独立服务的加密保存/恢复/删除、不可用场景经过验证；日志与普通配置不含明文。
  • 浅色、深色、窄窗口与键盘操作可用。

原型验证记录

日期 环境 场景 结果
2026-09-28 本地 Vite + React + Ant Design，Codex 内置浏览器 创建、重名校验、按名称搜索与选择、应用、返回设置、编辑名称、删除影响与解除关联 已通过交互检查；仅使用演示数据
2026-09-28 同上 改名保留关联 首轮发现编辑表单预填丢失，修正表单挂载后再次验证通过
2026-09-28 同上 1280×720 设置/仓库页、深色及 390px 窄窗口 已检查，截图见附件
2026-09-28 原型项目 npm run build 通过；Ant Design 打包体积提示不影响原型
待实施 正式应用 真实 token、平台 API、持久化、重启恢复、跨平台安全存储 未实施、未验证

原型只保留内存中的名称与关联元数据；输入的示例令牌值在保存时丢弃，刷新页面会重置演示数据。重启恢复和加密存储是设计要求，不是这次原型的实际能力。

原型阶段范围记录（历史）

以下为原型交付时的范围记录，当前实现状态见本页顶部。

用户已明确“设置维护名称和值，仓库按名称选择”的方向。以上主机首次绑定、逐远端关联和异常文案为推荐设计，实施前可继续调整。

首版不包含平台 OAuth 登录、令牌申请/撤销、跨设备同步或全局自动选取。远端异常、并发修改、存储迁移及平台权限需随实现补充实际测试。设计变更可通过 Wiki 历史回退；本次未修改产品源码。

关联资料

设计文档首页 · Alune 品牌说明 · 维护约定 · 代码仓库

Alune

Clone this wiki locally